SCSI_PKTALLOC(9F) Kernel Functions for Drivers SCSI_PKTALLOC(9F)

NAME

scsi_pktalloc, scsi_resalloc, scsi_pktfree, scsi_resfree - SCSI packet
utility routines

SYNOPSIS

#include <sys/scsi/scsi.h>

struct scsi_pkt *scsi_pktalloc (struct scsi_address* ap, int cmdlen,
int statuslen, int (*callback)(void));


struct scsi_pkt *scsi_resalloc (struct scsi_address* ap, int cmdlen,
int statuslen, opaque_t dmatoken, int (*callback)(void));


void scsi_pktfree (struct scsi_pkt* pkt);


void scsi_resfree (struct scsi_pkt* pkt);

INTERFACE LEVEL

The scsi_pktalloc(), scsi_pktfree(), scsi_resalloc(), and scsi_resfree()
functions are obsolete. The scsi_pktalloc() and scsi_resalloc() functions
have been replaced by scsi_init_pkt(9F). The scsi_pktfree() and
scsi_resfree() functions have been replaced by scsi_destroy_pkt(9F).

PARAMETERS

ap
Pointer to a scsi_address structure.


cmdlen
The required length for the SCSI command descriptor block
(CDB) in bytes.


statuslen
The required length for the SCSI status completion block
(SCB) in bytes.


dmatoken
Pointer to an implementation-dependent object.


callback
A pointer to a callback function, or NULL_FUNC or
SLEEP_FUNC.


pkt
Pointer to a scsi_pkt(9S) structure.

DESCRIPTION

The scsi_pktalloc() function requests the host adapter driver to allocate
a command packet. For commands that have a data transfer associated with
them, scsi_resalloc() should be used.


ap is a pointer to a scsi_address structure. Allocator routines use it to
determine the associated host adapter.


The cmdlen parameter is the required length for the SCSI command
descriptor block. This block is allocated such that a kernel virtual
address is established in the pkt_cdbp field of the allocated scsi_pkt
structure.


statuslen is the required length for the SCSI status completion block.
The address of the allocated block is placed into the pkt_scbp field of
the scsi_pkt structure.


The dmatoken parameter is a pointer to an implementation dependent object
which defines the length, direction, and address of the data transfer
associated with this SCSI packet (command). The dmatoken must be a
pointer to a buf(9S) structure. If dmatoken is NULL, no DMA resources are
required by this SCSI command, so none are allocated. Only one transfer
direction is allowed per command. If there is an unexpected data transfer
phase (either no data transfer phase expected, or the wrong direction
encountered), the command is terminated with the pkt_reason set to
CMD_DMA_DERR. dmatoken provides the information to determine if the
transfer count is correct.


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

NULL_FUNC
Do not wait for resources. Return a NULL pointer.


SLEEP_FUNC
Wait indefinitely for resources.


Other Values
callback points to a function which is called when
resources may have become available. callback must return
either 0 (indicating that it attempted to allocate
resources but again failed to do so), in which case it is
put back on a list to be called again later, or 1
indicating either success in allocating resources or
indicating that it no longer cares for a retry.


The scsi_pktfree() function frees the packet.


The scsi_resfree() function free all resources held by the packet and the
packet itself.

RETURN VALUES

Both allocation routines return a pointer to a scsi_pkt structure on
success, or NULL on failure.

CONTEXT

If callback is SLEEP_FUNC, then this routine can be called only from user
or kernel context. Otherwise, it can be called from user, kernel, or
interrupt context. The callback function may not block or call routines
that block. Both deallocation routines can be called from user, kernel,
or interrupt context.

ATTRIBUTES

See attributes(7) for a description of the following attributes:


+----------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+----------------+-----------------+
|Stability Level | Obsolete |
+----------------+-----------------+

SEE ALSO

attributes(7), scsi_dmafree(9F), scsi_dmaget(9F), buf(9S), scsi_pkt(9S)


Writing Device Drivers

NOTES

The scsi_pktalloc(), scsi_pktfree(), scsi_resalloc(), and scsi_resfree()
functions are obsolete and will be discontinued in a future release. The
scsi_pktalloc() and scsi_resalloc() functions have been replaced by
scsi_init_pkt(9F). The scsi_pktfree() and scsi_resfree() functions have
been replaced by scsi_destroy_pkt(9F).

January 16, 2006 SCSI_PKTALLOC(9F)