From d95d22201a66c239a038cc88ccf1c798ca586c91 Mon Sep 17 00:00:00 2001 From: zvecr Date: Sun, 22 May 2022 21:12:32 +0100 Subject: [PATCH] multiline description? --- data/templates/xap/docs/routes.md.j2 | 6 +-- data/xap/xap_0.2.0.hjson | 2 + docs/xap_0.0.1.md | 6 +-- docs/xap_0.1.0.md | 38 ++++++++-------- docs/xap_0.2.0.md | 66 ++++++++++++++-------------- 5 files changed, 60 insertions(+), 58 deletions(-) diff --git a/data/templates/xap/docs/routes.md.j2 b/data/templates/xap/docs/routes.md.j2 index 6b27f967755..c740ae2f5e1 100644 --- a/data/templates/xap/docs/routes.md.j2 +++ b/data/templates/xap/docs/routes.md.j2 @@ -3,10 +3,10 @@ {{ route.description }} {% if route.routes %} -| Name | Route | Definition | -| -- | -- | -- | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | {%- for subid, subroute in route.routes | dictsort %} -| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure unlock required__ {% endif %}{{ subroute.description.split('\n')[0] }} | +| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {{ subroute.description.replace('\n', '
') }} | {%- endfor %} {% endif %} {%- endfor %} diff --git a/data/xap/xap_0.2.0.hjson b/data/xap/xap_0.2.0.hjson index 6fd98531482..822e5190a08 100755 --- a/data/xap/xap_0.2.0.hjson +++ b/data/xap/xap_0.2.0.hjson @@ -61,6 +61,7 @@ name: Set Keycode define: SET_KEYMAP_KEYCODE description: TODO + permissions: secure request_type: struct request_struct_length: 5 request_struct_members: [ @@ -136,6 +137,7 @@ type: command name: Set Keycode define: SET_ENCODER_KEYCODE + permissions: secure description: TODO request_type: struct request_struct_length: 5 diff --git a/docs/xap_0.0.1.md b/docs/xap_0.0.1.md index e8d165ef10e..20e6115a7cf 100644 --- a/docs/xap_0.0.1.md +++ b/docs/xap_0.0.1.md @@ -75,8 +75,8 @@ This is the primary method for determining if a subsystem has been enabled in th This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device. -| Name | Route | Definition | -| -- | -- | -- | -| Version Query | `0x00 0x00` | XAP protocol version query. | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Version Query | `0x00 0x00` | | XAP 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}.
* Response:
* `u32` value. | diff --git a/docs/xap_0.1.0.md b/docs/xap_0.1.0.md index 4ce1deb43ba..de21009a9cc 100644 --- a/docs/xap_0.1.0.md +++ b/docs/xap_0.1.0.md @@ -88,30 +88,30 @@ This is the primary method for determining if a subsystem has been enabled in th This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device. -| Name | Route | Definition | -| -- | -- | -- | -| Version Query | `0x00 0x00` | XAP protocol version query. | -| Capabilities Query | `0x00 0x01` | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | -| Enabled subsystem query | `0x00 0x02` | 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. | -| Secure Status | `0x00 0x03` | Query secure route status | -| Secure Unlock | `0x00 0x04` | Initiate secure route unlock sequence | -| Secure Lock | `0x00 0x05` | Disable secure routes | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Version Query | `0x00 0x00` | | XAP 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}.
* Response:
* `u32` value. | +| Capabilities Query | `0x00 0x01` | | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Enabled subsystem query | `0x00 0x02` | | 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. | +| Secure Status | `0x00 0x03` | | 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 | +| Secure Unlock | `0x00 0x04` | | Initiate secure route unlock sequence | +| Secure Lock | `0x00 0x05` | | Disable secure routes | ### QMK - `0x01` This subsystem is always present, and provides the ability to address QMK-specific functionality. -| Name | Route | Definition | -| -- | -- | -- | -| Version Query | `0x01 0x00` | QMK protocol version query. | -| Capabilities Query | `0x01 0x01` | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | -| Board identifiers | `0x01 0x02` | Retrieves the set of identifying information for the board. | -| Board Manufacturer | `0x01 0x03` | Retrieves the name of the manufacturer | -| Product Name | `0x01 0x04` | Retrieves the product name | -| info.json length | `0x01 0x05` | Retrieves the length of info.json | -| info.json | `0x01 0x06` | Retrieves a chunk of info.json | -| Jump to bootloader | `0x01 0x07` | __Secure unlock required__ Jump to bootloader | -| info.json | `0x01 0x08` | Retrieves a unique identifier for the board. | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Version Query | `0x01 0x00` | | 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}.
* Response:
* `u32` value. | +| Capabilities Query | `0x01 0x01` | | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Board identifiers | `0x01 0x02` | | Retrieves the set of identifying information for the board. | +| Board Manufacturer | `0x01 0x03` | | Retrieves the name of the manufacturer | +| Product Name | `0x01 0x04` | | Retrieves the product name | +| info.json length | `0x01 0x05` | | Retrieves the length of info.json | +| info.json | `0x01 0x06` | | Retrieves a chunk of info.json | +| Jump to bootloader | `0x01 0x07` | __Secure__ | Jump to bootloader

May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported

* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader | +| info.json | `0x01 0x08` | | Retrieves a unique identifier for the board. | ### Keyboard - `0x02` This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP. diff --git a/docs/xap_0.2.0.md b/docs/xap_0.2.0.md index e48d1a32315..fc8afa4ebf3 100644 --- a/docs/xap_0.2.0.md +++ b/docs/xap_0.2.0.md @@ -88,30 +88,30 @@ This is the primary method for determining if a subsystem has been enabled in th This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device. -| Name | Route | Definition | -| -- | -- | -- | -| Version Query | `0x00 0x00` | XAP protocol version query. | -| Capabilities Query | `0x00 0x01` | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | -| Enabled subsystem query | `0x00 0x02` | 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. | -| Secure Status | `0x00 0x03` | Query secure route status | -| Secure Unlock | `0x00 0x04` | Initiate secure route unlock sequence | -| Secure Lock | `0x00 0x05` | Disable secure routes | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Version Query | `0x00 0x00` | | XAP 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}.
* Response:
* `u32` value. | +| Capabilities Query | `0x00 0x01` | | XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Enabled subsystem query | `0x00 0x02` | | 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. | +| Secure Status | `0x00 0x03` | | 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 | +| Secure Unlock | `0x00 0x04` | | Initiate secure route unlock sequence | +| Secure Lock | `0x00 0x05` | | Disable secure routes | ### QMK - `0x01` This subsystem is always present, and provides the ability to address QMK-specific functionality. -| Name | Route | Definition | -| -- | -- | -- | -| Version Query | `0x01 0x00` | QMK protocol version query. | -| Capabilities Query | `0x01 0x01` | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | -| Board identifiers | `0x01 0x02` | Retrieves the set of identifying information for the board. | -| Board Manufacturer | `0x01 0x03` | Retrieves the name of the manufacturer | -| Product Name | `0x01 0x04` | Retrieves the product name | -| info.json length | `0x01 0x05` | Retrieves the length of info.json | -| info.json | `0x01 0x06` | Retrieves a chunk of info.json | -| Jump to bootloader | `0x01 0x07` | __Secure unlock required__ Jump to bootloader | -| info.json | `0x01 0x08` | Retrieves a unique identifier for the board. | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Version Query | `0x01 0x00` | | 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}.
* Response:
* `u32` value. | +| Capabilities Query | `0x01 0x01` | | QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Board identifiers | `0x01 0x02` | | Retrieves the set of identifying information for the board. | +| Board Manufacturer | `0x01 0x03` | | Retrieves the name of the manufacturer | +| Product Name | `0x01 0x04` | | Retrieves the product name | +| info.json length | `0x01 0x05` | | Retrieves the length of info.json | +| info.json | `0x01 0x06` | | Retrieves a chunk of info.json | +| Jump to bootloader | `0x01 0x07` | __Secure__ | Jump to bootloader

May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported

* 0 means secure routes are disabled, and should be considered as a failure
* 1 means successful, board will jump to bootloader | +| info.json | `0x01 0x08` | | Retrieves a unique identifier for the board. | ### Keyboard - `0x02` This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP. @@ -125,30 +125,30 @@ This subsystem is always present, and reserved for user-specific functionality. This subsystem allows for live modifications of the keymap, allowing keys to be reassigned without rebuilding the firmware. -| Name | Route | Definition | -| -- | -- | -- | -| Capabilities Query | `0x04 0x00` | Dynamic Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | -| Get Layer Count | `0x04 0x01` | TODO | -| Get Keycode | `0x04 0x02` | TODO | -| Set Keycode | `0x04 0x03` | TODO | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Capabilities Query | `0x04 0x00` | | Dynamic Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Get Layer Count | `0x04 0x01` | | TODO | +| Get Keycode | `0x04 0x02` | | TODO | +| Set Keycode | `0x04 0x03` | __Secure__ | TODO | ### Dynamic Encoders - `0x05` This subsystem allows for live modifications of the keymap, allowing encoder functionality to be reassigned without rebuilding the firmware. -| Name | Route | Definition | -| -- | -- | -- | -| Capabilities Query | `0x05 0x00` | Dynamic Encoders subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | -| Get Keycode | `0x05 0x02` | TODO | -| Set Keycode | `0x05 0x03` | TODO | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Capabilities Query | `0x05 0x00` | | Dynamic Encoders subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Get Keycode | `0x05 0x02` | | TODO | +| Set Keycode | `0x05 0x03` | __Secure__ | TODO | ### Lighting - `0x06` This subsystem allows for control over the lighting subsystem. -| Name | Route | Definition | -| -- | -- | -- | -| Capabilities Query | `0x06 0x00` | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | +| Name | Route | Tags | Definition | +| -- | -- | -- | -- | +| Capabilities Query | `0x06 0x00` | | Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem. | ## Broadcast messages