2 * Copyright (c) 2003 Silicon Graphics International Corp.
3 * Copyright (c) 2011 Spectra Logic Corporation
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions, and the following disclaimer,
11 * without modification.
12 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
13 * substantially similar to the "NO WARRANTY" disclaimer below
14 * ("Disclaimer") and any redistribution must be conditioned upon
15 * including a substantially similar Disclaimer requirement for further
16 * binary redistribution.
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
22 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
28 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 * POSSIBILITY OF SUCH DAMAGES.
31 * $Id: //depot/users/kenm/FreeBSD-test2/sys/cam/ctl/ctl_ioctl.h#4 $
35 * CAM Target Layer ioctl interface.
37 * Author: Ken Merry <ken@FreeBSD.org>
43 #define CTL_DEFAULT_DEV "/dev/cam/ctl"
45 * Maximum number of targets we support.
47 #define CTL_MAX_TARGETS 1
50 * Maximum target ID we support.
52 #define CTL_MAX_TARGID 15
55 * Maximum number of LUNs we support at the moment. MUST be a power of 2.
57 #define CTL_MAX_LUNS 256
60 * Maximum number of initiators per port.
62 #define CTL_MAX_INIT_PER_PORT 2048 // Was 16
65 * Maximum number of ports registered at one time.
67 #define CTL_MAX_PORTS 32
70 * Maximum number of initiators we support.
72 #define CTL_MAX_INITIATORS (CTL_MAX_INIT_PER_PORT * CTL_MAX_PORTS)
74 /* Hopefully this won't conflict with new misc devices that pop up */
83 uint32_t target_id; /* Passed in to CTL */
84 uint32_t lun_id; /* Passed in to CTL */
85 uint32_t num_entries; /* Returned from CTL */
86 ctl_ooa_status status; /* Returned from CTL */
89 struct ctl_hard_startstop_info {
96 struct ctl_bbrread_info {
97 int lun_num; /* Passed in to CTL */
98 uint64_t lba; /* Passed in to CTL */
99 int len; /* Passed in to CTL */
100 cfi_mt_status status; /* Returned from CTL */
101 cfi_bbrread_status bbr_status; /* Returned from CTL */
102 uint8_t scsi_status; /* Returned from CTL */
103 struct scsi_sense_data sense_data; /* Returned from CTL */
109 CTL_DELAY_TYPE_ONESHOT
114 CTL_DELAY_LOC_DATAMOVE,
116 } ctl_delay_location;
119 CTL_DELAY_STATUS_NONE,
121 CTL_DELAY_STATUS_INVALID_LUN,
122 CTL_DELAY_STATUS_INVALID_TYPE,
123 CTL_DELAY_STATUS_INVALID_LOC,
124 CTL_DELAY_STATUS_NOT_IMPLEMENTED
127 struct ctl_io_delay_info {
130 ctl_delay_type delay_type;
131 ctl_delay_location delay_loc;
133 ctl_delay_status status;
140 } ctl_gs_sync_status;
143 * The target and LUN id specify which device to modify. The sync interval
144 * means that we will let through every N SYNCHRONIZE CACHE commands.
146 struct ctl_sync_info {
147 uint32_t target_id; /* passed to kernel */
148 uint32_t lun_id; /* passed to kernel */
149 int sync_interval; /* depends on whether get/set */
150 ctl_gs_sync_status status; /* passed from kernel */
158 #define CTL_STATS_NUM_TYPES 3
161 CTL_LUN_STATS_NO_BLOCKSIZE = 0x01
162 } ctl_lun_stats_flags;
164 struct ctl_lun_io_port_stats {
166 uint64_t bytes[CTL_STATS_NUM_TYPES];
167 uint64_t operations[CTL_STATS_NUM_TYPES];
168 struct bintime time[CTL_STATS_NUM_TYPES];
169 uint64_t num_dmas[CTL_STATS_NUM_TYPES];
170 struct bintime dma_time[CTL_STATS_NUM_TYPES];
173 struct ctl_lun_io_stats {
177 ctl_lun_stats_flags flags;
178 struct ctl_lun_io_port_stats ports[CTL_MAX_PORTS];
183 CTL_SS_NEED_MORE_SPACE,
188 CTL_STATS_FLAG_NONE = 0x00,
189 CTL_STATS_FLAG_TIME_VALID = 0x01
193 int alloc_len; /* passed to kernel */
194 struct ctl_lun_io_stats *lun_stats; /* passed to/from kernel */
195 int fill_len; /* passed to userland */
196 int num_luns; /* passed to userland */
197 ctl_stats_status status; /* passed to userland */
198 ctl_stats_flags flags; /* passed to userland */
199 struct timespec timestamp; /* passed to userland */
203 * The types of errors that can be injected:
205 * NONE: No error specified.
206 * ABORTED: SSD_KEY_ABORTED_COMMAND, 0x45, 0x00
207 * MEDIUM_ERR: Medium error, different asc/ascq depending on read/write.
208 * UA: Unit attention.
209 * CUSTOM: User specifies the sense data.
210 * TYPE: Mask to use with error types.
212 * Flags that affect injection behavior:
213 * CONTINUOUS: This error will stay around until explicitly cleared.
214 * DESCRIPTOR: Use descriptor sense instead of fixed sense.
217 CTL_LUN_INJ_NONE = 0x000,
218 CTL_LUN_INJ_ABORTED = 0x001,
219 CTL_LUN_INJ_MEDIUM_ERR = 0x002,
220 CTL_LUN_INJ_UA = 0x003,
221 CTL_LUN_INJ_CUSTOM = 0x004,
222 CTL_LUN_INJ_TYPE = 0x0ff,
223 CTL_LUN_INJ_CONTINUOUS = 0x100,
224 CTL_LUN_INJ_DESCRIPTOR = 0x200
228 * Flags to specify what type of command the given error pattern will
229 * execute on. The first group of types can be ORed together.
231 * READ: Any read command.
232 * WRITE: Any write command.
233 * READWRITE: Any read or write command.
234 * READCAP: Any read capacity command.
235 * TUR: Test Unit Ready.
237 * MASK: Mask for basic command patterns.
241 * CMD: The CDB to act on is specified in struct ctl_error_desc_cmd.
242 * RANGE: For read/write commands, act when the LBA is in the
246 CTL_LUN_PAT_NONE = 0x000,
247 CTL_LUN_PAT_READ = 0x001,
248 CTL_LUN_PAT_WRITE = 0x002,
249 CTL_LUN_PAT_READWRITE = CTL_LUN_PAT_READ | CTL_LUN_PAT_WRITE,
250 CTL_LUN_PAT_READCAP = 0x004,
251 CTL_LUN_PAT_TUR = 0x008,
252 CTL_LUN_PAT_ANY = 0x0ff,
253 CTL_LUN_PAT_MASK = 0x0ff,
254 CTL_LUN_PAT_CMD = 0x100,
255 CTL_LUN_PAT_RANGE = 0x200
256 } ctl_lun_error_pattern;
259 * This structure allows the user to specify a particular CDB pattern to
262 * cdb_pattern: Fill in the relevant bytes to look for in the CDB.
263 * cdb_valid_bytes: Bitmask specifying valid bytes in the cdb_pattern.
264 * flags: Specify any command flags (see ctl_io_flags) that
267 struct ctl_error_desc_cmd {
268 uint8_t cdb_pattern[CTL_MAX_CDBLEN];
269 uint32_t cdb_valid_bytes;
274 * Error injection descriptor.
276 * target_id: Target ID to act on.
277 * lun_id LUN to act on.
278 * lun_error: The type of error to inject. See above for descriptions.
279 * error_pattern: What kind of command to act on. See above.
280 * cmd_desc: For CTL_LUN_PAT_CMD only.
281 * lba_range: For CTL_LUN_PAT_RANGE only.
282 * custom_sense: Specify sense. For CTL_LUN_INJ_CUSTOM only.
283 * serial: Serial number returned by the kernel. Use for deletion.
284 * links: Kernel use only.
286 struct ctl_error_desc {
287 uint32_t target_id; /* To kernel */
288 uint32_t lun_id; /* To kernel */
289 ctl_lun_error lun_error; /* To kernel */
290 ctl_lun_error_pattern error_pattern; /* To kernel */
291 struct ctl_error_desc_cmd cmd_desc; /* To kernel */
292 struct ctl_lba_len lba_range; /* To kernel */
293 struct scsi_sense_data custom_sense; /* To kernel */
294 uint64_t serial; /* From kernel */
295 STAILQ_ENTRY(ctl_error_desc) links; /* Kernel use only */
299 CTL_OOA_FLAG_NONE = 0x00,
300 CTL_OOA_FLAG_ALL_LUNS = 0x01
305 CTL_OOA_NEED_MORE_SPACE,
307 } ctl_get_ooa_status;
310 CTL_OOACMD_FLAG_NONE = 0x00,
311 CTL_OOACMD_FLAG_DMA = 0x01,
312 CTL_OOACMD_FLAG_BLOCKED = 0x02,
313 CTL_OOACMD_FLAG_ABORT = 0x04,
314 CTL_OOACMD_FLAG_RTR = 0x08,
315 CTL_OOACMD_FLAG_DMA_QUEUED = 0x10
318 struct ctl_ooa_entry {
319 ctl_ooa_cmd_flags cmd_flags;
320 uint8_t cdb[CTL_MAX_CDBLEN];
324 struct bintime start_bt;
328 ctl_ooa_flags flags; /* passed to kernel */
329 uint64_t lun_num; /* passed to kernel */
330 uint32_t alloc_len; /* passed to kernel */
331 uint32_t alloc_num; /* passed to kernel */
332 struct ctl_ooa_entry *entries; /* filled in kernel */
333 uint32_t fill_len; /* passed to userland */
334 uint32_t fill_num; /* passed to userland */
335 uint32_t dropped_num; /* passed to userland */
336 struct bintime cur_bt; /* passed to userland */
337 ctl_get_ooa_status status; /* passed to userland */
343 CTL_PORT_LIST_NEED_MORE_SPACE,
345 } ctl_port_list_status;
347 struct ctl_port_list {
348 uint32_t alloc_len; /* passed to kernel */
349 uint32_t alloc_num; /* passed to kernel */
350 struct ctl_port_entry *entries; /* filled in kernel */
351 uint32_t fill_len; /* passed to userland */
352 uint32_t fill_num; /* passed to userland */
353 uint32_t dropped_num; /* passed to userland */
354 ctl_port_list_status status; /* passed to userland */
363 #define CTL_ERROR_STR_LEN 160
365 #define CTL_BEARG_RD 0x01
366 #define CTL_BEARG_WR 0x02
367 #define CTL_BEARG_RW (CTL_BEARG_RD|CTL_BEARG_WR)
368 #define CTL_BEARG_ASCII 0x04
373 * namelen: Length of the name field, including the terminating NUL.
375 * name: Name of the paramter. This must be NUL-terminated.
377 * flags: Flags for the parameter, see above for values.
379 * vallen: Length of the value in bytes.
381 * value: Value to be set/fetched.
383 * kname: For kernel use only.
385 * kvalue: For kernel use only.
406 * LUN creation parameters:
408 * flags: Various LUN flags, see ctl_backend.h for a
409 * description of the flag values and meanings.
411 * device_type: The SCSI device type. e.g. 0 for Direct Access,
412 * 3 for Processor, etc. Only certain backends may
413 * support setting this field. The CTL_LUN_FLAG_DEV_TYPE
414 * flag should be set in the flags field if the device
417 * lun_size_bytes: The size of the LUN in bytes. For some backends
418 * this is relevant (e.g. ramdisk), for others, it may
419 * be ignored in favor of using the properties of the
420 * backing store. If specified, this should be a
421 * multiple of the blocksize.
423 * The actual size of the LUN is returned in this
426 * blocksize_bytes: The LUN blocksize in bytes. For some backends this
427 * is relevant, for others it may be ignored in
428 * favor of using the properties of the backing store.
430 * The actual blocksize of the LUN is returned in this
433 * req_lun_id: The requested LUN ID. The CTL_LUN_FLAG_ID_REQ flag
434 * should be set if this is set. The request will be
435 * granted if the LUN number is available, otherwise
436 * the LUN addition request will fail.
438 * The allocated LUN number is returned in this field.
440 * serial_num: This is the value returned in SCSI INQUIRY VPD page
441 * 0x80. If it is specified, the CTL_LUN_FLAG_SERIAL_NUM
442 * flag should be set.
444 * The serial number value used is returned in this
447 * device_id: This is the value returned in the T10 vendor ID
448 * based DESIGNATOR field in the SCSI INQUIRY VPD page
449 * 0x83 data. If it is specified, the CTL_LUN_FLAG_DEVID
450 * flag should be set.
452 * The device id value used is returned in this field.
454 struct ctl_lun_create_params {
455 ctl_backend_lun_flags flags;
457 uint64_t lun_size_bytes;
458 uint32_t blocksize_bytes;
460 uint8_t serial_num[CTL_SN_LEN];
461 uint8_t device_id[CTL_DEVID_LEN];
465 * LUN removal parameters:
467 * lun_id: The number of the LUN to delete. This must be set.
468 * The LUN must be backed by the given backend.
470 struct ctl_lun_rm_params {
475 * LUN modification parameters:
477 * lun_id: The number of the LUN to modify. This must be set.
478 * The LUN must be backed by the given backend.
480 * lun_size_bytes: The size of the LUN in bytes. If zero, update
481 * the size using the backing file size, if possible.
483 struct ctl_lun_modify_params {
485 uint64_t lun_size_bytes;
489 * Union of request type data. Fill in the appropriate union member for
492 union ctl_lunreq_data {
493 struct ctl_lun_create_params create;
494 struct ctl_lun_rm_params rm;
495 struct ctl_lun_modify_params modify;
499 * LUN request interface:
501 * backend: This is required, and is NUL-terminated a string
502 * that is the name of the backend, like "ramdisk" or
505 * reqtype: The type of request, CTL_LUNREQ_CREATE to create a
506 * LUN, CTL_LUNREQ_RM to delete a LUN.
508 * reqdata: Request type-specific information. See the
509 * description of individual the union members above
510 * for more information.
512 * num_be_args: This is the number of backend-specific arguments
513 * in the be_args array.
515 * be_args: This is an array of backend-specific arguments.
516 * See above for a description of the fields in this
519 * status: Status of the LUN request.
521 * error_str: If the status is CTL_LUN_ERROR, this will
522 * contain a string describing the error.
524 * kern_be_args: For kernel use only.
527 char backend[CTL_BE_NAME_LEN];
528 ctl_lunreq_type reqtype;
529 union ctl_lunreq_data reqdata;
531 struct ctl_be_arg *be_args;
532 ctl_lun_status status;
533 char error_str[CTL_ERROR_STR_LEN];
534 struct ctl_be_arg *kern_be_args;
542 * OK: Request completed successfully.
544 * NEED_MORE_SPACE: The allocated length of the entries field is too
545 * small for the available data.
547 * ERROR: An error occured, look at the error string for a
548 * description of the error.
553 CTL_LUN_LIST_NEED_MORE_SPACE,
555 } ctl_lun_list_status;
560 * backend_name: This is a NUL-terminated string. If the string
561 * length is 0, then all LUNs on all backends will
562 * be enumerated. Otherwise this is the name of the
563 * backend to be enumerated, like "ramdisk" or "block".
565 * alloc_len: The length of the data buffer allocated for entries.
566 * In order to properly size the buffer, make one call
567 * with alloc_len set to 0, and then use the returned
568 * dropped_len as the buffer length to allocate and
569 * pass in on a subsequent call.
571 * lun_xml: XML-formatted information on the requested LUNs.
573 * fill_len: The amount of data filled in the storage for entries.
575 * status: The status of the request. See above for the
576 * description of the values of this field.
578 * error_str: If the status indicates an error, this string will
579 * be filled in to describe the error.
581 struct ctl_lun_list {
582 char backend[CTL_BE_NAME_LEN]; /* passed to kernel*/
583 uint32_t alloc_len; /* passed to kernel */
584 char *lun_xml; /* filled in kernel */
585 uint32_t fill_len; /* passed to userland */
586 ctl_lun_list_status status; /* passed to userland */
587 char error_str[CTL_ERROR_STR_LEN];
588 /* passed to userland */
591 #define CTL_IO _IOWR(CTL_MINOR, 0x00, union ctl_io)
592 #define CTL_ENABLE_PORT _IOW(CTL_MINOR, 0x04, struct ctl_port_entry)
593 #define CTL_DISABLE_PORT _IOW(CTL_MINOR, 0x05, struct ctl_port_entry)
594 #define CTL_DUMP_OOA _IO(CTL_MINOR, 0x06)
595 #define CTL_CHECK_OOA _IOWR(CTL_MINOR, 0x07, struct ctl_ooa_info)
596 #define CTL_HARD_STOP _IOR(CTL_MINOR, 0x08, \
597 struct ctl_hard_startstop_info)
598 #define CTL_HARD_START _IOR(CTL_MINOR, 0x09, \
599 struct ctl_hard_startstop_info)
600 #define CTL_DELAY_IO _IOWR(CTL_MINOR, 0x10, struct ctl_io_delay_info)
601 #define CTL_REALSYNC_GET _IOR(CTL_MINOR, 0x11, int)
602 #define CTL_REALSYNC_SET _IOW(CTL_MINOR, 0x12, int)
603 #define CTL_SETSYNC _IOWR(CTL_MINOR, 0x13, struct ctl_sync_info)
604 #define CTL_GETSYNC _IOWR(CTL_MINOR, 0x14, struct ctl_sync_info)
605 #define CTL_GETSTATS _IOWR(CTL_MINOR, 0x15, struct ctl_stats)
606 #define CTL_ERROR_INJECT _IOWR(CTL_MINOR, 0x16, struct ctl_error_desc)
607 #define CTL_BBRREAD _IOWR(CTL_MINOR, 0x17, struct ctl_bbrread_info)
608 #define CTL_GET_OOA _IOWR(CTL_MINOR, 0x18, struct ctl_ooa)
609 #define CTL_DUMP_STRUCTS _IO(CTL_MINOR, 0x19)
610 #define CTL_GET_PORT_LIST _IOWR(CTL_MINOR, 0x20, struct ctl_port_list)
611 #define CTL_LUN_REQ _IOWR(CTL_MINOR, 0x21, struct ctl_lun_req)
612 #define CTL_LUN_LIST _IOWR(CTL_MINOR, 0x22, struct ctl_lun_list)
613 #define CTL_ERROR_INJECT_DELETE _IOW(CTL_MINOR, 0x23, struct ctl_error_desc)
614 #define CTL_SET_PORT_WWNS _IOW(CTL_MINOR, 0x24, struct ctl_port_entry)
616 #endif /* _CTL_IOCTL_H_ */