/*-
 * Data structures and definitions for the CAM system.
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * Copyright (c) 1997 Justin T. Gibbs.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions, and the following disclaimer,
 *    without modification, immediately at the beginning of the file.
 * 2. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef _CAM_CAM_H
#define _CAM_CAM_H 1

#ifdef _KERNEL
#include "opt_cam.h"
/* Only need the hooks here so no opt_kdtrace.h */
#include <sys/queue.h>
#include <sys/sdt.h>
#endif

#ifndef _KERNEL
#include <stdbool.h>
#include <stdio.h>
#endif

typedef u_int path_id_t;
typedef u_int target_id_t;
typedef uint64_t lun_id_t;

#define CAM_XPT_PATH_ID ((path_id_t)~0)
#define CAM_BUS_WILDCARD ((path_id_t)~0)
#define CAM_TARGET_WILDCARD ((target_id_t)~0)
#define CAM_LUN_WILDCARD (~(u_int)0)

#define CAM_EXTLUN_BYTE_SWIZZLE(lun) (  \
        ((((uint64_t)lun) & 0xffff000000000000L) >> 48) | \
        ((((uint64_t)lun) & 0x0000ffff00000000L) >> 16) | \
        ((((uint64_t)lun) & 0x00000000ffff0000L) << 16) | \
        ((((uint64_t)lun) & 0x000000000000ffffL) << 48))

/*
 * Maximum length for a CAM CDB.  
 */
#define CAM_MAX_CDBLEN 16

/*
 * Definition of a CAM peripheral driver entry.  Peripheral drivers instantiate
 * one of these for each device they wish to communicate with and pass it into
 * the xpt layer when they wish to schedule work on that device via the
 * xpt_schedule API.
 */
struct cam_periph;

/*
 * Priority information for a CAM structure. 
 */
typedef enum {
    CAM_RL_HOST,
    CAM_RL_BUS,
    CAM_RL_XPT,
    CAM_RL_DEV,
    CAM_RL_NORMAL,
    CAM_RL_VALUES
} cam_rl;
/*
 * The generation number is incremented every time a new entry is entered into
 * the queue giving round robin per priority level scheduling.
 */
typedef struct {
        uint32_t priority;
#define CAM_PRIORITY_HOST       ((CAM_RL_HOST << 8) + 0x80)
#define CAM_PRIORITY_BUS        ((CAM_RL_BUS << 8) + 0x80)
#define CAM_PRIORITY_XPT        ((CAM_RL_XPT << 8) + 0x80)
#define CAM_PRIORITY_DEV        ((CAM_RL_DEV << 8) + 0x80)
#define CAM_PRIORITY_OOB        (CAM_RL_DEV << 8)
#define CAM_PRIORITY_NORMAL     ((CAM_RL_NORMAL << 8) + 0x80)
#define CAM_PRIORITY_NONE       (uint32_t)-1
        uint32_t generation;
        int       index;
#define CAM_UNQUEUED_INDEX      -1
#define CAM_ACTIVE_INDEX        -2
#define CAM_DONEQ_INDEX         -3
#define CAM_ASYNC_INDEX         -4
#define CAM_EXTRAQ_INDEX        INT_MAX
} cam_pinfo;

/*
 * Macro to compare two generation numbers.  It is used like this:  
 *
 *      if (GENERATIONCMP(a, >=, b))
 *              ...;
 *
 * GERERATIONCMP uses modular arithmetic to guard against wraps
 * wraps in the generation number.
 */
#define GENERATIONCMP(x, op, y) ((int32_t)((x) - (y)) op 0)

/* CAM flags XXX Move to cam_periph.h ??? */
typedef enum {
        CAM_FLAG_NONE           = 0x00,
        CAM_EXPECT_INQ_CHANGE   = 0x01,
        CAM_RETRY_SELTO         = 0x02 /* Retry Selection Timeouts */
} cam_flags;

enum {
        SF_RETRY_UA             = 0x01, /* Retry UNIT ATTENTION conditions. */
        SF_NO_PRINT             = 0x02, /* Never print error status. */
        SF_QUIET_IR             = 0x04, /* Be quiet about Illegal Request responses */
        SF_PRINT_ALWAYS         = 0x08, /* Always print error status. */
        SF_NO_RECOVERY          = 0x10, /* Don't do active error recovery. */
        SF_NO_RETRY             = 0x20, /* Don't do any retries. */
        SF_RETRY_BUSY           = 0x40  /* Retry BUSY status. */
};

/* CAM  Status field values */
typedef enum {
        /* CCB request is in progress */
        CAM_REQ_INPROG          = 0x00,

        /* CCB request completed without error */
        CAM_REQ_CMP             = 0x01,

        /* CCB request aborted by the host */
        CAM_REQ_ABORTED         = 0x02,

        /* Unable to abort CCB request */
        CAM_UA_ABORT            = 0x03,

        /* CCB request completed with an error */
        CAM_REQ_CMP_ERR         = 0x04,

        /* CAM subsystem is busy */
        CAM_BUSY                = 0x05,

        /* CCB request was invalid */
        CAM_REQ_INVALID         = 0x06,

        /* Supplied Path ID is invalid */
        CAM_PATH_INVALID        = 0x07,

        /* SCSI Device Not Installed/there */
        CAM_DEV_NOT_THERE       = 0x08,

        /* Unable to terminate I/O CCB request */
        CAM_UA_TERMIO           = 0x09,

        /* Target Selection Timeout */
        CAM_SEL_TIMEOUT         = 0x0a,

        /* Command timeout */
        CAM_CMD_TIMEOUT         = 0x0b,

        /* SCSI error, look at error code in CCB */
        CAM_SCSI_STATUS_ERROR   = 0x0c,

        /* Message Reject Received */
        CAM_MSG_REJECT_REC      = 0x0d,

        /* SCSI Bus Reset Sent/Received */
        CAM_SCSI_BUS_RESET      = 0x0e,

        /* Uncorrectable parity error occurred */
        CAM_UNCOR_PARITY        = 0x0f,

        /* Autosense: request sense cmd fail */
        CAM_AUTOSENSE_FAIL      = 0x10,

        /* No HBA Detected error */
        CAM_NO_HBA              = 0x11,

        /* Data Overrun error */
        CAM_DATA_RUN_ERR        = 0x12,

        /* Unexpected Bus Free */
        CAM_UNEXP_BUSFREE       = 0x13,

        /* Target Bus Phase Sequence Failure */
        CAM_SEQUENCE_FAIL       = 0x14,

        /* CCB length supplied is inadequate */
        CAM_CCB_LEN_ERR         = 0x15,

        /* Unable to provide requested capability*/
        CAM_PROVIDE_FAIL        = 0x16,

        /* A SCSI BDR msg was sent to target */
        CAM_BDR_SENT            = 0x17,

        /* CCB request terminated by the host */
        CAM_REQ_TERMIO          = 0x18,

        /* Unrecoverable Host Bus Adapter Error */
        CAM_UNREC_HBA_ERROR     = 0x19,

        /* Request was too large for this host */
        CAM_REQ_TOO_BIG         = 0x1a,

        /*
         * This request should be requeued to preserve
         * transaction ordering.  This typically occurs
         * when the SIM recognizes an error that should
         * freeze the queue and must place additional
         * requests for the target at the sim level
         * back into the XPT queue.
         */
        CAM_REQUEUE_REQ         = 0x1b,

        /* ATA error, look at error code in CCB */
        CAM_ATA_STATUS_ERROR    = 0x1c,

        /* Initiator/Target Nexus lost. */
        CAM_SCSI_IT_NEXUS_LOST  = 0x1d,

        /* SMP error, look at error code in CCB */
        CAM_SMP_STATUS_ERROR    = 0x1e,

        /*
         * Command completed without error but  exceeded the soft
         * timeout threshold.
         */
        CAM_REQ_SOFTTIMEOUT     = 0x1f,

        /*
         * NVME error, look at errro code in CCB
         */
        CAM_NVME_STATUS_ERROR   = 0x20,

        /*
         * 0x21 - 0x32 are unassigned
         */

        /* Initiator Detected Error */
        CAM_IDE                 = 0x33,

        /* Resource Unavailable */
        CAM_RESRC_UNAVAIL       = 0x34,

        /* Unacknowledged Event by Host */
        CAM_UNACKED_EVENT       = 0x35,

        /* Message Received in Host Target Mode */
        CAM_MESSAGE_RECV        = 0x36,

        /* Invalid CDB received in Host Target Mode */
        CAM_INVALID_CDB         = 0x37,

        /* Lun supplied is invalid */
        CAM_LUN_INVALID         = 0x38,

        /* Target ID supplied is invalid */
        CAM_TID_INVALID         = 0x39,

        /* The requested function is not available */
        CAM_FUNC_NOTAVAIL       = 0x3a,

        /* Nexus is not established */
        CAM_NO_NEXUS            = 0x3b,

        /* The initiator ID is invalid */
        CAM_IID_INVALID         = 0x3c,

        /* The SCSI CDB has been received */
        CAM_CDB_RECVD           = 0x3d,

        /* The LUN is already enabled for target mode */
        CAM_LUN_ALRDY_ENA       = 0x3e,

        /* SCSI Bus Busy */
        CAM_SCSI_BUSY           = 0x3f,

        /*
         * Flags
         */

        /* The DEV queue is frozen w/this err */
        CAM_DEV_QFRZN           = 0x40,

        /* Autosense data valid for target */
        CAM_AUTOSNS_VALID       = 0x80,

        /* SIM ready to take more commands */
        CAM_RELEASE_SIMQ        = 0x100,

        /* SIM has this command in its queue */
        CAM_SIM_QUEUED          = 0x200,

        /* Quality of service data is valid */
        CAM_QOS_VALID           = 0x400,

        /* Mask bits for just the status # */
        CAM_STATUS_MASK = 0x3F,

        /*
         * Target Specific Adjunct Status
         */

        /* sent sense with status */
        CAM_SENT_SENSE          = 0x40000000
} cam_status;

typedef enum {
        CAM_ESF_NONE            = 0x00,
        CAM_ESF_COMMAND         = 0x01,
        CAM_ESF_CAM_STATUS      = 0x02,
        CAM_ESF_PROTO_STATUS    = 0x04,
        CAM_ESF_ALL             = 0xff
} cam_error_string_flags;

typedef enum {
        CAM_EPF_NONE            = 0x00,
        CAM_EPF_MINIMAL         = 0x01,
        CAM_EPF_NORMAL          = 0x02,
        CAM_EPF_ALL             = 0x03,
        CAM_EPF_LEVEL_MASK      = 0x0f
        /* All bits above bit 3 are protocol-specific */
} cam_error_proto_flags;

typedef enum {
        CAM_ESF_PRINT_NONE      = 0x00,
        CAM_ESF_PRINT_STATUS    = 0x10,
        CAM_ESF_PRINT_SENSE     = 0x20
} cam_error_scsi_flags;

typedef enum {
        CAM_ESMF_PRINT_NONE     = 0x00,
        CAM_ESMF_PRINT_STATUS   = 0x10,
        CAM_ESMF_PRINT_FULL_CMD = 0x20,
} cam_error_smp_flags;

typedef enum {
        CAM_EAF_PRINT_NONE      = 0x00,
        CAM_EAF_PRINT_STATUS    = 0x10,
        CAM_EAF_PRINT_RESULT    = 0x20
} cam_error_ata_flags;

typedef enum {
        CAM_ENF_PRINT_NONE      = 0x00,
        CAM_ENF_PRINT_STATUS    = 0x10,
} cam_error_nvme_flags;

typedef enum {
        CAM_STRVIS_FLAG_NONE            = 0x00,
        CAM_STRVIS_FLAG_NONASCII_MASK   = 0x03,
        CAM_STRVIS_FLAG_NONASCII_TRIM   = 0x00,
        CAM_STRVIS_FLAG_NONASCII_RAW    = 0x01,
        CAM_STRVIS_FLAG_NONASCII_SPC    = 0x02,
        CAM_STRVIS_FLAG_NONASCII_ESC    = 0x03
} cam_strvis_flags;

struct cam_status_entry
{
        cam_status  status_code;
        const char *status_text;
};

extern const struct cam_status_entry cam_status_table[];
extern const int num_cam_status_entries;
#ifdef _KERNEL
extern int cam_sort_io_queues;
#ifdef SDT_PROVIDER_DECLARE
SDT_PROVIDER_DECLARE(cam);
#endif
#define CAM_PROBE1(group, probe, arg0)                          \
        SDT_PROBE1(cam, , group, probe, arg0)
#define CAM_PROBE2(group, probe, arg0, arg1)                    \
        SDT_PROBE2(cam, , group, probe, arg0, arg1)
#define CAM_PROBE3(group, probe, arg0, arg1, arg2)              \
        SDT_PROBE3(cam, , group, probe, arg0, arg1, arg2)
#define CAM_PROBE4(group, probe, arg0, arg1, arg2, arg3)        \
        SDT_PROBE4(cam, , group, probe, arg0, arg1, arg2, arg3)
#endif
union ccb;
struct sbuf;

#ifdef SYSCTL_DECL      /* from sysctl.h */
SYSCTL_DECL(_kern_cam);
#endif

__BEGIN_DECLS
typedef int (cam_quirkmatch_t)(caddr_t, caddr_t);

caddr_t cam_quirkmatch(caddr_t target, caddr_t quirk_table, int num_entries,
                       int entry_size, cam_quirkmatch_t *comp_func);

void    cam_strvis(uint8_t *dst, const uint8_t *src, int srclen, int dstlen);
void    cam_strvis_flag(uint8_t *dst, const uint8_t *src, int srclen,
                        int dstlen, uint32_t flags);
void    cam_strvis_sbuf(struct sbuf *sb, const uint8_t *src, int srclen,
                        uint32_t flags);

int     cam_strmatch(const uint8_t *str, const uint8_t *pattern, int str_len);
const struct cam_status_entry*
        cam_fetch_status_entry(cam_status status);
#ifdef _KERNEL
char *  cam_error_string(union ccb *ccb, char *str, int str_len,
                         cam_error_string_flags flags,
                         cam_error_proto_flags proto_flags);
void    cam_error_print(union ccb *ccb, cam_error_string_flags flags,
                        cam_error_proto_flags proto_flags);
#else /* _KERNEL */
struct cam_device;

char *  cam_error_string(struct cam_device *device, union ccb *ccb, char *str,
                         int str_len, cam_error_string_flags flags,
                         cam_error_proto_flags proto_flags);
void    cam_error_print(struct cam_device *device, union ccb *ccb,
                        cam_error_string_flags flags,
                        cam_error_proto_flags proto_flags, FILE *ofile);
#endif /* _KERNEL */
__END_DECLS

#ifdef _KERNEL
static __inline void cam_init_pinfo(cam_pinfo *pinfo)
{
        pinfo->priority = CAM_PRIORITY_NONE;
        pinfo->index = CAM_UNQUEUED_INDEX;
}
#endif

#endif /* _CAM_CAM_H */