1# CHPP Release Notes 2 3A 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. 4 5### 2020-03-04 (4c668b3) 6 7Initial release of CHPP. 8 9- CHPP transport and app layers 10- Loopback testing service 11 12### 2020-07-28 (7cebe57) 13 14This release enables service integration with WWAN / WiFi / GNSS devices based on the CHRE PAL API. 15 16- New functionality 17 18 - Reset and reset-ack implementation to allow either peer to initialize the other (e.g., upon boot) 19 - Discovery service to provide a list of services 20 - Discovery client to match clients with discovered services 21 - Standard WWAN service based on the CHRE PAL API 22 - Standard WiFi service based on the CHRE PAL API 23 - Standard GNSS service based on the CHRE PAL API 24 - Standard WWAN client based on the CHRE PAL API 25 26- Updates and bug fixes to existing layers, including 27 28 - Better logging to assist verification and debugging 29 - Error replies are sent over the wire for transport layer errors 30 - Over-the-wire preamble has been corrected (byte shifting error) 31 32- API and integration changes 33 34 - App layer header now includes an error code 35 - App layer message type now occupies only the least significant nibble (LSN). The most significant nibble (MSN) is reserved 36 - chppPlatformLinkSend() now returns an error code instead of a boolean 37 - Added initialization, deinitialization, and reset functionality for the link layer (see link.h) 38 - Condition variables functionality needs to be supported alongside other platform functionality (see chpp/platform/) 39 - Name changes for the logging APIs 40 41### 2020-08-07 (0b41306) 42 43This release contains bug fixes as well as the loopback client. 44 45- New functionality 46 47 - Loopback client to run and verify a loopback test using a provided data buffer 48 49- Cleanup and bug fixes 50 51 - Corrected sequence number handling 52 - Updated log messages 53 - More accurate casting into enums 54 55### 2020-08-27 (8ab5c23) 56 57This release contains additional clients, a virtual link layer for testing (e.g., using loopback), and several important bug fixes. 58 59- New functionality 60 61 - Basic implementation of the standard WiFi client based on the CHRE PAL API 62 - Basic implementation of the standard GNSS client based on the CHRE PAL API 63 - Virtual link layer that connects CHPP with itself on Linux to enable testing, including reset, discovery, and loopback 64 65- Cleanup and bug fixes 66 67 - Client implementation cleanup 68 - Client-side handling of close responses 69 - Reset / reset-ack handshaking mechanism fixed 70 - Loopback client fixed 71 - Enhanced log messages 72 - Service command #s are now sequential 73 74- API and integration changes 75 76 - Platform-specific time functionality (platform_time.h) 77 78### 2020-10-01 (95829e3) 79 80This release updates client functionality using the parser, adds a transport-layer loopback mechanism for testing and debugging, and includes several important bug fixes. 81 82- New functionality 83 84 - Parser for CHPP -> CHRE Data Structure Decoding 85 - Completed client functionality using parser-generated functions 86 - Transport-layer-loopback client and service. The Transport-layer loopback ignores app layer functionality and state, as well as checksums and sequence numbers 87 88- Cleanup and bug fixes 89 90 - Improved compiler compatibility for MSVC, as well as when enabling additional compiler warning flags 91 - Fixed handling of fragmented datagrams 92 - Corrected MTU calculation 93 - Corrected loopback assert 94 - Slimmer OOM logging 95 - Parser code and header files were relocated 96 97### 2021-02-08 (f1d249c) 98 99In addition to enhancements and bug fixes, this release enables error and reset handling and several other features. 100 101- New functionality 102 103 - ARQ implementation. Note that it is necessary to either implement chppNotifierTimedWait() or a single-threaded workaround as described in QUICKSTART.md to detect timeouts 104 - 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 105 - Timesync functionality and timestamp offset correction for WiFi and WWAN measurements 106 - Reset handling throughout the transport layer, clients, and services, opening and recovering state as needed 107 - WiFi RTT client and service support 108 - Multiple loopback client support 109 - Transport-layer-loopback client validates response and returns the result 110 - Support for pseudo-opening services at the client, so they appear always available 111 - Correct responses generated at clients when async requests fail at services 112 113- Cleanup and bug fixes 114 115 - Client and service fixes including length and bound checks, missing implementations 116 - Parser fixes including empty pointers set to null, compatibility with processors lacking unaligned access support 117 - Stability fixes throughout CHPP and tests 118 - Improved compiler compatibility for C99+ and pre-C99 systems (even though CHPP does not officially support pre-C99) 119 - Updated documentation and logging 120 121### 2021-03-25 (f908420) 122 123This release updates the built-in timesync and checksum functionality and addresses bugs and compatibility issues. 124 125- Updated functionality 126 127 - Timesync is redesigned to become non-blocking 128 - Outgoing checksums are enabled by default 129 - An updated sample CRC32 implementation is provided (It is still expected that devices that have existing, optimized implementations use their own) 130 - Client deinitialization and reset support 131 132- Cleanup and bug fixes 133 134 - Logging updates, including reset reasoning, avoiding %s for compatibility 135 - Stability fixes and cleanup throughout CHPP and tests, including the reopening flow, permanent_failure state, and a memory leak 136 - Testing improvements 137 138### 2021-05-24 (c9bfae3) 139 140This release enables better identification of end-of-packets as well as addressing bugs and compatibility issues. 141 142- Updated functionality 143 144 - Rx timeout detection 145 - Rx MTU enforcement 146 - Support for Rx end-of-packet notifications from the link layer (optional, platform dependent) 147 148- Cleanup and bug fixes 149 150 - Reset functionality cleanup, including updating the functionality of CHPP_TRANSPORT_MAX_RETX and CHPP_TRANSPORT_MAX_RESET to reflect their intent accurately 151 - Pseudo-open clients remain pseudo-open after open failures 152 - Fixed reopen failures after transport reset 153 - Added missing WiFi ranging service response 154 - Memory allocation and initialization improvements 155 - Mutex handling improvements 156 - Compatibility fixes 157 - Testing improvements 158 159### 2021-06-17 (this) 160 161This 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. 162 163- Updated functionality 164 165 - Client request timeout support 166 167- Cleanup and bug fixes 168 169 - Service open-state tracking 170 - Memory handling fixes 171 - Added GNSS passive location listener service response 172 - Enforced error code requirements on service responses 173 - Fixed ARQ handling of duplicate packets 174 - Client request/response state refactoring 175 - Client registration cleanup 176 - Reset handling fixes 177 - Testing improvements 178 179### 2023-01 180 181Update CHPP to make it possible to use different link layers on the same platform. 182 183**Before:** 184 185The link layer API is defined by: 186 187- A few global functions: 188 - `chppPlatformLinkInit` 189 - `chppPlatformLinkDeinit` 190 - `chppPlatformLinkSend` 191 - `chppPlatformLinkDoWork` 192 - `chppPlatformLinkReset` 193 194- A few defines: 195 - `CHPP_PLATFORM_LINK_TX_MTU_BYTES` 196 - `CHPP_PLATFORM_LINK_RX_MTU_BYTES` 197 - `CHPP_PLATFORM_TRANSPORT_TIMEOUT_MS` 198 199**After:** 200 201In order to be able to use different link layers, the link layer API is now defined by 202 203- A `ChppLinkApi` API struct composed of pointers to the entry points: 204 - `init` 205 - `deinit` 206 - `send` 207 - `doWork` 208 - `reset` 209 - `getConfig` [added] 210 - `getTxBuffer` [added] 211- A free form state, 212- A `ChppLinkConfiguration` struct replacing the former defines. 213 214#### Migration 215 216You first need to create a `struct` holding the state of the link layer. 217This state `struct` is free form but would usually contain: 218- The TX buffer - it was owned by the transport layer in the previous version. 219 The TX buffer size must be added to the configuration `ChppLinkConfiguration` struct. 220 You can compute the size from your former `CHPP_PLATFORM_LINK_TX_MTU_BYTES`. 221 The formula to use is `min(CHPP_PLATFORM_LINK_TX_MTU_BYTES, 1024) + CHPP_TRANSPORT_ENCODING_OVERHEAD_BYTES`. 222 For example if your `CHPP_PLATFORM_LINK_TX_MTU_BYTES` was 2048, the TX buffer size should be `1024 + CHPP_TRANSPORT_ENCODING_OVERHEAD_BYTES`. 223 Note that 1024 (or whatever the value of the min is) is the effective payload. 224 The TX buffer will be slightly larger to accommodate the transport layer encoding overhead. 225- A pointer to the transport layer state which is required for the transport layer callbacks 226 227You need to create an instance of `ChppLinkApi` with pointers to the link functions. 228The 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. 229 230The `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). 231 232The `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. 233 234The added `getConfig` function returns the configuration `ChppLinkConfiguration` struct. The configuration might be shared across link instances or specific to a given instance. 235 236The added `getTxBuffer` function returns a pointer to the TX buffer that is part in the state. 237 238Then 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. 239 240Other changes: 241 242- You need to pass the link state and the link `ChppLinkApi` struct when initializing the transport layer with `chppTransportInit`. 243- 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. 244 245### 2023-03 246 247The `chppRegisterService` signature changes from 248 249``` 250uint8_t chppRegisterService(struct ChppAppState *appContext, 251 void *serviceContext, 252 const struct ChppService *newService); 253``` 254 255to 256 257``` 258void chppRegisterService(struct ChppAppState *appContext, void *serviceContext, 259 struct ChppServiceState *serviceState, 260 const struct ChppService *newService); 261``` 262 263The handle which used to be returned is now populated in `serviceState`. 264`service->appContext` is also initialized to the passed `appContext`. 265 266This change makes the signature and behavior consistent with `chreRegisterClient`.