The difficulty arises from the fact that on pretty much any modern desktop operating system, a user-mode program can't just directly access the hardware or kernel data structures in this way.

To make things worse, although we could in theory write a file containing our screendump data to the filesystem directly from within the kernel, this is generally considered a very bad idea. In fact, doing anything in the kernel that could be achieved just as well in userspace is usually a bad design choice.

So the correct way to solve this problem and add the missing feature is to write a small amount of kernel code to pass the required data to userspace, then code a separate regular userspace program to process it and finally write the data out to disk.

In both cases, we'll be adding a new ioctl to the wscons subsystem. This ioctl can then be called from a standard usermode C program, and then kernel will dutifully copy the requested data into a buffer that the usermode program has pre-allocated and then passed to it.

If you're not familiar with the concept of an ioctl, you might want to read the manuals page for ioctl and wsdisplay before continuing with this article.

The format of the character cell data in the wscons subsystem is fairly typical of a character based terminal. Two values are stored for each character, one being the ASCII character value, and the other being an attribute value. Technically, the character value is a unicode value rather than ASCII, but to keep things simple we'll treat the values as unsigned chars in the 0 - 255 range.

Within the existing wscons code, these pairs of values are usually stored in a struct wsdisplay_charcell.

To begin with, we can simply ignore the attribute value and copy the raw character values out.

First of all, we need to add a new structure to wsconsio.h:

The rows and cols values will be filled in by our new piece of kernel code, and returned to userland so that we know how many characters make up the entire screendump as well as where the line breaks should come. The pointers will be malloc'ed in userland before calling the kernel code.

We also need to add a define for our new ioctl to wsconsio.h:

The parameters we are supplying are:

The range of ioctl numbers 160-255 is marked as reserved for future use. Since our new ioctl operates on the display, it would have made more sense to use the 64-95 range, but this is already full.

The _IOWR macro is defined in sys/sys/ioccom.h, along with other ioctl-related macros. The choice of _IOWR, _IOR, or _IOW, determines whether the values that are defined in our struct wsdisplay_screendump_text are copied from userland to the kernel, from the kernel back to userland, or both.

Since in this case we need to pass pointers from userland to the kernel and receive the values for rows and cols back, we need data to move in both directions, so we use _IOWR.

Note that the actual content of textdata and attrdata will be copied from kernel memory space to our userland memory allocation by our own code, (specifically a call to the copyout kernel function), and not by this _IOWR mechanism, which is only responsible for passing the values of the pointers.

Now that we have a mechanism in place to call our new ioctl, we can add the code to implement it to wsdisplay.c. The function wsdisplay_internal_ioctl mostly consists of a large switch statement, and it is here that we can add our new routine:

Since we have changed a kernel header file which is also used by userland programs, we need to perform an additional step along with the normal kernel compile and installation.

The file /usr/src/sys/dev/wscons/wsconsio.h needs to be copied to /usr/include/dev/wscons/wsconsio.h:

Here we are using the struct wsdisplay_screendump_text that we added to wsconsio.h, and creating a variable 'screendump' of that type.

The two pointers to memory that will be used to hold the userland copy of the screendump characters and attributes need to have memory allocated. If we wanted to allocate exactly the right amount of memory then we could make a separate call to find out the actual screen dimensions, however since the memory required is small in this instance, we just allocate 64K which should be enough to cover any reasonably-sized text console.

Note that since we are not using the attribute data, we could also just set the attrdata pointer to NULL:

This would cause the corresponding call to copyout to fail and return EFAULT, which is fine because our kernel code doesn't care and will just continue regardless.

Compiling and running the above code will result in the creation of a text file containing each of the characters from the display and nothing else. So in the case of a 160 x 49 display, we would get a file of exactly 7840 bytes.

That's not particularly useful, because it doesn't even contain newline characters at the end of each line. In other words, all of the content is on one long line of 7840 characters. As a result, if we viewed it on a display of a different size then the lines would appear to wrap at the wrong points.

We can easily modify our program above to add newlines at the right places, based on the value of screendump.cols:

With this new version of the code we get a text file that has the correct number of rows and columns to match the original display.

Of course, each line of the output is still padded with spaces to the full length of the line, but this can also easily be fixed with a slight change to the main routine:

The above works quite well for capturing text data that happens to be displayed on the console. But we're still missing the attributes, so we can't see text in different colors, and details such as bold and underlining are lost.

One solution is to parse the attribute data, and convert it into CSS that we can use together with an HTML encoded version of the text. This allows us to represent the whole display in a form that preserves virtually everything except the actual font.

Unfortunately, this process is complicated somewhat by the fact that the raw attribute data is device specific. The correct way to convert it back to device-inspecific values is to use the 'unpack attribute' functions, but doing so adds somewhat to the complexity of the kernel code. For this proof of concept we'll stick to assuming that the attributes are in the format used by the rasops code, which should cover the vast majority of users on the amd64 platform.

The following program produces a 'screendump.html' file in the current directory when run, which contains a fairly accurate rendering of the text currently on the console. It even includes support for 256 colors as implemented by some of the console enhancement patches I recently created.

Whilst text-based screenshots are very useful, to capture the exact rendering of the screen we obviously need to produce a graphics file from a pixel-by-pixel readout of the framebuffer.

In principle, this isn't too much different from what we've already done above, except that we'll be reading RGB pixel data instead of ASCII character values and attribute bytes. However, we can't really do this directly from the wscons code because we need to access all sorts of data structures that are specific to the graphics hardware in use - there is no convenient equivalent to the GETCHAR macro to read individual pixel values.

In practice, for graphics hardware that is common on the amd64 platform this is all handled through yet another abstraction layer which is known as rasops, (raster operations). This effectively sits between the higher-level wscons code and the various low-level graphics drivers, and provides us with a unified way to access the framebuffer regardless of the actual hardware in use. The rasops code also implements a few other details such as the virtual terminals functionality, (in other words, if we're looking at virtual terminal 1 and a program outputs to virtual terminal 2, that output doesn't actually get painted to the screen), and display rotation, (which is very limited in scope and virtually unused on OpenBSD systems today).

So even though we only want access some parameters to determine the display size and the address of the framebuffer, then copy the pixel data out, we need to write a new rasops function.

Just like with the first new ioctl that performs text-based screenshots, we need to add some code to wsconsio.h:

This is all directly equivalent to the code we added before.

Instead of rows and columns, we have width and height in pixels, along with 'stride', which will be explained shortly but is basically the width in bytes rather than pixels, taking into account any padding and alignment. We also include the display bit depth so that we can eventually apply the correct post-processing to the pixel data to make it usable.

Before we write our own new rasops function, let's look at how to call an existing one.

To actually call the rasops routines from the wscons code, we use the WSEMULOP macro. This is defined in wsemulvar.h, and accepts the following arguments:

None of this is really documented, except for the source code itself, so expect to do a lot of reading if you want to do anything new with the rasops code.

A simple but practical example might make things clearer:

All this does is to call the existing rasops putchar routine with some hard-coded arguments. Specifically, row 10, column 10, character '!', and an attribute byte that specifies red text on a green background.

We can invoke this ioctl with a very simple userland program:

The main thing that we want to know is the kernel virtual memory address corresponding to the start of the framebuffer. This, along with other useful information such as the height and width of the display, is stored in a struct rasops_info, as defined in rasops.h. Here in this definition we can see the pointer ri_bits, along with ri_width, and ri_height.

What is not necessarily so obvious is how we actually get to the relevant rasops_info from what we are supplied in the wsdisplay_internal_ioctl function where our ioctl kernel code will be inserted.

We're supplied with a pointer to a struct wsscreen, scr. This contains an element scr_dconf, which is a struct wsscreen_internal. This struct wsscreen_internal has an element emulcookie, which is a void pointer but which will point to a struct rasops_screen. Finally, this struct rasops_screen has a pointer to a rasops_info structure.

So the whole chain looks something like this:

We'll call our new rasops function 'screendump'. The code to call it from the ioctl handler in wsdisplay.c is very simple and almost the same as what we have in the example above:

Next, we need to add a function pointer for our new function to struct wsdisplay_emulops, defined in wsdisplayvar.h:

Note: Although we could add this extra function pointer anywhere within the definition of struct wsdisplay_emulops, some of the device drivers, (such as the vga driver), have their wsdisplay_emulops structure hard-coded as a constant. As a result, any re-ordering of the existing entries would break those drivers. To avoid this, add the new entry to the end of the current list, after unpack_attr.

At this point we can finally move to the rasops code itself.

The generic rasops functions, in other words those which are not specific to a particular bit-depth, are in rasops.c. This is where we will put our screendump function, as although the format of the data will obviously be different depending on the bit-depth, actually reading out the entire content of the framebuffer will can be done in exactly the same way regardless.

If we were going to do any post-processing of the pixel data within the new rasops screendump function itself, we might want to write separate functions for each bit-depth. However, this functionality is much better done in userspace - we want to do as little as possible within the kernel.

The following code is what we are going to add to rasops.c:

Obviously we should add a function prototype near the top of the file along with the existing ones, underneath the 'generic functions' comment:

The new function should be fairly self-explanatory. We cast the supplied cookie to a struct rasops_info, from which we can obtain the width, height, stride, and depth of the display. These values are assigned to the corresponding members of the struct wsdisplay_screendump_pixels that will soon be passed back to the calling program.

Now that we have our new function in place, we're almost ready to go.

The initial assignment of the function pointers is performed in rasops_reconfig, which is called from rasops_init.

It might seem that we just need to set the new function pointer to point to rasops_screendump, by placing this assignment underneath the 'Fill in defaults' comment:

But this is not enough. Now we have to deal with a strange complexity of the rasops code, which can be seen if we continue reading the source for rasops_init past it's call to rasops_reconfig.

The pointers in ri->ri_ops are copied elsewhere, and then if the RI_VCONS flag is set then the original values are replaced with calls to similarly named functions, which differ by having 'vcons' in their names. So rasops_copycols becomes rasops_vcons_copycols, and so on. There is also a further check for the RI_WRONLY flag, so that further replacement routines can be substituted that avoid writing to the framebuffer.

Our screendump routine doesn't really need any additional code to be vcons-aware, and it obviously wouldn't make much sense to try to create a version that doesn't read from the framebuffer, so we don't need any of this added complexity for our function to work. However the easiest way to ensure that our new code works as expected is to provide a rasops_vcons_screendump wrapper function that just calls rasops_screendump, and fill in the extra function pointers as required.

The rasops_vcons_screendump function does nothing other than to call rasops_screendump via a new rs_ri->ri_screendump function pointer:

Of course, we should add the function prototype as well, along with the existing ones for the other vcons functions:

We also need to add that new function pointer to the definition of struct rasops_info in rasops.h:

Next we modify rasops_init to copy the original pointer:

Finally, we also modify rasops_init to re-assign ri->ri_ops.screendump to the vcons version:

Here is a sample program that calls WSDISPLAY_SCREENDUMP_PIXELS, and converts the data it receives from the common 32bpp BGR0 format to a 24-bit RGB ppm file:

All we do here is to cycle over the raw framebuffer data one pixel at a time, and re-arrange each set of four bytes into a three byte RGB value.

For each line, once we reach the width as specified in screendump.width, further data is ignored until the end of the line as defined by the value of screendump.stride.

The resulting ppm file is written to rgb_screendump.ppm in the current directory, and can be viewed with any standard image viewer that supports the ppm format.

The new ioctl that we've added to wsdisplay.c can potentially be called even when we are not using graphics hardware that uses the rasops routines. A few different graphics drivers exist where this is the case, most of them for uncommon display devices, but one exception that we can easily use for testing purposes is the plain vga text mode driver.

With our code in it's current form, if we try to access the WSDISPLAYIO_SCREENDUMP_PIXELS ioctl whilst running with the vga driver, we'll cause a kernel panic:

This shows that we've tried to execute code at address 0x0. This shouldn't come as much of a surprise, since we added a new function pointer to struct wsdisplay_emulops and this hasn't been initialized by the code in vga.c, (which initializes vga_emulops as a constant with the function pointers hard-coded).

Since the vga driver declares this struct wsdisplay_emulops in global scope, (in other words, outside of any function), the C standard guarantees that it's elements will be initialized to NULL.

However other device drivers don't necessarily do this, and instead declare their struct wsdisplay_emulops in a similar way to the code in rasops.c.

The upshot of this is that we can't simply change our ioctl handling code to check for a NULL function pointer:

This would certainly work to catch the case of accessing the function whilst using the vga driver, but it's not a general solution.

The definitive and most compatible way to fix this, of course, is to add a screendump function of some sort to each of the display drivers, even if it just returns EINVAL without providing any framebuffer data.

We can easily do this for the vga driver:

Adding this function, along with it's function prototype and an entry for it in the declaration for vga_emulops will cause our call to WSEMULOP in the ioctl handler to return EINVAL in the result variable.

Now we just need to change our code to return this value instead of always returning zero:

Of course, since our userland screen dumping program always checks for a successful call to WSDISPLAYIO_GINFO before calling WSDISPLAYIO_SCREENDUMP_PIXELS, running it unmodified even with the vga driver in use will not trigger a kernel panic anyway.

A tar archive containing the kernel patches and userland utilities can be downloaded here.

All of the files within the tar archives are signed using our signify key.

At this point you can re-compile and re-install the kernel in the normal way.

You should also copy the modified wsconsio.h header file to the correct place in the /usr/include/ hierarchy:

The userland utilities can be compiled with no special options, after verifying their checksums: