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

NAME

6       id32_alloc,  id32_free,  id32_lookup - 32-bit driver ID management rou‐
7       tines
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/id32.h>
12
13
14
15       uint32_t id32_alloc(void *ptr, int flag);
16
17
18       void id32_free(uint32_t token);
19
20
21       void *id32_lookup(uint32_t token);
22
23

INTERFACE LEVEL

25       Solaris architecture specific (Solaris DDI).
26

PARAMETERS

28       ptr      any valid 32- or 64-bit pointer
29
30
31       flag     determines  whether  caller  can   sleep   for   memory   (see
32                kmem_alloc(9F) for a description)
33
34

DESCRIPTION

36       These  routines  were originally developed so that device drivers could
37       manage 64-bit pointers on devices  that  save  space  only  for  32-bit
38       pointers.
39
40
41       Many  device  drivers  need to pass a 32-bit value to the hardware when
42       attempting I/O.  Later, when that  I/O  completes,  the  only  way  the
43       driver  has  to  identify  the request that generated that I/O is via a
44       "token". When the I/O is initiated, the driver passes this token to the
45       hardware.  When  the I/O completes the hardware passes back this 32-bit
46       token.
47
48
49       Before Solaris supported 64-bit pointers, device drivers just passed  a
50       raw  32-bit  pointer  to the hardware. When pointers grew to be 64 bits
51       this was no longer possible. The id32_*() routines were created to help
52       drivers translate between 64-bit pointers and a 32-bit token.
53
54
55       Given  a  32-  or  64-bit pointer, the routine id32_alloc() allocates a
56       32-bit token, returning 0 if KM_NOSLEEP was specified and memory  could
57       not  be  allocated. The allocated token is passed back to id32_lookup()
58       to obtain the original 32- or 64-bit pointer.
59
60
61       The routine id32_free() is  used  to  free  an  allocated  token.  Once
62       id32_free() is called, the supplied token is no longer valid.
63
64
65       Note  that  these  routines have some degree of error checking. This is
66       done so that an invalid token  passed  to  id32_lookup()  will  not  be
67       accepted  as  valid.  When  id32_lookup()  detects  an invalid token it
68       returns NULL. Calling routines should check for this  return  value  so
69       that they do not try to dereference a NULL pointer.
70

CONTEXT

72       These  functions can be called from user or interrupt context. The rou‐
73       tine id32_alloc() should not be called from interrupt context when  the
74       KM_SLEEP  flag  is  passed  in.  All  other routines can be called from
75       interrupt or kernel context.
76

SEE ALSO

78       kmem_alloc(9F)
79
80
81       Writing Device Drivers
82
83
84
85SunOS 5.11                        12 Dec 2001                   id32_alloc(9F)
Impressum