xenocara/xserver/xkb/XKM_file_format.txt

685 lines
15 KiB
Plaintext

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.