pci_map_single return value

[Anton Blanchard]

Hi Brian,

> How does this look?

This is what I currently have, it adds some documentation and links into
the generic DMA API.

Anton

===== Documentation/DMA-API.txt 1.3 vs edited =====
--- 1.3/Documentation/DMA-API.txt	Mon May 26 16:18:46 2003
+++ edited/Documentation/DMA-API.txt	Sun Dec 21 07:16:36 2003
@@ -199,6 +199,18 @@
 cache width is.

 int
+dma_error(dma_addr_t dma_addr)
+
+int
+pci_dma_error(dma_addr_t dma_addr)
+
+In some circumstances dma_map_single and dma_map_page will fail to create
+a mapping. A driver can check for these errors by testing the returned
+dma address with dma_error(). A non zero return value means the mapping
+could not be created and the driver should take appropriate action (eg
+reduce current DMA mapping usage or delay and try again later).
+
+int
 dma_map_sg(struct device *dev, struct scatterlist *sg, int nents,
 	   enum dma_data_direction direction)
 int
@@ -210,7 +222,10 @@
 Returns: the number of physical segments mapped (this may be shorted
 than <nents> passed in if the block layer determines that some
 elements of the scatter/gather list are physically adjacent and thus
-may be mapped with a single entry).
+may be mapped with a single entry).
+
+As with the other mapping interfaces, dma_map_sg can fail. When it
+does, 0 is returned and a driver should take appropriate action.

 void
 dma_unmap_sg(struct device *dev, struct scatterlist *sg, int nhwentries,
===== Documentation/DMA-mapping.txt 1.17 vs edited =====
--- 1.17/Documentation/DMA-mapping.txt	Sun Aug 17 04:46:50 2003
+++ edited/Documentation/DMA-mapping.txt	Fri Jan  2 22:50:47 2004
@@ -519,7 +519,7 @@
 ends and the second one starts on a page boundary - in fact this is a huge
 advantage for cards which either cannot do scatter-gather or have very
 limited number of scatter-gather entries) and returns the actual number
-of sg entries it mapped them to.
+of sg entries it mapped them to. On failure 0 is returned.

 Then you should loop count times (note: this can be less than nents times)
 and use sg_dma_address() and sg_dma_len() macros where you previously
@@ -809,6 +809,27 @@
    deleted.

 2) More to come...
+
+			Handling Errors
+
+DMA address space is limited on some architectures and an allocation
+failure can be determined by:
+
+- checking if pci_alloc_consistent returns NULL or pci_map_sg returns 0
+
+- checking the returned dma_addr_t of pci_map_single and pci_map_page
+  by using pci_dma_error():
+
+	dma_addr_t dma_handle;
+
+	dma_handle = pci_map_single(dev, addr, size, direction);
+	if (pci_dma_error(dma_handle)) {
+		/*
+		 * reduce current DMA mapping usage,
+		 * delay and try again later or
+		 * reset driver.
+		 */
+	}

 			   Closing

===== include/asm-generic/dma-mapping.h 1.4 vs edited =====
--- 1.4/include/asm-generic/dma-mapping.h	Tue Jan 14 09:37:47 2003
+++ edited/include/asm-generic/dma-mapping.h	Sun Dec 21 06:12:41 2003
@@ -120,6 +120,12 @@
 	pci_dma_sync_sg(to_pci_dev(dev), sg, nelems, (int)direction);
 }

+static inline int
+dma_error(dma_addr_t dma_addr)
+{
+	return pci_dma_error(dma_addr);
+}
+
 /* Now for the API extensions over the pci_ one */

 #define dma_alloc_noncoherent(d, s, h, f) dma_alloc_coherent(d, s, h, f)
===== include/asm-generic/pci-dma-compat.h 1.3 vs edited =====
--- 1.3/include/asm-generic/pci-dma-compat.h	Tue Jan 14 03:26:02 2003
+++ edited/include/asm-generic/pci-dma-compat.h	Sun Dec 21 06:09:37 2003
@@ -84,4 +84,10 @@
 	dma_sync_sg(hwdev == NULL ? NULL : &hwdev->dev, sg, nelems, (enum dma_data_direction)direction);
 }

+static inline int
+pci_dma_error(dma_addr_t dma_addr)
+{
+	return dma_error(dma_addr);
+}
+
 #endif
===== include/asm-i386/dma-mapping.h 1.2 vs edited =====
--- 1.2/include/asm-i386/dma-mapping.h	Tue Jan 14 03:28:47 2003
+++ edited/include/asm-i386/dma-mapping.h	Fri Jan  2 22:54:53 2004
@@ -91,6 +91,12 @@
 {
 	flush_write_buffers();
 }
+
+static inline int
+dma_error(dma_addr_t dma_addr)
+{
+	return 0;
+}

 static inline int
 dma_supported(struct device *dev, u64 mask)


** Sent via the linuxppc64-dev mail list. See http://lists.linuxppc.org/