doc: Initial checking of utility documentation updates with generatio…

…n script

Updating old utility documentation files to how we have separated this in closed source SeaChest.
Version history and about docs are separate and a generator script is used to create the documentation.

I tried to preserve some about and version info from the old docs, but many were updated using the internal SeaChest version history since the versions have historically matched since there is little difference between open and close source tools.

[#127]

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

docs/Feature_Docs/About_ATA_Security_Frozen.txt

@@ -0,0 +1,22 @@
+When drives are reported Security "Frozen" by SeaChest
+------------------------------------------------------
+Note:  Your system or the SeaChest software may report that a SATA password
+cannot be changed because it is "frozen". Many systems BIOS will automatically
+set the ATA SECURITY FREEZE LOCK command on all SATA drives at start up. The
+SECURITY FREEZE LOCK command prevents changes to all Security states until a
+following power-on reset or hardware reset. The purpose of the SECURITY FREEZE
+LOCK command is to prevent password setting attacks on the security system.
+
+The SeaChest --deviceInfo command will display something similar to this: "ATA
+Security Information: Supported, Frozen". To disable Freeze Lock, first check
+your BIOS SATA disk options to control the setting at start up. Otherwise, you
+might pause the boot up shortly after powering on the system and then
+temporarily remove the power to the security frozen drive (let it completely
+spin down). When the power is back on the drive it will start without being
+frozen.
+
+Windows systems may also decide not to recognize the drive if it is ATA
+Security Locked and it will not be listed by the SeaChest --scan command.  If
+the drive remains undetected in Windows, your alternative is to make a bootable
+USB flash drive and run SeaChest_Erase from the Linux operating system.
+

docs/Feature_Docs/About_Bad_LBAs.txt

@@ -0,0 +1,49 @@
+======================
+Bad LBA (Sector) Found
+======================
+IMPORTANT: Please read and carefully consider all of the following information
+about your "Bad LBA (Logical Block Address, or Sector) Found" options.
+
+A bad sector is a small 512-byte area on the disk drive that is reporting
+errors and cannot be accessed properly. New bad sectors, sometimes called grown
+defects, are often caused by some kind of physical damage. If a file or folder
+uses this sector, then the file is already incomplete or corrupt because the
+bytes are not readable.
+
+**** NOTE **** The following information applies only to Seagate Technology,
+Maxtor, Samsung and LaCie brand disk drives:
+
+When SeaChest discovers a bad LBA (sector) through reading, it displays a count
+of the bad sectors.
+
+Sectors are often not in use. If a sector is in use, then that file is
+incomplete or corrupt. When a bad sector happens to align with a folder or
+directory listing structure, then the links to files and sub-folders it manages
+may be broken.
+
+You should carefully consider the importance of your data. While the sector is
+currently unreadable, if the file or folder is important to you then you may
+need professional recovery services to possibly reclaim the data. In this case,
+select to scan without trying to repair sectors on the drive.
+
+If you have decided that the file or folder is replaceable, already backed up
+or just not important to you, then you can tell SeaChest to attempt to attempt
+to repair the sector.  See the Sector Repair Commands section above.
+
+By design, modern disk drives maintain spare sectors for reallocation purposes.
+Usually, sectors become difficult to read long before they become impossible to
+read. In this situation the actual data bytes in the sector are preserved and
+transferred to the new spare during a sector reallocation. Similarly, when a
+disk drive writes data and encounters a problem, the drive firmware retires the
+problem sector and activates a replacement before giving successful write
+status.
+
+If you give permission to attempt to repair a bad sector, then SeaChest will
+attempt to write a 512-byte pattern of zeros to that single error sector.
+Usually, this action will assist the disk drive firmware in managing the
+problem by retiring the problem sector and activating a spare in its place. If
+the attempted repair fails to reallocate the LBA to an available spare, then
+the test is a FAIL and the drive is bad.
+
+Note: Seagate Technology is not responsible for lost user data.
+

docs/Feature_Docs/About_Fast_Format.txt

@@ -0,0 +1,18 @@
+================
+About FastFormat
+================
+A FastFormat (quickly changing the logical sector size) may take a few minutes
+for the process to complete. The disk activity LED may show activity during the
+conversion.  The larger the drive, the longer it takes.
+
+NOTE: Operating systems do a device discovery during start up and set various
+parameters, like total sectors and sector size, into the storage device
+descriptions. The logical sector size times the number or logical sectors
+defines the drive capacity.  You should expect to see OS I/O errors if you
+change the logical sector size on a drive and then perform read or write
+operations before the OS has updated its storage device descriptions.  Some
+operating systems will throw an error after accessing a drive that has just run
+a FastFormat but during its error recovery routines it may re-discover the
+device parameters and update the system logs.  A system restart, however, is
+the most reliable way to refresh the storage device descriptions.
+

docs/Feature_Docs/About_Format_Unit.txt

@@ -0,0 +1,46 @@
+==================================
+About the SCSI Format Unit Command
+==================================
+(from the Seagate SCSI Commands Reference Manual, 100293068 Rev. H July 2014)
+http://www.seagate.com/files/staticfiles/support/docs/manual/Interface%20manuals/100293068h.pdf
+
+The FORMAT UNIT command requests that the device server format the medium into
+application client accessible logical blocks as specified in the number of
+blocks and block length values received in the last mode parameter block
+descriptor in a MODE SELECT command. In addition, the device server may certify
+the medium and create control structures for the management of the medium and
+defects. The degree that the medium is altered by this command is
+vendor-specific.
+
+If a device server receives a FORMAT UNIT command before receiving a MODE
+SELECT command with a mode parameter block descriptor the device server shall
+use the number of blocks and block length at which the logical unit is
+currently formatted (i.e., no change is made to the number of blocks and the
+block length of the logical unit during the format operation).
+
+The simplest form of the FORMAT UNIT command (i.e., a FORMAT UNIT command with
+no parameter data) accomplishes medium formatting with little application
+client control over defect management. The device server implementation
+determines the degree of defect management that is to be performed. Additional
+forms of this command increase the application client's control over defect
+management.
+
+The application client may specify:
+  a) defect list(s) to be used;
+  b) defect locations;
+  c) that logical unit certification be enabled; and
+  d) exception handling in the event that defect lists are not accessible.
+
+While performing a format operation, the device server shall respond to
+commands attempting to enter into the task set except INQUIRY commands, REPORT
+LUNS commands, and REQUEST SENSE commands with CHECK CONDITION status with the
+sense key set to NOT READY and the additional sense code set to LOGICAL UNIT
+NOT READY, FORMAT IN PROGRESS. Handling of commands already in the task set is
+vendor-specific. If the device server receives an INQUIRY command, a REPORT
+LUNS commands, or a REQUEST SENSE command, then the device server shall process
+the command. The device server shall return data for an INQUIRY command based
+on the condition of the SCSI target device before beginning the FORMAT UNIT
+command (i.e., INQUIRY data shall not change until after successful completion
+of a format operation). The processing of commands in the task set when a
+FORMAT UNIT command is received is vendor specific.
+

docs/Feature_Docs/About_PowerChoice.txt

@@ -0,0 +1,44 @@
+================================
+How PowerChoice Technology Works
+================================
+See the Seagate technology paper "Seagate' PowerChoice' Technology Provides
+Unprecedented Hard Drive Power Savings and Flexibility"
+http://www.seagate.com/files/docs/pdf/en-GB/whitepaper/tp608-powerchoice-tech-provides-gb.pdf
+
+Each individual power condition builds on the capabilities of the previous
+higher power condition in order to save incrementally more power. The specific
+energy-saving steps implemented for each power condition are as follows:
+
+Idle_A
+        - Disables most of the servo system, reduces processor and channel
+        power consumption
+        - Discs rotating at full speed (7,200 RPM)
+Idle_B
+        - Disables most of the servo system, reduces processor and channel
+        power consumption
+        - Heads are unloaded to drive ramp.
+        - Discs rotating at full speed (7,200 RPM)
+Idle_C/Standby_Y (SAS Only)
+        - Disables most of the servo system, reduces processor and channel
+        power consumption
+        - Heads are unloaded to drive ramp.
+        - Drive speed reduced to a lower RPM (reduced RPM)
+Standby_Z
+        - Heads are unloaded to drive ramp.
+        - Drive motor is spun down.
+        - Drive still responds to non-media access host commands.
+
+Flexibility is a key feature of PowerChoice technology, enabling commands from
+the host side to customize power condition settings and direct a drive into or
+out of power conditions as required. Two different options are available for
+the user to modify PowerChoice technology settings, depending on the interface
+used:
+
+SAS
+        Host-definable timers via mode pages
+        Immediate host-commanded power transitions via Start/Stop Unit (SSU)
+        command
+SATA
+        Host-definable timers via Set Features commands
+        Immediate host-commanded power transitions via Set Features commands
+

docs/Feature_Docs/Enabling_TCG_Commands_In_Linux.txt

@@ -0,0 +1,71 @@
+==============================
+Enabling TCG Commands In Linux
+==============================
+Abstract
+--------
+The SeaChest_Erase --revert and --revertSP commands require specific support be
+enabled in the Linux kernel.  This document describes the process to enable
+support for sending ATA Trusted Trusted Computing Group (TCG) commands in
+Linux. The focus is on how to do this through Ubuntu Linux 14.04LTS, however,
+the process should apply to other Linux's as well although others may vary
+slightly.
+
+Modifying The GRUB Configuration File (Ubuntu example used)
+-----------------------------------------------------------
+In order to make the change to allow TCG commands persist across reboots, you
+must modify the kernel boot parameters. In Ubuntu, this is accomplished by
+modifying the GRUB 2 configuration file. This section references the Grub2
+configuration documentation from the Ubuntu Community:
+https://help.ubuntu.com/community/Grub2/Setup#Configuring_GRUB_2
+
+Follow these steps to perform this modification in Ubuntu (other Linux's may be
+similar).
+
+1. You must modify the file /etc/default/grub. You can do this by running "sudo
+gedit /etc/default/grub"
+
+2. Once this file is open in the editor of your choice, add
+"libata.allow_tpm=1" to the line  that begins with "GRUB_CMDLINE_LINUX_DEFAULT"
+(or which ever line in grub is the one you use to boot your kernel, but this is
+the default).
+
+3. Close your editor
+
+4. Run the command "sudo update-grub" to apply your changes to the grub boot
+configuration (the file modified in these steps is a config file for the config
+file).
+
+5. Restart your computer to make this active
+
+Temporarily Enabling TCG Commands In Linux
+------------------------------------------
+You can temporarily enable TCG commands without modifying the kernel boot
+parameters. This can be accomplished by modifying the libata parameters file.
+Below is a sample script that can be run to do this.
+
+Sample Script:
+
+cd /sys/module/libata/parameters
+sudo chmod 644 allow_tpm
+echo 1 | sudo dd of=./allow_tpm
+sudo chmod 444 allow_tpm
+
+Tiny Core - Enabling TCG Commands
+------------------------------------------
+Follow these steps to enable TCG commands on a Tiny Core bootable USB flash
+drive.
+
+1. Leave the USB flash drive in after you run the Windows-based USB boot maker
+tool.
+
+2. Using a (Windows) text editor go to USB:/boot/syslinux.cfg and in there, add
+libata.allow_tpm=1 on the append line with the other kernel boot parameters.
+
+3. Using a (Windows) text editor go to USB:/EFI/boot/refind.conf and add
+libata.allow_tpm=1 on the options line with the other kernel boot parameters
+
+Alternate method:
+If Linux is already booted and you only want to temporarily enable TCG
+commands, you can change the contents of
+/sys/module/libata/parameters/allow_tpm from "0" to a "1".
+

docs/Feature_Docs/Interpretting_Head_Health.txt

@@ -0,0 +1,43 @@
+Interpreting Head Health and Status
+-----------------------------------
+Beginning in 2016, some Seagate nearline drives started to support the
+Remanufacture command set which allows a disk drive with a manageable
+read/write head problem to remain in service at a reduced capacity by
+"depopulating" the head element.  You can check if a drive supports the
+Remanufacture command set by running --deviceInfo and looking for 'Storage
+Element Depopulation' in the list of supported features.  (Not to be confused
+with 'SATA Rebuild Assist' which is a feature used to rebuild RAID systems.)
+
+A drive failure (due to a head problem) that is easily removed from the system
+is replaced with a spare drive.  A drive that is nearly inaccessible may make
+sense to remain in the system at a reliable lesser capacity by depopulating the
+problem head.
+
+If supported by the drive, the --showPhysicalElementStatus command will display
+a simple table showing head number, type, health, and status.
+
+The Health level is represented like a percentage, 0-100.  0 is perfectly
+healthy, 100 = at manufacturer's limit, above this to 207 is above the
+manufacturer's limit. A report of 254 means a depopulate is in progress.
+
+The Status levels are active, in limit, degraded, truncated, truncate failed.
+
+If a drive head has developed isolated, degraded performance, and does not
+affect any other reliability in the system, then the head can be removed from
+service. A drive with seven platters and fourteen heads would lose 1/14th of
+its storage capacity, or ~7%.  Likewise, a four head drive would lose 25%.
+
+If a drive is reported as "degraded" by --showPhysicalElementStatus then it can
+be depopulated using the --removePhysicalElement command.  When a head is
+depopulated the drive must perform a complete full pack write; this is
+obviously data destructive and takes a very long time to complete.
+
+When disk drives are built the post assembly factory process includes media
+scanning, any defects mapping, defining sector sizes, and establishing system,
+cache and data zones.  This activity is generically known as a low-level
+format.  During head depopulation (i.e. removing a physical element) the drive
+performs a kind of 'mid-level format' using Sanitize Overwrite which has the
+unique behavior that once started it must finish.  If power is interrupted
+during a Sanitize Overwrite it will pick up again where it left off when power
+returns.
+

docs/Feature_Docs/Windows_Firmware_Download_Restrictions.txt

@@ -0,0 +1,22 @@
+Windows Restrictions Over SATA Firmware Downloads
+-------------------------------------------------
+You should not attempt downloading firmware to a SATA disk drive in the Windows
+operating system unless the drive supports the 'deferred' mode.  You define the
+mode with the SeaChest command line option '--downloadMode deferred'.  If
+the drive does not support deferred mode then the command will be aborted.
+Windows may not be so restrictive on secondary, non-boot SATA drives or SATA
+drives attached to host bus adapters (HBAs, controllers, USB, etc).
+
+If you force a primary SATA boot drive to download firmware in Windows using a
+different --downloadMode setting, then the result will likely be a BSOD (blue
+screen of death) system crash.  This is because the legacy SATA firmware
+download modes require the drive to spin down and then back up and the
+momentary disappearance of the drive causes the operating system to crash.
+Windows is actually protecting the system when it thinks the drive has stopped
+responding (see wikis about Ring 0 Protection).
+
+The 'deferred' mode does not spin down the drive.  Instead, the drive waits for
+a future reboot of the system and self-activates the firmware at that time.
+Other operating systems may utilize the SeaChest --activateFW command to
+trigger the switch to the new firmware version.
+