RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity

Merge pull request #8655 from gebart/pr/netopt-docs

Browse Source 
netopt: Clarify documentation
This commit is contained in:
Joakim Nohlgård 2018-03-29 20:28:31 +02:00 committed by GitHub
commit 59d6f10cf6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 250 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

441
sys/include/net/netopt.h
View File

@ -8,7 +8,7 @@
*/
/**
* @defgroup net_netopt Configuration options for network APIs
* @defgroup net_netopt Netopt - Configuration options for network APIs
* @ingroup net
* @brief List of available configuration options for the
* @ref drivers_netdev_api and the @ref net_gnrc_netapi
@ -32,40 +32,69 @@ extern "C" {
/**
* @brief Global list of configuration options available throughout the
* network stack, e.g. by netdev and netapi
*
* The data type specified in parentheses for each individual option is the
* data type to use for the argument when getting/setting the value of the option.
*
* All arguments longer than 1 byte (e.g. uint16_t) are given in host byte order
* unless anything else is specified below.
*/
typedef enum {
NETOPT_CHANNEL, /**< get/set channel as uint16_t in host
* byte order */
NETOPT_IS_CHANNEL_CLR, /**< check if channel is clear */
NETOPT_ADDRESS, /**< get/set address in host byte order */
/**
* @brief (uint16_t) channel number
*/
NETOPT_CHANNEL,
/**
* @brief (@ref netopt_enable_t) check whether the network medium is clear
*
* Getting this option can be used to trigger a manual clear channel
* assessment (CCA) on some wireless devices.
*/
NETOPT_IS_CHANNEL_CLR,
/**
* @brief (byte array, see below) link layer address in network byte order
*
* Device type | Length | Meaning
* ------------- | ------ | -----
* IEEE 802.15.4 | 2 | device short address
* Ethernet | 6 | device MAC address
* nrfmin | 2 | device short address
* CC110x | 1 | device address
*/
NETOPT_ADDRESS,
/**
* @brief get/set long address in host byte order
* @brief (byte array, see below) long link layer address in network byte order
*
* Examples for this include the EUI-64 in IEEE 802.15.4
* Device type | Length | Meaning
* ------------- | -------- | -----
* IEEE 802.15.4 | 8 | device long address (EUI-64), @ref eui64_t
* nrfmin | 8 | device long address (based on short address)
* BLE | 8 | device long address (EUI-64), @ref eui64_t
*/
NETOPT_ADDRESS_LONG,
NETOPT_ADDR_LEN, /**< get the default address length a
* network device expects as uint16_t in
* host byte order */
NETOPT_SRC_LEN, /**< get/set the address length to choose
* for the network device's source address
* as uint16_t in host byte order */
/**
* @brief get/set the network ID as uint16_t in host byte order
* @brief (uint16_t) get the default address length a network device expects
*/
NETOPT_ADDR_LEN,
/**
* @brief (uint16_t) address length to use for the link layer source address
*/
NETOPT_SRC_LEN,
/**
* @brief (uint16_t) network ID
*
* Examples for this include the PAN ID in IEEE 802.15.4
*/
NETOPT_NID,
/**
* @brief get/set hop limit as uint8_t
* @brief (uint8_t) hop limit
*/
NETOPT_HOP_LIMIT,
/**
* @brief get the IPv6 interface identifier of a network interface as
* eui64_t.
* @brief (@ref eui64_t) get the IPv6 interface identifier of a network interface
*
* @see <a href="https://tools.ietf.org/html/rfc4291#section-2.5.1">
* RFC 4291, section 2.5.1
@ -80,26 +109,27 @@ typedef enum {
NETOPT_IPV6_IID,
/**
* @brief get IPv6 addresses of an interface as array of @ref ipv6_addr_t
* or add an IPv6 address as @ref ipv6_addr_t to an interface
* @brief (@ref ipv6_addr_t[]) get IPv6 addresses of an interface as array
* of @ref ipv6_addr_t or add an IPv6 address as @ref ipv6_addr_t
* to an interface
*
* When adding an IPv6 address to a GNRC interface using
* @ref GNRC_NETAPI_MSG_TYPE_SET, the gnrc_netapi_opt_t::context field can
* be used to pass the prefix length (8 MSB) and some flags (8 LSB)
* according to @ref net_gnrc_netif_ipv6_addrs_flags. The address is however always
* considered to be manually added.
* according to @ref net_gnrc_netif_ipv6_addrs_flags. The address is however
* always considered to be manually added.
* When getting the option you can pass an array of @ref ipv6_addr_t of any
* length greater than 0 to the getter. The array will be filled up to to
* its maximum and the remaining addresses on the interface will be ignored
*/
NETOPT_IPV6_ADDR,
/**
* @brief Removes an IPv6 address as @ref ipv6_addr_t from an interface
* @brief (@ref ipv6_addr_t) Removes an IPv6 address from an interface
*/
NETOPT_IPV6_ADDR_REMOVE,
/**
* @brief get the flags to the addresses returned by @ref NETOPT_IPV6_ADDR
* as array of uint8_t
* @brief (array of uint8_t) get the flags to the addresses returned by
* @ref NETOPT_IPV6_ADDR as array
*
* The information contained in the array is very specific to the
* interface's API. For GNRC e.g. the values are according to
@ -107,8 +137,8 @@ typedef enum {
*/
NETOPT_IPV6_ADDR_FLAGS,
/**
* @brief get IPv6 multicast groups of an interface as array of
* @ref ipv6_addr_t or join an IPv6 multicast group as
* @brief (@ref ipv6_addr_t) get IPv6 multicast groups of an interface as
* array of @ref ipv6_addr_t or join an IPv6 multicast group as
* @ref ipv6_addr_t on an interface
*
* When adding an IPv6 address to a GNRC interface using
@ -122,50 +152,72 @@ typedef enum {
*/
NETOPT_IPV6_GROUP,
/**
* @brief Leaves an IPv6 multicast group as @ref ipv6_addr_t on an
* interface
* @brief (@ref ipv6_addr_t) Leave an IPv6 multicast group on an interface
*/
NETOPT_IPV6_GROUP_LEAVE,
NETOPT_IPV6_FORWARDING, /**< en/disable IPv6 forwarding or read the
* current state */
NETOPT_IPV6_SND_RTR_ADV, /**< en/disable sending of IPv6 router
* advertisements or read the current state */
NETOPT_TX_POWER, /**< get/set the output power for radio
* devices in dBm as int16_t in host byte
* order */
NETOPT_MAX_PACKET_SIZE, /**< get/set the maximum packet size a
* network module can handle as uint16_t
* in host byte order */
/**
* @brief en/disable preloading or read the current state.
* @brief (@ref netopt_enable_t) IPv6 forwarding state
*/
NETOPT_IPV6_FORWARDING,
/**
* @brief (@ref netopt_enable_t) sending of IPv6 router advertisements
*/
NETOPT_IPV6_SND_RTR_ADV,
/**
* @brief (int16_t) transmit power for radio devices in dBm
*/
NETOPT_TX_POWER,
/**
* @brief (uint16_t) maximum packet size a network module can handle
*/
NETOPT_MAX_PACKET_SIZE,
/**
* @brief (@ref netopt_enable_t) frame preloading
*
* Preload using gnrc_netdev_driver_t::send_data() or gnrc_netapi_send()
* respectively, send setting state to @ref NETOPT_STATE_TX
* Preload frame data using gnrc_netdev_driver_t::send_data() or gnrc_netapi_send(),
* trigger sending by setting state to @ref NETOPT_STATE_TX
*/
NETOPT_PRELOADING,
NETOPT_PROMISCUOUSMODE, /**< en/disable promiscuous mode or read
* the current state */
NETOPT_AUTOACK, /**< en/disable link layer auto ACKs or read
* the current state */
NETOPT_ACK_PENDING, /**< en/disable the frame pending bit of ACKs.
* This bit is copied into the frame pending
* subfield of the ACK if it is the response
* to a data request MAC command frame, which
* lets the data request sender know if the ACK
* sender has pending data or not. */
NETOPT_ACK_REQ, /**< en/disable acknowledgement requests or
* read the current state */
NETOPT_RETRANS, /**< get/set the maximum number of
* retransmissions. */
NETOPT_PROTO, /**< get/set the protocol for the layer
* as type gnrc_nettype_t. */
NETOPT_STATE, /**< get/set the state of network devices as
* type netopt_state_t */
NETOPT_RAWMODE, /**< en/disable the pre-processing of data
* in a network device driver as type
* gnrc_nettype_t */
/**
* @brief en/disable the interrupt at reception start.
* @brief (@ref netopt_enable_t) promiscuous mode
*/
NETOPT_PROMISCUOUSMODE,
/**
* @brief (@ref netopt_enable_t) automatic link layer ACKs
*/
NETOPT_AUTOACK,
/**
* @brief (@ref netopt_enable_t) frame pending bit of ACKs
*
* For IEEE 802.15.4, this bit is copied into the frame pending subfield of
* the ACK if it is the response to a data request MAC command frame.
*/
NETOPT_ACK_PENDING,
/**
* @brief (@ref netopt_enable_t) acknowledgement request on outgoing frames
*
* For IEEE 802.15.4, this bit is copied into the ACK req subfield of the
* frame control field.
*/
NETOPT_ACK_REQ,
/**
* @brief (uint8_t) maximum number of retransmissions
*/
NETOPT_RETRANS,
/**
* @brief (@ref gnrc_nettype_t) the protocol for the layer
*/
NETOPT_PROTO,
/**
* @brief (@ref netopt_state_t) state of network device
*/
NETOPT_STATE,
/**
* @brief (@ref netopt_enable_t) when enabled, bypass protocol processing of incoming frames
*/
NETOPT_RAWMODE,
/**
* @brief (@ref netopt_enable_t) trigger interrupt at reception start
*
* It is mostly triggered after the preamble is correctly received
*
@ -174,9 +226,9 @@ typedef enum {
NETOPT_RX_START_IRQ,
/**
* @brief en/disable the interrupt after packet reception.
* @brief (@ref netopt_enable_t) trigger interrupt after frame reception
*
* This interrupt is triggered after a complete packet is received.
* This interrupt is triggered after a complete frame is received.
*
* @note in case a transceiver does not support this interrupt, the event
* may be triggered by the driver
@ -184,10 +236,10 @@ typedef enum {
NETOPT_RX_END_IRQ,
/**
* @brief en/disable the interrupt right in the beginning of transmission.
* @brief (@ref netopt_enable_t) trigger interrupt at transmission start
*
* This interrupt is triggered when the transceiver starts to send out the
* packet.
* frame.
*
* @note in case a transceiver does not support this interrupt, the event
* may be triggered by the driver
@ -195,16 +247,16 @@ typedef enum {
NETOPT_TX_START_IRQ,
/**
* @brief en/disable the interrupt after packet transmission.
* @brief (@ref netopt_enable_t) trigger interrupt after frame transmission
*
* This interrupt is triggered when the full packet is transmitted.
* This interrupt is triggered when the full frame has been transmitted.
*
* @note not all transceivers may support this interrupt
*/
NETOPT_TX_END_IRQ,
/**
* @brief Check automatically before sending if the channel is clear.
* @brief (@ref netopt_enable_t) perform channel clear assessment before transmitting
*
* This may be a hardware feature of the given transceiver, or might be
* otherwise implemented in software. If the device supports CSMA this
@ -213,69 +265,10 @@ typedef enum {
*
* @note Be sure not to set NETOPT_CSMA simultaneously.
*
* TODO: How to get feedback?
* @todo How to get feedback?
*/
NETOPT_AUTOCCA,
/**
* @brief en/disable CSMA/CA support
*
* If the device supports CSMA in hardware, this option enables it with
* default parameters. For further configuration refer to the other
* NETOPT_CSMA_* options.
*/
NETOPT_CSMA,
/**
* @brief get/set the maximum number of CSMA retries
*
* (uint8_t)
* The maximum number of backoffs the CSMA-CA algorithm will attempt before
* declaring a channel access failure. Named macMaxCsmaBackoffs in
* IEEE Std 802.15.4-2015.
*
* 802.15.4 default: 4
*/
NETOPT_CSMA_RETRIES,
/**
* @brief get/set the maximum backoff exponent for the CSMA-CA algorithm
*
* (uint8_t) Named macMaxBE in IEEE Std 802.15.4-2015.
*
* 802.15.4 default: 5
*/
NETOPT_CSMA_MAXBE,
/**
* @brief get/set the minimum backoff exponent for the CSMA-CA algorithm
*
* (uint8_t) Named macMinBE in IEEE Std 802.15.4-2015.
*
* 802.15.4 default: 3
*/
NETOPT_CSMA_MINBE,
/**
* @brief en/disable blocking of radio sleep when running a duty cycling MAC layer
*
* (netopt_enable_t) Enabling this option tells the MAC layer to never put
* the radio to sleep. Useful in gateways and routers not running on
* batteries to improve responsiveness and allow battery powered nodes on
* the same network to sleep more often.
*/
NETOPT_MAC_NO_SLEEP,
/**
* @brief read-only check for a wired interface.
*
* If the interface is wireless this function will return -ENOTSUP, a
* positive value otherwise.
*
* @note Setting this option will always return -ENOTSUP.
*/
NETOPT_IS_WIRED,
/**
* @brief (@ref netopt_enable_t) Phy link status.
*
@ -289,43 +282,101 @@ typedef enum {
NETOPT_LINK_CONNECTED,
/**
* @brief get a device's "type", e.g., ethernet, 802.15.4, ...
* @brief (@ref netopt_enable_t) CSMA/CA support
*
* If the device supports CSMA in hardware, this option enables it with
* default parameters. For further configuration refer to the other
* NETOPT_CSMA_* options.
*/
NETOPT_CSMA,
/**
* @brief (uint8_t) maximum number of CSMA retries
*
* The maximum number of backoffs the CSMA-CA algorithm will attempt before
* declaring a channel access failure. Named macMaxCsmaBackoffs in
* IEEE Std 802.15.4-2015.
*
* IEEE 802.15.4 default: 4
*/
NETOPT_CSMA_RETRIES,
/**
* @brief (uint8_t) maximum backoff exponent for the CSMA-CA algorithm
*
* Named macMaxBE in IEEE Std 802.15.4-2015.
*
* IEEE 802.15.4 default: 5
*/
NETOPT_CSMA_MAXBE,
/**
* @brief (uint8_t) minimum backoff exponent for the CSMA-CA algorithm
*
* Named macMinBE in IEEE Std 802.15.4-2015.
*
* IEEE 802.15.4 default: 3
*/
NETOPT_CSMA_MINBE,
/**
* @brief (@ref netopt_enable_t) block transceiver sleep
*
* Enabling this option tells the MAC layer to never put the radio to sleep.
* Useful in gateways and routers not running on batteries to improve
* responsiveness and allow battery powered nodes on the same network to
* sleep more often.
*/
NETOPT_MAC_NO_SLEEP,
/**
* @brief (@ref netopt_enable_t) read-only check for a wired interface.
*
* This option will return -ENOTSUP for wireless interfaces.
*
* @note Setting this option will always return -ENOTSUP.
*/
NETOPT_IS_WIRED,
/**
* @brief (uint16_t) device type
*
* e.g. NETDEV_TYPE_ETHERNET, NETDEV_TYPE_IEEE802154, etc.
*/
NETOPT_DEVICE_TYPE,
/**
* @brief get/set the channel page as defined by IEEE 802.15.4
* @brief (uint8_t) channel page as defined by IEEE 802.15.4
*/
NETOPT_CHANNEL_PAGE,
/**
* @brief get/set the CCA threshold for the radio transceiver
* @brief (int8_t) CCA threshold for the radio transceiver
*
* This is the value, in dBm, that the radio transceiver uses to decide
* if the channel is clear or not (CCA). If the current signal strength
* whether the channel is clear or not (CCA). If the current signal strength
* (RSSI/ED) is stronger than this CCA threshold value, the transceiver
* usually considers that the radio medium is busy. Otherwise, i.e.
* if RSSI/ED value is less than the CCA threshold value, the radio
* medium is supposed to be free (the possibly received weak signal
* is considered to be background, meaningless noise).
* usually considers that the radio medium is busy. Otherwise, i.e. if
* RSSI/ED value is less than the CCA threshold value, the radio medium is
* supposed to be free (the possibly received weak signal is considered to
* be background, meaningless noise).
*
* Most transceivers allow to set this CCA threshold value.
* Some research work has proven that dynamically adapting it
* to network environment can improve QoS, especially in WSN.
* Most transceivers allow to set this CCA threshold value. Some research
* work has proven that dynamically adapting it to network environment can
* improve QoS, especially in WSN.
*/
NETOPT_CCA_THRESHOLD,
/**
* @brief CCA mode for the radio transceiver
* @brief (uint8_t) CCA mode for the radio transceiver
*
* Get/set the CCA mode as uint8_t
* corresponding to the respective PHY standard.
* Get/set the CCA mode corresponding to the respective PHY standard.
* - IEEE 802.15.4: @ref netdev_ieee802154_cca_mode_t
*/
NETOPT_CCA_MODE,
/**
* @brief get statistics about sent and received packets and data of the device or protocol
* @brief (@ref netstats_t*) get statistics about sent and received packets and data of the device or protocol
*
* Expects a pointer to a @ref netstats_t struct that will be pointed to
* the corresponding @ref netstats_t of the module.
@ -333,49 +384,56 @@ typedef enum {
NETOPT_STATS,
/**
* @brief en/disable encryption.
* @brief (@ref netopt_enable_t) link layer encryption.
*/
NETOPT_ENCRYPTION, /**< en/disable encryption */
NETOPT_ENCRYPTION_KEY, /**< set encryption key */
NETOPT_ENCRYPTION,
/**
* @brief Test mode for the radio, e.g. for CE or FCC certification
* @brief (byte array) set encryption key
*
* Get/set the test mode as type @ref netopt_rf_testmode_t or as uint8_t
* if the radio supports other vendor specific test modes.
* The required byte array size is dependent on encryption algorithm and device.
*/
NETOPT_ENCRYPTION_KEY,
/**
* @brief (@ref netopt_rf_testmode_t) Test mode for the radio, e.g. for CE or FCC certification
*
* @note Setting this option should always return -ENOTSUP,
* unless it was explicitly allowed at build time,
* therefore it should be secured with an additional macro in the device driver.
* For development and certification purposes only, this test modes can disturb
* normal radio communications and exceed the limits, established by
* the regulatory authority.
* Get/set the test mode as type @ref netopt_rf_testmode_t or as uint8_t if
* the radio supports other vendor specific test modes.
*
* @note Setting this option should always return -ENOTSUP, unless it was
* explicitly allowed at build time, therefore it should be secured with an
* additional macro in the device driver.
*
* @attention For development and certification purposes only! These test
* modes can disturb normal radio communications and exceed the limits
* established by the regulatory authority.
*
*/
NETOPT_RF_TESTMODE,
/**
* @brief add an address to a link layer filter list
* @brief (@ref l2filter_t) add an address to a link layer filter list
*
* 'Getting' this option from a device will return a pointer of type
* Getting this option from a device will return a pointer of type
* @ref l2filter_t to the first entry of a filter list.
* When 'Setting' this option a pointer to an link layer address as well as
* When setting this option a pointer to an link layer address as well as
* the length of the address are expected as parameters.
*/
NETOPT_L2FILTER,
/**
* @brief remove an address from a link layer filter list
* @brief (@ref l2filter_t) remove an address from a link layer filter list
*
* 'Getting' this value always returns -ENOTSUP.
* When 'Setting' this option a pointer to an link layer address as well as
* the length of the address are expected as parameters. 'Setting' this
* Getting this value always returns -ENOTSUP.
* When setting this option a pointer to an link layer address as well as
* the length of the address are expected as parameters. Setting this
* option will lead to the given address being removed from the filer list.
*/
NETOPT_L2FILTER_RM,
/**
* @brief Energy level during the last performed CCA or RX frame
* @brief (int8_t) Energy level during the last performed CCA or RX frame
*
* Get the last ED level available as an int8_t. The source of the
* measurement is unspecified and may come from the latest CCA
@ -384,19 +442,17 @@ typedef enum {
NETOPT_LAST_ED_LEVEL,
/**
* @brief Get/Set preamble length as uint16_t in host byte order.
* @brief (uint16_t) preamble length
*/
NETOPT_PREAMBLE_LENGTH,
/**
* @brief Enable/disable integrity check (e.g CRC).
* @brief (@ref netopt_enable_t) frame integrity check (e.g CRC)
*/
NETOPT_INTEGRITY_CHECK,
/**
* @brief Get/Set the channel center frequency.
*
* Values are retrieved/passed as uint32_t in host byte order.
* @brief (uint32_t) channel center frequency
*
* For example, with LoRa, this corresponds to the center frequency of
* each channel (867300000, etc) for a given frequency band
@ -405,71 +461,74 @@ typedef enum {
NETOPT_CHANNEL_FREQUENCY,
/**
* @brief Enable/disable channel hopping.
* @brief (@ref netopt_enable_t) channel hopping
*/
NETOPT_CHANNEL_HOP,
/**
* @brief Get/Set channel hopping period as uint8_t.
* @brief (uint8_t) channel hopping period
*/
NETOPT_CHANNEL_HOP_PERIOD,
/**
* @brief Enable/disable single packet reception.
* @brief (@ref netopt_enable_t) single frame reception
*
* If enabled, RX is turned off upon reception of a packet
* If enabled, RX is turned off upon reception of a frame
*/
NETOPT_SINGLE_RECEIVE,
/**
* @brief Get/Set the reception timeout of a packet.
* @brief (uint32_t) reception timeout of a frame
*
* Values are retrieved/passed as uint32_t in host byte order.
* @todo in what time unit?
*/
NETOPT_RX_TIMEOUT,
/**
* @brief Get/Set the transmission timeout of a packet.
* @brief (uint32_t) transmission timeout of a frame
*
* Values are retrieved/passed as uint32_t in host byte order.
* @todo in what time unit?
*/
NETOPT_TX_TIMEOUT,
/**
* @brief Get/Set the radio modulation bandwidth as uint8_t.
* @brief (uint8_t) radio modulation bandwidth
*/
NETOPT_BANDWIDTH,
/**
* @brief Get/Set the radio spreading factor as uint8_t.
* @brief (uint8_t) radio spreading factor
*/
NETOPT_SPREADING_FACTOR,
/**
* @brief Get/Set the radio coding rate as uint8_t.
* @brief (uint8_t) radio coding rate
*/
NETOPT_CODING_RATE,
/**
* @brief Enable/disable fixed header mode.
* @brief (@ref netopt_enable_t) fixed header mode
*/
NETOPT_FIXED_HEADER,
/**
* @brief Enable/disable IQ inverted.
* @brief (@ref netopt_enable_t) IQ inverted
*/
NETOPT_IQ_INVERT,
NETOPT_6LO_IPHC, /**< en/disable header compression according to
* [RFC 6282](https://tools.ietf.org/html/rfc6282)
* or read the current state */
/**
* @brief (@ref netopt_enable_t) header compression
*
* @see [RFC 6282](https://tools.ietf.org/html/rfc6282)
*/
NETOPT_6LO_IPHC,
/**
* @brief Get retry amount from missing ACKs of the last transmission
* @brief (uint8_t) retry amount from missing ACKs of the last transmission
*
* This retrieves the number of retries needed for the last transmissions.
* Only retransmissions due to missing ACK packets are considered.
* Retries due to CCA failures are not counted.
* This retrieves the number of retries needed for the last transmission.
* Only retransmissions due to missing ACK frames are considered, retries
* due to CCA failures are not counted.
*/
NETOPT_TX_RETRIES_NEEDED,
@ -478,7 +537,7 @@ typedef enum {
/**
* @brief maximum number of options defined here.
*
* @note Interfaces are not meant to respond to that.
* @note Interfaces are not meant to respond to this option
*/
NETOPT_NUMOF,
} netopt_t;