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

[Francisco Iglesias]

On [2022 Jan 07] Fri 16:07:17, Peter Maydell wrote:
> 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);

Hi Peter,

> 
> 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 ?

Yes, I can see that above is not clear enough at the moment, I'll attemp to
improve and fix this in v6! I'll also correct the other issues you found in the
series!

Thank you very much for reviewing again!

Best regards,
Francisco

> 
> thanks
> -- PMM