==== IPv6 ==== .. warning:: Migrated from: https://cwiki.apache.org/confluence/display/NUTTX/IPv6 NuttX has supported the Internet Protocol Version 4 (IPv4) for many years. There have been fragments of IPv6 in the code base for many years as well, but these fragments were not more than place markers and not functional. But recently, post NuttX-7.6, I have focused some effort into completing the IPv6 implementation. This Wiki page contains notes from that integration effort and will, hopefully, evolve to provide full documentation for NuttX IPv6 support. Current status: Basic functionality is complete and verified. That includes ICMPPv6 Neighbor Discover Protocol, IPCMPv6 Echo Request/Response (for ``ping6``), TCP/IPv6, and UDP/IPv6. It has also been proven that you can support a platform with `both` IPv4 and IPv6 enabled. Ethernet Driver Requirements ============================ Basic Driver Requirements ------------------------- In order to support IPv6, Ethernet drivers must do the following: * They must recognize IPv6 packets and call ``ipv6_input`` in order to pass the packets into the network stack. This is equivalent to calling ``ipv4_input`` when an IPv4 pack is received. * When sending an IPv6, the drivers must call ``neighbor_out()`` in order to add the MAC address of the destination into the link layer header. IPv6's `ICMPv6 Neighbor Discovery Protocol` is the moral equivalent of the `Address Resolution Protocol` (ARP) used with IPv6. And the IPv6 ``neighbor_out()`` performs a similar function to the IPv4 ``arp_out()`` function. * Ethernet drivers must also support some additional address filtering. For IPv4 support, most Ethernet drivers are configured to accept only Ethernet packets with matching MAC addresses and broadcast packets (or selected multicast packets if IGMP support is enabled). Additional filtering support is needed to support IPv6. All existing NuttX Ethernet drivers have already been modified to support the requirements of the first two bullets. However, additional logic must be added to most of the existing Ethernet drivers to support the final requirement. Multicast Address Filtering --------------------------- Each Ethernet device connects to the Ethernet wire via a PHY and so potentially has access to every packet that passes on the wire. In `promiscuous` mode, that is the behavior that is desired but normally it is not: The amount of traffic that appears on the wire would swamp most modest MCUs in promiscuous mode. So instead, the Ethernet MAC hardware will support address filtering. That is, the hardware will look at the Ethernet header at the beginning of each packet and will ignore packets that do not have the desired information in the Ethernet header. The software will see only those filtered packets that are desired. Typically, the Ethernet MAC is set-up for `unicast` address filtering: The hardware is programmed so that that only packets whose destination Ethernet MAC address matches the MAC address programmed into the hardware are accepted. In addition, special `broadcast` Ethernet addresses will also be accepted. In this way, the volume of Ethernet data received by the MCU is greatly reduced. `Multicast` addresses are a little different. Unlike broadcast addresses, there are many possible multicast addresses and so the Ethernet MAC hardware must support some special capability to match the destination Ethernet address in an incoming packet with a variety of multicast addresses. Usually this involves `hashing` the Ethernet address and performing a `hash table lookup` to check for an address match. Each Ethernet driver uses a common interface that is defined in ``nuttx/include/nuttx/net/netdev.h``. That interface defines, among other things, a set of calls into the Ethernet driver to perform a variety of functions. One of those functions is multicast address filtering: .. code-block:: c #ifdef CONFIG_NET_IGMP int (*d_addmac)(FAR struct net_driver_s *dev, FAR const uint8_t *mac); int (*d_rmmac)(FAR struct net_driver_s *dev, FAR const uint8_t *mac); #endif The ``d_addmac()`` interface adds a multicast address to the hash table; ``d_rmmac()`` removes a multicast address from the hash table. These interface is only required if IGMP is supported, but the underlying ability to program multicast address filtered is required for full IPv6 support. This interface exists in all Ethernet drivers but most are currently place holders and are `to-be-provided`. At present, only the STMicro STM32, the TI Tiva TM4C, and the Atmel SAM3/4 and SAMA5D3/4 Ethernet drivers support multicast hash tables. This capability will have to be added to any additional Ethernet drivers that are modified to support IPv6. ICMPv6 Neighbor Discovery Protocol ---------------------------------- The ICMPv6 Neighbor Discover protocol is the reason for this additional address filtering. The ICMPv6 Neighbor Discovery Protocol is the replacement for IPv4's ARP. It different from ARP in the it is implemented not at the Ethernet link layer, but within the IPv6 layer. In order to receive broadcast packets to ICMPv6, the IPv6 Multicast address of 33.33.ff.xx.xx.xx is used, where the xx.xx.xx part derives from the IPv6 address. The Ethernet driver filtering logic must be modified so that it accepts packets directed to the that MAC address. At present, this additional support is only implemented for the TI Tiva TM4C129X Ethernet driver. Below is a snippet of code from that drier showing how this is implemented: .. code-block:: c /* Set the MAC address */ tiva_macaddress(priv); #ifdef CONFIG_NET_ICMPv6 /* Set up the IPv6 multicast address */ tiva_ipv6multicast(priv); #endif Where `tiva_macaddress()` sets up the normal MAC address filtering and `tiva_ipv6multicast()` sets up the special filtering needed by IPv6: .. code-block:: c /**************************************************************************** * Function: tiva_ipv6multicast * * Description: * Configure the IPv6 multicast MAC address. * * Parameters: * priv - A reference to the private driver state structure * * Returned Value: * OK on success; Negated errno on failure. * * Assumptions: ***************************************************************************/ #ifdef CONFIG_NET_ICMPv6 static void tiva_ipv6multicast(FAR struct tiva_ethmac_s *priv) { struct net_driver_s *dev; uint16_t tmp16; uint8_t mac[6]; /* For ICMPv6, we need to add the IPv6 multicast address * For IPv6 multicast addresses, the Ethernet MAC is derived by * the four low-order octets OR'ed with the MAC 33:33:00:00:00:00, * so for example the IPv6 address FF02:DEAD:BEEF::1:3 would map * to the Ethernet MAC address 33:33:00:01:00:03. * NOTES: This appears correct for the ICMPv6 Router Solicitation * Message, but the ICMPv6 Neighbor Solicitation message seems to * use 33:33:ff:01:00:03. */ mac[0] = 0x33; mac[1] = 0x33; dev = &priv->dev; tmp16 = dev->d_ipv6addr[6]; mac[2] = 0xff; mac[3] = tmp16 >> 8; tmp16 = dev->d_ipv6addr[7]; mac[4] = tmp16 & 0xff; mac[5] = tmp16 >> 8; nvdbg("IPv6 Multicast: %02x:%02x:%02x:%02x:%02x:%02x\n", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]); (void)tiva_addmac(dev, mac); #ifdef CONFIG_NET_ICMPv6_AUTOCONF /* Add the IPv6 all link-local nodes Ethernet address. This is the * address that we expect to receive ICMPv6 Router Advertisement * packets. */ (void)tiva_addmac(dev, g_ipv6_ethallnodes.ether_addr_octet); #endif /* CONFIG_NET_ICMPv6_AUTOCONF */ #ifdef CONFIG_NET_ICMPv6_ROUTER /* Add the IPv6 all link-local routers Ethernet address. This is the * address that we expect to receive ICMPv6 Router Solicitation * packets. */ (void)tiva_addmac(dev, g_ipv6_ethallrouters.ether_addr_octet); #endif /* CONFIG_NET_ICMPv6_ROUTER */ } #endif /* CONFIG_NET_ICMPv6 */ The following Ethernet drivers are complete and IPv6 ready. All others Ethernet drivers have all required IPv6 support `except` that they are missing (1) the required ICMPv6 addressing filtering described above and/or (2) support for multi-cast address filtering. * STMicro STM32 * TI Tiva TM4C * Atmel SAMA5D4 * NXP LPC17xx Board Configurations ==================== At present, there are three board configuration that are pre-configured to use IPv6: ``nuttx/boards/arm/tiva/dk-tm4c129x/configs/ipv6``, ``nuttx/boards/arm/stm32/stm32f4discovery/ipv6``, and ``nuttx/boards/arm/tiva/tm4c1294-launchpad/configs/ipv6``. These default configurations have only IPv6 enabled. But the `README` files at in those board directories describes how to enable `both` IPv4 and IPv6 simultaneously. Ping ==== Ping from Host PC ----------------- Ping from Windows cmd Terminal `````````````````````````````` .. code-block:: bash ping -6 fc00::2 Ping From Linux shell ````````````````````` .. code-block:: bash ping6 fc00::2 Ping from the NuttShell (NSH) ----------------------------- .. code-block:: bash nsh> ping6 fc00::2 NSH ifconfig ============ IPv4 Only --------- ``CONFIG_NET_IPv4=y`` and ``CONFIG_NET_IPv6=n`` .. code-block:: bash nsh> ifconfig eth0 Link encap: Ethernet HWaddr 00:1a:b6:02:81:14 at UP inet addr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 IPv4 TCP UDP ICMP Received 003b 001c 0000 0004 Dropped 001b 0000 0000 0000 IPv4 VHL: 0000 Frg: 0000 Checksum 0000 0000 0000 ---- TCP ACK: 0000 SYN: 0000 RST: 0000 0000 Type 0000 ---- ---- 0000 Sent 0031 002d 0000 0004 Rexmit ---- ---- 0000 ---- NOTE: The detailed packet statistics only appear if ``CONFIG_NET_STATISTICS`` is enabled. IPv6 Only --------- ``CONFIG_NET_IPv4=n`` and ``CONFIG_NET_IPv6=y`` .. code-block:: bash nsh> ifconfig eth0 Link encap: Ethernet HWaddr 00:1a:b6:02:81:14 at UP inet6 addr:fc00::2 inet6 DRaddr:fc00::1 inet6 Mask:ffff:ffff:ffff::ffff:ffff:ffff:ff80 IPv6 TCP UDP ICMPv6 Received 0007 0000 0000 0007 Dropped 0000 0000 0000 0000 IPv6 VHL: 0000 Checksum ---- 0000 0000 ---- TCP ACK: 0000 SYN: 0000 RST: 0000 0000 Type 0000 ---- ---- 0000 Sent 0011 0000 0000 0011 Rexmit ---- ---- 0000 ---- Both IPv4 and IPv6 ------------------ ``CONFIG_NET_IPv4=y`` and ``CONFIG_NET_IPv6=y`` .. code-block:: bash nsh> ifconfig eth0 Link encap: Ethernet HWaddr 00:1a:b6:02:81:14 at UP inet addr:10.0.0.2 DRaddr:10.0.0.1 Mask:255.255.255.0 inet6 addr:fc00::2 inet6 DRaddr:fc00::1 inet6 Mask:ffff:ffff:ffff::ffff:ffff:ffff:ff80 IPv4 IPv6 TCP UDP ICMP ICMPv6 Received 0047 000a 001c 0000 0004 000a Dropped 0027 0000 0000 0000 0000 0000 IPv4 VHL: 0000 Frg: 0000 IPv6 VHL: 0000 Checksum 0000 ---- 0000 0000 ---- ---- TCP ACK: 0000 SYN: 0000 RST: 0000 0000 Type 0000 0000 ---- ---- 0000 0000 Sent 0033 000a 002f 0000 0004 000a Rexmit ---- ---- ---- 0000 ---- ---- Tests, Applications, and Network Utilities ========================================== In addition to the core RTOS support IPv6, changes are also required to networking tests, to networking aware applications, and, of course, to all of the network utils (``netutils``). * NuttShell (NSH): IPv6 support is partially available. NSH is capable of initializing the IPv6 domain and some of the NSH commands have been adapted to support IPv6. A ping6 command has been added. But there are many commands that still require updating. * Tests: There are several networking tests in ``apps/examples``. The ``nettest`` test and the ``udp`` test have been adapted to work in the IPv6 domain, but none of the others have yet been adapted. * Netutils: The network utilities in ``apps/netutils`` have been adapted to work with IPv6: DHCP, FTP, TFTP, Telnet, etc. Support for managing IPv6 address have been included in the ``netlib``, but nothing else has yet been updated.