XKM File Format Description
|
Version 15
|
|
1. Introduction
|
|
The XKM file format is the exchange format for XKB keyboard descriptions
|
between the server and xkbcomp. Usually, the server forks off xkbcomp,
|
xkbcomp compiles the XKM format from the given parameters.
|
The resulting XKM file is put into a directory readable by the server and
|
then parsed.
|
|
The XKM format is little more than a binary dump of various XKB-specific
|
structures and hence tied to the ABI of the server.
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
1.1 About this file format description
|
|
This description was produced by analyzing the XKM parsing code. Parts of
|
the file description present in the original format specification may be
|
missing. This description thus cannot be a reference document for XKM
|
implementations.
|
|
No description of the meaning of the various fields is given here. Refer to
|
the XKB protocol specification for more details.
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
2. Notations used in this document
|
|
Notation for structures:
|
|
┌───
|
Name of struct
|
name of field: type or fixed value of field
|
name of field: type or fixed value of field
|
└───
|
|
Data types are identical to those used in the X Protocol specification
|
except where noted otherwise. Structs specific to XKM are prefixed with XKM,
|
defines specific to the XKB protocol specification are prefixed with Xkb and
|
their value is equivalent to that in the protocol specification.
|
|
Multiple instances of a given type are denoted in the following form:
|
name of field: LISTofFIELDTYPE
|
|
Length specifiers for such fields are usually prefixed with num_. For
|
example, a struct containing a num_foo of 8 and a 'foo' field contains 8
|
structures of type 'foo'.
|
|
Variable length padding is specified as pad(x), where x is the length of the
|
data to be padded out to a multiple of 4 bytes. For example, given an x of
|
10, pad(x) would be the remaining 2 bytes to pad the whole struct to 12
|
bytes.
|
|
A special notation is a variable content struct. In this case, the contents
|
of the struct depend on the value of one or more specific fields.
|
┌───
|
Name of struct
|
field: type or fixed value of field
|
field: type or fixed value of field
|
───
|
field ⇒ value 1
|
⇒
|
specific field: type
|
specific field: type
|
───
|
field ⇒ value 2
|
⇒
|
specific field: type
|
specific field: type
|
└───
|
This notation denotes that if field is of value 1, this struct contains the
|
specific fields listed underneath value 1.
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3. XKM Format
|
|
The XKM format is a binary format with structs usually being padded to a
|
multiple of 4 bytes. No provisions for endianess are provided, the parser is
|
left to guess the endianess of the XKM file.
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
3.1 Common data types
|
|
┌───
|
XKMCountedString
|
count: CARD16
|
string: count * CHAR
|
pad: pad(count + 2)
|
└───
|
|
XKMCountedString is used for user-readable identifiers. Prime example are
|
the level names and the section names ("complete", "evdev(inet)", etc.)
|
|
┌───
|
XKMGroupBits: CARD8
|
group1 0x1
|
group2 0x2
|
group3 0x4
|
group4 0x8
|
└───
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3.2 Header and Table of Contents
|
|
┌───
|
XKMHeader
|
version: CARD8
|
identifier1: 'm'
|
identifier2: 'k'
|
idenfifier3: 'x'
|
└───
|
|
The XKM file format has a 4 byte header identifying the file and the XKM
|
version. The header is followed by the table of contents indicating the
|
sections present in this file.
|
|
┌───
|
XKMFileInfo
|
type: CARD8
|
min_keycode: CARD8
|
max_keycode: CARD8
|
num_sectioninfo: CARD8
|
present: CARD16
|
pad: CARD16
|
sectioninfo: LISTofXKMSectionInfo
|
└───
|
|
min_keycode and max_keycode specify the keycode range for this keyboard
|
descriptions. The core protocol requires min_keycode always be equal to or
|
greater than 8.
|
|
┌───
|
XKMSectionInfo
|
type: CARD16
|
XkmTypesIndex 0
|
XkmCompatMapIndex 1
|
XkmSymbolsIndex 2
|
XkmIndicatorsIndex 3
|
XkmKeyNamesIndex 4
|
XkmGeometryIndex 5
|
XkmVirtualModsIndex 6
|
format: CARD16
|
size: CARD16
|
offset: CARD16
|
└───
|
|
Describes the section found in a chunk of a file. This struct is found
|
_twice_ in the file per section, once as part of the XKMFileInfo, once at
|
the beginning of the actual section (see offset).
|
The type specifies the type of the section, the section is to be parsed
|
according to this type.
|
Size and offset specify the size in bytes and the offset into the file in
|
bytes, respectively.
|
|
3.3 Sections
|
|
Each section resides at the offset specified in the XKMFileInfo sectioninfo.
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3.3.1 XKMTypes
|
|
An XKMTypes section describes the key types defined in a layout. Roughly
|
speaking, a key type defines how many levels a given key has and which
|
modifiers change to a particular level.
|
|
┌───
|
XKMTypesSection
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
num_types: CARD16
|
pad: CARD16
|
types: LISTofXKMKeyType
|
└───
|
|
┌───
|
XKMKeyType
|
real_mods: CARD8
|
num_levels: CARD8
|
virt_mods: CARD16
|
num_map_entries: CARD8
|
num_level_names: CARD8
|
perserve: CARD8
|
pad: CARD8
|
map_entries: LISTofXKMKTMapEntry
|
name: XKMCountedString
|
mods: LISTofXKMModsDesc
|
level_names: LISXTofXKMCountedString
|
└───
|
|
The num_map_entries specifies the number of structs in both map_entries and mods. mods is only present if preserve is TRUE.
|
|
┌───
|
XKMKTMapEntry
|
level: CARD8
|
real_mods: CARD8
|
virt_mods: CARD16
|
└───
|
|
┌───
|
XKMModsDesc
|
real_mods: CARD8
|
pad: CARD8
|
virt_mods: CARD16
|
└───
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
3.3.2 XKMCompatMap
|
|
An XKMCompatMap section describes the actions a keyboard may trigger. This
|
ranges from the TerminateServer action to simple modifier bits.
|
|
┌───
|
XKMCompatMap
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
num_si: CARD16
|
group_mask: XKMGroupBits
|
pad: CARD8
|
si: LISTofXKMSymInterpreterDesc
|
groups: LISTofXKMModsDesc
|
└───
|
|
One XKMModsDesc is present for each bit set in group_mask.
|
|
┌───
|
XKMSymInterpretDesc
|
sym: CARD32
|
mods: CARD8
|
match: CARD8
|
virtual_mod: CARD8
|
flags: CARD8
|
action_type: CARD8
|
action_data: XKMActionData
|
└───
|
|
Where the action is 7 bytes of CARD8 whose content is determined by
|
action_type.
|
|
┌───
|
XKMActionData:
|
pad0: CARD8
|
pad1: CARD16
|
pad2: CARD32
|
───
|
action_type ⇒ XkbSA_SetMods ||
|
action_type ⇒ XkbSA_LatchMods ||
|
action_type ⇒ XkbSA_LockMods
|
⇒
|
flags: CARD8
|
mask: CARD8
|
real_mods: CARD8
|
vmods1: CARD8
|
vmods2: CARD8
|
pad: CARD16
|
───
|
action_type ⇒ XkbSA_SetGroup ||
|
action_type ⇒ XkbSA_LatchGroup ||
|
action_type ⇒ XkbSA_LockGroup
|
⇒
|
flags: CARD8
|
group_XXX: CARD8
|
pad0: CARD8
|
pad1: CARD32
|
───
|
action_type ⇒ XkbSA_MovePtr
|
⇒
|
flags: CARD8
|
high_XXX: CARD8
|
low_XXX: CARD8
|
high_YYY: CARD8
|
low_YYY: CARD8
|
pad: CARD16
|
───
|
action_type ⇒ XkbSA_PtrBtn ||
|
action_type ⇒ XkbSA_LockPtrBtn
|
⇒
|
flags: CARD8
|
count: CARD8
|
button: CARD8
|
pad: CARD32
|
───
|
action_type ⇒ XkbSA_DeviceBtn ||
|
action_type ⇒ XkbSA_LockLockPtrBtn
|
⇒
|
flags: CARD8
|
count: CARD8
|
button: CARD8
|
device: CARD8
|
pad0: CARD8
|
pad1: CARD16
|
───
|
action_type ⇒ XkbSA_SetPtrDflt
|
⇒
|
flags: CARD8
|
affect: CARD8
|
valueXXX: CARD8
|
pad0: CARD32
|
───
|
action_type ⇒ XkbSA_ISOLock
|
⇒
|
flags: CARD8
|
mask: CARD8
|
real_mods: CARD8
|
group_XXX: CARD8
|
affect: CARD8
|
vmods1: CARD8
|
vmods1: CARD8
|
───
|
action_type ⇒ XkbSA_SwitchScreen
|
⇒
|
flags: CARD8
|
screenXXX: CARD8
|
pad0: CARD8
|
pad1: CARD32
|
───
|
action_type ⇒ XkbSA_SetControls ||
|
action_type ⇒ XkbSA_LockControls
|
⇒
|
flags: CARD8
|
ctrls3: CARD8
|
ctrls2: CARD8
|
ctrls1: CARD8
|
ctrls0: CARD8
|
pad: CARD16
|
───
|
action_type ⇒ XkbSA_RedirectKey
|
⇒
|
new_key: CARD8
|
mods_mask: CARD8
|
mods: CARD8
|
vmods_mask0: CARD8
|
vmods_mask1: CARD8
|
vmods0: CARD8
|
vmods1: CARD8
|
───
|
action_type ⇒ XkbSA_DeviceValuator
|
⇒
|
device: CARD8
|
v1_what: CARD8
|
v1_idx: CARD8
|
v1_value: CARD8
|
v2_what: CARD8
|
v2_idx: CARD8
|
v2_value: CARD8
|
pad: CARD8
|
───
|
action_type ⇒ XkbSA_XFree86Private ||
|
action_type ⇒ XkbSA_Terminate
|
⇒
|
pad0: CARD8
|
pad1: CARD16
|
pad2: CARD32
|
───
|
action_type ⇒ XkbSA_ActionMessage
|
⇒
|
press_msg: BOOL
|
release_msg: BOOL
|
gen_event: BOOL
|
message: 4 * CHAR
|
└───
|
|
Note: XkbSA_ActionMessage is currently unsupported and the contents are
|
ignored.
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
3.3.3 XkmSymbols
|
|
The symbols in a keymap define the actual keysyms each key may produce.
|
|
┌───
|
XKMSymbols
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
min_keycode: CARD8
|
max_keycode: CARD8
|
group_names_mask: XKMGroupBits
|
num_vmod_maps: CARD8
|
group_names: LISTofXKMCountedString
|
keysyms: XKMKeysymMapDesc
|
vmod_maps: XKMVModMapDesc
|
└───
|
One group_name is present for each bit set in group_names_mask.
|
The number of keysyms present is max_keycode - min_keycode + 1.
|
|
┌───
|
XKMKeysymMapDesc
|
width: CARD8
|
num_groups: CARD8
|
modifier_map: CARD8
|
flags: CARD8
|
names: LISTofXKMCountedString
|
syms: LISTofCARD32
|
behavior: XKMBehaviorDesc
|
└───
|
|
Presence of names is conditional on the XkmKeyHasTypes flag. The number of
|
strings is equal to the number of group bits in group_names_mask in the
|
preceeding XKMSymbols section.
|
The number of elements in syms is equal to width * num_groups.
|
Presence of behavior is conditional on the XkmKeyHasBehavior flag.
|
|
┌───
|
XKMKeyBehaviorDesc
|
type: CARD8
|
data: CARD8
|
pad: CARD16
|
└───
|
|
┌───
|
XKMVModMapDesc
|
key: CARD8
|
pad: CARD8
|
vmods: CARD16
|
└───
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3.3.4 XKMIndicators
|
|
┌───
|
XKMIndicators
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
num_indicators: CARD8
|
pad0: CARD8
|
pad1: CARD16
|
indicators: LISTofXKMIndicatorMapDesc
|
└───
|
|
┌───
|
XKMIndicatorMapDesc
|
name: XKMCountedString
|
indicator: CARD8
|
flags: CARD8
|
which_mods: CARD8
|
real_mods: CARD8
|
vmods: CARD16
|
which_groups: CARD8
|
groups: CARD8
|
ctrls: CARD32
|
└───
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3.3.5 XKMKeyNames
|
|
┌───
|
XKMKeyNames
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
min_keycode: CARD8
|
max_keycode: CARD8
|
num_aliases: CARD8
|
pad: CARD8
|
keynames: LISTofXKMKeyname
|
aliases: LISTofXKMKeyAlias
|
└───
|
|
keynames contains max_keycode - min_keycode + 1 entries.
|
|
┌───
|
XkmKeyname
|
name: 4 * CHAR8
|
└───
|
|
┌───
|
XkmKeyAlias
|
real: XkmKeyname
|
alias: XkmKeyname
|
└───
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3.3.5 XKMGeometry
|
|
┌───
|
XKMGeometry
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
width_mm: CARD16
|
height_mm: CARD16
|
base_color_ndx: CARD8
|
label_color_ndx: CARD8
|
num_properties: CARD16
|
num_colors: CARD16
|
num_shapes: CARD16
|
num_sections: CARD16
|
num_doodads: CARD16
|
num_key_aliases: CARD16
|
pad: CARD16
|
label_font: XKMCountedString
|
properties: LISTofXKMGeomProperty
|
colors: LISTofXKMCountedString
|
shapes: LISTofXKMGeomShape
|
sections: LISTofXKMGeomSection
|
doodads: LISTofXKMGeomDoodad
|
key_aliases: LISTofXKMKeyAlias
|
└───
|
|
┌───
|
XKMGeomProperty
|
name: XKMCountedString
|
value: XKMCountedString
|
|
└───
|
|
┌───
|
XKMGeomShape
|
name: XKMCountedString
|
num_outlines: CARD8
|
primary_idx: CARD8
|
approx_idx: CARD8
|
pad: CARD8
|
outlines: LISTofXKMOutlineDesc
|
└───
|
|
┌───
|
XKMOutlineDesc
|
num_points: CARD8
|
corner_radius: CARD8
|
pad: CARD16
|
points: LISTofXKMPointDesc
|
└───
|
|
┌───
|
XKMPointDesc
|
x: INT16
|
y: INT16
|
└───
|
|
┌───
|
XKMGeomSection
|
name: XKMCountedString
|
top: INT16
|
left: INT16
|
width: CARD16
|
height: CARD16
|
angle: INT16
|
priority: CARD8
|
num_rows: CARD8
|
num_doodads: CARD8
|
num_overlays: CARD8
|
pad: CARD16
|
rows: LISTofXKMRowDesc
|
doodads: LISTofXKMGeomDoodad
|
overlays: LISTofXKMGeomOverlay
|
└───
|
|
┌───
|
XKMRowDesc
|
top: INT16
|
left: INT16
|
num_keys: CARD8
|
vertical: BOOL
|
pad: CARD16
|
keys: XKMKeyDesc
|
└───
|
|
┌───
|
XKMKeyDesc
|
name: XKMKeyname
|
gap: INT16
|
shape_idx: CARD8
|
color_idx: CARD8
|
└───
|
|
┌───
|
XKMGeomDoodad
|
name: XKMCountedString
|
type: CARD8
|
priority: CARD8
|
top: INT16
|
left: INT16
|
pad1: CARD16
|
pad2: CARD32
|
pad3: CARD32
|
───
|
type ⇒ XkbOutlineDoodad ||
|
type ⇒ XkbSolideDoodad
|
⇒
|
type: CARD8
|
priority: CARD8
|
top: INT16
|
left: INT16
|
angle: INT16
|
color_idx: CARD8
|
shape_idx: CARD8
|
pad0: CARD16
|
pad1: CARD32
|
───
|
type ⇒ XkbTextDoodad
|
⇒
|
type: CARD8
|
priority: CARD8
|
top: INT16
|
left: INT16
|
angle: INT16
|
width: CARD16
|
height: CARD16
|
color_idx: CARD8
|
pad0: CARD8
|
pad1: CARD16
|
text: XKMCountedString
|
font: XKMCountedString
|
───
|
type ⇒ XkbIndicatorDoodad
|
⇒
|
type: CARD8
|
priority: CARD8
|
top: INT16
|
left: INT16
|
shape_idx: CARD8
|
on_color_idx: CARD8
|
off_color_idx: CARD8
|
pad0: CARD8
|
pad1: CARD16
|
pad2: CARD32
|
───
|
type ⇒ XkbLogoDoodad
|
⇒
|
type: CARD8
|
priority: CARD8
|
top: INT16
|
left: INT16
|
angle: INT16
|
color_idx: CARD8
|
shape_idx: CARD8
|
pad0: CARD16
|
pad1: CARD32
|
logo_name: XKMCountedString
|
└───
|
|
WARNING: XKMGeomDoodad has variable length depending on the type.
|
NOTE: The current server implementation does not use all fields of all
|
structures.
|
|
┌───
|
XKMOverlayDesc
|
name: XKMCountedString
|
num_rows: CARD8
|
pad0: CARD8
|
pad1: CARD16
|
rows: LISTofXKMOverlayRowDesc
|
└───
|
|
┌───
|
XKMOverlayRowDesc
|
name: XKMCountedString
|
row_under: CARD8
|
num_keys: CARD8
|
pad: CARD16
|
keys: LISTofXKMOverlayKeyDesc
|
└───
|
|
┌───
|
XKMOverlayKeyDesc
|
over: XKMKeyname
|
under: XKMKeyname
|
└───
|
|
❧❧❧❧❧❧❧❧❧❧❧
|
|
3.3.6 XKMVirtualMods
|
|
┌───
|
XKMOverlayRowDesc
|
section_info: XKMSectionInfo
|
name: XKMCountedString
|
bound_mask: SETofVMODBITS
|
named_mask: SETofVMODBITS
|
vmods: LISTofCARD8
|
pad: pad(vmods)
|
names: LISTofXKMCountedString
|
└───
|
|
VMODBITS: CARD16
|
|
Number of elements in vmods is equal to the number of bits set in
|
bound_mask. The padding completes vmods to a multiple of 4 byte units.
|
Number of elements in names is equal to the number of bits set in
|
named_mask.
|
