1# CHPP Integration
2
3This guide focuses on integrating and porting CHPP to your desired platform. For implementation details please refer to the included README.md instead. The minimum typical steps are provided.
4
5## CHPP Transport Layer Integration
6
7### 1. Platform-specific functionality
8
9Implement the platform-specific functionality utilized by CHPP. These can be found in chpp/platform and include:
10
111. Memory allocation and deallocation
121. Thread notification mechanisms and thread signalling
131. Mutexes (or other resource sharing mechanism)
141. Condition variables
151. Logging (including defining CHPP_LOGx, CHPP_LOG_OOM, PRIuSIZE)
161. CRC32 (a half-byte algorithm is provided in platform/shared, but it is recommended to use a platform-optimized / hardware algorithm when available)
17
18Sample Linux implementations are provided.
19
20### 1. Link-Layer APIs
21
22The APIs that are needed to tie CHPP to the serial port are as follows. Details are provided in link.h.
23
241. void chppPlatformLinkInit(\*params)
251. void chppPlatformLinkDeinit(\*params)
261. void chppPlatformLinkReset(\*params)
271. enum ChppLinkErrorCode chppPlatformLinkSend(\*params, \*buf, len)
281. Depending on implementation, void chppLinkSendDoneCb(\*params)
291. void chppPlatformLinkDoWork(\*params)
301. bool chppRxDataCb(\*context, \*buf, len)
311. Optionally, chppRxPacketCompleteCb(\*context)
32
33In addition, the system must implement and initialize the platform-specific linkParams data structure as part of platform_link.h
34
35### 1. Initialization
36
37In order to initialize CHPP, it is necessary to
38
391. Allocate the transportContext and appContext structs that hold the state for each instance of the application and transport layers (in any order)
401. Call the layers’ initialization functions, chppTransportInit and chppAppInit (in any order)
411. Initialize the platform-specific linkParams struct (part of the transport struct)
421. Call chppWorkThreadStart to start the main thread for CHPP's Transport Layer
43
44### 1. Testing
45
46Several unit tests are provided in transport_test.c. In addition, loopback functionality is already implemented in CHPP, and can be used for testing. For details on crafting a loopback datagram, please refer to README.md and the transport layer unit tests (transport_test.c).
47
48### 1. Termination
49
50In order to terminate CHPP's main transport layer thread, it is necessary to
51
521. Call chppWorkThreadStop() to stop the main worker thread.
531. Call the layers’ deinitialization functions, chppTransportDeinit and chppAppDeinit (in any order)
541. Deallocate the transportContext, appContext, and the platform-specific linkParams structs
55
56### 1. Single-threaded systems
57
58If the system does not support multi-threading, the chppWorkThreadHandleSignal method can be used to directly handle signals without using chppWorkThreadStart.
59
60Note that the system MUST replicate the high-level behavior of chppWorkThreadStart exactly in this case. More details in the documentation of chppWorkThreadHandleSignal.
61
62For such systems, chppTransportGetTimeUntilNextDoWorkNs() can be used to replicate the functionality of chppNotifierTimedWait(). chppTransportGetTimeUntilNextDoWorkNs() returns the time until chppTransportDoWork() must be called again.
63
64## CHPP Services Integration
65
66CHPP provides several predefined services (including Loopback Test, Service Discovery), as well as three standard services that follow the CHRE PAL API to simplify integration and testing. CHPP allows for custom services as well, as described in README.md. The standard services included in CHPP are
67
681. WWAN
691. WiFi
701. GNSS
71
72In order to integrate the standard services using the CHRE PAL API, please refer to each service's interface as provided in include/chre/pal/
73