Skip to content

Commit e639695

Browse files
fg-cfhcarlescufi
fg-cfh
authored and
carlescufi
committed
doc: ieee802154: mgmt: improved docs
Hides types in the IEEE 802.15.4 net_mgmt sub-API that are of no public interest and improves documentation of the remainder. All constants that are not meant to be used by applications have been hidden. Only the API actually being of relevance to application developers is now publicly visible and documented. Signed-off-by: Florian Grandel <[email protected]>
1 parent c315d13 commit e639695

File tree

2 files changed

+157
-76
lines changed

2 files changed

+157
-76
lines changed

‎doc/zephyr.doxyfile.in

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2368,6 +2368,8 @@ PREDEFINED = __DOXYGEN__ \
23682368
CONFIG_HEAP_MEM_POOL_SIZE \
23692369
CONFIG_MMU \
23702370
CONFIG_NET_L2_ETHERNET_MGMT \
2371+
CONFIG_NET_L2_IEEE802154_MGMT \
2372+
CONFIG_NET_L2_IEEE802154_SECURITY \
23712373
CONFIG_NET_MGMT_EVENT \
23722374
CONFIG_NET_SOCKETS_POSIX_NAMES \
23732375
CONFIG_NET_TCP \

‎include/zephyr/net/ieee802154_mgmt.h

Lines changed: 155 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
* @file
99
* @brief IEEE 802.15.4 Management interface public header
1010
*
11-
* All references to the standard in this file cite IEEE 802.15.4-2020.
11+
* @note All references to the standard in this file cite IEEE 802.15.4-2020.
1212
*/
1313

1414
#ifndef ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_
@@ -33,9 +33,15 @@ extern "C" {
3333
* Most of these commands are also accessible via shell commands. See the
3434
* shell's help feature (`shell> ieee802154 help`).
3535
*
36+
* @note All section, table and figure references are to the IEEE 802.15.4-2020
37+
* standard.
38+
*
3639
* @{
3740
*/
3841

42+
/**
43+
* @cond INTERNAL_HIDDEN
44+
*/
3945

4046
#define _NET_IEEE802154_LAYER NET_MGMT_LAYER_L2
4147
#define _NET_IEEE802154_CODE 0x154
@@ -44,176 +50,245 @@ extern "C" {
4450
NET_MGMT_LAYER_CODE(_NET_IEEE802154_CODE))
4551
#define _NET_IEEE802154_EVENT (_NET_IEEE802154_BASE | NET_MGMT_EVENT_BIT)
4652

47-
/* All attributes and parameters are given in CPU byte order
48-
* (scalars) or big endian (byte arrays) unless otherwise
49-
* specified.
53+
enum net_request_ieee802154_cmd {
54+
NET_REQUEST_IEEE802154_CMD_SET_ACK = 1,
55+
NET_REQUEST_IEEE802154_CMD_UNSET_ACK,
56+
NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN,
57+
NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN,
58+
NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN,
59+
NET_REQUEST_IEEE802154_CMD_ASSOCIATE,
60+
NET_REQUEST_IEEE802154_CMD_DISASSOCIATE,
61+
NET_REQUEST_IEEE802154_CMD_SET_CHANNEL,
62+
NET_REQUEST_IEEE802154_CMD_GET_CHANNEL,
63+
NET_REQUEST_IEEE802154_CMD_SET_PAN_ID,
64+
NET_REQUEST_IEEE802154_CMD_GET_PAN_ID,
65+
NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR,
66+
NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR,
67+
NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR,
68+
NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR,
69+
NET_REQUEST_IEEE802154_CMD_GET_TX_POWER,
70+
NET_REQUEST_IEEE802154_CMD_SET_TX_POWER,
71+
NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS,
72+
NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS,
73+
};
74+
75+
/**
76+
* INTERNAL_HIDDEN @endcond
77+
*/
78+
79+
/**
80+
* @name Command Macros
81+
*
82+
* @brief IEEE 802.15.4 net management commands.
83+
*
84+
* @details These IEEE 802.15.4 subsystem net management commands can be called
85+
* by applications via @ref net_mgmt macro.
5086
*
51-
* The following IEEE 802.15.4 MAC management service primitives
52-
* are referenced below:
87+
* All attributes and parameters are given in CPU byte order (scalars) or big
88+
* endian (byte arrays) unless otherwise specified.
89+
*
90+
* The following IEEE 802.15.4 MAC management service primitives are referenced
91+
* in this enumeration:
5392
* - MLME-ASSOCIATE.request, see section 8.2.3
5493
* - MLME-DISASSOCIATE.request, see section 8.2.4
5594
* - MLME-SET/GET.request, see section 8.2.6
5695
* - MLME-SCAN.request, see section 8.2.11
5796
*
58-
* The following IEEE 802.15.4 MAC data service primitives
59-
* are referenced below:
97+
* The following IEEE 802.15.4 MAC data service primitives are referenced in
98+
* this enumeration:
6099
* - MLME-DATA.request, see section 8.3.2
61100
*
62101
* MAC PIB attributes (mac.../sec...): see sections 8.4.3 and 9.5.
63102
* PHY PIB attributes (phy...): see section 11.3.
64103
* Both are accessed through MLME-SET/GET primitives.
104+
*
105+
* @{
65106
*/
66-
enum net_request_ieee802154_cmd {
67-
NET_REQUEST_IEEE802154_CMD_SET_ACK = 1, /* sets AckTx for all subsequent
68-
* MLME-DATA (aka TX) requests
69-
*/
70-
NET_REQUEST_IEEE802154_CMD_UNSET_ACK, /* unsets AckTx for all subsequent
71-
* MLME-DATA requests
72-
*/
73-
NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN, /* MLME-SCAN(PASSIVE, ...) request */
74-
NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN, /* MLME-SCAN(ACTIVE, ...) request */
75-
NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN, /* not-standard */
76-
NET_REQUEST_IEEE802154_CMD_ASSOCIATE, /* MLME-ASSOCIATE(...) request */
77-
NET_REQUEST_IEEE802154_CMD_DISASSOCIATE, /* MLME-DISASSOCIATE(...) request */
78-
NET_REQUEST_IEEE802154_CMD_SET_CHANNEL, /* MLME-SET(phyCurrentChannel) request */
79-
NET_REQUEST_IEEE802154_CMD_GET_CHANNEL, /* MLME-GET(phyCurrentChannel) request */
80-
NET_REQUEST_IEEE802154_CMD_SET_PAN_ID, /* MLME-SET(macPanId) request */
81-
NET_REQUEST_IEEE802154_CMD_GET_PAN_ID, /* MLME-GET(macPanId) request */
82-
NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR, /* non-standard, see chapters 7.1 and 8.4.3.1, in
83-
* big endian byte order
84-
*/
85-
NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR, /* like MLME-GET(macExtendedAddress) but in big
86-
* endian byte order
87-
*/
88-
NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR, /* MLME-SET(macShortAddress) request, only
89-
* allowed for co-ordinators
90-
*/
91-
NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR, /* MLME-GET(macShortAddress) request */
92-
NET_REQUEST_IEEE802154_CMD_GET_TX_POWER, /* MLME-SET(phyUnicastTxPower/phyBroadcastTxPower)
93-
* request (currently not distinguished)
94-
*/
95-
NET_REQUEST_IEEE802154_CMD_SET_TX_POWER, /* MLME-GET(phyUnicastTxPower/phyBroadcastTxPower)
96-
* request
97-
*/
98-
99-
NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS, /* implies macSecurityEnabled=true,
100-
* configures basic sec* MAC PIB
101-
* attributes
102-
*/
103-
NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS, /* gets the configured sec* attributes */
104-
};
105-
106107

107-
#define NET_REQUEST_IEEE802154_SET_ACK \
108-
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_ACK)
108+
/** Sets AckTx for all subsequent MLME-DATA (aka TX) requests. */
109+
#define NET_REQUEST_IEEE802154_SET_ACK (_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_ACK)
109110

110111
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_ACK);
111112

112-
#define NET_REQUEST_IEEE802154_UNSET_ACK \
113+
/** Unsets AckTx for all subsequent MLME-DATA requests. */
114+
#define NET_REQUEST_IEEE802154_UNSET_ACK \
113115
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_UNSET_ACK)
114116

115117
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_UNSET_ACK);
116118

117-
#define NET_REQUEST_IEEE802154_PASSIVE_SCAN \
119+
/**
120+
* MLME-SCAN(PASSIVE, ...) request
121+
*
122+
* See @ref ieee802154_req_params for associated command parameters.
123+
*/
124+
#define NET_REQUEST_IEEE802154_PASSIVE_SCAN \
118125
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN)
119126

120127
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_PASSIVE_SCAN);
121128

122-
#define NET_REQUEST_IEEE802154_ACTIVE_SCAN \
129+
/**
130+
* MLME-SCAN(ACTIVE, ...) request
131+
*
132+
* See @ref ieee802154_req_params for associated command parameters.
133+
*/
134+
#define NET_REQUEST_IEEE802154_ACTIVE_SCAN \
123135
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN)
124136

125137
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_ACTIVE_SCAN);
126138

127-
#define NET_REQUEST_IEEE802154_CANCEL_SCAN \
139+
/** Cancels an ongoing MLME-SCAN(...) command (non-standard). */
140+
#define NET_REQUEST_IEEE802154_CANCEL_SCAN \
128141
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN)
129142

130143
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_CANCEL_SCAN);
131144

132-
#define NET_REQUEST_IEEE802154_ASSOCIATE \
145+
/** MLME-ASSOCIATE(...) request */
146+
#define NET_REQUEST_IEEE802154_ASSOCIATE \
133147
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_ASSOCIATE)
134148

135149
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_ASSOCIATE);
136150

137-
#define NET_REQUEST_IEEE802154_DISASSOCIATE \
151+
/** MLME-DISASSOCIATE(...) request */
152+
#define NET_REQUEST_IEEE802154_DISASSOCIATE \
138153
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_DISASSOCIATE)
139154

140155
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_DISASSOCIATE);
141156

142-
#define NET_REQUEST_IEEE802154_SET_CHANNEL \
157+
/** MLME-SET(phyCurrentChannel) request */
158+
#define NET_REQUEST_IEEE802154_SET_CHANNEL \
143159
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_CHANNEL)
144160

145161
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_CHANNEL);
146162

147-
#define NET_REQUEST_IEEE802154_GET_CHANNEL \
163+
/** MLME-GET(phyCurrentChannel) request */
164+
#define NET_REQUEST_IEEE802154_GET_CHANNEL \
148165
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_CHANNEL)
149166

150167
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_CHANNEL);
151168

152-
#define NET_REQUEST_IEEE802154_SET_PAN_ID \
169+
/** MLME-SET(macPanId) request */
170+
#define NET_REQUEST_IEEE802154_SET_PAN_ID \
153171
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_PAN_ID)
154172

155173
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_PAN_ID);
156174

157-
#define NET_REQUEST_IEEE802154_GET_PAN_ID \
175+
/** MLME-GET(macPanId) request */
176+
#define NET_REQUEST_IEEE802154_GET_PAN_ID \
158177
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_PAN_ID)
159178

160179
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_PAN_ID);
161180

162-
#define NET_REQUEST_IEEE802154_SET_EXT_ADDR \
181+
/**
182+
* Sets the extended interface address (non-standard), see sections 7.1
183+
* and 8.4.3.1, in big endian byte order
184+
*/
185+
#define NET_REQUEST_IEEE802154_SET_EXT_ADDR \
163186
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR)
164187

165188
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_EXT_ADDR);
166189

167-
#define NET_REQUEST_IEEE802154_GET_EXT_ADDR \
190+
/** like MLME-GET(macExtendedAddress) but in big endian byte order */
191+
#define NET_REQUEST_IEEE802154_GET_EXT_ADDR \
168192
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR)
169193

170194
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_EXT_ADDR);
171195

172-
#define NET_REQUEST_IEEE802154_SET_SHORT_ADDR \
196+
/** MLME-SET(macShortAddress) request, only allowed for co-ordinators */
197+
#define NET_REQUEST_IEEE802154_SET_SHORT_ADDR \
173198
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR)
174199

175200
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_SHORT_ADDR);
176201

177-
#define NET_REQUEST_IEEE802154_GET_SHORT_ADDR \
202+
/** MLME-GET(macShortAddress) request */
203+
#define NET_REQUEST_IEEE802154_GET_SHORT_ADDR \
178204
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR)
179205

180206
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_SHORT_ADDR);
181207

182-
#define NET_REQUEST_IEEE802154_GET_TX_POWER \
183-
(_NET_IEEE802154_BASE | \
184-
NET_REQUEST_IEEE802154_CMD_GET_TX_POWER)
208+
/**
209+
* MLME-SET(phyUnicastTxPower/phyBroadcastTxPower) request (currently
210+
* not distinguished)
211+
*/
212+
#define NET_REQUEST_IEEE802154_GET_TX_POWER \
213+
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_TX_POWER)
185214

186215
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_TX_POWER);
187216

188-
#define NET_REQUEST_IEEE802154_SET_TX_POWER \
189-
(_NET_IEEE802154_BASE | \
190-
NET_REQUEST_IEEE802154_CMD_SET_TX_POWER)
217+
/** MLME-GET(phyUnicastTxPower/phyBroadcastTxPower) request */
218+
#define NET_REQUEST_IEEE802154_SET_TX_POWER \
219+
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_TX_POWER)
191220

192221
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_TX_POWER);
193222

194223
#ifdef CONFIG_NET_L2_IEEE802154_SECURITY
195224

196-
#define NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS \
197-
(_NET_IEEE802154_BASE | \
198-
NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS)
225+
/**
226+
* Configures basic sec* MAC PIB attributes, implies
227+
* macSecurityEnabled=true.
228+
*
229+
* See @ref ieee802154_security_params for associated command parameters.
230+
*/
231+
#define NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS \
232+
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS)
199233

200234
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS);
201235

202-
#define NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS \
203-
(_NET_IEEE802154_BASE | \
204-
NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS)
236+
/**
237+
* Gets the configured sec* attributes.
238+
*
239+
* See @ref ieee802154_security_params for associated command parameters.
240+
*/
241+
#define NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS \
242+
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS)
205243

206244
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS);
207245

208246
#endif /* CONFIG_NET_L2_IEEE802154_SECURITY */
209247

248+
/**
249+
* @}
250+
*/
251+
252+
/**
253+
* @cond INTERNAL_HIDDEN
254+
*/
255+
210256
enum net_event_ieee802154_cmd {
211257
NET_EVENT_IEEE802154_CMD_SCAN_RESULT = 1,
212258
};
213259

260+
/**
261+
* INTERNAL_HIDDEN @endcond
262+
*/
263+
264+
/**
265+
* @name Event Macros
266+
*
267+
* @brief IEEE 802.15.4 net management events.
268+
*
269+
* @details These IEEE 802.15.4 subsystem net management events can be
270+
* subscribed to by applications via @ref net_mgmt_init_event_callback, @ref
271+
* net_mgmt_add_event_callback and @ref net_mgmt_del_event_callback.
272+
*
273+
* @{
274+
*/
275+
276+
/**
277+
* Signals the result of the @ref NET_REQUEST_IEEE802154_ACTIVE_SCAN or @ref
278+
* NET_REQUEST_IEEE802154_PASSIVE_SCAN net management commands.
279+
*
280+
* See @ref ieee802154_req_params for associated event parameters.
281+
*/
214282
#define NET_EVENT_IEEE802154_SCAN_RESULT \
215283
(_NET_IEEE802154_EVENT | NET_EVENT_IEEE802154_CMD_SCAN_RESULT)
216284

285+
/**
286+
* @}
287+
*/
288+
289+
/**
290+
* @cond INTERNAL_HIDDEN
291+
*/
217292

218293
#define IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan) \
219294
(_channel_set & BIT(_chan - 1))
@@ -222,6 +297,10 @@ enum net_event_ieee802154_cmd {
222297

223298
#define IEEE802154_ALL_CHANNELS UINT32_MAX
224299

300+
/**
301+
* INTERNAL_HIDDEN @endcond
302+
*/
303+
225304
/**
226305
* @brief Scanning parameters
227306
*

0 commit comments

Comments
 (0)