EP93xx: Document DMA M2P API
PATCH 1/1 EP93xx: Document DMA M2P API
Add documentation for the EP93xx DMA memory to peripheral/peripheral to memory API.
---
arch/arm/mach-ep93xx/include/mach/dma.h +81 -8
@@ -1,6 +1,11 @@ -/* -* arch/arm/mach-ep93xx/include/mach/dma.h -*/ +/** +* EP93xx DMA M2P memory to peripheral and peripheral to memory engine +* +* DMA M2P channels are available for audio, UARTs and IrDA. See chapter 10 of +* the EP93xx users guide for full details on the DMA M2P engine. +* See sound/soc/ep93xx/ep93xx-pcm.c for an example use of the DMA M2P code. +* +*/ #ifndef __ASM_ARCH_DMA_H#define __ASM_ARCH_DMA_H
@@ -8,12 +13,29 @@#include <linux/list.h> #include <linux/types.h> +/** +* Information about a buffer to be transferred using the DMA M2P engine +* +* @list: Entry in DMA buffer list +* @bus_addr: Physical address of the buffer +* @size: Size of the buffer in bytes +*/ struct ep93xx_dma_buffer {struct list_head list;u32 bus_addr;u16 size; }; +/** +* Information about a DMA M2P client +* +* @name: Unique name for this client +* @flags: Client flags +* @cookie: User data to pass to callback functions +* @buffer_started: Non NULL function to call when a transfer is started +* @buffer_finished: Non NULL function to call when a transfer is completed +* @channel: Internal DMA M2P channel pointer. Do not modify +*/ struct ep93xx_dma_m2p_client {char *name;u8 flags;
@@ -28,6 +50,9 @@ struct ep93xx_dma_m2p_client {void *channel; }; +/** +* DMA M2P ports +*/ #define EP93XX_DMA_M2P_PORT_I2S1 0x00#define EP93XX_DMA_M2P_PORT_I2S2 0x01#define EP93XX_DMA_M2P_PORT_AAC1 0x02
@@ -39,18 +64,66 @@ struct ep93xx_dma_m2p_client {#define EP93XX_DMA_M2P_PORT_UART3 0x08#define EP93XX_DMA_M2P_PORT_IRDA 0x09#define EP93XX_DMA_M2P_PORT_MASK 0x0f -#define EP93XX_DMA_M2P_TX 0x00 -#define EP93XX_DMA_M2P_RX 0x10 -#define EP93XX_DMA_M2P_ABORT_ON_ERROR 0x20 -#define EP93XX_DMA_M2P_IGNORE_ERROR 0x40 -#define EP93XX_DMA_M2P_ERROR_MASK 0x60 +/** +* DMA M2P client flags +*/ +#define EP93XX_DMA_M2P_TX 0x00/* Memory to peripheral */ +#define EP93XX_DMA_M2P_RX 0x10/* Peripheral to memory */ + +/** +* DMA M2P client error handling flags. See the EP93xx users guide +* documentation on the DMA M2P CONTROL register for more details +*/ +#define EP93XX_DMA_M2P_ABORT_ON_ERROR 0x20/* Abort on peripheral error */ +#define EP93XX_DMA_M2P_IGNORE_ERROR 0x40/* Ignore peripheral errors */ +#define EP93XX_DMA_M2P_ERROR_MASK 0x60/* Mask of error bits */ + +/** +* Register a client with the DMA M2P subsystem. The DMA M2P subsystem +* allocates a channel and an interrupt line for the DMA client. +* +* @m2p: Client information to register +* returns 0 on success +*/ int ep93xx_dma_m2p_client_register (struct ep93xx_dma_m2p_client *m2p); + +/** +* Unregister a DMA M2P subsystem. Any transfers currently in progress will be +* completed in hardware, but ignored in software. +* +* @m2p: Client to unregister +*/ void ep93xx_dma_m2p_client_unregister (struct ep93xx_dma_m2p_client *m2p); + +/** +* Submit a DMA M2P transfer. If the current or next transfer positions are +* free on the M2P client then the transfer is started immediately. If not, +* the transfer is added to the list of pending transfers. This function must +* not be called from the buffer_finished callback for an M2P channel. +* +* @m2p: DMA Client to submit the transfer on +* @buf: DMA Buffer to submit +*/ void ep93xx_dma_m2p_submit (struct ep93xx_dma_m2p_client *m2p,struct ep93xx_dma_buffer *buf); + +/** +* Put a DMA transfer on the pending list for an M2P channel. This function +* must only be called from the buffer_finished callback for an M2P channel. +* +* @m2p: DMA Client to submit the transfer on +* @buf: DMA Buffer to submit +*/ void ep93xx_dma_m2p_submit_recursive (struct ep93xx_dma_m2p_client *m2p,struct ep93xx_dma_buffer *buf); + +/** +* Flush all pending transfers on a DMA M2P client. Any transfers currently +* in progress will be completed in hardware, but ignored in software. +* +* @m2p: DMA client to flush transfers on +*/ void ep93xx_dma_m2p_flush (struct ep93xx_dma_m2p_client *m2p);#endif /* __ASM_ARCH_DMA_H */
PATCH 1/1 EP93xx: Document DMA M2P API
Quoted 2 lines · Ryan Mallon
Add documentation for the EP93xx DMA memory to peripheral/peripheral to memory API.
This is a good thing but I think that you might want to use standard kernel-doc style comments (see Documentation/kernel-doc-nano-HOWTO.txt) so that we can get nicely formatted document of the DMA API when 'make *docs' is run.
arch/arm/mach-ep93xx/include/mach/dma.h line 2
Quoted 13 lines
Signed-off-by Ryan Mallon <[email protected]>---
arch/arm/mach-ep93xx/include/mach/dma.h +2
-3@@ -1,6 +1,11 @@ -/* -* arch/arm/mach-ep93xx/include/mach/dma.h -*/ +/** +* EP93xx DMA M2P memory to peripheral and peripheral to memory engine
For this you need to use something like:
/**
* DOC: EP93xx DMA M2P memory to peripheral and peripheral to memory engine *
...
Quoted 10 lines
arch/arm/mach-ep93xx/include/mach/dma.h +6
-0+* +* DMA M2P channels are available for audio, UARTs and IrDA. See chapter 10 of +* the EP93xx users guide for full details on the DMA M2P engine. +* See sound/soc/ep93xx/ep93xx-pcm.c for an example use of the DMA M2P code. +* +*/ #ifndef __ASM_ARCH_DMA_H#define __ASM_ARCH_DMA_H
arch/arm/mach-ep93xx/include/mach/dma.h line 17
Quoted 5 lines
arch/arm/mach-ep93xx/include/mach/dma.h +2
-0@@ -8,12 +13,29 @@#include <linux/list.h> #include <linux/types.h> +/** +* Information about a buffer to be transferred using the DMA M2P engine
/**
* struct ep93xx_dma_buffer - buffer to be transferred using the DMA M2P engine
arch/arm/mach-ep93xx/include/mach/dma.h line 30
Quoted 13 lines
arch/arm/mach-ep93xx/include/mach/dma.h +7
-0+* +* @list: Entry in DMA buffer list +* @bus_addr: Physical address of the buffer +* @size: Size of the buffer in bytes +*/ struct ep93xx_dma_buffer {struct list_head list;u32 bus_addr;u16 size; }; +/** +* Information about a DMA M2P client
ditto
Quoted 12 lines
arch/arm/mach-ep93xx/include/mach/dma.h +8
-0+* +* @name: Unique name for this client +* @flags: Client flags +* @cookie: User data to pass to callback functions +* @buffer_started: Non NULL function to call when a transfer is started +* @buffer_finished: Non NULL function to call when a transfer is completed +* @channel: Internal DMA M2P channel pointer. Do not modify +*/ struct ep93xx_dma_m2p_client {char *name;u8 flags;
arch/arm/mach-ep93xx/include/mach/dma.h struct ep93xx_dma_m2p_client { · line 53
Quoted 4 lines
arch/arm/mach-ep93xx/include/mach/dma.h +1
-0@@ -28,6 +50,9 @@ struct ep93xx_dma_m2p_client {void *channel; }; +/**
Don't use /** here as this is just a normal comment.
Quoted 6 lines
arch/arm/mach-ep93xx/include/mach/dma.h +2
-0+* DMA M2P ports +*/ #define EP93XX_DMA_M2P_PORT_I2S1 0x00#define EP93XX_DMA_M2P_PORT_I2S2 0x01#define EP93XX_DMA_M2P_PORT_AAC1 0x02
arch/arm/mach-ep93xx/include/mach/dma.h struct ep93xx_dma_m2p_client { · line 68
Quoted 10 lines
arch/arm/mach-ep93xx/include/mach/dma.h +1
-5@@ -39,18 +64,66 @@ struct ep93xx_dma_m2p_client {#define EP93XX_DMA_M2P_PORT_UART3 0x08#define EP93XX_DMA_M2P_PORT_IRDA 0x09#define EP93XX_DMA_M2P_PORT_MASK 0x0f -#define EP93XX_DMA_M2P_TX 0x00 -#define EP93XX_DMA_M2P_RX 0x10 -#define EP93XX_DMA_M2P_ABORT_ON_ERROR 0x20 -#define EP93XX_DMA_M2P_IGNORE_ERROR 0x40 -#define EP93XX_DMA_M2P_ERROR_MASK 0x60 +/**
ditto
arch/arm/mach-ep93xx/include/mach/dma.h struct ep93xx_dma_m2p_client { · line 74
Quoted 6 lines
arch/arm/mach-ep93xx/include/mach/dma.h +6
-0+* DMA M2P client flags +*/ +#define EP93XX_DMA_M2P_TX 0x00/* Memory to peripheral */ +#define EP93XX_DMA_M2P_RX 0x10/* Peripheral to memory */ + +/**
ditto
arch/arm/mach-ep93xx/include/mach/dma.h struct ep93xx_dma_m2p_client { · line 83
Quoted 9 lines
arch/arm/mach-ep93xx/include/mach/dma.h +9
-0+* DMA M2P client error handling flags. See the EP93xx users guide +* documentation on the DMA M2P CONTROL register for more details +*/ +#define EP93XX_DMA_M2P_ABORT_ON_ERROR 0x20/* Abort on peripheral error */ +#define EP93XX_DMA_M2P_IGNORE_ERROR 0x40/* Ignore peripheral errors */ +#define EP93XX_DMA_M2P_ERROR_MASK 0x60/* Mask of error bits */ + +/** +* Register a client with the DMA M2P subsystem. The DMA M2P subsystem
/**
* ep93xx_dma_m2p_client_register - register a client ..
Also you might want to put these function comments in the .c file (so they are as close the actual code as possible).
Regards,
MW
Quoted 46 lines
arch/arm/mach-ep93xx/include/mach/dma.h +37
-0+* allocates a channel and an interrupt line for the DMA client. +* +* @m2p: Client information to register +* returns 0 on success +*/ int ep93xx_dma_m2p_client_register (struct ep93xx_dma_m2p_client *m2p); + +/** +* Unregister a DMA M2P subsystem. Any transfers currently in progress will be +* completed in hardware, but ignored in software. +* +* @m2p: Client to unregister +*/ void ep93xx_dma_m2p_client_unregister (struct ep93xx_dma_m2p_client *m2p); + +/** +* Submit a DMA M2P transfer. If the current or next transfer positions are +* free on the M2P client then the transfer is started immediately. If not, +* the transfer is added to the list of pending transfers. This function must +* not be called from the buffer_finished callback for an M2P channel. +* +* @m2p: DMA Client to submit the transfer on +* @buf: DMA Buffer to submit +*/ void ep93xx_dma_m2p_submit (struct ep93xx_dma_m2p_client *m2p,struct ep93xx_dma_buffer *buf); + +/** +* Put a DMA transfer on the pending list for an M2P channel. This function +* must only be called from the buffer_finished callback for an M2P channel. +* +* @m2p: DMA Client to submit the transfer on +* @buf: DMA Buffer to submit +*/ void ep93xx_dma_m2p_submit_recursive (struct ep93xx_dma_m2p_client *m2p,struct ep93xx_dma_buffer *buf); + +/** +* Flush all pending transfers on a DMA M2P client. Any transfers currently +* in progress will be completed in hardware, but ignored in software. +* +* @m2p: DMA client to flush transfers on +*/ void ep93xx_dma_m2p_flush (struct ep93xx_dma_m2p_client *m2p);#endif /* __ASM_ARCH_DMA_H */
PATCH 1/1 EP93xx: Document DMA M2P API
Quoted 8 lines · Mika Westerberg
Quoted 2 lines · Ryan Mallon
Add documentation for the EP93xx DMA memory to peripheral/peripheral to memory API.
This is a good thing but I think that you might want to use standard kernel-doc style comments (see
Documentation/kernel-doc-nano-HOWTO.txt) so that we can get nicely formatted document of the DMA API when 'make *docs' is run.
Ah, thanks. I didn't know there was documentation for kernel-doc :-). I had just been copying the way other subsystems were done. Will fix up and repost.
Quoted 7 lines
/**
*ep93xx_dma_m2p_client_register- register a client ..Also you might want to put these function comments in the .c file (so they are as close the actual code as possible).
I prefer the comments in the header, since if the API documentation is good the user will never have to look at the C code.
~Ryan
Signature · 7 lines
Bluewater Systems Ltd - ARM Technology Solution Centre Ryan Mallon 5 Amuri Park, 404 Barbadoes St ryan at bluewatersys.com PO Box 13 889, Christchurch 8013 http://www.bluewatersys.com New Zealand Phone: +64 3 3779127 Freecall: Australia 1800 148 751 Fax: +64 3 3779135 USA 1800 261 2934
PATCH 1/1 EP93xx: Document DMA M2P API
In reply to Mika WesterbergQuoted 10 lines · Mika Westerberg
Quoted 3 lines · Ryan Mallon
Add documentation for the EP93xx DMA memory to peripheral/peripheral to memory API.
This is a good thing but I think that you might want to use standard kernel-doc style comments (see
Documentation/kernel-doc-nano-HOWTO.txt) so that we can get nicely formatted document of the DMA API when 'make *docs' is run.
Here is the updated patch which uses proper kernel-doc formatting. I have also expanded the documentation in a couple of places.
---
arch/arm/mach-ep93xx/include/mach/dma.h +103 -10
@@ -1,6 +1,14 @@ -/* -* arch/arm/mach-ep93xx/include/mach/dma.h -*/ +/** +* DOC: EP93xx DMA M2P memory to peripheral and peripheral to memory engine +* +* The EP93xx DMA M2P subsystem handles DMA transfers between memory and +* peripherals. DMA M2P channels are available for audio, UARTs and IrDA. +* See chapter 10 of the EP93xx users guide for full details on the DMA M2P +* engine. +* +* See sound/soc/ep93xx/ep93xx-pcm.c for an example use of the DMA M2P code. +* +*/ #ifndef __ASM_ARCH_DMA_H#define __ASM_ARCH_DMA_H
@@ -8,12 +16,34 @@#include <linux/list.h> #include <linux/types.h> +/** +* struct ep93xx_dma_buffer - Information about a buffer to be transferred +* using the DMA M2P engine +* +* @list: Entry in DMA buffer list +* @bus_addr: Physical address of the buffer +* @size: Size of the buffer in bytes +*/ struct ep93xx_dma_buffer {struct list_head list;u32 bus_addr;u16 size; }; +/** +* struct ep93xx_dma_m2p_client - Information about a DMA M2P client +* +* @name: Unique name for this client +* @flags: Client flags +* @cookie: User data to pass to callback functions +* @buffer_started: Non NULL function to call when a transfer is started. +* The arguments are the user data cookie and the DMA +* buffer which is starting. +* @buffer_finished: Non NULL function to call when a transfer is completed. +* The arguments are the user data cookie, the DMA buffer +* which has completed, and a boolean flag indicating if +* the transfer had an error. +*/ struct ep93xx_dma_m2p_client {char *name;u8 flags;
@@ -24,10 +54,11 @@ struct ep93xx_dma_m2p_client {struct ep93xx_dma_buffer *buf, int bytes, int error); -/* Internal to the DMA code. */ +/* private: Internal use only */ void *channel; }; +/* DMA M2P ports */ #define EP93XX_DMA_M2P_PORT_I2S1 0x00#define EP93XX_DMA_M2P_PORT_I2S2 0x01#define EP93XX_DMA_M2P_PORT_AAC1 0x02
@@ -39,18 +70,80 @@ struct ep93xx_dma_m2p_client {#define EP93XX_DMA_M2P_PORT_UART3 0x08#define EP93XX_DMA_M2P_PORT_IRDA 0x09#define EP93XX_DMA_M2P_PORT_MASK 0x0f -#define EP93XX_DMA_M2P_TX 0x00 -#define EP93XX_DMA_M2P_RX 0x10 -#define EP93XX_DMA_M2P_ABORT_ON_ERROR 0x20 -#define EP93XX_DMA_M2P_IGNORE_ERROR 0x40 -#define EP93XX_DMA_M2P_ERROR_MASK 0x60 -int ep93xx_dma_m2p_client_register (struct ep93xx_dma_m2p_client *m2p); +/* DMA M2P client flags */ +#define EP93XX_DMA_M2P_TX 0x00/* Memory to peripheral */ +#define EP93XX_DMA_M2P_RX 0x10/* Peripheral to memory */ + +/* +* DMA M2P client error handling flags. See the EP93xx users guide +* documentation on the DMA M2P CONTROL register for more details +*/ +#define EP93XX_DMA_M2P_ABORT_ON_ERROR 0x20/* Abort on peripheral error */ +#define EP93XX_DMA_M2P_IGNORE_ERROR 0x40/* Ignore peripheral errors */ +#define EP93XX_DMA_M2P_ERROR_MASK 0x60/* Mask of error bits */ + +/** +* ep93xx_dma_m2p_client_register - Register a client with the DMA M2P +* subsystem +* +* @m2p: Client information to register +* returns 0 on success +* +* The DMA M2P subsystem allocates a channel and an interrupt line for the DMA +* client +*/ +int ep93xx_dma_m2p_client_register (struct ep93xx_dma_m2p_client *m2p); + +/** +* ep93xx_dma_m2p_client_unregister - Unregister a client from the DMA M2P +* subsystem +* +* @m2p: Client to unregister +* +* Any transfers currently in progress will be completed in hardware, but +* ignored in software. +*/ void ep93xx_dma_m2p_client_unregister (struct ep93xx_dma_m2p_client *m2p); + +/** +* ep93xx_dma_m2p_submit - Submit a DMA M2P transfer +* +* @m2p: DMA Client to submit the transfer on +* @buf: DMA Buffer to submit +* +* If the current or next transfer positions are free on the M2P client then +* the transfer is started immediately. If not, the transfer is added to the +* list of pending transfers. This function must not be called from the +* buffer_finished callback for an M2P channel. +* +*/ void ep93xx_dma_m2p_submit (struct ep93xx_dma_m2p_client *m2p,struct ep93xx_dma_buffer *buf); + +/** +* ep93xx_dma_m2p_submit_recursive - Put a DMA transfer on the pending list +* for an M2P channel +* +* @m2p: DMA Client to submit the transfer on +* @buf: DMA Buffer to submit +* +* This function must only be called from the buffer_finished callback for an +* M2P channel. It is commonly used to add the next transfer in a chained list +* of DMA transfers. +*/ void ep93xx_dma_m2p_submit_recursive (struct ep93xx_dma_m2p_client *m2p,struct ep93xx_dma_buffer *buf); + +/** +* ep93xx_dma_m2p_flush - Flush all pending transfers on a DMA M2P client +* +* @m2p: DMA client to flush transfers on +* +* Any transfers currently in progress will be completed in hardware, but +* ignored in software. +* +*/ void ep93xx_dma_m2p_flush (struct ep93xx_dma_m2p_client *m2p);#endif /* __ASM_ARCH_DMA_H */
PATCH 1/1 EP93xx: Document DMA M2P API
Quoted 5 lines · Ryan Mallon
Here is the updated patch which uses proper kernel-doc formatting. I have also expanded the documentation in a couple of places.
Signed-off-by Ryan Mallon <[email protected]>
Looks good.
Regards,
MW