ddi_umem_lock(9f)

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

NAME

6       ddi_umem_lock, ddi_umem_unlock - lock and unlock memory pages
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12       int ddi_umem_lock(caddr_t addr, size_t len, int flags,
13            ddi_umem_cookie_t *cookiep);
14
15
16       void ddi_umem_unlock(ddi_umem_cookie_t cookie);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI)
21

PARAMETERS

23   ddi_umem_lock
24       addr       Virtual address of memory object
25
26
27       len        Length of memory object in bytes
28
29
30       flags      Valid flags include:
31
32                  DDI_UMEMLOCK_READ    Memory  pages  are  locked  to  be read
33                                       from. (Disk write or a network send.)
34
35
36                  DDI_UMEMLOCK_WRITE    Memory pages are locked to be  written
37                                        to. (Disk read or a network receive.)
38
39
40
41       cookiep    Pointer to a kernel memory cookie.
42
43
44   ddi_umem_unlock
45       cookie    Kernel memory cookie allocated by ddi_umem_lock().
46
47

DESCRIPTION

49       The  ddi_umem_lock()  function locks down the physical pages (including
50       I/O pages) that correspond to  the  current  process'  virtual  address
51       range [addr, addr + size) and fills in a cookie representing the locked
52       pages. This cookie can be used to create a buf(9S) structure  that  can
53       be    used    to    perform    I/O    (see   ddi_umem_iosetup(9F)   and
54       ddi_dma_buf_bind_handle(9F), or it can be  used  with  devmap_umem_set‐
55       up(9F) to export the memory to an application.
56
57
58       The virtual address and length specified must be at a page boundary and
59       the mapping performed in terms of  the  system  page  size.  See  page‐
60       size(1).
61
62
63       The flags argument indicates the intended use of the locked memory. Set
64       flags to DDI_UMEMLOCK_READ if the memory pages will be read (for  exam‐
65       ple,  in  a  disk  write  or  a  network  send.) Set flags to DDI_UMEM‐
66       LOCK_WRITE if the memory pages will be written (for example, in a  disk
67       read or a network receive). You must choose one (and only one) of these
68       values.
69
70
71       To unlock the locked pages, the drivers call  ddi_umem_unlock(9F)  with
72       the cookie obtained from ddi_umem_lock().
73
74
75       The  process  is  not  allowed to exec(2) or fork(2) while its physical
76       pages are locked down by the device driver.
77
78
79       The device driver  must  ensure  that  the  physical  pages  have  been
80       unlocked after the application has called close(2).
81

RETURN VALUES

83       On success, a 0 is returned. Otherwise, one of the following errno val‐
84       ues is returned.
85
86       EFAULT    User process has no mapping at that address range or does not
87                 support locking
88
89
90       EACCES    User process does not have the required permission.
91
92
93       ENOMEM    The system does not have sufficient resources to lock memory,
94                 or locking len memory would exceed a limit or  resource  con‐
95                 trol on locked memory.
96
97
98       EAGAIN    Could  not  allocate  system  resources  required to lock the
99                 pages. The ddi_umem_lock() could succeed at a later time.
100
101
102       EINVAL    Requested memory is not aligned on a system page boundary.
103
104

CONTEXT

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

NOTES

114       The ddi_umem_unlock() function consumes physical memory. The driver  is
115       responsible for a speedy unlock to free up the resources.
116
117
118       The  ddi_umem_unlock()  function  can defer unlocking of the pages to a
119       later time depending on the implementation.
120
121
122
123SunOS 5.11                        10 Apr 2007                ddi_umem_lock(9F)