1tran_setup_pkt(9E) Driver Entry Points tran_setup_pkt(9E)
2
6 tran_setup_pkt, tran_teardown_pkt, tran_pkt_constructor,
7 tran_pkt_destructor - SCSI HBA packet allocation and deallocation
8
10 #include <sys/scsi/scsi.h>
11 struct scsi_pkt *prefix_tran_setup_pkt(struct scsi_pkt *pkt,
13 int (*callback) (caddr_t), caddr_t arg);
14 void prefix_tran_teardown_pkt(struct scsi_pkt *pkt);
17 int prefix_tran_pkt_constructor(struct scsi_pkt *pkt,
20 scsi_hba_tran_t *tranp, int kmflags);
21 void prefix_tran_pkt_destructor(struct scsi_pkt *pkt,
24 struct scsi_hba_tran_t *tranp);
25
28 Solaris architecture specific (Solaris DDI).
29
31 pkt Pointer to the scsi_pkt(9S) structure.
32 flags Flags for associating DMA resources with the packet.
35 callback Pointer to either NULL_FUNC or SLEEP_FUNC.
38 arg Always NULL.
41 kmflags Either KM_SLEEP or KM_NOSLEEP.
44
47 The tran_setup_pkt() and tran_destroy_pkt() vectors in the
48 scsi_hba_tran(9S) structure are alternatives to the tran_init_pkt() and
49 tran_destroy_pkt() entry points. They are initialized during the HBA
50 driver's attach(9E) and they are used when a target driver calls
51 scsi_init_pkt(9F) and scsi_destroy_pkt(9F).
52 tran_setup_pkt()
54 The tran_setup_pkt() vector is the entry point into the HBA which is
55 used to initialize HBA specific information in a scsi_pkt structure on
56 behalf of a SCSI target driver. All fields documented in scsi_pkt(9S)
57 are initialized.
58 If the HBA driver chose not to preallocate memory for pkt_cdbp and/or
61 pkt_scbp, it must allocate the requested memory at this time and point
62 pkt_cdbp and pkt_scbp to the allocated memory.
63 An HBA driver which provides a tran_setup_pkt entry point inspects the
66 pkt_numcookies and pkt_cookies fields at tran_start time to set up the
67 transfer. If pkt_numcookies is zero, there are no DMA resources associ‐
68 ated with this packet. If pkt_numcookies is not zero, it indicates the
69 number of DMA cookies that pkt_cookies points to.
70 The pkt_tgtlen field contains the length of the packet private area
73 pointed to by pkt_private, allocated on behalf of the SCSI target
74 driver.
75 The pkt_scblen field contains the length of the SCSI status completion
78 block pointed to by pkt_scbp. If the status length is greater than or
79 equal to sizeof (struct scsi_arq_status) and the auto_rqsensecapability
80 has been set, automatic request sense (ARS) is enabled for this packet.
81 If the status lengthislessthansizeof (struct scsi_arq_status), auto‐
82 matic request sense should be disabled for this pkt if the HBA driver
83 is capable of disabling ARQ on a per-packet basis.
84 The pkt_cdblen field contains the length of the SCSI command descriptor
87 block.
88 The callback argument indicates what the allocator routines should do
91 when resources are not available:
92 NULL_FUNC Do not wait for resources. Return a NULL pointer.
94 SLEEP_FUNC Wait indefinitely for resources.
97 tran_teardown_pkt()
100 The tran_teardown_pkt() is the entry point into the HBA that must free
101 all of the resources that were allocated to the scsi_pkt(9S) structure
102 during tran_setup_pkt().
103 tran_pkt_constructor() tran_pkt_destructor()
105 When using tran_pkt_setup() and tran_pkt_teardown(), tran_pkt_construc‐
106 tor() and tran_pkt_destructor() are additional optional entry points
107 that perform the actions of a constructor and destructor. The construc‐
108 tor is called after the following fields in the scsi_pkt structure have
109 been initialized:
110 o pkt_address
112 o pkt_ha_private
114 o pkt_cdbp
116 o pkt_private
118 o pkt_scbp
120 o pkt_cdblen
122 o pkt_tgtlen
124 o pkt_scblen
126 Allocating and freeing a DMA handle are examples of something that
129 could be done in the constructor and destructor. See kmem_cache_cre‐
130 ate(9F) for additional restrictions on what actions can be performed in
131 a constructor and destructor.
132 HBA drivers that implement tran_setup_pkt() must signal scsi_pkt(9S)
135 completion by calling scsi_hba_pkt_comp(9F). Direct use of the
136 scsi_pkt pkt_comp field is not permitted and results in undefined
137 behavior.
138
140 tran_setup_pkt() must return zero on success, and -1 on failure.
141
143 attach(9E), tran_sync_pkt(9E), bioerror(9F), ddi_dma_buf_bind_han‐
144 dle(9F), kmem_cache_create(9F), scsi_alloc_consistent_buf(9F),
145 scsi_destroy_pkt(9F), scsi_hba_attach(9F), scsi_hba_pkt_alloc(9F),
146 scsi_hba_pkt_comp(9F), scsi_hba_pkt_free(9F), scsi_init_pkt(9F),
147 buf(9S), scsi_address(9S), scsi_hba_tran(9S), scsi_pkt(9S)
148 Writing Device Drivers
151SunOS 5.11 29 Jan 2009 tran_setup_pkt(9E)