[deb_xorg-server.git] / xkb / XKM_file_format.txt

                        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.
Commit	Line	Data
7217e0ca ML	1	XKM File Format Description
	2	Version 15
	3
	4	1. Introduction
	5
	6	The XKM file format is the exchange format for XKB keyboard descriptions
	7	between the server and xkbcomp. Usually, the server forks off xkbcomp,
	8	xkbcomp compiles the XKM format from the given parameters.
	9	The resulting XKM file is put into a directory readable by the server and
	10	then parsed.
	11
	12	The XKM format is little more than a binary dump of various XKB-specific
	13	structures and hence tied to the ABI of the server.
	14
	15	❧❧❧❧❧❧❧❧❧❧❧
	16
	17	1.1 About this file format description
	18
	19	This description was produced by analyzing the XKM parsing code. Parts of
	20	the file description present in the original format specification may be
	21	missing. This description thus cannot be a reference document for XKM
	22	implementations.
	23
	24	No description of the meaning of the various fields is given here. Refer to
	25	the XKB protocol specification for more details.
	26	❧❧❧❧❧❧❧❧❧❧❧
	27
	28	2. Notations used in this document
	29
	30	Notation for structures:
	31
	32	┌───
	33	Name of struct
	34	name of field: type or fixed value of field
	35	name of field: type or fixed value of field
	36	└───
	37
	38	Data types are identical to those used in the X Protocol specification
	39	except where noted otherwise. Structs specific to XKM are prefixed with XKM,
	40	defines specific to the XKB protocol specification are prefixed with Xkb and
	41	their value is equivalent to that in the protocol specification.
	42
	43	Multiple instances of a given type are denoted in the following form:
	44	name of field: LISTofFIELDTYPE
	45
	46	Length specifiers for such fields are usually prefixed with num_. For
	47	example, a struct containing a num_foo of 8 and a 'foo' field contains 8
	48	structures of type 'foo'.
	49
	50	Variable length padding is specified as pad(x), where x is the length of the
	51	data to be padded out to a multiple of 4 bytes. For example, given an x of
	52	10, pad(x) would be the remaining 2 bytes to pad the whole struct to 12
	53	bytes.
	54
	55	A special notation is a variable content struct. In this case, the contents
	56	of the struct depend on the value of one or more specific fields.
	57	┌───
	58	Name of struct
	59	field: type or fixed value of field
	60	field: type or fixed value of field
	61	───
	62	field ⇒ value 1
	63	⇒
	64	specific field: type
65	specific field: type
66	───
67	field ⇒ value 2
68	⇒
69	specific field: type
70	specific field: type
71	└───
72	This notation denotes that if field is of value 1, this struct contains the
73	specific fields listed underneath value 1.
74
75	❧❧❧❧❧❧❧❧❧❧❧
76
77	3. XKM Format
78
79	The XKM format is a binary format with structs usually being padded to a
80	multiple of 4 bytes. No provisions for endianess are provided, the parser is
81	left to guess the endianess of the XKM file.
82
83	❧❧❧❧❧❧❧❧❧❧❧
84	3.1 Common data types
85
86	┌───
87	XKMCountedString
88	count: CARD16
89	string: count * CHAR
90	pad: pad(count + 2)
91	└───
92
93	XKMCountedString is used for user-readable identifiers. Prime example are
94	the level names and the section names ("complete", "evdev(inet)", etc.)
95
96	┌───
97	XKMGroupBits: CARD8
98	group1 0x1
99	group2 0x2
100	group3 0x4
101	group4 0x8
102	└───
103
104	❧❧❧❧❧❧❧❧❧❧❧
105
106	3.2 Header and Table of Contents
107
108	┌───
109	XKMHeader
110	version: CARD8
111	identifier1: 'm'
112	identifier2: 'k'
113	idenfifier3: 'x'
114	└───
115
116	The XKM file format has a 4 byte header identifying the file and the XKM
117	version. The header is followed by the table of contents indicating the
118	sections present in this file.
119
120	┌───
121	XKMFileInfo
122	type: CARD8
123	min_keycode: CARD8
124	max_keycode: CARD8
125	num_sectioninfo: CARD8
126	present: CARD16
127	pad: CARD16
128	sectioninfo: LISTofXKMSectionInfo
129	└───
130
131	min_keycode and max_keycode specify the keycode range for this keyboard
132	descriptions. The core protocol requires min_keycode always be equal to or
133	greater than 8.
134
135	┌───
136	XKMSectionInfo
137	type: CARD16
138	XkmTypesIndex 0
139	XkmCompatMapIndex 1
140	XkmSymbolsIndex 2
141	XkmIndicatorsIndex 3
142	XkmKeyNamesIndex 4
143	XkmGeometryIndex 5
144	XkmVirtualModsIndex 6
145	format: CARD16
146	size: CARD16
147	offset: CARD16
148	└───
149
150	Describes the section found in a chunk of a file. This struct is found
151	_twice_ in the file per section, once as part of the XKMFileInfo, once at
152	the beginning of the actual section (see offset).
153	The type specifies the type of the section, the section is to be parsed
154	according to this type.
155	Size and offset specify the size in bytes and the offset into the file in
156	bytes, respectively.
157
158	3.3 Sections
159
160	Each section resides at the offset specified in the XKMFileInfo sectioninfo.
161
162	❧❧❧❧❧❧❧❧❧❧❧
163
164	3.3.1 XKMTypes
165
166	An XKMTypes section describes the key types defined in a layout. Roughly
167	speaking, a key type defines how many levels a given key has and which
168	modifiers change to a particular level.
169
170	┌───
171	XKMTypesSection
172	section_info: XKMSectionInfo
173	name: XKMCountedString
174	num_types: CARD16
175	pad: CARD16
176	types: LISTofXKMKeyType
177	└───
178
179	┌───
180	XKMKeyType
181	real_mods: CARD8
182	num_levels: CARD8
183	virt_mods: CARD16
184	num_map_entries: CARD8
185	num_level_names: CARD8
186	perserve: CARD8
187	pad: CARD8
188	map_entries: LISTofXKMKTMapEntry
189	name: XKMCountedString
190	mods: LISTofXKMModsDesc
191	level_names: LISXTofXKMCountedString
192	└───
193
194	The num_map_entries specifies the number of structs in both map_entries and mods. mods is only present if preserve is TRUE.
195
196	┌───
197	XKMKTMapEntry
198	level: CARD8
199	real_mods: CARD8
200	virt_mods: CARD16
201	└───
202
203	┌───
204	XKMModsDesc
205	real_mods: CARD8
206	pad: CARD8
207	virt_mods: CARD16
208	└───
209
210	❧❧❧❧❧❧❧❧❧❧❧
211	3.3.2 XKMCompatMap
212
213	An XKMCompatMap section describes the actions a keyboard may trigger. This
214	ranges from the TerminateServer action to simple modifier bits.
215
216	┌───
217	XKMCompatMap
218	section_info: XKMSectionInfo
219	name: XKMCountedString
220	num_si: CARD16
221	group_mask: XKMGroupBits
222	pad: CARD8
223	si: LISTofXKMSymInterpreterDesc
224	groups: LISTofXKMModsDesc
225	└───
226
227	One XKMModsDesc is present for each bit set in group_mask.
228
229	┌───
230	XKMSymInterpretDesc
231	sym: CARD32
232	mods: CARD8
233	match: CARD8
234	virtual_mod: CARD8
235	flags: CARD8
236	action_type: CARD8
237	action_data: XKMActionData
238	└───
239
240	Where the action is 7 bytes of CARD8 whose content is determined by
241	action_type.
242
243	┌───
244	XKMActionData:
245	pad0: CARD8
246	pad1: CARD16
247	pad2: CARD32
248	───
249	action_type ⇒ XkbSA_SetMods \|\|
250	action_type ⇒ XkbSA_LatchMods \|\|
251	action_type ⇒ XkbSA_LockMods
252	⇒
253	flags: CARD8
254	mask: CARD8
255	real_mods: CARD8
256	vmods1: CARD8
257	vmods2: CARD8
258	pad: CARD16
259	───
260	action_type ⇒ XkbSA_SetGroup \|\|
261	action_type ⇒ XkbSA_LatchGroup \|\|
262	action_type ⇒ XkbSA_LockGroup
263	⇒
264	flags: CARD8
265	group_XXX: CARD8
266	pad0: CARD8
267	pad1: CARD32
268	───
269	action_type ⇒ XkbSA_MovePtr
270	⇒
271	flags: CARD8
272	high_XXX: CARD8
273	low_XXX: CARD8
274	high_YYY: CARD8
275	low_YYY: CARD8
276	pad: CARD16
277	───
278	action_type ⇒ XkbSA_PtrBtn \|\|
279	action_type ⇒ XkbSA_LockPtrBtn
280	⇒
281	flags: CARD8
282	count: CARD8
283	button: CARD8
284	pad: CARD32
285	───
286	action_type ⇒ XkbSA_DeviceBtn \|\|
287	action_type ⇒ XkbSA_LockLockPtrBtn
288	⇒
289	flags: CARD8
290	count: CARD8
291	button: CARD8
292	device: CARD8
293	pad0: CARD8
294	pad1: CARD16
295	───
296	action_type ⇒ XkbSA_SetPtrDflt
297	⇒
298	flags: CARD8
299	affect: CARD8
300	valueXXX: CARD8
301	pad0: CARD32
302	───
303	action_type ⇒ XkbSA_ISOLock
304	⇒
305	flags: CARD8
306	mask: CARD8
307	real_mods: CARD8
308	group_XXX: CARD8
309	affect: CARD8
310	vmods1: CARD8
311	vmods1: CARD8
312	───
313	action_type ⇒ XkbSA_SwitchScreen
314	⇒
315	flags: CARD8
316	screenXXX: CARD8
317	pad0: CARD8
318	pad1: CARD32
319	───
320	action_type ⇒ XkbSA_SetControls \|\|
321	action_type ⇒ XkbSA_LockControls
322	⇒
323	flags: CARD8
324	ctrls3: CARD8
325	ctrls2: CARD8
326	ctrls1: CARD8
327	ctrls0: CARD8
328	pad: CARD16
329	───
330	action_type ⇒ XkbSA_RedirectKey
331	⇒
332	new_key: CARD8
333	mods_mask: CARD8
334	mods: CARD8
335	vmods_mask0: CARD8
336	vmods_mask1: CARD8
337	vmods0: CARD8
338	vmods1: CARD8
339	───
340	action_type ⇒ XkbSA_DeviceValuator
341	⇒
342	device: CARD8
343	v1_what: CARD8
344	v1_idx: CARD8
345	v1_value: CARD8
346	v2_what: CARD8
347	v2_idx: CARD8
348	v2_value: CARD8
349	pad: CARD8
350	───
351	action_type ⇒ XkbSA_XFree86Private \|\|
352	action_type ⇒ XkbSA_Terminate
353	⇒
354	pad0: CARD8
355	pad1: CARD16
356	pad2: CARD32
357	───
358	action_type ⇒ XkbSA_ActionMessage
359	⇒
360	press_msg: BOOL
361	release_msg: BOOL
362	gen_event: BOOL
363	message: 4 * CHAR
364	└───
365
366	Note: XkbSA_ActionMessage is currently unsupported and the contents are
367	ignored.
368
369	❧❧❧❧❧❧❧❧❧❧❧
370	3.3.3 XkmSymbols
371
372	The symbols in a keymap define the actual keysyms each key may produce.
373
374	┌───
375	XKMSymbols
376	section_info: XKMSectionInfo
377	name: XKMCountedString
378	min_keycode: CARD8
379	max_keycode: CARD8
380	group_names_mask: XKMGroupBits
381	num_vmod_maps: CARD8
382	group_names: LISTofXKMCountedString
383	keysyms: XKMKeysymMapDesc
384	vmod_maps: XKMVModMapDesc
385	└───
386	One group_name is present for each bit set in group_names_mask.
387	The number of keysyms present is max_keycode - min_keycode + 1.
388
389	┌───
390	XKMKeysymMapDesc
391	width: CARD8
392	num_groups: CARD8
393	modifier_map: CARD8
394	flags: CARD8
395	names: LISTofXKMCountedString
396	syms: LISTofCARD32
397	behavior: XKMBehaviorDesc
398	└───
399
400	Presence of names is conditional on the XkmKeyHasTypes flag. The number of
401	strings is equal to the number of group bits in group_names_mask in the
402	preceeding XKMSymbols section.
403	The number of elements in syms is equal to width * num_groups.
404	Presence of behavior is conditional on the XkmKeyHasBehavior flag.
405
406	┌───
407	XKMKeyBehaviorDesc
408	type: CARD8
409	data: CARD8
410	pad: CARD16
411	└───
412
413	┌───
414	XKMVModMapDesc
415	key: CARD8
416	pad: CARD8
417	vmods: CARD16
418	└───
419
420	❧❧❧❧❧❧❧❧❧❧❧
421
422	3.3.4 XKMIndicators
423
424	┌───
425	XKMIndicators
426	section_info: XKMSectionInfo
427	name: XKMCountedString
428	num_indicators: CARD8
429	pad0: CARD8
430	pad1: CARD16
431	indicators: LISTofXKMIndicatorMapDesc
432	└───
433
434	┌───
435	XKMIndicatorMapDesc
436	name: XKMCountedString
437	indicator: CARD8
438	flags: CARD8
439	which_mods: CARD8
440	real_mods: CARD8
441	vmods: CARD16
442	which_groups: CARD8
443	groups: CARD8
444	ctrls: CARD32
445	└───
446	❧❧❧❧❧❧❧❧❧❧❧
447
448	3.3.5 XKMKeyNames
449
450	┌───
451	XKMKeyNames
452	section_info: XKMSectionInfo
453	name: XKMCountedString
454	min_keycode: CARD8
455	max_keycode: CARD8
456	num_aliases: CARD8
457	pad: CARD8
458	keynames: LISTofXKMKeyname
459	aliases: LISTofXKMKeyAlias
460	└───
461
462	keynames contains max_keycode - min_keycode + 1 entries.
463
464	┌───
465	XkmKeyname
466	name: 4 * CHAR8
467	└───
468
469	┌───
470	XkmKeyAlias
471	real: XkmKeyname
472	alias: XkmKeyname
473	└───
474
475	❧❧❧❧❧❧❧❧❧❧❧
476
477	3.3.5 XKMGeometry
478
479	┌───
480	XKMGeometry
481	section_info: XKMSectionInfo
482	name: XKMCountedString
483	width_mm: CARD16
484	height_mm: CARD16
485	base_color_ndx: CARD8
486	label_color_ndx: CARD8
487	num_properties: CARD16
488	num_colors: CARD16
489	num_shapes: CARD16
490	num_sections: CARD16
491	num_doodads: CARD16
492	num_key_aliases: CARD16
493	pad: CARD16
494	label_font: XKMCountedString
495	properties: LISTofXKMGeomProperty
496	colors: LISTofXKMCountedString
497	shapes: LISTofXKMGeomShape
498	sections: LISTofXKMGeomSection
499	doodads: LISTofXKMGeomDoodad
500	key_aliases: LISTofXKMKeyAlias
501	└───
502
503	┌───
504	XKMGeomProperty
505	name: XKMCountedString
506	value: XKMCountedString
507
508	└───
509
510	┌───
511	XKMGeomShape
512	name: XKMCountedString
513	num_outlines: CARD8
514	primary_idx: CARD8
515	approx_idx: CARD8
516	pad: CARD8
517	outlines: LISTofXKMOutlineDesc
518	└───
519
520	┌───
521	XKMOutlineDesc
522	num_points: CARD8
523	corner_radius: CARD8
524	pad: CARD16
525	points: LISTofXKMPointDesc
526	└───
527
528	┌───
529	XKMPointDesc
530	x: INT16
531	y: INT16
532	└───
533
534	┌───
535	XKMGeomSection
536	name: XKMCountedString
537	top: INT16
538	left: INT16
539	width: CARD16
540	height: CARD16
541	angle: INT16
542	priority: CARD8
543	num_rows: CARD8
544	num_doodads: CARD8
545	num_overlays: CARD8
546	pad: CARD16
547	rows: LISTofXKMRowDesc
548	doodads: LISTofXKMGeomDoodad
549	overlays: LISTofXKMGeomOverlay
550	└───
551
552	┌───
553	XKMRowDesc
554	top: INT16
555	left: INT16
556	num_keys: CARD8
557	vertical: BOOL
558	pad: CARD16
559	keys: XKMKeyDesc
560	└───
561
562	┌───
563	XKMKeyDesc
564	name: XKMKeyname
565	gap: INT16
566	shape_idx: CARD8
567	color_idx: CARD8
568	└───
569
570	┌───
571	XKMGeomDoodad
572	name: XKMCountedString
573	type: CARD8
574	priority: CARD8
575	top: INT16
576	left: INT16
577	pad1: CARD16
578	pad2: CARD32
579	pad3: CARD32
580	───
581	type ⇒ XkbOutlineDoodad \|\|
582	type ⇒ XkbSolideDoodad
583	⇒
584	type: CARD8
585	priority: CARD8
586	top: INT16
587	left: INT16
588	angle: INT16
589	color_idx: CARD8
590	shape_idx: CARD8
591	pad0: CARD16
592	pad1: CARD32
593	───
594	type ⇒ XkbTextDoodad
595	⇒
596	type: CARD8
597	priority: CARD8
598	top: INT16
599	left: INT16
600	angle: INT16
601	width: CARD16
602	height: CARD16
603	color_idx: CARD8
604	pad0: CARD8
605	pad1: CARD16
606	text: XKMCountedString
607	font: XKMCountedString
608	───
609	type ⇒ XkbIndicatorDoodad
610	⇒
611	type: CARD8
612	priority: CARD8
613	top: INT16
614	left: INT16
615	shape_idx: CARD8
616	on_color_idx: CARD8
617	off_color_idx: CARD8
618	pad0: CARD8
619	pad1: CARD16
620	pad2: CARD32
621	───
622	type ⇒ XkbLogoDoodad
623	⇒
624	type: CARD8
625	priority: CARD8
626	top: INT16
627	left: INT16
628	angle: INT16
629	color_idx: CARD8
630	shape_idx: CARD8
631	pad0: CARD16
632	pad1: CARD32
633	logo_name: XKMCountedString
634	└───
635
636	WARNING: XKMGeomDoodad has variable length depending on the type.
637	NOTE: The current server implementation does not use all fields of all
638	structures.
639
640	┌───
641	XKMOverlayDesc
642	name: XKMCountedString
643	num_rows: CARD8
644	pad0: CARD8
645	pad1: CARD16
646	rows: LISTofXKMOverlayRowDesc
647	└───
648
649	┌───
650	XKMOverlayRowDesc
651	name: XKMCountedString
652	row_under: CARD8
653	num_keys: CARD8
654	pad: CARD16
655	keys: LISTofXKMOverlayKeyDesc
656	└───
657
658	┌───
659	XKMOverlayKeyDesc
660	over: XKMKeyname
661	under: XKMKeyname
662	└───
663
664	❧❧❧❧❧❧❧❧❧❧❧
665
666	3.3.6 XKMVirtualMods
667
668	┌───
669	XKMOverlayRowDesc
670	section_info: XKMSectionInfo
671	name: XKMCountedString
672	bound_mask: SETofVMODBITS
673	named_mask: SETofVMODBITS
674	vmods: LISTofCARD8
675	pad: pad(vmods)
676	names: LISTofXKMCountedString
677	└───
678
679	VMODBITS: CARD16
680
681	Number of elements in vmods is equal to the number of bits set in
682	bound_mask. The padding completes vmods to a multiple of 4 byte units.
683	Number of elements in names is equal to the number of bits set in
684	named_mask.