Line data Source code
1 1 : /*
2 : * Copyright (c) 2018-2021 mcumgr authors
3 : * Copyright (c) 2023 Nordic Semiconductor ASA
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file
10 : * @brief SMP - Simple Management Protocol.
11 : *
12 : * SMP is a basic protocol that sits on top of the mgmt layer. SMP requests
13 : * and responses have the following format:
14 : *
15 : * [Offset 0]: Mgmt header
16 : * [Offset 8]: CBOR map of command-specific key-value pairs.
17 : *
18 : * SMP request packets may contain multiple concatenated requests. Each
19 : * request must start at an offset that is a multiple of 4, so padding should
20 : * be inserted between requests as necessary. Requests are processed
21 : * sequentially from the start of the packet to the end. Each response is sent
22 : * individually in its own packet. If a request elicits an error response,
23 : * processing of the packet is aborted.
24 : */
25 :
26 : #ifndef H_SMP_
27 : #define H_SMP_
28 :
29 : #include <zephyr/net_buf.h>
30 : #include <zephyr/mgmt/mcumgr/transport/smp.h>
31 :
32 : #include <zcbor_common.h>
33 :
34 : #ifdef __cplusplus
35 : extern "C" {
36 : #endif
37 :
38 : /** SMP MCUmgr protocol version, part of the SMP header */
39 1 : enum smp_mcumgr_version_t {
40 : /** Version 1: the original protocol */
41 : SMP_MCUMGR_VERSION_1 = 0,
42 :
43 : /** Version 2: adds more detailed error reporting capabilities */
44 : SMP_MCUMGR_VERSION_2,
45 : };
46 :
47 0 : struct cbor_nb_reader {
48 0 : struct net_buf *nb;
49 : /* CONFIG_MCUMGR_SMP_CBOR_MAX_DECODING_LEVELS + 2 translates to minimal
50 : * zcbor backup states.
51 : */
52 0 : zcbor_state_t zs[CONFIG_MCUMGR_SMP_CBOR_MAX_DECODING_LEVELS + 2];
53 : };
54 :
55 0 : struct cbor_nb_writer {
56 0 : struct net_buf *nb;
57 0 : zcbor_state_t zs[CONFIG_MCUMGR_SMP_CBOR_MAX_ENCODING_LEVELS + 2];
58 :
59 : #if defined(CONFIG_MCUMGR_SMP_SUPPORT_ORIGINAL_PROTOCOL)
60 : uint16_t error_group;
61 : uint16_t error_ret;
62 : #endif
63 : };
64 :
65 : /**
66 : * @brief Allocates a net_buf for holding an mcumgr request or response.
67 : *
68 : * @return A newly-allocated buffer net_buf on success;
69 : * NULL on failure.
70 : */
71 1 : struct net_buf *smp_packet_alloc(void);
72 :
73 : /**
74 : * @brief Frees an mcumgr net_buf
75 : *
76 : * @param nb The net_buf to free.
77 : */
78 1 : void smp_packet_free(struct net_buf *nb);
79 :
80 : /**
81 : * @brief Decodes, encodes, and transmits SMP packets.
82 : */
83 1 : struct smp_streamer {
84 0 : struct smp_transport *smpt;
85 0 : struct cbor_nb_reader *reader;
86 0 : struct cbor_nb_writer *writer;
87 :
88 : #ifdef CONFIG_MCUMGR_SMP_VERBOSE_ERR_RESPONSE
89 : const char *rc_rsn;
90 : #endif
91 : };
92 :
93 : /**
94 : * @brief Processes a single SMP request packet and sends all corresponding responses.
95 : *
96 : * Processes all SMP requests in an incoming packet. Requests are processed
97 : * sequentially from the start of the packet to the end. Each response is sent
98 : * individually in its own packet. If a request elicits an error response,
99 : * processing of the packet is aborted. This function consumes the supplied
100 : * request buffer regardless of the outcome.
101 : *
102 : * @param streamer The streamer providing the required SMP callbacks.
103 : * @param req The request packet to process.
104 : *
105 : * @return 0 on success, #mcumgr_err_t code on failure.
106 : */
107 1 : int smp_process_request_packet(struct smp_streamer *streamer, void *req);
108 :
109 : /**
110 : * @brief Appends an "err" response
111 : *
112 : * This appends an err response to a pending outgoing response which contains a
113 : * result code for a specific group. Note that error codes are specific to the
114 : * command group they are emitted from).
115 : *
116 : * @param zse The zcbor encoder to use.
117 : * @param group The group which emitted the error.
118 : * @param ret The command result code to add.
119 : *
120 : * @return true on success, false on failure (memory error).
121 : */
122 1 : bool smp_add_cmd_err(zcbor_state_t *zse, uint16_t group, uint16_t ret);
123 :
124 : #if defined(CONFIG_MCUMGR_SMP_SUPPORT_ORIGINAL_PROTOCOL)
125 : /** @typedef smp_translate_error_fn
126 : * @brief Translates a SMP version 2 error response to a legacy SMP version 1 error code.
127 : *
128 : * @param ret The SMP version 2 group error value.
129 : *
130 : * @return #enum mcumgr_err_t Legacy SMP version 1 error code to return to client.
131 : */
132 : typedef int (*smp_translate_error_fn)(uint16_t err);
133 : #endif
134 :
135 : #ifdef __cplusplus
136 : }
137 : #endif
138 :
139 : #endif /* H_SMP_ */
|
