1tran_init_pkt(9E) Driver Entry Points tran_init_pkt(9E)
2
6 tran_init_pkt, tran_destroy_pkt - SCSI HBA packet preparation and deal‐
7 location
8
10 #include <sys/scsi/scsi.h>
11 struct scsi_pkt *prefixtran_init_pkt(struct scsi_address *ap,
13 struct scsi_pkt *pkt, struct buf *bp, int cmdlen,
14 int statuslen, int tgtlen, intflags, int (*callback,
15 caddr_t),caddr_t arg);
16 void prefixtran_destroy_pkt(struct scsi_address *ap,
19 struct scsi_pkt *pkt);
20
23 Solaris architecture specific (Solaris DDI).
24
26 ap Pointer to a scsi_address(9S) structure.
27 pkt Pointer to a scsi_pkt(9S) structure allocated in an ear‐
30 lier call, or NULL.
31 bp Pointer to a buf(9S) structure if DMA resources are to be
34 allocated for the pkt, or NULL.
35 cmdlen The required length for the SCSI command descriptor block
38 (CDB) in bytes.
39 statuslen The required length for the SCSI status completion block
42 (SCB) in bytes.
43 tgtlen The length of the packet private area within the scsi_pkt
46 to be allocated on behalf of the SCSI target driver.
47 flags Flags for creating the packet.
50 callback Pointer to either NULL_FUNC or SLEEP_FUNC.
53 arg Always NULL.
56
59 The tran_init_pkt() and tran_destroy_pkt() vectors in the scsi_hba_tran
60 structure must be initialized during the HBA driver's attach(9E) to
61 point to HBA entry points to be called when a target driver calls
62 scsi_init_pkt(9F) and scsi_destroy_pkt(9F).
63 tran_init_pkt()
65 tran_init_pkt() is the entry point into the HBA which is used to allo‐
66 cate and initialize a scsi_pkt structure on behalf of a SCSI target
67 driver. If pkt is NULL, the HBA driver must use scsi_hba_pkt_alloc(9F)
68 to allocate a new scsi_pkt structure.
69 If bp is non-NULL, the HBA driver must allocate appropriate DMA
72 resources for the pkt, for example, throughddi_dma_buf_setup(9F) or
73 ddi_dma_buf_bind_handle(9F).
74 If the PKT_CONSISTENT bit is set in flags, the buffer was allocated by
77 scsi_alloc_consistent_buf(9F). For packets marked with PKT_CONSISTENT,
78 the HBA driver must synchronize any cached data transfers before call‐
79 ing the target driver's command completion callback.
80 If the PKT_DMA_PARTIAL bit is set in flags, the HBA driver should set
83 up partial data transfers, such as setting the DDI_DMA_PARTIAL bit in
84 the flags argument if interfaces such as ddi_dma_buf_setup(9F) or
85 ddi_dma_buf_bind_handle(9F) are used.
86 If only partial DMA resources are available, tran_init_pkt() must
89 return in the pkt_resid field of pkt the number of bytes of DMA
90 resources not allocated.
91 If both pkt and bp are non-NULL, if the PKT_DMA_PARTIAL bit is set
94 in flags, and if DMA resources have already been allocated for the
95 pkt with a previous call to tran_init_pkt() that returned a non-zero
96 pkt_resid field, this request is to move the DMA resources for the sub‐
97 sequent piece of the transfer.
98 The contents of scsi_address(9S) pointed to by ap are copied into the
101 pkt_address field of the scsi_pkt(9S) by scsi_hba_pkt_alloc(9F).
102 tgtlen is the length of the packet private area in the scsi_pkt struc‐
105 ture to be allocated on behalf of the SCSI target driver.
106 statuslen is the required length for the SCSI status completion block.
109 If the requested status length is greater than or equal to
110 sizeof(struct scsi_arq_status) and the auto_rqsense capability has
111 been set, automatic request sense (ARS) is enabled for this packet. If
112 the status length is less than sizeof(struct scsi_arq_status), auto‐
113 matic request sense must be disabled for this pkt.
114 If the HBA driver is not capable of disabling ARQ on a per-packet basis
117 and tran_init_pkt() is called with a statuslen that is less than
118 sizeof(struct scsi_arq_status), the driver's tran_init_pkt routine
119 should allocate at least sizeof(struct scsi_arq_status). If an ARS is
120 needed, upon successful ARS done by the HBA driver, the driver must
121 copy the sense data over and set STAT_ARQ_DONE in pkt_state.
122 cmdlen is the required length for the SCSI command descriptor block.
125 Note: tgtlen, statuslen, and cmdlen are used only when the HBA driver
128 allocates the scsi_pkt(9S), in other words, when pkt is NULL.
129 callback indicates what the allocator routines should do when resources
132 are not available:
133 NULL_FUNC Do not wait for resources. Return a NULL pointer.
135 SLEEP_FUNC Wait indefinitely for resources.
138 tran_destroy_pkt()
141 tran_destroy_pkt() is the entry point into the HBA that must free all
142 of the resources that were allocated to the scsi_pkt(9S) structure dur‐
143 ing tran_init_pkt().
144
146 tran_init_pkt() must return a pointer to a scsi_pkt(9S) structure on
147 success, or NULL on failure.
148 If pkt is NULL on entry, and tran_init_pkt() allocated a packet
151 throughscsi_hba_pkt_alloc(9F) but was unable to allocate DMA resources,
152 tran_init_pkt() must free the packet through scsi_hba_pkt_free(9F)
153 before returning NULL.
154
156 attach(9E), tran_setup_pkt(9E), tran_sync_pkt(9E), biodone(9F), bioer‐
157 ror(9F), ddi_dma_buf_bind_handle(9F), ddi_dma_buf_setup(9F),
158 kmem_cache_create(9F), scsi_alloc_consistent_buf(9F),
159 scsi_destroy_pkt(9F), scsi_hba_attach(9F), scsi_hba_pkt_alloc(9F),
160 scsi_hba_pkt_free(9F), scsi_init_pkt(9F), buf(9S), scsi_address(9S),
161 scsi_hba_tran(9S), scsi_pkt(9S)
162 Writing Device Drivers
165
167 If a DMA allocation request fails with DDI_DMA_NOMAPPING, indicate the
168 error by calling bioerror(9F) with bp and an error code of EFAULT.
169 If a DMA allocation request fails with DDI_DMA_TOOBIG, indicate the
172 error by calling bioerror(9F) with bp and an error code of EINVAL.
173 For increased performance, an HBA driver may want to provide a cache
176 for scsi_pkt(9S) allocation. This cache should be implemented by the
177 HBA driver providing a tran_setup_pkt(9E) implementation. Implementing
178 this cache by direct use of kmem_cache_create(9F) adds a compile-time
179 dependency on scsi_pkt() size, which is illegal.
180SunOS 5.11 11 Jan 2009 tran_init_pkt(9E)