Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 4ae9ca82 authored by FUJITA Tomonori's avatar FUJITA Tomonori Committed by Linus Torvalds
Browse files

Documentation: move the error handling to the better place in DMA-API-HOWTO 



Handing DMA mapping errors is essential.  Let's put it in the more
appropriate place rather than the end of the doc.

Signed-off-by: default avatarFUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent b02de871

Documentation/DMA-API-HOWTO.txt

+30 −30
Original line number Diff line number Diff line
@@ -639,6 +639,36 @@ is planned to completely remove virt_to_bus() and bus_to_virt() as 
they are entirely deprecated.  Some ports already do not provide these

as it is impossible to correctly support them.



			Handling Errors



DMA address space is limited on some architectures and an allocation

failure can be determined by:



- checking if dma_alloc_coherent returns NULL or dma_map_sg returns 0



- checking the returned dma_addr_t of dma_map_single and dma_map_page

  by using dma_mapping_error():



	dma_addr_t dma_handle;



	dma_handle = dma_map_single(dev, addr, size, direction);

	if (dma_mapping_error(dev, dma_handle)) {

		/*

		 * reduce current DMA mapping usage,

		 * delay and try again later or

		 * reset driver.

		 */

	}



Networking drivers must call dev_kfree_skb to free the socket buffer

and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook

(ndo_start_xmit). This means that the socket buffer is just dropped in

the failure case.



SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping

fails in the queuecommand hook. This means that the SCSI subsystem

passes the command to the driver again later.



		Optimizing Unmap State Space Consumption



On many platforms, dma_unmap_{single,page}() is simply a nop.
@@ -710,36 +740,6 @@ to "Closing". 


2) More to come...



			Handling Errors



DMA address space is limited on some architectures and an allocation

failure can be determined by:



- checking if dma_alloc_coherent returns NULL or dma_map_sg returns 0



- checking the returned dma_addr_t of dma_map_single and dma_map_page

  by using dma_mapping_error():



	dma_addr_t dma_handle;



	dma_handle = dma_map_single(dev, addr, size, direction);

	if (dma_mapping_error(dev, dma_handle)) {

		/*

		 * reduce current DMA mapping usage,

		 * delay and try again later or

		 * reset driver.

		 */

	}



Networking drivers must call dev_kfree_skb to free the socket buffer

and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook

(ndo_start_xmit). This means that the socket buffer is just dropped in

the failure case.



SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping

fails in the queuecommand hook. This means that the SCSI subsystem

passes the command to the driver again later.



			   Closing



This document, and the API itself, would not be in its current