5    CAM Data Structures

Data structures are the mechanism used to pass information between peripheral device drivers and the CAM subsystem. This chapter describes the CAM data structures that peripheral device drivers use. They are defined in the file /usr/sys/include/io/cam/cam.h. This chapter discusses the following:

• CAM control block (CCB)

• Input/output (I/O) data structures

• Control CCB structures

• Configuration data structures

Other chapters reference these structures. You can read this chapter now to become familiar with the structures, or you can refer to it when you encounter references to the structures in other chapters.

5.1    CAM Control Blocks

The CAM control block (CCB) data structures let the device driver writer specify the action to be performed by the XPT and SIM. The CCBs are allocated by calling the xpt_ccb_alloc routine. Table 5-1 contains the name of each CCB data structure and a brief description.

Table 5-1: CAM Control Blocks

All CCBs contain a CCB_HEADER structure. Peripheral device driver writers need to understand the CCB_HEADER data structure, which is discussed in the section that follows.

5.1.1    The CCB_HEADER Structure

SCSI/CAM peripheral device driver writers allocate a CCB structure by calling the xpt_ccb_alloc routine. The CCB_HEADER structure is common to all CCBs and is the first structure filled in. It contains the following members:

typedef struct ccb_header
{
    struct ccb_header *my_addr; /* The address of this CCB */
    u_short cam_ccb_len;        /* Length of the entire CCB */
    u_char cam_func_code;       /* XPT function code */
    u_char cam_status;          /* Returned CAM subsystem */
                                /* status */
    u_char cam_path_id;         /* Path ID for the request */
    u_char cam_target_id;       /* Target device ID */
    u_char cam_target_lun;      /* Target LUN number */
    u_long cam_flags;           /* Flags for operation of */
                                /* the subsystem */
} CCB_HEADER;

5.1.1.1    The my_addr and cam_ccb_len Members

The my_addr member is set to a pointer to the virtual address of the starting address of the CCB. The xpt_ccb_alloc routine automatically fills it in.

The cam_ccb_len member is set to the length (in bytes) of this specific CCB type. The ccmn_get_ccb routine fills in this member. The length includes the my_addr and cam_ccb_len members.

5.1.1.2    The cam_func_code Member

The cam_func_code member lets device driver writers specify the CCB type XPT/SIM functions. Device driver writers can set this member to one of the function codes listed in Table 5-2. They are defined in the file /usr/sys/include/io/cam/cam.h.

Table 5-2: CAM Function Codes

5.1.1.3    The cam_status Member

The cam_status member is the action or event that occurred during this CCB request. The cam_status member is set by the XPT/SIM after the specified function has completed. A CAM_REQ_INPROG status indicates that either the function is still executing or is still in the queue. The XPT/SIM can set this member to one of the CAM status codes listed in Table 5-3. They are defined in the file /usr/sys/include/io/cam/cam.h.

Table 5-3: CAM Status Codes

5.2    I/O Data Structure

Peripheral device drivers make SCSI device action requests through the following data structures:

• The CCB_SCSIIO structure

• The CDB_UN structure

5.2.1    The CCB_SCSIIO Structure

A peripheral driver indicates to the XPT/SIM that it wants to make a SCSI device action request by setting the cam_func_code member of the CCB_HEADER structure to the constant XPT_SCSI_IO. The peripheral driver writer then uses the CCB_SCSIIO structure to specify the requests.

The CCB_SCSIIO structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;        /* Header information fields */
    u_char *cam_pdrv_ptr;     /* Ptr to the Peripheral driver */
                              /* working set */
    CCB_HEADER *cam_next_ccb; /* Ptr to the next CCB for action */
    u_char *cam_req_map;      /* Ptr for mapping info on the Req. */
    void (*cam_cbfcnp)();     /* Callback on completion function */
    u_char *cam_data_ptr;     /* Pointer to the data buf/SG list */
    u_long cam_dxfer_len;     /* Data xfer length */
    u_char *cam_sense_ptr;    /* Pointer to the sense data buffer */
    u_char cam_sense_len;     /* Num of bytes in the Autosense buf */
    u_char cam_cdb_len;       /* Number of bytes for the CDB */
    u_short cam_sglist_cnt;   /* Num of scatter/gather list entries */
    u_long cam_sort;          /* Value used by the SIM to sort on  */
    cam_scsi_status           /* Returned SCSI device status */
    cam_sense_resid           /* Autosense residual length: */
                                      /* two's complement */
    cam_osd_rsvdi[2]          /* OSD reserved field for alignment */
    long cam_resid;           /* Transfer residual length: */
                                      /* two's complement */
    CDB_UN cam_cdb_io;        /* Union for CDB bytes/pointer */
    u_long cam_timeout;       /* Timeout value */
    u_char *cam_msg_ptr;      /* Pointer to the message buffer */
    u_short cam_msgb_len;     /* Num of bytes in the message buf */
    u_short cam_vu_flags;     /* Vendor unique flags */
    u_char cam_tag_action;    /* What to do for tag queuing */
    u_char cam_iorsvd0[3];    /* Reserved field, for alignment */
    u_char cam_sim_priv[ SIM_PRIV ];   /* SIM private data area */
} CCB_SCSIIO;

5.2.2    The CDB_UN Structure

The CDB_UN structure is defined as follows:

typedef union
{
    u_char *cam_cdb_ptr;                /* Pointer to the CDB bytes */
                                                       /* to send */
    u_char cam_cdb_bytes[ IOCDBLEN ];   /* Area for the inline CDB *?
                                                       /* to send */
} CDB_UN;

5.3    Control CCB Structures

The control CCB structures allow the driver writer to specify such tasks as resetting the SCSI bus, terminating an I/O process request, and so forth. This section discusses the following control structures:

• CCB_RELSIM

• CCB_SETASYNC

• CCB_ABORT

• CCB_RESETBUS

• CCB_RESETDEV

• CCB_TERMIO

5.3.1    The CCB_RELSIM Structure

Device driver writers use the CCB_RELSIM structure to release the SIM's internal CCB queue. The CCB_RELSIM structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;           /* Header information fields */
} CCB_RELSIM;

5.3.2    The CCB_SETASYNC Structure

SCSI/CAM peripheral device driver writers use the CCB_SETASYNC structure to set the asynchronous callback for notification of the following events when they occur:

• Unsolicited SCSI BUS DEVICE RESET (BDR)

• Unsolicited RESELECTION

• SCSI AEN (asynchronous event notification enabled)

• Sent BDR to target

• SIM module loaded

• SIM module unloaded

• New devices found

The CCB_SETASYNC structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;         /* Header information fields */
    u_long cam_async_flags;    /* Event enables for Callback response */
    void (*cam_async_func)();  /* Async Callback function address */
    u_char *pdrv_buf;          /* Buffer set aside by the */
                               /* peripheral driver */
    u_char pdrv_buf_len;       /* The size of the buffer */
} CCB_SETASYNC;

5.3.3    The CCB_ABORT Structure

Device driver writers use the CCB_ABORT structure to abort a CCB that is on the SIM queue. The CCB_ABORT structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;             /* Header information fields */
    CCB_HEADER *cam_abort_ch;      /* Pointer to the CCB to abort */
} CCB_ABORT;

5.3.4    The CCB_RESETBUS Structure

Device driver writers use the CCB_RESETBUS structure to reset the SCSI bus. The CCB_RESETBUS structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;      /* Header information fields */
} CCB_RESETBUS;

5.3.5    The CCB_RESETDEV Structure

Device driver writers use the CCB_RESETDEV structure to reset a single SCSI device. The CCB_RESETDEV structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;      /* Header information fields */
} CCB_RESETDEV;

5.3.6    The CCB_TERMIO Structure

Device driver writers use the CCB_TERMIO structure to terminate an I/O process request. The CCB_TERMIO structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;             /* Header information fields */
    CCB_HEADER *cam_termio_ch;     /* Pointer to the CCB to terminate */
} CCB_TERMIO;

5.4    Configuration CCB Structures

The configuration CCB structures let the driver writer obtain information such as the device type, version number for the SIM/HBA, and vendor IDs. The following configuration CCBs are described in this section:

• The CCB_GETDEV structure

• The CDB_SETDEV structure

• The CDB_PATHINQ structure

5.4.1    The CCB_GETDEV Structure

Device driver writers use the CCB_GETDEV structure to obtain a device type and inquiry information. The CCB_GETDEV structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;       /* Header information fields */
    u_char cam_pd_type;      /* Peripheral device type from the TLUN */
    char *cam_inq_data;      /* Ptr to the inquiry data space */
} CCB_GETDEV;

5.4.2    The CCB_SETDEV Structure

Device driver writers use the CCB_SETDEV structure to set the device type. The CCB_SETDEV structure is defined as follows:

typedef struct
{
    CCB_HEADER cam_ch;      /* Header information fields */
    u_char cam_dev_type;    /* Value for the dev type field in EDT */
} CCB_SETDEV;

5.4.3    The CCB_PATHINQ Structure

Device driver writers use the CCB_PATHINQ structure to obtain SIM information such as supported features and version numbers. The CCB_PATHINQ structure is defined as follows:

typedef struct
{
   CCB_HEADER cam_ch;               /* Header information fields */
   u_char cam_version_num;          /* Version number for the SIM/HBA */
   u_char cam_hba_inquiry;          /* Mimic of INQ byte 7 for the HBA */
   u_char cam_target_sprt;          /* Flags for target mode support */
   u_char cam_hba_misc;             /* Misc HBA feature flags */
   u_char cam_vuhba_flags[ VUHBA ]; /* Vendor unique capabilities */
   u_long cam_sim_priv;             /* Size of SIM private data area */
   u_long cam_async_flags;          /* Event cap. for Async Callback */
   u_char cam_hpath_id;             /* Highest path ID in subsystem */
   u_char cam_initiator_id;         /* ID of the HBA on the SCSI bus */
   char cam_sim_vid[ SIM_ID ];      /* Vendor ID of the SIM */
   char cam_hba_vid[ HBA_ID ];      /* Vendor ID of the HBA */
   u_char *cam_osd_usage;           /* Ptr for the OSD specific area */
} CCB_PATHINQ;