diff options
author | ru <ru@FreeBSD.org> | 2004-07-02 23:52:20 +0000 |
---|---|---|
committer | ru <ru@FreeBSD.org> | 2004-07-02 23:52:20 +0000 |
commit | 01548ace1533487f9c0488f55112c9d8641f8184 (patch) | |
tree | 23294a96f715e1e5bc35c1029ec151c90ee95b96 /lib/libcam | |
parent | 47f5e31e2bb626743fa9e912918201fe505b1419 (diff) | |
download | FreeBSD-src-01548ace1533487f9c0488f55112c9d8641f8184.zip FreeBSD-src-01548ace1533487f9c0488f55112c9d8641f8184.tar.gz |
Mechanically kill hard sentence breaks.
Diffstat (limited to 'lib/libcam')
-rw-r--r-- | lib/libcam/cam.3 | 58 | ||||
-rw-r--r-- | lib/libcam/cam_cdbparse.3 | 60 |
2 files changed, 79 insertions, 39 deletions
diff --git a/lib/libcam/cam.3 b/lib/libcam/cam.3 index 439fe78..abfd7c2 100644 --- a/lib/libcam/cam.3 +++ b/lib/libcam/cam.3 @@ -121,8 +121,10 @@ .Fc .Sh DESCRIPTION The CAM library consists of a number of functions designed to aid in -programming with the CAM subsystem. This man page covers the basic set of -library functions. More functions are documented in the man pages listed +programming with the CAM subsystem. +This man page covers the basic set of +library functions. +More functions are documented in the man pages listed below. .Pp Many of the CAM library functions use the @@ -181,29 +183,35 @@ takes as arguments a string describing the device it is to open, and suitable for passing to .Xr open 2 . The "path" passed in may actually be most any type of string that contains -a device name and unit number to be opened. The string will be parsed by +a device name and unit number to be opened. +The string will be parsed by .Fn cam_get_device -into a device name and unit number. Once the device name and unit number +into a device name and unit number. +Once the device name and unit number are determined, a lookup is performed to determine the passthrough device that corresponds to the given device. .Fn cam_open_device is rather simple to use, but it isn't really suitable for general use -because its behavior isn't necessarily deterministic. Programmers writing +because its behavior isn't necessarily deterministic. +Programmers writing new applications should make the extra effort to use one of the other open routines documented below. .Pp .Fn cam_open_spec_device opens the .Xr pass 4 -device that corresponds to the device name and unit number passed in. The +device that corresponds to the device name and unit number passed in. +The .Ar flags should be flags suitable for passing to .Xr open 2 . The .Ar device -argument is optional. The user may supply pre-allocated space for the +argument is optional. +The user may supply pre-allocated space for the .Va cam_device -structure. If the +structure. +If the .Ar device argument is .Va NULL , @@ -219,11 +227,14 @@ is similar to except that it takes a .Tn SCSI bus, target and logical unit instead of a device name and unit number as -arguments. The +arguments. +The .Va path_id argument is the CAM equivalent of a .Tn SCSI -bus number. It represents the logical bus number in the system. The +bus number. +It represents the logical bus number in the system. +The .Ar flags should be flags suitable for passing to .Xr open 2 . @@ -238,10 +249,12 @@ takes as an argument the .Fa path of a .Xr pass 4 -device to open. No translation or lookup is performed, so the path passed +device to open. +No translation or lookup is performed, so the path passed in must be that of a CAM .Xr pass 4 -device. The +device. +The .Fa flags should be flags suitable for passing to .Xr open 2 . @@ -258,15 +271,18 @@ structure. frees the .Va cam_device structure allocated by one of the above open() calls, and closes the file -descriptor to the passthrough device. This routine should not be called if +descriptor to the passthrough device. +This routine should not be called if the user allocated space for the .Va cam_device -structure. Instead, the user should call +structure. +Instead, the user should call .Fn cam_close_spec_device . .Pp .Fn cam_close_spec_device merely closes the file descriptor opened in one of the open() routines -described above. This function should be called when the +described above. +This function should be called when the .Va cam_device structure was allocated by the caller, rather than the CAM library. .Pp @@ -297,7 +313,8 @@ takes as arguments a structure, and a string with length .Fa len . It creates a colon-terminated printing prefix string similar to the ones -used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". +used by the kernel. +e.g.: "(cd0:ahc1:0:4:0): ". .Fn cam_path_string will place at most .Fa len Ns \-1 @@ -370,7 +387,8 @@ returns a value of -1 if an error occured, and is set to indicate the error. .Pp .Fn cam_path_string -returns a filled printing prefix string as a convenience. This is the same +returns a filled printing prefix string as a convenience. +This is the same .Fa str that is passed into .Fn cam_path_string . @@ -403,11 +421,13 @@ The CAM library first appeared in .Fn cam_open_device doesn't check to see if the .Fa path -passed in is a symlink to something. It also doesn't check to see if the +passed in is a symlink to something. +It also doesn't check to see if the .Fa path passed in is an actual .Xr pass 4 -device. The former would be rather easy to implement, but the latter would +device. +The former would be rather easy to implement, but the latter would require a definitive way to identify a device node as a .Xr pass 4 device. diff --git a/lib/libcam/cam_cdbparse.3 b/lib/libcam/cam_cdbparse.3 index e31a0fb..7d7d4de 100644 --- a/lib/libcam/cam_cdbparse.3 +++ b/lib/libcam/cam_cdbparse.3 @@ -170,7 +170,8 @@ layer. These functions may be used in new applications, but users may find it easier to use the various SCSI CCB building functions included with the .Xr cam 3 -library. (e.g.\& +library. +(e.g.\& .Fn cam_fill_csio , .Fn scsi_start_stop , and @@ -194,10 +195,12 @@ argument. .Fa data_ptr is the data buffer used during the .Tn SCSI -data phase. If no data is to be +data phase. +If no data is to be transferred for the .Tn SCSI -command in question, this should be set to NULL. If there is data to +command in question, this should be set to NULL. +If there is data to transfer for the command, this buffer must be at least .Fa dxfer_len long. @@ -252,17 +255,20 @@ typedef enum { } ccb_flags; .Ed .Pp -Multiple flags should be ORed together. Any of the CCB flags may be used, +Multiple flags should be ORed together. +Any of the CCB flags may be used, although it is worth noting several important ones here: .Pp .Bl -tag -width CAM_PASS_ERR_RECOVER .It Dv CAM_DIR_IN -This indicates that the operation in question is a read operation. i.e., +This indicates that the operation in question is a read operation. +i.e., data is being read from the .Tn SCSI device to the user-supplied buffer. .It Dv CAM_DIR_OUT -This indicates that the operation is a write operation. i.e. data is being +This indicates that the operation is a write operation. +i.e., data is being written from the user-supplied buffer to the device. .It Dv CAM_DIR_NONE This indicates that there is no data to be transferred for this command. @@ -271,7 +277,8 @@ This flag disables device queue freezing as an error recovery mechanism. .It Dv CAM_PASS_ERR_RECOVER This flag tells the .Xr pass 4 -driver to enable error recovery. The default is to not perform error +driver to enable error recovery. +The default is to not perform error recovery, which means that the retry count won't be honored without this flag, among other things. .It Dv CAM_DATA_PHYS @@ -282,7 +289,8 @@ is a physical address, not a virtual address. .Pp The .Fa retry_count -tells the kernel how many times to retry the command in question. The +tells the kernel how many times to retry the command in question. +The retry count is ignored unless the .Xr pass 4 driver is told to enable error recovery via the @@ -291,22 +299,26 @@ flag. .Pp The .Fa timeout -tells the kernel how long to wait for the given command to complete. If +tells the kernel how long to wait for the given command to complete. +If the timeout expires and the command hasn't completed, the CCB will be returned from the kernel with an appropriate error status. .Pp .Fa cmd_spec is a CDB format specifier used to build up the SCSI CDB. -This text string is made up of a list of field specifiers. Field +This text string is made up of a list of field specifiers. +Field specifiers specify the value for each CDB field (including indicating that the value be taken from the next argument in the variable argument list), the width -of the field in bits or bytes, and an optional name. White space is +of the field in bits or bytes, and an optional name. +White space is ignored, and the pound sign ('#') introduces a comment that ends at the end of the current line. .Pp The optional name is the first part of a field specifier and -is in curly braces. The text in curly braces in this example are +is in curly braces. +The text in curly braces in this example are the names: .Dl "{PS} v:b1 {Reserved} 0:b1 {Page Code} v:b6 # Mode select page" .Pp @@ -378,7 +390,8 @@ function takes two arguments: .It Fa gethook is passed into the .Fn arg_get -function at each invocation. This enables the +function at each invocation. +This enables the .Fn arg_get function to keep some state in between calls without using global or static variables. @@ -447,7 +460,8 @@ is a void pointer to the value being passed into the function. .It Fa count is the size of the value being passed into the .Fn arg_put -function. The argument format determines the unit of measure. +function. +The argument format determines the unit of measure. .It Fa name This is a text description of the field, if one was provided in the .Fa fmt . @@ -506,7 +520,8 @@ The CAM versions of these functions are based upon similar functions implemented for the old .Fx .Tn SCSI -layer. The encoding/decoding functions in the old +layer. +The encoding/decoding functions in the old .Tn SCSI code were written by Peter Dufault. .Pp @@ -516,7 +531,8 @@ SCSI command in user space. The old .Va scsireq data structure was almost identical to the SGI /dev/scsi data -structure. If anyone knows the name of the authors it should +structure. +If anyone knows the name of the authors it should go here; Peter Dufault first read about it in a 1989 Sun Expert magazine. .Pp The new CCB data structures are derived from the CAM-2 and CAM-3 @@ -533,16 +549,20 @@ library and the related kernel ioctl. If anyone needs that for compatibility contact dufault@hda.com. .Sh AUTHORS Kenneth Merry implemented the CAM versions of these encoding and decoding -functions. This current work is based upon earlier work by Peter Dufault. +functions. +This current work is based upon earlier work by Peter Dufault. .Sh BUGS There should probably be a function that encodes both the CDB and the data buffer portions of a .Tn SCSI -CCB. I discovered this while implementing the arbitrary command execution +CCB. +I discovered this while implementing the arbitrary command execution code in .Xr camcontrol 8 , but I haven't yet had time to implement such a function. .Pp -Some of the CCB flag descriptions really don't belong here. Rather they -belong in a generic CCB man page. Since that man page hasn't yet been +Some of the CCB flag descriptions really don't belong here. +Rather they +belong in a generic CCB man page. +Since that man page hasn't yet been written, the shorter descriptions here will have to suffice. |