sys/cam/cam.h

   1 /*-
   2  * Data structures and definitions for the CAM system.
   3  *
   4  * SPDX-License-Identifier: BSD-2-Clause
   5  *
   6  * Copyright (c) 1997 Justin T. Gibbs.
   7  * All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions
  11  * are met:
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions, and the following disclaimer,
  14  *    without modification, immediately at the beginning of the file.
  15  * 2. The name of the author may not be used to endorse or promote products
  16  *    derived from this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
  22  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28  * SUCH DAMAGE.
  29  */
  30
  31 #ifndef _CAM_CAM_H
  32 #define _CAM_CAM_H 1
  33
  34 #ifdef _KERNEL
  35 #include "opt_cam.h"
  36 #endif
  37
  38 #include <sys/cdefs.h>
  39 #ifndef _KERNEL
  40 #include <stdbool.h>
  41 #endif
  42
  43 typedef u_int path_id_t;
  44 typedef u_int target_id_t;
  45 typedef uint64_t lun_id_t;
  46
  47 #define CAM_XPT_PATH_ID ((path_id_t)~0)
  48 #define CAM_BUS_WILDCARD ((path_id_t)~0)
  49 #define CAM_TARGET_WILDCARD ((target_id_t)~0)
  50 #define CAM_LUN_WILDCARD (~(u_int)0)
  51
  52 #define CAM_EXTLUN_BYTE_SWIZZLE(lun) (  \
  53         ((((uint64_t)lun) & 0xffff000000000000L) >> 48) | \
  54         ((((uint64_t)lun) & 0x0000ffff00000000L) >> 16) | \
  55         ((((uint64_t)lun) & 0x00000000ffff0000L) << 16) | \
  56         ((((uint64_t)lun) & 0x000000000000ffffL) << 48))
  57
  58 /*
  59  * Maximum length for a CAM CDB.
  60  */
  61 #define CAM_MAX_CDBLEN 16
  62
  63 /*
  64  * Definition of a CAM peripheral driver entry.  Peripheral drivers instantiate
  65  * one of these for each device they wish to communicate with and pass it into
  66  * the xpt layer when they wish to schedule work on that device via the
  67  * xpt_schedule API.
  68  */
  69 struct cam_periph;
  70
  71 /*
  72  * Priority information for a CAM structure.
  73  */
  74 typedef enum {
  75     CAM_RL_HOST,
  76     CAM_RL_BUS,
  77     CAM_RL_XPT,
  78     CAM_RL_DEV,
  79     CAM_RL_NORMAL,
  80     CAM_RL_VALUES
  81 } cam_rl;
  82 /*
  83  * The generation number is incremented every time a new entry is entered into
  84  * the queue giving round robin per priority level scheduling.
  85  */
  86 typedef struct {
  87         uint32_t priority;
  88 #define CAM_PRIORITY_HOST       ((CAM_RL_HOST << 8) + 0x80)
  89 #define CAM_PRIORITY_BUS        ((CAM_RL_BUS << 8) + 0x80)
  90 #define CAM_PRIORITY_XPT        ((CAM_RL_XPT << 8) + 0x80)
  91 #define CAM_PRIORITY_DEV        ((CAM_RL_DEV << 8) + 0x80)
  92 #define CAM_PRIORITY_OOB        (CAM_RL_DEV << 8)
  93 #define CAM_PRIORITY_NORMAL     ((CAM_RL_NORMAL << 8) + 0x80)
  94 #define CAM_PRIORITY_NONE       (uint32_t)-1
  95         uint32_t generation;
  96         int       index;
  97 #define CAM_UNQUEUED_INDEX      -1
  98 #define CAM_ACTIVE_INDEX        -2
  99 #define CAM_DONEQ_INDEX         -3
 100 #define CAM_ASYNC_INDEX         -4
 101 #define CAM_EXTRAQ_INDEX        INT_MAX
 102 } cam_pinfo;
 103
 104 /*
 105  * Macro to compare two generation numbers.  It is used like this:
 106  *
 107  *      if (GENERATIONCMP(a, >=, b))
 108  *              ...;
 109  *
 110  * GERERATIONCMP uses modular arithmetic to guard against wraps
 111  * wraps in the generation number.
 112  */
 113 #define GENERATIONCMP(x, op, y) ((int32_t)((x) - (y)) op 0)
 114
 115 /* CAM flags XXX Move to cam_periph.h ??? */
 116 typedef enum {
 117         CAM_FLAG_NONE           = 0x00,
 118         CAM_EXPECT_INQ_CHANGE   = 0x01,
 119         CAM_RETRY_SELTO         = 0x02 /* Retry Selection Timeouts */
 120 } cam_flags;
 121
 122 enum {
 123         SF_RETRY_UA             = 0x01, /* Retry UNIT ATTENTION conditions. */
 124         SF_NO_PRINT             = 0x02, /* Never print error status. */
 125         SF_QUIET_IR             = 0x04, /* Be quiet about Illegal Request responses */
 126         SF_PRINT_ALWAYS         = 0x08, /* Always print error status. */
 127         SF_NO_RECOVERY          = 0x10, /* Don't do active error recovery. */
 128         SF_NO_RETRY             = 0x20, /* Don't do any retries. */
 129         SF_RETRY_BUSY           = 0x40  /* Retry BUSY status. */
 130 };
 131
 132 /* CAM  Status field values */
 133 typedef enum {
 134         /* CCB request is in progress */
 135         CAM_REQ_INPROG          = 0x00,
 136
 137         /* CCB request completed without error */
 138         CAM_REQ_CMP             = 0x01,
 139
 140         /* CCB request aborted by the host */
 141         CAM_REQ_ABORTED         = 0x02,
 142
 143         /* Unable to abort CCB request */
 144         CAM_UA_ABORT            = 0x03,
 145
 146         /* CCB request completed with an error */
 147         CAM_REQ_CMP_ERR         = 0x04,
 148
 149         /* CAM subsystem is busy */
 150         CAM_BUSY                = 0x05,
 151
 152         /* CCB request was invalid */
 153         CAM_REQ_INVALID         = 0x06,
 154
 155         /* Supplied Path ID is invalid */
 156         CAM_PATH_INVALID        = 0x07,
 157
 158         /* SCSI Device Not Installed/there */
 159         CAM_DEV_NOT_THERE       = 0x08,
 160
 161         /* Unable to terminate I/O CCB request */
 162         CAM_UA_TERMIO           = 0x09,
 163
 164         /* Target Selection Timeout */
 165         CAM_SEL_TIMEOUT         = 0x0a,
 166
 167         /* Command timeout */
 168         CAM_CMD_TIMEOUT         = 0x0b,
 169
 170         /* SCSI error, look at error code in CCB */
 171         CAM_SCSI_STATUS_ERROR   = 0x0c,
 172
 173         /* Message Reject Received */
 174         CAM_MSG_REJECT_REC      = 0x0d,
 175
 176         /* SCSI Bus Reset Sent/Received */
 177         CAM_SCSI_BUS_RESET      = 0x0e,
 178
 179         /* Uncorrectable parity error occurred */
 180         CAM_UNCOR_PARITY        = 0x0f,
 181
 182         /* Autosense: request sense cmd fail */
 183         CAM_AUTOSENSE_FAIL      = 0x10,
 184
 185         /* No HBA Detected error */
 186         CAM_NO_HBA              = 0x11,
 187
 188         /* Data Overrun error */
 189         CAM_DATA_RUN_ERR        = 0x12,
 190
 191         /* Unexpected Bus Free */
 192         CAM_UNEXP_BUSFREE       = 0x13,
 193
 194         /* Target Bus Phase Sequence Failure */
 195         CAM_SEQUENCE_FAIL       = 0x14,
 196
 197         /* CCB length supplied is inadequate */
 198         CAM_CCB_LEN_ERR         = 0x15,
 199
 200         /* Unable to provide requested capability*/
 201         CAM_PROVIDE_FAIL        = 0x16,
 202
 203         /* A SCSI BDR msg was sent to target */
 204         CAM_BDR_SENT            = 0x17,
 205
 206         /* CCB request terminated by the host */
 207         CAM_REQ_TERMIO          = 0x18,
 208
 209         /* Unrecoverable Host Bus Adapter Error */
 210         CAM_UNREC_HBA_ERROR     = 0x19,
 211
 212         /* Request was too large for this host */
 213         CAM_REQ_TOO_BIG         = 0x1a,
 214
 215         /*
 216          * This request should be requeued to preserve
 217          * transaction ordering.  This typically occurs
 218          * when the SIM recognizes an error that should
 219          * freeze the queue and must place additional
 220          * requests for the target at the sim level
 221          * back into the XPT queue.
 222          */
 223         CAM_REQUEUE_REQ         = 0x1b,
 224
 225         /* ATA error, look at error code in CCB */
 226         CAM_ATA_STATUS_ERROR    = 0x1c,
 227
 228         /* Initiator/Target Nexus lost. */
 229         CAM_SCSI_IT_NEXUS_LOST  = 0x1d,
 230
 231         /* SMP error, look at error code in CCB */
 232         CAM_SMP_STATUS_ERROR    = 0x1e,
 233
 234         /*
 235          * Command completed without error but  exceeded the soft
 236          * timeout threshold.
 237          */
 238         CAM_REQ_SOFTTIMEOUT     = 0x1f,
 239
 240         /*
 241          * NVME error, look at errro code in CCB
 242          */
 243         CAM_NVME_STATUS_ERROR   = 0x20,
 244
 245         /*
 246          * 0x21 - 0x32 are unassigned
 247          */
 248
 249         /* Initiator Detected Error */
 250         CAM_IDE                 = 0x33,
 251
 252         /* Resource Unavailable */
 253         CAM_RESRC_UNAVAIL       = 0x34,
 254
 255         /* Unacknowledged Event by Host */
 256         CAM_UNACKED_EVENT       = 0x35,
 257
 258         /* Message Received in Host Target Mode */
 259         CAM_MESSAGE_RECV        = 0x36,
 260
 261         /* Invalid CDB received in Host Target Mode */
 262         CAM_INVALID_CDB         = 0x37,
 263
 264         /* Lun supplied is invalid */
 265         CAM_LUN_INVALID         = 0x38,
 266
 267         /* Target ID supplied is invalid */
 268         CAM_TID_INVALID         = 0x39,
 269
 270         /* The requested function is not available */
 271         CAM_FUNC_NOTAVAIL       = 0x3a,
 272
 273         /* Nexus is not established */
 274         CAM_NO_NEXUS            = 0x3b,
 275
 276         /* The initiator ID is invalid */
 277         CAM_IID_INVALID         = 0x3c,
 278
 279         /* The SCSI CDB has been received */
 280         CAM_CDB_RECVD           = 0x3d,
 281
 282         /* The LUN is already enabled for target mode */
 283         CAM_LUN_ALRDY_ENA       = 0x3e,
 284
 285         /* SCSI Bus Busy */
 286         CAM_SCSI_BUSY           = 0x3f,
 287
 288         /*
 289          * Flags
 290          */
 291
 292         /* The DEV queue is frozen w/this err */
 293         CAM_DEV_QFRZN           = 0x40,
 294
 295         /* Autosense data valid for target */
 296         CAM_AUTOSNS_VALID       = 0x80,
 297
 298         /* SIM ready to take more commands */
 299         CAM_RELEASE_SIMQ        = 0x100,
 300
 301         /* SIM has this command in its queue */
 302         CAM_SIM_QUEUED          = 0x200,
 303
 304         /* Quality of service data is valid */
 305         CAM_QOS_VALID           = 0x400,
 306
 307         /* Mask bits for just the status # */
 308         CAM_STATUS_MASK = 0x3F,
 309
 310         /*
 311          * Target Specific Adjunct Status
 312          */
 313
 314         /* sent sense with status */
 315         CAM_SENT_SENSE          = 0x40000000
 316 } cam_status;
 317
 318 typedef enum {
 319         CAM_ESF_NONE            = 0x00,
 320         CAM_ESF_COMMAND         = 0x01,
 321         CAM_ESF_CAM_STATUS      = 0x02,
 322         CAM_ESF_PROTO_STATUS    = 0x04,
 323         CAM_ESF_ALL             = 0xff
 324 } cam_error_string_flags;
 325
 326 typedef enum {
 327         CAM_EPF_NONE            = 0x00,
 328         CAM_EPF_MINIMAL         = 0x01,
 329         CAM_EPF_NORMAL          = 0x02,
 330         CAM_EPF_ALL             = 0x03,
 331         CAM_EPF_LEVEL_MASK      = 0x0f
 332         /* All bits above bit 3 are protocol-specific */
 333 } cam_error_proto_flags;
 334
 335 typedef enum {
 336         CAM_ESF_PRINT_NONE      = 0x00,
 337         CAM_ESF_PRINT_STATUS    = 0x10,
 338         CAM_ESF_PRINT_SENSE     = 0x20
 339 } cam_error_scsi_flags;
 340
 341 typedef enum {
 342         CAM_ESMF_PRINT_NONE     = 0x00,
 343         CAM_ESMF_PRINT_STATUS   = 0x10,
 344         CAM_ESMF_PRINT_FULL_CMD = 0x20,
 345 } cam_error_smp_flags;
 346
 347 typedef enum {
 348         CAM_EAF_PRINT_NONE      = 0x00,
 349         CAM_EAF_PRINT_STATUS    = 0x10,
 350         CAM_EAF_PRINT_RESULT    = 0x20
 351 } cam_error_ata_flags;
 352
 353 typedef enum {
 354         CAM_STRVIS_FLAG_NONE            = 0x00,
 355         CAM_STRVIS_FLAG_NONASCII_MASK   = 0x03,
 356         CAM_STRVIS_FLAG_NONASCII_TRIM   = 0x00,
 357         CAM_STRVIS_FLAG_NONASCII_RAW    = 0x01,
 358         CAM_STRVIS_FLAG_NONASCII_SPC    = 0x02,
 359         CAM_STRVIS_FLAG_NONASCII_ESC    = 0x03
 360 } cam_strvis_flags;
 361
 362 struct cam_status_entry
 363 {
 364         cam_status  status_code;
 365         const char *status_text;
 366 };
 367
 368 extern const struct cam_status_entry cam_status_table[];
 369 extern const int num_cam_status_entries;
 370 #ifdef _KERNEL
 371 extern int cam_sort_io_queues;
 372 #endif
 373 union ccb;
 374 struct sbuf;
 375
 376 #ifdef SYSCTL_DECL      /* from sysctl.h */
 377 SYSCTL_DECL(_kern_cam);
 378 #endif
 379
 380 __BEGIN_DECLS
 381 typedef int (cam_quirkmatch_t)(caddr_t, caddr_t);
 382
 383 caddr_t cam_quirkmatch(caddr_t target, caddr_t quirk_table, int num_entries,
 384                        int entry_size, cam_quirkmatch_t *comp_func);
 385
 386 void    cam_strvis(uint8_t *dst, const uint8_t *src, int srclen, int dstlen);
 387 void    cam_strvis_flag(uint8_t *dst, const uint8_t *src, int srclen,
 388                         int dstlen, uint32_t flags);
 389 void    cam_strvis_sbuf(struct sbuf *sb, const uint8_t *src, int srclen,
 390                         uint32_t flags);
 391
 392 int     cam_strmatch(const uint8_t *str, const uint8_t *pattern, int str_len);
 393 const struct cam_status_entry*
 394         cam_fetch_status_entry(cam_status status);
 395 #ifdef _KERNEL
 396 char *  cam_error_string(union ccb *ccb, char *str, int str_len,
 397                          cam_error_string_flags flags,
 398                          cam_error_proto_flags proto_flags);
 399 void    cam_error_print(union ccb *ccb, cam_error_string_flags flags,
 400                         cam_error_proto_flags proto_flags);
 401 #else /* _KERNEL */
 402 struct cam_device;
 403
 404 char *  cam_error_string(struct cam_device *device, union ccb *ccb, char *str,
 405                          int str_len, cam_error_string_flags flags,
 406                          cam_error_proto_flags proto_flags);
 407 void    cam_error_print(struct cam_device *device, union ccb *ccb,
 408                         cam_error_string_flags flags,
 409                         cam_error_proto_flags proto_flags, FILE *ofile);
 410 #endif /* _KERNEL */
 411 __END_DECLS
 412
 413 #ifdef _KERNEL
 414 static __inline void cam_init_pinfo(cam_pinfo *pinfo)
 415 {
 416         pinfo->priority = CAM_PRIORITY_NONE;
 417         pinfo->index = CAM_UNQUEUED_INDEX;
 418 }
 419 #endif
 420
 421 #endif /* _CAM_CAM_H */