====== General Purpose DMA Engine Framework for FreeBSD (GPDMA) ======

===== Abstract =====
The aim of this project is to provide a generic, flexible framework for initiating and controlling DMA transfers using General Purpose DMA engines, found in most of embedded %%SoCs%% - along with tests and documentation. There are analogous frameworks for %%NetBSD%% (dmover(4%%))%% and Solaris (ddi_dmae(9F%%))%%, but they are not well suited for embedded targets and don't offer all required features.

===== Deliverables =====
  - Design and implement kobj-based API for DMA engines drivers, along with respective manual pages. API would include operations for programming DMA channels, starting/stopping transfers and completion notification to upper layer via apporiate callbacks. There should be possibility to express even complex DMA transfers - with support for memory filling, XOR engines, reading/writing on memory mapped FIFOs, etc. Upper layer should also have information about transfer types supported by particular DMA engine and it's limitations.
  - Implement respective API for upper layer - kernel and device drivers and, of course, document it in manual pages. Introduce new type of resource - SYS_RES_DMA - describing DMA channels.
  - Provide an example implementation of DMA engine driver using our new framework - edma(4) on TI [[http://focus.ti.com/docs/prod/folders/print/tms320dm6446.html|DaVinci]] (DM644x) and optionally idma(4) on Marvell 88F6xxx ([[http://www.marvell.com/products/embedded_processors/kirkwood/plugcomputer.jsp|SheevaPlug]]).
  - Make some parts of kernel use DMA engine, if available (memcpy, bzero, etc).
  - Convert example device driver to use our new framework - most likely dvmmc(4) on TI [[http://focus.ti.com/docs/prod/folders/print/tms320dm6446.html|DaVinci]].
  - Write character device driver (/dev/dma?) implementig some ioctl() calls to allow userspace applications benefit from hardware memory copying/filling.
  - Implement unit tests to check whether all possible transfer types work correctly.
  - Implement regression tests to verify correctness of operation in stress environments.
  - Put all above in form suitable for commiting.

===== Milestones =====

^ Milestone ^ Status ^ Comment ^
| M1: Kobj interface for DMA engine drivers as well as framework glue code for upper layers is complete //(Week 3)// | Complete | Established working API's |
| M2: Working implementation of example DMA engine driver //(Week 5)// | Complete | EDMA3 driver working |
| M3: dvmmc(4) uses DMA, kernel memcpy/memmove/bzero uses DMA if possible //(Week 7)// | Complete |  |
| M4: DMA engine is controllable from userspace via special device node //(Week 9)// | Complete |  |
| M5: Manual pages and documentation are complete //(Week 10)// | In progress |  |
| M6: Unit and regression tests are complete and framework is ready for commiting //(Week 12)// | In progress |  |

===== Post-GSOC tasks =====

^ Milestone ^ Status ^ Comment ^
| Simplify API | In progress |  |
| Convert %%DaVinci%% platform to FDT | Complete |  |
| Convert GPDMA to FDT | Not done |  |
| Write Marvell IDMA driver | Not done |  |
| DMA transfer queueing | Not done |  |

===== Mentor =====

RafalJaworowski

===== APIs =====

  * [[SOC2010JakubKlama/EngineAPI|DMA engine driver API]]
  * [[SOC2010JakubKlama/KernelAPI|Kernel API for GPDMA]]
  * [[SOC2010JakubKlama/CharDevice|GPDMA character device]]

===== References =====

  * [[http://www.freebsd.org/news/status/report-2010-01-2010-03.html#FreeBSD/arm-port-for-TI-DaVinci|FreeBSD/DaVinci port]]
  * [[http://netbsd.gw.com/cgi-bin/man-cgi?dmover++NetBSD-current|dmover(4) on NetBSD]]
  * [[http://docs.sun.com/app/docs/doc/806-0639/6j9vsttje?l=en&a=view&q=ddi_dmae|ddi_dmae(9F) on Solaris]]
  * [[http://focus.ti.com/docs/prod/folders/print/tms320dm6446.html#technicaldocuments|DM6446 documents]]
  * [[http://p4web.freebsd.org/@md=d&cd=//&c=eCv@//depot/projects/soc2010/jceel_dma/?ac=83|Project P4 branch]]