ddi_umem_iosetup(9f) [osx man page]

ddi_umem_iosetup(9F)					   Kernel Functions for Drivers 				      ddi_umem_iosetup(9F)

NAME

       ddi_umem_iosetup - Setup I/O requests to application memory

SYNOPSIS

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

       struct  buf  *ddi_umem_iosetup(ddi_umem_cookie_t  cookie,off_t  off, size_t  len,  int direction, dev_t dev, daddr_t blkno,   int (*iodone)
       (struct buf *), int sleepflag);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI)

PARAMETERS

       cookie	       The kernel memory cookie allocated by ddi_umem_lock(9F).

       off	       Offset from the start of the cookie.

       len	       Length of the I/O request in bytes.

       direction       Must be set to B_READ for reads from the device or B_WRITE for writes to the device.

       dev	       Device number

       blkno	       Block number on device.

       iodone	       Specific biodone(9F) routine.

       sleepflag       Determines whether caller can sleep for memory. Possible flags are DDI_UMEM_SLEEP to allow sleeping until memory is  avail-
		       able, or DDI_UMEM_NOSLEEP to return NULL immediately if memory is not available.

DESCRIPTION

       The  ddi_umem_iosetup(9F)  function  is	used  by  drivers  to  setup  I/O  requests to application memory which has been locked down using
       ddi_umem_lock(9F).

       The ddi_umem_iosetup(9F) function returns a pointer to a buf(9S) structure corresponding to the memory cookie  cookie.  Drivers	can  setup
       multiple  buffer  structures  simultaneously active using the same memory cookie. The buf(9S) structures can span all or part of the region
       represented by the cookie and can overlap each other. The buf(9S) structure can be passed to ddi_dma_buf_bind_handle(9F)  to  initiate  DMA
       transfers to or from the locked down memory.

       The off	parameter specifies the offset from the start of the cookie. The len parameter represents the length of region to be mapped by the
       buffer. The direction parameter must be set to either B_READ or B_WRITE, to indicate the action that will be performed by the device. (Note
       that  this direction is in the opposite sense of the VM system's direction of DDI_UMEMLOCK_READ and DDI_UMEMLOCK_WRITE.) The direction must
       be compatible with the flags used to create the memory cookie in ddi_umem_lock(9F). For example, if  ddi_umem_lock()  is  called  with  the
       flags parameter set to DDI_UMEMLOCK_READ, the direction parameter in ddi_umem_iosetup() should be set to B_WRITE.

       The dev parameter specifies the device to which the buffer is to perform I/O.The blkno parameter represents the block number on the device.
       It will be assigned to the b_blkno field of the returned buffer structure. The iodone parameter enables the driver to identify  a  specific
       biodone(9F)  routine  to  be called by the driver when the I/O is complete. The sleepflag  parameter determines if the caller can sleep for
       memory. DDI_UMEM_SLEEP allocations may sleep but are guaranteed to succeed. DDI_UMEM_NOSLEEP allocations do not sleep but may fail  (return
       NULL) if memory is currently not available.

       After the I/O has completed and the buffer structure is no longer needed, the driver calls freerbuf(9F) to free the buffer structure.

RETURN VALUES

       The ddi_umem_iosetup(9F) function returns a pointer to the initialized buffer header, or NULL if no space is available.

CONTEXT

       The  ddi_umem_iosetup(9F)  function  can  be  called  from  any	context only if flag is set to DDI_UMEM_NOSLEEP. If DDI_UMEM_SLEEP is set,
       ddi_umem_iosetup(9F) can be called from user and kernel context only.

SEE ALSO

       ddi_umem_lock(9F), ddi_dma_buf_bind_handle(9F), freerbuf(9F), physio(9F), buf(9S)

SunOS 5.10							    4 Feb 2003						      ddi_umem_iosetup(9F)

Check Out this Related Man Page

ddi_umem_lock(9F)					   Kernel Functions for Drivers 					 ddi_umem_lock(9F)

NAME

       ddi_umem_lock, ddi_umem_unlock - lock and unlock memory pages

SYNOPSIS

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

       int ddi_umem_lock(caddr_t addr, size_t len, int flags, ddi_umem_cookie_t *cookiep);

       void ddi_umem_unlock(ddi_umem_cookie_t cookie);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI)

PARAMETERS

   ddi_umem_lock
       addr

	   Virtual address of memory object

       len

	   Length of memory object in bytes

       flags

	   Valid flags include:

	   DDI_UMEMLOCK_READ

	       Memory pages are locked to be read from. (Disk write or a network send.)

	   DDI_UMEMLOCK_WRITE

	       Memory pages are locked to be written to. (Disk read or a network receive.)

       cookiep

	   Pointer to a kernel memory cookie.

   ddi_umem_unlock
       cookie

	   Kernel memory cookie allocated by ddi_umem_lock().

DESCRIPTION

       The  ddi_umem_lock(9F) function locks down the physical pages (including I/O pages) that correspond to the current process' virtual address
       range [addr, addr + size) and fills in a cookie representing the locked pages. This cookie can be used to create a buf(9S)  structure  that
       can  be	used  to  perform  I/O (see ddi_umem_iosetup(9F) and ddi_dma_buf_bind_handle(9F)), or it can be used with devmap_umem_setup(9F) to
       export the memory to an application.

       The virtual address and length specified must be at a page boundary and the mapping performed in terms of the system page size.	See  page-
       size(1).

       The  flags  argument  indicates the intended use of the locked memory. Set flags to DDI_UMEMLOCK_READ if the memory pages will be read (for
       example, in a disk write or a network send.) Set flags to DDI_UMEMLOCK_WRITE if the memory pages will be written (for example,  in  a  disk
       read or a network receive). You must choose one (and only one) of these values.

       To unlock the locked pages, the drivers call ddi_umem_unlock(9F) with the cookie obtained from ddi_umem_lock(9F).

       The process is not allowed to exec(2) or fork(2) while its physical pages are locked down by the device driver.

       The device driver must ensure that the physical pages have been unlocked after the application has called close(2).

RETURN VALUES

       On success, a 0 is returned. Otherwise, one of the following errno values is returned.

       EFAULT

	   User process has no mapping at that address range or does not support locking

       EACCES

	   User process does not have the required permission.

       ENOMEM

	   The system does not have sufficient resources to lock memory.

       EAGAIN

	   Could not allocate system resources required to lock the pages. The ddi_umem_lock() could succeed at a later time.

       EINVAL

	   Requested memory is not aligned on a system page boundary.

CONTEXT

       The ddi_umem_lock() function can only be called from user context; ddi_umem_unlock() from user, kernel, and interrupt contexts.

SEE ALSO

       ddi_umem_iosetup(9F), ddi_dma_buf_bind_handle(9F), devmap_umem_setup(9F), ddi_umem_alloc(9F)

NOTES

       The ddi_umem_lock(9F) function consumes physical memory. The driver is responsible for a speedy unlock to free up the resources.

       ddi_umem_unlock() can defer unlocking of the pages to a later time depending on the implementation.

SunOS 5.10							    4 Feb 2003							 ddi_umem_lock(9F)

Linux and UNIX Man Pages

ddi_umem_iosetup(9f) [osx man page]

Check Out this Related Man Page