ddi_umem_alloc(9f)

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

NAME

6       ddi_umem_alloc,  ddi_umem_free  - allocate and free page-aligned kernel
7       memory
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <sys/sunddi.h>
12
13       void *ddi_umem_alloc(size_t size, int flag,
14            ddi_umem_cookie_t *cookiep);
15
16
17       void ddi_umem_free(ddi_umem_cookie_t cookie);
18
19

INTERFACE LEVEL

21       Solaris DDI specific (Solaris DDI).
22

PARAMETERS

24   ddi_umem_alloc()
25       size       Number of bytes to allocate.
26
27
28       flag       Used to determine the sleep and pageable conditions.
29
30                  Possible sleep flags are DDI_UMEM_SLEEP, which allows sleep‐
31                  ing  until  memory is available, and DDI_UMEM_NOSLEEP, which
32                  returns NULL immediately if memory is not available.
33
34                  The default condition is to allocate locked memory; this can
35                  be   changed   to   allocate   pageable   memory  using  the
36                  DDI_UMEM_PAGEABLE flag.
37
38
39       cookiep    Pointer to a kernel memory cookie.
40
41
42   ddi_umem_free()
43       cookie    A kernel memory cookie allocated in ddi_umem_alloc().
44
45

DESCRIPTION

47       ddi_umem_alloc() allocates page-aligned kernel  memory  and  returns  a
48       pointer  to  the  allocated  memory. The number of bytes allocated is a
49       multiple of the system page size (roundup of size). The allocated  mem‐
50       ory  can  be  used in the kernel and can be exported to user space. See
51       devmap(9E) and devmap_umem_setup(9F) for further information.
52
53
54       flag determines whether the caller can sleep for memory and whether the
55       allocated memory is locked or not. DDI_UMEM_SLEEP allocations may sleep
56       but are guaranteed to  succeed.  DDI_UMEM_NOSLEEP  allocations  do  not
57       sleep but may fail (return NULL) if memory is currently unavailable. If
58       DDI_UMEM_PAGEABLE is set, pageable  memory  will  be  allocated.  These
59       pages  can be swapped out to secondary memory devices. The initial con‐
60       tents of memory allocated using ddi_umem_alloc() is zero-filled.
61
62
63       *cookiep is a pointer to the kernel memory cookie  that  describes  the
64       kernel  memory  being  allocated.  A  typical  use  of  cookiep  is  in
65       devmap_umem_setup(9F) when the drivers want to export the kernel memory
66       to a user application.
67
68
69       To  free  the allocated memory, a driver calls ddi_umem_free() with the
70       cookie obtained from  ddi_umem_alloc().  ddi_umem_free()  releases  the
71       entire buffer.
72

RETURN VALUES

74       Non-null    Successful  completion.  ddi_umem_alloc() returns a pointer
75                   to the allocated memory.
76
77
78       NULL        Memory cannot  be  allocated  by  ddi_umem_alloc()  because
79                   DDI_UMEM_NOSLEEP is set and the system is out of resources.
80
81

CONTEXT

83       ddi_umem_alloc()  can  be  called  from  any  context if flag is set to
84       DDI_UMEM_NOSLEEP. If DDI_UMEM_SLEEP is  set,  ddi_umem_alloc()  can  be
85       called from user and kernel context only. ddi_umem_free() can be called
86       from any context.
87

WARNINGS

96       Setting  the  DDI_UMEM_PAGEABLE flag in ddi_umem_alloc() will result in
97       an allocation of pageable memory. Because these pages  can  be  swapped
98       out  to  secondary  memory  devices,  drivers should use this flag with
99       care. This memory must not be used for the following purposes:
100
101           o      For synchronization objects  such  as  locks  and  condition
102                  variables.  See  mutex(9F),  semaphore(9F),  rwlock(9F), and
103                  condvar(9F).
104
105           o      For driver interrupt routines.
106
107
108       Memory allocated using ddi_umem_alloc() without setting  DDI_UMEM_PAGE‐
109       ABLE flag cannot be paged. Available memory is therefore limited by the
110       total physical memory on the system. It is also limited by  the  avail‐
111       able  kernel virtual address space, which is often the more restrictive
112       constraint on large-memory configurations.
113
114
115       Excessive use of kernel memory is likely to effect overall system  per‐
116       formance. Over-commitment of kernel memory may cause unpredictable con‐
117       sequences.
118
119
120       Misuse of the kernel memory allocator, such as writing past the end  of
121       a  buffer,  using a buffer after freeing it, freeing a buffer twice, or
122       freeing an invalid pointer, will cause the system to  corrupt  data  or
123       panic.
124
125
126       Do  not  call ddi_umem_alloc() within DDI_SUSPEND and DDI_RESUME opera‐
127       tions. Memory acquired at these times is not reliable. In  some  cases,
128       such a call can cause a system to hang.
129

NOTES

131       ddi_umem_alloc(0,     flag,     cookiep)     always    returns    NULL.
132       ddi_umem_free(NULL) has no effects on system.
133
134
135
136SunOS 5.11                        19 Mar 2002               ddi_umem_alloc(9F)