thesofproject · lgirdwood · Jul 3, 2018 · Jul 3, 2018
@@ -0,0 +1,8 @@
+.. _dma-drivers-api:
+
+DMA Drivers API
+###############
+
+.. TODO: to be uncommented once repo cross ref is clarified
+   .. doxygengroup:: sof_dma_drivers
+      :project: SOF Project
@@ -0,0 +1,10 @@
+.. _api:
+
+API Documentation
+#################
+
+.. toctree::
+   :maxdepth: 1
+
+   dma-drivers-api
+   uapi
@@ -0,0 +1,8 @@
+.. _api-uapi:
+
+uAPI
+####
+
+.. TODO: to be uncommented once repo cross ref is clarified
+   .. doxygengroup:: sof_uapi
+      :project: SOF Project
@@ -187,7 +187,10 @@ def setup(app):
 
 
 breathe_projects = {
-	"SOF Project" : "doxygen/xml",
+   "SOF Project" : "doxygen/xml",
 }
 breathe_default_project = "SOF Project"
 breathe_default_members = ('members', 'undoc-members', 'content-only')
+breathe_domain_by_extension = {
+   "h" : "c",
+}
@@ -0,0 +1,23 @@
+
+package audio {
+    component "<comp>" as comp
+}
+
+interface dma_get
+component "lib::\ndma" as lib_dma
+
+lib_dma -up- dma_get
+
+interface dma_ops
+
+component "drivers::dma::\n<dma impl>" as dma_impl
+dma_impl -up- dma_ops
+
+component "platform" as plat
+
+lib_dma <. dma_impl : (1) registered\nby platform
+
+dma_ops <. plat : (2) calls probe() @init
+
+comp ..> dma_get : (3) obtains dmac
+comp ..> dma_ops : (4) calls API
@@ -0,0 +1,40 @@
+class dma {
+	dma_get(dmac_id) : struct dma*
+}
+hide dma attributes
+
+class dma_ops {
+	channel_get()
+	channel_put()
+	start()
+	stop()
+	pause()
+	release()
+	status()
+	set_config()
+	set_cb()
+	pm_context_restore()
+	probe()
+}
+hide dma_ops attributes
+
+class dma_plat_data {
+	id : uint32_t
+	base : uint32_t
+	channels : uint32_t
+	irq : uint32_t
+	drv_plat_data : void *
+}
+hide dma_plat_data methods
+
+class "struct dma" as s_dma {
+	plat_data : dma_plat_data
+	lock : spinlock_t
+	ops : const dma_ops *
+	private : void *
+}
+hide s_dma methods
+
+dma_ops - s_dma
+s_dma -- dma_plat_data
+s_dma <- dma : provides
@@ -0,0 +1,22 @@
+participant client
+participant lib
+participant dma
+
+== Obtaining Reference to DMAC ==
+client -> lib : dma_get(capabilities)
+client <-- lib : dma
+
+== Start ==
+client -> dma : dma_channel_get( stream tag )
+client <-- dma : ch#
+
+client -> dma : dma_set_cb( ch#, client.cb() )
+client -> dma : dma_set_config( ch#, config )
+client -> dma : dma_start( ch# )
+
+== Transmission ==
+...
+
+== Stop ==
+client -> dma : dma_stop( ch# )
+client -> dma : dma_channel_put( ch# )
@@ -0,0 +1,79 @@
+.. _dma-drivers:
+
+DMA Drivers
+###########
+
+For the documentation of support devices refer to
+:ref:`dma-drivers-supported-devices`.
+
+Intro
+*****
+
+Access to the DMA Controllers (DMAC) available on the platform is provided by
+the ``dma_get()`` function implemented by the *library* code. Reference to a
+DMAC instance obtained from ``dma_get()`` is represented by a pointer to
+``struct dma``. Each ``struct dma`` instance provides ``dma_ops`` API used by
+the DMA clients to setup and run DMA transmission.
+
+.. uml:: images/dma-ops.pu
+   :caption: DMA Driver API
+
+Flows
+*****
+
+DMAC Initialization
+===================
+
+There is one-time initialization phase when the ADSP goes to D0 state. Each
+platform registers its DMA drivers in the list maintained by the *lib* at
+startup.
+
+Any component from the *audio* package may use a DMA engine by obtaining a
+reference to the ``dma_ops`` interface from the *lib*'s list. This flow may
+happen unlimited number of times during ADSP D0.
+
+.. uml:: images/dma-drv-use.pu
+   :caption: DMAC Initialization
+
+Channel Initialization & Data Transfer
+======================================
+
+.. uml:: images/dma-transfer.pu
+   :caption: Channel Initialization & Data Transfer
+
+Using DMA Driver API
+********************
+
+See :ref:`dma-drivers-api`
+
+.. note:: The API is accessed through a common structure however an
+   implementation may keep some specific private data, attached to the
+   ``dma.private`` pointer.
+
+Initialization of DMACs
+=======================
+
+The probing is done during the platform initialization by calling
+``dma_probe()`` on each ``dma`` instance inside the ``platform_init()``::
+
+   int (*probe)(struct dma *dma);
+
+More aggressive power optimization approach may require to probe the devices on
+demand, right before use.
+
+A static array of ``dma`` instances declared in the platform's code for
+*library/dma* may need replacement with a dynamic method that discovers the
+quantities available on the platform using capability registers provided by the
+HW.
+
+Requesting a Channel
+====================
+
+In case the host co-manages the DMA HW and the channel is "allocated" by the
+host side, the FW component has to wait until its ``params()`` API is called
+in order to learn the channel ID and pass it to the ``channel_get()`` request.
+
+.. _dma-drivers-supported-devices:
+
+Supported Devices
+*****************
@@ -0,0 +1,11 @@
+.. _drivers:
+
+Drivers
+#######
+
+Location: *src/drivers*
+
+.. toctree::
+   :maxdepth: 1
+
+   dma/index
@@ -0,0 +1,10 @@
+.. _developer_guides:
+
+Developer Guides
+################
+
+.. toctree::
+   :maxdepth: 1
+
+   porting
+   drivers/index
@@ -0,0 +1,21 @@
+.. _porting:
+
+Porting Guides
+##############
+
+Architecture Porting Guide
+**************************
+
+Platform Porting Guide
+**********************
+
+Platform Interface
+==================
+
+Location: *src/platform*
+
+Main Interface
+--------------
+
+Clock Interface
+----------------
@@ -27,6 +27,8 @@ Sections
    introduction/index.rst
    getting_started/index.rst
    platforms/index.rst
+   developer_guides/index.rst
    release_notes.rst
    howtos/index.rst
    contribute/index.rst
+   api/index.rst