devmap_setup(9f)

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

NAME

6       devmap_setup,  ddi_devmap_segmap - set up a user mapping to device mem‐
7       ory using the devmap framework
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13
14
15       int devmap_setup(dev_t dev, offset_t off, ddi_as_handle_t as,
16            caddr_t *addrp, size_tlen, uint_t prot, uint_t maxprot,
17            uint_t flags, cred_t *cred);
18
19
20       int ddi_devmap_segmap(dev_t dev, off_t off, ddi_as_handle_t as,
21            caddr_t *addrp, off_tlen, uint_t prot, uint_t maxprot,
22            uint_t flags, cred_t *cred);
23
24

INTERFACE LEVEL

26       Solaris DDI specific (Solaris DDI).
27

PARAMETERS

29       dev         Device whose memory is to be mapped.
30
31
32       off         User offset within the logical device memory at  which  the
33                   mapping begins.
34
35
36       as          An  opaque  data structure that describes the address space
37                   into which the device memory should be mapped.
38
39
40       addrp       Pointer to the starting address in the address  space  into
41                   which the device memory should be mapped.
42
43
44       len         Length (in bytes) of the memory to be mapped.
45
46
47       prot        A  bit  field that specifies the protections. Some possible
48                   settings combinations are:
49
50                   PROT_READ      Read access is desired.
51
52
53                   PROT_WRITE     Write access is desired.
54
55
56                   PROT_EXEC      Execute access is desired.
57
58
59                   PROT_USER      User-level access is desired (the mapping is
60                                  being  done  as a result of a mmap(2) system
61                                  call).
62
63
64                   PROT_ALL       All access is desired.
65
66
67
68       maxprot     Maximum protection flag possible for attempted mapping; the
69                   PROT_WRITE  bit  may  be  masked out if the user opened the
70                   special file read-only.
71
72
73       flags       Flags indicating type of mapping. The following  flags  can
74                   be specified:
75
76                   MAP_PRIVATE     Changes are private.
77
78
79                   MAP_SHARED      Changes should be shared.
80
81
82                   MAP_FIXED       The  user  specified  an address in  *addrp
83                                   rather than letting the  system  choose  an
84                                   address.
85
86
87
88       cred        Pointer to the user credential structure.
89
90

DESCRIPTION

92       devmap_setup()  and ddi_devmap_segmap() allow device drivers to use the
93       devmap framework to set up user mappings to device memory.  The  devmap
94       framework  provides  several advantages over the default device mapping
95       framework that  is  used  by  ddi_segmap(9F)  or  ddi_segmap_setup(9F).
96       Device drivers should use the devmap framework, if the driver wants to:
97
98           o      use  an  optimal  MMU  pagesize to minimize address transla‐
99                  tions,
100
101           o      conserve kernel resources,
102
103           o      receive callbacks to manage events on the mapping,
104
105           o      export kernel memory to applications,
106
107           o      set up device contexts for the user mapping  if  the  device
108                  requires context switching,
109
110           o      assign device access attributes to the user mapping, or
111
112           o      change the maximum protection for the mapping.
113
114
115       devmap_setup()  must  be called in the segmap(9E) entry point to estab‐
116       lish the mapping for the application. ddi_devmap_segmap() can be called
117       in,  or be used as, the segmap(9E) entry point. The differences between
118       devmap_setup() and ddi_devmap_segmap() are in the data  type  used  for
119       off and len.
120
121
122       When  setting  up  the mapping,  devmap_setup() and ddi_devmap_segmap()
123       call the devmap(9E) entry point to validate the range to be mapped. The
124       devmap(9E)  entry  point also translates the logical offset (as seen by
125       the application) to the corresponding physical offset within the device
126       address  space. If the driver does not provide its own devmap(9E) entry
127       point, EINVAL will be returned to the mmap(2) system call.
128

RETURN VALUES

130       0           Successful completion.
131
132
133       Non-zero    An error occurred.  The return value of devmap_setup()  and
134                   ddi_devmap_segmap()   should   be   used  directly  in  the
135                   segmap(9E) entry point.
136
137

CONTEXT

139       devmap_setup() and ddi_devmap_segmap() can be called from user or  ker‐
140       nel context only.
141