user-vt-realizer-configuration 5 file formats nosh
user-vt-realizer-configuration configuration of user virtual terminal realizers

## Description

The various realizers for user-space virtual terminals — console-fb-realizer 1, console-evdev-realizer 1, console-ugen-hid-realizer 1, console-uhid-realizer 1, console-wscons-realizer 1, console-pcat-mouse-realizer 1, console-pcat-keyboard-realizer 1, console-ps2-mouse-realizer 1, and console-kvt-realizer 1 — automatically use resources located in subdirectories of their working directories. The filenames of these resources are determined by the category of I/O device being realized upon, and by the identity of that I/O device. The realizers employ a search path mechanism attempting to find the files to use.

All of these realizers generally run as services, and their working directories are the service directories. console-termio-realizer 1 is an ad-hoc tool that generally does not run as a service, and so does not employ this configuration system. All of its various resources are supplied as command-line arguments.

## Resource subdirectories

The various subdirectories, not all of which are needed by all realizers, are:

`./vcs/`

  contains the user-space virtual terminal back end to connect to (a subdirectory whose contents are detailed in user-vt 5)

`./kbdmaps/`

  contains the keyboard map (read-only) data file (a file whose format is detailed in console-keyboard-map 5)

`./mice-aggregate/`

  contains the aggregate mouse state (read-write) file

`./keyboards-aggregate/`

  contains the aggregate keyboard state (read-write) file

## Shared and private resources

With this mechanism different configurations can be specified locally for individual realized devices, or global configurations can be shared amongst multiple realized devices.

- Local resources are private to each individual realizer. They are directly stored in the realizer's working directory subdirectories.

- Global resources are shared by multiple realizers in order to combine I/O devices. By convention they are to be found in subdirectories of the `/etc/system-control/convert/user-vt/` directory. Symbolic links in the realizer's working directory point to those subdirectories.

### Examples

Keyboard map configuration is almost always globally shared, and is by convention a collection of symbolic links in a `/etc/system-control/convert/user-vt/kbdmaps/` directory. So this symbolic link is usually in place:

`./kbdmaps` → `/etc/system-control/convert/user-vt/kbdmaps`

Virtual terminal back end configuration is almost always globally shared, and is by convention a collection of symbolic links in a `/etc/system-control/convert/user-vt/vcs/` directory. So this symbolic link is usually in place:

`./vcs` → `/etc/system-control/convert/user-vt/vcs`

## Searching

To determine which file/directory to use within each of those subdirectories, realizers employ the identity of the I/O device being realized to construct progressively shorter file/directory names, finally falling back to the file/directory name `default`. Usually the identity is read from the device or is determined by the device's bus location, but for some devices it is also taken from the basename of the devicename argument given on the realizer's command lines,

The specific search path is determined by the category of device:

- Generic USB (usb-ugen) realizers use a sequence of device paths that are combinations of the device class, device subclass, vendor ID, product ID, bus number, and address of the device: `usb.ugen.Bbus.Aaddress.VvendorID.PproductID`, `usb.ugen.Bbus.Aaddress.VvendorID`, `usb.ugen.VvendorID.PproductID`, `usb.ugen.VvendorID`, `usb.ugen.Cclass.Ssubclass.VvendorID`, `usb.ugen.Cclass.Ssubclass`, `usb.ugen.Cclass`, `usb.ugen.Bbus.Aaddress`, `usb.ugen`. The class, subclass, vendorID, and productID are 4-digit lowercase hexdecimal numbers.

- PC/AT keyboard realizers use a name that is a combination of the EISA PaP ID for a PC/AT keyboard and the device basename, shortened to one that omits the device basename; e.g. `eisa.pnp0301.atkbd0` shortened to `eisa.pnp0301`.

- PC/AT mouse realizers use a name that is a combination of the EISA PaP ID for a PC/AT mouse and the device basename, shortened to one that omits the device basename; e.g. `eisa.pnp0F01.bpsm0` shortened to `eisa.pnp0F01`.

- PS/2 mouse realizers use a name that is a combination of the EISA PaP ID for a PS/2 mouse and the device basename, shortened to one that omits the device basename; e.g. `eisa.pnp0F03.mice` shortened to `eisa.pnp0F03`.

- evdev realizers use a name that is a combination of a prefix and the device basename, shortened to one that omits the device basename; e.g. `evdev.event0` shortened to `evdev`.

- framebuffer realizers use a name that is a combination of an unassigned EISA PaP ID and the device basename, shortened to one that omits the device basename: `eisa.pnpFB00.basename`, and `eisa.pnpFB00`.

- USB-HID (uhid) realizers use a sequence of device paths that include the device basename: `usb.basename`, and `usb.uhid`. No class or ID information is available from the device driver.

- KVT realizers use a name that is a combination of a prefix and the device basename, shortened to one that omits the device basename: `kvt.basename`, and `kvt`.

### Examples

Global keyboard map configuration is by convention a collection of symbolic links in a `/etc/system-control/convert/user-vt/kbdmaps/` directory, which in turn (in order to keep the configuration separate from the actual compiled map files) point to the actual map files in a `/etc/system-control/convert/kbdmaps/` directory. So these symbolic links would have the following consequences:

`/etc/system-control/convert/user-vt/kbdmaps/default` → `/etc/system-control/convert/kbdmaps/jp.109`

  This sets the default keyboard map file as the Japanese 109-key Windows keyboard map file.

`/etc/system-control/convert/user-vt/kbdmaps/eisa.pnp0301` → `/etc/system-control/convert/kbdmaps/us.104`

  This sets the keyboard map file for all PC/AT keyboards as the U.S.A. 104-key Windows keyboard map file.

`/etc/system-control/convert/user-vt/kbdmaps/kvt` → `/etc/system-control/convert/kbdmaps/br.106`

  This sets the keyboard map file for all KVT keyboards as the Brazilian ABNT2 106-key Windows keyboard map file.

Global virtual terminal back end configuraton is by convention a collection of symbolic links in a `/etc/system-control/convert/user-vt/vcs/` directory, which in turn point to the actual virtual terminal directories in (conventionally) `/run/dev/`. So these symbolic links would have the following consequences:

`/etc/system-control/convert/user-vt/vcs/kvt` → `/run/dev/head0`

  This sets all KVT realizers to use the `head0` user-space virtual terminal.

`/etc/system-control/convert/user-vt/vcs/eisa.pnp0301.atkbd0` → `/run/dev/head0`

  This sets the realizer of the first PC/AT keyboard to use the `head0` user-space virtual terminal.

`/etc/system-control/convert/user-vt/vcs/eisa.pnpFB00.fb0` → `/run/dev/head0`

  This sets the realizer of the second framebuffer to use the `head0` user-space virtual terminal.

`/etc/system-control/convert/user-vt/vcs/eisa.pnpFB00.fb1` → `/run/dev/head1`

  This sets the realizer of the second framebuffer to use the `head1` user-space virtual terminal.

## Author

Jonathan de Boyne Pollard