docs/MCU_based_host/mcu_api.md

   1 # APIs for MCU based Host
   2
   3 # 1. Serial interface layer
   4 This section explains serial interface APIs and data structures provided by MCU based ESP Host software.
   5
   6 ## 1.1 Data Structures
   7
   8 ### _struct_ `serial_handle_s`
   9 This structure holds instance of a virtual serial interface. It contains following fields:
  10
  11 *Public Members*
  12 - `QueueHandle_t queue`:
  13 Buffer queue for storing received data packets
  14 - `uint8_t if_type`:
  15 ESP Hosted Interface type
  16 - `uint8_t if_num`:
  17 ESP Hosted Interface number
  18 - `struct serial_operations *ops`:
  19 Hook functions supported by virtual serial interface
  20 - `uint8_t state`:
  21 State of a handle
  22 - `void (*serial_rx_callback) (void)`:
  23 Rx callback registered by upper layer.
  24
  25 ---
  26
  27 ### _struct_ `serial_operations`
  28 This structure defines hook functions that are defined by virtual serial driver
  29
  30 *Public Members*
  31 - `int (*open)  (serial_handle_t *serial_hdl)`:
  32 Prepares and opens specified serial interface for communication.
  33   - Parameters:
  34     - `serial_hdl`:
  35 Non null handle for virtual serial interface
  36   - Returns:
  37     - 0: success
  38     - -1: failure
  39
  40 - `uint8_t *(*read)  (const serial_handle_t * serial_hdl, uint16_t * rlen)`:
  41 This function performs non blocking read operation over specified serial interface handle.
  42   - Parameters:
  43     - `serial_hdl`:
  44 Non null handle for virtual serial interface
  45     - `rlen`:
  46 Output parameter, indicates number of bytes read
  47   - Returns:
  48     - On success, pointer to received buffer
  49     - On failure [and when no data is available to read], NULL
  50
  51 - `int (*write) (const serial_handle_t * serial_hdl, uint8_t * wbuffer, const uint16_t wlen)`:
  52 This function performs write operation on specified serial interface handle.
  53   - Parameters:
  54     - `serial_hdl`:
  55 Non null handle for virtual serial interface
  56     - `wbuffer`:
  57 Data buffer to be written over serial interface
  58     - `wlen`:
  59 Length of data to be written in bytes
  60   - Returns
  61     - 0: success
  62     - -1: failure
  63
  64 - `int (*close) (serial_handle_t * serial_hdl)`:
  65 Closes specified serial interface handle.
  66   - Parameters:
  67     - `serial_hdl`:
  68 Non null handle for virtual serial interface
  69   - Returns
  70     - 0: success
  71     - -1: failure
  72
  73 ---
  74
  75
  76 ## 1.2 Functions
  77
  78 ### `serial_handle_t * serial_init(void(*rx_data_ind)(void))`
  79 This API can be used by higher layer to setup a serial interface. A serial interface handle is returned in response. This handle can be used to perform further operations on specified serial interface.
  80
  81 #### Parameters
  82 - `void(*rx_data_ind)(void)`:
  83 Call back function in higher layer. This is used to indicate availibility of Rx data to higher layer. Higher layer can perform read operation to get this data.
  84
  85 #### Return
  86 - NULL: failure
  87 - Non NULL: pointer to a valid serial interface handle
  88
  89 ---
  90
  91 # 2. Network interface layer
  92 This section explains network interface APIs and data structures provided by ESP Host software.
  93
  94 ## 2.1 Data structures
  95
  96 ### _struct_ `netdev`
  97 - This is a opaque structure which network stack should define.
  98 - This denotes instance of a network device in a network stack.
  99 - Along with network stack specific data, it should also hold private structure of underlying driver.
 100
 101 ---
 102
 103 ### _struct_ `pbuf`
 104 This is a basic structure that holds a network packet which is being transmitted or received.
 105
 106 *Public Members*
 107 - `uint8_t *payload`:
 108 This points to network payload buffer which is being transmitted or received
 109 - `uint16_t len`:
 110 This represents length of payload field in bytes
 111
 112 ---
 113
 114 ### _struct_ `netdev_ops`
 115 This structure represents management hooks which are implemented by underlying driver [which is SPI host driver in this case].
 116
 117 *Public Members*
 118 - `int (* netdev_open) (struct netdev *)`
 119 This function prepares underlying driver for data transmission or reception on specified network device instance.
 120 - Parameters:
 121     - `netdev`:
 122 Non null network device instance
 123 - Returns:
 124     - 0: success
 125     - -1: failure
 126
 127 - `int (* netdev_close) (struct netdev *)`
 128 Network stack calls this function while closing a network device instance.
 129   - Parameters:
 130     - `netdev`:
 131 Non null network device instance
 132   - Returns:
 133     - 0: success
 134     - -1: failure
 135
 136 - `int (* netdev_xmit) (struct netdev *, struct pbuf *)`
 137 Network stack calls this function to transfer a data packet from network stack to underlying SPI host driver.
 138   - Parameters:
 139     - `netdev`:
 140 Non null network device instance
 141     - `pbuf`:
 142 Non null buffer pointer. This will be freed by SPI host driver.
 143   - Returns:
 144     - 0: success
 145     - -1: failure
 146
 147 ---
 148
 149 ## 2.2 Functions
 150 Below are the APIs that are to be implemented by network stack.
 151
 152 ### `struct netdev * netdev_alloc(uint32_t sizeof_priv, char *name)`
 153 This function allocates and initializes a network device instance for a given network interface name. This function also allocates memory for storing priv instance of SPI host driver.
 154
 155 #### Parameters
 156 - `sizeof_priv`:
 157 This denotes size [in bytes] of a priv instance of SPI host driver.
 158 - `name`:
 159 Name of network interface for which a network device instance to be allocated
 160
 161 #### Return
 162 - NULL: failure
 163 - Non NULL: Pointer to the struct netdev
 164
 165 ---
 166
 167 ### `void netdev_free(struct netdev *ndev)`
 168 This function frees network device instance. This also frees memory allocated for storing priv instance of SPI host driver.
 169
 170 #### Parameters
 171 - `ndev`:
 172 Non null network device instance to be freed
 173
 174 ---
 175
 176 ### `void * netdev_get_priv(struct netdev *ndev)`
 177 This function returns pointer to the priv instance of SPI host driver from the specified network device instance
 178
 179 #### Parameters
 180 - `ndev`:
 181 Non null network device instance
 182
 183 #### Return
 184 - NULL: failure
 185 - Non NULL : pointer to the priv instance of SPI host driver
 186
 187 ---
 188
 189 ### `int netdev_register(struct netdev *ndev, struct netdev_ops *ops)`
 190 This function registers a network device with network stack.
 191
 192 #### Parameters
 193 - `ndev`:
 194 Non null network device instance to be registered
 195 - `ops`:
 196 Management hooks implemented by SPI host driver
 197
 198 #### Return
 199 - 0: success
 200 - -1: failure
 201
 202 ---
 203
 204 ### `int netdev_unregister(struct netdev *ndev)`
 205 This function unregisters a network device
 206
 207 #### Parameters
 208 - `ndev`:
 209 Non null network device instance to be unregistered
 210
 211 #### Return
 212 - 0: success
 213 - -1: failure
 214
 215 ---
 216
 217
 218 ### `int netdev_rx(struct netdev *ndev, struct pbuf *net_buf)`
 219 SPI host driver calls this function to pass on received network packet to network stack
 220
 221 #### Parameters
 222 - `ndev`:
 223 Non null network device instance for which a packet has been received
 224 - `net_buf`:
 225 Non null buffer that contains received network packet. The SPI host driver will allocate this buffer. Network stack is supposed to free this buffer.
 226
 227 #### Return
 228 - 0: success
 229 - -1: failure
 230
 231 ---