[PATCH] xkb: Add XKM file format description.
Peter Hutterer
peter.hutterer at who-t.net
Fri Dec 18 17:16:58 PST 2009
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
I'd really like to see this in git somewhere and the server is as good a
place as any.
xkb/XKM_file_format.txt | 685 +++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 685 insertions(+), 0 deletions(-)
create mode 100644 xkb/XKM_file_format.txt
diff --git a/xkb/XKM_file_format.txt b/xkb/XKM_file_format.txt
new file mode 100644
index 0000000..6c1e2e0
--- /dev/null
+++ b/xkb/XKM_file_format.txt
@@ -0,0 +1,685 @@
+ 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 fo
+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 identicial 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.1 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.2. Sections
+
+Each section resides at the offset specified in the XKMFileInfo sectioninfo.
+
+ ❧❧❧❧❧❧❧❧❧❧❧
+
+3.2.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.2.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.2.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 sysms 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.2.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.2.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.2.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.2.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.
+
--
1.6.5.2
More information about the xorg-devel
mailing list