SA(4)

💖 SA(4) — SCSI Sequential Access device driver 💖

Kernel Interfaces Manual ✨ SA(4) ✨

---

🌸 NAME 🌸

sa — the SCSI Sequential Access device driver. bestie this is the tape driver. yes tapes. they're iconic and they're not going anywhere (they are going somewhere, that's literally what tapes do).

---

🎀 SYNOPSIS 🎀

device sa

that's it. that's the whole vibe. one line. slay.

---

🦋 DESCRIPTION 🦋

okay so sa is the driver that holds it down for every single SCSI device in the sequential access class that's hooked up to your system through a supported SCSI Host Adapter. and what's in the sequential access class? tape, plus all the other linear access devices out there. if it reads and writes in order and you can't just jump around it like a disk, it's in the club. 💅

now — a SCSI Host adapter has to be separately configured into the system first, before you can even think about configuring a SCSI sequential access device. adapter first, tape second. the order matters, no cap. 🌟

---

💜 MOUNT SESSIONS 💜

the whole sa driver is built around one concept and it's called a “mount session”. what is it? it's the period between the moment a tape gets mounted, and the moment it gets unmounted. that's the window. 🫶

any parameters you set during a mount session stay in effect for the rest of that session — or until something replaces them. they don't just wander off. ✨

and there's more than one way to unmount the tape and close the session out. here's the list:

1. Closing a rewind device, which we call sub-mode 00 down below. example: /dev/sa0. 🎀
2. Using the MTOFFL ioctl(2) command — which you can reach through the ‘offline’ command of mt(1). 💅

also super important: tape devices are exclusive open devices, with exactly one exception — when a control mode device is opened. in that exception case, exclusive access is only sought when it's actually needed (like, say, to set parameters). so it's not clingy 24/7, only when it has to be. 😌

---

✨ SUB-MODES ✨

bits 0 and 1 of the minor number? those are your ‘sub-modes’. and the sub-modes are all about one thing: what happens when the device gets closed. three of them. let's go. 🔥

• 00 — a close will rewind the device. and if the tape has been written to, then a file mark gets written before the rewind is requested. the device is unmounted. bye bestie 👋
• 01 — a close will leave the tape mounted. if the tape was written to, a file mark gets written. no other head positioning happens at all. any further reads or writes occur directly after the last read, or after the written file mark. it just keeps going. ⭐
• 10 — a close will rewind the device. if the tape has been written to, a file mark gets written before the rewind is requested. and then — on completion of the rewind — an unload command is issued. the device is unmounted. full send. 💀

---

🌈 BLOCKING MODES 🌈

SCSI tapes can run in either ‘variable’ or ‘fixed’ block-size mode. that's the split. 💫

most QIC-type devices run in fixed block-size mode. meanwhile most nine-track tapes and many new cartridge formats allow variable block-size. and the difference between the two is genuinely this:

Variable block-size: every write you make to the device results in a single logical record written to the tape. you can never read or write part of a record from tape — though you can request a larger block and read a smaller record. and you can't read multiple blocks either. so data from a single write is read by a single read, periodt. 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. 🎀

when you're 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. so 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. rude but consistent. 😭

Fixed block-size: data written by the user gets passed to the tape as a succession of fixed size blocks. it may be contiguous in memory, but it's considered to be a series of independent blocks. you may never write an amount of data that isn't an exact multiple of the blocksize. 💅

and here's the fun part — you 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. it's giving remix. ✨

if you request more blocks than remain in the file, the drive will encounter the file mark. since there's still some data to return (unless there were no records before the file mark), the read will succeed and return that data. the next read returns immediately with a value of 0. and same as above — if the file mark is never read, it stays there for the next process to read if you're in no-rewind mode. 🦋

---

🎀 BLOCK SIZES 🎀

okay so 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. NOT. capital N-O-T. 🙈

and why is that a good thing? because the application author gets to have confidence that his wishes are respected in terms of the block size written to tape. so like — 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 FreeBSD behavior, prior to FreeBSD 10.0, was to break up large reads or writes into smaller blocks when going to the tape. and the problem with that behavior is that it hides the actual on-tape block size from the application writer — at least in variable block mode. sneaky. not slay. 😤

if the user would like his large reads and writes broken up into separate pieces, he may set the following loader tunables. but listen —

these tunables WILL GO AWAY in FreeBSD 11.0. they are provided for transition purposes only. they are not the main character, they're the side character with a countdown timer. ⏳

• kern.cam.sa.allow_io_split — this variable, when set to 1, will configure all sa devices to split large buffers into smaller pieces when needed. 🫶
• kern.cam.sa.%d.allow_io_split — this variable, when set to 1, will configure the given sa unit to split large buffers into multiple pieces. and this will override the global setting, if it exists. so the specific one wins. 👑

and there are several sysctl(8) variables available to view block handling parameters. viewing only. look, don't touch. 💅

• kern.cam.sa.%d.allow_io_split — this variable lets the user see, but not modify, the current I/O split setting. and 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. it's locked for your own good bestie. 🔒
• kern.cam.sa.%d.maxio — 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 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. so it's a guide, not a promise. ✨
• kern.cam.sa.%d.cpi_maxio — this variable shows the maximum I/O size supported by the controller, in bytes, reported via the CAM Path Inquiry CCB (XPT_PATH_INQ). and if this is 0? that means the controller has not reported a maximum I/O size. it said nothing. silent. 🤐

---

💅 FILE MARK HANDLING 💅

file mark handling on write is automatic. you don't have to think about it. the driver thinks about it for you. 🧚

so: 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. 💖

and if a rewind is requested after a write, then the driver assumes the last file on the tape has been written, and ensures that there are two file marks written to the tape. two. not one. two. ✌️

the exception to all of 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, they report a `phantom' file mark when the last file is read. spooky. 👻 these devices include the QIC family of devices.

and, as the original so honestly puts it: 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. we don't know, and we're not pretending to know. respect. 🫡

---

⭐ PARAMETERS ⭐

the sa driver supports a number of parameters. here's how you talk to them: 🌸

• the user can query parameters using mt param -l (which uses the MTIOCPARAMGET ioctl)
• the user can set parameters using mt param -s (which uses the MTIOCPARAMSET ioctl)

see mt(1) and mtio(4) for more details on the interface. 🎀

and now, the supported parameters. all of them. buckle up. ✨

• sili — the default is 0. when set to 1, it sets the Suppress Incorrect Length Indicator (SILI) bit on tape reads. here's the tea: 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. 💅
• eot_warn — the default is 0. by default, the sa driver reports entering Programmable Early Warning, Early Warning and End of Media conditions by returning a write with 0 bytes written, and errno set to 0. if eot_warn is set to 1, the sa driver will set errno to ENOSPC when it enters any of the out of space conditions. so like. do you want the quiet warning or the loud one. your call. 🫶
• protection.protection_supported — this is a read-only parameter, and it's set to 1 if the tape drive supports protection information. that's it, that's the whole job. 🦋
• protection.prot_method — 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:
  • 0 — no protection.
  • 1 — Reed-Solomon CRC, 4 bytes in length.
  • 2 — CRC32C, 4 bytes in length.
• protection.pi_length — length of the protection information, see above for lengths. 📏
• protection.lbp_w — 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. ✅
• protection.lbp_r — 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. 👀
• protection.rdbp — if set to 1, enable logical block protection on the RECOVER BUFFERED DATA command. the sa driver does not currently use the RECOVER BUFFERED DATA command. so like. it's there. it's vibing. it's not being used. 💀

---

🎀 IOCTLS 🎀

the sa driver supports all of the ioctls of mtio(4). all of them. every single one. periodt. 💖

---

💜 FILES 💜

• /dev/[n][e]sa[0-9] — general form:
• /dev/sa0 — Rewind on close
• /dev/nsa0 — No rewind on close
• /dev/esa0 — Eject on close (if capable)
• /dev/sa0.ctl — Control mode device (to examine state while another program is accessing the device, e.g.). 🫶

---

✨ and that's part one bestie, there's more coming, don't go anywhere ✨

🩺 DIAGNOSTICS 🩺

okay bestie, this part is lowkey the coolest thing ever — the sa driver can inject an End Of Media (EOM) notification, purely to help you with application development and testing. it's like a little simulator mode, and it's giving dev environment slay ✨

EOM gets indicated to your application by returning the read or write with 0 bytes written. that's the signal, that's the vibe check, that's how you know 💅

and there's more — when EOM is injected, the tape position status gets updated to temporarily show Beyond of the Programmable Early Warning (BPEW) status. yes, BPEW, say it with your chest 🗣️

to actually see that BPEW status, you use the MTIOCEXTGET ioctl, which is the same one the mt status command uses. iykyk 🫶

so to inject an EOM notification, you just set this sysctl variable to 1:

kern.cam.sa.%d.inject_eom

and here's the cute part: one EOM notification gets sent, BPEW status is set for one position query, and then the driver state resets back to normal. one and done, no leftovers, no mess, periodt 🎀

---

👀 SEE ALSO 👀

• mt(1)
• cam(4)

go read those too bestie, they're part of the lore 📚

---

👑 AUTHORS 👑

the sa driver was written for the CAM SCSI subsystem by Justin T. Gibbs and Kenneth Merry — absolute icons, no cap 🫡

many of the ideas were gleaned from the st device driver, which was written and ported from Mach 2.5 by Julian Elischer. so basically a whole lineage of talented people, and we're all just standing on their shoulders 💜

the owner of record for many years was Matthew Jacob. the current maintainer is Kenneth Merry. thank you for your service, fr fr 🌸

---

💀 BUGS 💀

okay so, real talk, 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. it's giving "we're working on it" energy, and that's honest 🙈

additionally — and this is important, don't skip it — certain tapes (QIC tapes mostly) that were written under FreeBSD 2.X are not automatically read correctly with this driver. so you may need to explicitly set variable block mode, or set it to the blocksize that works best for your device, in order to read tapes written under FreeBSD 2.X. yes bestie, you have to do it manually. it's not automatic. it's giving vintage tape archaeology 🏺

and one more: partitions are only supported for status information and location. it would be nice to add support for creating and editing tape partitions, but that's not a thing right now. manifesting it for a future release tho ✨🦋

---

and that's the whole page, bestie!! this one came from the Debian crew, dated May 5, 2017, and it's page SA(4) of your friendly neighborhood manual set. go forth and back up your data responsibly, mwah 💋🎀