Summary ------- If an HBA driver allocates a scsi_pkt in its tran_init_pkt(9e) entry point, it is required to use the scsi_hba_pkt_alloc(9f) function to allocate it. However, for performance reasons many Sun HBA drivers have ignored this restriction and instead created private kernel memory caches to handle allocating and initializing scsi packets. This makes it difficult to change the size of a scsi_pkt(9s) without breaking HBA drivers that aren't DDI-compliant. It also creates a lot of duplicated code. This fast-track provides a set of optional entry points that can be used as an alternative to tran_init_pkt and tran_destroy_pkt, which allow an HBA driver to take advantage of a common kmem_cache mechanism. Background ---------- An HBA driver's tran_init_pkt(9e) entry point can be called to provide several different services; it can be called to allocate a scsi_pkt, to allocate DMA resources for an existing scsi_pkt, or to allocate both a scsi_pkt and assign DMA resources to it. If it is allocating a scsi_pkt, it is supposed to call scsi_hba_pkt_alloc(9f) which allocates memory for the following fields: pkt_ha_private HBA private data area. pkt_private Target driver private data area. pkt_scbp SCSI status completion block. pkt_cdbp SCSI command descriptor block. The HBA driver then initializes the remainder of the scsi_pkt. Many Sun HBA drivers have created their own kernel memory caches in order to preallocate memory and DMA resources associated with a scsi packet, as well as set up the relevent fields of the scsi_pkt structure. Proposal -------- Rather than having every HBA deal with managing its own cache and initializing the scsi_pkt structure, have the SCSA framework provide a kmem_cache mechanism which hands the HBA driver a scsi_pkt which is already initialized. tran_init_pkt(9e) and tran_destroy_pkt(9e) become optional. Instead a driver may elect to supply tran_init_cache_pkt(9e), tran_init_cache_bp(9e), and tran_fini_cache_pkt(9e) entry points, as well as specify sizes for the length of the hba-private data and whether to preallocate memory for the CDB and sense data. (There are two entry points, one for packet initialization and one to allocate DMA resources, because the two functions are logically separate.) The HBA driver may also provide a constructor and destructor. See sample man pages for detailed descriptions. Interface Table: ---------------- INTERFACE STABILITY COMMENTS tran_setup_pkt contracted cons. private scsi_hba_tran_t struct member tran_setup_bp contracted cons. private scsi_hba_tran_t struct member tran_teardown_pkt contracted cons. private scsi_hba_tran_t struct member tran_pkt_constructor contracted cons. private scsi_hba_tran_t struct member tran_pkt_destructor contracted cons. private scsi_hba_tran_t struct member tran_hba_len contracted cons. private scsi_hba_tran_t struct member pkt_cdblen contracted cons. private scsi_pkt struct member pkt_scblen contracted cons. private scsi_pkt struct member pkt_tgtlen contracted cons. private scsi_pkt struct member SCSI_HBA_TRAN_CDB contracted cons. private scsi_hba_attach flag SCSI_HBA_TRAN_SCB contracted cons. private scsi_hba_attach flag Release Binding: --------------- Minor.