diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/devicetree/bindings/net/fsl-enetc.txt | 69 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt | 82 | ||||
| -rw-r--r-- | Documentation/networking/ieee802154.rst (renamed from Documentation/networking/ieee802154.txt) | 193 | ||||
| -rw-r--r-- | Documentation/networking/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/networking/switchdev.txt | 19 |
5 files changed, 250 insertions, 114 deletions
diff --git a/Documentation/devicetree/bindings/net/fsl-enetc.txt b/Documentation/devicetree/bindings/net/fsl-enetc.txt new file mode 100644 index 000000000000..c812e25ae90f --- /dev/null +++ b/Documentation/devicetree/bindings/net/fsl-enetc.txt @@ -0,0 +1,69 @@ +* ENETC ethernet device tree bindings + +Depending on board design and ENETC port type (internal or +external) there are two supported link modes specified by +below device tree bindings. + +Required properties: + +- reg : Specifies PCIe Device Number and Function + Number of the ENETC endpoint device, according + to parent node bindings. +- compatible : Should be "fsl,enetc". + +1) The ENETC external port is connected to a MDIO configurable phy: + +In this case, the ENETC node should include a "mdio" sub-node +that in turn should contain the "ethernet-phy" node describing the +external phy. Below properties are required, their bindings +already defined in ethernet.txt or phy.txt, under +Documentation/devicetree/bindings/net/*. + +Required: + +- phy-handle : Phandle to a PHY on the MDIO bus. + Defined in ethernet.txt. + +- phy-connection-type : Defined in ethernet.txt. + +- mdio : "mdio" node, defined in mdio.txt. + +- ethernet-phy : "ethernet-phy" node, defined in phy.txt. + +Example: + + ethernet@0,0 { + compatible = "fsl,enetc"; + reg = <0x000000 0 0 0 0>; + phy-handle = <&sgmii_phy0>; + phy-connection-type = "sgmii"; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + sgmii_phy0: ethernet-phy@2 { + reg = <0x2>; + }; + }; + }; + +2) The ENETC port is an internal port or has a fixed-link external +connection: + +In this case, the ENETC port node defines a fixed link connection, +as specified by "fixed-link.txt", under +Documentation/devicetree/bindings/net/*. + +Required: + +- fixed-link : "fixed-link" node, defined in "fixed-link.txt". + +Example: + ethernet@0,2 { + compatible = "fsl,enetc"; + reg = <0x000200 0 0 0 0>; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; diff --git a/Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt b/Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt new file mode 100644 index 000000000000..534e38058fe0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt @@ -0,0 +1,82 @@ +Properties for an MDIO bus multiplexer consumer device + +This is a special case of MDIO mux when MDIO mux is defined as a consumer +of a mux producer device. The mux producer can be of any type like mmio mux +producer, gpio mux producer or generic register based mux producer. + +Required properties in addition to the MDIO Bus multiplexer properties: + +- compatible : should be "mmio-mux-multiplexer" +- mux-controls : mux controller node to use for operating the mux +- mdio-parent-bus : phandle to the parent MDIO bus. + +each child node of mdio bus multiplexer consumer device represent a mdio +bus. + +for more information please refer +Documentation/devicetree/bindings/mux/mux-controller.txt +and Documentation/devicetree/bindings/net/mdio-mux.txt + +Example: +In below example the Mux producer and consumer are separate nodes. + +&i2c0 { + fpga@66 { // fpga connected to i2c + compatible = "fsl,lx2160aqds-fpga", "fsl,fpga-qixis-i2c", + "simple-mfd"; + reg = <0x66>; + + mux: mux-controller { // Mux Producer + compatible = "reg-mux"; + #mux-control-cells = <1>; + mux-reg-masks = <0x54 0xf8>, /* 0: reg 0x54, bits 7:3 */ + <0x54 0x07>; /* 1: reg 0x54, bits 2:0 */ + }; + }; +}; + +mdio-mux-1 { // Mux consumer + compatible = "mdio-mux-multiplexer"; + mux-controls = <&mux 0>; + mdio-parent-bus = <&emdio1>; + #address-cells = <1>; + #size-cells = <0>; + + mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + mdio@8 { + reg = <0x8>; + #address-cells = <1>; + #size-cells = <0>; + }; + + .. + .. +}; + +mdio-mux-2 { // Mux consumer + compatible = "mdio-mux-multiplexer"; + mux-controls = <&mux 1>; + mdio-parent-bus = <&emdio2>; + #address-cells = <1>; + #size-cells = <0>; + + mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + mdio@1 { + reg = <0x1>; + #address-cells = <1>; + #size-cells = <0>; + }; + + .. + .. +}; diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.rst index e74d8e1da0e2..36ca823a1122 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.rst @@ -1,54 +1,79 @@ - - Linux IEEE 802.15.4 implementation - +=============================== +IEEE 802.15.4 Developer's Guide +=============================== Introduction ============ The IEEE 802.15.4 working group focuses on standardization of the bottom two layers: Medium Access Control (MAC) and Physical access (PHY). And there are mainly two options available for upper layers: - - ZigBee - proprietary protocol from the ZigBee Alliance - - 6LoWPAN - IPv6 networking over low rate personal area networks + +- ZigBee - proprietary protocol from the ZigBee Alliance +- 6LoWPAN - IPv6 networking over low rate personal area networks The goal of the Linux-wpan is to provide a complete implementation of the IEEE 802.15.4 and 6LoWPAN protocols. IEEE 802.15.4 is a stack of protocols for organizing Low-Rate Wireless Personal Area Networks. The stack is composed of three main parts: - - IEEE 802.15.4 layer; We have chosen to use plain Berkeley socket API, - the generic Linux networking stack to transfer IEEE 802.15.4 data - messages and a special protocol over netlink for configuration/management - - MAC - provides access to shared channel and reliable data delivery - - PHY - represents device drivers +- IEEE 802.15.4 layer; We have chosen to use plain Berkeley socket API, + the generic Linux networking stack to transfer IEEE 802.15.4 data + messages and a special protocol over netlink for configuration/management +- MAC - provides access to shared channel and reliable data delivery +- PHY - represents device drivers Socket API ========== -int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); -..... +.. c:function:: int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); The address family, socket addresses etc. are defined in the include/net/af_ieee802154.h header or in the special header in the userspace package (see either http://wpan.cakelab.org/ or the git tree at https://github.com/linux-wpan/wpan-tools). +6LoWPAN Linux implementation +============================ + +The IEEE 802.15.4 standard specifies an MTU of 127 bytes, yielding about 80 +octets of actual MAC payload once security is turned on, on a wireless link +with a link throughput of 250 kbps or less. The 6LoWPAN adaptation format +[RFC4944] was specified to carry IPv6 datagrams over such constrained links, +taking into account limited bandwidth, memory, or energy resources that are +expected in applications such as wireless Sensor Networks. [RFC4944] defines +a Mesh Addressing header to support sub-IP forwarding, a Fragmentation header +to support the IPv6 minimum MTU requirement [RFC2460], and stateless header +compression for IPv6 datagrams (LOWPAN_HC1 and LOWPAN_HC2) to reduce the +relatively large IPv6 and UDP headers down to (in the best case) several bytes. + +In September 2011 the standard update was published - [RFC6282]. +It deprecates HC1 and HC2 compression and defines IPHC encoding format which is +used in this Linux implementation. + +All the code related to 6lowpan you may find in files: net/6lowpan/* +and net/ieee802154/6lowpan/* + +To setup a 6LoWPAN interface you need: +1. Add IEEE802.15.4 interface and set channel and PAN ID; +2. Add 6lowpan interface by command like: +# ip link add link wpan0 name lowpan0 type lowpan +3. Bring up 'lowpan0' interface -Kernel side -============= +Drivers +======= Like with WiFi, there are several types of devices implementing IEEE 802.15.4. 1) 'HardMAC'. The MAC layer is implemented in the device itself, the device - exports a management (e.g. MLME) and data API. +exports a management (e.g. MLME) and data API. 2) 'SoftMAC' or just radio. These types of devices are just radio transceivers - possibly with some kinds of acceleration like automatic CRC computation and - comparation, automagic ACK handling, address matching, etc. +possibly with some kinds of acceleration like automatic CRC computation and +comparation, automagic ACK handling, address matching, etc. Those types of devices require different approach to be hooked into Linux kernel. - HardMAC -======= +------- See the header include/net/ieee802154_netdev.h. You have to implement Linux net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family @@ -64,9 +89,8 @@ net_device with a pointer to struct ieee802154_mlme_ops instance. The fields assoc_req, assoc_resp, disassoc_req, start_req, and scan_req are optional. All other fields are required. - SoftMAC -======= +------- The MAC is the middle layer in the IEEE 802.15.4 Linux stack. This moment it provides interface for drivers registration and management of slave interfaces. @@ -79,99 +103,78 @@ This layer is going to be extended soon. See header include/net/mac802154.h and several drivers in drivers/net/ieee802154/. +Fake drivers +------------ + +In addition there is a driver available which simulates a real device with +SoftMAC (fakelb - IEEE 802.15.4 loopback driver) interface. This option +provides a possibility to test and debug the stack without usage of real hardware. Device drivers API ================== The include/net/mac802154.h defines following functions: - - struct ieee802154_hw * - ieee802154_alloc_hw(size_t priv_data_len, const struct ieee802154_ops *ops): - allocation of IEEE 802.15.4 compatible hardware device - - void ieee802154_free_hw(struct ieee802154_hw *hw): - freeing allocated hardware device +.. c:function:: struct ieee802154_dev *ieee802154_alloc_device (size_t priv_size, struct ieee802154_ops *ops) - - int ieee802154_register_hw(struct ieee802154_hw *hw): - register PHY which is the allocated hardware device, in the system +Allocation of IEEE 802.15.4 compatible device. - - void ieee802154_unregister_hw(struct ieee802154_hw *hw): - freeing registered PHY +.. c:function:: void ieee802154_free_device(struct ieee802154_dev *dev) - - void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, - u8 lqi): - telling 802.15.4 module there is a new received frame in the skb with - the RF Link Quality Indicator (LQI) from the hardware device +Freeing allocated device. - - void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, - bool ifs_handling): - telling 802.15.4 module the frame in the skb is or going to be - transmitted through the hardware device +.. c:function:: int ieee802154_register_device(struct ieee802154_dev *dev) + +Register PHY in the system. + +.. c:function:: void ieee802154_unregister_device(struct ieee802154_dev *dev) + +Freeing registered PHY. + +.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi): + +Telling 802.15.4 module there is a new received frame in the skb with +the RF Link Quality Indicator (LQI) from the hardware device. + +.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling): + +Telling 802.15.4 module the frame in the skb is or going to be +transmitted through the hardware device The device driver must implement the following callbacks in the IEEE 802.15.4 -operations structure at least: -struct ieee802154_ops { - ... - int (*start)(struct ieee802154_hw *hw); - void (*stop)(struct ieee802154_hw *hw); - ... - int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); - int (*ed)(struct ieee802154_hw *hw, u8 *level); - int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); - ... -}; - - - int start(struct ieee802154_hw *hw): - handler that 802.15.4 module calls for the hardware device initialization. - - - void stop(struct ieee802154_hw *hw): - handler that 802.15.4 module calls for the hardware device cleanup. - - - int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): - handler that 802.15.4 module calls for each frame in the skb going to be - transmitted through the hardware device. - - - int ed(struct ieee802154_hw *hw, u8 *level): - handler that 802.15.4 module calls for Energy Detection from the hardware - device. - - - int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): - set radio for listening on specific channel of the hardware device. +operations structure at least:: -Moreover IEEE 802.15.4 device operations structure should be filled. + struct ieee802154_ops { + ... + int (*start)(struct ieee802154_hw *hw); + void (*stop)(struct ieee802154_hw *hw); + ... + int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); + int (*ed)(struct ieee802154_hw *hw, u8 *level); + int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); + ... + }; -Fake drivers -============ +.. c:function:: int start(struct ieee802154_hw *hw): -In addition there is a driver available which simulates a real device with -SoftMAC (fakelb - IEEE 802.15.4 loopback driver) interface. This option -provides a possibility to test and debug the stack without usage of real hardware. +Handler that 802.15.4 module calls for the hardware device initialization. -See sources in drivers/net/ieee802154 folder for more details. +.. c:function:: void stop(struct ieee802154_hw *hw): +Handler that 802.15.4 module calls for the hardware device cleanup. -6LoWPAN Linux implementation -============================ +.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): -The IEEE 802.15.4 standard specifies an MTU of 127 bytes, yielding about 80 -octets of actual MAC payload once security is turned on, on a wireless link -with a link throughput of 250 kbps or less. The 6LoWPAN adaptation format -[RFC4944] was specified to carry IPv6 datagrams over such constrained links, -taking into account limited bandwidth, memory, or energy resources that are -expected in applications such as wireless Sensor Networks. [RFC4944] defines -a Mesh Addressing header to support sub-IP forwarding, a Fragmentation header -to support the IPv6 minimum MTU requirement [RFC2460], and stateless header -compression for IPv6 datagrams (LOWPAN_HC1 and LOWPAN_HC2) to reduce the -relatively large IPv6 and UDP headers down to (in the best case) several bytes. +Handler that 802.15.4 module calls for each frame in the skb going to be +transmitted through the hardware device. -In September 2011 the standard update was published - [RFC6282]. -It deprecates HC1 and HC2 compression and defines IPHC encoding format which is -used in this Linux implementation. +.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level): -All the code related to 6lowpan you may find in files: net/6lowpan/* -and net/ieee802154/6lowpan/* +Handler that 802.15.4 module calls for Energy Detection from the hardware +device. -To setup a 6LoWPAN interface you need: -1. Add IEEE802.15.4 interface and set channel and PAN ID; -2. Add 6lowpan interface by command like: - # ip link add link wpan0 name lowpan0 type lowpan -3. Bring up 'lowpan0' interface +.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): + +Set radio for listening on specific channel of the hardware device. + +Moreover IEEE 802.15.4 device operations structure should be filled. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index b08cf145d5eb..f0da1b001514 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -25,6 +25,7 @@ Contents: device_drivers/intel/iavf device_drivers/intel/ice devlink-info-versions + ieee802154 kapi z8530book msg_zerocopy diff --git a/Documentation/networking/switchdev.txt b/Documentation/networking/switchdev.txt index 633dd1fd81b7..86174ce8cd13 100644 --- a/Documentation/networking/switchdev.txt +++ b/Documentation/networking/switchdev.txt @@ -371,22 +371,3 @@ The driver can monitor for updates to arp_tbl using the netevent notifier NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy to know when arp_tbl neighbor entries are purged from the port. - -Transaction item queue -^^^^^^^^^^^^^^^^^^^^^^ - -For switchdev ops attr_set and obj_add, there is a 2 phase transaction model -used. First phase is to "prepare" anything needed, including various checks, -memory allocation, etc. The goal is to handle the stuff that is not unlikely -to fail here. The second phase is to "commit" the actual changes. - -Switchdev provides an infrastructure for sharing items (for example memory -allocations) between the two phases. - -The object created by a driver in "prepare" phase and it is queued up by: -switchdev_trans_item_enqueue() -During the "commit" phase, the driver gets the object by: -switchdev_trans_item_dequeue() - -If a transaction is aborted during "prepare" phase, switchdev code will handle -cleanup of the queued-up objects. |