Re: [PATCH v5 12/12] docs/devel: Add documentation for the DMA control interface

[Peter Maydell <peter.maydell@linaro.org>]

On Tue, 14 Dec 2021 at 11:04, Francisco Iglesias
<francisco.iglesias@xilinx.com> wrote:
>
> Also, since being the author, list myself as maintainer for the file.
>
> Signed-off-by: Francisco Iglesias <francisco.iglesias@xilinx.com>


> +DmaCtrlIfClass
> +--------------
> +
> +The ``DmaCtrlIfClass`` contains the interface methods that can be
> +implemented by a DMA engine.
> +
> +.. code-block:: c
> +
> +    typedef struct DmaCtrlIfClass {
> +        InterfaceClass parent;
> +
> +        /*
> +         * read: Start a read transfer on the DMA engine implementing the DMA
> +         * control interface
> +         *
> +         * @dma_ctrl: the DMA engine implementing this interface
> +         * @addr: the address to read
> +         * @len: the number of bytes to read at 'addr'
> +         */

The prototype seems to be missing here.

> +    } DmaCtrlIfClass;
> +
> +
> +dma_ctrl_if_read
> +----------------------------
> +
> +The ``dma_ctrl_if_read`` function is used from a model embedding the DMA engine
> +for starting DMA read transfers.
> +
> +.. code-block:: c
> +
> +    /*
> +     * Start a read transfer on a DMA engine implementing the DMA control
> +     * interface.
> +     *
> +     * @dma_ctrl: the DMA engine implementing this interface
> +     * @addr: the address to read
> +     * @len: the number of bytes to read at 'addr'
> +     */
> +    void dma_ctrl_if_read(DmaCtrlIf *dma, hwaddr addr, uint32_t len);

The method says it "starts" the transfer. How does the thing on the
end of the DMA control interface find out when the transfer completes,
or if there were any errors ?

thanks
-- PMM