From owner-freebsd-doc Mon Feb 18 13:10:16 2002 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id ABC7C37B405 for ; Mon, 18 Feb 2002 13:10:00 -0800 (PST) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.6/8.11.6) id g1ILA0q83352; Mon, 18 Feb 2002 13:10:00 -0800 (PST) (envelope-from gnats) Received: from relay3-gui.server.ntli.net (relay3-gui.server.ntli.net [194.168.4.200]) by hub.freebsd.org (Postfix) with ESMTP id 52CD537B405 for ; Mon, 18 Feb 2002 13:06:39 -0800 (PST) Received: from pc4-card4-0-cust162.cdf.cable.ntl.com ([80.4.14.162] helo=rhadamanth.private.submonkey.net ident=mailnull) by relay3-gui.server.ntli.net with esmtp (Exim 3.03 #2) id 16cuzc-0006Q4-00 for FreeBSD-gnats-submit@freebsd.org; Mon, 18 Feb 2002 21:06:36 +0000 Received: from setantae by rhadamanth.private.submonkey.net with local (Exim 3.34 #1) id 16cuzZ-0000G4-00 for FreeBSD-gnats-submit@freebsd.org; Mon, 18 Feb 2002 21:06:33 +0000 Message-Id: Date: Mon, 18 Feb 2002 21:06:33 +0000 From: Ceri Reply-To: Ceri To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.113 Subject: docs/35089: Developers' Handbook : SCSI chapter minor fixes Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org >Number: 35089 >Category: docs >Synopsis: Developers' Handbook : SCSI chapter minor fixes >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Mon Feb 18 13:10:00 PST 2002 >Closed-Date: >Last-Modified: >Originator: Ceri >Release: FreeBSD 4.5-STABLE i386 >Organization: >Environment: System: FreeBSD rhadamanth.private.submonkey.net 4.5-STABLE FreeBSD 4.5-STABLE #0: Tue Feb 12 17:56:57 GMT 2002 setantae@rhadamanth.private.submonkey.net:/usr/obj/usr/src/sys/RHADAMANTH i386 >Description: - "" -> - There is no function called xpt_selease_simq; there is one called xpt_release_simq, though Ceri >How-To-Repeat: >Fix: --- doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml.old Mon Feb 18 20:58:44 2002 +++ doc/en_US.ISO8859-1/books/developers-handbook/scsi/chapter.sgml Mon Feb 18 21:03:16 2002 @@ -36,7 +36,7 @@ and from the CAM code itself (by Justing T. Gibbs, see /sys/cam/*). When some solution looked the most logical and was essentially verbatim extracted from the code - by Justin Gibbs, I marked it as "recommended". + by Justin Gibbs, I marked it as recommended. The document is illustrated with examples in pseudo-code. Although sometimes the examples have many details @@ -174,7 +174,7 @@ driver_name - the name of the actual driver, - such as "ncr" or "wds" + such as ncr or wds. softc - pointer to the driver's internal descriptor for this SCSI card. This @@ -182,7 +182,7 @@ data. unit - the controller unit number, for example - for controller "wds0" this number will be + for controller wds0 this number will be 0 max_dev_transactions - maximal number of @@ -237,7 +237,7 @@ A typical example of such an event is a device reset. Each transaction and event identifies the devices to which it applies - by the means of "path". The target-specific events normally + by the means of path. The target-specific events normally occur during a transaction with this device. So the path from that transaction may be re-used to report this event (this is safe because the event path is copied in the event reporting @@ -273,10 +273,10 @@ (cam_sim_path(sim)) SCSI target number of the device (CAM_TARGET_WILDCARD - means "all devices") + means all devices) SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means - "all LUNs") + all LUNs) If the driver can not allocate this path it will not be able to @@ -324,13 +324,13 @@ Do some action on request of the CAM subsystem. Sim describes the SIM for the request, CCB is the request - itself. CCB stands for "CAM Control Block". It is a union of + itself. CCB stands for CAM Control Block. It is a union of many specific instances, each describing arguments for some type of transactions. All of these instances share the CCB header where the common part of arguments is stored. CAM supports the SCSI controllers working in both initiator - ("normal") mode and target (simulating a SCSI device) mode. Here + (normal) mode and target (simulating a SCSI device) mode. Here we only consider the part relevant to the initiator mode. There are a few function and macros (in other words, @@ -398,7 +398,7 @@ are a surprising number of status values defined in /sys/cam/cam.h which should be able to represent the status of a request in great detail. More - interesting yet, the status is in fact a "bitwise or" of an + interesting yet, the status is in fact a bitwise or of an enumerated status value (the lower 6 bits) and possible additional flag-like bits (the upper bits). The enumerated values will be discussed later in more detail. The summary of @@ -447,7 +447,7 @@ allowed to sleep, so all the synchronization for resource access must be done using SIM or device queue freezing. Besides the aforementioned flags the CAM subsystem provides functions - xpt_selease_simq() and + xpt_release_simq() and xpt_release_devq() to unfreeze the queues directly, without passing a CCB to CAM. @@ -497,7 +497,7 @@ XPT_SCSI_IO - execute an I/O transaction - The instance "struct ccb_scsiio csio" of the union ccb is + The instance struct ccb_scsiio csio of the union ccb is used to transfer the arguments. They are: @@ -785,8 +785,8 @@ } - XPT_RESET_DEV - send the SCSI "BUS - DEVICE RESET" message to a device + XPT_RESET_DEV - send the SCSI BUS + DEVICE RESET message to a device There is no data transferred in CCB except the header and the most interesting argument of it is target_id. Depending on @@ -877,8 +877,8 @@ XPT_ABORT - abort the specified CCB - The arguments are transferred in the instance "struct - ccb_abort cab" of the union ccb. The only argument field in it + The arguments are transferred in the instance struct + ccb_abort cab of the union ccb. The only argument field in it is: abort_ccb - pointer to the CCB to be @@ -1037,7 +1037,7 @@ XPT_SET_TRAN_SETTINGS - explicitly set values of SCSI transfer settings - The arguments are transferred in the instance "struct ccb_trans_setting cts" + The arguments are transferred in the instance struct ccb_trans_setting cts of the union ccb: @@ -1096,8 +1096,8 @@ The current settings are, as the name says, current. Changing them means that the parameters must be - re-negotiated on the next transfer. Again, these "new current - settings" are not supposed to be forced on the device, just they + re-negotiated on the next transfer. Again, these new current + settings are not supposed to be forced on the device, just they are used as the initial step of negotiations. Also they must be limited by actual capabilities of the SCSI controller: for example, if the SCSI controller has 8-bit bus and the request @@ -1121,7 +1121,7 @@ in effect goal - those requested by - setting of the "current" parameters + setting of the current parameters The code looks like: @@ -1207,8 +1207,8 @@ SCSI transfer settings This operations is the reverse of - XPT_SET_TRAN_SETTINGS. Fill up the CCB instance "struct - ccb_trans_setting cts" with data as requested by the flags + XPT_SET_TRAN_SETTINGS. Fill up the CCB instance struct + ccb_trans_setting cts with data as requested by the flags CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both are set then the existing drivers return the current settings). Set all the bits in the valid field. @@ -1216,8 +1216,8 @@ XPT_CALC_GEOMETRY - calculate logical (BIOS) geometry of the disk - The arguments are transferred in the instance "struct - ccb_calc_geometry ccg" of the union ccb: + The arguments are transferred in the instance struct + ccb_calc_geometry ccg of the union ccb: @@ -1269,7 +1269,7 @@ This gives the general idea, the exact calculation depends on the quirks of the particular BIOS. If BIOS provides no way - set the "extended translation" flag in EEPROM this flag should + set the extended translation flag in EEPROM this flag should normally be assumed equal to 1. Other popular geometries are: @@ -1286,8 +1286,8 @@ words get the SIM driver and SCSI controller (also known as HBA - Host Bus Adapter) properties - The properties are returned in the instance "struct -ccb_pathinq cpi" of the union ccb: + The properties are returned in the instance struct +ccb_pathinq cpi of the union ccb: @@ -1534,7 +1534,7 @@ The conditions handled by the interrupt routine and the details depend very much on the hardware. We consider the set of - "typical" conditions. + typical conditions. First, we check if a SCSI reset was encountered on the bus (probably caused by another SCSI controller on the same SCSI @@ -1899,7 +1899,7 @@ SCSI bus reset CAM_REQ_CMP_ERR - - "impossible" SCSI phase occurred or something else as weird or + impossible SCSI phase occurred or something else as weird or just a generic error if further detail is not available >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message