| blob | afb43407d0a2701075b601acbf873b3e80b898f0 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH IOCTL 9E "Dec 3, 1996"
7 .SH NAME
8 ioctl \- control a character device
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/cred.h>
13 #include <sys/file.h>
14 #include <sys/types.h>
15 #include <sys/errno.h>
16 #include <sys/ddi.h>
17 #include <sys/sunddi.h>
21 \fBint prefix\fR\fBioctl\fR(\fBdev_t\fR \fIdev\fR, \fBint\fR \fIcmd\fR, \fBintptr_t\fR \fIarg\fR, \fBint\fR \fImode\fR,
22 \fBcred_t *\fR\fIcred_p\fR, \fBint *\fR\fIrval_p\fR);
23 .fi
25 .SH INTERFACE LEVEL
26 .sp
27 .LP
28 Architecture independent level 1 (DDI/DKI). This entry point is \fBoptional\fR.
29 .SH ARGUMENTS
30 .sp
31 .ne 2
32 .na
33 \fB\fIdev\fR\fR
34 .ad
35 .RS 10n
36 Device number.
37 .RE
39 .sp
40 .ne 2
41 .na
42 \fB\fIcmd\fR\fR
43 .ad
44 .RS 10n
45 Command argument the driver \fBioctl()\fR routine interprets as the operation
46 to be performed.
47 .RE
49 .sp
50 .ne 2
51 .na
52 \fB\fIarg\fR\fR
53 .ad
54 .RS 10n
55 Passes parameters between a user program and the driver. When used with
56 terminals, the argument is the address of a user program structure containing
57 driver or hardware settings. Alternatively, the argument may be a value that
58 has meaning only to the driver. The interpretation of the argument is driver
59 dependent and usually depends on the command type; the kernel does not
60 interpret the argument.
61 .RE
63 .sp
64 .ne 2
65 .na
66 \fB\fImode\fR\fR
67 .ad
68 .RS 10n
69 A bit field that contains:
70 .RS +4
71 .TP
72 .ie t \(bu
73 .el o
74 Information set when the device was opened. The driver may use it to determine
75 if the device was opened for reading or writing. The driver can make this
76 determination by checking the \fBFREAD\fR or \fBFWRITE\fR flags. See the
77 \fIflag\fR argument description of the \fBopen()\fR routine for further
78 values.
79 .RE
80 .RS +4
81 .TP
82 .ie t \(bu
83 .el o
84 Information on whether the caller is a 32-bit or 64-bit thread.
85 .RE
86 .RS +4
87 .TP
88 .ie t \(bu
89 .el o
90 In some circumstances address space information about the \fIarg\fR argument.
91 See below.
92 .RE
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fIcred_p\fR\fR
99 .ad
100 .RS 10n
101 Pointer to the user credential structure.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fIrval_p\fR\fR
108 .ad
109 .RS 10n
110 Pointer to return value for calling process. The driver may elect to set the
111 value which is valid only if the \fBioctl()\fR succeeds.
112 .RE
114 .SH DESCRIPTION
115 .sp
116 .LP
117 \fBioctl()\fR provides character-access drivers with an alternate entry point
118 that can be used for almost any operation other than a simple transfer of
119 characters in and out of buffers. Most often, \fBioctl()\fR is used to control
120 device hardware parameters and establish the protocol used by the driver in
121 processing data.
122 .sp
123 .LP
124 The kernel determines that this is a character device, and looks up the entry
125 point routines in \fBcb_ops\fR(9S). The kernel then packages the user request
126 and arguments as integers and passes them to the driver's \fBioctl()\fR
127 routine. The kernel itself does no processing of the passed command, so it is
128 up to the user program and the driver to agree on what the arguments mean.
129 .sp
130 .LP
131 I/O control commands are used to implement the terminal settings passed from
132 \fBttymon\fR(1M) and \fBstty\fR(1), to format disk devices, to implement a
133 trace driver for debugging, and to clean up character queues. Since the kernel
134 does not interpret the command type that defines the operation, a driver is
135 free to define its own commands.
136 .sp
137 .LP
138 Drivers that use an \fBioctl()\fR routine typically have a command to ``read''
139 the current \fBioctl()\fR settings, and at least one other that sets new
140 settings. Drivers can use the \fImode\fR argument to determine if the device
141 unit was opened for reading or writing, if necessary, by checking the
142 \fBFREAD\fR or \fBFWRITE\fR setting.
143 .sp
144 .LP
145 If the third argument, \fIarg\fR, is a pointer to a user buffer, the driver
146 can call the \fBcopyin\fR(9F) and \fBcopyout\fR(9F) functions to transfer data
147 between kernel and user space.
148 .sp
149 .LP
150 Other kernel subsystems may need to call into the drivers \fBioctl()\fR
151 routine. Drivers that intend to allow their \fBioctl()\fR routine to be used
152 in this way should publish the \fBddi-kernel-ioctl\fR property on the
153 associated devinfo node(s).
154 .sp
155 .LP
156 When the \fBddi-kernel-ioctl\fR property is present, the \fImode\fR argument is
157 used to pass address space information about \fIarg\fR through to the driver.
158 If the driver expects \fIarg\fR to contain a buffer address, and the
159 \fBFKIOCTL\fR flag is set in \fImode\fR, then the driver should assume that it
160 is being handed a kernel buffer address. Otherwise, \fIarg\fR may be the
161 address of a buffer from a user program. The driver can use
162 \fBddi_copyin\fR(9F) and \fBddi_copyout\fR(9F) perform the correct type of copy
163 operation for either kernel or user address spaces. See the example on
164 \fBddi_copyout\fR(9F).
165 .sp
166 .LP
167 Drivers have to interact with 32-bit and 64-bit applications. If a device
168 driver shares data structures with the application (for example, through
169 exported kernel memory) and the driver gets recompiled for a 64-bit kernel but
170 the application remains 32-bit, binary layout of any data structures will be
171 incompatible if they contain longs or pointers. The driver needs to know
172 whether there is a model mismatch between the current thread and the kernel and
173 take necessary action. The \fImode\fR argument has additional bits set to
174 determine the C Language Type Model which the current thread expects.
175 \fImode\fR has \fBFILP32\fR set if the current thread expects 32-bit (
176 \fIILP32\fR) semantics, or \fBFLP64\fR if the current thread expects 64-bit (
177 \fILP64\fR) semantics. \fImode\fR is used in combination with
178 \fBddi_model_convert_from\fR(9F) and the \fBFMODELS\fR mask to determine
179 whether there is a data model mismatch between the current thread and the
180 device driver (see the example below). The device driver might have to adjust
181 the shape of data structures before exporting them to a user thread which
182 supports a different data model.
183 .sp
184 .LP
185 To implement I/O control commands for a driver the following two steps are
186 required:
187 .RS +4
188 .TP
189 1.
190 Define the I/O control command names and the associated value in the
191 driver's header and comment the commands.
192 .RE
193 .RS +4
194 .TP
195 2.
196 Code the \fBioctl()\fR routine in the driver that defines the functionality
197 for each I/O control command name that is in the header.
198 .RE
199 .sp
200 .LP
201 The \fBioctl()\fR routine is coded with instructions on the proper action to
202 take for each command. It is commonly a \fBswitch\fR statement, with each
203 \fBcase\fR definition corresponding to an \fBioctl()\fR name to identify the
204 action that should be taken. However, the command passed to the driver by the
205 user process is an integer value associated with the command name in the
206 header.
207 .SH RETURN VALUES
208 .sp
209 .LP
210 \fBioctl()\fR should return \fB0\fR on success, or the appropriate error
211 number. The driver may also set the value returned to the calling process
212 through \fIrval_p\fR.
213 .SH EXAMPLES
214 .LP
215 \fBExample 1 \fR\fBioctl()\fR entry point
216 .sp
217 .LP
218 The following is an example of the \fBioctl()\fR entry point and how to support
219 32-bit and 64-bit applications with the same device driver.
221 .sp
222 .in +2
223 .nf
224 struct passargs32 {
225 int len;
226 caddr32_t addr;
227 };
229 struct passargs {
230 int len;
231 caddr_t addr;
232 };
234 xxioctl(dev_t dev, int cmd, intptr_t arg, int mode,
235 cred_t *credp, int *rvalp) {
236 struct passargs pa;
238 #ifdef _MULTI_DATAMODEL
239 switch (ddi_model_convert_from(mode & FMODELS)) {
240 case DDI_MODEL_ILP32:
241 {
242 struct passargs32 pa32;
244 ddi_copyin(arg, &pa32, sizeof (struct passargs32),\e
245 mode);
246 pa.len = pa32.len;
247 pa.address = pa32.address;
248 break;
249 }
250 case DDI_MODEL_NONE:
251 ddi_copyin(arg, &pa, sizeof (struct passargs),\e
252 mode);
253 break;
254 }
255 #else /* _MULTI_DATAMODEL */
256 ddi_copyin(arg, &pa, sizeof (struct passargs), mode);
257 #endif /* _MULTI_DATAMODEL */
259 do_ioctl(&pa);
260 .\|.\|.\|.
261 }
262 .fi
263 .in -2
265 .SH SEE ALSO
266 .sp
267 .LP
268 \fBstty\fR(1), \fBttymon\fR(1M), \fBdkio\fR(7I), \fBfbio\fR(7I),
269 \fBtermio\fR(7I), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E),
270 \fBcopyin\fR(9F), \fBcopyout\fR(9F), \fBddi_copyin\fR(9F),
271 \fBddi_copyout\fR(9F), \fBddi_model_convert_from\fR(9F), \fBcb_ops\fR(9S)
272 .sp
273 .LP
274 \fIWriting Device Drivers\fR
275 .SH WARNINGS
276 .sp
277 .LP
278 Non-STREAMS driver \fBioctl()\fR routines must make sure that user data is
279 copied into or out of the kernel address space explicitly using
280 \fBcopyin\fR(9F), \fBcopyout\fR(9F), \fBddi_copyin\fR(9F), or
281 \fBddi_copyout\fR(9F), as appropriate.
282 .sp
283 .LP
284 It is a severe error to simply dereference pointers to the user address space,
285 even when in user context.
286 .sp
287 .LP
288 Failure to use the appropriate copying routines can result in panics under load
289 on some platforms, and reproducible panics on others.
290 .SH NOTES
291 .sp
292 .LP
293 STREAMS drivers do not have \fBioctl()\fR routines. The stream head converts
294 I/O control commands to \fBM_IOCTL\fR messages, which are handled by the
295 driver's \fBput\fR(9E) or \fBsrv\fR(9E) routine.