diff options
Diffstat (limited to 'static/freebsd/man4/sa.4 3.html')
| -rw-r--r-- | static/freebsd/man4/sa.4 3.html | 425 |
1 files changed, 0 insertions, 425 deletions
diff --git a/static/freebsd/man4/sa.4 3.html b/static/freebsd/man4/sa.4 3.html deleted file mode 100644 index 326ad744..00000000 --- a/static/freebsd/man4/sa.4 3.html +++ /dev/null @@ -1,425 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SA(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">SA(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">sa</code> — <span class="Nd">SCSI - Sequential Access device driver</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="Cd">device sa</code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver provides support for all - SCSI devices of the sequential access class that are attached to the system - through a supported SCSI Host Adapter. The sequential access class includes - tape and other linear access devices.</p> -<p class="Pp">A SCSI Host adapter must also be separately configured into the - system before a SCSI sequential access device can be configured.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="MOUNT_SESSIONS"><a class="permalink" href="#MOUNT_SESSIONS">MOUNT - SESSIONS</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver is based around the concept - of a - “<a class="permalink" href="#mount"><i class="Em" id="mount">mount - session</i></a>”, which is defined as the period between the time - that a tape is mounted, and the time when it is unmounted. Any parameters - set during a mount session remain in effect for the remainder of the session - or until replaced. The tape can be unmounted, bringing the session to a - close in several ways. These include:</p> -<ol class="Bl-enum"> - <li>Closing a `rewind device', referred to as sub-mode 00 below. An example is - <span class="Pa">/dev/sa0</span>.</li> - <li>Using the MTOFFL <a class="Xr">ioctl(2)</a> command, reachable through the - ‘<code class="Cm">offline</code>’ command of - <a class="Xr">mt(1)</a>.</li> -</ol> -<p class="Pp">It should be noted that tape devices are exclusive open devices, - except in the case where a control mode device is opened. In the latter - case, exclusive access is only sought when needed (e.g., to set - parameters).</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SUB-MODES"><a class="permalink" href="#SUB-MODES">SUB-MODES</a></h1> -<p class="Pp">The sub-modes differ in the action taken when the device is - closed:</p> -<dl class="Bl-tag"> - <dt><span class="Pa">/dev/sa*</span></dt> - <dd>A close will rewind the device; if the tape has been written, then a file - mark will be written before the rewind is requested. The device is - unmounted.</dd> - <dt><span class="Pa">/dev/nsa*</span></dt> - <dd>A close will leave the tape mounted. If the tape was written to, a file - mark will be written. No other head positioning takes place. Any further - reads or writes will occur directly after the last read, or the written - file mark.</dd> - <dt><span class="Pa">/dev/esa*</span></dt> - <dd>A close will rewind the device. If the tape has been written, then a file - mark will be written before the rewind is requested. On completion of the - rewind an unload command will be issued. The device is unmounted.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="BLOCKING_MODES"><a class="permalink" href="#BLOCKING_MODES">BLOCKING - MODES</a></h1> -<p class="Pp">SCSI tapes may run in either - ‘<a class="permalink" href="#variable"><i class="Em" id="variable">variable</i></a>’ - or - ‘<a class="permalink" href="#fixed"><i class="Em" id="fixed">fixed</i></a>’ - block-size modes. Most QIC-type devices run in fixed block-size mode, where - most nine-track tapes and many new cartridge formats allow variable - block-size. The difference between the two is as follows:</p> -<dl class="Bl-inset"> - <dt id="part">Variable block-size:</dt> - <dd>Each write made to the device results in a single logical record written - to the tape. One can never read or write - <a class="permalink" href="#part"><i class="Em">part</i></a> of a record - from tape (though you may request a larger block and read a smaller - record); nor can one read multiple blocks. Data from a single write is - therefore read by a single read. The block size used may be any value - supported by the device, the SCSI adapter and the system (usually between - 1 byte and 64 Kbytes, sometimes more). - <p class="Pp">When reading a variable record/block from the tape, the head - is logically considered to be immediately after the last item read, and - before the next item after that. If the next item is a file mark, but it - was never read, then the next process to read will immediately hit the - file mark and receive an end-of-file notification.</p> - </dd> - <dt>Fixed block-size:</dt> - <dd>Data written by the user is passed to the tape as a succession of fixed - size blocks. It may be contiguous in memory, but it is considered to be a - series of independent blocks. One may never write an amount of data that - is not an exact multiple of the blocksize. One may read and write the same - data as a different set of records. In other words, blocks that were - written together may be read separately, and vice-versa. - <p class="Pp">If one requests more blocks than remain in the file, the drive - will encounter the file mark. As there is some data to return (unless - there were no records before the file mark), the read will succeed, - returning that data. The next read will return immediately with a value - of 0. (As above, if the file mark is never read, it remains for the next - process to read if in no-rewind mode.)</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="BLOCK_SIZES"><a class="permalink" href="#BLOCK_SIZES">BLOCK - SIZES</a></h1> -<p class="Pp">By default, the driver will NOT accept reads or writes to a tape - device that are larger than may be written to or read from the mounted tape - using a single write or read request. Because of this, the application - author may have confidence that his wishes are respected in terms of the - block size written to tape. For example, if the user tries to write a 256KB - block to the tape, but the controller can handle no more than 128KB, the - write will fail. The previous <span class="Ux">FreeBSD</span> behavior, - prior to <span class="Ux">FreeBSD</span> 10.0, was to break up large reads - or writes into smaller blocks when going to the tape. The problem with that - behavior, though, is that it hides the actual on-tape block size from the - application writer, at least in variable block mode.</p> -<p class="Pp">If the user would like his large reads and writes broken up into - separate pieces, he may set the following loader tunables. Note that these - tunables WILL GO AWAY in <span class="Ux">FreeBSD 11.0</span>. They are - provided for transition purposes only.</p> -<dl class="Bl-tag"> - <dt>kern.cam.sa.allow_io_split</dt> - <dd> - <p class="Pp">This variable, when set to 1, will configure all - <code class="Nm">sa</code> devices to split large buffers into smaller - pieces when needed.</p> - </dd> - <dt>kern.cam.sa.%d.allow_io_split</dt> - <dd> - <p class="Pp">This variable, when set to 1, will configure the given - <code class="Nm">sa</code> unit to split large buffers into multiple - pieces. This will override the global setting, if it exists.</p> - </dd> -</dl> -<p class="Pp">There are several <a class="Xr">sysctl(8)</a> variables available - to view block handling parameters:</p> -<dl class="Bl-tag"> - <dt>kern.cam.sa.%d.allow_io_split</dt> - <dd> - <p class="Pp">This variable allows the user to see, but not modify, the - current I/O split setting. The user is not permitted to modify this - setting so that there is no chance of behavior changing for the - application while a tape is mounted.</p> - </dd> - <dt>kern.cam.sa.%d.maxio</dt> - <dd> - <p class="Pp">This variable shows the maximum I/O size in bytes that is - allowed by the combination of kernel tuning parameters (MAXPHYS, - DFLTPHYS) and the capabilities of the controller that is attached to the - tape drive. Applications may look at this value for a guide on how large - an I/O may be permitted, but should keep in mind that the actual maximum - may be restricted further by the tape drive via the SCSI READ BLOCK - LIMITS command.</p> - </dd> - <dt>kern.cam.sa.%d.cpi_maxio</dt> - <dd> - <p class="Pp">This variable shows the maximum I/O size supported by the - controller, in bytes, that is reported via the CAM Path Inquiry CCB - (XPT_PATH_INQ). If this is 0, that means that the controller has not - reported a maximum I/O size.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="FILE_MARK_HANDLING"><a class="permalink" href="#FILE_MARK_HANDLING">FILE - MARK HANDLING</a></h1> -<p class="Pp">The handling of file marks on write is automatic. If the user has - written to the tape, and has not done a read since the last write, then a - file mark will be written to the tape when the device is closed. If a rewind - is requested after a write, then the driver assumes that the last file on - the tape has been written, and ensures that there are two file marks written - to the tape. The exception to this is that there seems to be a standard - (which we follow, but do not understand why) that certain types of tape do - not actually write two file marks to tape, but when read, report a `phantom' - file mark when the last file is read. These devices include the QIC family - of devices. (It might be that this set of devices is the same set as that of - fixed block devices. This has not been determined yet, and they are treated - as separate behaviors by the driver at this time.)</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="PARAMETERS"><a class="permalink" href="#PARAMETERS">PARAMETERS</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver supports a number of - parameters. The user can query parameters using “mt param -l” - (which uses the <code class="Dv">MTIOCPARAMGET</code> ioctl) and the user - can set parameters using “mt param -s” (which uses the - <code class="Dv">MTIOCPARAMSET</code> ioctl). See <a class="Xr">mt(1)</a> - and <a class="Xr">mtio(4)</a> for more details on the interface.</p> -<p class="Pp">Supported parameters:</p> -<dl class="Bl-tag"> - <dt>sili</dt> - <dd>The default is 0. When set to 1, it sets the Suppress Incorrect Length - Indicator (SILI) bit on tape reads. Tape drives normally return sense data - (which contains the residual) when the application reads a block that is - not the same length as the amount of data requested. The SILI bit - suppresses that notification in most cases. See the SSC-5 spec (available - at t10.org), specifically the section on the READ(6) command, for more - information.</dd> - <dt>eot_warn</dt> - <dd>The default is 0. By default, the <code class="Nm">sa</code> driver - reports entering Programmable Early Warning, Early Warning and End of - Media conditions by returning a write with 0 bytes written, and - <code class="Dv">errno</code> set to 0. If <var class="Va">eot_warn</var> - is set to 1, the <code class="Nm">sa</code> driver will set - <code class="Dv">errno</code> to <code class="Dv">ENOSPC</code> when it - enters any of the out of space conditions.</dd> - <dt>protection.protection_supported</dt> - <dd>This is a read-only parameter, and is set to 1 if the tape drive supports - protection information.</dd> - <dt>protection.prot_method</dt> - <dd>If protection is supported, set this to the desired protection method - supported by the tape drive. As of SSC-5r03 (available at t10.org), the - protection method values are: - <dl class="Bl-tag"> - <dt>0</dt> - <dd>No protection.</dd> - <dt>1</dt> - <dd>Reed-Solomon CRC, 4 bytes in length.</dd> - <dt>2</dt> - <dd>CRC32C, 4 bytes in length.</dd> - </dl> - </dd> - <dt>protection.pi_length</dt> - <dd>Length of the protection information, see above for lengths.</dd> - <dt>protection.lbp_w</dt> - <dd>If set to 1, enable logical block protection on writes. The CRC must be - appended to the end of the block written to the tape driver. The tape - drive will verify the CRC when it receives the block.</dd> - <dt>protection.lbp_r</dt> - <dd>If set to 1, enable logical block protection on reads. The CRC will be - appended to the end of the block read from the tape driver. The - application should verify the CRC when it receives the block.</dd> - <dt>protection.rdbp</dt> - <dd>If set to 1, enable logical block protection on the RECOVER BUFFERED DATA - command. The <code class="Nm">sa</code> driver does not currently use the - RECOVER BUFFERED DATA command.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="TIMEOUTS"><a class="permalink" href="#TIMEOUTS">TIMEOUTS</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver has a set of default - timeouts for SCSI commands (READ, WRITE, TEST UNIT READY, etc.) that will - likely work in most cases for many tape drives.</p> -<p class="Pp">For newer tape drives that claim to support the SPC-4 standard - (SCSI Primary Commands 4) or later standards, the <code class="Nm">sa</code> - driver will attempt to use the REPORT SUPPORTED OPERATION CODES command to - fetch timeout descriptors from the drive. If the drive does report timeout - descriptors, the <code class="Nm">sa</code> driver will use the drive's - recommended timeouts for commands.</p> -<p class="Pp">The timeouts in use are reported in units of - <b class="Sy">thousandths</b> of a second via the - <var class="Va">kern.cam.sa.%d.timeout.*</var> <a class="Xr">sysctl(8)</a> - variables.</p> -<p class="Pp">To override either the default timeouts, or the timeouts - recommended by the drive, you can set one of two sets of loader tunable - values. If you have a drive that supports the REPORT SUPPORTED OPERATION - CODES timeout descriptors (see the <a class="Xr">camcontrol(8)</a> - <var class="Va">opcodes</var> subcommand) it is generally best to use those - values. The global <var class="Va">kern.cam.sa.timeout.*</var> values will - override the timeouts for all <code class="Nm">sa</code> driver instances. - If there are 5 tape drives in the system, they'll all get the same timeouts. - The <var class="Va">kern.cam.sa.%d.timeout.*</var> values (where %d is the - numeric <code class="Nm">sa</code> instance number) will override the global - timeouts as well as either the default timeouts or the timeouts recommended - by the drive.</p> -<p class="Pp">To set timeouts after boot, the per-instance timeout values, for - example: <var class="Va">kern.cam.sa.0.timeout.read</var>, are available as - sysctl variables.</p> -<p class="Pp">If a tape drive arrives after boot, the global tunables or - per-instance tunables that apply to the newly arrived drive will be - used.</p> -<p class="Pp">Loader tunables:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt>kern.cam.sa.timeout.erase</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.locate</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.mode_select</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.mode_sense</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.prevent</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.read</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.read_position</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.read_block_limits</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.report_density</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.reserve</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.rewind</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.space</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.tur</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.write</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.timeout.write_filemarks</dt> - <dd style="width: auto;"> </dd> -</dl> -<p class="Pp">Loader tunable values and <a class="Xr">sysctl(8)</a> values:</p> -<p class="Pp"></p> -<dl class="Bl-tag Bl-compact"> - <dt>kern.cam.sa.%d.timeout.erase</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.locate</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.mode_select</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.mode_sense</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.prevent</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.read</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.read_position</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.read_block_limits</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.report_density</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.reserve</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.rewind</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.space</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.tur</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.write</dt> - <dd style="width: auto;"> </dd> - <dt>kern.cam.sa.%d.timeout.write_filemarks</dt> - <dd style="width: auto;"> </dd> -</dl> -<p class="Pp">As mentioned above, the timeouts are set and reported in - <b class="Sy">thousandths</b> of a second, so be sure to account for that - when setting them.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver supports all of the ioctls - of <a class="Xr">mtio(4)</a>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> -<dl class="Bl-tag Bl-compact"> - <dt><span class="Pa">/dev/[n][e]sa[0-9]</span></dt> - <dd>general form:</dd> - <dt><span class="Pa">/dev/sa0</span></dt> - <dd>Rewind on close</dd> - <dt><span class="Pa">/dev/nsa0</span></dt> - <dd>No rewind on close</dd> - <dt><span class="Pa">/dev/esa0</span></dt> - <dd>Eject on close (if capable)</dd> - <dt><span class="Pa">/dev/sa0.ctl</span></dt> - <dd>Control mode device (to examine state while another program is accessing - the device, e.g.).</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver supports injecting End Of - Media (EOM) notification to aid application development and testing. EOM is - indicated to the application by returning the read or write with 0 bytes - written. In addition, when EOM is injected, the tape position status will be - updated to temporarily show Beyond of the Programmable Early Warning (BPEW) - status. To see BPEW status, use the <code class="Dv">MTIOCEXTGET</code> - ioctl, which is used by the “mt status” command. To inject an - EOM notification, set the</p> -<p class="Pp"><var class="Va">kern.cam.sa.%d.inject_eom</var></p> -<p class="Pp">sysctl variable to 1. One EOM notification will be sent, BPEW - status will be set for one position query, and then the driver state will be - reset to normal.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">mt(1)</a>, <a class="Xr">cam(4)</a>, - <a class="Xr">mtio(4)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">sa</code> driver was written for the CAM SCSI - subsystem by <span class="An">Justin T. Gibbs</span> and - <span class="An">Kenneth Merry</span>. Many ideas were gleaned from the - <code class="Nm">st</code> device driver written and ported from Mach 2.5 by - <span class="An">Julian Elischer</span>.</p> -<p class="Pp">The owner of record for many years was <span class="An">Matthew - Jacob</span>. The current maintainer is <span class="An">Kenneth - Merry</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">This driver lacks many of the hacks required to deal with older - devices. Many older SCSI-1 devices may not work properly with this driver - yet.</p> -<p class="Pp">Additionally, certain tapes (QIC tapes mostly) that were written - under <span class="Ux">FreeBSD</span> 2.X are not automatically read - correctly with this driver: you may need to explicitly set variable block - mode or set to the blocksize that works best for your device in order to - read tapes written under <span class="Ux">FreeBSD</span> 2.X.</p> -<p class="Pp">Partitions are only supported for status information and location. - It would be nice to add support for creating and editing tape - partitions.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 18, 2022</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |