ddi_umem_iosetup(9f)

1ddi_umem_iosetup(9F)     Kernel Functions for Drivers     ddi_umem_iosetup(9F)
2
3
4

NAME

6       ddi_umem_iosetup - Setup I/O requests to application memory
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       struct buf *ddi_umem_iosetup(ddi_umem_cookie_t cookie,off_t off,
15            size_t len, int direction, dev_t dev, daddr_t blkno,
16            int (*iodone) (struct buf *), int sleepflag);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI)
21

PARAMETERS

23       cookie        The kernel memory cookie allocated by ddi_umem_lock(9F).
24
25
26       off           Offset from the start of the cookie.
27
28
29       len           Length of the I/O request in bytes.
30
31
32       direction     Must  be  set  to  B_READ  for  reads  from the device or
33                     B_WRITE for writes to the device.
34
35
36       dev           Device number
37
38
39       blkno         Block number on device.
40
41
42       iodone        Specific biodone(9F) routine.
43
44
45       sleepflag     Determines whether caller can sleep for memory.  Possible
46                     flags  are  DDI_UMEM_SLEEP to allow sleeping until memory
47                     is available, or DDI_UMEM_NOSLEEP to return NULL  immedi‐
48                     ately if memory is not available.
49
50

DESCRIPTION

52       The  ddi_umem_iosetup(9F)  function  is  used  by  drivers to setup I/O
53       requests to  application  memory  which  has  been  locked  down  using
54       ddi_umem_lock(9F).
55
56
57       The ddi_umem_iosetup(9F) function returns a pointer to a buf(9S) struc‐
58       ture corresponding to the memory cookie cookie. Drivers can setup  mul‐
59       tiple  buffer  structures  simultaneously  active using the same memory
60       cookie. The buf(9S) structures can span all or part of the region  rep‐
61       resented  by  the cookie and can overlap each other. The buf(9S) struc‐
62       ture can be  passed  to  ddi_dma_buf_bind_handle(9F)  to  initiate  DMA
63       transfers to or from the locked down memory.
64
65
66       The  off   parameter specifies the offset from the start of the cookie.
67       The len parameter represents the length of region to be mapped  by  the
68       buffer.  The  direction  parameter  must  be  set  to  either B_READ or
69       B_WRITE, to indicate the action that will be performed by  the  device.
70       (Note  that  this direction is in the opposite sense of the VM system's
71       direction of DDI_UMEMLOCK_READ and DDI_UMEMLOCK_WRITE.)  The  direction
72       must  be  compatible with the flags used to create the memory cookie in
73       ddi_umem_lock(9F). For example, if ddi_umem_lock() is called  with  the
74       flags  parameter  set  to DDI_UMEMLOCK_READ, the direction parameter in
75       ddi_umem_iosetup() should be set to B_WRITE.
76
77
78       The dev parameter specifies the device to which the buffer is  to  per‐
79       form I/O.The blkno parameter represents the block number on the device.
80       It will be assigned to the b_blkno field of the returned buffer  struc‐
81       ture.  The  iodone  parameter enables the driver to identify a specific
82       biodone(9F) routine to be called by the driver when  the  I/O  is  com‐
83       plete.  The sleepflag  parameter determines if the caller can sleep for
84       memory. DDI_UMEM_SLEEP allocations may sleep but are guaranteed to suc‐
85       ceed.  DDI_UMEM_NOSLEEP  allocations  do not sleep but may fail (return
86       NULL) if memory is currently not available.
87
88
89       After the I/O has completed and  the  buffer  structure  is  no  longer
90       needed, the driver calls freerbuf(9F) to free the buffer structure.
91

RETURN VALUES

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

CONTEXT

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