1 #ifndef SG_PT_H 2 #define SG_PT_H 3 4 /* 5 * Copyright (c) 2005-2021 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 #include <stdint.h> 14 #include <stdbool.h> 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /* This declaration hides the fact that each implementation has its own 21 * structure "derived" (using a C++ term) from this one. It compiles 22 * because 'struct sg_pt_base' is only referenced (by pointer: 'objp') 23 * in this interface. An instance of this structure represents the 24 * context of one synchronous SCSI (or NVME) command and the context 25 * can be re-used. If an instance of sg_pt_base is shared across several 26 * threads then it is up to the application to take care of multi-threaded 27 * issues with that instance. */ 28 struct sg_pt_base; 29 30 31 /* The format of the version string is like this: "3.04 20180213". 32 * The leading digit will be incremented if this interface changes 33 * in a way that may impact backward compatibility. */ 34 const char * scsi_pt_version(); 35 const char * sg_pt_version(); /* both functions give same result */ 36 37 38 /* Returns file descriptor or file handle and is >= 0 if successful. 39 * If error in Unix returns negated errno. */ 40 int scsi_pt_open_device(const char * device_name, bool read_only, 41 int verbose); 42 43 /* Similar to scsi_pt_open_device() but takes Unix style open flags OR-ed 44 * together. Returns valid file descriptor or handle ( >= 0 ) if successful, 45 * otherwise returns -1 or a negated errno. 46 * In Win32 O_EXCL translated to equivalent. */ 47 int scsi_pt_open_flags(const char * device_name, int flags, int verbose); 48 49 /* Returns 0 if successful. 'device_fd' should be a value that was previously 50 * returned by scsi_pt_open_device() or scsi_pt_open_flags() that has not 51 * already been closed. If error in Unix returns negated errno. */ 52 int scsi_pt_close_device(int device_fd); 53 54 /* Assumes dev_fd is an "open" file handle associated with device_name. If 55 * the implementation (possibly for one OS) cannot determine from dev_fd if 56 * a SCSI or NVMe pass-through is referenced, then it might guess based on 57 * device_name. Returns 1 if SCSI generic pass-though device, returns 2 if 58 * secondary SCSI pass-through device (in Linux a bsg device); returns 3 is 59 * char NVMe device (i.e. no NSID); returns 4 if block NVMe device (includes 60 * NSID), 5 is also a NVMe device (FreeBSD CAM NVMe (e.g. /dev/nda0)) or 0 61 * if something else (e.g. ATA block device) or dev_fd < 0. 62 * The return value differs somewhat by OS. 63 * If error, returns negated errno (operating system) value. */ 64 int check_pt_file_handle(int dev_fd, const char * device_name, int verbose); 65 66 67 /* Creates an object that can be used to issue one or more SCSI commands 68 * (or task management functions). Returns NULL if problem. 69 * Once this object has been created it should be destroyed with 70 * destruct_scsi_pt_obj() when it is no longer needed. */ 71 struct sg_pt_base * construct_scsi_pt_obj(void); 72 73 /* An alternate and preferred way to create an object that can be used to 74 * issue one or more SCSI (or NVMe) commands (or task management functions). 75 * This variant associates a device file descriptor (handle) with the object 76 * and a verbose argument that causes messages to be written to stderr if 77 * errors occur. The reason for this is to optionally allow the detection of 78 * NVMe devices that will cause pt_device_is_nvme() to return true. Set 79 * dev_fd to -1 if no open device file descriptor is available. Caller 80 * should additionally call get_scsi_pt_os_err() after this call to check 81 * for errors. The dev_fd argument may be -1 to indicate no device file 82 * descriptor. */ 83 struct sg_pt_base * 84 construct_scsi_pt_obj_with_fd(int dev_fd, int verbose); 85 86 /* Forget any previous dev_fd and install the one given. May attempt to 87 * find file type (e.g. if pass-though) from OS so there could be an error. 88 * Returns 0 for success or the same value as get_scsi_pt_os_err() 89 * will return. dev_fd should be >= 0 for a valid file handle or -1 . */ 90 int set_pt_file_handle(struct sg_pt_base * objp, int dev_fd, int verbose); 91 92 /* Valid file handles (which is the return value) are >= 0 . Returns -1 93 * if there is no valid file handle. */ 94 int get_pt_file_handle(const struct sg_pt_base * objp); 95 96 /* Clear state information held in *objp . This allows this object to be 97 * used to issue more than one SCSI command. The dev_fd is remembered. 98 * Use set_pt_file_handle() to change dev_fd. */ 99 void clear_scsi_pt_obj(struct sg_pt_base * objp); 100 101 /* Partially clear state information held in *objp . Any error settings and 102 * the data-in and data-out settings are cleared. So dev_fd, cdb and sense 103 * settings are kept. */ 104 void partial_clear_scsi_pt_obj(struct sg_pt_base * objp); 105 106 /* Set the CDB (command descriptor block). May also be a NVMe Admin command 107 * which will be 64 bytes long. 108 * 109 * Note that the sg_cmds_is_nvme() function found in sg_cmds_basic.h can be 110 * called after this function to "guess" which command set the given command 111 * belongs to. It is valid to supply a cdb value of NULL. */ 112 void set_scsi_pt_cdb(struct sg_pt_base * objp, const uint8_t * cdb, 113 int cdb_len); 114 115 /* Set the sense buffer and the maximum length of that buffer. For NVMe 116 * commands this "sense" buffer will receive the 4 DWORDs of from the 117 * completion queue. It is valid to supply a sense value of NULL. */ 118 void set_scsi_pt_sense(struct sg_pt_base * objp, uint8_t * sense, 119 int max_sense_len); 120 121 /* Set a pointer and length to be used for data transferred from device */ 122 void set_scsi_pt_data_in(struct sg_pt_base * objp, /* from device */ 123 uint8_t * dxferp, int dxfer_ilen); 124 125 /* Set a pointer and length to be used for data transferred to device */ 126 void set_scsi_pt_data_out(struct sg_pt_base * objp, /* to device */ 127 const uint8_t * dxferp, int dxfer_olen); 128 129 /* Set a pointer and length to be used for metadata transferred to 130 * (out_true=true) or from (out_true=false) device (NVMe only) */ 131 void set_pt_metadata_xfer(struct sg_pt_base * objp, uint8_t * mdxferp, 132 uint32_t mdxfer_len, bool out_true); 133 134 /* The following "set_"s implementations may be dummies */ 135 void set_scsi_pt_packet_id(struct sg_pt_base * objp, int pack_id); 136 void set_scsi_pt_tag(struct sg_pt_base * objp, uint64_t tag); 137 void set_scsi_pt_task_management(struct sg_pt_base * objp, int tmf_code); 138 void set_scsi_pt_task_attr(struct sg_pt_base * objp, int attribute, 139 int priority); 140 141 /* Following is a guard which is defined when set_scsi_pt_flags() is 142 * present. Older versions of this library may not have this function. */ 143 #define SCSI_PT_FLAGS_FUNCTION 1 144 /* If neither QUEUE_AT_HEAD nor QUEUE_AT_TAIL are given, or both 145 * are given, use the pass-through default. */ 146 #define SCSI_PT_FLAGS_QUEUE_AT_TAIL 0x10 147 #define SCSI_PT_FLAGS_QUEUE_AT_HEAD 0x20 148 /* Set (potentially OS dependent) flags for pass-through mechanism. 149 * Apart from contradictions, flags can be OR-ed together. */ 150 void set_scsi_pt_flags(struct sg_pt_base * objp, int flags); 151 152 #define SCSI_PT_DO_START_OK 0 153 #define SCSI_PT_DO_BAD_PARAMS 1 154 #define SCSI_PT_DO_TIMEOUT 2 155 #define SCSI_PT_DO_NOT_SUPPORTED 4 156 #define SCSI_PT_DO_NVME_STATUS 48 /* == SG_LIB_NVME_STATUS */ 157 /* If OS error prior to or during command submission then returns negated 158 * error value (e.g. Unix '-errno'). This includes interrupted system calls 159 * (e.g. by a signal) in which case -EINTR would be returned. Note that 160 * system call errors also can be fetched with get_scsi_pt_os_err(). 161 * Return 0 if okay (i.e. at the very least: command sent). Positive 162 * return values are errors (see SCSI_PT_DO_* defines). If a file descriptor 163 * has already been provided by construct_scsi_pt_obj_with_fd() then the 164 * given 'fd' can be -1 or the same value as given to the constructor. */ 165 int do_scsi_pt(struct sg_pt_base * objp, int fd, int timeout_secs, 166 int verbose); 167 168 /* NVMe Admin commands can be sent directly to do_scsi_pt(). Unfortunately 169 * NVMe has at least one other command set: "NVM" to access user data and 170 * the opcodes in the NVM command set overlap with the Admin command set. 171 * So NVMe Admin commands should be sent do_scsi_pt() while NVMe "NVM" 172 * commands should be sent to this function. No SCSI commands should be 173 * sent to this function. Currently submq is not implemented and all 174 * submitted NVM commands are sent on queue 0, the same queue use for 175 * Admin commands. The return values follow the same pattern as do_scsi_pt(), 176 * with 0 returned being good. The NVMe device file descriptor must either 177 * be given to the obj constructor, or a prior set_pt_file_handle() call. */ 178 int do_nvm_pt(struct sg_pt_base * objp, int submq, int timeout_secs, 179 int verbose); 180 181 #define SCSI_PT_RESULT_GOOD 0 182 #define SCSI_PT_RESULT_STATUS 1 /* other than GOOD and CHECK CONDITION */ 183 #define SCSI_PT_RESULT_SENSE 2 184 #define SCSI_PT_RESULT_TRANSPORT_ERR 3 185 #define SCSI_PT_RESULT_OS_ERR 4 186 /* This function, called soon after do_scsi_pt(), returns one of the above 187 * result categories. The highest numbered applicable category is returned. 188 * 189 * Note that the sg_cmds_process_resp() function found in sg_cmds_basic.h 190 * is useful for processing SCSI command responses. 191 * And the sg_cmds_is_nvme() function found in sg_cmds_basic.h can be called 192 * after set_scsi_pt_cdb() to "guess" which command set the given command 193 * belongs to. */ 194 int get_scsi_pt_result_category(const struct sg_pt_base * objp); 195 196 /* If not available return 0 which implies there is no residual value. If 197 * supported it is the number of bytes requested to transfer less the 198 * number actually transferred. This it typically important for data-in 199 * transfers. For data-out (only) transfers, the 'dout_req_len - 200 * dout_act_len' is returned. For bidi transfer the data-in residual is 201 * returned. */ 202 int get_scsi_pt_resid(const struct sg_pt_base * objp); 203 204 /* Returns SCSI status value (from device that received the command). If an 205 * NVMe command was issued directly (i.e. through do_scsi_pt() then return 206 * NVMe status (i.e. ((SCT << 8) | SC)). If problem returns -1. */ 207 int get_scsi_pt_status_response(const struct sg_pt_base * objp); 208 209 /* Returns SCSI status value or, if NVMe command given to do_scsi_pt(), 210 * then returns NVMe result (i.e. DWord(0) from completion queue). If 211 * 'objp' is NULL then returns 0xffffffff. */ 212 uint32_t get_pt_result(const struct sg_pt_base * objp); 213 214 /* These two get functions should just echo what has been given to 215 * set_scsi_pt_cdb(). If it has not been called or clear_scsi_pt_obj() 216 * has been called then they return 0 and NULL respectively. */ 217 int get_scsi_pt_cdb_len(const struct sg_pt_base * objp); 218 uint8_t * get_scsi_pt_cdb_buf(const struct sg_pt_base * objp); 219 220 /* Actual sense length returned. If sense data is present but 221 actual sense length is not known, return 'max_sense_len' */ 222 int get_scsi_pt_sense_len(const struct sg_pt_base * objp); 223 uint8_t * get_scsi_pt_sense_buf(const struct sg_pt_base * objp); 224 225 /* If not available return 0 (for success). */ 226 int get_scsi_pt_os_err(const struct sg_pt_base * objp); 227 char * get_scsi_pt_os_err_str(const struct sg_pt_base * objp, int max_b_len, 228 char * b); 229 230 /* If not available return 0 (for success) */ 231 int get_scsi_pt_transport_err(const struct sg_pt_base * objp); 232 void set_scsi_pt_transport_err(struct sg_pt_base * objp, int err); 233 char * get_scsi_pt_transport_err_str(const struct sg_pt_base * objp, 234 int max_b_len, char * b); 235 236 /* If not available return -1 otherwise return number of milliseconds 237 * that the lower layers (and hardware) took to execute the previous 238 * command. */ 239 int get_scsi_pt_duration_ms(const struct sg_pt_base * objp); 240 241 /* If not available return 0 otherwise return number of nanoseconds that the 242 * lower layers (and hardware) took to execute the command just completed. */ 243 uint64_t get_pt_duration_ns(const struct sg_pt_base * objp); 244 245 /* The two functions yield requested and actual data transfer lengths in 246 * bytes. The second argument is a pointer to the data-in length; the third 247 * argument is a pointer to the data-out length. The pointers may be NULL. 248 * The _actual_ values are related to resid (residual count from DMA) */ 249 void get_pt_req_lengths(const struct sg_pt_base * objp, int * req_dinp, 250 int * req_doutp); 251 void get_pt_actual_lengths(const struct sg_pt_base * objp, int * act_dinp, 252 int * act_doutp); 253 254 /* Return true if device associated with 'objp' uses NVMe command set. To 255 * be useful (in modifying the type of command sent (SCSI or NVMe) then 256 * construct_scsi_pt_obj_with_fd() should be used followed by an invocation 257 * of this function. */ 258 bool pt_device_is_nvme(const struct sg_pt_base * objp); 259 260 /* If a NVMe block device (which includes the NSID) handle is associated 261 * with 'objp', then its NSID is returned (values range from 0x1 to 262 * 0xffffffe). Otherwise 0 is returned. */ 263 uint32_t get_pt_nvme_nsid(const struct sg_pt_base * objp); 264 265 266 /* Should be invoked once per objp after other processing is complete in 267 * order to clean up resources. For ever successful construct_scsi_pt_obj() 268 * call there should be one destruct_scsi_pt_obj(). If the 269 * construct_scsi_pt_obj_with_fd() function was used to create this object 270 * then the dev_fd provided to that constructor is not altered by this 271 * destructor. So the user should still close dev_fd (perhaps with 272 * scsi_pt_close_device() ). */ 273 void destruct_scsi_pt_obj(struct sg_pt_base * objp); 274 275 #ifdef SG_LIB_WIN32 276 #define SG_LIB_WIN32_DIRECT 1 277 278 /* Request SPT direct interface when state_direct is 1, state_direct set 279 * to 0 for the SPT indirect interface. Default setting selected by build 280 * (i.e. library compile time) and is usually indirect. */ 281 void scsi_pt_win32_direct(int state_direct); 282 283 /* Returns current SPT interface state, 1 for direct, 0 for indirect */ 284 int scsi_pt_win32_spt_state(void); 285 286 #endif 287 288 #ifdef __cplusplus 289 } 290 #endif 291 292 #endif /* SG_PT_H */ 293