CH(4)

💖 CH(4) — the SCSI media-changer (juke box) driver 💖

okay bestie, this is CH(4), straight out of the Kernel Interfaces Manual, and it's about the driver that runs your jukebox. No, not the music one. The robot arm that shuffles tapes around one. Sit down, hydrate, let's go. 🎀

---

✨ NAME ✨

ch — the SCSI media-changer (juke box) driver 🦋

---

✨ SYNOPSIS ✨

device ch

that's it. that's the whole vibe. 💅

---

✨ DESCRIPTION ✨

okay so the ch driver is the support system for a SCSI media changer. and what a media changer does is multiplex a whole bunch of media slots between a bunch of drives. so like, many slots, several drives, one little robotic matchmaker moving things around. 🧚

and listen — the changer device may optionally come with a bar code reader, which reads the label info stuck onto the media. so it can literally know what's on each tape. iconic behavior. 👑

💡 heads up: a SCSI adapter has to be separately configured into the system before you can configure a SCSI changer. no adapter, no changer, no exceptions.

so here's what happens: as the SCSI adapter gets probed during boot, the SCSI bus gets scanned for devices. any device that answers back as a 'Changer' type device gets 'attached' to the ch driver. cute, right?

now, history lesson, don't scroll: in FreeBSD releases prior to 2.1, the first one found gets attached as ch0, the next as ch1, etc. Beginning in 2.1 it became possible to specify what ch unit a device should come on line as — go check scsi(4) for the details on kernel configuration. 📖

---

✨ KERNEL CONFIGURATION ✨

you only have to explicitly configure one ch device. that's it. the data structures get dynamically allocated as media changes are found on the SCSI bus. so like, it handles itself. lowkey self-sufficient. 💅

---

✨ IOCTLS ✨

user mode programs talk to the changer driver through a bunch of ioctls, all described below. here's the important mapping: changer element addresses used in the communication between the kernel and the changer device get mapped to zero-based logical addresses.

element types are specified like this:

• CHET_MT — medium transport element (picker). 🫳
• CHET_ST — storage element (slot). 📦
• CHET_IE — import/export element (portal). 🌀
• CHET_DT — data transfer element (drive). 💾

the following ioctl(2) calls apply to the changer, and they're all defined in the header file <sys/chio.h>. 🌸

---

• CHIOMOVE (struct changer_move) — move a medium from one element to another (MOVE MEDIUM) using the current picker. the source and destination elements are specified in a changer_move structure, which includes at least the following fields:

u_int cm_fromtype; /* element type to move from */
u_int cm_fromunit; /* logical unit of from element */
u_int cm_totype;   /* element type to move to */
u_int cm_tounit;   /* logical unit of to element */
u_int cm_flags;    /* misc. flags */

if the CM_INVERT in the cm_flags field is set, the medium changer is instructed to flip the medium while moving it. yes. it does a little flip. 🤸

• CHIOEXCHANGE (struct changer_exchange) — move the medium located in the source element to the first destination element, and move the medium that had been in the first destination element to the second destination element. in case of a simple exchange, the source and second destination elements should be the same. the current picker is used to perform the operation. the addresses of the affected elements are specified to the ioctl in a changer_exchange structure which includes at least the following fields:

u_int ce_srctype;        /* element type of source */
u_int ce_srcunit;        /* logical unit of source */
u_int ce_fdsttype; /* element type of first destination */
u_int ce_fdstunit; /* logical unit of first destination */
u_int ce_sdsttype; /* element type of second destination */
u_int ce_sdstunit; /* logical unit of second destination */
u_int ce_flags;  /* misc. flags */

in ce_flags, CM_INVERT1 and/or CM_INVERT2 may be set to flip the first or second medium during the exchange operation, respectively.

⚠️ not me telling you this: this operation is untested. fr fr. tread carefully bestie. 💀

• CHIOPOSITION (struct changer_position) — position the current picker in front of the specified element. the element is specified with a changer_position structure, which includes at least the following elements:

u_int cp_type;  /* element type */
u_int cp_unit;  /* logical unit of element */
u_int cp_flags; /* misc. flags */

the cp_flags field may be set to CP_INVERT to invert the picker during the operation.

• CHIOGPICKER (int) — return the logical address of the current picker. 📍
• CHIOSPICKER (int) — select the picker specified by the given logical address. 👈
• CHIOGPARAMS (struct changer_params) — return the configuration parameters for the media changer. this ioctl fills the changer_params structure passed by the user with at least the following fields:

u_int cp_npickers; /* number of pickers */
u_int cp_nslots;   /* number of slots */
u_int cp_nportals; /* number of import/export portals */
u_int cp_ndrives;  /* number of drives */

this call can be used by applications to query the dimensions of the jukebox before using the CHIGSTATUS ioctl to query the jukebox status. 🔍

• CHIOIELEM — perform the INITIALIZE ELEMENT STATUS call on the media changer device. this forces the media changer to update its internal status information with respect to loaded media. it also scans any barcode labels provided that it has a label reader. the ch driver's status is not affected by this call. 🧹
• CHIOGSTATUS (struct changer_element_status_request) — perform the READ ELEMENT STATUS call on the media changer device. this call reads the element status information of the media changer and converts it to an array of changer_element_status structures.

with each call to CHIOGSTATUS, the status of one or more elements of one type may be queried. ✨

the application passes a changer_element_status_request structure to the ch driver which contains the following fields:

u_int                          cesr_element_type;
u_int                          cesr_element_base;
u_int                          cesr_element_count;
u_int                          cesr_flags;
struct changer_element_status *cesr_element_status;

this structure is read by the driver to determine the type, logical base address and number of elements for which information is to be returned in the array of changer_element_status structures pointed to by the cesr_element_status field. the application must allocate enough memory for cesr_element_count status structures (see below). the cesr_flags can optionally be set to CESR_VOLTAGS to indicate that volume tag (bar code) information is to be read from the jukebox and returned. 🏷️

the cesr_element_base and cesr_element_count fields must be valid with respect to the physical configuration of the changer. if they are not, the CHIOGSTATUS ioctl returns the EINVAL error code. 🚫

the information about the elements is returned in an array of changer_element_status structures. this structure include at least the following fields:

u_int            ces_addr;      /* element address in media changer */
u_char           ces_flags;     /* see CESTATUS definitions below */
u_char           ces_sensecode; /* additional sense code for element */
u_char           ces_sensequal; /* additional sense code qualifier */
u_char           ces_invert;    /* invert bit */
u_char           ces_svalid;    /* source address (ces_source) valid */
u_short          ces_source;    /* source address of medium */
changer_voltag_t ces_pvoltag;   /* primary volume tag */
changer_voltag_t ces_avoltag;   /* alternate volume tag */
u_char           ces_idvalid;   /* ces_scsi_id is valid */
u_char           ces_scsi_id;   /* SCSI id of element (if ces_idvalid is nonzero) */
u_char           ces_lunvalid;  /* ces_scsi_lun is valid */
u_char           ces_scsi_lun;  /* SCSI lun of element (if ces_lunvalid is nonzero) */

the ces_addr field contains the address of the element in the coordinate system of the media changer. it is not used by the driver, and should be used for diagnostic purposes only. 🩺

the following flags are defined for the ces_flags field:

• CESTATUS_FULL — a medium is present. ✅
• CESTATUS_IMPEXP — the medium has been deposited by the operator (and not by a picker). 🙋
• CESTATUS_EXCEPT — the element is in an exceptional state (e.g. invalid barcode label, barcode not yet scanned). 😭
• CESTATUS_ACCESS — the element is accessible by the picker. 🫴
• CESTATUS_EXENAB — the element supports medium export. 📤
• CESTATUS_INENAB — the element supports medium import. 📥

🎀 note that not all flags are valid for all element types. so don't come for the driver when a flag doesn't apply to your slot, okay?

---

✨ NOTES ✨

this version of the ch driver has been tested with a DEC TZ875 (5 slot, one DLT drive) and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader). so like, real hardware, real results. 💪

many of the features the ch driver supports are not thoroughly tested due to the fact that the devices available for testing do not support the necessary commands. 😭 this is true for alternate volume tags, media flipping, import/export element handling, multiple picker operation and other things. so bestie, if you're using those, you're lowkey on your own adventure. 🦋

---

✨ FILES ✨

• /dev/ch[0-9] — device entries 🎀

---

✨ DIAGNOSTICS ✨

if the media changer does not support features requested by the ch driver, it will produce both console error messages and failure return codes to the ioctls described here. so you'll get yelled at in two different ways. 💀

---

✨ SEE ALSO ✨

chio(1), cam(4), cd(4), da(4), sa(4) 🔗

---

✨ HISTORY ✨

the ch driver appeared in 386BSD 0.1. an elder. a legend. 👑

✨ AUTHORS ✨

okay so bestie, let's give credit where credit is due, because this whole driver was a group project and the lore is kinda iconic 💖

• Jason R. Thorpe <thorpej@and.com> wrote the ch driver, for And Communications, over at http://www.and.com/ 👑 like, the whole thing, from scratch. main character energy fr fr.
• Then Stefan Grefen <grefen@goofy.zdv.uni-mainz.de> added it to the system, and honestly? the way that he apparently just had one of these devices lying around is so real of him 🙈 it's giving "oh this old thing? yeah I own one."
• Then Kenneth Merry <ken@FreeBSD.org> ported it to CAM, which is a whole glow-up, slay ✨
• And finally Hans Huebner</hans> <hans@artcom.de> updated it to support volume tags, aka the feature we've been yapping about this entire page 🎀

no cap, every one of them ate and left zero crumbs 🫶 so if you're out here using this driver, go say thank you in your heart or whatever 💅

---

and that's a wrap on the whole page, bestie!! 🌸 this version is the Debian one, dated May 14, 1998, and it lives at section CH(4) in the manual 📖 go forth and query those changer volumes responsibly, ily, bye 🦋💜