= Import the Xen grant-table bus_dma(9) handlers from OpenBSD =
 * Student: PratyushYadav (<<MailTo(pratyush AT SPAMFREE freebsd DOT org)>>)
 * Mentors:
  * EdwardTomaszNapierala (<<MailTo(trasz AT SPAMFREE freebsd DOT org)>>)
  * AkshayJaggi (<<MailTo(jaggi AT SPAMFREE freebsd DOT org)>>)
 * Special Thanks:
  * RogerPau (<<MailTo(royger AT SPAMFREE freebsd DOT org)>>)

== Project description ==
Xen uses the grant table interface to grant foreign domains access to page frames and to do ownership transfer. Each domain maintains its own grant table and it shares that with Xen to tell it what permissions other domains have on its pages. The index of a grant table entry, called a grant reference, is transmitted to the other domains that need to access the page. OpenBSD’s implementation uses wrappers for the bus_dma(9) interface to implement custom bus_dma functions for communication between domains. This project will bring in the grant table handlers from OpenBSD and integrate them with the rest of the system.

== Approach to solving the problem ==

First, I will take a look at OpenBSD's implementation of the Xen drivers. I will understand where and how the bus_dma(9) interface is used. Then I will identify where that interface would fit in FreeBSD's implementation.

Then comes the importing part. Once the importing is partially completed, some testing will need to be done. After that, complete the implementation and test thoroughly.

== Deliverables ==

 * Mid-term deliverable: Implement the bus_dma(9) wrappers to map and share grants with domains.

 * Final deliverable: Modify the rest of the system to fully use the new implementation and integrate with all the frontends and backends.

== Progress Blog ==

I maintain a progress blog on Blogger which I update nearly every day with what I did that day. Take a look at: [[https://pratyushgsoc.blogspot.com/|Google Summer of Code Progress Blog]]

== The Code ==

Review:
 * https://reviews.freebsd.org/D18550
 * https://reviews.freebsd.org/D18551
 * https://reviews.freebsd.org/D18552
 * https://reviews.freebsd.org/D18553

My !GitHub fork: https://github.com/prati0100/freebsd/tree/projects/xen_bus_dma

For the entire patch so far, with the all the commits squashed (I update this less often): https://github.com/prati0100/freebsd/tree/busdma_xen_clean

Individual Commits (Some of these commits are not finalized as of yet, I will update the links when I over-write them. For the most latest work, check the above branches)
 * [[https://github.com/prati0100/freebsd/commit/f3647f520509c1d1e791e7154bd3cd5daac30d0c|Implemented the Xen-specific bus_dma(9) grant table handlers]]
 * [[https://github.com/prati0100/freebsd/commit/95d76f1b81720685a560f928fa44c02610564354|Updated xenpv.c to use the Xen-specific dma tag]]
 * [[https://github.com/prati0100/freebsd/commit/ac9139483a35884df251cbb9e3b865119143face|Updated the blkfront driver to use the Xen-specific dma implementation]]
 * [[https://github.com/prati0100/freebsd/commit/1e8b313ecbc2bcba7b27fcf1d5ad419ae2cb0cc0|Updated the netfront driver to use the Xen-specific dma implementation]]

== Work Done So Far ==

 * Implementation of the grant-table bus_dma(9) handlers.

 * Updated the xenpv DEVMETHODs so that the devices hanging off the xenpv bus use the new busdma implementation.

 * Updated the blkfront driver to use the new busdma implementation.

 * Updated the netfront driver to use the new busdma implementation.

== Work Left ==

 * If unload on a map is called when it is waiting for grant references, we will likely leak memory, and even might cause an invalid memory access resulting in a crash. I'm not sure if an implementation should handle this kind of situation, or it should be left to the client drivers using it. Need to investigate into the expectations of the interface and then fix the bug.

 * Further testing:

  * The implementation works well when there is no shortage of bounce pages. But I have not been able to test when the load called on the parent defers. Need to produce such a situation and make sure everything works as it should.

== Bugs I spotted while working on the project ==

 * [[https://reviews.freebsd.org/D15553|Xen: Removed some leftover code from gnttab.h]]

 * [[https://reviews.freebsd.org/D15899|Xen: Added missing check for free callbacks in gnttab_end_foreign_access_references()]]

 * [[https://reviews.freebsd.org/D16136|Xen blkfront: Fixed memory leak in xbd_connect()]]

 * [[https://reviews.freebsd.org/D16505|Xen: Make gnttab_list_lock a recursive lock]]

 * [[https://reviews.freebsd.org/D16045|Xen blkfront: Fixed wrong error code return in xbd_dump()]]

 * [[https://reviews.freebsd.org/D16446|Xen: Fix potential page faults in the grant_table.c]]

== Useful links ==

 * OpenBSD's implementation can be found in [[http://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/sys/dev/pv/xen.c?content-type=text/plain|src/sys/dev/pv/xen.c]].

 * Some information about grant tables and [[https://xenbits.xen.org/docs/unstable/misc/grant-tables.txt|grant references]].

 * The [[https://www.freebsd.org/cgi/man.cgi?query=bus_dma(9)|bus_dma(9)]] interface.