The Terminal Driver Writers Guide

by Steffen Seeger
last updated $Date: 1997/12/14 21:55:31 $


This document should give an overview of the console code, explain the scroller programming interface and give a hint what needs to be rewritten when implementing a new terminal parser.

The Console Code

The console code, which is implemented in file:linux/drivers/char/console.c implements the neccessary functions needed to handle a text display and scrolling on it. It does so by extending the struct kgi_device by the neccessary fields to keep the console state in a struct kgi_console. This is done in file:ggi/include/console.h and header files included from there. With the current implementation, there is a drawback in terms of binary compatibilty with the terminal drivers which is one reason why they aren't loadable yet. Currently the kernel needs to know about all terminal drivers that are possible at compile time. So, adding a new terminal emulation driver needs currently a kernel recompile. This will probably change in the future, but the basic interface will remain as it is now, as long as we don't face major problems.

The console code handles all the neccessary interfacing to the TTY layer and the display hardware and is optimized for several levels of hardware access which are currently

This implementation has been written from scratch and performs - at least for the most common case of normal text output better than the old Linux-2.0 code - from 30% to 50% better in comparable hardware configurations. We expect a significant speed up when the code interfacing to the TTY layer can be tuned to allow 'burst' writes to the parsers, which are prepared for this. If you know a solution here, your expertise is welcome.

The Scroller Programming Interface

The scroller is a simple abstraction from terminals that provides the basic functions to build terminal parsers easily. A terminal parser should use these functions to do it's output and not touch the framebuffers directly. This is because the scroller is highly optimized to produce fast output and transparent backing store even on slow and limited hardware. It provides the following features for terminal drivers:

All scroller function names have the prefix "scroll_" and are implemented in file:linux/drivers/char/console.c. Some of them interface to other parts of KGI and for terminal drivers you will never have to worry about them. Those that might be of interest for you are describied below in more detail. If a function refers to pixels, the number of the pixel is used, not the coordinates. The pixel number of a pixel at (x,y) is y*FB_SIZE + x where FB_SIZEX is the stride of the frame buffer.

void scroll_modified(struct kgi_console *cons,ggi_uint from,ggi_uint to);

void scroll_update_attr(struct kgi_console *cons);

void scroll_update_gadgets(struct kgi_console *cons);

void scroll_sync(struct kgi_console *cons);

void scroll_write(struct kgi_console *cons, unicode c);

void scroll_lf(struct kgi_console *cons);

void scroll_reverse_lf(struct kgi_console *cons);

void scroll_gotoxy(struct kgi_console *cons, int new_x, int new_y);

void scroll_cr(struct kgi_console *cons);

void scroll_bs(struct kgi_console *cons);

void scroll_need_sync(struct kgi_console *cons);

void scroll_mksound(struct kgi_console *cons, int pitch, int duration);

void scroll_up(struct kgi_console *cons, ggi_uint t, ggi_uint b, ggi_uint n);

void scroll_down(struct kgi_console *cons, ggi_uint t, ggi_uint b, ggi_uint n);

void scroll_erase_display(struct kgi_console *cons, int arg);

void scroll_erase_line(struct kgi_console *cons, int arg);

void scroll_insert_chars(struct kgi_console *cons, ggi_uint n);

void scroll_delete_chars(struct kgi_console *cons, ggi_uint n);

void scroll_erase_chars(struct kgi_console *cons, ggi_uint n);

void scroll_backward(struct kgi_console *cons, int lines);

void scroll_forward(struct kgi_console *cons, int lines);

However, there are some pitfalls you may step into when starting a new terminal driver:

What needs to be rewritten...

All needed to extend GGI by another terminal parser is basically the implementation of the following routines (Note that we reserve to implement parser specific ioctl()-calls for later versions):

The purpose of each of the routines is explained in more detail below, it is suggested you have the neccessary include files at hand to look up the data structures. A more complicated implementation can be found in file:linux/drivers/char/terminals/xterm.c

void handle_event(struct kgi_device *, ggi_event *);

This function is called from an interrupt routine and should run as short as possible. It might be called from an IRQ bottom half handler in future releases, but you should the neccessary things as fast as possible here. Let' s have a look at the version for the dumb parser implemented in file:linux/drivers/char/console.c:

static void dumb_handle_event(struct kgi_device *dev, ggi_event *ev)
{

}

As you can see, this basically puts the characters to report to the application(s) into the TTYs flip-buffer and marks it for rescheduling. Which events are reported to handle_event() is determined by dev->event_mask which can be set as the device wants it. So it is possible to recieve keypress events, pointer moves and button presses etc. or even scancodes or keycodes. Thus one could write an emulation of the Linux-2.0 terminal code very simple. (It should be noted here that in order to emulate the behavior of the Linux-2.0 code in terms of console switches, the scroll_save() and scroll_restore() functions will need some adjustment. Currently there are higher priorites for us, which is why this isn't done yet.)

void do_reset(struct kgi_console *, ggi_uint do_reset);

This function should reset the parser specific state in the struct kgi_console argument passed by reference. The calling interface to this function might change slightly in the future, but the purpose will remain. To give you a clue about the basic tasks this has too perform, again the implementation for the dumb console parser taken from file:linux/drivers/char/console.c:

static void dumb_do_reset(struct kgi_console *cons, ggi_uint do_reset)
{

}

The do_reset() function is called from the console code after allocation and basic initialisation of the struct kgi_console associated with a TTY special file when one of these (/dev/tty??) is opened. [NOTE: This documentation is under construction, expect an update here!]


Copyright (c) 1997 Steffen Seeger - All rights of this work, especially publishing, translation and all kinds of reproduction are reserved by the author. You may, however, print a copy for personal use provided that the name(s) of the authors are included with the copy.