| # CHPP Release Notes |
| |
| A summary of notable changes is provided in the form of release notes. Dates are provided as yyyy-mm-dd. Note that this is not meant to be a detailed changelog; for a detailed change list, please refer to git commits. |
| |
| ### 2020-03-04 (4c668b3) |
| |
| Initial release of CHPP. |
| |
| - CHPP transport and app layers |
| - Loopback testing service |
| |
| ### 2020-07-28 (7cebe57) |
| |
| This release enables service integration with WWAN / WiFi / GNSS devices based on the CHRE PAL API. |
| |
| - New functionality |
| |
| - Reset and reset-ack implementation to allow either peer to initialize the other (e.g., upon boot) |
| - Discovery service to provide a list of services |
| - Discovery client to match clients with discovered services |
| - Standard WWAN service based on the CHRE PAL API |
| - Standard WiFi service based on the CHRE PAL API |
| - Standard GNSS service based on the CHRE PAL API |
| - Standard WWAN client based on the CHRE PAL API |
| |
| - Updates and bug fixes to existing layers, including |
| |
| - Better logging to assist verification and debugging |
| - Error replies are sent over the wire for transport layer errors |
| - Over-the-wire preamble has been corrected (byte shifting error) |
| |
| - API and integration changes |
| |
| - App layer header now includes an error code |
| - App layer message type now occupies only the least significant nibble (LSN). The most significant nibble (MSN) is reserved |
| - chppPlatformLinkSend() now returns an error code instead of a boolean |
| - Added initialization, deinitialization, and reset functionality for the link layer (see link.h) |
| - Condition variables functionality needs to be supported alongside other platform functionality (see chpp/platform/) |
| - Name changes for the logging APIs |
| |
| ### 2020-08-07 (0b41306) |
| |
| This release contains bug fixes as well as the loopback client. |
| |
| - New functionality |
| |
| - Loopback client to run and verify a loopback test using a provided data buffer |
| |
| - Cleanup and bug fixes |
| |
| - Corrected sequence number handling |
| - Updated log messages |
| - More accurate casting into enums |
| |
| ### 2020-08-27 (8ab5c23) |
| |
| This release contains additional clients, a virtual link layer for testing (e.g., using loopback), and several important bug fixes. |
| |
| - New functionality |
| |
| - Basic implementation of the standard WiFi client based on the CHRE PAL API |
| - Basic implementation of the standard GNSS client based on the CHRE PAL API |
| - Virtual link layer that connects CHPP with itself on Linux to enable testing, including reset, discovery, and loopback |
| |
| - Cleanup and bug fixes |
| |
| - Client implementation cleanup |
| - Client-side handling of close responses |
| - Reset / reset-ack handshaking mechanism fixed |
| - Loopback client fixed |
| - Enhanced log messages |
| - Service command #s are now sequential |
| |
| - API and integration changes |
| |
| - Platform-specific time functionality (platform_time.h) |
| |
| ### 2020-10-01 (95829e3) |
| |
| This release updates client functionality using the parser, adds a transport-layer loopback mechanism for testing and debugging, and includes several important bug fixes. |
| |
| - New functionality |
| |
| - Parser for CHPP -> CHRE Data Structure Decoding |
| - Completed client functionality using parser-generated functions |
| - Transport-layer-loopback client and service. The Transport-layer loopback ignores app layer functionality and state, as well as checksums and sequence numbers |
| |
| - Cleanup and bug fixes |
| |
| - Improved compiler compatibility for MSVC, as well as when enabling additional compiler warning flags |
| - Fixed handling of fragmented datagrams |
| - Corrected MTU calculation |
| - Corrected loopback assert |
| - Slimmer OOM logging |
| - Parser code and header files were relocated |
| |
| ### 2021-02-08 (f1d249c) |
| |
| In addition to enhancements and bug fixes, this release enables error and reset handling and several other features. |
| |
| - New functionality |
| |
| - ARQ implementation. Note that it is necessary to either implement chppNotifierTimedWait() or a single-threaded workaround as described in QUICKSTART.md to detect timeouts |
| - Checksum support via IEEE CRC-32. A sample implementation is provided, but it is expected that most devices have optimized implementations available or may prefer implementations with alternate optimization criteria |
| - Timesync functionality and timestamp offset correction for WiFi and WWAN measurements |
| - Reset handling throughout the transport layer, clients, and services, opening and recovering state as needed |
| - WiFi RTT client and service support |
| - Multiple loopback client support |
| - Transport-layer-loopback client validates response and returns the result |
| - Support for pseudo-opening services at the client, so they appear always available |
| - Correct responses generated at clients when async requests fail at services |
| |
| - Cleanup and bug fixes |
| |
| - Client and service fixes including length and bound checks, missing implementations |
| - Parser fixes including empty pointers set to null, compatibility with processors lacking unaligned access support |
| - Stability fixes throughout CHPP and tests |
| - Improved compiler compatibility for C99+ and pre-C99 systems (even though CHPP does not officially support pre-C99) |
| - Updated documentation and logging |
| |
| ### 2021-03-25 (f908420) |
| |
| This release updates the built-in timesync and checksum functionality and addresses bugs and compatibility issues. |
| |
| - Updated functionality |
| |
| - Timesync is redesigned to become non-blocking |
| - Outgoing checksums are enabled by default |
| - An updated sample CRC32 implementation is provided (It is still expected that devices that have existing, optimized implementations use their own) |
| - Client deinitialization and reset support |
| |
| - Cleanup and bug fixes |
| |
| - Logging updates, including reset reasoning, avoiding %s for compatibility |
| - Stability fixes and cleanup throughout CHPP and tests, including the reopening flow, permanent_failure state, and a memory leak |
| - Testing improvements |
| |
| ### 2021-05-24 (c9bfae3) |
| |
| This release enables better identification of end-of-packets as well as addressing bugs and compatibility issues. |
| |
| - Updated functionality |
| |
| - Rx timeout detection |
| - Rx MTU enforcement |
| - Support for Rx end-of-packet notifications from the link layer (optional, platform dependent) |
| |
| - Cleanup and bug fixes |
| |
| - Reset functionality cleanup, including updating the functionality of CHPP_TRANSPORT_MAX_RETX and CHPP_TRANSPORT_MAX_RESET to reflect their intent accurately |
| - Pseudo-open clients remain pseudo-open after open failures |
| - Fixed reopen failures after transport reset |
| - Added missing WiFi ranging service response |
| - Memory allocation and initialization improvements |
| - Mutex handling improvements |
| - Compatibility fixes |
| - Testing improvements |
| |
| ### 2021-06-17 (this) |
| |
| This release adds request timeout support at the client and addresses several bugs and compatibility issues throughout CHPP, including fixing open-state tracking at the service. Note that with the corrected open-state tracking, it is essential for services to correctly implement the close() PAL API so that it disables any ongoing requests and returns to a clean state. |
| |
| - Updated functionality |
| |
| - Client request timeout support |
| |
| - Cleanup and bug fixes |
| |
| - Service open-state tracking |
| - Memory handling fixes |
| - Added GNSS passive location listener service response |
| - Enforced error code requirements on service responses |
| - Fixed ARQ handling of duplicate packets |
| - Client request/response state refactoring |
| - Client registration cleanup |
| - Reset handling fixes |
| - Testing improvements |
| |
| ### 2023-01 |
| |
| Update CHPP to make it possible to use different link layers on the same platform. |
| |
| **Before:** |
| |
| The link layer API is defined by: |
| |
| - A few global functions: |
| - `chppPlatformLinkInit` |
| - `chppPlatformLinkDeinit` |
| - `chppPlatformLinkSend` |
| - `chppPlatformLinkDoWork` |
| - `chppPlatformLinkReset` |
| |
| - A few defines: |
| - `CHPP_PLATFORM_LINK_TX_MTU_BYTES` |
| - `CHPP_PLATFORM_LINK_RX_MTU_BYTES` |
| - `CHPP_PLATFORM_TRANSPORT_TIMEOUT_MS` |
| |
| **After:** |
| |
| In order to be able to use different link layers, the link layer API is now defined by |
| |
| - A `ChppLinkApi` API struct composed of pointers to the entry points: |
| - `init` |
| - `deinit` |
| - `send` |
| - `doWork` |
| - `reset` |
| - `getConfig` [added] |
| - `getTxBuffer` [added] |
| - A free form state, |
| - A `ChppLinkConfiguration` struct replacing the former defines. |
| |
| #### Migration |
| |
| You first need to create a `struct` holding the state of the link layer. |
| This state `struct` is free form but would usually contain: |
| - The TX buffer - it was owned by the transport layer in the previous version. |
| The TX buffer size must be added to the configuration `ChppLinkConfiguration` struct. |
| You can compute the size from your former `CHPP_PLATFORM_LINK_TX_MTU_BYTES`. |
| The formula to use is `min(CHPP_PLATFORM_LINK_TX_MTU_BYTES, 1024) + CHPP_TRANSPORT_ENCODING_OVERHEAD_BYTES`. |
| For example if your `CHPP_PLATFORM_LINK_TX_MTU_BYTES` was 2048, the TX buffer size should be `1024 + CHPP_TRANSPORT_ENCODING_OVERHEAD_BYTES`. |
| Note that 1024 (or whatever the value of the min is) is the effective payload. |
| The TX buffer will be slightly larger to accommodate the transport layer encoding overhead. |
| - A pointer to the transport layer state which is required for the transport layer callbacks |
| |
| You need to create an instance of `ChppLinkApi` with pointers to the link functions. |
| The API of the existing function have changed. They now take a `void *` pointer to the free form link state where they used to take a `struct ChppPlatformLinkParameters *`. You should cast that `void* linkContext` pointer to the type of your free form state. |
| |
| The `init` function now takes a second `struct ChppTransportState *transportContext` parameter. That function should store it in the state as it will be needed later to callback into the transport layer. The `init` function might store the `ChppLinkConfiguration` configuration in the state (if the configuration varies across link layer instances). |
| |
| The `send` function does not take a pointer to the TX buffer (`uint8_t *buf`) any more. That's because this buffer is now owned by the link layer and part of the link state. |
| |
| The added `getConfig` function returns the configuration `ChppLinkConfiguration` struct. The configuration might be shared across link instances or specific to a given instance. |
| |
| The added `getTxBuffer` function returns a pointer to the TX buffer that is part in the state. |
| |
| Then you need to create the `ChppLinkConfiguration` struct. It contains the size of TX buffer, the size of the RX buffer. Those are equivalent to the former defines. Note that `CHPP_PLATFORM_TRANSPORT_TIMEOUT_MS` was not used and has been deleted. |
| |
| Other changes: |
| |
| - You need to pass the link state and the link `ChppLinkApi` struct when initializing the transport layer with `chppTransportInit`. |
| - When calling the `chppLinkSendDoneCb` and `chppWorkThreadSignalFromLink` from the link layer the first parameter should now be a pointer to the transport layer. You would typically retrieve that pointer from the link state where you should have stored it in the `init` function. |
| |
| ### 2023-03 |
| |
| The `chppRegisterService` signature changes from |
| |
| ``` |
| uint8_t chppRegisterService(struct ChppAppState *appContext, |
| void *serviceContext, |
| const struct ChppService *newService); |
| ``` |
| |
| to |
| |
| ``` |
| void chppRegisterService(struct ChppAppState *appContext, void *serviceContext, |
| struct ChppServiceState *serviceState, |
| const struct ChppService *newService); |
| ``` |
| |
| The handle which used to be returned is now populated in `serviceState`. |
| `service->appContext` is also initialized to the passed `appContext`. |
| |
| This change makes the signature and behavior consistent with `chreRegisterClient`. |
| |
| ### 2023-08 |
| |
| Services can now send requests and receive responses from clients. |
| |
| The changes to the public API of the different layers are described below. |
| Check the inline documentation for more information. |
| |
| **Breaking changes** |
| |
| - `ChppClientState` and `ChppServiceState` have been unified into `ChppEndpointState`. |
| |
| #### app.c / app.h |
| |
| **Breaking changes** |
| |
| - Move all sync primitives to a new `struct ChppSyncResponse`, |
| - Renamed `ChppClient.rRStateCount` to `ChppClient.outReqCount`. The content and meaning stay the same, |
| - Split `struct ChppRequestResponseState` to `struct ChppOutgoingRequestState` and `struct ChppIncomingRequestState`. Both the struct have the same layout and usage as the former `struct`. Having different types is only to make code clearer as both clients and services now support both incoming and outgoing requests, |
| - Renamed `ChppAppState.nextClientRequestTimeoutNs` to `ChppAppState.nextRequestTimeoutNs`. The content and meaning stay the same, |
| - Renamed `CHPP_CLIENT_REQUEST_TIMEOUT_INFINITE` to `CHPP_REQUEST_TIMEOUT_INFINITE`. |
| |
| **Added APIs** |
| |
| - Added `chppAllocResponseTypedArray` and `chppAllocResponseFixed` to allocate responses. Those can be used by both clients and services. They call the added `chppAllocResponse`, |
| - Added `CHPP_MESSAGE_TYPE_SERVICE_REQUEST` and `CHPP_MESSAGE_TYPE_CLIENT_RESPONSE` to the message types (`ChppMessageType`). Used for requests sent by the services and the corresponding responses sent by the client, |
| - Added `ChppService.responseDispatchFunctionPtr` to handle client responses, |
| - Added `ChppService.outReqCount` holding the number of commands supported by the service (0 when the service can not send requests), |
| - Added `ChppClient.requestDispatchFunctionPtr` to handle service requests, |
| - Added `ChppAppState.registeredServiceStates` to track service states, |
| - Added `ChppAppState.nextServiceRequestTimeoutNs` to track when the next service sent request will timeout, |
| - Added `chppTimestampIncomingRequest` to be used by both clients and services, |
| - Added `chppTimestampOutgoingRequest` to be used by both clients and services, |
| - Added `chppTimestampIncomingResponse` to be used by both clients and services, |
| - Added `chppTimestampOutgoingResponse` to be used by both clients and services, |
| - Added `chppSendTimestampedResponseOrFail` to be used by both clients and services, |
| - Added `chppSendTimestampedRequestOrFail` to be used by both clients and services, |
| - Added `chppWaitForResponseWithTimeout` to be used by both clients and services. |
| |
| #### clients.c / clients.h |
| |
| **Breaking changes** |
| |
| - Renamed `ChppClientState.rRStates` to `outReqStates` - the new type is `ChppOutgoingRequestState`. The content and meaning stay the same, |
| - Nest all sync primitive in `ChppClientState` into a `struct ChppSyncResponse syncResponse`, |
| - `chppRegisterClient` takes a `ChppOutgoingRequestState` instead of the former `ChppRequestResponseState`, |
| - `chppClientTimestampRequest` is replaced with `chppTimestampOutgoingRequest` in the app layer. Parameters are different, |
| - `chppClientTimestampResponse` is replaced with `chppTimestampIncomingResponse` in the app layer. Parameters are different, |
| - `chppSendTimestampedRequestOrFail` is renamed to `chppClientSendTimestampedRequestOrFail`. It takes a `ChppOutgoingRequestState` instead of the former `ChppRequestResponseState`, |
| - `chppSendTimestampedRequestAndWait` is renamed to `chppClientSendTimestampedRequestAndWait`. It takes a `ChppOutgoingRequestState` instead of the former `ChppRequestResponseState`, |
| - `chppSendTimestampedRequestAndWaitTimeout` is renamed to `chppClientSendTimestampedRequestAndWaitTimeout`. It takes a `ChppOutgoingRequestState` instead of the former `ChppRequestResponseState`, |
| - `chppClientSendOpenRequest` takes a `ChppOutgoingRequestState` instead of the former `ChppRequestResponseState`. |
| |
| #### services.c / services.h |
| |
| **Breaking changes** |
| |
| - Replaced `chppAllocServiceResponseTypedArray` with `chppAllocResponseTypedArray` in the app layer, |
| - Replaced `chppAllocServiceResponseFixed` with `chppAllocResponseFixed` in the app layer, |
| - Replaced `chppAllocServiceResponse` with `chppAllocResponse` in the app layer, |
| - `chppRegisterService` now takes and additional `struct ChppOutgoingRequestState *` to track outgoing requests. `NULL` when the service do not send requests. |
| |
| **Added APIs** |
| |
| - Added `chppAllocServiceRequestFixed` and `chppAllocServiceRequestTypedArray` to allocate service requests. They call the added `chppAllocServiceRequest`, |
| - Added `ChppServiceState.outReqStates` to track outgoing requests, |
| - Added `ChppServiceState.transaction` to track app layer packet number, |
| - Added `ChppServiceState.syncResponse` for sync responses, |
| - Added `chppAllocServiceRequest`, |
| - Added `chppAllocServiceRequestCommand`, |
| - Added `chppServiceSendTimestampedRequestOrFail`, |
| - Added `chppServiceSendTimestampedRequestAndWaitTimeout`, |
| - Added `chppServiceCloseOpenRequests` to close pending requests on reset. |
