1 /*
2  * Copyright Runtime.io 2018. All rights reserved.
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef ZEPHYR_INCLUDE_MGMT_SERIAL_H_
8 #define ZEPHYR_INCLUDE_MGMT_SERIAL_H_
9 
10 #include <zephyr/types.h>
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 #define MCUMGR_SERIAL_HDR_PKT       0x0609
17 #define MCUMGR_SERIAL_HDR_FRAG      0x0414
18 #define MCUMGR_SERIAL_MAX_FRAME     127
19 
20 #define MCUMGR_SERIAL_HDR_PKT_1     (MCUMGR_SERIAL_HDR_PKT >> 8)
21 #define MCUMGR_SERIAL_HDR_PKT_2     (MCUMGR_SERIAL_HDR_PKT & 0xff)
22 #define MCUMGR_SERIAL_HDR_FRAG_1    (MCUMGR_SERIAL_HDR_FRAG >> 8)
23 #define MCUMGR_SERIAL_HDR_FRAG_2    (MCUMGR_SERIAL_HDR_FRAG & 0xff)
24 
25 /**
26  * @brief Maintains state for an incoming mcumgr request packet.
27  */
28 struct mcumgr_serial_rx_ctxt {
29 	/* Contains the partially- or fully-received mcumgr request.  Data
30 	 * stored in this buffer has already been base64-decoded.
31 	 */
32 	struct net_buf *nb;
33 
34 	/* Length of full packet, as read from header. */
35 	uint16_t pkt_len;
36 };
37 
38 /** @typedef mcumgr_serial_tx_cb
39  * @brief Transmits a chunk of raw response data.
40  *
41  * @param data                  The data to transmit.
42  * @param len                   The number of bytes to transmit.
43  *
44  * @return                      0 on success; negative error code on failure.
45  */
46 typedef int (*mcumgr_serial_tx_cb)(const void *data, int len);
47 
48 /**
49  * @brief Processes an mcumgr request fragment received over a serial
50  *        transport.
51  *
52  * Processes an mcumgr request fragment received over a serial transport.  If
53  * the fragment is the end of a valid mcumgr request, this function returns a
54  * net_buf containing the decoded request.  It is the caller's responsibility
55  * to free the net_buf after it has been processed.
56  *
57  * @param rx_ctxt               The receive context associated with the serial
58  *                                  transport being used.
59  * @param frag                  The incoming fragment to process.
60  * @param frag_len              The length of the fragment, in bytes.
61  *
62  * @return                      A net_buf containing the decoded request if a
63  *                                  complete and valid request has been
64  *                                  received.
65  *                              NULL if the packet is incomplete or invalid.
66  */
67 struct net_buf *mcumgr_serial_process_frag(
68 	struct mcumgr_serial_rx_ctxt *rx_ctxt,
69 	const uint8_t *frag, int frag_len);
70 
71 /**
72  * @brief Encodes and transmits an mcumgr packet over serial.
73  *
74  * @param data                  The mcumgr packet data to send.
75  * @param len                   The length of the unencoded mcumgr packet.
76  * @param cb                    A callback used to transmit raw bytes.
77  *
78  * @return                      0 on success; negative error code on failure.
79  */
80 int mcumgr_serial_tx_pkt(const uint8_t *data, int len, mcumgr_serial_tx_cb cb);
81 
82 #ifdef __cplusplus
83 }
84 #endif
85 
86 #endif
87