1scsi_ifgetcap(9F)        Kernel Functions for Drivers        scsi_ifgetcap(9F)
2
3
4

NAME

6       scsi_ifgetcap, scsi_ifsetcap - get/set SCSI transport capability
7

SYNOPSIS

9       #include <sys/scsi/scsi.h>
10
11
12
13       int scsi_ifgetcap(struct scsi_address *ap, char *cap, int whom);
14
15
16       int scsi_ifsetcap(struct scsi_address *ap, char *cap, int value,
17            int whom);
18
19

INTERFACE LEVEL

21       Solaris DDI specific (Solaris DDI).
22

PARAMETERS

24       ap       Pointer to the scsi_address structure.
25
26
27       cap      Pointer to the string capability identifier.
28
29
30       value    Defines the new state of the capability.
31
32
33       whom     Determines  if  all  targets  or  only the specified target is
34                affected.
35
36

DESCRIPTION

38       The scsi_ifsetcap() function is used by target drivers to set the capa‐
39       bilities  of  the  host adapter driver. The cap pointer is a name-value
40       pair identified by a null-terminated character string and  the  integer
41       value  of the cap. The current value of the capability can be retrieved
42       with the scsi_ifgetcap() function. If the whom value is 0,  all  target
43       drivers  are affected. Otherwise, the scsi_address structure pointed to
44       by ap is the only target that is affected.
45
46
47       The driver should  confirm  that  scsi_ifsetcap()  and  scsi_ifsetcap()
48       functions  are  called  with a cap that points to a capability which is
49       supported by the device.
50
51
52       The following capabilities have been defined:
53
54       dma-max                 Maximum dma transfer size that is supported  by
55                               the host adapter.
56
57
58       dma-max-arch            Maximum  dma transfer size that is supported by
59                               system.  Takes  the  host  adapter  and  system
60                               architecture  into  account. This is useful for
61                               target drivers which  do  not  support  partial
62                               DMAs  on systems which do not have an IOMMU. In
63                               this case, the DMA can also be limited  by  the
64                               host   adapters   "scatter/gather"   list  con‐
65                               straints.
66
67                               The "dma-max-arch" capability can not  be  set.
68                               It  is  implemented  with this command and does
69                               not rely on a tran_getcap(9E) response from the
70                               HBA.
71
72
73       msg-out                 Message out capability that is supported by the
74                               host adapter: 0 disables, 1 enables.
75
76
77       disconnect              Disconnect capability that is supported by  the
78                               host adapter: 0 disables, 1 enables.
79
80
81       synchronous             Synchronous  data  transfer  capability that is
82                               supported by the host adapter:  0  disables,  1
83                               enables.
84
85
86       wide-xfer               Wide  transfer  capability that is supported by
87                               the host adapter: 0 disables, 1 enables.
88
89
90       parity                  Parity checking capability that is supported by
91                               host adapter: 0 disables, 1 enables.
92
93
94       initiator-id            Host bus address that is returned.
95
96
97       untagged-qing           Host  adapter capability that supports internal
98                               queueing of commands without tagged queueing: 0
99                               disables, 1 enables.
100
101
102       tagged-qing             Host  adapter capability that supports queuing:
103                               0 disables, 1 enables.
104
105
106       auto-rqsense            Host  adapter  capability  that  supports  auto
107                               request  sense on check conditions: 0 disables,
108                               1 enables.
109
110
111       sector-size             Capability that is set by the target driver  to
112                               inform the HBA of the granularity, in bytes, of
113                               the DMA breakup. The HBA DMA limit structure is
114                               set  to reflect the byte total of this setting.
115                               See          ddi_dma_lim_sparc(9S)           or
116                               ddi_dma_lim_x86(9S).  The sector-size should be
117                               set to the size of the  physical  disk  sector.
118                               The capability defaults to 512 bytes.
119
120
121       total-sectors           Capability  that is set by the target driver to
122                               inform the HBA of the total number  of  sectors
123                               on the device returned by the SCSI get capacity
124                               command. This capability must be set before the
125                               target driver ``gets'' the geometry capability.
126
127
128       geometry                Capability  that  returns the HBA geometry of a
129                               target disk. The target driver sets the  total-
130                               sectors capability before ``getting'' the geom‐
131                               etry capability. The geometry is returned as  a
132                               32-bit  value.  The upper 16 bits represent the
133                               number of heads per cylinder. The lower 16 bits
134                               represent  the number of sectors per track. The
135                               geometry capability cannot be ``set''.
136
137                               If geometry is not relevant or appropriate  for
138                               the  target disk, scsi_ifgetcap() can return -1
139                               to indicate that the geometry is  not  defined.
140                               For  example,  if the HBA BIOS supports Logical
141                               Block   Addressing   for   the   target   disk,
142                               scsi_ifgetcap()   returns   -1.   Attempts   to
143                               retreive the "virtual geometry" from the target
144                               driver, such as the DKIOCG_VIRTGEOM ioctl, will
145                               fail. See dkio(7I) for more  information  about
146                               DKIOCG_VIRTGEOM.
147
148
149       reset-notification      Host adapter capability that supports bus reset
150                               notification:  0  disables,  1   enables.   See
151                               scsi_reset_notify(9F).
152
153
154       linked-cmds             Host  adapter  capability  that supports linked
155                               commands: 0 disables, 1 enables.
156
157
158       qfull-retries           Capability that enables or disables QUEUE  FULL
159                               handling.  If  0, the HBA will not retry a com‐
160                               mand when a QUEUE FULL status is  returned.  If
161                               the  value  is  greater  than 0, the HBA driver
162                               retries the command a specified number of times
163                               at  an  interval determined by the qfull-retry-
164                               interval. The range for qfull-retries is 0-255.
165
166
167       qfull-retry-interval    Capability that sets the retry interval in mil‐
168                               liseconds  (ms)  for  commands completed with a
169                               QUEUE FULL status. The range  for  qfull-retry-
170                               intervals is 0-1000 ms.
171
172
173       lun-reset               Capability that is created with a value of zero
174                               by HBA drivers that support the RESET_LUN  flag
175                               in  the  tran_reset(9E) function. If it exists,
176                               the lun-reset value can be set to 1  by  target
177                               drivers  to allow the use of LOGICAL UNIT RESET
178                               on a specific  target  instance.  If  lun-reset
179                               does   not  exist  or  has  a  value  of  zero,
180                               scsi_reset(9F) is prevented  from  passing  the
181                               RESET_LUN  flag to tran_reset() function of the
182                               HBA driver. If lun-reset exists and has a value
183                               of  1,  the  tran_reset()  function  of the HBA
184                               driver can be called with the RESET_LUN flag.
185
186
187       interconnect-type       Capability held in  the  tran_interconnect_type
188                               element  of struct scsi_hba_tran that indicates
189                               the HBA transport interconnect type . The inte‐
190                               ger  value  of  the  interconnect  type  of the
191                               transport is defined in the  services.h  header
192                               file.
193
194
195       max-cdb-length          Host  adapter  capability  of  the maximum sup‐
196                               ported CDB (Command Descriptor  Block)  length.
197                               The  target  driver  asks for the capability at
198                               attach time. If the  HBA  driver  supports  the
199                               capability,  the  maximum  length of the CDB is
200                               returned in bytes. The target driver  can  then
201                               use  that  value to determine which CDB is used
202                               for the HBA.
203
204                               If the HBA driver does not support the max-cdb-
205                               length  capability,  the  default  value of the
206                               target driver is used for  the  CDB  determina‐
207                               tion.
208
209

RETURN VALUES

211       The scsi_ifsetcap() function returns:
212
213       1        If the capability was successfully set to the new value.
214
215
216       0        If the capability is not variable.
217
218
219       −1       If  the  capability was not defined, or setting the capability
220                to a new value failed.
221
222
223
224       The scsi_ifgetcap() function returns the current value of a capability,
225       or:
226
227       −1       If the capability was not defined.
228
229

EXAMPLES

231       Example 1 Using scsi_ifgetcap()
232
233         if (scsi_ifgetcap(&sd->sd_address, "auto-rqsense", 1) == 1) {
234            un->un_arq_enabled = 1;
235         } else {
236            un->un_arq_enabled =
237                ((scsi_ifsetcap(&sd->sd_address, "auto-rqsense", 1, 1) == 1) ?
238                      1 : 0);
239         }
240
241         if (scsi_ifsetcap(&devp->sd_address, "tagged-qing", 1, 1) == 1) {
242                un->un_dp->options |= SD_QUEUEING;
243                un->un_throttle = MAX_THROTTLE;
244         } else if (scsi_ifgetcap(&devp->sd_address, "untagged-qing", 0) == 1) {
245                un->un_dp->options |= SD_QUEUEING;
246                un->un_throttle = 3;
247         } else {
248                un->un_dp->options &= ~SD_QUEUEING;
249                un->un_throttle = 1;
250         }
251
252

CONTEXT

254       These functions can be called from user, interrupt, or kernel context.
255

ATTRIBUTES

257       See attributes(5) for descriptions of the following attributes:
258
259
260
261
262       ┌─────────────────────────────┬─────────────────────────────┐
263       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
264       ├─────────────────────────────┼─────────────────────────────┤
265       │Interface Stability          │Committed                    │
266       └─────────────────────────────┴─────────────────────────────┘
267

SEE ALSO

269       tran_reset(9E),       scsi_hba_lookup_capstr(9F),       scsi_reset(9F),
270       scsi_reset_notify(9F),   ddi_dma_lim_sparc(9S),    ddi_dma_lim_x86(9S),
271       scsi_address(9S), scsi_arq_status(9S)
272
273
274       Writing Device Drivers
275
276
277
278SunOS 5.11                        16 Oct 2007                scsi_ifgetcap(9F)
Impressum