Driver Entry Points traninitpkt(9E)
NAME
traninitpkt, trandestroypkt - SCSI HBA packet prepara-
tion and deallocation
SYNOPSIS
#include
struct scsipkt *prefixtraninitpkt(struct scsiaddress *ap,
struct scsipkt *pkt, struct buf *bp, int cmdlen,
int statuslen, int tgtlen, intflags, int (*callback,
caddrt),caddrt arg);
void prefixtrandestroypkt(struct scsiaddress *ap,
struct scsipkt *pkt);
INTERFACE LEVEL
Solaris architecture specific (Solaris DI).
PARAMETERS
ap Pointer to a scsiaddress(9S) structure.
pkt Pointer to a scsipkt(9S) structure allocated
in an earlier call, or NUL.
bp Pointer to a buf(9S) structure if DMA resources
are to be allocated for the pkt, or NUL.
cmdlen The required length for the SCSI command
descriptor block (CDB) in bytes.
statuslen The required length for the SCSI status comple-
tion block (SCB) in bytes.
tgtlen The length of the packet private area within
the scsipkt to be allocated on behalf of the
SCSI target driver.
flags Flags for creating the packet.
callback Pointer to either NULFUNC or SLEPFUNC.
SunOS 5.11 Last change: 11 Jan 2009 1
Driver Entry Points traninitpkt(9E)
arg Always NUL.
DESCRIPTION
The traninitpkt() and trandestroypkt() vectors in the
scsihbatran structure must be initialized during the HBA
driver's attach(9E) to point to HBA entry points to be
called when a target driver calls scsiinitpkt(9F) and
scsidestroypkt(9F).
traninitpkt()
traninitpkt() is the entry point into the HBA which is
used to allocate and initialize a scsipkt structure on
behalf of a SCSI target driver. If pkt is NUL, the HBA
driver must use scsihbapktalloc(9F) to allocate a new
scsipkt structure.
If bp is non-NUL, the HBA driver must allocate appropriate
DMA resources for the pkt, for example,
throughddidmabufsetup(9F) or ddidmabufbindhandle(9F).
If the PKTCONSISTENT bit is set in flags, the buffer was
allocated by scsiallocconsistentbuf(9F). For packets
marked with PKTCONSISTENT, the HBA driver must synchronize
any cached data transfers before calling the target driver's
command completion callback.
If the PKTDMAPARTIAL bit is set in flags, the HBA driver
should set up partial data transfers, such as setting the
DIDMAPARTIAL bit in the flags argument if interfaces such
as ddidmabufsetup(9F) or ddidmabufbindhandle(9F) are
used.
If only partial DMA resources are available,
traninitpkt() must return in the pktresid field of pkt
the number of bytes of DMA resources not allocated.
If both pkt and bp are non-NUL, if the PKTDMAPARTIAL
bit is set in flags, and if DMA resources have already been
allocated for the pkt with a previous call to
traninitpkt() that returned a non-zero pktresid field,
this request is to move the DMA resources for the subsequent
piece of the transfer.
The contents of scsiaddress(9S) pointed to by ap are copied
into the pktaddress field of the scsipkt(9S) by
SunOS 5.11 Last change: 11 Jan 2009 2
Driver Entry Points traninitpkt(9E)
scsihbapktalloc(9F).
tgtlen is the length of the packet private area in the
scsipkt structure to be allocated on behalf of the SCSI
target driver.
statuslen is the required length for the SCSI status comple-
tion block. If the requested status length is greater than
or equal to sizeof(struct scsiarqstatus) and the
autorqsense capability has been set, automatic request
sense (ARS) is enabled for this packet. If the status length
is less than sizeof(struct scsiarqstatus), automatic
request sense must be disabled for this pkt.
If the HBA driver is not capable of disabling ARQ on a per-
packet basis and traninitpkt() is called with a statuslen
that is less than sizeof(struct scsiarqstatus), the
driver's traninitpkt routine should allocate at least
sizeof(struct scsiarqstatus). If an ARS is needed, upon
successful ARS done by the HBA driver, the driver must copy
the sense data over and set STATARQDONE in pktstate.
cmdlen is the required length for the SCSI command descrip-
tor block.
Note: tgtlen, statuslen, and cmdlen are used only when the
HBA driver allocates the scsipkt(9S), in other words, when
pkt is NUL.
callback indicates what the allocator routines should do
when resources are not available:
NULFUNC Do not wait for resources. Return a NUL
pointer.
SLEPFUNC Wait indefinitely for resources.
trandestroypkt()
trandestroypkt() is the entry point into the HBA that must
free all of the resources that were allocated to the
scsipkt(9S) structure during traninitpkt().
RETURN VALUES
SunOS 5.11 Last change: 11 Jan 2009 3
Driver Entry Points traninitpkt(9E)
traninitpkt() must return a pointer to a scsipkt(9S)
structure on success, or NUL on failure.
If pkt is NUL on entry, and traninitpkt() allocated a
packet throughscsihbapktalloc(9F) but was unable to allo-
cate DMA resources, traninitpkt() must free the packet
through scsihbapktfree(9F) before returning NUL.
SEE ALSO
attach(9E), transetuppkt(9E), transyncpkt(9E),
biodone(9F), bioerror(9F), ddidmabufbindhandle(9F),
ddidmabufsetup(9F), kmemcachecreate(9F),
scsiallocconsistentbuf(9F), scsidestroypkt(9F),
scsihbaattach(9F), scsihbapktalloc(9F),
scsihbapktfree(9F), scsiinitpkt(9F), buf(9S),
scsiaddress(9S), scsihbatran(9S), scsipkt(9S)
Writing Device Drivers
NOTES
If a DMA allocation request fails with DIDMANOMAPING,
indicate the error by calling bioerror(9F) with bp and an
error code of EFAULT.
If a DMA allocation request fails with DIDMATOBIG, indi-
cate the error by calling bioerror(9F) with bp and an error
code of EINVAL.
For increased performance, an HBA driver may want to provide
a cache for scsipkt(9S) allocation. This cache should be
implemented by the HBA driver providing a transetuppkt(9E)
implementation. Implementing this cache by direct use of
kmemcachecreate(9F) adds a compile-time dependency on
scsipkt() size, which is illegal.
SunOS 5.11 Last change: 11 Jan 2009 4
|
