diff --git a/doc/subsystems/networking/networking.rst b/doc/subsystems/networking/networking.rst index 3706add44b9..084aaa2c725 100644 --- a/doc/subsystems/networking/networking.rst +++ b/doc/subsystems/networking/networking.rst @@ -20,3 +20,4 @@ operation of the stacks and how they were implemented. buffers.rst qemu_setup.rst usbnet_setup.rst + vlan.rst diff --git a/doc/subsystems/networking/overview.rst b/doc/subsystems/networking/overview.rst index c82abd39b01..5f40fc6a2f3 100644 --- a/doc/subsystems/networking/overview.rst +++ b/doc/subsystems/networking/overview.rst @@ -99,6 +99,10 @@ can be disabled if not needed. is even possible to have zero-copy data path from application to device driver. +* **Virtual LAN support.** Virtual LANs (VLANs) allow partitioning of physical + ethernet networks into logical networks. See :ref:`vlan-support` for more + details. + Additionally these network technologies (link layers) are supported in Zephyr OS v1.7 and later: diff --git a/doc/subsystems/networking/vlan.rst b/doc/subsystems/networking/vlan.rst new file mode 100644 index 00000000000..83d6b13c8db --- /dev/null +++ b/doc/subsystems/networking/vlan.rst @@ -0,0 +1,46 @@ +.. _vlan-support: + +Virtual LAN (VLAN) Support +########################## + +Overview +******** + +`Virtual LAN `_ (VLAN) is a +partitioned and isolated computer network at the data link layer +(OSI layer 2). For ethernet network this refers to +`IEEE 802.1Q `_ + +In Zephyr, each individual VLAN is modelled as a virtual network interface. +This means that there is an ethernet network interface that corresponds to +a real physical ethernet port in the system. A virtual network interface is +created for each VLAN, and this virtual network interface connects to the +real network interface. This is similar to how Linux implements VLANs. The +*eth0* is the real network interface and *vlan0* is a virtual network interface +that is run on top of *eth0*. + +VLAN support must be enabled at compile time by setting option +:option:`CONFIG_NET_VLAN` and also setting option +:option:`CONFIG_NET_VLAN_COUNT` to reflect how many network interfaces there +will be in the system. For example, if there is one network interface without +VLAN support, and two with VLAN support, the :option:`CONFIG_NET_VLAN_COUNT` +should be set to 3. + +Even if VLAN is enabled in a :file:`prj.conf` file, the VLAN needs to be +activated at runtime by the application. The VLAN API provides a +:cpp:func:`net_eth_vlan_enable()` function to do that. The application needs +to give the network interface and desired VLAN tag as a parameter to that +function. The VLAN tagging for a given network interface can be disabled by a +:cpp:func:`net_eth_vlan_disable()` function. The application needs to configure +the VLAN network interface itself, such as setting the IP address, etc. + +See also the :ref:`vlan-sample` VLAN sample application for API usage +example. The source code for that sample application can be found at +:file:`samples/net/vlan`. + +The net-shell module contains *net vlan add* and *net vlan del* commands +that can be used to enable or disable VLAN tags for a given network interface. + +See the `IEEE 802.1Q spec`_ for more information about ethernet VLANs. + +.. _IEEE 802.1Q spec: https://ieeexplore.ieee.org/document/6991462/