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

NAME

6       segmap - map device memory into user space
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/mman.h>
11       #include <sys/param.h>
12       #include <sys/vm.h>
13       #include <sys/ddi.h>
14       #include <sys/sunddi.h>
15
16
17
18       int prefixsegmap(dev_t dev, off_t off, struct as *asp, caddr_t *addrp,
19            off_t len, unsigned int prot, unsigned int maxprot, unsigned int flags,
20            cred_t *cred_p);
21
22

INTERFACE LEVEL

24       Architecture independent level 2 (DKI only).
25

ARGUMENTS

27       dev         Device whose memory is to be mapped.
28
29
30       off         Offset within device memory at which mapping begins.
31
32
33       asp         Pointer  to  the address space into which the device memory
34                   should be mapped.
35
36
37       addrp       Pointer to the address in the address space  to  which  the
38                   device memory should be mapped.
39
40
41       len         Length (in bytes) of the memory to be mapped.
42
43
44       prot        A  bit  field that specifies the protections. Possible set‐
45                   tings are:
46
47                   PROT_READ      Read access is desired.
48
49
50                   PROT_WRITE     Write access is desired.
51
52
53                   PROT_EXEC      Execute access is desired.
54
55
56                   PROT_USER      User-level access is desired (the mapping is
57                                  being  done as a result of a  mmap(2) system
58                                  call).
59
60
61                   PROT_ALL       All access is desired.
62
63
64
65       maxprot     Maximum protection flag possible for attempted mapping; the
66                   PROT_WRITE  bit  may  be  masked out if the user opened the
67                   special file read-only.
68
69
70       flags       Flags indicating  type  of  mapping.  Possible  values  are
71                   (other bits may be set):
72
73                   MAP_SHARED      Changes should be shared.
74
75
76                   MAP_PRIVATE     Changes are private.
77
78
79
80       cred_p      Pointer to the  user credentials structure.
81
82

DESCRIPTION

84       The   segmap() entry point is an optional routine for character drivers
85       that support memory mapping.  The  mmap(2) system call, when applied to
86       a  character  special file, allows device memory to be mapped into user
87       space for direct access by the user application.
88
89
90       Typically, a character driver that needs to support the  mmap(2) system
91       call  supplies either an devmap(9E) entry point, or both an  devmap(9E)
92       and a  segmap() entry  point  routine  (see  the  devmap(9E)  reference
93       page).  If  no  segmap()  entry  point  is  provided  for  the  driver,
94       devmap_setup(9F) is used as a default.
95
96
97       A driver for a memory-mapped device would  provide  a   segmap()  entry
98       point if it:
99
100           o      needs  to maintain a separate context for each user mapping.
101                  See  devmap_setup(9F) for details.
102
103           o      needs to assign device access attributes to  the  user  map‐
104                  ping.
105
106
107       The responsibilities of a  segmap() entry point are:
108
109           o      Verify  that  the  range, defined by  offset and  len, to be
110                  mapped is valid for  the device.  Typically,  this  task  is
111                  performed  by calling the  devmap(9E) entry point. Note that
112                  if you are using ddi_devmap_segmap(9F)  or  devmap_setup(9F)
113                  to  set  up  the mapping, it will call your devmap(9E) entry
114                  point for you to validate the range to be mapped.
115
116           o      Assign  device  access  attributes  to  the  mapping.    See
117                  ddi_devmap_segmap(9F),   and   ddi_device_acc_attr(9S)   for
118                  details.
119
120           o      Set up device contexts for the user mapping if  your  device
121                  requires    context  switching.   See  devmap_setup(9F)  for
122                  details.
123
124           o      Perform   the   mapping   with   ddi_devmap_segmap(9F),   or
125                  devmap_setup(9F) and return the status if it fails.
126

RETURN VALUES

128       The  segmap()  routine  should return  0 if the driver is successful in
129       performing the memory map of its device address space into  the  speci‐
130       fied address space.
131
132
133       The segmap() must return an error number on failure. For example, valid
134       error numbers would be   ENXIO  if  the  offset/length  pair  specified
135       exceeds  the  limits  of  the  device  memory, or  EINVAL if the driver
136       detects an invalid type of mapping attempted.
137
138
139       If one of  the  mapping  routines  ddi_devmap_segmap()  or  devmap_set‐
140       up()fails,  you must return the error number returned by the respective
141       routine.
142

SEE ALSO

144       mmap(2),    devmap(9E),    devmap_setup(9F),     ddi_devmap_segmap(9F),
145       ddi_device_acc_attr(9S)
146
147
148       Writing Device Drivers
149
150
151
152SunOS 5.11                        14 Jan 1997                       segmap(9E)
Impressum