If you've got no idea what we're talking about here, let me take a moment to explain.

We're not talking about configuring the connection at the hardware level. So this isn't about supported baud rates, parity, stop bits, 7E1, 8N1, hardware handshaking or anything along those lines.

Rather, we're talking terminal descriptions. As well as the printable alpha-numeric characters, every physical terminal or terminal emulator needs to understand certain control sequences to do things like move the cursor around, scroll, clear the screen, change colors, set underlining and bold fonts, and so on.

These control sequences are essentially different for every terminal, although admittedly there is now a lot of common ground for the simplest and most essential controls.

The problem is that it's the system at the remote end of the connection that needs to send the right codes for your terminal. Since the remote system usually wants to support as many different terminal types as possible, (because it has no idea who might be connecting to it), it needs to have a large database with descriptions of every possible terminal that just might connect one day.

In many non-UNIX-like systems, the operation of the local display and keyboard is tightly bound to various functions of the OS. It's expected that you'll sit in front of the machine to use it. If remote access is possible, it's implemented quite separately from the low-level drivers for the local hardware.

Not so on a BSD system. The system's physical console is not really a special case. The local display and keyboard are abstracted from the system and a piece of kernel code uses them to emulate a terminal. That emulated terminal is then connected to the rest of the system in more or less the same way that any other connection is, such as a serial port or networked ssh socket.

Connecting to an OpenBSD machine from a different system over the network with ssh should work just fine, as long as the terminal that you're using to connect has an entry in the termtypes database, (and it almost certainly does).

If you connect via a serial port, you'll need to set the terminal type yourself. The vast majority of terminals understand enough sequences from the vt220 terminal type to make basic operations such as cursor movement and clearing the screen work, so for simple command line work setting it to vt220 might even be sufficient.

Most people running OpenBSD on i386 or amd64 hardware in 2023 will find that their display hardware is supported by the framebuffer console, and it's been like this for about ten years now. Although the kernel starts booting in the 80 × 25 character VGA text mode set up by the BIOS, it quickly changes to a bitmapped display, such as 1920 × 1080, and draws each character graphically.

This not only allows for a much larger terminal size, (measured in characters), but also potentially allows for a full range of text effects and use of color with no restrictions. This is in contrast to the VGA text console which, for example, doesn't allow free use of color together with underlining due to hardware limitations.

If we were to create an entirely custom and proprietary set of control sequences, then the chances are high that the remote system wouldn't have anything like it in it's database. On the other hand, if we use code sequences that are already used by a common terminal type, such as vt220, and supplement them with additional codes, we can expect that the remote system will at least be able to control the essential basic terminal functions. Color and different fonts might not work, but at least the text will be in the right place.

This is basically the situation today with the wscons code in OpenBSD. The terminal emulation code fully supports color, for example, but by default most programs running on the console won't use it, (unless they ignore the termtypes database and make their own assumptions about what the terminal supports).

The default terminal type, in other words the terminal type that the rest of the programs on the system are targeting, is set to vt220. This is a very safe default, and allows users to connect to just about any remote system without breakage.

However it's also what is preventing most local programs from using any features that are not supported by the vt220 terminfo entry, including color.

The terminfo file does include an entry specifically for the OpenBSD console, called pccon. This was added in 2011, and has seen a few minor updates since. However, it has a few issues:

If the wscons code emulated a common, well-known terminal entry in the terminfo database, which also happened to provide more functions than vt220, then our problem would be solved. The changes to make this happen only need to be made at the local end, since by definition, if the chosen entry is common and well-known, then we can assume that any remote systems will support it.

If we boot in to a fresh installation of OpenBSD 7.2 and set the TERM environment variable to xterm, we can quickly see that support for some of the control sequences is missing. Simple terminal commands work, but launching vi and trying to edit a text file results in screen re-painting problems when we scroll.

Lots of programs from the ports tree will also show similar issues.

From looking at the output, it's fairly obvious that some kind of cursor movement controls are missing.

To find out more, we can compare the terminfo entries for vt220 and xterm. This is slightly awkward, as the terminfo format allows one entry to include parts from other entries, so we need to look at quite a few to build the whole picture.

Some of the capabilities that are defined in xterm but not in vt220 are already supported by the wscons code. This includes the color setting sequences, setab and setaf, as well as two that work to hide and show the cursor, civis and cnorm. These will automatically function as expected when we set TERM=xterm, without further modification of the code.

However, other capabilities that are defined in the terminfo entry but not yet implemented by wscons include:

If you've read my 'Candlelit Consoles' article, some of this will likely feel familiar. We're going to be looking at /usr/src/sys/dev/wscons/wsemul_vt100_subr.c again, because that's where a lot of the console emulation code resides.

Specifically, control is handed to the function wsemul_vt100_handle_csi in this file once the CSI has been detected. This function is basically one massive switch statement, with several smaller switch statements embedded, that either pass control to various other functions that implement the sequence in question, set flags, or do other small manipulations of the state of the console directly.

Here is the code to implement the vpa and hpa capabilities:

As might be expected, the code only needs to change one value. In this case, the current row and column are both stored in edp, which is defined as a struct wsemul_vt100_emuldata in wsemul_vt100var.h. This file also contains the definitions for various macros that are used throughout the CSI implementation code, such as DEF1_ARG as used above.

This code is also fairly trivial:

Unsurprisingly, the wscons code already contains functions to scroll the screen. The wsemul_vt100_scrollup routine is called when the cursor is already on the bottom line of the display, and needs to move to what would be the next line - this is just normal one-line scrolling.

What we want to do here, though, is allow these functions to be called directly by control sequences, and pass them the argument received as part of that sequence, as that represents the number of lines that we want to scroll.

Luckily, these functions already handle two complexities that we would otherwise have to deal with. The first of these is scroll regions, where a only a pre-defined set of rows is scrolled rather than the whole display, and the second is characters which are either double width, double height, or both.

Implementing reverse tabs actually requires some new logic, but it's still very simple:

This is effectively the reverse of the algorithm used in the existing forward tab code, which can be found in wsemul_vt100.c, within the function wsemul_vt100_output_c0c1.

First we check to see if we are already in the left-most column. If we are, then we don't need to do anything at all, and the code just becomes a NOP.

To find the previous tab-stop, in principle we just need to step back from the current cursor position one column at a time until we either find a column that is flagged as a tab-stop, or we reach the leftmost first column.

The value of edp->tabs is usually expected to be a pointer to an area of memory, one byte for every column, containing flags that indicate whether that particular column is a tab-stop by being set to a non-zero value.

However, the normal forward tabbing code in wsemul_vt100.c also checks whether edp->tabs is a null pointer, (which can happen in wsemul_vt100_cnattach), in other words, no memory has been allocated. In this case, that code uses a simple fixed set of tab-stops calculated as being at every eighth column.

Patching the kernel with the above code, we can see that already a lot of programs will happily run and produce a correct display on the console with TERM set to xterm.

The biggest problem still remaining is that the F1 - F4 keys are not recognised by any program that uses the terminfo database to interpret them.

Amazingly, they don't even work with the default vt220 terminfo entry, so at least our switch hasn't broken this functionality.

The wscons code that defines the sequences sent by various function keys is in wsemul_vt100_keys.c. Here we can see that for F1 - F4, the control sequences are defined as ␛[11~, ␛[12~, ␛[13~, and ␛[14~. This is actually the most logical, natural, and technically correct way to extend backwards the set of sequences used for F5 onwards.

However, the terminfo entry for xterm expects ␛OP, ␛OQ, ␛OR, and ␛OS. These are the control sequences traditionally associated with the PF1 - PF4 keys, (and in fact they are defined as such further down in wsemul_vt100_keys.c). These PF keys were the only function keys on the original VT52 terminal, and were located at the top of the numeric keypad.

To fix this, we've got two choices. We could leave the definitions in wsemul_vt100_keys.c alone, and change the assignment in the various keyboard mappings found in /usr/src/sys/dev/pckbc/wskbdmap_mfii.c to make the physical F1 - F4 keys send the sequence designated as KS_KP_F1 - KS_KP_F4. Alternatively, we could just change the definitions for F1 - F4 in wsemul_vt100_keys.c to send ␛OP, ␛OQ, ␛OR, and ␛OS.

Note that the first approach won't affect the use of CONTROL-ALT-Fkey to switch virtual terminals, as the command function, (I.E. switching VT), for these keys is defined separately.

I've tested both methods of making F1 - F4 work with the xterm terminfo entry, and they both give satisfactory results.

If you're lucky enough to have a keyboard that sports F13 - F24 keys, (or if you've mapped these sequences to other key combinations, such as shift-F1 - shift-F12), there is additional work to do. The sequences expected when running with TERM=xterm are also different to those which wscons currently generates. In this case, changing them in wsemul_vt100_keys.c is the obvious solution.

Xterm implements quite a few features which wscons doesn't yet support. If we're going to use the xterm terminfo entry with wscons, it would be nice to implement at least some of them, as obviously any program parsing that terminfo entry is going to assume that they are available. I demonstrated code to implement dim text in my Candlelit Console article, and if you've tried the accompanying patchset you'll know that it also includes sample implementations of strikethrough and double underline. These were only intended as a proof of concept, and only worked for displays using the 32bpp functions, but they do indeed show that the functionality is not difficult to add.

Today we've seen how, with just a few lines of code, it's possible to make the console broadly compatible with a widely used terminal description which supports far more features than a vt220.