illumos: manual page: tran_setup

TRAN_SETUP_PKT(9E) Driver Entry Points TRAN_SETUP_PKT(9E)

NAME

tran_setup_pkt, tran_teardown_pkt, tran_pkt_constructor,
tran_pkt_destructor - SCSI HBA packet allocation and deallocation

SYNOPSIS

#include <sys/scsi/scsi.h>

int prefix_tran_setup_pkt(struct scsi_pkt *pkt,
int (*callback) (caddr_t), caddr_t arg);

void prefix_tran_teardown_pkt(struct scsi_pkt *pkt);

int prefix_tran_pkt_constructor(struct scsi_pkt *pkt,
scsi_hba_tran_t *tranp, int kmflags);

void prefix_tran_pkt_destructor(struct scsi_pkt *pkt,
struct scsi_hba_tran_t *tranp);

INTERFACE LEVEL

illumos architecture specific (illumos DDI).

PARAMETERS

pkt
Pointer to the scsi_pkt(9S) structure.

flags
Flags for associating DMA resources with the packet.

callback
Pointer to either NULL_FUNC or SLEEP_FUNC.

arg
Always NULL.

kmflags
Either KM_SLEEP or KM_NOSLEEP.

DESCRIPTION

The tran_setup_pkt() and tran_teardown_pkt() vectors in the
scsi_hba_tran(9S) structure are alternatives to the tran_init_pkt() and
tran_destroy_pkt() entry points. They are initialized during the HBA
driver's attach(9E) and they are used when a target driver calls
scsi_init_pkt(9F) and scsi_destroy_pkt(9F).

tran_setup_pkt()
The tran_setup_pkt() vector is the entry point into the HBA which is used
to initialize HBA specific information in a scsi_pkt structure on behalf
of a SCSI target driver. All fields documented in scsi_pkt(9S) are
initialized.

If the HBA driver chose not to preallocate memory for pkt_cdbp and/or
pkt_scbp, it must allocate the requested memory at this time and point
pkt_cdbp and pkt_scbp to the allocated memory.

An HBA driver which provides a tran_setup_pkt entry point inspects the
pkt_numcookies and pkt_cookies fields at tran_start time to set up the
transfer. If pkt_numcookies is zero, there are no DMA resources
associated with this packet. If pkt_numcookies is not zero, it indicates
the number of DMA cookies that pkt_cookies points to.

The pkt_tgtlen field contains the length of the packet private area
pointed to by pkt_private, allocated on behalf of the SCSI target driver.

The pkt_scblen field contains the length of the SCSI status completion
block pointed to by pkt_scbp. If the status length is greater than or
equal to sizeof (struct scsi_arq_status) and the auto-rqsense capability
has been set, automatic request sense (ARS) is enabled for this packet.
If the status length is less than sizeof (struct scsi_arq_status),
automatic request sense should be disabled for this pkt if the HBA driver
is capable of disabling ARQ on a per-packet basis.

The pkt_cdblen field contains the length of the SCSI command descriptor
block.

The callback argument indicates what the allocator routines should do
when resources are not available:

NULL_FUNC
Do not wait for resources. Return -1 when resources are not
available.

SLEEP_FUNC
Wait indefinitely for resources.

tran_teardown_pkt()
The tran_teardown_pkt() is the entry point into the HBA that must free
all of the resources that were allocated to the scsi_pkt(9S) structure
during tran_setup_pkt().

tran_pkt_constructor() tran_pkt_destructor()
When using tran_pkt_setup() and tran_pkt_teardown(),
tran_pkt_constructor() and tran_pkt_destructor() are additional optional
entry points that perform the actions of a constructor and destructor.
The constructor is called after the following fields in the scsi_pkt
structure have been initialized:

o pkt_address

o pkt_ha_private

o pkt_cdbp

o pkt_private

o pkt_scbp

o pkt_cdblen

o pkt_tgtlen

o pkt_scblen

Allocating and freeing a DMA handle are examples of something that could
be done in the constructor and destructor. See kmem_cache_create(9F) for
additional restrictions on what actions can be performed in a constructor
and destructor.

HBA drivers that implement tran_setup_pkt() must signal scsi_pkt(9S)
completion by calling scsi_hba_pkt_comp(9F). Direct use of the scsi_pkt
pkt_comp field is not permitted and results in undefined behavior.

RETURN VALUES