ddi_dma_addr_bind_handle man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]


       ddi_dma_addr_bind_handle - binds an address to a DMA handle

       #include <sys/ddi.h>
       #include <sys/sunddi.h>

       int ddi_dma_addr_bind_handle(ddi_dma_handle_t handle, struct as *as,
	    caddr_t addr, size_t len, uint_t flags, int (*callback) (caddr_t) ,
	    caddr_t arg, ddi_dma_cookie_t *cookiep, uint_t *ccountp);

       Solaris DDI specific (Solaris DDI).

		    The	   DMA	handle	previously  allocated  by  a  call  to

		    A pointer to an address space  structure.  This  parameter
		    should be set to NULL, which implies kernel address space.

		    Virtual address of the memory object.

		    Length of the memory object in bytes.

		    Valid flags include:

					   Transfer  direction	is from memory
					   to I/O.

					   Transfer direction is from  I/O  to

					   Both read and write.

					   Establish  an MMU redzone at end of
					   the object.

					   Partial resource allocation.

					   Nonsequential,  random,  and	 small
					   block transfers.

					   Sequential,	unidirectional, block-
					   sized, and block-aligned transfers.

		    The address of a function to call back later if  resources
		    are	 not  currently available. The following special func‐
		    tion addresses may also  be used.

					 Wait until resources are available.

					 Do  not  wait	until  resources   are
					 available and do not schedule a call‐

		    Argument to be passed to the callback function,  callback,
		    if such a function is specified.

		    A pointer to the first  ddi_dma_cookie(9S) structure.

		    Upon  a successful return,	ccountp points to a value rep‐
		    resenting the number of cookies for this DMA object.

       ddi_dma_addr_bind_handle() allocates DMA resources for a memory	object
       such  that  a  device  can  perform  DMA	 to  or	 from the object.  DMA
       resources are allocated considering  the	 device's  DMA	attributes  as
       expressed by ddi_dma_attr(9S) (see ddi_dma_alloc_handle(9F)).

       ddi_dma_addr_bind_handle()  fills in the first DMA cookie pointed to by
       cookiep with the appropriate address, length, and bus  type.   *ccountp
       is  set to the number of DMA cookies representing this DMA object. Sub‐
       sequent DMA cookies must be retrieved by calling ddi_dma_nextcookie(9F)
       the number of times specified by *countp-1.

       When a DMA transfer completes, the driver frees up system DMA resources
       by calling ddi_dma_unbind_handle(9F).

       The flags argument contains information for mapping routines.


	   These flags describe the intended direction of the DMA transfer.


	   This flag should be set if the device is doing  sequential,	unidi‐
	   rectional, block-sized, and block-aligned transfers to or from mem‐
	   ory.	 The  alignment	 and  padding  constraints  specified  by  the
	   minxfer  and	 burstsizes  fields  in	 the  DMA attribute structure,
	   ddi_dma_attr(9S) (see ddi_dma_alloc_handle(9F)) is used to allocate
	   the most effective hardware support for large transfers.


	   This flag should be set if  the device accesses memory randomly, or
	   if synchronization steps using ddi_dma_sync(9F) need to be as effi‐
	   cient  as  possible.	 I/O  parameter	 blocks used for communication
	   between  a  device  and  a  driver  should	be   allocated	 using


	   If  this flag is set, the system attempts to	 establish a protected
	   red zone after the object. The DMA resource allocation functions do
	   not	guarantee  the success of this request as some implementations
	   may not have the hardware ability to support a red zone.


	   Setting this flag indicates the caller  can	accept	resources  for
	   part	 of the object. That is, if the size of the object exceeds the
	   resources available, only resources for a portion of the object are
	   allocated.  The system indicates this condition by returning status
	   DDI_DMA_PARTIAL_MAP.	 At  a	later  point,  the  caller   can   use
	   ddi_dma_getwin(9F)  to  change  the valid portion of the object for
	   which resources are allocated. If resources were allocated for only
	   part	 of  the  object, ddi_dma_addr_bind_handle() returns resources
	   for the first DMAwindow. Even when DDI_DMA_PARTIAL is set, the sys‐
	   tem	may  decide  to allocate resources for the entire object (less
	   overhead) in which case DDI_DMA_MAPPED is returned.

       The callback function callback indicates how a caller wants  to	handle
       the possibility of resources not being available. If callback is set to
       DDI_DMA_DONTWAIT, the caller does not care if the allocation fails, and
       can  handle  an allocation failure appropriately. If callback is set to
       DDI_DMA_SLEEP, the caller wishes to have the allocation	routines  wait
       for  resources to become available. If any other value is set and a DMA
       resource allocation fails, this value is assumed to be the address of a
       function to be called when resources  become available. When the speci‐
       fied function is called,	 arg is passed to it as an argument. The spec‐
       ified  callback function must  return either DDI_DMA_CALLBACK_RUNOUT or
       DDI_DMA_CALLBACK_DONE. DDI_DMA_CALLBACK_RUNOUT indicates that the call‐
       back  function attempted to allocate DMA resources but failed.  In this
       case, the callback function is put back on a list to  be	 called	 again
       later.  DDI_DMA_CALLBACK_DONE  indicates	 that either the allocation of
       DMA resources was successful or the driver no longer wishes to retry.

       The callback function is called in interrupt context.  Therefore,  only
       system  functions  accessible  from interrupt context are be available.
       The callback function must take whatever steps are necessary to protect
       its critical resources, data structures, queues, and so on.

       ddi_dma_addr_bind_handle() returns:

			       Successfully allocated resources for the entire

			       Successfully allocated resources for a part  of
			       the  object.  This  is  acceptable when partial
			       transfers  are	permitted   by	 setting   the
			       DDI_DMA_PARTIAL flag in flags.

			       Another	I/O  transaction is using the DMA han‐

			       No resources are available at the present time.

			       The object cannot  be  reached  by  the	device
			       requesting the resources.

			       The  object is too big.	A request of this size
			       can never be  satisfied on this particular sys‐
			       tem.   The  maximum  size  varies  depending on
			       machine and configuration.

       ddi_dma_addr_bind_handle() can be called from user, kernel,  or	inter‐
       rupt  context,  except when callback is set to  DDI_DMA_SLEEP, in which
       case it can only be called from user or kernel context.

       ddi_dma_alloc_handle(9F), ddi_dma_free_handle(9F),  ddi_dma_getwin(9F),
       ddi_dma_mem_alloc(9F),	ddi_dma_mem_free(9F),  ddi_dma_nextcookie(9F),
       ddi_dma_sync(9F),   ddi_dma_unbind_handle(9F),	 ddi_umem_iosetup(9F),
       ddi_dma_attr(9S), ddi_dma_cookie(9S)

       Writing Device Drivers

       If  the	driver permits partial mapping with the	 DDI_DMA_PARTIAL flag,
       the number of cookies in	 each  window  may  exceed  the	 size  of  the
       device's scatter/gather list as specified in the	 dma_attr_sgllen field
       in the ddi_dma_attr(9S) structure. In this case, each  set  of  cookies
       comprising  a   DMA window will satisfy the DMA attributes as described
       in the ddi_dma_attr(9S) structure in all aspects. The driver should set
       up its DMA engine and perform one transfer for each set of cookies suf‐
       ficient for its scatter/gather list, up to the number  of  cookies  for
       this    window,	 before	  advancing   to   the	 next	window	 using

				 Jul 26, 1996	  DDI_DMA_ADDR_BIND_HANDLE(9F)

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net