diff --git a/api/dma-drivers-api.rst b/api/dma-drivers-api.rst new file mode 100644 index 00000000..86a13636 --- /dev/null +++ b/api/dma-drivers-api.rst @@ -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 diff --git a/api/index.rst b/api/index.rst new file mode 100644 index 00000000..74cb678a --- /dev/null +++ b/api/index.rst @@ -0,0 +1,10 @@ +.. _api: + +API Documentation +################# + +.. toctree:: + :maxdepth: 1 + + dma-drivers-api + uapi diff --git a/api/uapi.rst b/api/uapi.rst new file mode 100644 index 00000000..4e80433c --- /dev/null +++ b/api/uapi.rst @@ -0,0 +1,8 @@ +.. _api-uapi: + +uAPI +#### + +.. TODO: to be uncommented once repo cross ref is clarified + .. doxygengroup:: sof_uapi + :project: SOF Project diff --git a/conf.py b/conf.py index f752708c..333ff4d0 100644 --- a/conf.py +++ b/conf.py @@ -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", +} diff --git a/developer_guides/drivers/dma/images/dma-drv-use.pu b/developer_guides/drivers/dma/images/dma-drv-use.pu new file mode 100644 index 00000000..a5ab537c --- /dev/null +++ b/developer_guides/drivers/dma/images/dma-drv-use.pu @@ -0,0 +1,23 @@ + +package audio { + component "" as comp +} + +interface dma_get +component "lib::\ndma" as lib_dma + +lib_dma -up- dma_get + +interface dma_ops + +component "drivers::dma::\n" 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 diff --git a/developer_guides/drivers/dma/images/dma-ops.pu b/developer_guides/drivers/dma/images/dma-ops.pu new file mode 100644 index 00000000..7062f9e7 --- /dev/null +++ b/developer_guides/drivers/dma/images/dma-ops.pu @@ -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 diff --git a/developer_guides/drivers/dma/images/dma-transfer.pu b/developer_guides/drivers/dma/images/dma-transfer.pu new file mode 100644 index 00000000..e5594acd --- /dev/null +++ b/developer_guides/drivers/dma/images/dma-transfer.pu @@ -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# ) diff --git a/developer_guides/drivers/dma/index.rst b/developer_guides/drivers/dma/index.rst new file mode 100644 index 00000000..113036e1 --- /dev/null +++ b/developer_guides/drivers/dma/index.rst @@ -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 +***************** diff --git a/developer_guides/drivers/index.rst b/developer_guides/drivers/index.rst new file mode 100644 index 00000000..a27a8560 --- /dev/null +++ b/developer_guides/drivers/index.rst @@ -0,0 +1,11 @@ +.. _drivers: + +Drivers +####### + +Location: *src/drivers* + +.. toctree:: + :maxdepth: 1 + + dma/index diff --git a/developer_guides/index.rst b/developer_guides/index.rst new file mode 100644 index 00000000..45059226 --- /dev/null +++ b/developer_guides/index.rst @@ -0,0 +1,10 @@ +.. _developer_guides: + +Developer Guides +################ + +.. toctree:: + :maxdepth: 1 + + porting + drivers/index diff --git a/developer_guides/porting.rst b/developer_guides/porting.rst new file mode 100644 index 00000000..8a6d7c91 --- /dev/null +++ b/developer_guides/porting.rst @@ -0,0 +1,21 @@ +.. _porting: + +Porting Guides +############## + +Architecture Porting Guide +************************** + +Platform Porting Guide +********************** + +Platform Interface +================== + +Location: *src/platform* + +Main Interface +-------------- + +Clock Interface +---------------- diff --git a/index.rst b/index.rst index c1367742..c1973527 100644 --- a/index.rst +++ b/index.rst @@ -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