diff options
Diffstat (limited to 'xorg-server/xkb/XKM_file_format.txt')
| -rw-r--r-- | xorg-server/xkb/XKM_file_format.txt | 684 |
1 files changed, 684 insertions, 0 deletions
diff --git a/xorg-server/xkb/XKM_file_format.txt b/xorg-server/xkb/XKM_file_format.txt new file mode 100644 index 000000000..0ba28ee8c --- /dev/null +++ b/xorg-server/xkb/XKM_file_format.txt @@ -0,0 +1,684 @@ + 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. |