doc: Updating man pages using help2man

Updating man pages using the help2man tool. Some have been updated, others are freshly created.

[#88]

Signed-off-by: Tyler Erickson <[email protected]>

Author: vonericsen

docs/man/man8/openSeaChest_Basics.8

@@ -0,0 +1,312 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.1.
+.TH OPENSEACHEST_PASSTHROUGHTEST "1" "July 2022" "openSeaChest_PassthroughTest ==========================================================================================" "User Commands"
+.SH NAME
+openSeaChest_PassthroughTest \- manual page for openSeaChest_PassthroughTest ==========================================================================================
+.SH DESCRIPTION
+==========================================================================================
+.IP
+openSeaChest_PassthroughTest \- openSeaChest drive utilities \- NVMe Enabled
+Copyright (c) 2014\-2022 Seagate Technology LLC and/or its Affiliates, All Rights Reserved
+openSeaChest_PassthroughTest Version: 1.1.5\-3_2_1 X86_64
+Build Date: Jul 21 2022
+Today: Thu Jul 21 16:48:45 2022        User: tyler
+.PP
+==========================================================================================
+Usage
+=====
+.IP
+openSeaChest_PassthroughTest [\-d <sg_device>] {arguments} {options}
+.PP
+Examples
+========
+.IP
+openSeaChest_PassthroughTest \fB\-\-scan\fR
+openSeaChest_PassthroughTest \fB\-d\fR /dev/sg? \fB\-i\fR
+.PP
+Return codes
+============
+.IP
+Generic/Common exit codes
+0 = No Error Found
+1 = Error in command line options
+2 = Invalid Device Handle or Missing Device Handle
+3 = Operation Failure
+4 = Operation not supported
+5 = Operation Aborted
+6 = File Path Not Found
+7 = Cannot Open File
+8 = File Already Exists
+9 = Need Elevated Privileges
+Anything else = unknown error
+.PP
+Utility Options
+===============
+.HP
+\fB\-\-echoCommandLine\fR
+.IP
+Echo the command line entered into the utility on the screen.
+.HP
+\fB\-\-enableLegacyUSBPassthrough\fR
+.IP
+Only use this option on old USB or IEEE1394 (Firewire)
+products that do not otherwise work with the tool.
+This option will enable a trial and error method that
+attempts sending various ATA Identify commands through
+vendor specific means. Because of this, certain products
+that may respond in unintended ways since they may interpret
+these commands differently than the bridge chip the command
+was designed for.
+.HP
+\fB\-\-forceATA\fR
+.IP
+Using this option will force the current drive to
+be treated as a ATA drive. Only ATA commands will
+be used to talk to the drive.
+.TP
+\fB\-\-forceATADMA\fR
+(SATA Only)
+.IP
+Using this option will force the tool to issue SAT
+commands to ATA device using the protocol set to DMA
+whenever possible (on DMA commands).
+This option can be combined with \fB\-\-forceATA\fR
+.TP
+\fB\-\-forceATAPIO\fR
+(SATA Only)
+.IP
+Using this option will force the tool to issue PIO
+commands to ATA device when possible. This option can
+be combined with \fB\-\-forceATA\fR
+.TP
+\fB\-\-forceATAUDMA\fR
+(SATA Only)
+.IP
+Using this option will force the tool to issue SAT
+commands to ATA device using the protocol set to UDMA
+whenever possible (on DMA commands).
+This option can be combined with \fB\-\-forceATA\fR
+.HP
+\fB\-\-forceSCSI\fR
+.IP
+Using this option will force the current drive to
+be treated as a SCSI drive. Only SCSI commands will
+be used to talk to the drive.
+.HP
+\fB\-h\fR, \fB\-\-help\fR
+.IP
+Show utility options and example usage (this output you see now)
+Please report bugs/suggestions to [email protected].
+Include the output of \fB\-\-version\fR information in the email.
+.HP
+\fB\-\-license\fR
+.IP
+Display the Seagate End User License Agreement (EULA).
+.HP
+\fB\-\-modelMatch\fR [model Number]
+.IP
+Use this option to run on all drives matching the provided
+model number. This option will provide a closest match although
+an exact match is preferred. Ex: ST500 will match ST500LM0001
+.HP
+\fB\-\-noBanner\fR
+.IP
+Use this option to suppress the text banner that displays each time
+openSeaChest is run.
+.HP
+\fB\-\-onlyFW\fR [firmware revision]
+.IP
+Use this option to run on all drives matching the provided
+firmware revision. This option will only do an exact match.
+.HP
+\fB\-\-onlySeagate\fR
+.IP
+Use this option to match only Seagate drives for the options
+provided
+.HP
+\fB\-q\fR, \fB\-\-quiet\fR
+.IP
+Run openSeaChest_PassthroughTest in quiet mode. This is the same as
+\fB\-v\fR 0 or \fB\-\-verbose\fR 0
+.HP
+\fB\-v\fR [0\-4], \fB\-\-verbose\fR [0 | 1 | 2 | 3 | 4]
+.IP
+Show verbose information. Verbosity levels are:
+0 \- quiet
+1 \- default
+2 \- command descriptions
+3 \- command descriptions and values
+4 \- command descriptions, values, and data buffers
+Example: \fB\-v\fR 3 or \fB\-\-verbose\fR 3
+.HP
+\fB\-V\fR, \fB\-\-version\fR
+.IP
+Show openSeaChest_PassthroughTest version and copyright information & exit
+.PP
+Utility Arguments
+=================
+.HP
+\fB\-d\fR, \fB\-\-device\fR deviceHandle
+.IP
+Use this option with most commands to specify the device
+handle on which to perform an operation. Example: /dev/sg?
+.HP
+\fB\-F\fR, \fB\-\-scanFlags\fR [option list]
+.IP
+Use this option to control the output from scan with the
+options listed below. Multiple options can be combined.
+.TP
+ata \- show only ATA (SATA) devices
+usb \- show only USB devices
+scsi \- show only SCSI (SAS) devices
+nvme \- show only NVMe devices
+interfaceATA \- show devices on an ATA interface
+interfaceUSB \- show devices on a USB interface
+interfaceSCSI \- show devices on a SCSI or SAS interface
+interfaceNVME = show devices on an NVMe interface
+sd \- show sd device handles
+sgtosd \- show the sd and sg device handle mapping
+.HP
+\fB\-i\fR, \fB\-\-deviceInfo\fR
+.IP
+Show information and features for the storage device
+.HP
+\fB\-s\fR, \fB\-\-scan\fR
+.IP
+Scan the system and list all storage devices with logical
+/dev/sg? assignments. Shows model, serial and firmware
+numbers.  If your device is not listed on a scan  immediately
+after booting, then wait 10 seconds and run it again.
+.HP
+\fB\-S\fR, \fB\-\-Scan\fR
+.IP
+This option is the same as \fB\-\-scan\fR or \fB\-s\fR,
+however it will also perform a low level rescan to pick up
+other devices. This low level rescan may wake devices from low
+power states and may cause the OS to re\-enumerate them.
+Use this option when a device is plugged in and not discovered in
+a normal scan.
+NOTE: A low\-level rescan may not be available on all interfaces or
+all OSs. The low\-level rescan is not guaranteed to find additional
+devices in the system when the device is unable to come to a ready state.
+.HP
+\fB\-\-SATInfo\fR
+.IP
+Displays SATA device information on any interface
+using both SCSI Inquiry / VPD / Log reported data
+(translated according to SAT) and the ATA Identify / Log
+reported data.
+.HP
+\fB\-\-testUnitReady\fR
+.IP
+Issues a SCSI Test Unit Ready command and displays the
+status. If the drive is not ready, the sense key, asc,
+ascq, and fru will be displayed and a human readable
+translation from the SPC spec will be displayed if one
+is available.
+.HP
+\fB\-\-ptDriveHint\fR [ata | nvme]
+.IP
+This option passes a hint to the software that the device being tested is
+an ATA or NVMe drive so it can appropriately test it.
+This option is most useful when also using \fB\-\-ptTypeHint\fR
+.HP
+\fB\-\-ptTypeHint\fR [sat | legacyATA]
+.IP
+Add this option if the device being tested is likely to support one of
+the supported passthrough types. This hints to the software to perform
+additional testing for these passthroughs if no other support is apparent.
+.TP
+sat \- device supports SAT ATA\-passthrough commands (12 or 16 byte)
+legacyATA \- device supports a legacy vendor unique method to passthrough
+.TP
+ATA commands. You must also specify \fB\-\-enableLegacyATAPTTest\fR
+in order for these commands to be tested.
+.HP
+\fB\-\-disablePassthroughTesting\fR
+.IP
+Disables all ATA passthrough testing. Device will only be tested with SCSI commands from
+SPC and SBC specifications.
+.HP
+\fB\-\-enableLegacyATAPTTest\fR
+.IP
+Add this option to the command line to allow sending legacy passthrough CDBs from
+old USB adapters or drivers. By default these are off since these operation codes
+may perform unintended actions on devices that don't actually support passthrough.
+For example: There is a USB thumbdrive that receives one of these and bricks immediately.
+Only add this to the command line if you understand and have high confidence that the
+device you are testing is likely to support one of these passthroughs. Most of these devices
+will have been created prior to 2006 when the SAT spec was added for a standardized passthrough.
+.HP
+\fB\-\-enableHangCmdsTest\fR [all | zlr | sctgpl | rrTdir]
+.IP
+There are some commands that are known to cause some translators
+to hang when they are received. This option covers some known commands for some devices
+This must be enabled manually for a more complete test, but if it hangs the device could cause problems.
+Each of these tests has a specific hack/quirk related to it, so if the device hangs, then it must be added
+to the list for higher compatibility. Not all hangs will be able to be detected by the software!
+Put this option on the command line multiple times to add different combinations of tests.
+.TP
+all \- run all known commands that may cause hangs
+zlr \- do SCSI read commands with zero transfer length
+sctgpl \- try reading the SCT status log with a GPL read log ext command
+rrTdir \- in the SAT return response information protocol, run it without setting the tdir bit as the spec allows
+.HP
+\fB\-\-forceRetest\fR
+.IP
+Use this option to force this utility to retest this device if it reports
+that it is already known. This may be useful when testing multiple devices
+that use the same chip and are identified, or when trying to troubleshoot
+compatibility on another OS.
+.HP
+\fB\-\-runPTTest\fR
+.IP
+This option is used to perform the passthrough test.
+The passthrough test is an attempt to figure out quirks or
+hacks with different translators in order to make the device
+more compatible with the rest of the openSeaChest software.
+The default test is done using only what can be determined about
+the device from the SCSI reported data. Attempting to passthrough
+ATA or NVMe commands may not be done depending on how the device reports.
+Using the other options can help tell this software to test for other
+behavior. The other options to control the test are as follows:
+.TP
+\fB\-\-ptDriveHint\fR
+\fB\-\-ptTypeHint\fR
+\fB\-\-disablePassthroughTesting\fR
+\fB\-\-enableLegacyATAPTTest\fR
+\fB\-\-enableHangCmdsTest\fR
+\fB\-\-forceRetest\fR
+.IP
+openSeaChest_PassthroughTest \- openSeaChest drive utilities \- NVMe Enabled
+Copyright (c) 2014\-2022 Seagate Technology LLC and/or its Affiliates, All Rights Reserved
+openSeaChest_PassthroughTest Version: 1.1.5\-3_2_1 X86_64
+Build Date: Jul 21 2022
+Today: Thu Jul 21 16:48:45 2022        User: tyler
+.PP
+==========================================================================================
+Version Info for openSeaChest_PassthroughTest:
+.IP
+Utility Version: 1.1.5
+opensea\-common Version: 1.22.0
+opensea\-transport Version: 3.2.1
+opensea\-operations Version: 3.1.1
+Build Date: Jul 21 2022
+Compiled Architecture: X86_64
+Detected Endianness: Little Endian
+Compiler Used: GCC
+Compiler Version: 11.2.0
+Operating System Type: Linux
+Operating System Version: 5.15.0\-39
+Operating System Name: Ubuntu 22.04 LTS
+.SH "SEE ALSO"
+The full documentation for
+.B openSeaChest_PassthroughTest
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B openSeaChest_PassthroughTest
+programs are properly installed at your site, the command
+.IP
+.B info openSeaChest_PassthroughTest
+.PP
+should give you access to the complete manual.