• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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`.