1 ==============================
2 Summary of `HDIO_` ioctl calls
3 ==============================
4
5 - Edward A. Falk <efalk@google.com>
6
7 November, 2004
8
9 This document attempts to describe the ioctl(2
10 the HD/IDE layer. These are by-and-large impl
11 drivers/ata/libata-scsi.c.
12
13 ioctl values are listed in <linux/hdreg.h>. A
14 are as follows:
15
16 ioctls that pass argument pointers to user
17
18 ======================= ==============
19 HDIO_GETGEO get device geo
20 HDIO_GET_32BIT get current io
21 HDIO_GET_IDENTITY get IDE identi
22 HDIO_DRIVE_TASKFILE execute raw ta
23 HDIO_DRIVE_TASK execute task a
24 HDIO_DRIVE_CMD execute a spec
25 ======================= ==============
26
27 ioctls that pass non-pointer values:
28
29 ======================= ==============
30 HDIO_SET_32BIT change io_32bi
31 ======================= ==============
32
33
34 The information that follows was determined fr
35 code. It is likely that some corrections will
36
37 ----------------------------------------------
38
39 General:
40
41 Unless otherwise specified, all ioctl
42 and -1 with errno set to an appropriat
43
44 Unless otherwise specified, all ioctl
45 errno to EFAULT on a failed attempt to
46 address space.
47
48 Unless otherwise specified, all data s
49 are defined in <linux/hdreg.h>
50
51 ----------------------------------------------
52
53 HDIO_GETGEO
54 get device geometry
55
56
57 usage::
58
59 struct hd_geometry geom;
60
61 ioctl(fd, HDIO_GETGEO, &geom);
62
63
64 inputs:
65 none
66
67
68
69 outputs:
70 hd_geometry structure containi
71
72
73 ========= ======================
74 heads number of heads
75 sectors number of sectors/trac
76 cylinders number of cylinders, m
77 start starting sector of thi
78 ========= ======================
79
80
81 error returns:
82 - EINVAL
83
84 if the device is not a
85 or if the user passes
86
87
88 notes:
89 Not particularly useful with m
90 is a polite fiction anyway. M
91 purely by sector number nowada
92 drive geometry is an abstracti
93 to change. Currently (as of N
94 are the "bios" values -- presu
95 when Linux first booted.
96
97 In addition, the cylinders fie
98 unsigned short, meaning that o
99 ioctl will not return a meanin
100 than 65535 tracks.
101
102 The start field is unsigned lo
103 contain a meaningful value for
104
105
106
107 HDIO_GET_IDENTITY
108 get IDE identification info
109
110
111 usage::
112
113 unsigned char identity[512];
114
115 ioctl(fd, HDIO_GET_IDENTITY, identit
116
117 inputs:
118 none
119
120
121
122 outputs:
123 ATA drive identity information
124 the IDENTIFY DEVICE and IDENTI
125 the ATA specification.
126
127 error returns:
128 - EINVAL Called on a partition
129 - ENOMSG IDENTIFY DEVICE inform
130
131 notes:
132 Returns information that was o
133 probed. Some of this informat
134 this ioctl does not re-probe t
135 information.
136
137 This information is also avail
138
139
140
141 HDIO_GET_32BIT
142 get current io_32bit setting
143
144
145 usage::
146
147 long val;
148
149 ioctl(fd, HDIO_GET_32BIT, &val);
150
151 inputs:
152 none
153
154
155
156 outputs:
157 The value of the current io_32
158
159
160
161 notes:
162 0=16-bit, 1=32-bit, 2,3 = 32bi
163
164
165
166 HDIO_DRIVE_TASKFILE
167 execute raw taskfile
168
169
170 Note:
171 If you don't have a copy of th
172 handy, you should probably ign
173
174 - Execute an ATA disk command directly
175 registers of the drive. Requires AD
176 privileges.
177
178 usage::
179
180 struct {
181
182 ide_task_request_t req_task;
183 u8 outbuf[OUTPUT_SIZE];
184 u8 inbuf[INPUT_SIZE];
185 } task;
186 memset(&task.req_task, 0, sizeof(tas
187 task.req_task.out_size = sizeof(task
188 task.req_task.in_size = sizeof(task.
189 ...
190 ioctl(fd, HDIO_DRIVE_TASKFILE, &task
191 ...
192
193 inputs:
194
195 (See below for details on memory are
196
197 ============ ======================
198 io_ports[8] values to be written t
199 hob_ports[8] high-order bytes, for
200 out_flags flags indicating which
201 in_flags flags indicating which
202 data_phase see below
203 req_cmd command type to be exe
204 out_size size of output buffer
205 outbuf buffer of data to be t
206 inbuf buffer of data to be r
207 ============ ======================
208
209 outputs:
210
211 =========== ======================
212 io_ports[] values returned in the
213 hob_ports[] high-order bytes, for
214 out_flags flags indicating which
215 in_flags flags indicating which
216 outbuf buffer of data to be t
217 inbuf buffer of data to be r
218 =========== ======================
219
220 error returns:
221 - EACCES CAP_SYS_ADMIN or CAP_S
222 - ENOMSG Device is not a disk d
223 - ENOMEM Unable to allocate mem
224 - EFAULT req_cmd == TASKFILE_IN
225 - EPERM
226
227 req_cmd == TASKFILE_MU
228 multi-count not yet se
229 - EIO Drive failed the comma
230
231 notes:
232
233 [1] READ THE FOLLOWING NOTES *CAREFU
234 FULL OF GOTCHAS. Extreme caution sh
235 this ioctl. A mistake can easily co
236 system.
237
238 [2] Both the input and output buffer
239 user and written back to the user, e
240
241 [3] If one or more bits are set in o
242 zero, the following values are used
243 written back into in_flags on comple
244
245 * IDE_TASKFILE_STD_IN_FLAGS | (IDE_
246 if LBA48 addressing is enabled fo
247 * IDE_TASKFILE_STD_IN_FLAGS
248 if CHS/LBA28
249
250 The association between in_flags.all
251 bitfield flips depending on endianne
252 only uses inflags.b.data bit and ign
253 The end result is that, on any endia
254 effect other than modifying in_flags
255
256 [4] The default value of SELECT is (
257 except for four drives per port chip
258 per port chipsets, it's (0xa0|DEV_bi
259 pair and (0x80|DEV_bit|LBA_bit) for
260
261 [5] The argument to the ioctl is a p
262 memory containing a ide_task_request
263 by an optional buffer of data to be
264 drive, followed by an optional buffe
265 the drive.
266
267 Command is passed to the disk drive
268 structure, which contains these fiel
269
270 ============ ==============
271 io_ports[8] values for the
272 hob_ports[8] high-order byt
273 out_flags flags indicati
274 io_ports[] and
275 contain valid
276 in_flags flags indicati
277 io_ports[] and
278 are expected t
279 on return.
280 data_phase See below
281 req_cmd Command type,
282 out_size output (user->
283 in_size input (drive->
284 ============ ==============
285
286 When out_flags is zero, the followin
287
288 ============ ==============
289 HOB_FEATURE If the drive s
290 HOB_NSECTOR If the drive s
291 HOB_SECTOR If the drive s
292 HOB_LCYL If the drive s
293 HOB_HCYL If the drive s
294 FEATURE
295 NSECTOR
296 SECTOR
297 LCYL
298 HCYL
299 SELECT First, masked
300 otherwise; the
301 value of SELEC
302 ============ ==============
303
304 If any bit in out_flags is set, the
305
306 ============ ==============
307 HOB_DATA If out_flags.b
308 travel on DD8-
309 and on DD0-DD7
310 DATA If out_flags.b
311 travel on DD0-
312 and on DD8-DD1
313 HOB_NSECTOR If out_flags.b
314 HOB_SECTOR If out_flags.b
315 HOB_LCYL If out_flags.b
316 HOB_HCYL If out_flags.b
317 FEATURE If out_flags.b
318 NSECTOR If out_flags.b
319 SECTOR If out_flags.b
320 LCYL If out_flags.b
321 HCYL If out_flags.b
322 SELECT Or'ed with the
323 loaded regardl
324 ============ ==============
325
326 Taskfile registers are read back fro
327 {io|hob}_ports[] after the command c
328 following conditions is met; otherwi
329 will be written back, unchanged.
330
331 1. The drive fails the command (EI
332 2. One or more than one bits are s
333 3. The requested data_phase is TAS
334
335 ============ ==============
336 HOB_DATA If in_flags.b.
337 DD8-DD15 on li
338 DD0-DD7 on big
339 DATA If in_flags.b.
340 DD0-DD7 on lit
341 DD8-DD15 on bi
342 HOB_FEATURE If the drive s
343 HOB_NSECTOR If the drive s
344 HOB_SECTOR If the drive s
345 HOB_LCYL If the drive s
346 HOB_HCYL If the drive s
347 NSECTOR
348 SECTOR
349 LCYL
350 HCYL
351 ============ ==============
352
353 The data_phase field describes the d
354 performed. Value is one of:
355
356 =================== =======
357 TASKFILE_IN
358 TASKFILE_MULTI_IN
359 TASKFILE_OUT
360 TASKFILE_MULTI_OUT
361 TASKFILE_IN_OUT
362 TASKFILE_IN_DMA
363 TASKFILE_IN_DMAQ == IN_
364 TASKFILE_OUT_DMA
365 TASKFILE_OUT_DMAQ == OUT
366 TASKFILE_P_IN unimpl
367 TASKFILE_P_IN_DMA unimpl
368 TASKFILE_P_IN_DMAQ unimpl
369 TASKFILE_P_OUT unimpl
370 TASKFILE_P_OUT_DMA unimpl
371 TASKFILE_P_OUT_DMAQ unimpl
372 =================== =======
373
374 The req_cmd field classifies the com
375 one of:
376
377 ======================== ======
378 IDE_DRIVE_TASK_NO_DATA
379 IDE_DRIVE_TASK_SET_XFER unimpl
380 IDE_DRIVE_TASK_IN
381 IDE_DRIVE_TASK_OUT unimpl
382 IDE_DRIVE_TASK_RAW_WRITE
383 ======================== ======
384
385 [6] Do not access {in|out}_flags->al
386 all the bits. Always access individ
387 value will flip depending on endiann
388 reason, do not use IDE_{TASKFILE|HOB
389 constants defined in hdreg.h.
390
391
392
393 HDIO_DRIVE_CMD
394 execute a special drive command
395
396
397 Note: If you don't have a copy of the
398 handy, you should probably ignore this
399
400 usage::
401
402 u8 args[4+XFER_SIZE];
403
404 ...
405 ioctl(fd, HDIO_DRIVE_CMD, args);
406
407 inputs:
408 Commands other than WIN_SMART:
409
410 ======= =======
411 args[0] COMMAND
412 args[1] NSECTOR
413 args[2] FEATURE
414 args[3] NSECTOR
415 ======= =======
416
417 WIN_SMART:
418
419 ======= =======
420 args[0] COMMAND
421 args[1] SECTOR
422 args[2] FEATURE
423 args[3] NSECTOR
424 ======= =======
425
426 outputs:
427 args[] buffer is filled with r
428
429
430 data returned by the disk.
431
432 ======== ======================
433 args[0] status
434 args[1] error
435 args[2] NSECTOR
436 args[3] undefined
437 args[4+] NSECTOR * 512 bytes of
438 ======== ======================
439
440 error returns:
441 - EACCES Access denied: requir
442 - ENOMEM Unable to allocate mem
443 - EIO Drive reports error
444
445 notes:
446
447 [1] For commands other than WIN_SMAR
448 args[3]. SECTOR, LCYL and HCYL are
449 WIN_SMART, 0x4f and 0xc2 are loaded
450 respectively. In both cases SELECT
451 value for the drive. Please refer t
452 notes for the default value of SELEC
453
454 [2] If NSECTOR value is greater than
455 DRQ when interrupting for the comman
456 are read from the device into the ar
457 In the above example, the area would
458 args[4..4+XFER_SIZE]. 16bit PIO is
459 HDIO_SET_32BIT setting.
460
461 [3] If COMMAND == WIN_SETFEATURES &&
462 && NSECTOR >= XFER_SW_DMA_0 && the d
463 mode, IDE driver will try to tune th
464 drive accordingly.
465
466
467
468 HDIO_DRIVE_TASK
469 execute task and special drive command
470
471
472 Note: If you don't have a copy of the
473 handy, you should probably ignore this
474
475 usage::
476
477 u8 args[7];
478
479 ...
480 ioctl(fd, HDIO_DRIVE_TASK, args);
481
482 inputs:
483 Taskfile register values:
484
485 ======= =======
486 args[0] COMMAND
487 args[1] FEATURE
488 args[2] NSECTOR
489 args[3] SECTOR
490 args[4] LCYL
491 args[5] HCYL
492 args[6] SELECT
493 ======= =======
494
495 outputs:
496 Taskfile register values:
497
498
499 ======= =======
500 args[0] status
501 args[1] error
502 args[2] NSECTOR
503 args[3] SECTOR
504 args[4] LCYL
505 args[5] HCYL
506 args[6] SELECT
507 ======= =======
508
509 error returns:
510 - EACCES Access denied: requir
511 - ENOMEM Unable to allocate mem
512 - ENOMSG Device is not a disk d
513 - EIO Drive failed the comma
514
515 notes:
516
517 [1] DEV bit (0x10) of SELECT registe
518 appropriate value for the drive is u
519 are used unaltered.
520
521
522
523 HDIO_SET_32BIT
524 change io_32bit flags
525
526
527 usage::
528
529 int val;
530
531 ioctl(fd, HDIO_SET_32BIT, val);
532
533 inputs:
534 New value for io_32bit flag
535
536
537
538 outputs:
539 none
540
541
542
543 error return:
544 - EINVAL Called on a partition
545 - EACCES Access denied: requir
546 - EINVAL value out of range [0
547 - EBUSY Controller busy
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.