Line data    Source code

       1            0 : /*
       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              : /**
      11              :  * @brief This allows to use the MCUmgr SMP protocol over serial.
      12              :  * @defgroup mcumgr_transport_serial Serial transport
      13              :  * @ingroup mcumgr_transport
      14              :  * @{
      15              :  */
      16              : 
      17              : #include <zephyr/types.h>
      18              : 
      19              : #ifdef __cplusplus
      20              : extern "C" {
      21              : #endif
      22              : 
      23              : /** Serial packet header */
      24            1 : #define MCUMGR_SERIAL_HDR_PKT       0x0609
      25              : /** Serial fragment header */
      26            1 : #define MCUMGR_SERIAL_HDR_FRAG      0x0414
      27              : /** Maximum frame size */
      28            1 : #define MCUMGR_SERIAL_MAX_FRAME     127
      29              : 
      30              : /** First byte of packet header */
      31            1 : #define MCUMGR_SERIAL_HDR_PKT_1     (MCUMGR_SERIAL_HDR_PKT >> 8)
      32              : /** Second byte of packet header */
      33            1 : #define MCUMGR_SERIAL_HDR_PKT_2     (MCUMGR_SERIAL_HDR_PKT & 0xff)
      34              : /** First byte of fragment header */
      35            1 : #define MCUMGR_SERIAL_HDR_FRAG_1    (MCUMGR_SERIAL_HDR_FRAG >> 8)
      36              : /** Second byte of fragment header */
      37            1 : #define MCUMGR_SERIAL_HDR_FRAG_2    (MCUMGR_SERIAL_HDR_FRAG & 0xff)
      38              : 
      39              : /**
      40              :  * @brief Maintains state for an incoming mcumgr request packet.
      41              :  */
      42            1 : struct mcumgr_serial_rx_ctxt {
      43              :         /** Contains the partially- or fully-received mcumgr request.  Data
      44              :          * stored in this buffer has already been base64-decoded.
      45              :          */
      46            1 :         struct net_buf *nb;
      47              : 
      48              :         /** Length of full packet, as read from header. */
      49            1 :         uint16_t pkt_len;
      50              : };
      51              : 
      52              : /** @typedef mcumgr_serial_tx_cb
      53              :  * @brief Transmits a chunk of raw response data.
      54              :  *
      55              :  * @param data                  The data to transmit.
      56              :  * @param len                   The number of bytes to transmit.
      57              :  *
      58              :  * @return                      0 on success; negative error code on failure.
      59              :  */
      60            1 : typedef int (*mcumgr_serial_tx_cb)(const void *data, int len);
      61              : 
      62              : /**
      63              :  * @brief Processes an mcumgr request fragment received over a serial
      64              :  *        transport.
      65              :  *
      66              :  * Processes an mcumgr request fragment received over a serial transport.  If
      67              :  * the fragment is the end of a valid mcumgr request, this function returns a
      68              :  * net_buf containing the decoded request.  It is the caller's responsibility
      69              :  * to free the net_buf after it has been processed.
      70              :  *
      71              :  * @param rx_ctxt               The receive context associated with the serial
      72              :  *                                  transport being used.
      73              :  * @param frag                  The incoming fragment to process.
      74              :  * @param frag_len              The length of the fragment, in bytes.
      75              :  *
      76              :  * @return                      A net_buf containing the decoded request if a
      77              :  *                                  complete and valid request has been
      78              :  *                                  received.
      79              :  *                              NULL if the packet is incomplete or invalid.
      80              :  */
      81            1 : struct net_buf *mcumgr_serial_process_frag(
      82              :         struct mcumgr_serial_rx_ctxt *rx_ctxt,
      83              :         const uint8_t *frag, int frag_len);
      84              : 
      85              : /**
      86              :  * @brief Encodes and transmits an mcumgr packet over serial.
      87              :  *
      88              :  * @param data                  The mcumgr packet data to send.
      89              :  * @param len                   The length of the unencoded mcumgr packet.
      90              :  * @param cb                    A callback used to transmit raw bytes.
      91              :  *
      92              :  * @return                      0 on success; negative error code on failure.
      93              :  */
      94            1 : int mcumgr_serial_tx_pkt(const uint8_t *data, int len, mcumgr_serial_tx_cb cb);
      95              : 
      96              : #ifdef __cplusplus
      97              : }
      98              : #endif
      99              : 
     100              : /**
     101              :  * @}
     102              :  */
     103              : 
     104              : #endif