Doug / smarc-fsl-linux-kernel

Download as
Browse Code ยป

Commit 878fa89f97954337d1dc41f0ccc3a8b5f89cfbc7

Authored by Daniel Silverstone
Committed by Dmitry Eremin-Solenikov
1 parent dfd06fe824
Exists in master and in 7 other branches imx_3.0.35_4.1.0, imx_3.10.17_1.0.1_ga, imx_3.10.53_1.1.0_ga, imx_3.14.28_1.0.0_ga, smarc-imx_3.10.53_1.1.0_ga, smarc-imx_3.14.28_1.0.0_ga, smarc-l5.0.0_1.0.0-ga

IEEE80154: Add documentation to the IEEE80154 netlink and fakehard driver 

This adds some perfunctory documentation comments to the IEEE 802.15.4
fakehard.c driver (Fake hard MAC) and the nl802154.h (outgoing netlink messages)
header.

These comments are not necessarily complete, but they do reference the
IEEE 802.15.4-2006 document where possible.

Signed-off-by: Daniel Silverstone <dsilvers@simtec.co.uk>

Showing 2 changed files with 196 additions and 0 deletions Side-by-side Diff

drivers/ieee802154/fakehard.c
Diff comments   View file @ 878fa89
... ... @@ -31,6 +31,12 @@
31 31 #include <net/ieee802154/mac_def.h>
32 32 #include <net/ieee802154/nl802154.h>
33 33  
  34 +/**
  35 + * fake_get_pan_id - Retrieve the PAN ID of the device.
  36 + * @dev: The network device to retrieve the PAN of.
  37 + *
  38 + * Return the ID of the PAN from the PIB.
  39 + */
34 40 static u16 fake_get_pan_id(struct net_device *dev)
35 41 {
36 42 BUG_ON(dev->type != ARPHRD_IEEE802154);
... ... @@ -38,6 +44,14 @@
38 44 return 0xeba1;
39 45 }
40 46  
  47 +/**
  48 + * fake_get_short_addr - Retrieve the short address of the device.
  49 + * @dev: The network device to retrieve the short address of.
  50 + *
  51 + * Returns the IEEE 802.15.4 short-form address cached for this
  52 + * device. If the device has not yet had a short address assigned
  53 + * then this should return 0xFFFF to indicate a lack of association.
  54 + */
41 55 static u16 fake_get_short_addr(struct net_device *dev)
42 56 {
43 57 BUG_ON(dev->type != ARPHRD_IEEE802154);
... ... @@ -45,6 +59,19 @@
45 59 return 0x1;
46 60 }
47 61  
  62 +/**
  63 + * fake_get_dsn - Retrieve the DSN of the device.
  64 + * @dev: The network device to retrieve the DSN for.
  65 + *
  66 + * Returns the IEEE 802.15.4 DSN for the network device.
  67 + * The DSN is the sequence number which will be added to each
  68 + * packet or MAC command frame by the MAC during transmission.
  69 + *
  70 + * DSN means 'Data Sequence Number'.
  71 + *
  72 + * Note: This is in section 7.2.1.2 of the IEEE 802.15.4-2006
  73 + * document.
  74 + */
48 75 static u8 fake_get_dsn(struct net_device *dev)
49 76 {
50 77 BUG_ON(dev->type != ARPHRD_IEEE802154);
... ... @@ -52,6 +79,19 @@
52 79 return 0x00; /* DSN are implemented in HW, so return just 0 */
53 80 }
54 81  
  82 +/**
  83 + * fake_get_bsn - Retrieve the BSN of the device.
  84 + * @dev: The network device to retrieve the BSN for.
  85 + *
  86 + * Returns the IEEE 802.15.4 BSN for the network device.
  87 + * The BSN is the sequence number which will be added to each
  88 + * beacon frame sent by the MAC.
  89 + *
  90 + * BSN means 'Beacon Sequence Number'.
  91 + *
  92 + * Note: This is in section 7.2.1.2 of the IEEE 802.15.4-2006
  93 + * document.
  94 + */
55 95 static u8 fake_get_bsn(struct net_device *dev)
56 96 {
57 97 BUG_ON(dev->type != ARPHRD_IEEE802154);
... ... @@ -59,6 +99,19 @@
59 99 return 0x00; /* BSN are implemented in HW, so return just 0 */
60 100 }
61 101  
  102 +/**
  103 + * fake_assoc_req - Make an association request to the HW.
  104 + * @dev: The network device which we are associating to a network.
  105 + * @addr: The coordinator with which we wish to associate.
  106 + * @channel: The channel on which to associate.
  107 + * @cap: The capability information field to use in the association.
  108 + *
  109 + * Start an association with a coordinator. The coordinator's address
  110 + * and PAN ID can be found in @addr.
  111 + *
  112 + * Note: This is in section 7.3.1 and 7.5.3.1 of the IEEE
  113 + * 802.15.4-2006 document.
  114 + */
62 115 static int fake_assoc_req(struct net_device *dev,
63 116 struct ieee802154_addr *addr, u8 channel, u8 cap)
64 117 {
65 118  
66 119  
... ... @@ -67,18 +120,70 @@
67 120 IEEE802154_SUCCESS);
68 121 }
69 122  
  123 +/**
  124 + * fake_assoc_resp - Send an association response to a device.
  125 + * @dev: The network device on which to send the response.
  126 + * @addr: The address of the device to respond to.
  127 + * @short_addr: The assigned short address for the device (if any).
  128 + * @status: The result of the association request.
  129 + *
  130 + * Queue the association response of the coordinator to another
  131 + * device's attempt to associate with the network which we
  132 + * coordinate. This is then added to the indirect-send queue to be
  133 + * transmitted to the end device when it polls for data.
  134 + *
  135 + * Note: This is in section 7.3.2 and 7.5.3.1 of the IEEE
  136 + * 802.15.4-2006 document.
  137 + */
70 138 static int fake_assoc_resp(struct net_device *dev,
71 139 struct ieee802154_addr *addr, u16 short_addr, u8 status)
72 140 {
73 141 return 0;
74 142 }
75 143  
  144 +/**
  145 + * fake_disassoc_req - Disassociate a device from a network.
  146 + * @dev: The network device on which we're disassociating a device.
  147 + * @addr: The device to disassociate from the network.
  148 + * @reason: The reason to give to the device for being disassociated.
  149 + *
  150 + * This sends a disassociation notification to the device being
  151 + * disassociated from the network.
  152 + *
  153 + * Note: This is in section 7.5.3.2 of the IEEE 802.15.4-2006
  154 + * document, with the reason described in 7.3.3.2.
  155 + */
76 156 static int fake_disassoc_req(struct net_device *dev,
77 157 struct ieee802154_addr *addr, u8 reason)
78 158 {
79 159 return ieee802154_nl_disassoc_confirm(dev, IEEE802154_SUCCESS);
80 160 }
81 161  
  162 +/**
  163 + * fake_start_req - Start an IEEE 802.15.4 PAN.
  164 + * @dev: The network device on which to start the PAN.
  165 + * @addr: The coordinator address to use when starting the PAN.
  166 + * @channel: The channel on which to start the PAN.
  167 + * @bcn_ord: Beacon order.
  168 + * @sf_ord: Superframe order.
  169 + * @pan_coord: Whether or not we are the PAN coordinator or just
  170 + * requesting a realignment perhaps?
  171 + * @blx: Battery Life Extension feature bitfield.
  172 + * @coord_realign: Something to realign something else.
  173 + *
  174 + * If pan_coord is non-zero then this starts a network with the
  175 + * provided parameters, otherwise it attempts a coordinator
  176 + * realignment of the stated network instead.
  177 + *
  178 + * Note: This is in section 7.5.2.3 of the IEEE 802.15.4-2006
  179 + * document, with 7.3.8 describing coordinator realignment.
  180 + *
  181 + * Note: There is currently no way to notify the coordinator userland
  182 + * program of whether or not the PAN has started successfully. As
  183 + * such, the coordinator program cannot know when the MAC has
  184 + * completed starting the network and will simply have to assume
  185 + * completeness based on some form of time delay.
  186 + */
82 187 static int fake_start_req(struct net_device *dev, struct ieee802154_addr *addr,
83 188 u8 channel,
84 189 u8 bcn_ord, u8 sf_ord, u8 pan_coord, u8 blx,
... ... @@ -87,6 +192,21 @@
87 192 return 0;
88 193 }
89 194  
  195 +/**
  196 + * fake_scan_req - Start a channel scan.
  197 + * @dev: The network device on which to perform a channel scan.
  198 + * @type: The type of scan to perform.
  199 + * @channels: The channel bitmask to scan.
  200 + * @duration: How long to spend on each channel.
  201 + *
  202 + * This starts either a passive (energy) scan or an active (PAN) scan
  203 + * on the channels indicated in the @channels bitmask. The duration of
  204 + * the scan is measured in terms of superframe duration. Specifically,
  205 + * the scan will spend aBaseSuperFrameDuration * ((2^n) + 1) on each
  206 + * channel.
  207 + *
  208 + * Note: This is in section 7.5.2.1 of the IEEE 802.15.4-2006 document.
  209 + */
90 210 static int fake_scan_req(struct net_device *dev, u8 type, u32 channels,
91 211 u8 duration)
92 212 {
include/net/ieee802154/nl802154.h
Diff comments   View file @ 878fa89
... ... @@ -24,17 +24,93 @@
24 24 struct net_device;
25 25 struct ieee802154_addr;
26 26  
  27 +/**
  28 + * ieee802154_nl_assoc_indic - Notify userland of an association request.
  29 + * @dev: The network device on which this association request was
  30 + * received.
  31 + * @addr: The address of the device requesting association.
  32 + * @cap: The capability information field from the device.
  33 + *
  34 + * This informs a userland coordinator of a device requesting to
  35 + * associate with the PAN controlled by the coordinator.
  36 + *
  37 + * Note: This is in section 7.3.1 of the IEEE 802.15.4-2006 document.
  38 + */
27 39 int ieee802154_nl_assoc_indic(struct net_device *dev,
28 40 struct ieee802154_addr *addr, u8 cap);
  41 +
  42 +/**
  43 + * ieee802154_nl_assoc_confirm - Notify userland of association.
  44 + * @dev: The device which has completed association.
  45 + * @short_addr: The short address assigned to the device.
  46 + * @status: The status of the association.
  47 + *
  48 + * Inform userland of the result of an association request. If the
  49 + * association request included asking the coordinator to allocate
  50 + * a short address then it is returned in @short_addr.
  51 + *
  52 + * Note: This is in section 7.3.2 of the IEEE 802.15.4 document.
  53 + */
29 54 int ieee802154_nl_assoc_confirm(struct net_device *dev,
30 55 u16 short_addr, u8 status);
  56 +
  57 +/**
  58 + * ieee802154_nl_disassoc_indic - Notify userland of disassociation.
  59 + * @dev: The device on which disassociation was indicated.
  60 + * @addr: The device which is disassociating.
  61 + * @reason: The reason for the disassociation.
  62 + *
  63 + * Inform userland that a device has disassociated from the network.
  64 + *
  65 + * Note: This is in section 7.3.3 of the IEEE 802.15.4 document.
  66 + */
31 67 int ieee802154_nl_disassoc_indic(struct net_device *dev,
32 68 struct ieee802154_addr *addr, u8 reason);
  69 +
  70 +/**
  71 + * ieee802154_nl_disassoc_confirm - Notify userland of disassociation
  72 + * completion.
  73 + * @dev: The device on which disassociation was ordered.
  74 + * @status: The result of the disassociation.
  75 + *
  76 + * Inform userland of the result of requesting that a device
  77 + * disassociate, or the result of requesting that we disassociate from
  78 + * a PAN managed by another coordinator.
  79 + *
  80 + * Note: This is in section 7.1.4.3 of the IEEE 802.15.4 document.
  81 + */
33 82 int ieee802154_nl_disassoc_confirm(struct net_device *dev,
34 83 u8 status);
  84 +
  85 +/**
  86 + * ieee802154_nl_scan_confirm - Notify userland of completion of scan.
  87 + * @dev: The device which was instructed to scan.
  88 + * @status: The status of the scan operation.
  89 + * @scan_type: What type of scan was performed.
  90 + * @unscanned: Any channels that the device was unable to scan.
  91 + * @edl: The energy levels (if a passive scan).
  92 + *
  93 + *
  94 + * Note: This is in section 7.1.11 of the IEEE 802.15.4 document.
  95 + * Note: This API does not permit the return of an active scan result.
  96 + */
35 97 int ieee802154_nl_scan_confirm(struct net_device *dev,
36 98 u8 status, u8 scan_type, u32 unscanned,
37 99 u8 *edl/*, struct list_head *pan_desc_list */);
  100 +
  101 +/**
  102 + * ieee802154_nl_beacon_indic - Notify userland of a received beacon.
  103 + * @dev: The device on which a beacon was received.
  104 + * @panid: The PAN of the coordinator.
  105 + * @coord_addr: The short address of the coordinator on that PAN.
  106 + *
  107 + * Note: This is in section 7.1.5 of the IEEE 802.15.4 document.
  108 + * Note: This API does not provide extended information such as what
  109 + * channel the PAN is on or what the LQI of the beacon frame was on
  110 + * receipt.
  111 + * Note: This API cannot indicate a beacon frame for a coordinator
  112 + * operating in long addressing mode.
  113 + */
38 114 int ieee802154_nl_beacon_indic(struct net_device *dev, u16 panid,
39 115 u16 coord_addr);
40 116