1 #ifndef SG_LIB_H 2 #define SG_LIB_H 3 4 /* 5 * Copyright (c) 2004-2014 Douglas Gilbert. 6 * All rights reserved. 7 * Use of this source code is governed by a BSD-style 8 * license that can be found in the BSD_LICENSE file. 9 */ 10 11 /* 12 * 13 * On 5th October 2004 a FreeBSD license was added to this file. 14 * The intention is to keep this file and the related sg_lib.c file 15 * as open source and encourage their unencumbered use. 16 * 17 * Current version number is in the sg_lib.c file and can be accessed 18 * with the sg_lib_version() function. 19 */ 20 21 22 /* 23 * This header file contains defines and function declarations that may 24 * be useful to applications that communicate with devices that use a 25 * SCSI command set. These command sets have names like SPC-4, SBC-3, 26 * SSC-3, SES-2 and draft standards defining them can be found at 27 * http://www.t10.org . Virtually all devices in the Linux SCSI subsystem 28 * utilize SCSI command sets. Many devices in other Linux device subsystems 29 * utilize SCSI command sets either natively or via emulation (e.g. a 30 * parallel ATA disk in a USB enclosure). 31 */ 32 33 #include <stdio.h> 34 #include <stdint.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /* SCSI Peripheral Device Types (PDT) [5 bit field] */ 41 #define PDT_DISK 0x0 /* direct access block device (disk) */ 42 #define PDT_TAPE 0x1 /* sequential access device (magnetic tape) */ 43 #define PDT_PRINTER 0x2 /* printer device (see SSC-1) */ 44 #define PDT_PROCESSOR 0x3 /* processor device (e.g. SAFTE device) */ 45 #define PDT_WO 0x4 /* write once device (some optical disks) */ 46 #define PDT_MMC 0x5 /* CD/DVD/BD (multi-media) */ 47 #define PDT_SCANNER 0x6 /* obsolete */ 48 #define PDT_OPTICAL 0x7 /* optical memory device (some optical disks) */ 49 #define PDT_MCHANGER 0x8 /* media changer device (e.g. tape robot) */ 50 #define PDT_COMMS 0x9 /* communications device (obsolete) */ 51 #define PDT_SAC 0xc /* storage array controller device */ 52 #define PDT_SES 0xd /* SCSI Enclosure Services (SES) device */ 53 #define PDT_RBC 0xe /* Reduced Block Commands (simplified PDT_DISK) */ 54 #define PDT_OCRW 0xf /* optical card read/write device */ 55 #define PDT_BCC 0x10 /* bridge controller commands */ 56 #define PDT_OSD 0x11 /* Object Storage Device (OSD) */ 57 #define PDT_ADC 0x12 /* Automation/drive commands (ADC) */ 58 #define PDT_SMD 0x13 /* Security Manager Device (SMD) */ 59 #define PDT_ZBC 0x14 /* Zoned Block Commands (ZBC) */ 60 #define PDT_WLUN 0x1e /* Well known logical unit (WLUN) */ 61 #define PDT_UNKNOWN 0x1f /* Unknown or no device type */ 62 63 #ifndef SAM_STAT_GOOD 64 /* The SCSI status codes as found in SAM-4 at www.t10.org */ 65 #define SAM_STAT_GOOD 0x0 66 #define SAM_STAT_CHECK_CONDITION 0x2 67 #define SAM_STAT_CONDITION_MET 0x4 68 #define SAM_STAT_BUSY 0x8 69 #define SAM_STAT_INTERMEDIATE 0x10 /* obsolete in SAM-4 */ 70 #define SAM_STAT_INTERMEDIATE_CONDITION_MET 0x14 /* obsolete in SAM-4 */ 71 #define SAM_STAT_RESERVATION_CONFLICT 0x18 72 #define SAM_STAT_COMMAND_TERMINATED 0x22 /* obsolete in SAM-3 */ 73 #define SAM_STAT_TASK_SET_FULL 0x28 74 #define SAM_STAT_ACA_ACTIVE 0x30 75 #define SAM_STAT_TASK_ABORTED 0x40 76 #endif 77 78 /* The SCSI sense key codes as found in SPC-4 at www.t10.org */ 79 #define SPC_SK_NO_SENSE 0x0 80 #define SPC_SK_RECOVERED_ERROR 0x1 81 #define SPC_SK_NOT_READY 0x2 82 #define SPC_SK_MEDIUM_ERROR 0x3 83 #define SPC_SK_HARDWARE_ERROR 0x4 84 #define SPC_SK_ILLEGAL_REQUEST 0x5 85 #define SPC_SK_UNIT_ATTENTION 0x6 86 #define SPC_SK_DATA_PROTECT 0x7 87 #define SPC_SK_BLANK_CHECK 0x8 88 #define SPC_SK_VENDOR_SPECIFIC 0x9 89 #define SPC_SK_COPY_ABORTED 0xa 90 #define SPC_SK_ABORTED_COMMAND 0xb 91 #define SPC_SK_RESERVED 0xc 92 #define SPC_SK_VOLUME_OVERFLOW 0xd 93 #define SPC_SK_MISCOMPARE 0xe 94 #define SPC_SK_COMPLETED 0xf 95 96 /* Transport protocol identifiers or just Protocol identifiers */ 97 #define TPROTO_FCP 0 98 #define TPROTO_SPI 1 99 #define TPROTO_SSA 2 100 #define TPROTO_1394 3 101 #define TPROTO_SRP 4 102 #define TPROTO_ISCSI 5 103 #define TPROTO_SAS 6 104 #define TPROTO_ADT 7 105 #define TPROTO_ATA 8 106 #define TPROTO_UAS 9 /* USB attached SCSI */ 107 #define TPROTO_SOP 0xa /* SCSI over PCIe */ 108 #define TPROTO_NONE 0xf 109 110 111 /* The format of the version string is like this: "1.87 20130731" */ 112 const char * sg_lib_version(); 113 114 /* Returns length of SCSI command given the opcode (first byte). 115 * Yields the wrong answer for variable length commands (opcode=0x7f) 116 * and potentially some vendor specific commands. */ 117 int sg_get_command_size(unsigned char cdb_byte0); 118 119 /* Command name given pointer to the cdb. Certain command names 120 * depend on peripheral type (give 0 if unknown). Places command 121 * name into buff and will write no more than buff_len bytes. */ 122 void sg_get_command_name(const unsigned char * cdbp, int peri_type, 123 int buff_len, char * buff); 124 125 /* Command name given only the first byte (byte 0) of a cdb and 126 * peripheral type. */ 127 void sg_get_opcode_name(unsigned char cdb_byte0, int peri_type, int buff_len, 128 char * buff); 129 130 /* Command name given opcode (byte 0), service action and peripheral type. 131 * If no service action give 0, if unknown peripheral type give 0. */ 132 void sg_get_opcode_sa_name(unsigned char cdb_byte0, int service_action, 133 int peri_type, int buff_len, char * buff); 134 135 /* Fetch scsi status string. */ 136 void sg_get_scsi_status_str(int scsi_status, int buff_len, char * buff); 137 138 /* This is a slightly stretched SCSI sense "descriptor" format header. 139 * The addition is to allow the 0x70 and 0x71 response codes. The idea 140 * is to place the salient data of both "fixed" and "descriptor" sense 141 * format into one structure to ease application processing. 142 * The original sense buffer should be kept around for those cases 143 * in which more information is required (e.g. the LBA of a MEDIUM ERROR). */ 144 struct sg_scsi_sense_hdr { 145 unsigned char response_code; /* permit: 0x0, 0x70, 0x71, 0x72, 0x73 */ 146 unsigned char sense_key; 147 unsigned char asc; 148 unsigned char ascq; 149 unsigned char byte4; 150 unsigned char byte5; 151 unsigned char byte6; 152 unsigned char additional_length; 153 }; 154 155 /* Maps the salient data from a sense buffer which is in either fixed or 156 * descriptor format into a structure mimicking a descriptor format 157 * header (i.e. the first 8 bytes of sense descriptor format). 158 * If zero response code returns 0. Otherwise returns 1 and if 'sshp' is 159 * non-NULL then zero all fields and then set the appropriate fields in 160 * that structure. sshp::additional_length is always 0 for response 161 * codes 0x70 and 0x71 (fixed format). */ 162 int sg_scsi_normalize_sense(const unsigned char * sensep, int sense_len, 163 struct sg_scsi_sense_hdr * sshp); 164 165 /* Attempt to find the first SCSI sense data descriptor that matches the 166 * given 'desc_type'. If found return pointer to start of sense data 167 * descriptor; otherwise (including fixed format sense data) returns NULL. */ 168 const unsigned char * sg_scsi_sense_desc_find(const unsigned char * sensep, 169 int sense_len, int desc_type); 170 171 /* Get sense key from sense buffer. If successful returns a sense key value 172 * between 0 and 15. If sense buffer cannot be decode, returns -1 . */ 173 int sg_get_sense_key(const unsigned char * sensep, int sense_len); 174 175 /* Yield string associated with sense_key value. Returns 'buff'. */ 176 char * sg_get_sense_key_str(int sense_key, int buff_len, char * buff); 177 178 /* Yield string associated with ASC/ASCQ values. Returns 'buff'. */ 179 char * sg_get_asc_ascq_str(int asc, int ascq, int buff_len, char * buff); 180 181 /* Returns 1 if valid bit set, 0 if valid bit clear. Irrespective the 182 * information field is written out via 'info_outp' (except when it is 183 * NULL). Handles both fixed and descriptor sense formats. */ 184 int sg_get_sense_info_fld(const unsigned char * sensep, int sb_len, 185 uint64_t * info_outp); 186 187 /* Returns 1 if any of the 3 bits (i.e. FILEMARK, EOM or ILI) are set. 188 * In descriptor format if the stream commands descriptor not found 189 * then returns 0. Writes 1 or 0 corresponding to these bits to the 190 * last three arguments if they are non-NULL. */ 191 int sg_get_sense_filemark_eom_ili(const unsigned char * sensep, int sb_len, 192 int * filemark_p, int * eom_p, int * ili_p); 193 194 /* Returns 1 if SKSV is set and sense key is NO_SENSE or NOT_READY. Also 195 * returns 1 if progress indication sense data descriptor found. Places 196 * progress field from sense data where progress_outp points. If progress 197 * field is not available returns 0. Handles both fixed and descriptor 198 * sense formats. N.B. App should multiply by 100 and divide by 65536 199 * to get percentage completion from given value. */ 200 int sg_get_sense_progress_fld(const unsigned char * sensep, int sb_len, 201 int * progress_outp); 202 203 /* Closely related to sg_print_sense(). Puts decoded sense data in 'buff'. 204 * Usually multiline with multiple '\n' including one trailing. If 205 * 'raw_sinfo' set appends sense buffer in hex. */ 206 void sg_get_sense_str(const char * leadin, const unsigned char * sense_buffer, 207 int sb_len, int raw_sinfo, int buff_len, char * buff); 208 209 /* Yield string associated with peripheral device type (pdt). Returns 210 * 'buff'. If 'pdt' out of range yields "bad pdt" string. */ 211 char * sg_get_pdt_str(int pdt, int buff_len, char * buff); 212 213 /* Yield string associated with transport protocol identifier (tpi). Returns 214 * 'buff'. If 'tpi' out of range yields "bad tpi" string. */ 215 char * sg_get_trans_proto_str(int tpi, int buff_len, char * buff); 216 217 extern FILE * sg_warnings_strm; 218 219 void sg_set_warnings_strm(FILE * warnings_strm); 220 221 /* The following "print" functions send ACSII to 'sg_warnings_strm' file 222 * descriptor (default value is stderr) */ 223 void sg_print_command(const unsigned char * command); 224 void sg_print_sense(const char * leadin, const unsigned char * sense_buffer, 225 int sb_len, int raw_info); 226 void sg_print_scsi_status(int scsi_status); 227 228 /* Utilities can use these exit status values for syntax errors and 229 * file (device node) problems (e.g. not found or permissions). */ 230 #define SG_LIB_SYNTAX_ERROR 1 /* command line syntax problem */ 231 #define SG_LIB_FILE_ERROR 15 /* device or other file problem */ 232 233 /* The sg_err_category_sense() function returns one of the following. 234 * These may be used as exit status values (from a process). Notice that 235 * some of the lower values correspond to SCSI sense key values. */ 236 #define SG_LIB_CAT_CLEAN 0 /* No errors or other information */ 237 /* Value 1 left unused for utilities to use SG_LIB_SYNTAX_ERROR */ 238 #define SG_LIB_CAT_NOT_READY 2 /* sense key, unit stopped? */ 239 /* [sk,asc,ascq: 0x2,*,*] */ 240 #define SG_LIB_CAT_MEDIUM_HARD 3 /* medium or hardware error, blank check */ 241 /* [sk,asc,ascq: 0x3/0x4/0x8,*,*] */ 242 #define SG_LIB_CAT_ILLEGAL_REQ 5 /* Illegal request (other than invalid */ 243 /* opcode): [sk,asc,ascq: 0x5,*,*] */ 244 #define SG_LIB_CAT_UNIT_ATTENTION 6 /* sense key, device state changed */ 245 /* [sk,asc,ascq: 0x6,*,*] */ 246 /* was SG_LIB_CAT_MEDIA_CHANGED earlier [sk,asc,ascq: 0x6,0x28,*] */ 247 #define SG_LIB_CAT_DATA_PROTECT 7 /* sense key, media write protected? */ 248 /* [sk,asc,ascq: 0x7,*,*] */ 249 #define SG_LIB_CAT_INVALID_OP 9 /* (Illegal request,) Invalid opcode: */ 250 /* [sk,asc,ascq: 0x5,0x20,0x0] */ 251 #define SG_LIB_CAT_COPY_ABORTED 10 /* sense key, some data transferred */ 252 /* [sk,asc,ascq: 0xa,*,*] */ 253 #define SG_LIB_CAT_ABORTED_COMMAND 11 /* interpreted from sense buffer */ 254 /* [sk,asc,ascq: 0xb,! 0x10,*] */ 255 #define SG_LIB_CAT_MISCOMPARE 14 /* sense key, probably verify */ 256 /* [sk,asc,ascq: 0xe,*,*] */ 257 #define SG_LIB_CAT_NO_SENSE 20 /* sense data with key of "no sense" */ 258 /* [sk,asc,ascq: 0x0,*,*] */ 259 #define SG_LIB_CAT_RECOVERED 21 /* Successful command after recovered err */ 260 /* [sk,asc,ascq: 0x1,*,*] */ 261 #define SG_LIB_CAT_RES_CONFLICT SAM_STAT_RESERVATION_CONFLICT 262 /* 24: this is a SCSI status, not sense. */ 263 /* It indicates reservation by another */ 264 /* machine blocks this command */ 265 #define SG_LIB_CAT_PROTECTION 40 /* subset of aborted command (for PI, DIF) */ 266 /* [sk,asc,ascq: 0xb,0x10,*] */ 267 #define SG_LIB_CAT_MALFORMED 97 /* Response to SCSI command malformed */ 268 #define SG_LIB_CAT_SENSE 98 /* Something else is in the sense buffer */ 269 #define SG_LIB_CAT_OTHER 99 /* Some other error/warning has occurred */ 270 /* (e.g. a transport or driver error) */ 271 272 /* Returns a SG_LIB_CAT_* value. If cannot decode sense_buffer or a less 273 * common sense key then return SG_LIB_CAT_SENSE .*/ 274 int sg_err_category_sense(const unsigned char * sense_buffer, int sb_len); 275 276 /* Here are some additional sense data categories that are not returned 277 * by sg_err_category_sense() but are returned by some related functions. */ 278 #define SG_LIB_CAT_ILLEGAL_REQ_WITH_INFO 17 /* Illegal request (other than */ 279 /* invalid opcode) plus 'info' field: */ 280 /* [sk,asc,ascq: 0x5,*,*] */ 281 #define SG_LIB_CAT_MEDIUM_HARD_WITH_INFO 18 /* medium or hardware error */ 282 /* sense key plus 'info' field: */ 283 /* [sk,asc,ascq: 0x3/0x4,*,*] */ 284 #define SG_LIB_CAT_PROTECTION_WITH_INFO 41 /* aborted command sense key, */ 285 /* protection plus 'info' field: */ 286 /* [sk,asc,ascq: 0xb,0x10,*] */ 287 #define SG_LIB_CAT_TIMEOUT 33 288 289 /* Yield string associated with sense category. Returns 'buff' (or pointer 290 * to "Bad sense category" if 'buff' is NULL). If sense_cat unknown then 291 * yield "Sense category: <sense_cat>" string. */ 292 const char * sg_get_category_sense_str(int sense_cat, int buff_len, 293 char * buff, int verbose); 294 295 296 /* Iterates to next designation descriptor in the device identification 297 * VPD page. The 'initial_desig_desc' should point to start of first 298 * descriptor with 'page_len' being the number of valid bytes in that 299 * and following descriptors. To start, 'off' should point to a negative 300 * value, thereafter it should point to the value yielded by the previous 301 * call. If 0 returned then 'initial_desig_desc + *off' should be a valid 302 * descriptor; returns -1 if normal end condition and -2 for an abnormal 303 * termination. Matches association, designator_type and/or code_set when 304 * any of those values are greater than or equal to zero. */ 305 int sg_vpd_dev_id_iter(const unsigned char * initial_desig_desc, int page_len, 306 int * off, int m_assoc, int m_desig_type, 307 int m_code_set); 308 309 310 /* <<< General purpose (i.e. not SCSI specific) utility functions >>> */ 311 312 /* Always returns valid string even if errnum is wild (or library problem). 313 * If errnum is negative, flip its sign. */ 314 char * safe_strerror(int errnum); 315 316 317 /* Print (to stdout) 'str' of bytes in hex, 16 bytes per line optionally 318 * followed at the right hand side of the line with an ASCII interpretation. 319 * Each line is prefixed with an address, starting at 0 for str[0]..str[15]. 320 * All output numbers are in hex. 'no_ascii' allows for 3 output types: 321 * > 0 each line has address then up to 16 ASCII-hex bytes 322 * = 0 in addition, the bytes are listed in ASCII to the right 323 * < 0 only the ASCII-hex bytes are listed (i.e. without address) 324 */ 325 void dStrHex(const char* str, int len, int no_ascii); 326 327 /* Print (to sg_warnings_strm (stderr)) 'str' of bytes in hex, 16 bytes per 328 * line optionally followed at right by its ASCII interpretation. Same 329 * logic as dStrHex() with different output stream (i.e. stderr). */ 330 void dStrHexErr(const char* str, int len, int no_ascii); 331 332 /* Read 'len' bytes from 'str' and output as ASCII-Hex bytes (space 333 * separated) to 'b' not to exceed 'b_len' characters. Each line 334 * starts with 'leadin' (NULL for no leadin) and there are 16 bytes 335 * per line with an extra space between the 8th and 9th bytes. 'format' 336 * is unused, set to 0 . */ 337 void dStrHexStr(const char* str, int len, const char * leadin, int format, 338 int b_len, char * b); 339 340 /* Returns 1 when executed on big endian machine; else returns 0. 341 * Useful for displaying ATA identify words (which need swapping on a 342 * big endian machine). 343 */ 344 int sg_is_big_endian(); 345 346 /* Extract character sequence from ATA words as in the model string 347 * in a IDENTIFY DEVICE response. Returns number of characters 348 * written to 'ochars' before 0 character is found or 'num' words 349 * are processed. */ 350 int sg_ata_get_chars(const unsigned short * word_arr, int start_word, 351 int num_words, int is_big_endian, char * ochars); 352 353 /* Print (to stdout) 16 bit 'words' in hex, 8 words per line optionally 354 * followed at the right hand side of the line with an ASCII interpretation 355 * (pairs of ASCII characters in big endian order (upper first)). 356 * Each line is prefixed with an address, starting at 0. 357 * All output numbers are in hex. 'no_ascii' allows for 3 output types: 358 * > 0 each line has address then up to 8 ASCII-hex words 359 * = 0 in addition, the words are listed in ASCII pairs to the right 360 * = -1 only the ASCII-hex words are listed (i.e. without address) 361 * = -2 only the ASCII-hex words, formatted for "hdparm --Istdin" 362 * < -2 same as -1 363 * If 'swapb' non-zero then bytes in each word swapped. Needs to be set 364 * for ATA IDENTIFY DEVICE response on big-endian machines. 365 */ 366 void dWordHex(const unsigned short* words, int num, int no_ascii, int swapb); 367 368 /* If the number in 'buf' can not be decoded or the multiplier is unknown 369 * then -1 is returned. Accepts a hex prefix (0x or 0X) or a 'h' (or 'H') 370 * suffix. Otherwise a decimal multiplier suffix may be given. Recognised 371 * multipliers: c C *1; w W *2; b B *512; k K KiB *1,024; 372 * KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; 373 * GB *1,000,000,000 and <n>x<m> which multiplies <n> by <m> . Ignore leading 374 * spaces and tabs; accept comma, space, tab and hash as terminator. */ 375 int sg_get_num(const char * buf); 376 377 /* If the number in 'buf' can not be decoded then -1 is returned. Accepts a 378 * hex prefix (0x or 0X) or a 'h' (or 'H') suffix; otherwise decimal is 379 * assumed. Does not accept multipliers. Accept a comma (","), a whitespace 380 * or newline as terminator. */ 381 int sg_get_num_nomult(const char * buf); 382 383 /* If the number in 'buf' can not be decoded or the multiplier is unknown 384 * then -1LL is returned. Accepts a hex prefix (0x or 0X) or a 'h' (or 'H') 385 * suffix. Otherwise a decimal multiplier suffix may be given. In addition 386 * to supporting the multipliers of sg_get_num(), this function supports: 387 * t T TiB *(2**40); TB *(10**12); p P PiB *(2**50); PB *(10**15) . 388 * Ignore leading spaces and tabs; accept comma, space, tab and hash as 389 * terminator. */ 390 int64_t sg_get_llnum(const char * buf); 391 392 393 /* <<< Architectural support functions [is there a better place?] >>> */ 394 395 /* Non Unix OSes distinguish between text and binary files. 396 * Set text mode on fd. Does nothing in Unix. Returns negative number on 397 * failure. */ 398 int sg_set_text_mode(int fd); 399 400 /* Set binary mode on fd. Does nothing in Unix. Returns negative number on 401 * failure. */ 402 int sg_set_binary_mode(int fd); 403 404 #ifdef __cplusplus 405 } 406 #endif 407 408 #endif 409