/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright (c) 1990, 2010, Oracle and/or its affiliates. All rights reserved.
 * Copyright 2014 Garrett D'Amore <garrett@damore.org>
 * Copyright 2022 RackTop Systems, Inc.
 */

#ifndef _SYS_SCSI_IMPL_TRANSPORT_H
#define _SYS_SCSI_IMPL_TRANSPORT_H

/*
 * Include the loadable module wrapper.
 */
#include <sys/modctl.h>
#include <sys/note.h>

#ifdef  __cplusplus
extern "C" {
#endif

#ifdef  _KERNEL

/*
 * Opaque  handles to address maps
 */
typedef struct __scsi_iportmap  scsi_hba_iportmap_t;
typedef struct __scsi_tgtmap    scsi_hba_tgtmap_t;

/*
 * SCSI transport structures
 *
 *      As each Host Adapter makes itself known to the system,
 *      it will create and register with the library the structure
 *      described below. This is so that the library knows how to route
 *      packets, resource control requests, and capability requests
 *      for any particular host adapter. The 'a_hba_tran' field of a
 *      scsi_address structure made known to a Target driver will
 *      point to one of these transport structures.
 */

typedef struct scsi_hba_tran    scsi_hba_tran_t;

struct scsi_hba_tran {
        /*
         * Ptr to the device info structure for this particular HBA. If a SCSA
         * HBA driver separates initiator port function from HBA function,
         * this field still refers to the HBA and is used to manage DMA.
         */
        dev_info_t      *tran_hba_dip;

        /*
         * Private fields for use by the HBA itself.
         */
        void            *tran_hba_private;      /* HBA softstate */

        /*
         * The following two fields are only used in the deprecated
         * SCSI_HBA_TRAN_CLONE case. Use SCSI_HBA_ADDR_COMPLEX instead.
         */
        void                    *tran_tgt_private;
        struct scsi_device      *tran_sd;

        /*
         * Vectors to point to specific HBA entry points
         */
        int             (*tran_tgt_init)(
                                dev_info_t              *hba_dip,
                                dev_info_t              *tgt_dip,
                                scsi_hba_tran_t         *tran,
                                struct scsi_device      *sd);

        int             (*tran_tgt_probe)(
                                struct scsi_device      *sd,
                                int                     (*callback)(
                                                                void));
        void            (*tran_tgt_free)(
                                dev_info_t              *hba_dip,
                                dev_info_t              *tgt_dip,
                                scsi_hba_tran_t         *tran,
                                struct scsi_device      *sd);

        int             (*tran_start)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);

        int             (*tran_reset)(
                                struct scsi_address     *ap,
                                int                     level);

        int             (*tran_abort)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);

        int             (*tran_getcap)(
                                struct scsi_address     *ap,
                                char                    *cap,
                                int                     whom);

        int             (*tran_setcap)(
                                struct scsi_address     *ap,
                                char                    *cap,
                                int                     value,
                                int                     whom);

        struct scsi_pkt *(*tran_init_pkt)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt,
                                struct buf              *bp,
                                int                     cmdlen,
                                int                     statuslen,
                                int                     tgtlen,
                                int                     flags,
                                int                     (*callback)(
                                                                caddr_t arg),
                                caddr_t                 callback_arg);

        void            (*tran_destroy_pkt)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);

        void            (*tran_dmafree)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);

        void            (*tran_sync_pkt)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);

        int             (*tran_reset_notify)(
                                struct scsi_address     *ap,
                                int                     flag,
                                void                    (*callback)(caddr_t),
                                caddr_t                 arg);

        int             (*tran_get_bus_addr)(
                                struct scsi_device      *sd,
                                char                    *name,
                                int                     len);

        int             (*tran_get_name)(
                                struct scsi_device      *sd,
                                char                    *name,
                                int                     len);

        int             (*tran_clear_aca)(
                                struct scsi_address     *ap);

        int             (*tran_clear_task_set)(
                                struct scsi_address     *ap);

        int             (*tran_terminate_task)(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);

        int             (*tran_get_eventcookie)(
                                dev_info_t              *hba_dip,
                                dev_info_t              *tgt_dip,
                                char                    *name,
                                ddi_eventcookie_t       *eventp);

        int             (*tran_add_eventcall)(
                                dev_info_t              *hba_dip,
                                dev_info_t              *tgt_dip,
                                ddi_eventcookie_t       event,
                                void                    (*callback)(
                                                dev_info_t *tgt_dip,
                                                ddi_eventcookie_t event,
                                                void *arg,
                                                void *bus_impldata),
                                void                    *arg,
                                ddi_callback_id_t *cb_id);

        int             (*tran_remove_eventcall)(dev_info_t *devi,
                        ddi_callback_id_t cb_id);

        int             (*tran_post_event)(
                                dev_info_t              *hba_dip,
                                dev_info_t              *tgt_dip,
                                ddi_eventcookie_t       event,
                                void                    *bus_impldata);

        int             (*tran_quiesce)(
                                dev_info_t              *hba_dip);

        int             (*tran_unquiesce)(
                                dev_info_t              *hba_dip);

        int             (*tran_bus_reset)(
                                dev_info_t              *hba_dip,
                                int                     level);

        /*
         * Implementation-private specifics.
         * No HBA should refer to any of the fields below.
         * This information can and will change.
         */
        int                     tran_hba_flags;         /* flag options */

        uint_t                  tran_obs1;
        uchar_t                 tran_obs2;
        uchar_t                 tran_obs3;

        /*
         * open_lock: protect tran_minor_isopen
         * open_flag: bit field indicating which minor nodes are open.
         *      0 = closed, 1 = shared open, all bits 1 = excl open.
         *
         * NOTE: Unused if HBA driver implements its own open(9e) entry point.
         */
        kmutex_t                tran_open_lock;
        uint64_t                tran_open_flag;

        /*
         * bus_config vectors - ON Consolidation Private
         * These interfaces are subject to change.
         */
        int             (*tran_bus_config)(
                                dev_info_t              *hba_dip,
                                uint_t                  flag,
                                ddi_bus_config_op_t     op,
                                void                    *arg,
                                dev_info_t              **tgt_dipp);

        int             (*tran_bus_unconfig)(
                                dev_info_t              *hba_dip,
                                uint_t                  flag,
                                ddi_bus_config_op_t     op,
                                void                    *arg);

        int             (*tran_bus_power)(
                                dev_info_t              *dip,
                                void                    *impl_arg,
                                pm_bus_power_op_t       op,
                                void                    *arg,
                                void                    *result);

        /*
         * Inter-Connect type of transport as defined in
         * usr/src/uts/common/sys/scsi/impl/services.h
         */
        int             tran_interconnect_type;

        /* tran_setup_pkt(9E) related scsi_pkt fields */
        int             (*tran_pkt_constructor)(
                                struct scsi_pkt         *pkt,
                                scsi_hba_tran_t         *tran,
                                int                     kmflag);
        void            (*tran_pkt_destructor)(
                                struct scsi_pkt         *pkt,
                                scsi_hba_tran_t         *tran);
        kmem_cache_t    *tran_pkt_cache_ptr;
        uint_t          tran_hba_len;
        int             (*tran_setup_pkt)(
                                struct scsi_pkt         *pkt,
                                int                     (*callback)(
                                                                caddr_t arg),
                                caddr_t                 callback_arg);
        void            (*tran_teardown_pkt)(
                                struct scsi_pkt         *pkt);
        ddi_dma_attr_t  tran_dma_attr;

        void            *tran_extension;

        /*
         * An fm_capable HBA driver can set tran_fm_capable prior to
         * scsi_hba_attach_setup(). If not set, SCSA provides a default
         * implementation.
         */
        int             tran_fm_capable;

        /*
         * Ptr to the device info structure for initiator port. If a SCSA HBA
         * driver separates initiator port function from HBA function, this
         * field still refers to the initiator port.
         */
        dev_info_t      *tran_iport_dip;

        /*
         * map of initiator ports below HBA
         */
        scsi_hba_iportmap_t     *tran_iportmap;

        /*
         * map of targets below initiator
         */
        scsi_hba_tgtmap_t       *tran_tgtmap;

#ifdef  SCSI_SIZE_CLEAN_VERIFY
        /*
         * Must be last: Building a driver with-and-without
         * -DSCSI_SIZE_CLEAN_VERIFY, and checking driver modules for
         * differences with a tools like 'wsdiff' allows a developer to verify
         * that their driver has no dependencies on scsi*(9S) size.
         */
        int             _pad[8];
#endif  /* SCSI_SIZE_CLEAN_VERIFY */
};
size_t  scsi_hba_tran_size();                   /* private */

#ifdef __lock_lint
_NOTE(SCHEME_PROTECTS_DATA("stable data",
        scsi_hba_tran::tran_sd
        scsi_hba_tran::tran_hba_dip
        scsi_hba_tran::tran_hba_flags
        scsi_hba_tran::tran_open_flag
        scsi_hba_tran::tran_pkt_cache_ptr))
/*
 * we only modify the dma attributes (like dma_attr_granular) upon
 * attach and in response to a setcap. It is also up to the target
 * driver to not have any outstanding I/Os when it is changing the
 * capabilities of the transport.
 */
_NOTE(SCHEME_PROTECTS_DATA("serialized by target driver", \
        scsi_hba_tran::tran_dma_attr.dma_attr_granular))
#endif

/*
 * Prototypes for SCSI HBA interface functions
 *
 * All these functions are public interfaces, with the
 * exception of:
 *      interface                               called by
 *      scsi_initialize_hba_interface()         _init() of scsi module
 *      scsi_uninitialize_hba_interface()       _fini() of scsi module
 */

void            scsi_initialize_hba_interface(void);

#ifdef  NO_SCSI_FINI_YET
void            scsi_uninitialize_hba_interface(void);
#endif  /* NO_SCSI_FINI_YET */

int             scsi_hba_init(
                                struct modlinkage       *modlp);

void            scsi_hba_fini(
                                struct modlinkage       *modlp);

int             scsi_hba_attach_setup(
                                dev_info_t              *hba_dip,
                                ddi_dma_attr_t          *hba_dma_attr,
                                scsi_hba_tran_t         *tran,
                                int                     flags);

int             scsi_hba_detach(
                                dev_info_t              *hba_dip);

scsi_hba_tran_t *scsi_hba_tran_alloc(
                                dev_info_t              *hba_dip,
                                int                     flags);

int             scsi_tran_ext_alloc(
                                scsi_hba_tran_t         *tran,
                                size_t                  length,
                                int                     flags);

void            scsi_tran_ext_free(
                                scsi_hba_tran_t         *tran,
                                size_t                  length);

void            scsi_hba_tran_free(
                                scsi_hba_tran_t         *tran);

int             scsi_hba_probe(
                                struct scsi_device      *sd,
                                int                     (*callback)(void));

int             scsi_hba_probe_pi(
                                struct scsi_device      *sd,
                                int                     (*callback)(void),
                                int                     pi);

int             scsi_hba_ua_get_reportdev(
                                struct scsi_device      *sd,
                                char                    *ba,
                                int                     len);

int             scsi_hba_ua_get(
                                struct scsi_device      *sd,
                                char                    *ua,
                                int                     len);

char            *scsi_get_device_type_string(
                                char                    *prop_name,
                                dev_info_t              *hba_dip,
                                struct scsi_device      *sd);

int             scsi_get_scsi_maxluns(
                                struct scsi_device      *sd);

int             scsi_get_scsi_options(
                                struct scsi_device      *sd,
                                int                     default_scsi_options);

int             scsi_get_device_type_scsi_options(
                                dev_info_t              *hba_dip,
                                struct scsi_device      *sd,
                                int                     default_scsi_options);

struct scsi_pkt *scsi_hba_pkt_alloc(
                                dev_info_t              *hba_dip,
                                struct scsi_address     *ap,
                                int                     cmdlen,
                                int                     statuslen,
                                int                     tgtlen,
                                int                     hbalen,
                                int                     (*callback)(caddr_t),
                                caddr_t                 arg);

void            scsi_hba_pkt_free(
                                struct scsi_address     *ap,
                                struct scsi_pkt         *pkt);


int             scsi_hba_lookup_capstr(
                                char                    *capstr);

int             scsi_hba_in_panic(void);

int             scsi_hba_open(
                                dev_t                   *devp,
                                int                     flags,
                                int                     otyp,
                                cred_t                  *credp);

int             scsi_hba_close(
                                dev_t                   dev,
                                int                     flag,
                                int                     otyp,
                                cred_t                  *credp);

int             scsi_hba_ioctl(
                                dev_t                   dev,
                                int                     cmd,
                                intptr_t                arg,
                                int                     mode,
                                cred_t                  *credp,
                                int                     *rvalp);

void            scsi_hba_nodename_compatible_get(
                                struct scsi_inquiry     *inq,
                                char                    *binding_set,
                                int                     dtype_node,
                                char                    *compat0,
                                char                    **nodenamep,
                                char                    ***compatiblep,
                                int                     *ncompatiblep);

void            scsi_hba_nodename_compatible_free(
                                char                    *nodename,
                                char                    **compatible);

int             scsi_device_prop_update_inqstring(
                                struct scsi_device      *sd,
                                char                    *name,
                                char                    *data,
                                size_t                  len);

void            scsi_hba_pkt_comp(
                                struct scsi_pkt         *pkt);

int             scsi_device_identity(
                                struct scsi_device      *sd,
                                int                     (*callback)(void));

char            *scsi_hba_iport_unit_address(
                                dev_info_t              *dip);

int             scsi_hba_iport_register(
                                dev_info_t              *dip,
                                char                    *port);

int             scsi_hba_iport_exist(
                                dev_info_t              *dip);

dev_info_t      *scsi_hba_iport_find(
                                dev_info_t              *pdip,
                                char                    *portnm);


/*
 * Flags for scsi_hba_attach
 *
 * SCSI_HBA_ADDR_SPI            The host adapter driver wants the
 *                              scsi_address(9S) structure to be maintained
 *                              in legacy SPI 'a_target'/'a_lun' form (default).
 *
 * SCSI_HBA_ADDR_COMPLEX        The host adapter has a complex unit-address
 *                              space, and the HBA driver wants to maintain
 *                              per-scsi_device(9S) HBA private data using
 *                              scsi_address_device(9F) and
 *                              scsi_device_hba_private_[gs]et(9F).  The HBA
 *                              driver must maintain a private representation
 *                              of the scsi_device(9S) unit-address - typically
 *                              established during tran_tgt_init(9E) based on
 *                              property values.
 *
 * SCSI_HBA_TRAN_PHCI           The host adapter is an mpxio/scsi_vhci pHCI.
 *                              The framework should take care of
 *                              mdi_phci_register() stuff.
 *
 * SCSI_HBA_HBA                 The host adapter node (associated with a PCI
 *                              function) is just an HBA, all SCSI initiator
 *                              port function is provided by separate 'iport'
 *                              children of the host adapter node.  These iport
 *                              children bind to the same driver as the host
 *                              adapter node. Both nodes are managed by the
 *                              same driver. The driver can distinguish context
 *                              by calling scsi_hba_iport_unit_address().
 *
 * ::SCSI_HBA_TRAN_CLONE        Deprecated: use SCSI_HBA_ADDR_COMPLEX instead.
 *                              SCSI_HBA_TRAN_CLONE was a KLUDGE to address
 *                              limitations of the scsi_address(9S) structure
 *                              via duplication of scsi_hba_tran(9S) and
 *                              use of tran_tgt_private.
 *
 */
#define SCSI_HBA_TRAN_CLONE     0x01    /* Deprecated */
#define SCSI_HBA_TRAN_PHCI      0x02    /* treat HBA as mpxio 'pHCI' */
#define SCSI_HBA_TRAN_CDB       0x04    /* allocate cdb */
#define SCSI_HBA_TRAN_SCB       0x08    /* allocate sense */
#define SCSI_HBA_HBA            0x10    /* all HBA children are iports */

#define SCSI_HBA_ADDR_SPI       0x20    /* scsi_address in SPI form */
#define SCSI_HBA_ADDR_COMPLEX   0x40    /* scsi_address is COMPLEX */

/* upper bits used to record SCSA configuration state */
#define SCSI_HBA_SCSA_PHCI      0x10000 /* need mdi_phci_unregister */
#define SCSI_HBA_SCSA_TA        0x20000 /* scsi_hba_tran_alloc used */
#define SCSI_HBA_SCSA_FM        0x40000 /* using common ddi_fm_* */

/*
 * Flags for scsi_hba allocation functions
 */
#define SCSI_HBA_CANSLEEP       0x01            /* can sleep */

/*
 * Support extra flavors for SCSA children
 */
#define SCSA_FLAVOR_SCSI_DEVICE NDI_FLAVOR_VANILLA
#define SCSA_FLAVOR_SMP         1
#define SCSA_FLAVOR_IPORT       2
#define SCSA_NFLAVORS           3

/*
 * Maximum number of iport nodes under PCI function
 */
#define SCSI_HBA_MAX_IPORTS     32

/*
 * SCSI iport map interfaces
 */
int     scsi_hba_iportmap_create(
                                dev_info_t              *hba_dip,
                                int                     csync_usec,
                                int                     stable_usec,
                                scsi_hba_iportmap_t     **iportmapp);

int     scsi_hba_iportmap_iport_add(
                                scsi_hba_iportmap_t     *iportmap,
                                char                    *iport_addr,
                                void                    *iport_priv);

int     scsi_hba_iportmap_iport_remove(
                                scsi_hba_iportmap_t     *iportmap,
                                char                    *iport_addr);

void    scsi_hba_iportmap_destroy(scsi_hba_iportmap_t   *iportmap);

/*
 * SCSI target map interfaces
 */
typedef enum {
        SCSI_TM_FULLSET = 0,
        SCSI_TM_PERADDR
} scsi_tgtmap_mode_t;

typedef enum {
        SCSI_TGT_SCSI_DEVICE = 0,
        SCSI_TGT_SMP_DEVICE,
        SCSI_TGT_NTYPES
} scsi_tgtmap_tgt_type_t;

typedef enum {
        SCSI_TGT_DEACT_RSN_GONE = 0,
        SCSI_TGT_DEACT_RSN_CFG_FAIL,
        SCSI_TGT_DEACT_RSN_UNSTBL
} scsi_tgtmap_deact_rsn_t;

typedef void    (*scsi_tgt_activate_cb_t)(
                                void                    *tgtmap_priv,
                                char                    *tgt_addr,
                                scsi_tgtmap_tgt_type_t  tgt_type,
                                void                    **tgt_privp);
typedef boolean_t       (*scsi_tgt_deactivate_cb_t)(
                                void                    *tgtmap_priv,
                                char                    *tgt_addr,
                                scsi_tgtmap_tgt_type_t  tgt_type,
                                void                    *tgt_priv,
                                scsi_tgtmap_deact_rsn_t tgt_deact_rsn);
int     scsi_hba_tgtmap_create(
                                dev_info_t              *iport_dip,
                                scsi_tgtmap_mode_t      rpt_mode,
                                int                     csync_usec,
                                int                     stable_usec,
                                void                    *tgtmap_priv,
                                scsi_tgt_activate_cb_t  activate_cb,
                                scsi_tgt_deactivate_cb_t deactivate_cb,
                                scsi_hba_tgtmap_t       **tgtmapp);

int     scsi_hba_tgtmap_set_begin(scsi_hba_tgtmap_t     *tgtmap);

int     scsi_hba_tgtmap_set_add(
                                scsi_hba_tgtmap_t       *tgtmap,
                                scsi_tgtmap_tgt_type_t  tgt_type,
                                char                    *tgt_addr,
                                void                    *tgt_priv);

int     scsi_hba_tgtmap_set_end(
                                scsi_hba_tgtmap_t       *tgtmap,
                                uint_t                  flags);

int     scsi_hba_tgtmap_set_flush(scsi_hba_tgtmap_t     *tgtmap);

int     scsi_hba_tgtmap_tgt_add(
                                scsi_hba_tgtmap_t       *tgtmap,
                                scsi_tgtmap_tgt_type_t  tgt_type,
                                char                    *tgt_addr,
                                void                    *tgt_priv);

int     scsi_hba_tgtmap_tgt_remove(
                                scsi_hba_tgtmap_t       *tgtmap,
                                scsi_tgtmap_tgt_type_t  tgt_type,
                                char                    *tgt_addr);

void    scsi_hba_tgtmap_destroy(scsi_hba_tgtmap_t       *tgt_map);

void    scsi_hba_tgtmap_scan_luns(scsi_hba_tgtmap_t     *tgt_map,
                                char                    *tgt_addr);


/*
 * For minor nodes created by the SCSA framework, minor numbers are
 * formed by left-shifting instance by INST_MINOR_SHIFT and OR in a
 * number less than 64.
 *
 * - Numbers 0 - 31 are reserved by the framework, part of the range are
 *      in use, as defined below.
 *
 * - Numbers 32 - 63 are available for HBA driver use.
 */
#define INST_MINOR_SHIFT        6
#define TRAN_MINOR_MASK         ((1 << INST_MINOR_SHIFT) - 1)
#define TRAN_OPEN_EXCL          (uint64_t)-1

#define DEVCTL_MINOR            0
#define SCSI_MINOR              1

#define INST2DEVCTL(x)          (((x) << INST_MINOR_SHIFT) | DEVCTL_MINOR)
#define INST2SCSI(x)            (((x) << INST_MINOR_SHIFT) | SCSI_MINOR)
#define MINOR2INST(x)           ((x) >> INST_MINOR_SHIFT)

#define SCSI_HBA_PROP_RECEPTACLE_LABEL  "receptacle-label"

#endif  /* _KERNEL */

#ifdef  __cplusplus
}
#endif

#endif  /* _SYS_SCSI_IMPL_TRANSPORT_H */