diff --git a/sys/include/net/netopt.h b/sys/include/net/netopt.h index 331a5c4585..d921aa72ed 100644 --- a/sys/include/net/netopt.h +++ b/sys/include/net/netopt.h @@ -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 * 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;