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_ */