devmap_map(9e)

1devmap_map(9E)                Driver Entry Points               devmap_map(9E)
2
3
4

NAME

6       devmap_map - device mapping create entry point
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int prefixdevmap_map(devmap_cookie_t dhp, dev_t dev,
15            uint_t flags, offset_t off, size_t len, void **pvtp);
16
17

INTERFACE LEVEL

19       Solaris DDI specific (Solaris DDI).
20

ARGUMENTS

22       dhp       An opaque mapping handle that the system uses to describe the
23                 mapping currently being created.
24
25
26       dev       The device whose memory is to be mapped.
27
28
29       flags     Flags indicating type of mapping. Possible values are:
30
31                 MAP_PRIVATE     Changes are private.
32
33
34                 MAP_SHARED      Changes should be shared.
35
36
37
38       off       User offset within the logical device  memory  at  which  the
39                 mapping begins.
40
41
42       len       Length (in bytes) of the memory to be mapped.
43
44
45       pvtp      A  pointer  to be filled in by device drivers with the driver
46                 private mapping data.
47
48

DESCRIPTION

50       The devmap_map() entry point is an optional routine that allows drivers
51       to  perform additional processing or to allocate private resources dur‐
52       ing the mapping setup time.  For example, in order for  device  drivers
53       to support context switching, the drivers allocate private mapping data
54       and associate the private data  with  the  mapping  parameters  in  the
55       devmap_map() entry point.
56
57
58       The system calls devmap_map() after the user mapping to device physical
59       memory has been established. (For example, after the  devmap(9E)  entry
60       point is called.)
61
62
63       devmap_map()  receives  a  pointer to the driver private data  for this
64       mapping in pvtp. The system expects the driver to allocate its  private
65       data  and  set  *pvtp to the allocated data.  The driver must store off
66       and len, which define the range of the mapping, in  its  private  data.
67       Later,  when the system calls devmap_unmap(9E), the driver will use the
68       off and  len stored in pvtp to check if the entire mapping, or  just  a
69       part  of  it, is being unmapped. If only a part of the mapping is being
70       unmapped, the driver must allocate  a new private data for the  remain‐
71       ing  mapping  before  freeing  the  old  private data.  The driver will
72       receive *pvtp in subsequent event notification callbacks.
73
74
75       If the driver support context switching,  it should store  the  mapping
76       handle    dhp   in   its   private   data   *pvtp   for  later  use  in
77       devmap_unload(9F).
78
79
80       For a driver that supports context switching, flags  indicates  whether
81       or  not  the driver should allocate a private context  for the mapping.
82       For example, a driver may allocate a memory region to store the  device
83       context if flags is set to  MAP_PRIVATE.
84

RETURN VALUES

86       devmap_map() returns the following values:
87
88       0           Successful completion.
89
90
91       Non-zero    An error occurred.
92
93

EXAMPLES

95       Example 1  devmap_map()implementation
96
97
98       The following shows an example implementation for devmap_map().
99
100
101         static int
102         xxdevmap_map(devmap_cookie_t dhp, dev_t dev, uint_t flags, \
103              offset_t off,size_t len, void **pvtp)
104         {
105              struct xx_resources  *pvt;
106              struct xx_context *this_context;
107              struct xx_softc *softc;
108              softc = ddi_get_soft_state(statep, getminor(dev));
109
110              this_context = get_context(softc, off, len);
111
112              /* allocate resources for the mapping  - Device dependent */
113              pvt = kmem_zalloc(sizeof (struct xx_resources), KM_SLEEP);
114
115              pvt->off = off;
116              pvt->len = len;
117              pvt->dhp = dhp;
118              pvt->ctx = this_context;
119              *pvtp = pvt;
120         }
121
122