bridgeif: improve documentation

src/apps/mqtt/mqtt.c

@@ -695,7 +695,7 @@ mqtt_incomming_suback(struct mqtt_request_t *r, u8_t result)
  * @param remaining_length Remaining length of complete message
  */
 static mqtt_connection_status_t
-  mqtt_message_received(mqtt_client_t *client, u8_t fixed_hdr_idx, u16_t length, u32_t remaining_length)
+mqtt_message_received(mqtt_client_t *client, u8_t fixed_hdr_idx, u16_t length, u32_t remaining_length)
 {
   mqtt_connection_status_t res = MQTT_CONNECT_ACCEPTED;
 
@@ -705,6 +705,9 @@ static mqtt_connection_status_t
   u8_t pkt_type = MQTT_CTL_PACKET_TYPE(client->rx_buffer[0]);
   u16_t pkt_id = 0;
 
+  LWIP_ERROR("buffer length mismatch", fixed_hdr_idx + length <= MQTT_VAR_HEADER_BUFFER_LEN,
+    return MQTT_CONNECT_DISCONNECTED);
+
   if (pkt_type == MQTT_MSG_TYPE_CONNACK) {
     if (client->conn_state == MQTT_CONNECTING) {
       /* Get result code from CONNACK */

src/include/netif/bridgeif.h

@@ -58,16 +58,25 @@ typedef u64_t bridgeif_portmask_t;
 
 #define BR_FLOOD ((bridgeif_portmask_t)-1)
 
-
+/** Initialisation data for @ref bridgeif_init.
+ * An instance of this type must be passed as parameter 'state' to @ref netif_add
+ * when the bridge is added.
+ */
 typedef struct bridgeif_initdata_s {
+  /** MAC address of the bridge (cannot use the netif's addresses) */
   struct eth_addr ethaddr;
+  /** Maximum number of ports in the bridge (ports are stored in an array, this
+      influences memory allocated for netif->state of the bridge netif). */
   u8_t            max_ports;
+  /** Maximum number of dynamic/learning entries in the bridge's forwarding database.
+      In the default implementation, this controls memory consumption only. */
   u16_t           max_fdb_dynamic_entries;
+  /** Maximum number of static forwarding entries. Influences memory consumption! */
   u16_t           max_fdb_static_entries;
 } bridgeif_initdata_t;
 
 /* Use this for constant initialization of a bridgeif_initdat_t
-   (ethaddr must be passed as pointer)*/
+   (ethaddr must be passed as MAKE_ETH_ADDR())*/
 #define BRIDGEIF_INITDATA1(max_ports, max_fdb_dynamic_entries, max_fdb_static_entries, ethaddr) {ethaddr, max_ports, max_fdb_dynamic_entries, max_fdb_static_entries}
 /* Use this for constant initialization of a bridgeif_initdat_t
    (each byte of ethaddr must be passed)*/

src/include/netif/bridgeif_opts.h

@@ -50,7 +50,7 @@
  * to call directly into bridgeif code and on top of that, directly call into
  * the selected forwarding port's 'linkoutput' function.
  * This means that the bridgeif input/output path is protected from concurrent access
- * but as well, the port netif's drivers must correctly handle concurrent access!
+ * but as well, *all* bridge port netif's drivers must correctly handle concurrent access!
  * == 0: get into tcpip_thread for every input packet (no multithreading)
  * ATTENTION: as ==0 relies on tcpip.h, the default depends on NO_SYS setting
  */

src/netif/bridgeif.c

@@ -44,6 +44,29 @@
  * On receive, the port netif calls into the bridge (via its netif->input function) and
  * the bridge selects the port(s) (and/or its netif->input function) to pass the received pbuf to.
  *
+ * Usage:
+ * - add the port netifs just like you would when using them as dedicated netif without a bridge
+ *   - only NETIF_FLAG_ETHARP/NETIF_FLAG_ETHERNET netifs are supported as bridge ports
+ *   - add the bridge port netifs without IPv4 addresses (i.e. pass 'NULL, NULL, NULL')
+ *   - don't add IPv6 addresses to the port netifs!
+ * - set up the bridge configuration in a global variable of type 'bridgeif_initdata_t' that contains
+ *   - the MAC address of the bridge
+ *   - some configuration options controlling the memory consumption (maximum number of ports
+ *     and FDB entries)
+ *   - e.g. for a bridge MAC address 00-01-02-03-04-05, 2 bridge ports, 1024 FDB entries + 16 static MAC entries:
+ *     bridgeif_initdata_t mybridge_initdata = BRIDGEIF_INITDATA1(2, 1024, 16, MAKE_ETH_ADDR(0, 1, 2, 3, 4, 5));
+ * - add the bridge netif (with IPv4 config):
+ *   struct netif bridge_netif;
+ *   netif_add(&bridge_netif, &my_ip, &my_netmask, &my_gw, &mybridge_initdata, bridgeif_init, tcpip_input);
+ *   NOTE: the passed 'input' function depends on BRIDGEIF_PORT_NETIFS_OUTPUT_DIRECT setting,
+ *         which controls where the forwarding is done (netif low level input context vs. tcpip_thread)
+ * - set up all ports netifs and the bridge netif
+ *
+ * - When adding a port netif, NETIF_FLAG_ETHARP flag will be removed from a port
+ *   to prevent ETHARP working on that port netif (we only want one IP per bridge not per port).
+ * - When adding a port netif, its input function is changed to call into the bridge.
+ *
+ *
  * @todo:
  * - compact static FDB entries (instead of walking the whole array)
  * - add FDB query/read access
@@ -555,6 +578,10 @@ bridgeif_tcpip_input(struct pbuf *p, struct netif *netif)
  * @ingroup bridgeif
  * Initialization function passed to netif_add().
  *
+ * ATTENTION: A pointer to a @ref bridgeif_initdata_t must be passed as 'state'
+ *            to @ref netif_add when adding the bridge. I supplies MAC address
+ *            and controls memory allocation (number of ports, FDB size).
+ *
  * @param netif the lwip network interface structure for this ethernetif
  * @return ERR_OK if the loopif is initialized
  *         ERR_MEM if private data couldn't be allocated
@@ -569,8 +596,10 @@ bridgeif_init(struct netif *netif)
 
   LWIP_ASSERT("netif != NULL", (netif != NULL));
 #if !BRIDGEIF_PORT_NETIFS_OUTPUT_DIRECT
-  LWIP_ASSERT("bridgeif does not need tcpip_input, use netif_input/ethernet_input instead",
-    netif->input != tcpip_input);
+  if (netif->input == tcpip_input) {
+    LWIP_DEBUGF(BRIDGEIF_DEBUG|LWIP_DBG_ON, ("bridgeif does not need tcpip_input, use netif_input/ethernet_input instead",
+      netif->input != tcpip_input));
+  }
 #endif
 
   if (bridgeif_netif_client_id == 0xFF) {