ddi_dma_addr_bind_handle man page on OpenIndiana

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

ddi_dma_addr_bind_handle(Kernel Functions for Drivddi_dma_addr_bind_handle(9F)

NAME
       ddi_dma_addr_bind_handle - binds an address to a DMA handle

SYNOPSIS
       #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);

INTERFACE LEVEL
       Solaris DDI specific (Solaris DDI).

PARAMETERS
       handle	    The	   DMA	handle	previously  allocated  by  a  call  to
		    ddi_dma_alloc_handle(9F).

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

       addr	    Virtual address of the memory object.

       len	    Length of the memory object in bytes.

       flags	    Valid flags include:

		    DDI_DMA_WRITE	   Transfer direction is  from	memory
					   to I/O.

		    DDI_DMA_READ	   Transfer  direction	is from I/O to
					   memory.

		    DDI_DMA_RDWR	   Both read and write.

		    DDI_DMA_REDZONE	   Establish an MMU redzone at end  of
					   the object.

		    DDI_DMA_PARTIAL	   Partial resource allocation.

		    DDI_DMA_CONSISTENT	   Nonsequential,  random,  and	 small
					   block transfers.

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

       callback	    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.

		    DDI_DMA_SLEEP	 Wait until resources are available.

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

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

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

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

DESCRIPTION
       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.	Subse‐
       quent  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.

       DDI_DMA_WRITE, DDI_DMA_READ, DDI_DMA_RDWR

	   These flags describe the intended direction of the DMA transfer.

       DDI_DMA_STREAMING

	   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.

       DDI_DMA_CONSISTENT

	   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
	   DDI_DMA_CONSISTENT.

       DDI_DMA_REDZONE

	   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.

       DDI_DMA_PARTIAL

	   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.

RETURN VALUES
       ddi_dma_addr_bind_handle() returns:

       DDI_DMA_MAPPED	       Successfully allocated resources for the entire
			       object.

       DDI_DMA_PARTIAL_MAP     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.

       DDI_DMA_INUSE	       Another I/O transaction is using the  DMA  han‐
			       dle.

       DDI_DMA_NORESOURCES     No resources are available at the present time.

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

       DDI_DMA_TOOBIG	       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.

CONTEXT
       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.

SEE ALSO
       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

NOTES
       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
       sufficient for its scatter/gather list, up to the number of cookies for
       this   window,	before	 advancing   to	  the	next   window	 using
       ddi_dma_getwin(9F).

SunOS 5.11			  26 Jul 1996	  ddi_dma_addr_bind_handle(9F)
[top]

List of man pages available for OpenIndiana

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]
Tweet
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