xtalk_dma(D3)
xtalk_dmatrans_addr - construct DMA address xtalk_dmatrans_list - construct DMA addresses xtalk_dmamap_alloc - allocate an XIO DMA channel xtalk_dmamap_addr - set DMA channel target xtalk_dmamap_list - set DMA channel targets xtalk_dmamap_done - mark DMA channel unused xtalk_dmamap_free - release XIO DMA channel resources xtalk_dmamap_drain - drain a DMA MAP based DMA path xtalk_dmaaddr_drain - drain a DMA path to a specific block xtalk_dmalist_drain - drain a DMA path for an alenlist
As shipped in IRIX 6.5.15. Last changed in IRIX 6.5.15.
NAME xtalk_dmatrans_addr - construct DMA address xtalk_dmatrans_list - construct DMA addresses xtalk_dmamap_alloc - allocate an XIO DMA channel xtalk_dmamap_addr - set DMA channel target xtalk_dmamap_list - set DMA channel targets xtalk_dmamap_done - mark DMA channel unused xtalk_dmamap_free - release XIO DMA channel resources xtalk_dmamap_drain - drain a DMA MAP based DMA path xtalk_dmaaddr_drain - drain a DMA path to a specific block xtalk_dmalist_drain - drain a DMA path for an alenlist SYNOPSIS #include <sys/xtalk/xtalk.h> iopaddr_t xtalk_dmatrans_addr( vertex_hdl_t vhdl, device_desc_t desc, iopaddr_t addr, size_t size, unsigned flags) alenlist_t xtalk_dmatrans_list( vertex_hdl_t vhdl, device_desc_t desc, alenlist_t list, unsigned flags) xtalk_dmamap_t xtalk_dmamap_alloc( vertex_hdl_t vhdl, device_desc_t desc, xtalk_space_t space, size_t max, unsigned flags) iopaddr_t xtalk_dmamap_addr( xtalk_dmamap_t map, iopaddr_t addr, size_t size); alenlist_t xtalk_dmamap_list( xtalk_dmamap_t map, alenlist_t list, unsigned flags); void xtalk_dmamap_done(xtalk_dmamap_t xtalk_dmamap) void xtalk_dmamap_free(xtalk_dmamap_t xtalk_dmamap) void xtalk_dmamap_drain( xtalk_dmamap_t *xtalk_dmamap) void xtalk_dmaaddr_drain( vertex_hdl_t vhdl, paddr_t addr, size_t bytes) void xtalk_dmalist_drain( vertex_hdl_t vhdl, alenlist_t *list) Arguments vhdl is the appropriate XIO connection point. desc is a device descriptor, usually zero. addr is the offset within the space. size is the size of the mapped region. list is an ordered list of address/length pairs. max is the maximum size mapped at any one time. flags is used to specify attributes of the mapping. DESCRIPTION When a device driver wishes to use Direct Memory Access (DMA) to communicate with a device, the system needs to have a chance to set up any appropriate mapping registers. There are two different models for how to do this. The simple model provides permanent mappings through fixed mapping resources. o xtalk_dmatrans_addr() is the one-stop shopping place for using system fixed shareable mapping resources to construct an XIO DMA address that will land the DMA requests at the targeted memory location. This is not always possible, and when it is not, the function will return NULL. o xtalk_dmatrans_list() is similar, but operates on a list of blocks of memory returning a list of blocks of XIO space. It is not always possible to establish such mappings using common shared system resources, so the concept of a DMA channel that preallocates scarce mapping resources is provided. Such channels are allocated using xtalk_dmamap_alloc(), which is given the maximum size to be mapped. o xtalk_dmamap_addr() or xtalk_dmamap_list() is then used to actually establish the proper mappings for a DMA target; given the base address and block size of the region for DMA (or a list of these), it will hand back the base XIO address to be used for accessing that region (or a list of these). o If the same DMA channel is to be used at different times to map different target areas, xtalk_dmamap_done() should be called to idle any mapping hardware (and possibly flush out any pipes or buffers along the path that might do unexpected things when mapping registers are modified). Then xtalk_dmamap_addr() or xtalk_dmamap_list() can again be called, specifying the new target area. When a driver is completely finished with a DMA channel -- either because the channel is used only for initialization of the device, or because the device or the driver is being shut down -- the DMA channel resources should be released back to the system using xtalk_dmamap_free(). xtalk_dmamap_drain(), xtalk_dmaaddr_drain() and xtalk_dmalist_drain() are used after a device reports it has completed DMA, to be sure that all data along the DMA path has in fact reached its destination. DMA Attribute Flags All functions that have flag words can be asked to set up or disable certain DMA acceleration features of whatever machine is in use. XTALK_INPLACE When list operations are performed, this flag requests that the list be modified in place. If this flag is not specified, the infrastructure will attempt to allocate a new list for the result data, which will take longer and may fail but which will avoid modifying the input list. XTALK_NOSLEEP If this flag is specified, any resources that are needed from the system are allocated without sleeping. If any resource allocation would have required the infrastructure to sleep, the service call will return a failure code. Translation Results If the target of the DMA is not in fact memory, the result of a translation may be a packed XIO address, which contains not only the usual 48-bit offset in the target port, but the actual 4-bit target XIO port number. While this is likely to be a rare condition, triggered only when code explicitly schedules DMA to a destination that is memory-mapped from another device, it is advisable for all drivers calling xtalk_dma*() services to check for and handle these packed addresses. For more information, see XIO_PACK(D3). EXAMPLES Here is one way that a driver might make use of dmamap and dmatrans calls. xiofoo_attach(vertex_hdl_t vhdl) { xtalk_dmamap_t command_map; iopaddr_t command_dma; struct xiofoo_regs *reg_pio; struct xiofoo_ring *command_ring; ... /* * This driver has decided to use a dmamap * to get to its command rings, which contain * things like DMA addresses and counts. */ /* allocate the channel */ command_map = xtalk_dmamap_alloc (vhdl, 0, RINGBYTES, 0); command_dma = xtalk_dmamap_addr( command_map, kvtophys(command_ring), RINGBYTES); /* tell the device where it can find * it's command rings. */ reg_pio->command_dma = command_dma; ... } { caddr_t data_buffer; size_t data_size; ... data_dma = xtalk_dmatrans_addr(vhdl, 0, kvtophys(data_buffer), data_size, 0); command_ring->data_dma_addr = data_dma; command_ring->data_dma_size = data_size; command_ring->ready = 1; } SEE ALSO XIO_PACK(D3), xtalk(D3), xtalk_error(D3), xtalk_get(D3), xtalk_intr(D3), xtalk_pio(D3). DIAGNOSTICS xtalk_dmatrans_addr() will return XIO_NOWHERE if shared (fixed) resources can not be used to construct a valid XIO address that maps to the desired range of physical addresses. xtalk_dmatrans_list() will return a null pointer if any of the requested physical address blocks can not be reached using shared fixed resources, or if unable to allocate a return list. xtalk_dmamap_alloc() will return a null pointer if resources can not be allocated to establish DMA mappings of the requested size, or if the parameters are inconsistent. xtalk_dmamap_addr() will return a null pointer if the specified target address can not be mapped using the specified DMA channel; this would usually be due to specifying a target block that is outside the previously specified target area or is larger than the previously specified maximum mapping size. It may also return a null pointer if the DMA channel is currently in use and has not been marked idle by a xtalk_dmamap_done() call. xtalk_dmamap_addr() can return a null pointer for all the reasons mentioned above, or if it is unable to allocate the return list.