Title and Copyright Pages

About This Manual
Audience
New and Changed Features
Organization
Related Documentation
Reader's Comments
Conventions

1    SCSI/CAM Software Architecture
1.1    Overview
1.2    CAM User Agent Device Driver
1.3    SCSI/CAM Peripheral Device Drivers
1.3.1    S/CA Common Device Driver Modules
1.3.2    S/CA Generic Device Driver Modules
1.3.3    CAM SCSI Disk Device Driver Modules
1.3.4    CAM SCSI Tape Device Driver Modules
1.3.5    CAM SCSI CD-ROM/AUDIO Device Driver Modules
1.4    SCSI/CAM Special I/O Interface
1.5    SCSI/CAM Configuration Driver
1.6    CAM Transport Layer (XPT)
1.7    SCSI Interface Module Layers (SIM)

2    CAM User Agent Modules
2.1    User Agent Introduction
2.2    User Agent Error Handling
2.3    User Agent Data Structures
2.3.1    The UAGT_CAM_CCB Data Structure
2.3.1.1    The uagt_ccb Member
2.3.1.2    The uagt_ccblen Member
2.3.1.3    The uagt_buffer Member
2.3.1.4    The uagt_buflen Member
2.3.1.5    The uagt_snsbuf Member
2.3.1.6    The uagt_snslen Member
2.3.1.7    The uagt_cdb Member
2.3.1.8    The uagt_cdblen Member
2.3.1.9    The uagt_flags Member
2.3.2    The UAGT_CAM_SCAN Data Structure
2.4    User Agent Routines
2.4.1    The uagt_open Routine
2.4.2    The uagt_close Routine
2.4.3    The uagt_ioctl Routine
2.5    Sample User Agent Drivers
2.5.1    Sample User Agent Driver Inquiry Program
2.5.1.1    The Include Files and Definitions Section
2.5.1.2    Main Program Section
2.5.1.3    User Agent Open Section
2.5.1.4    Filling in XPT_SCSI_IO Request CCB_HEADER Fields
2.5.1.5    Filling in INQUIRY Command CCB_HEADER Fields
2.5.1.6    Filling in the UAGT_CAM_CCB Fields
2.5.1.7    Sending the CCB to the CAM Subsystem
2.5.1.8    Print INQUIRY Data Routine
2.5.1.9    Print CAM Status Routine
2.5.1.10    Sample Output for a Valid Nexus
2.5.1.11    Sample Output for an Invalid Nexus
2.5.1.12    Sample Shell Script
2.5.2    Sample User Agent Scanner Driver Program
2.5.2.1    Scanner Program Header File
2.5.2.2    The Include Files Section
2.5.2.3    CDB Setup Section
2.5.2.4    Definitions Section
2.5.2.5    Main Program Section
2.5.2.6    Nexus Conversion Section
2.5.2.7    Parameter Assignment Section
2.5.2.8    Data Structure Setup Section
2.5.2.9    Window Parameters Setup Section
2.5.2.10    CCB Setup for the DEFINE WINDOW Command
2.5.2.11    Error Checking Section
2.5.2.12    CCB Setup for the READ Command
2.5.2.13    Read and Write Loop Section
2.5.2.14    Local Function Definition Section

3    S/CA Common Modules
3.1    Common SCSI Device Driver Data Structures
3.1.1    Peripheral Device Unit Table
3.1.2    Peripheral Device Structure
3.1.2.1    The pd_dev Member
3.1.2.2    The pd_spec_size Member
3.1.3    Device Descriptor Structure
3.1.4    Mode Select Table Structure
3.1.5    Density Table Structure
3.1.5.1    The den_blocking Member
3.1.6    SCSI/CAM Peripheral Device Driver Working Set Structure
3.1.6.1    The pws_flink Member
3.1.6.2    The pws_blink Member
3.1.6.3    The pws_ccb Member
3.2    Common SCSI Device Driver Macros
3.3    Common SCSI Device Driver Routines
3.3.1    Common I/O Routines
3.3.1.1    The ccmn_init Routine
3.3.1.2    The ccmn_open_unit Routine
3.3.1.3    The ccmn_close_unit Routine
3.3.2    Common Queue Manipulation Routines
3.3.2.1    The ccmn_send_ccb Routine
3.3.2.2    The ccmn_send_ccb_wait Routine
3.3.2.3    The ccmn_rem_ccb Routine
3.3.2.4    The ccmn_abort_que Routine
3.3.2.5    The ccmn_term_que Routine
3.3.3    Common CCB Management Routines
3.3.3.1    The ccmn_get_ccb Routine
3.3.3.2    The ccmn_rel_ccb Routine
3.3.3.3    The ccmn_io_ccb_bld Routine
3.3.3.4    The ccmn_gdev_ccb_bld Routine
3.3.3.5    The ccmn_sdev_ccb_bld Routine
3.3.3.6    The ccmn_sasy_ccb_bld Routine
3.3.3.7    The ccmn_rsq_ccb_bld Routine
3.3.3.8    The ccmn_pinq_ccb_bld Routine
3.3.3.9    The ccmn_abort_ccb_bld Routine
3.3.3.10    The ccmn_term_ccb_bld Routine
3.3.3.11    The ccmn_bdr_ccb_bld Routine
3.3.3.12    The ccmn_br_ccb_bld Routine
3.3.4    Common SCSI I/O Command Building Routines
3.3.4.1    The ccmn_tur Routine
3.3.4.2    The ccmn_start_unit Routine
3.3.4.3    The ccmn_mode_select Routine
3.3.5    Common CCB Status Routine
3.3.6    Common Buf Structure Pool Management Routines
3.3.6.1    The ccmn_get_bp Routine
3.3.6.2    The ccmn_rel_bp Routine
3.3.7    Common Data Buffer Pool Management Routines
3.3.7.1    The ccmn_get_dbuf Routine
3.3.7.2    The ccmn_rel_dbuf Routine
3.3.8    Common Routines for Loadable Drivers
3.3.8.1    The ccmn_check_idle Routine
3.3.8.2    The ccmn_find_ctlr Routine
3.3.8.3    The ccmn_attach_device Routine
3.3.9    Miscellaneous Common Routines
3.3.9.1    The ccmn_DoSpecialCmd Routine
3.3.9.2    The ccmn_SysSpecialCmd Routine
3.3.9.3    The ccmn_errlog Routine

4    S/CA Generic Modules
4.1    Prerequisites for Using the CAM Generic Routines
4.1.1    The ioctl Commands
4.1.2    Error Handling
4.1.3    Kernel Interface
4.2    Data Structures That Generic Routines Use
4.2.1    Generic-Specific Structure
4.2.1.1    The gen_flags Member
4.2.1.2    The gen_state_flags Member
4.2.1.3    The gen_resid Member
4.2.2    Generic Action Structure
4.2.2.1    The act_ccb Member
4.2.2.2    The act_ret_error Member
4.2.2.3    The act_fatal Member
4.2.2.4    The act_ccb_status Member
4.2.2.5    The act_scsi_status Member
4.2.2.6    The act_chkcond_error Member
4.3    Generic I/O Routines
4.3.1    The cgen_open Routine
4.3.2    The cgen_close Routine
4.3.3    The cgen_read Routine
4.3.4    The cgen_write Routine
4.3.5    The cgen_strategy Routine
4.3.6    The cgen_ioctl Routine
4.4    Generic Internal Routines
4.4.1    The cgen_ccb_chkcond Routine
4.4.2    The cgen_done Routine
4.4.3    The cgen_iodone Routine
4.4.4    The cgen_async Routine
4.4.5    The cgen_minphys Routine
4.4.6    The cgen_slave Routine
4.4.7    The cgen_attach Routine
4.5    Generic Command Support Routines
4.5.1    The cgen_ready Routine
4.5.2    The cgen_open_sel Routine
4.5.3    The cgen_mode_sns Routine

5    CAM Data Structures
5.1    CAM Control Blocks
5.1.1    The CCB_HEADER Structure
5.1.1.1    The my_addr and cam_ccb_len Members
5.1.1.2    The cam_func_code Member
5.1.1.3    The cam_status Member
5.2    I/O Data Structure
5.2.1    The CCB_SCSIIO Structure
5.2.2    The CDB_UN Structure
5.3    Control CCB Structures
5.3.1    The CCB_RELSIM Structure
5.3.2    The CCB_SETASYNC Structure
5.3.3    The CCB_ABORT Structure
5.3.4    The CCB_RESETBUS Structure
5.3.5    The CCB_RESETDEV Structure
5.3.6    The CCB_TERMIO Structure
5.4    Configuration CCB Structures
5.4.1    The CCB_GETDEV Structure
5.4.2    The CCB_SETDEV Structure
5.4.3    The CCB_PATHINQ Structure

6    SCSI/CAM Configuration Driver Modules
6.1    Configuration Driver Introduction
6.2    Configuration Driver XPT Interface
6.3    Configuration Driver Data Structures
6.3.1    Configuration Driver Control Structure
6.3.1.1    The ccfg_flags Member
6.3.1.2    The inq_buf Member
6.3.2    CAM Equipment Device Table
6.3.2.1    The edt Member
6.3.2.2    The edt_scan_count Member
6.3.2.3    The edt_flags Member
6.3.3    SCSI/CAM Peripheral Driver Configuration Structure
6.3.3.1    The cpd_name Member
6.3.3.2    The cpd_slave Member
6.3.3.3    The cpd_attach Member
6.3.3.4    The cpd_unload Member
6.4    The cam_config.c File
6.5    Configuration Driver Entry Point Routines
6.5.1    The ccfg_slave Routine
6.5.2    The ccfg_attach Routine
6.5.3    The ccfg_action Routine
6.5.4    The ccfg_edtscan Routine

7    CAM XPT I/O Support Routines
7.1    The xpt_action Routine
7.2    The xpt_ccb_alloc Routine
7.3    The xpt_ccb_free Routine
7.4    The xpt_init Routine

8    CAM SIM Modules
8.1    SIM Asynchronous Callback Handling
8.2    SIM Routines That Device Driver Writers Use
8.2.1    The sim_action Routine
8.2.2    The sim_init Routine
8.3    Digital-Specific Features of the SIM Layers
8.3.1    SCSI I/O CCB Priorities
8.3.2    SCSI I/O CCB Reordering

9    S/CA Error Handling
9.1    CAM Error-Handling Macro
9.2    CAM Error-Logging Structures
9.2.1    Error Entry Structure
9.2.1.1    The ent_type Member
9.2.1.2    The ent_size Member
9.2.1.3    The ent_total_size Member
9.2.1.4    The ent_vers Member
9.2.1.5    The ent_data Member
9.2.1.6    The ent_pri Member
9.2.2    Error Header Structure
9.2.2.1    The hdr_type Member
9.2.2.2    The hdr_size Member
9.2.2.3    The hdr_class Member
9.2.2.4    The hdr_subsystem Member
9.2.2.5    The hdr_entries Member
9.2.2.6    The hdr_list Member
9.2.2.7    The hdr_pri Member
9.3    Event Reporting
9.3.1    The uerf Utility
9.4    The cam_logger Routine

10    S/CA Debugging Facilities
10.1    CAM Debugging Variables
10.1.1    The camdbg_flag Variable
10.1.2    The camdbg_id Variable
10.2    CAM Debugging Macros
10.3    CAM Debugging Routines
10.3.1    CAM Debugging Status Routines
10.3.1.1    The cdbg_CamFunction Routine
10.3.1.2    The cdbg_CamStatus Routine
10.3.1.3    The cdbg_ScsiStatus Routine
10.3.1.4    The cdbg_SystemStatus Routine
10.3.2    CAM Dump Routines
10.3.2.1    The cdbg_DumpCCBHeader Routine
10.3.2.2    The cdbg_DumpCCBHeaderFlags Routine
10.3.2.3    The cdbg_DumpSCSIIO Routine
10.3.2.4    The cdbg_DumpPDRVws Routine
10.3.2.5    The cdbg_DumpABORT Routine
10.3.2.6    The cdbg_DumpTERMIO Routine
10.3.2.7    The cdbg_DumpBuffer Routine
10.3.2.8    The cdbg_GetDeviceName Routine
10.3.2.9    The cdbg_DumpInquiryData Routine

11    Programmer-Defined SCSI/CAM Device Drivers
11.1    Programmer-Defined SCSI/CAM Data Structures
11.1.1    Programmer-Defined Peripheral Device Unit Table
11.1.1.1    The pu_device Member
11.1.1.2    The pu_opens Member
11.1.1.3    The pu_config Member
11.1.1.4    The pu_type Member
11.1.2    Programmer-Defined Peripheral Device Structure
11.1.3    Programmer-Defined Device Descriptor Structure
11.1.3.1    The dd_pv_name Member
11.1.3.2    The dd_length Member
11.1.3.3    The dd_dev_name Member
11.1.3.4    The dd_device_type Member
11.1.3.5    The dd_def_partition Member
11.1.3.6    The dd_block_size Member
11.1.3.7    The dd_max_record Member
11.1.3.8    The dd_density_tbl Member
11.1.3.9    The dd_modesel_tbl Member
11.1.3.10    The dd_flags Member
11.1.3.11    The dd_scsi_optcmds Member
11.1.3.12    The dd_ready_time Member
11.1.3.13    The dd_que_depth Member
11.1.3.14    The dd_valid Member
11.1.3.15    The dd_inq_len Member
11.1.3.16    The dd_req_sense_len Member
11.1.4    Programmer-Defined Density Table Structure
11.1.4.1    The den_flags Member
11.1.4.2    The den_density_code Member
11.1.4.3    The den_compress_code Member
11.1.4.4    The den_speed_setting Member
11.1.4.5    The den_buffered_setting Member
11.1.4.6    The den_blocking Member
11.1.4.7    Sample Density Table Structure Entry
11.1.5    Programmer-Defined Mode Select Table Structure
11.1.5.1    The ms_page Member
11.1.5.2    The ms_data Member
11.1.5.3    The ms_data_len Member
11.1.5.4    The ms_ent_sp_pf Member
11.1.5.5    Sample Mode Select Table Structure Entry
11.2    Sample SCSI/CAM Device-Specific Data Structures
11.2.1    Programmer-Defined Tape-Specific Structure
11.2.1.1    The ts_flags Member
11.2.1.2    The ts_state_flags Member
11.2.1.3    The ts_resid Member
11.2.1.4    The ts_block_size Member
11.2.1.5    The ts_density Member
11.2.1.6    The ts_records Member
11.2.1.7    The ts_num_filemarks Member
11.2.2    Programmer-Defined Disk-Specific and CD-ROM-Specific Structure
11.2.3    SCSI/CAM CD-ROM/AUDIO I/O Control Commands
11.2.3.1    Structures That SCSI/CAM CD-ROM/AUDIO I/O Control Commands Use
11.2.3.1.1    Structure That All SCSI/CAM CD-ROM/AUDIO I/O Control Commands Use
11.2.3.1.2    Structure That the CDROM_PLAY_AUDIO and CDROM_PLAY_VAUDIO Commands Use
11.2.3.1.3    Structure That the CDROM_PLAY_AUDIO_MSF and CDROM_PLAY_MSF Commands Use
11.2.3.1.4    Structure That the CDROM_PLAY_AUDIO_TI Command Uses
11.2.3.1.5    Structure That the CDROM_PLAY_AUDIO_TR Command Uses
11.2.3.1.6    Structure That the CDROM_TOC_HEADER Command Uses
11.2.3.1.7    Structures That the CDROM_TOC_ENTRYS Command Uses
11.2.3.1.8    Structures That the CDROM_READ_SUBCHANNEL Command Uses
11.2.3.1.9    Structures That the CDROM_READ_HEADER Command Uses
11.2.3.1.10    Structure That the CDROM_PLAY_TRACK Command Uses
11.2.3.1.11    Structure That the CDROM_PLAYBACK_CONTROL and CDROM_PLAYBACK_STATUS Commands Use
11.2.3.1.12    Structure That the CDROM_PLAYBACK_CONTROL Command Uses
11.2.3.1.13    Structure That the CDROM_PLAYBACK_STATUS Command Uses
11.3    Adding a Programmer-Defined SCSI/CAM Device

12    SCSI/CAM Special I/O Interface
12.1    Application Program Access
12.2    Device Driver Access
12.3    SCSI/CAM Special Command Tables
12.3.1    The sph_flink and sph_blink Members
12.3.2    The sph_cmd_table Member
12.3.3    The sph_device_type Member
12.3.4    The sph_table_flags Member
12.3.5    The sph_table_name Member
12.4    SCSI/CAM Special Command Table Entries
12.4.1    The spc_ioctl_cmd and spc_sub_command Members
12.4.2    The spc_cmd_flags Member
12.4.3    The spc_command_code Member
12.4.4    The spc_device_type Member
12.4.5    The spc_cmd_parameter Member
12.4.6    The spc_cam_flags Member
12.4.7    The spc_file_flags Member
12.4.8    The spc_data_length Member
12.4.9    The spc_timeout Member
12.4.10    The spc_docmd Member
12.4.11    The spc_mkcdb Member
12.4.12    The spc_setup Member
12.4.13    The spc_cdbp Member
12.4.14    The spc_cmdp Member
12.4.15    Sample SCSI/CAM Special Command Table
12.5    SCSI/CAM Special I/O Argument Structure
12.5.1    The sa_flags Member
12.5.2    The sa_dev Member
12.5.3    The sa_unit, sa_bus, sa_target, and sa_lun Members
12.5.4    The sa_ioctl_cmd Member
12.5.5    The sa_ioctl_scmd Member
12.5.6    The sa_ioctl_data Member
12.5.7    The sa_device_name Member
12.5.8    The sa_device_type Member
12.5.9    The sa_iop_length and sa_iop_buffer Members
12.5.10    The sa_file_flags Member
12.5.11    The sa_sense_length and sa_sense_buffer Members
12.5.12    The sa_user_length and sa_user_buffer Members
12.5.13    The sa_bp Member
12.5.14    The sa_ccb Member
12.5.15    The special_cmd Member
12.5.16    The special_header Member
12.5.17    The sa_cmd_parameter Member
12.5.18    The sa_error Member
12.5.19    The sa_start Member
12.5.20    The sa_data_length and sa_data_buffer Members
12.5.21    The sa_cdb_pointer Member
12.5.22    The sa_cdb_length Member
12.5.23    The sa_cmd_flags Member
12.5.24    The sa_retry_count Member
12.5.25    The sa_retry_limit Member
12.5.26    The sa_timeout Member
12.5.27    The sa_xfer_resid Member
12.5.28    The sa_specific Member
12.5.29    Sample Function to Create a CDB
12.5.30    Sample Function to Set Up Parameters
12.6    SCSI/CAM Special I/O Control Command
12.6.1    The sp_flags Member
12.6.2    The sp_dev, sp_unit, sp_bus, sp_target, and sp_lun Members
12.6.3    The sp_sub_command Member
12.6.4    The sp_cmd_parameter Member
12.6.5    The sp_iop_length and sp_iop_buffer Members
12.6.6    The sp_sense_length, sp_sense_resid, and sp_sense_buffer Members
12.6.7    The sp_user_length and sp_user_buffer Members
12.6.8    The sp_timeout Member
12.6.9    The sp_retry_count Member
12.6.10    The sp_retry_limit Member
12.6.11    The sp_xfer_resid Member
12.6.12    Sample Function to Create an I/O Control Command
12.7    Other Sample Code
12.7.1    Sample Code to Open a Device
12.7.2    Sample Code to Create a Driver Entry Point

A    Header Files That Device Drivers Use

B    SCSI/CAM Routines
cam_logger
ccfg_attach
ccfg_edtscan
ccfg_slave
ccmn_abort_ccb_bld
ccmn_abort_que
ccmn_attach_device
ccmn_bdr_ccb_bld
ccmn_br_ccb_bld
ccmn_ccb_status
ccmn_check_idle
ccmn_close_unit
ccmn_DoSpecialCmd
ccmn_errlog
ccmn_find_ctlr
ccmn_gdev_ccb_bld
ccmn_get_bp
ccmn_get_ccb
ccmn_get_dbuf
ccmn_init
ccmn_io_ccb_bld
ccmn_mode_select
ccmn_open_unit
ccmn_pinq_ccb_bld
ccmn_rel_bp
ccmn_rel_ccb
ccmn_rel_dbuf
ccmn_rem_ccb
ccmn_rsq_ccb_bld
ccmn_sasy_ccb_bld
ccmn_sdev_ccb_bld
ccmn_send_ccb
ccmn_send_ccb_wait
ccmn_start_unit
ccmn_SysSpecialCmd
ccmn_term_ccb_bld
ccmn_term_que
ccmn_tur
cdbg_CamFunction
cdbg_CamStatus
cdbg_DumpABORT
cdbg_DumpBuffer
cdbg_DumpCCBHeader
cdbg_DumpCCBHeaderFlags
cdbg_DumpInquiryData
cdbg_DumpPDRVws
cdbg_DumpSCSIIO
cdbg_DumpTERMIO
cdbg_GetDeviceName
cdbg_ScsiStatus
cdbg_SystemStatus
cgen_async
cgen_attach
cgen_ccb_chkcond
cgen_close
cgen_done
cgen_ioctl
cgen_iodone
cgen_minphys
cgen_mode_sns
cgen_open
cgen_open_sel
cgen_read
cgen_ready
cgen_slave
cgen_strategy
cgen_write
sim_action
sim_init
uagt_close
uagt_ioctl
uagt_open
xpt_action
xpt_ccb_alloc
xpt_ccb_free
xpt_init

C    Sample Generic CAM Peripheral Driver

Examples

Figures

Tables