Skip to contentSkip to conversation

EP93xx: Document DMA M2P API

PATCH New Ryan Mallon 2 participants 5 messages Oct 18, 2010 – Oct 19, 2010

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
index 3a5961d..66b1555 100644
@@ -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 */
#1 lore raw

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

---

arch/arm/mach-ep93xx/include/mach/dma.h +2 -3
index 3a5961d..66b1555 100644
@@ -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 */
#2 lore raw

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
#3 lore raw

PATCH 1/1 EP93xx: Document DMA M2P API

In reply to Mika Westerberg
Quoted 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
index 3a5961d..a917a5b 100644
@@ -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 */