|
Lines 36-42
Link Here
|
| 36 |
<para>and from the CAM code itself (by Justing T. Gibbs, see |
36 |
<para>and from the CAM code itself (by Justing T. Gibbs, see |
| 37 |
<filename>/sys/cam/*</filename>). When some solution looked the |
37 |
<filename>/sys/cam/*</filename>). When some solution looked the |
| 38 |
most logical and was essentially verbatim extracted from the code |
38 |
most logical and was essentially verbatim extracted from the code |
| 39 |
by Justin Gibbs, I marked it as "recommended".</para> |
39 |
by Justin Gibbs, I marked it as <quote>recommended</quote>.</para> |
| 40 |
|
40 |
|
| 41 |
<para>The document is illustrated with examples in |
41 |
<para>The document is illustrated with examples in |
| 42 |
pseudo-code. Although sometimes the examples have many details |
42 |
pseudo-code. Although sometimes the examples have many details |
|
Lines 174-180
Link Here
|
| 174 |
</para></listitem> |
174 |
</para></listitem> |
| 175 |
|
175 |
|
| 176 |
<listitem><para>driver_name - the name of the actual driver, |
176 |
<listitem><para>driver_name - the name of the actual driver, |
| 177 |
such as "ncr" or "wds"</para></listitem> |
177 |
such as <quote>ncr</quote> or <quote>wds</quote>.</para></listitem> |
| 178 |
|
178 |
|
| 179 |
<listitem><para><structName>softc</structName> - pointer to the |
179 |
<listitem><para><structName>softc</structName> - pointer to the |
| 180 |
driver's internal descriptor for this SCSI card. This |
180 |
driver's internal descriptor for this SCSI card. This |
|
Lines 182-188
Link Here
|
| 182 |
data.</para></listitem> |
182 |
data.</para></listitem> |
| 183 |
|
183 |
|
| 184 |
<listitem><para>unit - the controller unit number, for example |
184 |
<listitem><para>unit - the controller unit number, for example |
| 185 |
for controller "wds0" this number will be |
185 |
for controller <quote>wds0</quote> this number will be |
| 186 |
0</para></listitem> |
186 |
0</para></listitem> |
| 187 |
|
187 |
|
| 188 |
<listitem><para>max_dev_transactions - maximal number of |
188 |
<listitem><para>max_dev_transactions - maximal number of |
|
Lines 237-243
Link Here
|
| 237 |
|
237 |
|
| 238 |
<para>A typical example of such an event is a device reset. Each |
238 |
<para>A typical example of such an event is a device reset. Each |
| 239 |
transaction and event identifies the devices to which it applies |
239 |
transaction and event identifies the devices to which it applies |
| 240 |
by the means of "path". The target-specific events normally |
240 |
by the means of <quote>path</quote>. The target-specific events normally |
| 241 |
occur during a transaction with this device. So the path from |
241 |
occur during a transaction with this device. So the path from |
| 242 |
that transaction may be re-used to report this event (this is |
242 |
that transaction may be re-used to report this event (this is |
| 243 |
safe because the event path is copied in the event reporting |
243 |
safe because the event path is copied in the event reporting |
|
Lines 273-282
Link Here
|
| 273 |
(<function>cam_sim_path(sim)</function>)</para></listitem> |
273 |
(<function>cam_sim_path(sim)</function>)</para></listitem> |
| 274 |
|
274 |
|
| 275 |
<listitem><para>SCSI target number of the device (CAM_TARGET_WILDCARD |
275 |
<listitem><para>SCSI target number of the device (CAM_TARGET_WILDCARD |
| 276 |
means "all devices")</para></listitem> |
276 |
means <quote>all devices</quote>)</para></listitem> |
| 277 |
|
277 |
|
| 278 |
<listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means |
278 |
<listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means |
| 279 |
"all LUNs")</para></listitem> |
279 |
<quote>all LUNs</quote>)</para></listitem> |
| 280 |
</itemizedlist> |
280 |
</itemizedlist> |
| 281 |
|
281 |
|
| 282 |
<para>If the driver can not allocate this path it will not be able to |
282 |
<para>If the driver can not allocate this path it will not be able to |
|
Lines 324-336
Link Here
|
| 324 |
|
324 |
|
| 325 |
<para>Do some action on request of the CAM subsystem. Sim |
325 |
<para>Do some action on request of the CAM subsystem. Sim |
| 326 |
describes the SIM for the request, CCB is the request |
326 |
describes the SIM for the request, CCB is the request |
| 327 |
itself. CCB stands for "CAM Control Block". It is a union of |
327 |
itself. CCB stands for <quote>CAM Control Block</quote>. It is a union of |
| 328 |
many specific instances, each describing arguments for some type |
328 |
many specific instances, each describing arguments for some type |
| 329 |
of transactions. All of these instances share the CCB header |
329 |
of transactions. All of these instances share the CCB header |
| 330 |
where the common part of arguments is stored.</para> |
330 |
where the common part of arguments is stored.</para> |
| 331 |
|
331 |
|
| 332 |
<para>CAM supports the SCSI controllers working in both initiator |
332 |
<para>CAM supports the SCSI controllers working in both initiator |
| 333 |
("normal") mode and target (simulating a SCSI device) mode. Here |
333 |
(<quote>normal</quote>) mode and target (simulating a SCSI device) mode. Here |
| 334 |
we only consider the part relevant to the initiator mode.</para> |
334 |
we only consider the part relevant to the initiator mode.</para> |
| 335 |
|
335 |
|
| 336 |
<para>There are a few function and macros (in other words, |
336 |
<para>There are a few function and macros (in other words, |
|
Lines 398-404
Link Here
|
| 398 |
are a surprising number of status values defined in |
398 |
are a surprising number of status values defined in |
| 399 |
<filename>/sys/cam/cam.h</filename> which should be able to |
399 |
<filename>/sys/cam/cam.h</filename> which should be able to |
| 400 |
represent the status of a request in great detail. More |
400 |
represent the status of a request in great detail. More |
| 401 |
interesting yet, the status is in fact a "bitwise or" of an |
401 |
interesting yet, the status is in fact a <quote>bitwise or</quote> of an |
| 402 |
enumerated status value (the lower 6 bits) and possible |
402 |
enumerated status value (the lower 6 bits) and possible |
| 403 |
additional flag-like bits (the upper bits). The enumerated |
403 |
additional flag-like bits (the upper bits). The enumerated |
| 404 |
values will be discussed later in more detail. The summary of |
404 |
values will be discussed later in more detail. The summary of |
|
Lines 447-453
Link Here
|
| 447 |
allowed to sleep, so all the synchronization for resource access |
447 |
allowed to sleep, so all the synchronization for resource access |
| 448 |
must be done using SIM or device queue freezing. Besides the |
448 |
must be done using SIM or device queue freezing. Besides the |
| 449 |
aforementioned flags the CAM subsystem provides functions |
449 |
aforementioned flags the CAM subsystem provides functions |
| 450 |
<function>xpt_selease_simq()</function> and |
450 |
<function>xpt_release_simq()</function> and |
| 451 |
<function>xpt_release_devq()</function> to unfreeze the queues |
451 |
<function>xpt_release_devq()</function> to unfreeze the queues |
| 452 |
directly, without passing a CCB to CAM.</para> |
452 |
directly, without passing a CCB to CAM.</para> |
| 453 |
|
453 |
|
|
Lines 497-503
Link Here
|
| 497 |
<listitem><para><emphasis>XPT_SCSI_IO</emphasis> - execute an |
497 |
<listitem><para><emphasis>XPT_SCSI_IO</emphasis> - execute an |
| 498 |
I/O transaction</para> |
498 |
I/O transaction</para> |
| 499 |
|
499 |
|
| 500 |
<para>The instance "struct ccb_scsiio csio" of the union ccb is |
500 |
<para>The instance <quote>struct ccb_scsiio csio</quote> of the union ccb is |
| 501 |
used to transfer the arguments. They are:</para> |
501 |
used to transfer the arguments. They are:</para> |
| 502 |
|
502 |
|
| 503 |
<itemizedlist> |
503 |
<itemizedlist> |
|
Lines 785-792
Link Here
|
| 785 |
}</programlisting> |
785 |
}</programlisting> |
| 786 |
</listitem> |
786 |
</listitem> |
| 787 |
|
787 |
|
| 788 |
<listitem><para><emphasis>XPT_RESET_DEV</emphasis> - send the SCSI "BUS |
788 |
<listitem><para><emphasis>XPT_RESET_DEV</emphasis> - send the SCSI <quote>BUS |
| 789 |
DEVICE RESET" message to a device</para> |
789 |
DEVICE RESET</quote> message to a device</para> |
| 790 |
|
790 |
|
| 791 |
<para>There is no data transferred in CCB except the header and |
791 |
<para>There is no data transferred in CCB except the header and |
| 792 |
the most interesting argument of it is target_id. Depending on |
792 |
the most interesting argument of it is target_id. Depending on |
|
Lines 877-884
Link Here
|
| 877 |
<listitem><para><emphasis>XPT_ABORT</emphasis> - abort the specified |
877 |
<listitem><para><emphasis>XPT_ABORT</emphasis> - abort the specified |
| 878 |
CCB</para> |
878 |
CCB</para> |
| 879 |
|
879 |
|
| 880 |
<para>The arguments are transferred in the instance "struct |
880 |
<para>The arguments are transferred in the instance <quote>struct |
| 881 |
ccb_abort cab" of the union ccb. The only argument field in it |
881 |
ccb_abort cab</quote> of the union ccb. The only argument field in it |
| 882 |
is:</para> |
882 |
is:</para> |
| 883 |
|
883 |
|
| 884 |
<para><emphasis>abort_ccb</emphasis> - pointer to the CCB to be |
884 |
<para><emphasis>abort_ccb</emphasis> - pointer to the CCB to be |
|
Lines 1037-1043
Link Here
|
| 1037 |
<listitem><para><emphasis>XPT_SET_TRAN_SETTINGS</emphasis> - explicitly |
1037 |
<listitem><para><emphasis>XPT_SET_TRAN_SETTINGS</emphasis> - explicitly |
| 1038 |
set values of SCSI transfer settings</para> |
1038 |
set values of SCSI transfer settings</para> |
| 1039 |
|
1039 |
|
| 1040 |
<para>The arguments are transferred in the instance "struct ccb_trans_setting cts" |
1040 |
<para>The arguments are transferred in the instance <quote>struct ccb_trans_setting cts</quote> |
| 1041 |
of the union ccb:</para> |
1041 |
of the union ccb:</para> |
| 1042 |
|
1042 |
|
| 1043 |
<itemizedlist> |
1043 |
<itemizedlist> |
|
Lines 1096-1103
Link Here
|
| 1096 |
|
1096 |
|
| 1097 |
<para>The current settings are, as the name says, |
1097 |
<para>The current settings are, as the name says, |
| 1098 |
current. Changing them means that the parameters must be |
1098 |
current. Changing them means that the parameters must be |
| 1099 |
re-negotiated on the next transfer. Again, these "new current |
1099 |
re-negotiated on the next transfer. Again, these <quote>new current |
| 1100 |
settings" are not supposed to be forced on the device, just they |
1100 |
settings</quote> are not supposed to be forced on the device, just they |
| 1101 |
are used as the initial step of negotiations. Also they must be |
1101 |
are used as the initial step of negotiations. Also they must be |
| 1102 |
limited by actual capabilities of the SCSI controller: for |
1102 |
limited by actual capabilities of the SCSI controller: for |
| 1103 |
example, if the SCSI controller has 8-bit bus and the request |
1103 |
example, if the SCSI controller has 8-bit bus and the request |
|
Lines 1121-1127
Link Here
|
| 1121 |
in effect</para></listitem> |
1121 |
in effect</para></listitem> |
| 1122 |
|
1122 |
|
| 1123 |
<listitem><para><emphasis>goal</emphasis> - those requested by |
1123 |
<listitem><para><emphasis>goal</emphasis> - those requested by |
| 1124 |
setting of the "current" parameters</para></listitem> |
1124 |
setting of the <quote>current</quote> parameters</para></listitem> |
| 1125 |
</itemizedlist> |
1125 |
</itemizedlist> |
| 1126 |
|
1126 |
|
| 1127 |
<para>The code looks like:</para> |
1127 |
<para>The code looks like:</para> |
|
Lines 1207-1214
Link Here
|
| 1207 |
SCSI transfer settings</para> |
1207 |
SCSI transfer settings</para> |
| 1208 |
|
1208 |
|
| 1209 |
<para>This operations is the reverse of |
1209 |
<para>This operations is the reverse of |
| 1210 |
XPT_SET_TRAN_SETTINGS. Fill up the CCB instance "struct |
1210 |
XPT_SET_TRAN_SETTINGS. Fill up the CCB instance <quote>struct |
| 1211 |
ccb_trans_setting cts" with data as requested by the flags |
1211 |
ccb_trans_setting cts</quote> with data as requested by the flags |
| 1212 |
CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both |
1212 |
CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both |
| 1213 |
are set then the existing drivers return the current |
1213 |
are set then the existing drivers return the current |
| 1214 |
settings). Set all the bits in the valid field.</para></listitem> |
1214 |
settings). Set all the bits in the valid field.</para></listitem> |
|
Lines 1216-1223
Link Here
|
| 1216 |
<listitem><para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate logical |
1216 |
<listitem><para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate logical |
| 1217 |
(BIOS) geometry of the disk</para> |
1217 |
(BIOS) geometry of the disk</para> |
| 1218 |
|
1218 |
|
| 1219 |
<para>The arguments are transferred in the instance "struct |
1219 |
<para>The arguments are transferred in the instance <quote>struct |
| 1220 |
ccb_calc_geometry ccg" of the union ccb:</para> |
1220 |
ccb_calc_geometry ccg</quote> of the union ccb:</para> |
| 1221 |
|
1221 |
|
| 1222 |
<itemizedlist> |
1222 |
<itemizedlist> |
| 1223 |
|
1223 |
|
|
Lines 1269-1275
Link Here
|
| 1269 |
|
1269 |
|
| 1270 |
<para>This gives the general idea, the exact calculation depends |
1270 |
<para>This gives the general idea, the exact calculation depends |
| 1271 |
on the quirks of the particular BIOS. If BIOS provides no way |
1271 |
on the quirks of the particular BIOS. If BIOS provides no way |
| 1272 |
set the "extended translation" flag in EEPROM this flag should |
1272 |
set the <quote>extended translation</quote> flag in EEPROM this flag should |
| 1273 |
normally be assumed equal to 1. Other popular geometries |
1273 |
normally be assumed equal to 1. Other popular geometries |
| 1274 |
are:</para> |
1274 |
are:</para> |
| 1275 |
|
1275 |
|
|
Lines 1286-1293
Link Here
|
| 1286 |
words get the SIM driver and SCSI controller (also known as HBA |
1286 |
words get the SIM driver and SCSI controller (also known as HBA |
| 1287 |
- Host Bus Adapter) properties</para> |
1287 |
- Host Bus Adapter) properties</para> |
| 1288 |
|
1288 |
|
| 1289 |
<para>The properties are returned in the instance "struct |
1289 |
<para>The properties are returned in the instance <quote>struct |
| 1290 |
ccb_pathinq cpi" of the union ccb:</para> |
1290 |
ccb_pathinq cpi</quote> of the union ccb:</para> |
| 1291 |
|
1291 |
|
| 1292 |
<itemizedlist> |
1292 |
<itemizedlist> |
| 1293 |
|
1293 |
|
|
Lines 1534-1540
Link Here
|
| 1534 |
|
1534 |
|
| 1535 |
<para>The conditions handled by the interrupt routine and the |
1535 |
<para>The conditions handled by the interrupt routine and the |
| 1536 |
details depend very much on the hardware. We consider the set of |
1536 |
details depend very much on the hardware. We consider the set of |
| 1537 |
"typical" conditions.</para> |
1537 |
<quote>typical</quote> conditions.</para> |
| 1538 |
|
1538 |
|
| 1539 |
<para>First, we check if a SCSI reset was encountered on the bus |
1539 |
<para>First, we check if a SCSI reset was encountered on the bus |
| 1540 |
(probably caused by another SCSI controller on the same SCSI |
1540 |
(probably caused by another SCSI controller on the same SCSI |
|
Lines 1899-1905
Link Here
|
| 1899 |
SCSI bus reset</para></listitem> |
1899 |
SCSI bus reset</para></listitem> |
| 1900 |
|
1900 |
|
| 1901 |
<listitem><para><emphasis>CAM_REQ_CMP_ERR</emphasis> - |
1901 |
<listitem><para><emphasis>CAM_REQ_CMP_ERR</emphasis> - |
| 1902 |
"impossible" SCSI phase occurred or something else as weird or |
1902 |
<quote>impossible</quote> SCSI phase occurred or something else as weird or |
| 1903 |
just a generic error if further detail is not |
1903 |
just a generic error if further detail is not |
| 1904 |
available</para></listitem> |
1904 |
available</para></listitem> |