2021-08-11 11:08:32 +00:00
{
version: 0.1.0
documentation: {
order: [
broadcast_messages
2022-05-22 15:01:37 +00:00
!broadcast_messages.md.j2
2021-08-11 11:08:32 +00:00
]
reserved_tokens:
'''
2022-07-06 23:57:59 +00:00
Two token values are reserved: `0xFFFE` and `0xFFFF`:
* `0xFFFE`: A message sent by a host application may use this token if no response is to be sent -- a "fire and forget" message.
2021-08-11 11:08:32 +00:00
* `0xFFFF`: Signifies a "broadcast" message sent by the firmware without prompting from the host application. Broadcast messages are defined later in this document.
Any request will generate at least one corresponding response, with the exception of messages using reserved tokens. Maximum total message length is 128 bytes due to RAM constraints.
'''
broadcast_messages:
'''
## Broadcast messages
Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
'''
}
response_flags: {
bits: {
1: {
name: Secure Failure
define: SECURE_FAILURE
description:
'''
When this bit is set, the requested _route_ was marked _secure_ but an _unlock sequence_ has not completed.
'''
}
}
}
type_docs: {
2023-03-22 21:20:55 +00:00
bool:
'''
Data type that contains values 0 and 1. Implementaed as an alias of `u8`.
'''
2021-08-11 11:08:32 +00:00
u64:
'''
An unsigned 64-bit integral, commonly seen as `uint64_t` from _stdint.h_.
'''
"struct{}":
'''
2021-09-16 01:43:19 +00:00
A structure of data, packing different objects together. Data is "compacted" -- there are no padding bytes between fields. Equivalent to a packed C-style `struct`. The order in which they're defined matches the order of the data in the response packet.
2021-08-11 11:08:32 +00:00
'''
}
term_definitions: {
Capability:
'''
A way to determine if certain functionality is enabled in the firmware. Any _subsystem_ that provides build-time restriction of functionality must provide a _route_ for a _capabilities query_.
'''
"Secure Route":
'''
A _route_ which has potentially destructive consequences, necessitating prior approval by the user before executing.
'''
"Unlock sequence":
'''
A physical sequence initiated by the user to enable execution of _secure routes_.
'''
}
2022-04-05 17:54:28 +00:00
type_definitions: {
broadcast_header: {
name: Broadcast Header
description: Packet format for broadcast messages.
type: struct
2022-04-19 02:33:56 +00:00
struct_length: 4
2022-04-05 17:54:28 +00:00
struct_members: [
{
type: token
name: token
},
{
type: u8
name: type
},
{
type: u8
name: length
}
]
}
}
2021-08-11 11:08:32 +00:00
broadcast_messages: {
define_prefix: XAP_BROADCAST
messages: {
0x00: {
name: Log message
define: LOG_MESSAGE
description:
'''
Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
**Example Log Broadcast** -- log message "Hello QMK!"
2022-05-22 19:55:17 +00:00
2021-08-11 11:08:32 +00:00
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Length | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload |
| **Value** | `0xFF` | `0xFF` | `0x00` | `0x0A`(10) | `0x48`(H) | `0x65`(e) | `0x6C`(l) | `0x6C`(l) | `0x6F`(o) | `0x20`( ) | `0x51`(Q) | `0x4D`(M) | `0x4B`(K) | `0x21`(!) |
'''
}
2022-04-05 17:54:28 +00:00
0x01: {
name: Secure Status
define: SECURE_STATUS
description:
'''
2022-05-22 19:55:17 +00:00
Secure status has changed. Payloads include a `u8` matching a 'Secure Status' request.
**Example Secure Status Broadcast** -- secure "Unlocking"
| Byte | 0 | 1 | 2 | 3 |
| --- | --- | --- | --- | --- |
| **Purpose** | Token | Token | Broadcast Type | Secure Status |
| **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
2022-04-05 17:54:28 +00:00
'''
return_type: u8
}
2022-06-23 23:04:08 +00:00
0x02: {
name: Keyboard
define: KB
description:
'''
Reserved for vendor-specific functionality. No messages are defined by XAP.
'''
},
0x03: {
name: User
define: USER
description:
'''
Reserved for user-specific functionality. No messages are defined by XAP.
'''
}
2021-08-11 11:08:32 +00:00
}
}
routes: {
0x00: {
routes: {
0x01: {
type: command
name: Capabilities Query
define: CAPABILITIES_QUERY
description:
'''
XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
'''
return_type: u32
return_purpose: capabilities
return_constant: XAP_ROUTE_XAP_CAPABILITIES
}
0x02: {
type: command
name: Enabled subsystem query
define: SUBSYSTEM_QUERY
description:
'''
XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.
'''
return_type: u32
return_purpose: capabilities
return_constant: XAP_ROUTE_CAPABILITIES
}
2022-03-31 00:18:26 +00:00
0x03: {
type: command
name: Secure Status
define: SECURE_STATUS
description:
'''
Query secure route status
* 0 means secure routes are disabled
* 1 means unlock sequence initiated but incomplete
* 2 means secure routes are allowed
* any other value should be interpreted as disabled
'''
return_type: u8
2022-04-10 23:43:18 +00:00
return_execute: secure_status
}
0x04: {
type: command
name: Secure Unlock
define: SECURE_UNLOCK
description: Initiate secure route unlock sequence
return_execute: secure_unlock
}
0x05: {
type: command
name: Secure Lock
define: SECURE_LOCK
description: Disable secure routes
return_execute: secure_lock
2022-03-31 00:18:26 +00:00
}
2021-08-11 11:08:32 +00:00
}
},
0x01: {
type: router
name: QMK
define: QMK
description:
'''
This subsystem is always present, and provides the ability to address QMK-specific functionality.
'''
routes: {
0x00: {
type: command
name: Version Query
define: VERSION_QUERY
description:
'''
QMK protocol version query.
* Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
* e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
'''
return_type: u32
return_purpose: bcd-version
return_constant: QMK_BCD_VERSION
}
0x01: {
type: command
name: Capabilities Query
define: CAPABILITIES_QUERY
description:
'''
QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
'''
return_type: u32
return_purpose: capabilities
return_constant: XAP_ROUTE_QMK_CAPABILITIES
}
0x02: {
type: command
name: Board identifiers
define: BOARD_IDENTIFIERS
description:
'''
Retrieves the set of identifying information for the board.
'''
return_type: struct
2022-04-19 02:33:56 +00:00
return_struct_length: 10
2021-08-11 11:08:32 +00:00
return_struct_members: [
{
type: u16
name: Vendor ID
},
{
type: u16
name: Product ID
},
{
type: u16
name: Product Version
},
{
type: u32
name: QMK Unique Identifier
}
]
return_constant: [
VENDOR_ID
PRODUCT_ID
DEVICE_VER
XAP_KEYBOARD_IDENTIFIER
]
}
0x03: {
type: command
name: Board Manufacturer
define: BOARD_MANUFACTURER
description: Retrieves the name of the manufacturer
return_type: string
return_constant: QSTR(MANUFACTURER)
}
0x04: {
type: command
name: Product Name
define: PRODUCT_NAME
description: Retrieves the product name
return_type: string
return_constant: QSTR(PRODUCT)
}
2022-03-28 20:06:11 +00:00
0x05: {
type: command
2022-06-19 21:04:30 +00:00
name: Config Blob Length
define: CONFIG_BLOB_LEN
description: Retrieves the length of the configuration data bundled within the firmware
2022-07-07 21:59:12 +00:00
return_type: u16
2022-06-19 21:04:30 +00:00
return_constant: CONFIG_BLOB_GZ_LEN
2022-03-28 20:06:11 +00:00
}
0x06: {
type: command
2022-06-19 21:04:30 +00:00
name: Config Blob Chunk
define: CONFIG_BLOB_CHUNK
description: Retrieves a chunk of the configuration data bundled within the firmware
2022-03-28 20:06:11 +00:00
request_type: u16
request_purpose: offset
return_type: u8[32]
2022-06-19 21:04:30 +00:00
return_execute: get_config_blob_chunk
2022-03-28 20:06:11 +00:00
}
2022-03-31 23:44:27 +00:00
0x07: {
type: command
name: Jump to bootloader
define: BOOTLOADER_JUMP
2022-04-12 00:37:25 +00:00
permissions: secure
2022-03-31 23:44:27 +00:00
enable_if_preprocessor: defined(BOOTLOADER_JUMP_SUPPORTED)
description:
'''
Jump to bootloader
2022-10-01 03:16:15 +00:00
May not be present - if QMK capabilities query returns “true”, then jump to bootloader is supported
2022-03-31 23:44:27 +00:00
* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader
'''
return_type: u8
return_execute: request_bootloader_jump
}
2022-04-18 23:04:22 +00:00
0x08: {
type: command
2022-06-23 23:04:08 +00:00
name: Hardware Identifier
2022-04-18 23:04:22 +00:00
define: HARDWARE_ID
description: Retrieves a unique identifier for the board.
return_type: u32[4]
return_execute: get_hardware_id
}
2022-10-01 03:16:15 +00:00
0x09: {
type: command
name: Reinitialize EEPROM
define: EEPROM_RESET
permissions: secure
enable_if_preprocessor: !defined(NO_RESET)
description:
'''
Reinitializes the keyboard's EEPROM (persistent memory)
May not be present - if QMK capabilities query returns “true”, then reinitialize is supported
* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will reinitialize and then reboot
'''
return_type: u8
return_execute: request_eeprom_reset
}
2021-08-11 11:08:32 +00:00
}
},
0x02: {
type: router
name: Keyboard
define: KB
description:
'''
2022-06-23 23:04:08 +00:00
This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
2021-08-11 11:08:32 +00:00
'''
routes: {
}
},
0x03: {
type: router
name: User
define: USER
description:
'''
This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
'''
routes: {
}
}
}
}
