1 #ifndef SG_CMDS_BASIC_H 2 #define SG_CMDS_BASIC_H 3 4 /* 5 * Copyright (c) 2004-2020 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 * SPDX-License-Identifier: BSD-2-Clause 11 */ 12 13 /* 14 * Error, warning and verbose output is sent to the file pointed to by 15 * sg_warnings_strm which is declared in sg_lib.h and can be set with 16 * the sg_set_warnings_strm() function. If not given sg_warnings_strm 17 * defaults to stderr. 18 * If 'noisy' is false and 'verbose' is zero then following functions should 19 * not output anything to sg_warnings_strm. If 'noisy' is true and 'verbose' 20 * is zero then Unit Attention, Recovered, Medium and Hardware errors (sense 21 * keys) send output to sg_warnings_strm. Increasing values of 'verbose' 22 * send increasing amounts of (debug) output to sg_warnings_strm. 23 */ 24 25 #include <stdint.h> 26 #include <stdbool.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /* Functions with the "_pt" suffix take a pointer to an object (derived from) 33 * sg_pt_base rather than an open file descriptor as their first argument. 34 * That object is assumed to be constructed and have a device file descriptor 35 * associated with it. clear_scsi_pt_obj() is called at the start of each 36 * "_pt" function. Caller is responsible for lifetime of ptp. 37 * If the sense buffer is accessed outside the "_pt" function then the caller 38 * must invoke set_scsi_pt_sense() _prior_ to the "_pt" function. Otherwise 39 * a sense buffer local to "_pt" function is used. 40 * Usually the cdb pointer will be NULL going into the "_pt" functions but 41 * could be given by the caller in which case it will used rather than a 42 * locally generated one. */ 43 44 struct sg_pt_base; 45 46 47 /* Invokes a SCSI INQUIRY command and yields the response 48 * Returns 0 when successful, SG_LIB_CAT_INVALID_OP -> not supported, 49 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, 50 * SG_LIB_CAT_ABORTED_COMMAND, a negated errno or -1 -> other errors */ 51 int sg_ll_inquiry(int sg_fd, bool cmddt, bool evpd, int pg_op, void * resp, 52 int mx_resp_len, bool noisy, int verbose); 53 54 /* Invokes a SCSI INQUIRY command and yields the response. Returns 0 when 55 * successful, various SG_LIB_CAT_* positive values, negated error or -1 56 * for other errors. The CMDDT field is obsolete in the INQUIRY cdb (since 57 * spc3r16 in 2003) so * an argument to set it has been removed (use the 58 * REPORT SUPPORTED OPERATION CODES command instead). Adds the ability to 59 * set the command abort timeout and the ability to report the residual 60 * count. If timeout_secs is zero or less the default command abort timeout 61 * (60 seconds) is used. If residp is non-NULL then the residual value is 62 * written where residp points. A residual value of 0 implies mx_resp_len 63 * bytes have be written where resp points. If the residual value equals 64 * mx_resp_len then no bytes have been written. */ 65 int sg_ll_inquiry_v2(int sg_fd, bool evpd, int pg_op, void * resp, 66 int mx_resp_len, int timeout_secs, int * residp, 67 bool noisy, int verbose); 68 69 /* Similar to sg_ll_inquiry_v2(). See note above about "_pt" suffix. */ 70 int sg_ll_inquiry_pt(struct sg_pt_base * ptp, bool evpd, int pg_op, 71 void * resp, int mx_resp_len, int timeout_secs, 72 int * residp, bool noisy, int verbose); 73 74 /* Invokes a SCSI LOG SELECT command. Return of 0 -> success, 75 * SG_LIB_CAT_INVALID_OP -> Log Select not supported, 76 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_UNIT_ATTENTION, 77 * SG_LIB_CAT_ABORTED_COMMAND, * SG_LIB_CAT_NOT_READY -> device not ready, 78 * -1 -> other failure */ 79 int sg_ll_log_select(int sg_fd, bool pcr, bool sp, int pc, int pg_code, 80 int subpg_code, uint8_t * paramp, int param_len, 81 bool noisy, int verbose); 82 83 /* Invokes a SCSI LOG SENSE command. Return of 0 -> success, 84 * SG_LIB_CAT_INVALID_OP -> Log Sense not supported, 85 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_UNIT_ATTENTION, 86 * SG_LIB_CAT_NOT_READY -> device not ready, SG_LIB_CAT_ABORTED_COMMAND, 87 * -1 -> other failure */ 88 int sg_ll_log_sense(int sg_fd, bool ppc, bool sp, int pc, int pg_code, 89 int subpg_code, int paramp, uint8_t * resp, 90 int mx_resp_len, bool noisy, int verbose); 91 92 /* Same as sg_ll_log_sense() apart from timeout_secs and residp. See 93 * sg_ll_inquiry_v2() for their description */ 94 int sg_ll_log_sense_v2(int sg_fd, bool ppc, bool sp, int pc, int pg_code, 95 int subpg_code, int paramp, uint8_t * resp, 96 int mx_resp_len, int timeout_secs, int * residp, 97 bool noisy, int verbose); 98 99 /* Invokes a SCSI MODE SELECT (6) command. Return of 0 -> success, 100 * SG_LIB_CAT_INVALID_OP -> invalid opcode, SG_LIB_CAT_ILLEGAL_REQ -> 101 * bad field in cdb, * SG_LIB_CAT_NOT_READY -> device not ready, 102 * SG_LIB_CAT_UNIT_ATTENTION, SG_LIB_CAT_ABORTED_COMMAND, 103 * -1 -> other failure */ 104 int sg_ll_mode_select6(int sg_fd, bool pf, bool sp, void * paramp, 105 int param_len, bool noisy, int verbose); 106 /* v2 adds RTD (revert to defaults) bit, added in spc5r11 */ 107 int sg_ll_mode_select6_v2(int sg_fd, bool pf, bool rtd, bool sp, 108 void * paramp, int param_len, bool noisy, 109 int verbose); 110 111 /* Invokes a SCSI MODE SELECT (10) command. Return of 0 -> success, 112 * SG_LIB_CAT_INVALID_OP -> invalid opcode, SG_LIB_CAT_ILLEGAL_REQ -> 113 * bad field in cdb, * SG_LIB_CAT_NOT_READY -> device not ready, 114 * SG_LIB_CAT_UNIT_ATTENTION, SG_LIB_CAT_ABORTED_COMMAND, 115 * -1 -> other failure */ 116 int sg_ll_mode_select10(int sg_fd, bool pf, bool sp, void * paramp, 117 int param_len, bool noisy, int verbose); 118 /* v2 adds RTD (revert to defaults) bit, added in spc5r11 */ 119 int sg_ll_mode_select10_v2(int sg_fd, bool pf, bool rtd, bool sp, 120 void * paramp, int param_len, bool noisy, 121 int verbose); 122 123 /* Invokes a SCSI MODE SENSE (6) command. Return of 0 -> success, 124 * SG_LIB_CAT_INVALID_OP -> invalid opcode, SG_LIB_CAT_ILLEGAL_REQ -> 125 * bad field in cdb, * SG_LIB_CAT_NOT_READY -> device not ready, 126 * SG_LIB_CAT_UNIT_ATTENTION, SG_LIB_CAT_ABORTED_COMMAND, 127 * -1 -> other failure */ 128 int sg_ll_mode_sense6(int sg_fd, bool dbd, int pc, int pg_code, 129 int sub_pg_code, void * resp, int mx_resp_len, 130 bool noisy, int verbose); 131 132 /* Invokes a SCSI MODE SENSE (10) command. Return of 0 -> success, 133 * SG_LIB_CAT_INVALID_OP -> invalid opcode, SG_LIB_CAT_ILLEGAL_REQ -> 134 * bad field in cdb, * SG_LIB_CAT_NOT_READY -> device not ready, 135 * SG_LIB_CAT_UNIT_ATTENTION, SG_LIB_CAT_ABORTED_COMMAND, 136 * -1 -> other failure */ 137 int sg_ll_mode_sense10(int sg_fd, bool llbaa, bool dbd, int pc, int pg_code, 138 int sub_pg_code, void * resp, int mx_resp_len, 139 bool noisy, int verbose); 140 141 /* Same as sg_ll_mode_sense10() apart from timeout_secs and residp. See 142 * sg_ll_inquiry_v2() for their description */ 143 int sg_ll_mode_sense10_v2(int sg_fd, bool llbaa, bool dbd, int pc, 144 int pg_code, int sub_pg_code, void * resp, 145 int mx_resp_len, int timeout_secs, int * residp, 146 bool noisy, int verbose); 147 148 /* Invokes a SCSI PREVENT ALLOW MEDIUM REMOVAL command (SPC-3) 149 * prevent==0 allows removal, prevent==1 prevents removal ... 150 * Return of 0 -> success, 151 * SG_LIB_CAT_INVALID_OP -> command not supported 152 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_UNIT_ATTENTION, 153 * SG_LIB_CAT_NOT_READY -> device not ready, SG_LIB_CAT_ABORTED_COMMAND, 154 * -1 -> other failure */ 155 int sg_ll_prevent_allow(int sg_fd, int prevent, bool noisy, int verbose); 156 157 /* Invokes a SCSI READ CAPACITY (10) command. Return of 0 -> success, 158 * SG_LIB_CAT_INVALID_OP -> invalid opcode, SG_LIB_CAT_UNIT_ATTENTION 159 * -> perhaps media changed, SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, 160 * SG_LIB_CAT_NOT_READY -> device not ready, SG_LIB_CAT_ABORTED_COMMAND, 161 * -1 -> other failure */ 162 int sg_ll_readcap_10(int sg_fd, bool pmi, unsigned int lba, void * resp, 163 int mx_resp_len, bool noisy, int verbose); 164 165 /* Invokes a SCSI READ CAPACITY (16) command. Returns 0 -> success, 166 * SG_LIB_CAT_UNIT_ATTENTION -> media changed??, SG_LIB_CAT_INVALID_OP 167 * -> cdb not supported, SG_LIB_CAT_IlLEGAL_REQ -> bad field in cdb 168 * SG_LIB_CAT_NOT_READY -> device not ready, SG_LIB_CAT_ABORTED_COMMAND, 169 * -1 -> other failure */ 170 int sg_ll_readcap_16(int sg_fd, bool pmi, uint64_t llba, void * resp, 171 int mx_resp_len, bool noisy, int verbose); 172 173 /* Invokes a SCSI REPORT LUNS command. Return of 0 -> success, 174 * SG_LIB_CAT_INVALID_OP -> Report Luns not supported, 175 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_ABORTED_COMMAND, 176 * SG_LIB_NOT_READY (shouldn't happen), -1 -> other failure */ 177 int sg_ll_report_luns(int sg_fd, int select_report, void * resp, 178 int mx_resp_len, bool noisy, int verbose); 179 180 /* Similar to sg_ll_report_luns(). See note above about "_pt" suffix. */ 181 int sg_ll_report_luns_pt(struct sg_pt_base * ptp, int select_report, 182 void * resp, int mx_resp_len, bool noisy, 183 int verbose); 184 185 /* Invokes a SCSI REQUEST SENSE command. Return of 0 -> success, 186 * SG_LIB_CAT_INVALID_OP -> Request Sense not supported??, 187 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_ABORTED_COMMAND, 188 * -1 -> other failure */ 189 int sg_ll_request_sense(int sg_fd, bool desc, void * resp, int mx_resp_len, 190 bool noisy, int verbose); 191 192 /* Similar to sg_ll_request_sense(). See note above about "_pt" suffix. */ 193 int sg_ll_request_sense_pt(struct sg_pt_base * ptp, bool desc, void * resp, 194 int mx_resp_len, bool noisy, int verbose); 195 196 /* Invokes a SCSI START STOP UNIT command (SBC + MMC). 197 * Return of 0 -> success, 198 * SG_LIB_CAT_INVALID_OP -> Start stop unit not supported, 199 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_UNIT_ATTENTION, 200 * SG_LIB_CAT_NOT_READY -> device not ready, SG_LIB_CAT_ABORTED_COMMAND, 201 * -1 -> other failure 202 * SBC-3 and MMC partially overlap on the power_condition_modifier(sbc) and 203 * format_layer_number(mmc) fields. They also overlap on the noflush(sbc) 204 * and fl(mmc) one bit field. This is the cause of the awkardly named 205 * pc_mod__fl_num and noflush__fl arguments to this function. */ 206 int sg_ll_start_stop_unit(int sg_fd, bool immed, int pc_mod__fl_num, 207 int power_cond, bool noflush__fl, bool loej, 208 bool start, bool noisy, int verbose); 209 210 /* Similar to sg_ll_start_stop_unit(). See note above about "_pt" suffix. */ 211 int sg_ll_start_stop_unit_pt(struct sg_pt_base * ptp, bool immed, 212 int pc_mod__fl_num, int power_cond, 213 bool noflush__fl, bool loej, bool start, 214 bool noisy, int verbose); 215 216 /* Invokes a SCSI SYNCHRONIZE CACHE (10) command. Return of 0 -> success, 217 * SG_LIB_CAT_UNIT_ATTENTION, SG_LIB_CAT_ABORTED_COMMAND, 218 * SG_LIB_CAT_INVALID_OP -> cdb not supported, 219 * SG_LIB_CAT_IlLEGAL_REQ -> bad field in cdb 220 * SG_LIB_CAT_NOT_READY -> device not ready, -1 -> other failure */ 221 int sg_ll_sync_cache_10(int sg_fd, bool sync_nv, bool immed, int group, 222 unsigned int lba, unsigned int count, bool noisy, 223 int verbose); 224 225 /* Invokes a SCSI TEST UNIT READY command. 226 * 'pack_id' is just for diagnostics, safe to set to 0. 227 * Return of 0 -> success, SG_LIB_CAT_UNIT_ATTENTION, 228 * SG_LIB_CAT_NOT_READY -> device not ready, 229 * SG_LIB_CAT_ABORTED_COMMAND, -1 -> other failure */ 230 int sg_ll_test_unit_ready(int sg_fd, int pack_id, bool noisy, int verbose); 231 232 /* Similar to sg_ll_test_unit_ready(). See note above about "_pt" suffix. */ 233 int sg_ll_test_unit_ready_pt(struct sg_pt_base * ptp, int pack_id, 234 bool noisy, int verbose); 235 236 /* Invokes a SCSI TEST UNIT READY command. 237 * 'pack_id' is just for diagnostics, safe to set to 0. 238 * Looks for progress indicator if 'progress' non-NULL; 239 * if found writes value [0..65535] else write -1. 240 * Return of 0 -> success, SG_LIB_CAT_UNIT_ATTENTION, 241 * SG_LIB_CAT_ABORTED_COMMAND, SG_LIB_CAT_NOT_READY -> 242 * device not ready, -1 -> other failure */ 243 int sg_ll_test_unit_ready_progress(int sg_fd, int pack_id, int * progress, 244 bool noisy, int verbose); 245 246 /* Similar to sg_ll_test_unit_ready_progress(). See note above about "_pt" 247 * suffix. */ 248 int sg_ll_test_unit_ready_progress_pt(struct sg_pt_base * ptp, int pack_id, 249 int * progress, bool noisy, int verbose); 250 251 252 struct sg_simple_inquiry_resp { 253 uint8_t peripheral_qualifier; 254 uint8_t peripheral_type; 255 uint8_t byte_1; /* was 'rmb' prior to version 1.39 */ 256 /* now rmb == !!(0x80 & byte_1) */ 257 uint8_t version; /* as per recent drafts: whole of byte 2 */ 258 uint8_t byte_3; 259 uint8_t byte_5; 260 uint8_t byte_6; 261 uint8_t byte_7; 262 char vendor[9]; /* T10 field is 8 bytes, NUL char appended */ 263 char product[17]; 264 char revision[5]; 265 }; 266 267 /* Yields most of first 36 bytes of a standard INQUIRY (evpd==0) response. 268 * Returns 0 when successful, SG_LIB_CAT_INVALID_OP -> not supported, 269 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_ABORTED_COMMAND, 270 * a negated errno or -1 -> other errors */ 271 int sg_simple_inquiry(int sg_fd, struct sg_simple_inquiry_resp * inq_data, 272 bool noisy, int verbose); 273 274 /* Similar to sg_simple_inquiry(). See note above about "_pt" suffix. */ 275 int sg_simple_inquiry_pt(struct sg_pt_base * ptvp, 276 struct sg_simple_inquiry_resp * inq_data, bool noisy, 277 int verbose); 278 279 /* MODE SENSE commands yield a response that has header then zero or more 280 * block descriptors followed by mode pages. In most cases users are 281 * interested in the first mode page. This function returns the (byte) 282 * offset of the start of the first mode page. Set mode_sense_6 to true for 283 * MODE SENSE (6) and false for MODE SENSE (10). Returns >= 0 is successful 284 * or -1 if failure. If there is a failure a message is written to err_buff 285 * if it is non-NULL and err_buff_len > 0. */ 286 int sg_mode_page_offset(const uint8_t * resp, int resp_len, 287 bool mode_sense_6, char * err_buff, int err_buff_len); 288 289 /* MODE SENSE commands yield a response that has header then zero or more 290 * block descriptors followed by mode pages. This functions returns the 291 * length (in bytes) of those three components. Note that the return value 292 * can exceed resp_len in which case the MODE SENSE command should be 293 * re-issued with a larger response buffer. If bd_lenp is non-NULL and if 294 * successful the block descriptor length (in bytes) is written to *bd_lenp. 295 * Set mode_sense_6 to true for MODE SENSE (6) and false for MODE SENSE (10) 296 * responses. Returns -1 if there is an error (e.g. response too short). */ 297 int sg_msense_calc_length(const uint8_t * resp, int resp_len, 298 bool mode_sense_6, int * bd_lenp); 299 300 /* Fetches current, changeable, default and/or saveable modes pages as 301 * indicated by pcontrol_arr for given pg_code and sub_pg_code. If 302 * mode6 is true then use MODE SENSE (6) else use MODE SENSE (10). If 303 * flexible true and mode data length seems wrong then try and 304 * fix (compensating hack for bad device or driver). pcontrol_arr 305 * should have 4 elements for output of current, changeable, default 306 * and saved values respectively. Each element should be NULL or 307 * at least mx_mpage_len bytes long. 308 * Return of 0 -> overall success, SG_LIB_CAT_INVALID_OP -> invalid opcode, 309 * SG_LIB_CAT_ILLEGAL_REQ -> bad field in cdb, SG_LIB_CAT_UNIT_ATTENTION, 310 * SG_LIB_CAT_NOT_READY -> device not ready, 311 * SG_LIB_CAT_MALFORMED -> bad response, -1 -> other failure. 312 * If success_mask pointer is not NULL then first zeros it. Then set bits 313 * 0, 1, 2 and/or 3 if the current, changeable, default and saved values 314 * respectively have been fetched. If error on current page 315 * then stops and returns that error; otherwise continues if an error is 316 * detected but returns the first error encountered. */ 317 int sg_get_mode_page_controls(int sg_fd, bool mode6, int pg_code, 318 int sub_pg_code, bool dbd, bool flexible, 319 int mx_mpage_len, int * success_mask, 320 void * pcontrol_arr[], int * reported_lenp, 321 int verbose); 322 323 /* Returns file descriptor >= 0 if successful. If error in Unix returns 324 negated errno. Implementation calls scsi_pt_open_device(). */ 325 int sg_cmds_open_device(const char * device_name, bool read_only, int verbose); 326 327 /* Returns file descriptor >= 0 if successful. If error in Unix returns 328 negated errno. Implementation calls scsi_pt_open_flags(). */ 329 int sg_cmds_open_flags(const char * device_name, int flags, int verbose); 330 331 /* Returns 0 if successful. If error in Unix returns negated errno. 332 Implementation calls scsi_pt_close_device(). */ 333 int sg_cmds_close_device(int device_fd); 334 335 const char * sg_cmds_version(); 336 337 #define SG_NO_DATA_IN 0 338 339 340 /* This is a helper function used by sg_cmds_* implementations after the 341 * call to the pass-through. pt_res is returned from do_scsi_pt(). If valid 342 * sense data is found it is decoded and output to sg_warnings_strm (def: 343 * stderr); depending on the 'noisy' and 'verbose' settings. Returns -2 for 344 * sense data (may not be fatal), -1 for failed, 0, or a positive number. If 345 * 'mx_di_len > 0' then asks pass-through for resid and returns 346 * (mx_di_len - resid); otherwise returns 0. So for data-in it should return 347 * the actual number of bytes received. For data-out (to device) or no data 348 * call with 'mx_di_len' set to 0 or less. If -2 returned then sense category 349 * output via 'o_sense_cat' pointer (if not NULL). Note that several sense 350 * categories also have data in bytes received; -2 is still returned. */ 351 int sg_cmds_process_resp(struct sg_pt_base * ptvp, const char * leadin, 352 int pt_res, bool noisy, int verbose, 353 int * o_sense_cat); 354 355 /* NVMe devices use a different command set. This function will return true 356 * if the device associated with 'pvtp' is a NVME device, else it will 357 * return false (e.g. for SCSI devices). */ 358 bool sg_cmds_is_nvme(const struct sg_pt_base * ptvp); 359 360 #ifdef __cplusplus 361 } 362 #endif 363 364 #endif 365