Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) IEEE 802.15.4 Developer's Guide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) The IEEE 802.15.4 working group focuses on standardization of the bottom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) two layers: Medium Access Control (MAC) and Physical access (PHY). And there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) are mainly two options available for upper layers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) - ZigBee - proprietary protocol from the ZigBee Alliance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) - 6LoWPAN - IPv6 networking over low rate personal area networks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) The goal of the Linux-wpan is to provide a complete implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) of the IEEE 802.15.4 and 6LoWPAN protocols. IEEE 802.15.4 is a stack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) of protocols for organizing Low-Rate Wireless Personal Area Networks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) The stack is composed of three main parts:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) - IEEE 802.15.4 layer;  We have chosen to use plain Berkeley socket API,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21)   the generic Linux networking stack to transfer IEEE 802.15.4 data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22)   messages and a special protocol over netlink for configuration/management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) - MAC - provides access to shared channel and reliable data delivery
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) - PHY - represents device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) Socket API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31)     int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) The address family, socket addresses etc. are defined in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) include/net/af_ieee802154.h header or in the special header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) in the userspace package (see either https://linux-wpan.org/wpan-tools.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) or the git tree at https://github.com/linux-wpan/wpan-tools).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) 6LoWPAN Linux implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) The IEEE 802.15.4 standard specifies an MTU of 127 bytes, yielding about 80
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) octets of actual MAC payload once security is turned on, on a wireless link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) with a link throughput of 250 kbps or less.  The 6LoWPAN adaptation format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) [RFC4944] was specified to carry IPv6 datagrams over such constrained links,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) taking into account limited bandwidth, memory, or energy resources that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) expected in applications such as wireless Sensor Networks.  [RFC4944] defines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) a Mesh Addressing header to support sub-IP forwarding, a Fragmentation header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) to support the IPv6 minimum MTU requirement [RFC2460], and stateless header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) compression for IPv6 datagrams (LOWPAN_HC1 and LOWPAN_HC2) to reduce the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) relatively large IPv6 and UDP headers down to (in the best case) several bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) In September 2011 the standard update was published - [RFC6282].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) It deprecates HC1 and HC2 compression and defines IPHC encoding format which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) used in this Linux implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) All the code related to 6lowpan you may find in files: net/6lowpan/*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) and net/ieee802154/6lowpan/*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) To setup a 6LoWPAN interface you need:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 1. Add IEEE802.15.4 interface and set channel and PAN ID;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) 2. Add 6lowpan interface by command like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) # ip link add link wpan0 name lowpan0 type lowpan
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 3. Bring up 'lowpan0' interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) Like with WiFi, there are several types of devices implementing IEEE 802.15.4.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 1) 'HardMAC'. The MAC layer is implemented in the device itself, the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) exports a management (e.g. MLME) and data API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 2) 'SoftMAC' or just radio. These types of devices are just radio transceivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) possibly with some kinds of acceleration like automatic CRC computation and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) comparation, automagic ACK handling, address matching, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) Those types of devices require different approach to be hooked into Linux kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) HardMAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) See the header include/net/ieee802154_netdev.h. You have to implement Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) code via plain sk_buffs. On skb reception skb->cb must contain additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) info as described in the struct ieee802154_mac_cb. During packet transmission
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) the skb->cb is used to provide additional data to device's header_ops->create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) function. Be aware that this data can be overridden later (when socket code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) submits skb to qdisc), so if you need something from that cb later, you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) store info in the skb->data on your own.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) To hook the MLME interface you have to populate the ml_priv field of your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) net_device with a pointer to struct ieee802154_mlme_ops instance. The fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) assoc_req, assoc_resp, disassoc_req, start_req, and scan_req are optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) All other fields are required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) SoftMAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) The MAC is the middle layer in the IEEE 802.15.4 Linux stack. This moment it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) provides interface for drivers registration and management of slave interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) NOTE: Currently the only monitor device type is supported - it's IEEE 802.15.4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) stack interface for network sniffers (e.g. WireShark).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) This layer is going to be extended soon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) See header include/net/mac802154.h and several drivers in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) drivers/net/ieee802154/.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) Fake drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) In addition there is a driver available which simulates a real device with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) SoftMAC (fakelb - IEEE 802.15.4 loopback driver) interface. This option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) provides a possibility to test and debug the stack without usage of real hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Device drivers API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) The include/net/mac802154.h defines following functions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) .. c:function:: struct ieee802154_dev *ieee802154_alloc_device (size_t priv_size, struct ieee802154_ops *ops)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Allocation of IEEE 802.15.4 compatible device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) .. c:function:: void ieee802154_free_device(struct ieee802154_dev *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) Freeing allocated device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) .. c:function:: int ieee802154_register_device(struct ieee802154_dev *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Register PHY in the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) .. c:function:: void ieee802154_unregister_device(struct ieee802154_dev *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Freeing registered PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) .. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Telling 802.15.4 module there is a new received frame in the skb with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) the RF Link Quality Indicator (LQI) from the hardware device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) .. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Telling 802.15.4 module the frame in the skb is or going to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) transmitted through the hardware device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) The device driver must implement the following callbacks in the IEEE 802.15.4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) operations structure at least::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)    struct ieee802154_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)         ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)         int     (*start)(struct ieee802154_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)         void    (*stop)(struct ieee802154_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)         ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)         int     (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)         int     (*ed)(struct ieee802154_hw *hw, u8 *level);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)         int     (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)         ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)    };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) .. c:function:: int start(struct ieee802154_hw *hw)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Handler that 802.15.4 module calls for the hardware device initialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) .. c:function:: void stop(struct ieee802154_hw *hw)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) Handler that 802.15.4 module calls for the hardware device cleanup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) .. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) Handler that 802.15.4 module calls for each frame in the skb going to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) transmitted through the hardware device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) .. c:function:: int ed(struct ieee802154_hw *hw, u8 *level)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) Handler that 802.15.4 module calls for Energy Detection from the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) .. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Set radio for listening on specific channel of the hardware device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) Moreover IEEE 802.15.4 device operations structure should be filled.