XARM(1)

NAME
Xarm - Arm server for X Version 11

SYNOPSIS
Xarm [display] [ -serialNo string ] [ +flog | -flog ] [ -sched # ] [ -kbd keyboard ] [ -kfile file ] [ -ri time ] [ -rd time ] [ -sound device ] [ -soundoff | -soundbell | -soundon ] [ -dev framebuffer ] [ -width size ] [ -height size ] [ -monochrome | -colour ] [ -scr ] [ -bw1 | -bw4 | -c1 | -c4 | -c8 ] [ -dynamic | -static ] [ -lowres | -mediumres | -highres | -svga | -py # ] [ -px # ] [ -bp colour ] [ -wp colour ] [ -frame colour ] [ -hard | -soft ] [ standard X server options ]

DESCRIPTION
Xarm is the server for Version 11 of the X window system on Acorn ARM hardware. It is started by typing x to a login prompt (which will start Xarm under the control of xdm(1)) or by using the startx command which itself uses xinit(1). The system configuration can be changed to alter how these commands behave - see the RISC i X X Window System Administrator's Guide for detailed information or consult the man page for Xstart(1) for details of the /etc/xdm/Xconfig file which controls the arguments to the server started as a result of an x login.

CONFIGURATIONS

Xarm operates under all ARM RISC i X versions from, and including, the RISC i X 1.2 release. It auto-configures to use a 1 bit per pixel black and white display, finding the display from the device /dev/fb (see fb(4)) and the monitor type from the current CMOS ram settings. It uses the standard keyboard and mouse - see kbd(4) interpreting the keys according to the information from the files in /usr/lib/X11/XKeyboard; see xarmkeymap(1) for more information.

The default behaviour of the Xarm server is normally overridden by command line arguments from the /etc/xdm/Xconfig file - see Xstart(1). This manual page describes the raw Xarm defaults and the various command line options.

The monitor type used by the X server, determined by the setting of the CMOS ram, will normally cause the X server to start up with the correct display mode. The monitor type must be set before booting RISC i X. By default Xarm chooses the 1 bit-per-pixel mode with the largest number of pixels from the range of modes which the operating system supports for the monitor type. The following modes are available with the five different monitor types:-

0 - low resolution
    Low resolution monitors use a 640x240x1 screen mode. Because this mode gives rectangular pixels it is normally unsuitable for graphics applications which will display distorted images. It is suitable for text based applications so long as the restricted number of lines available on the screen is acceptable. Suitable monitors are the standard Archimedes low resolution monochrome and colour monitors and multi-sync monitors.

    The -c4 option may be used to give a colour mode (640x240x4) - the colour map is a normal X static colour map with 16 predefined colours, an additional visual gives a 16 entry pseudo colour display on which the colours may be altered.

    The -c8 option supports an 8 bit per pixel colour mode (640x240x8) with a static colour map.

1 - medium resolution, multi-sync
    Various medium resolution modes may be used with a multi-sync monitor. The default mode is 768x600x1 - this is a Super VGA mode, and thus may not be supported by the monitor which you use. If this is the case start the X server with the -mediumres argument to force the mode to be 640x480 pixels in size. The -c4 option may be used to give an 800x600x4 mode with static and dynamic colour maps (two visuals) (or a 640x480x4 mode if -mediumres is specified). The -c8 option gives a 640x480x8 mode with (two) static colour visuals. All three modes have square pixels. Low resolution modes may also be selected with monitor type 1. R140 systems do not have adequate memory bandwidth to support the 640x480x8 mode, so this should not be used.

2 - high resolution
    The only high resolution mode is 1152x900x1 - requests for the multiple bit per pixel modes will be ignored. The mode requires a particular model of high resolution monitor; consult your dealer for more information.

3 - medium resolution, VGA
    Only 640x480 modes work with `VGA' type monitors. The 640x480x1, 640x480x4 and 640x480x8 modes may be selected - the monitors will not work with the low resolution modes.

4 - medium resolution, Super VGA
    800x600 and 640x480 modes may be used with monitor type 4. The 768x600x1 mode is the default, -c4 will select the 800x600x4 mode. Both these modes have square pixels, both are only supported on particular ARM systems which allow the video and memory clock speeds to be controlled separately - see the User or Welcome Guide for your system. The other modes may be selected using -mediumres (forcing the 480 line modes to be used). The command line options allow a particular mode to be specified. Since the required mode may require a particular monitor type it may be necessary to change the CMOS ram settings - this can be done from the RISC i XFS boot environment under RISC OS. The server will not attempt to change the monitor type itself - this is almost invariably the wrong thing to do.

EXAMPLES

Normally the server will automatically select the correct options from the information supplied by the frame buffer device however in many cases it is desirable to supplement this information with extra arguments to Xarm.

It is necessary to request a mode with more than one bit per pixel explicitly using either the -bw4 option for a monochrome mode or the -c4 or -c8 options for a colour mode. These default the other options to sensible values, in particular the monitor is assumed to be monochrome or colour as appropriate. If necessary up to eight screen modes can be used simultaneously using the -scr option to separate the arguments for each one, for example;

    Xarm -colour -bw1 -scr -c4

These options cause the server to offer two screens, :0.0 (the monochrome 1 bit per pixel screen) and :0.1 (the colour four bits per pixel screen). The server is configured to support a maximum of eight screens. Swapping between screens is done using a suitable X application such as xswitcher(1) or the f.warptoscreen function of the twm(1) window manager.

Low and medium resolution modes (using a multisync monitor) may be mixed in a similar way. Doing this is relatively expensive in terms of memory - it is far more efficient to use a single screen mode.

Other options which will commonly be used are those which inform the server of the characteristics of the monitor in use. The basic type of the monitor is determined from the vdu information in the CMOS RAM, however this does not reveal whether the monitor is colour or monochrome and what the physical dimensions of the screen are. If you specify any colour (-cn) modes the monitor is assumed to be capable of displaying colour, else a monochrome monitor is assumed.

The other two options which specify the characteristics of the monitor are -height and -width. Both of these arguments are followed by the size in millimetres of the relevant dimension of the monitor. The values default to:-

monitor | height | width
low resolution | 160 | 255
medium resolution | 190 | 255
high resolution | 265 | 340

These are approximately correct for a 19 inch high resolution monochrome monitor, a 14 inch medium resolution monitor and a 12 inch low resolution one.

OPTIONS

From RISC i X 1.1 the options supplied to Xarm must appear in the correct order. Only the ARM specific options are described in detail here. For descriptions of the other options see the Xserver(1) man page. Normally if repeated or conflicting options are given only the last is used, the exceptions are the monitor type options - -lowres, -mediumres and -highres - which cause the number of lines and the screen dimensions to be defaulted correctly. These options only alter values which have not yet been set, thus only the first such option is used. To avoid confusion you should avoid conflicting requests. The options are parsed in the order in which they are given. Xarm supports five classes of options;

Server
    Options which control the operation of the server. These may appear anywhere on the command line. Most of these options are as described in Xserver(1).

Keyboard
    Options which apply to the specified keyboard device. Because only one keyboard is supported these may appear anywhere on the command line.

Sound
    Options which change how bell sounds are produced and how the Acorn-Noise extension is supported. These may appear anywhere on the command line.

Monitor
    Options which control the treatment of the monitor attached to the server. The options must appear after the -dev option which defines the device.

Screen
    Options which apply to the particular screen used. These must appear after the monitor options describing the underlying device. If more than one screen is used on the same monitor subsequent definitions are introduced by the -scr option.

SERVER OPTIONS

The options which fall into the ``server'' class and may be given anywhere on the command line. This manual page only describes differences from the option descriptions in Xserver(1). Some additional options are provided for use when debugging the server. The +flog option can be used to find out about font utilisation during normal server execution.

-class display-class
    This specifies the display class of the server as described in Xserver(1). In the Xarm server the specified class is used to generate the display id of the server if the -serialNo option is also given. The default display class is Acorn-RISC_iX.

-serialNo string
    This option specifies the serial number of the machine. When using XDMCP this will be used to generate the manufacturer display id of the server. The display id will be display-class-serial-number. If the default display class is used (as described above) this will be Acorn-RISC_iX-serial-number. It is recommended that the serial number used have the form: model:number where model is the model of the machine running RISC i X (such as R140 or R260) and number is the actual serial number of the machine. This will generate a unique display id.

-displayID display-id
    This option specifies the complete display id of the server and overrides the default and anything derived from a -serialNo argument. The argument to -class is still used as the display class in XDMCP.

Other XDMCP options are as described in Xserver(1). Notice that the -once option now only works when -query is also specified (to cause XDMCP to be used). The effect is also the reverse of the behaviour in RISC i X 1.1 - the option causes the server to execute for only one session (previously the default) and the +once option is no longer supported.

+flog
    Turn on font logging. Each time a font is read from the disc a message is written to the server log file.

-flog
    Turn off font logging (the default.)

-sched #
    This option allows the round robin scheduler timeout to be set. The timeout governs the number of requests from a single client which are executed before input is read from another client. Normally this should not be specified. There is no guarantee that it will have any particular effect. However it can be useful to set the number to `1' when using applications which submit expensive graphics requests without waiting for input from the server.

-messages
    Informational messages are output. These may be helpful if the server is having problems opening the screen or keyboard devices, or if confirmation is required of the display id which the server is using.

+messages
    Do not output informational messages (the default).

 Other options described in Xserver(1) which behave differently when used with Xarm are as follows;

-logo
    This option has no effect - the logo screen saver is not supported.

-p time
    The screen saver always works by blanking the display (see the description of the -v option below). Thus the -p option has no effect.

-v  According to the X protocol this option causes the screen to be changed in a server-dependent fashion to avoid phosphor burn. The method adopted in Xarm is to display a picture of a black cat in a coal mine. This is effectively indistinguishable from screen blanking.

When running the server with RISC i X 1.1 clients or clients on other machines developed with older releases of X11 it may be necessary to run the server with the bc option (or to turn this option on using xset(1)). This is because the server previously failed to detect certain protocol errors which were generated by some clients. Since the server now detects these errors the clients will fail to run correctly.

Use of the -bs option is recommended on machines with less than 8Mbytes of memory as backing store support can result in significant increase in server memory utilisation with some applications.

The -x keyword to load extensions at run time is not supported.

KEYBOARD OPTIONS

Keyboard options are;

-kbd device
    Overrides the default keyboard/mouse device /dev/kbd.

-kfile file
    Overrides the default keyboard description file name /usr/lib/X11/XKeyboard/KB%d. Notice that the name may contain a (single) %d escape which will be replaced by the keyboard type number. Because the string is processed using sprintf(3) any other % character must be duplicated to prevent erroneous processing. Other numeric escapes may also be used - see the man page for sprintf. The keyboard type is passed as a single C (int) argument. Using escapes which expect a pointer (for example) will almost certainly cause the X server to crash.

-ri milliseconds
    This sets the delay in milliseconds before keyboard autorepeat starts - the key must be held down for the given time before the first repeat depression is delivered. All keys are capable of auto-repeating except those which are shift keys in the keyboard electronics; all the shift keys, all the keys with LEDs and the Home key. A value of 0 will restore the default (300 milliseconds.)

-rd milliseconds
    This sets the delay in milliseconds between the delivery of successive autorepeat depressions. A value of zero restores the default (50 milliseconds.)

The options -a, -c, c, -t, -f, -r and r are as described in Xserver(1).

SOUND OPTIONS

The sound options control how the server produces sounds. The options allow the server to be configured to produce no sound, to produce bell noises without using the RISC i X sound device, or to produce more complex sounds using the sound device.

-sound device
    This overrides the default sound device /dev/sound.

-soundoff
    This option causes the server not to produce any sounds and not to open the sound device. The option may be changed while the server is running by using the Acorn-Noise extension.

-soundbell
    The server uses the bell interface to produce sounds. This restricts sound output to a single pitch and five volume levels (including off), however it means that the server does not open the sound device. This option may be changed using the Acorn-Noise extension while the server is running.

-soundon
    This is the default. The server opens the sound device and uses this for all sound output (both that produced as a result of using the Acorn-Noise extension and that produced as a result of normal X11 Bell protocol requests). Because the sound device can only be opened by one process at once this prevents other programs which might use the sound device from running.

MONITOR OPTIONS

The monitor options are;

-dev device
    Overrides the default frame buffer device /dev/fb. Multiple -dev options may occur on the command line. Each option introduces a sequence of screen specifications using the specified device. Specifying -dev implicitly starts a new screen definition (as though -scr had been specified).

-monochrome
    Informs the server that the attached monitor is monochrome - all colours will be resolved to suitable shades of gray. Notice that the hardware incorrectly combines the three colour signals when producing output for a monochrome monitor to produce a gray shade which is preceived as incorrect by most humans. Specifying -monochrome ensures that this problem is avoided by only setting gray shades in the palette.

-colour
    Informs the server that the attached monitor is capable of colour output.

The width and height of the screen in millimetres are defaulted to suitable values according to the CMOS ram monitor type setting or -lowres, -mediumres or -highres if given. The defaults are intended to match commonly used monitors. They can be overridden using the following options:-

-width size
    Specifies the width of the displayed image on the screen, excluding borders.

-height size
    Specifies the height of the displayed image on the screen, excluding borders.

SCREEN OPTIONS

The following options allow control of the screen mode. Normally only the -c4 and -c8 options will be used (to force a colour display on a low resolution or multi-sync monitor.) The -lowres option can be useful with multi-sync monitors (monitor type 1) as these will also support low resolution video modes. The other options are provided for completeness.

-scr
    Introduces options for a new screen. This option is required if the server must support more than one screen, it separates the options for the previous screen from those for the next.

-c1 Provides a colour 1 bit per pixel static display. This is not normally very useful, however it allows the foreground pixel and background pixel colours to be set, using -fp and -bp, to colours (as opposed to gray values).

-c4 Forces the server to use colour 4 bit per pixel mode - this is only supported on medium and low resolution monitors (including Super VGA monitors).

-c8 Forces the server to use a colour 8 bit per pixel mode - this is only supported on VGA and lower resolution modes (not on Super VGA displays). Use of this option with R140 systems is not recommended as there is insufficient memory bandwidth available. If necessary the mode can be used on a second screen (using -scr -c8) and this screen can be selected after the display has been drawn - for example an image processing application could be used to drawn an image into a window on the 8 bit per pixel display then, when the image is complete, it can be displayed by warping the cursor into the window using xswitcher(1)).

-bw1
    Forces the server to use a 1 bit per pixel monochrome mode - this is the default mode on all displayes.

-bw4
    Causes the server to select a 4 bit per pixel mode for a monochrome monitor - colours are resolved to shades of gray and the underlying monitor type is defaulted to -monochrome.

-dynamic
    Causes the screen to support dynamic colour maps if possible. The effect of this option depends on the base mode selected. A dynamic colour map is not supported with -bw1 so the option is ignored. In 4 bit per pixel modes dynamic and static visuals (PseudoColor/GrayScale and StaticColor/StaticGray) are always created, -dynamic causes the dynamic visual to be the default for the screen rather than the static one. In the -c8 mode -dynamic causes the server to create a very unusual dynamic colour visual which represents the facilities offered by the hardware. This is described in more detail below. It should not be necessary to use this option, however some applications which need a dynamic colour map fail unless the default colour map is dynamic.

-static
    This option updoes the effects of -dynamic on the current screen.

-lowres
    Forces the server to switch to a low resolution display mode. This is normally only useful with a multi-sync monitor, where it is possible to use either a low resolution or medium resolution mode. Equivalent to 240 lines on the display. This mode is the default with monitor type 0.

-mediumres
    Forces the server to switch to a medium resolution display mode. This is the default for monitor type 3. Equivalent to 480 lines on the display.

-highres
    Forces the server to switch to select a high resolution mode - this is only possible with monitor type 2, and is the default. Equivalent to 900 lines on the display.

-svga
    Forces the server to switch to a Super VGA mode - equivalent to 600 lines on the display. This is the default for monitor type 4.

-py #
    Specifies the number of lines on the display. The server treats the value as a hint, it will select the mode with the nearest greater number of lines.

-px #
    Specifies the width of the display in pixels - again this is only a hint.

The following options allow control over the colours used in the selected video mode. The display border colour can be selected in any mode. In all cases the colour can be specified in one of three ways:-

0/1 If `0' is given it is interpreted as `black', `1' is interpreted as `white'.

rgb Three or six hexadecimal digits of red, green and blue values making a particular colour.

colour-name
    The name of a colour from the rgb colour data base.

The options are:-

-bp colour
    Specifies the colour of the black pixel.

-wp colour
    Specifies the colour of the white pixel. In both these cases the colours may be other than black or white. This allows (for example) a colour monitor to be used to produce a green `monochrome' display as well as allowing simple reversal of black and white on the display. In high resolution display modes the video output is strictly monochrome - if a colour is specified for either the black or the white pixel the device driver will choose black or white according to the intensity of the colour. If the -monochrome option is given or defaulted, colours which are not gray (equal in red, green and blue) will be converted to gray colours using an algorithm which approximates to the typical human sensitivity to red, green and blue light.

-frame colour
    This specifies the colour of the border round the display. Again, colour borders may be used on 1bpp displays (and the colour need not be the same as the black or white pixel colour.) On high resolution displays the effect of changing the border colour is to produce black and white bands round the display. This can be used to produce a grey border (try `555') but that is about all.

It is possible to control whether the server uses a software or hardware cursor. A software cursor may only be used in a 1 bit per pixel monochrome mode (-bw1). Both the software and hardware cursors are restricted to a size of 32x32 pixels. Cursor colour is independant of the colours in the current colour map, although it is resolved to a gray shade on a monochrome monitor.

-hard
    Use the hardware cursor. The cursor is automatically used in low and medium resolution modes, and a software cursor used in high resolution mode. Using the hardware cursor in high resolution mode may increase performance slightly, but the cursor looks awful.

-soft
    Use the software cursor.

VISUALS

Different sets of visuals are supported in different screen modes. In some modes non-standard or unusual visuals may be enabled by specifying particular flags. The default visuals are always static (the corresponding colour maps cannot be altered) unless the -dynamic flag is given for the screen.

Multiple visuals are used where there are multiple ways of treating the particular hardware display mode under the X protocol. Separate screens (introduced by -scr) are used for each hardware display mode because different modes require different amounts and formats of the same display memory - hence two hardware modes cannot be displayed simultaneously. The screen which is displayed is the one which contains the cursor, therefore to swap between screens an application need only use XWarpPointer(3X11) to warp the pointer into a window on the desired screen. The supplied xswitcher(1) application does this under user control, displaying a window on each screen. Internally the server holds the images of undisplayed screens in its own virtual memory space and copies these into the screen memory when required.

The screen modes supported are determined by the monitor type specified in the CMOS RAM, as follows:-

Monitor Type | 640x240 | 640x480 | 800x600 | 1152x900
0 | •
1 | • | • | •
2 |  |  |  | •
3 |  | •
4 |  | • | •

When -bw1 is used in Super VGA mode the actual screen size is 768x600 (not 800x600 pixels).

The visuals offered by each screen mode depend on the facilities of the hardware and the flags given on the command line. Each screen mode is controlled separately. The ARM hardware has a 20 entry palette up to 16 of which control the colours on the screen. The remaining 4 entries control the frame of the display (one entry) and the colour of the hardware cursor (3 entries). Only two of the cursor colours may be controlled via the X protocol - these entries correspond to areas of the cursor image within the cursor mask and areas outside the cursor image but within the mask. (The third entry controls areas outside the mask but within the image - the X protocol requires this area to be empty).

Each palette entry consists of a 13 bit value which can be broken down into three 4 bit values control the intensity of the red, green and blue guns on the display plus a supremacy bit which indicates whether the display image or a video image pixel is to be displayed for a pixel with a value which selects the corresponding palette entry. Currently the supremacy bit cannot be controlled over the X protocol.

In high resolution modes the palette must be set up with a fixed set of entries which can map set and unset pixels into black or white - thus the visual is technically still dynamic, however the number of bits per RGB value is only 1. In fact this mapping is done within the operating system and the server specifies the pixel colours as full 13 bit values, thus the bitsPerRGB field of the visual is still reported as 4.

In 1 and 4 bit per pixel modes the bitsPerRGB field is always 4. In 8 bit per pixel modes one visual has a bitsPerRGB value of 3 - this is a static colour visual with the colour map set up to give the colours of a 332 (bits of R, G, B) ``TrueColor'' visual. This is discussed in more detail below. Both 1 bit per pixel modes, -bw1 and -c1, have a single ``StaticGray'' or ``StaticColor'' visual, with the two colour map entries either black and white or as determined by the -bp and -wp command line arguments. No dynamic visual is provided (many applications seem incapable of dealing with such a visual, and it is not very useful).

In 4 bit per pixel modes static and dynamic visuals are always provided, with 16 entry colour maps. The default visual is the static one unless the -dynamic command line flag is given, in which case the dynamic (PseudoColor) visual is the default. Correctly written applications which need an alterable colour map will use XMatchVisualInfo (see XGetVisualInfo(3X)) to obtain the desired visual. On monochrome displays the static colour map holds a linear gray scale ramp going from pixel value 0 (dark) to pixel value 15 (light). The ends of the ramp are taken from the -bp and -wp pixel values, so the ramp may be inverted, however if colours are given they will be converted to gray scales first. On colour displays the static colour map holds the following set of colours:-

Colour | Red | Green | Blue | Luminance
Black | 0 | 0 | 0 | 0
Blue | 0 | 0 | 15 | 0.114
Grey25 | 4 | 4 | 4 | 0.267
SlateBlue4 | 4 | 4 | 11 | 0.32
Red | 15 | 0 | 0 | 0.301
Magenta | 15 | 0 | 15 | 0.415
Sienna | 11 | 4 | 4 | 0.407
MediumOrchid3 | 11 | 4 | 11 | 0.46
LimeGreen | 4 | 11 | 4 | 0.54
LightSeaGreen | 4 | 11 | 11 | 0.593
Green | 0 | 15 | 0 | 0.585
Cyan | 0 | 15 | 15 | 0.699
YellowGreen | 11 | 11 | 4 | 0.68
Grey69 | 11 | 11 | 11 | 0.733
Yellow | 15 | 15 | 0 | 0.886
White | 15 | 15 | 15 | 1

The luminance value is calculated using the formula for the Y component of the NTSC YIQ colour primary system. It is the intensity of the corresponding colour video signal when displayed on a black and white display.

This map includes the primary and secondary colours as well as four levels of grey. Applications which use this map will select the nearest colour, in some cases this may result in colours which do not contrast adequately - this can be solved by specifying contrasting colours on the command line of the application (using -xrm see X(1)) or in the users .Xdefaults file (or whatever file is loaded by xrdb(1)). The colour map has the property that, within the constraint of providing all the fully saturated colours, it minimises the maximum error in the representation of any colour (where the error is the distance in the RGB cube from the colour to the nearest colour map colour).

On both monochrome and colour displays if the dynamic map is the default the white pixel (pixel 15) will be as specified by -wp (or white) and the black pixel (0) will be as specified by -bp.

In 8 bit per pixel modes two static visuals are provided by default. The corresponding colour maps are set up to provide 256 colours evenly spaced through the RGB colour cube. The default visual uses a 2222 colour map with colours corresponding to all combinations of 2 bits of each of Red, Green, Blue and ``Tint''. The corresponding colours have RGB values of RRTTGGTTBBTT; 3 x 4 bits of each colour where the bottom two bits are identical for each colour (the Tint). Thus the colour map gives 16 grey levels, the darkest of which is a black and the lightest of which is full intensity white. Imagine the colour cube divided into 64 cubes, four along each axis. There are four accessible colours within each cube placed along the diagonal of the cube which goes from the lowest intensity vertex to the highest intensity vertex. Unfortunately, because of the way the hardware works, the mapping of the bits in a pixel value into the 8 bits required for a 2222 colour is not as simple as it could be - see below.

The other visual provides colours corresponding to a 332 colour map - 3 bits of Red and Green, plus 2 of Blue. This gives only four grey levels. In effect the RGB colour cube is divided into 256 equal rectanglar regions, with sides 2/16 long in the red and green axes and 4/16 long in the blue axis. Again the mapping of the bits of a pixel value into the (settable) bits of a 12 bit RGB value is explained below. The visual is distinguished by having a bitsPerRGB value of 3 as the palette setting reduces the colour resolution to three bits of red or green (and only two of blue). This is the only way in which an application can tell the different between these two static values.

If the -dynamic flag is given with an 8 bit per pixel value an additional PseudoColor (dynamic) visual is added to the screen. This attempts to express the capabilities of the hardware in terms of the X protocol. The visual has a bitsPerRGB value of 4 and 16 colour map entries (corresponding to the hardware) and it is listed under depth 8 - that is, it supports depth 8 images. The colour masks are set to values which will select the top four bits of a pixel value, the colour map corresponds to the bottom four bits. Allocation of colour map entries returns pixel values with (only) the low four bits set, and the colours returned from AllocColor and AllocNamedColor requests are converted to RGB values with only the low bits set. This is because of the way the hardware interprets an 8 bit pixel value - the top four bits of the value control the top bits of the RGB colour produced, the bottom four bits are looked up in the palette and control the remaining 8 bits of the colour. Thus the bits of a pixel value may be described as BGGRPPPP, where B is the top bit of the blue value, GG are the top two bits of the green value, R is the top bit of the red value and PPPP is an index into the palette. Then palette entry PPPP contributes the remaining three bits of blue and red and two bits of green. The red, green and blue mask values reported for the (PseudoColor) visual correspond to this, being 0x10, 0x30 and 0x80 respectively.

This unusual palette handling is used to implement the static visual classes by setting up the 16 palette entries in an appropriate manner. A 12 bit colour value is obtained from a combination of pixel bits and lookup table (palette) bits - ``plllppllplll'', where a bit ``p'' comes from the pixel and a bit ``l'' from the lookup table. The hardware restricts the RGB values to being at least 121 (ie it is not possible to implement a scheme with a less than 1 bit of colour over red and blue or two bits over green). The 2222 colour map causes a pixel value to be interpreted as BGGRBRTT (where T stands for one bit of Tint) and the palette is set up to contribute bits to the final 12 bit colour value so that it is formed from bits 421065107310 (BGR) of the original pixel value. Notice that bits 1 and 0 are replicated in each colour.

Similarly the 332 colour map causes the pixel to be interpreted as BGGRRRGB, which gives final colour values (the inverse of this mapping) of 70??651?432?. The bits marked ``?'' are not well defined in a 332 colour map - they could either be duplicates of other bits (as in the 2222 colour map) or fixed values. In fact they are set to give output colours of 707065164324 (BGR) as this gives the maximum intensity range for each primary (it does, however, mean that two of the four ``gray'' levels are not quite gray).

KEYBOARD

In RISC i X 1.2 only the Archimedes keyboard is supported. The Archimedes keyboard is mechanically similar to the IBM 101 keyboard. The keyboard has the standard typewriter keys, cursor keys, a numeric keypad and 12 function keys. The keys are mapped onto the standard X11 keycodes in an appropriate way.

The keyboard can generate up and down transitions for all keys but only has 2 key rollover for most keys. Certain keys are handled individually and, because these do not interfere with the 2 key rollover of the remainder, it is strongly recommended that these be used as modifier keys. The default modifier map uses these keys.

When the keyboard click is switched on (this is probably not a good idea) it only sounds on down transitions of non-modifier keys. The keyboard click does not sound on auto-repeats.

Xarm does not allow control of the keyboard LEDs, instead up and down transitions are transmitted on each alternate key press/release and the LED is always kept in step - ie the LED is on after a key down, off after a key up.

The Home and Print keys on the keyboard are both implemented as shifting keys in the hardware. There is no need to treat them specially although it is strongly recommended that the Print key is not used in application software as it may be used in the future within the operating system or the X server and is used within the Input Synthesis extension as the ``command key'' - see xtmrecord(1).

The keyboard has a keypad. These keys are treated as would be expected. The keys generate XK_KP_... key codes, except that the # key has no corresponding keypad code. It generates ``#''. In addition the keys on top on the top row of the keypad generate XK_KP_Fx codes when shifted, except for the Num Lock key which just generates XK_Num_Lock (and thus XK_KP_F1 is not available from the keyboard.)

The /dev/kbd driver takes one key for use in switching virtual terminals - this is the Break key. Application programs never see these keys.

The keyboard has cursor keys and function keys. Normal special control keys (TAB, Return, etc.) are also present.

In all cases the keyboard encodings used are determined by a separate file which is loaded when the keyboard is opened (each time the server reinitialises itself). The keyboard description file is determined by the -kfile argument as described above and defaults to /usr/lib/X11/XKeyboard/KB%d. These files are generated by compiling the textual files /usr/lib/X11/*.key using the xarmkeymap(1) program. The *.key files distributed may be modified to change the binding of physical keys to X11 keysyms - see xarmkeymap(1).

The handling of the Mode_switch keysym is a particular problem area. Currently this keysym is bound to the Alt keys on the keyboard. This can result in the extra graphics characters on some keys being inaccessible when the Alt key is interpreted specially by the application (such as xedit(1)). To work round this it is possible to separate the bindings of the left and right Alt keys and use one as Mode_switch and the other as Meta and Alt. See the comments in the various *.key files.

FONT SUPPORT
Xarm can use fonts in both BDF and SNF formats, either compressed or not. The SNF format used is a modification of the standard X11 SNF, so any SNF fonts must be compiled with Acorn's version of bdftosnf(1). To uncompress fonts the server requires the program /usr/ucb/uncompress. To use BDF fonts, the server requires the program /usr/bin/X11/bdftosnf.

For systems with limited disk space, fonts may be accessed across the network by FTP. The font path syntax has been extended to describe this. A font path is made up of a number of string components, each of which describes one font directory. In the simplest case, this will be a local pathname such asd /usr/lib/X11/fonts/. Note that the trailing slash is required.

If a colon is introduced into the name, then it will be interpreted as a remote directory. The full syntax is

    username@password@host:pathname:dirfile:aliasfile

Most of the fields are optional. If there is only one @ character, then the password defaults to xfonts. If the are no @ characters then both username and password default to xfonts.

Pathname is the full name of the font directory on the remote server. Because of the unknown nature of filename syntax on the remote machine, no interpretation is placed upon it; it is treated purely as a prefix to be prepended to file names. The default pathname is /usr/lib/X11/fonts/.

Dirfile is the filename in which to seek the font list. It defaults to fonts.dir. The pathname is always prepended. Aliasfile is the filename in which to seek the alias list. It defaults to fonts.alias. The pathname is always prepended.

You may include @ and : characters by escaping them with a backslash. To include a backslash in the string, enter two backslashes.

The font path may be set from the Xarm command line (see Xserver(1)) or queried and manipulated with the program xset(1).

There are obvious security problems with this system. Anyone with the ability to connect to the X server may query the current font path, and thus determine any password present. It is strongly recommended that the username and password be allowed to default, and a dedicated xfonts user be provided for font service. Alternatively set up an anonymous FTP account; see ftpd(8).

FTP errors are logged to Xarm's standard error stream. If an FTP font directory does not appear to work, then the server will drop it from the font path.

EXTENSIONS

The Input Synthesis extension is supported on Xarm. This extension allows a client application to record keyboard and mouse events and to cause the server to generate such events as though the corresponding keyboard or mouse action had occurred. The keyboard description file can be used to specify the extension command key.

The full list of supported extensions can be found using xdpyinfo(1).

FILES
/dev/fb | default frame buffer device
/dev/kbd | default keyboard/mouse device
/usr/lib/X11/rgb.* | rgb colour database
/usr/lib/X11/fonts/* | default font directorys (misc, 75dpi, 100dpi)
/usr/lib/X11/XKeyboard | directory containing keyboard files
/var/adm/X<n>msgs | error log file from X server <n>
/etc/rc.X | X system startup file
/etc/xdm/Xconfig | X server default configuration file

SEE ALSO

Xserver(1), xinit(1), xdm(1), Xstart(1), xadmin(1), xarmkeymap(1), X(1), ftp(1), twm(1), xswitcher(1), fb(4), kbd(4), ftpd(8), RISC i X X Window System Administrator's Guide

BUGS

Bugs in the Xarm server or the Acorn X11 system should be reported to unixbugs@acorn.co.uk - bugs are more likely to be fixed if submitted with a concise example which shows the problem on a system consisting solely of Acorn hardware and software. The X11 system should work correctly with any other X11 software which obeys the X11 protocol and uses TCP/IP or unix domain streams for communication (the server does not support DecNet connections.) Suggestions or comments are also welcomed.

AUTHORS

Acorn Computers Ltd
    JB, SH, SC