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, 425 insertions, 0 deletions
diff --git a/static/freebsd/man4/sa.4 3.html b/static/freebsd/man4/sa.4 3.html new file mode 100644 index 00000000..326ad744 --- /dev/null +++ b/static/freebsd/man4/sa.4 3.html @@ -0,0 +1,425 @@ +<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> |