From 6ec0ff387b0a4ca92941f4ad4cf75fb00ddda329 Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 7 Jul 2022 00:57:59 +0100 Subject: [PATCH] Update reserved tokens --- data/xap/xap_0.0.1.hjson | 7 +++++-- data/xap/xap_0.1.0.hjson | 4 ++-- docs/xap_0.0.1.md | 7 +++++-- docs/xap_0.1.0.md | 11 +++++++---- docs/xap_0.2.0.md | 11 +++++++---- lib/python/qmk/cli/xap/xap_client.py | 4 ++-- 6 files changed, 28 insertions(+), 16 deletions(-) diff --git a/data/xap/xap_0.0.1.hjson b/data/xap/xap_0.0.1.hjson index 2b6def0ff1..aa34d7828d 100755 --- a/data/xap/xap_0.0.1.hjson +++ b/data/xap/xap_0.0.1.hjson @@ -48,7 +48,10 @@ Communication generally follows a request/response pattern. - Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response, allowing response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. + Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response. + This allows response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. + Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. + To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`. This token is followed by a `u8` signifying the length of data in the request. ''' @@ -146,7 +149,7 @@ token: { name: Token - description: A `u16` associated with a specific request as well as its corresponding response. + description: A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. type: u16 } diff --git a/data/xap/xap_0.1.0.hjson b/data/xap/xap_0.1.0.hjson index 71023f9ac4..75beb98e89 100755 --- a/data/xap/xap_0.1.0.hjson +++ b/data/xap/xap_0.1.0.hjson @@ -13,8 +13,8 @@ reserved_tokens: ''' - Two token values are reserved: `0x0000` and `0xFFFF`: - * `0x0000`: A message sent by a host application may use this token if no response is to be sent -- a "fire and forget" message. + 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. * `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. diff --git a/docs/xap_0.0.1.md b/docs/xap_0.0.1.md index 004d84cbb0..410a2d9d32 100644 --- a/docs/xap_0.0.1.md +++ b/docs/xap_0.0.1.md @@ -28,13 +28,16 @@ This list defines the terms used across the entire set of XAP protocol documenta | _Request Header_ | Packet format for inbound data. Takes the format:
`token` - token
`u8` - length | | _Response Flags_ | An `u8` containing the status of the request. | | _Response Header_ | Packet format for outbound data. Takes the format:
`token` - token
`response_flags` - flags
`u8` - length | -| _Token_ | A `u16` associated with a specific request as well as its corresponding response. | +| _Token_ | A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. | ## Requests and Responses Communication generally follows a request/response pattern. -Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response, allowing response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. +Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response. +This allows response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. +Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. +To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`. This token is followed by a `u8` signifying the length of data in the request. diff --git a/docs/xap_0.1.0.md b/docs/xap_0.1.0.md index 5eb294729f..bdfd62df34 100644 --- a/docs/xap_0.1.0.md +++ b/docs/xap_0.1.0.md @@ -34,18 +34,21 @@ This list defines the terms used across the entire set of XAP protocol documenta | _Request Header_ | Packet format for inbound data. Takes the format:
`token` - token
`u8` - length | | _Response Flags_ | An `u8` containing the status of the request. | | _Response Header_ | Packet format for outbound data. Takes the format:
`token` - token
`response_flags` - flags
`u8` - length | -| _Token_ | A `u16` associated with a specific request as well as its corresponding response. | +| _Token_ | A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. | ## Requests and Responses Communication generally follows a request/response pattern. -Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response, allowing response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. +Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response. +This allows response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. +Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. +To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`. This token is followed by a `u8` signifying the length of data in the request. -Two token values are reserved: `0x0000` and `0xFFFF`: -* `0x0000`: A message sent by a host application may use this token if no response is to be sent -- a "fire and forget" message. +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. * `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. diff --git a/docs/xap_0.2.0.md b/docs/xap_0.2.0.md index bddc427f1a..1b3bedc7fc 100644 --- a/docs/xap_0.2.0.md +++ b/docs/xap_0.2.0.md @@ -34,18 +34,21 @@ This list defines the terms used across the entire set of XAP protocol documenta | _Request Header_ | Packet format for inbound data. Takes the format:
`token` - token
`u8` - length | | _Response Flags_ | An `u8` containing the status of the request. | | _Response Header_ | Packet format for outbound data. Takes the format:
`token` - token
`response_flags` - flags
`u8` - length | -| _Token_ | A `u16` associated with a specific request as well as its corresponding response. | +| _Token_ | A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`. | ## Requests and Responses Communication generally follows a request/response pattern. -Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response, allowing response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. +Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response. +This allows response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously. +Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below. +To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`. This token is followed by a `u8` signifying the length of data in the request. -Two token values are reserved: `0x0000` and `0xFFFF`: -* `0x0000`: A message sent by a host application may use this token if no response is to be sent -- a "fire and forget" message. +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. * `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. diff --git a/lib/python/qmk/cli/xap/xap_client.py b/lib/python/qmk/cli/xap/xap_client.py index c7803b687f..a7e47645e6 100644 --- a/lib/python/qmk/cli/xap/xap_client.py +++ b/lib/python/qmk/cli/xap/xap_client.py @@ -18,9 +18,9 @@ ResponseStruct = Struct('H', token))[0]