tran_setup_pkt(9e)

1tran_setup_pkt(9E)            Driver Entry Points           tran_setup_pkt(9E)
2
3
4

NAME

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

SYNOPSIS

10       #include <sys/scsi/scsi.h>
11
12       struct scsi_pkt *prefix_tran_setup_pkt(struct scsi_pkt *pkt,
13            int (*callback) (caddr_t), caddr_t arg);
14
15
16       void prefix_tran_teardown_pkt(struct scsi_pkt *pkt);
17
18
19       int prefix_tran_pkt_constructor(struct scsi_pkt *pkt,
20            scsi_hba_tran_t *tranp, int kmflags);
21
22
23       void prefix_tran_pkt_destructor(struct scsi_pkt *pkt,
24            struct scsi_hba_tran_t *tranp);
25
26

INTERFACE LEVEL

28       Solaris architecture specific (Solaris DDI).
29

PARAMETERS

31       pkt         Pointer to the scsi_pkt(9S) structure.
32
33
34       flags       Flags for associating DMA resources with the packet.
35
36
37       callback    Pointer to either NULL_FUNC or SLEEP_FUNC.
38
39
40       arg         Always NULL.
41
42
43       kmflags     Either KM_SLEEP or KM_NOSLEEP.
44
45

DESCRIPTION

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
53   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
59
60       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
64
65       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
71
72       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
76
77       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
85
86       The pkt_cdblen field contains the length of the SCSI command descriptor
87       block.
88
89
90       The callback argument indicates what the allocator routines  should  do
91       when resources are not available:
92
93       NULL_FUNC     Do not wait for resources. Return a NULL pointer.
94
95
96       SLEEP_FUNC    Wait indefinitely for resources.
97
98
99   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
104   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
111           o      pkt_address
112
113           o      pkt_ha_private
114
115           o      pkt_cdbp
116
117           o      pkt_private
118
119           o      pkt_scbp
120
121           o      pkt_cdblen
122
123           o      pkt_tgtlen
124
125           o      pkt_scblen
126
127
128       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
133
134       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

RETURN VALUES

140       tran_setup_pkt() must return zero on success, and -1 on failure.
141

NAME

SYNOPSIS

INTERFACE LEVEL

PARAMETERS

DESCRIPTION

RETURN VALUES

SEE ALSO