Zephyr API 3.6.99
Loading...
Searching...
No Matches
ieee802154_radio_api Struct Reference

IEEE 802.15.4 driver interface API. More...

#include <ieee802154_radio.h>

Data Fields

struct net_if_api iface_api
 network interface API
 
enum ieee802154_hw_caps(* get_capabilities )(const struct device *dev)
 Get the device driver capabilities.
 
int(* cca )(const struct device *dev)
 Clear Channel Assessment - Check channel's activity.
 
int(* set_channel )(const struct device *dev, uint16_t channel)
 Set current channel.
 
int(* filter )(const struct device *dev, bool set, enum ieee802154_filter_type type, const struct ieee802154_filter *filter)
 Set/Unset PAN ID, extended or short address filters.
 
int(* set_txpower )(const struct device *dev, int16_t dbm)
 Set TX power level in dbm.
 
int(* tx )(const struct device *dev, enum ieee802154_tx_mode mode, struct net_pkt *pkt, struct net_buf *frag)
 Transmit a packet fragment as a single frame.
 
int(* start )(const struct device *dev)
 Start the device.
 
int(* stop )(const struct device *dev)
 Stop the device.
 
int(* continuous_carrier )(const struct device *dev)
 Start continuous carrier wave transmission.
 
int(* configure )(const struct device *dev, enum ieee802154_config_type type, const struct ieee802154_config *config)
 Set or update driver configuration.
 
int(* ed_scan )(const struct device *dev, uint16_t duration, energy_scan_done_cb_t done_cb)
 Run an energy detection scan.
 
net_time_t(* get_time )(const struct device *dev)
 Get the current time in nanoseconds relative to the network subsystem's local uptime clock as represented by this network interface.
 
uint8_t(* get_sch_acc )(const struct device *dev)
 Get the current estimated worst case accuracy (maximum ± deviation from the nominal frequency) of the network subsystem's local clock used to calculate tolerances and guard times when scheduling delayed receive or transmit radio operations.
 
int(* attr_get )(const struct device *dev, enum ieee802154_attr attr, struct ieee802154_attr_value *value)
 Get the value of a driver specific attribute.
 

Detailed Description

IEEE 802.15.4 driver interface API.

Note
This structure is called "radio" API for backwards compatibility. A better name would be "IEEE 802.15.4 driver API" as typical drivers will not only implement L1/radio (PHY) features but also L2 (MAC) features if the vendor-specific driver hardware or firmware offers offloading opportunities.

While L1-level driver features are exclusively implemented by drivers and MAY be mandatory to support certain application requirements, L2 features SHOULD be optional by default and only need to be implemented for performance optimization or precise timing as deemed necessary by driver maintainers. Fallback implementations ("Soft MAC") SHOULD be provided in the driver-independent L2 layer for all L2/MAC features especially if these features are not implemented in vendor hardware/firmware by a majority of existing in-tree drivers. If, however, a driver offers offloading opportunities then L2 implementations SHALL delegate performance critical or resource intensive tasks to the driver.

All drivers SHALL support two externally observable interface operational states: "UP" and "DOWN". Drivers MAY additionally support a "TESTING" interface state (see continuous_carrier()).

The following rules apply:

  • An interface is considered "UP" when it is able to transmit and receive packets, "DOWN" otherwise (see precise definitions of the corresponding ifOperStatus values in RFC 2863, section 3.1.14, net_if_oper_state and the continuous_carrier() exception below). A device that has its receiver temporarily disabled during "UP" state due to an active receive window configuration is still considered "UP".
  • Upper layers will assume that the interface managed by the driver is "UP" after a call to start() returned zero or -EALREADY. Upper layers assume that the interface is "DOWN" after calling stop() returned zero or -EALREADY.
  • The driver SHALL block start()/stop() calls until the interface fully transitioned to the new state (e.g. the receiver is operational, ongoing transmissions were finished, etc.). Drivers SHOULD yield the calling thread (i.e. "sleep") if waiting for the new state without CPU interaction is possible.
  • Drivers are responsible of guaranteeing atomicity of state changes. Appropriate means of synchronization SHALL be implemented (locking, atomic flags, ...).
  • While the interface is "DOWN", the driver SHALL be placed in the lowest possible power state. The driver MAY return from a call to stop() before it reaches the lowest possible power state, i.e. manage power asynchronously. While the interface is "UP", the driver SHOULD autonomously and asynchronously transition to lower power states whenever possible. If the driver claims to support timed RX/TX capabilities and the upper layers configure an RX slot, then the driver SHALL immediately transition (asynchronously) to the lowest possible power state until the start of the RX slot or until a scheduled packet needs to be transmitted.
  • The driver SHALL NOT change the interface's "UP"/"DOWN" state on its own. Initially, the interface SHALL be in the "DOWN" state.
  • Drivers that implement the optional continuous_carrier() operation will be considered to be in the RFC 2863 "testing" ifOperStatus state if that operation returns zero. This state is active until either start() or stop() is called. If continuous_carrier() returns a non-zero value then the previous state is assumed by upper layers.
  • If calls to start()/stop() return any other value than zero or -EALREADY, upper layers will consider the interface to be in a "lowerLayerDown" state as defined in RFC 2863.
  • The RFC 2863 "dormant", "unknown" and "notPresent" ifOperStatus states are currently not supported. The "lowerLevelUp" state.
  • The ed_scan(), cca() and tx() operations SHALL only be supported in the "UP" state and return -ENETDOWN in any other state. See the function-level API documentation below for further details.
Note
In case of devices that support timed RX/TX, the "UP" state is not equal to "receiver enabled". If a receive window (i.e. RX slot, see IEEE802154_CONFIG_RX_SLOT) is configured before calling start() then the receiver will not be enabled when transitioning to the "UP" state. Configuring a receive window while the interface is "UP" will cause the receiver to be disabled immediately until the configured reception time has arrived.

Field Documentation

◆ attr_get

int(* ieee802154_radio_api::attr_get) (const struct device *dev, enum ieee802154_attr attr, struct ieee802154_attr_value *value)

Get the value of a driver specific attribute.

Note
This function SHALL NOT return any values configurable by the MAC (L2) layer. It is reserved to non-boolean (i.e. scalar or structured) attributes that originate from the driver implementation and cannot be directly or indirectly derived by L2. Boolean attributes SHALL be implemented as ieee802154_hw_caps.
Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized ("ready").
Return values
0The requested attribute is supported by the driver and the value can be retrieved from the corresponding ieee802154_attr_value member.
-ENOENTThe driver does not provide the requested attribute. The value structure has not been updated with attribute data. The content of the value attribute is undefined.

◆ cca

int(* ieee802154_radio_api::cca) (const struct device *dev)

Clear Channel Assessment - Check channel's activity.

Note
Implementations SHALL be isr-ok and MAY sleep. SHALL return -ENETDOWN unless the interface is "UP".
Parameters
devpointer to IEEE 802.15.4 driver device
Return values
0the channel is available
-EBUSYThe channel is busy.
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-ENETDOWNThe interface is not "UP".
-ENOTSUPCCA is not supported by this driver.
-EIOThe CCA procedure could not be executed.

◆ configure

int(* ieee802154_radio_api::configure) (const struct device *dev, enum ieee802154_config_type type, const struct ieee802154_config *config)

Set or update driver configuration.

The method blocks until the interface has been reconfigured atomically with respect to ongoing package reception, transmission or any other ongoing driver operation.

Note
Implementations SHALL be isr-ok and MAY sleep. MAY be called in any interface state once the driver is fully initialized ("ready"). Some configuration options may not be supported in all interface operational states, see the detailed specifications in ieee802154_config_type. In this case the operation returns -EACCES.
Parameters
devpointer to IEEE 802.15.4 driver device
typethe configuration type to be set
configthe configuration parameters to be set for the given configuration type
Return values
0configuration successful
-EINVALThe configuration parameters are invalid for the given configuration type.
-ENOTSUPThe given configuration type is not supported by this driver.
-EACCESThe given configuration type is supported by this driver but cannot be configured in the current interface operational state.
-ENOMEMThe configuration cannot be saved due to missing memory resources.
-ENOENTThe resource referenced in the configuration parameters cannot be found in the configuration.
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-EIOAn internal error occurred while trying to configure the given configuration parameter.

◆ continuous_carrier

int(* ieee802154_radio_api::continuous_carrier) (const struct device *dev)

Start continuous carrier wave transmission.

The method blocks until the interface has started to emit a continuous carrier. To leave this mode, start() or stop() should be called, which will put the driver back into the "UP" or "DOWN" states, respectively.

Note
Implementations MAY sleep and will usually NOT be isr-ok. MAY be called in any interface state once the driver is fully initialized ("ready").
Parameters
devpointer to IEEE 802.15.4 driver device
Return values
0continuous carrier wave transmission started
-EALREADYThe driver was already in "TESTING" state and emitting a continuous carrier.
-EIOnot started

◆ ed_scan

int(* ieee802154_radio_api::ed_scan) (const struct device *dev, uint16_t duration, energy_scan_done_cb_t done_cb)

Run an energy detection scan.

Note
requires IEEE802154_HW_ENERGY_SCAN capability
The radio channel must be set prior to calling this function.
Implementations SHALL be isr-ok and MAY sleep. SHALL return -ENETDOWN unless the interface is "UP".
Parameters
devpointer to IEEE 802.15.4 driver device
durationduration of energy scan in ms
done_cbfunction called when the energy scan has finished
Return values
0the energy detection scan was successfully scheduled
-EBUSYthe energy detection scan could not be scheduled at this time
-EALREADYa previous energy detection scan has not finished yet.
-ENETDOWNThe interface is not "UP".
-ENOTSUPThis driver does not support energy scans.
-EIOThe energy detection procedure could not be executed.

◆ filter

int(* ieee802154_radio_api::filter) (const struct device *dev, bool set, enum ieee802154_filter_type type, const struct ieee802154_filter *filter)

Set/Unset PAN ID, extended or short address filters.

Note
requires IEEE802154_HW_FILTER capability.
Implementations SHALL be isr-ok and MAY sleep. SHALL return -EIO unless the interface is either "UP" or "DOWN".
Parameters
devpointer to IEEE 802.15.4 driver device
settrue to set the filter, false to remove it
typethe type of entity to be added/removed from the filter list (a PAN ID or a source/destination address)
filterthe entity to be added/removed from the filter list
Return values
0The filter was successfully added/removed.
-EINVALThe given filter entity or filter entity type was not valid.
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-ENOTSUPSetting/removing this filter or filter type is not supported by this driver.
-EIOError while setting/removing the filter.

◆ get_capabilities

enum ieee802154_hw_caps(* ieee802154_radio_api::get_capabilities) (const struct device *dev)

Get the device driver capabilities.

Note
Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized ("ready").
Parameters
devpointer to IEEE 802.15.4 driver device
Returns
Bit field with all supported device driver capabilities.

◆ get_sch_acc

uint8_t(* ieee802154_radio_api::get_sch_acc) (const struct device *dev)

Get the current estimated worst case accuracy (maximum ± deviation from the nominal frequency) of the network subsystem's local clock used to calculate tolerances and guard times when scheduling delayed receive or transmit radio operations.

The deviation is given in units of PPM (parts per million).

Note
requires IEEE802154_HW_TXTIME and/or IEEE802154_HW_RXTIME capabilities.
Implementations may estimate this value based on current operating conditions (e.g. temperature). Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized ("ready").
Parameters
devpointer to IEEE 802.15.4 driver device
Returns
current estimated clock accuracy in PPM

◆ get_time

net_time_t(* ieee802154_radio_api::get_time) (const struct device *dev)

Get the current time in nanoseconds relative to the network subsystem's local uptime clock as represented by this network interface.

See net_time_t for semantic details.

Note
requires IEEE802154_HW_TXTIME and/or IEEE802154_HW_RXTIME capabilities. Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized ("ready").
Parameters
devpointer to IEEE 802.15.4 driver device
Returns
nanoseconds relative to the network subsystem's local clock, -1 if an error occurred or the operation is not supported

◆ iface_api

struct net_if_api ieee802154_radio_api::iface_api

network interface API

Note
Network devices must extend the network interface API. It is therefore mandatory to place it at the top of the driver API struct so that it can be cast to a network interface.

◆ set_channel

int(* ieee802154_radio_api::set_channel) (const struct device *dev, uint16_t channel)

Set current channel.

Note
Implementations SHALL be isr-ok and MAY sleep. SHALL return -EIO unless the interface is either "UP" or "DOWN".
Parameters
devpointer to IEEE 802.15.4 driver device
channelthe number of the channel to be set in CPU byte order
Return values
0channel was successfully set
-EALREADYThe previous channel is the same as the requested channel.
-EINVALThe given channel is not within the range of valid channels of the driver's current channel page, see the IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES driver attribute.
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-ENOTSUPThe given channel is within the range of valid channels of the driver's current channel page but unsupported by the current driver.
-EIOThe channel could not be set.

◆ set_txpower

int(* ieee802154_radio_api::set_txpower) (const struct device *dev, int16_t dbm)

Set TX power level in dbm.

Note
Implementations SHALL be isr-ok and MAY sleep. SHALL return -EIO unless the interface is either "UP" or "DOWN".
Parameters
devpointer to IEEE 802.15.4 driver device
dbmTX power in dbm
Return values
0The TX power was successfully set.
-EINVALThe given dbm value is invalid or not supported by the driver.
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-EIOThe TX power could not be set.

◆ start

int(* ieee802154_radio_api::start) (const struct device *dev)

Start the device.

Upper layers will assume the interface is "UP" if this operation returns with zero or -EALREADY. The interface is placed in receive mode before returning from this operation unless an RX slot has been configured (even if it lies in the past, see IEEE802154_CONFIG_RX_SLOT).

Note
Implementations SHALL be isr-ok and MAY sleep. MAY be called in any interface state once the driver is fully initialized ("ready").
Parameters
devpointer to IEEE 802.15.4 driver device
Return values
0The driver was successfully started.
-EALREADYThe driver was already "UP".
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-EIOThe driver could not be started.

◆ stop

int(* ieee802154_radio_api::stop) (const struct device *dev)

Stop the device.

Upper layers will assume the interface is "DOWN" if this operation returns with zero or -EALREADY. The driver switches off the receiver before returning if it was previously on. The driver enters the lowest possible power mode after this operation is called. This MAY happen asynchronously (i.e. after the operation already returned control).

Note
Implementations SHALL be isr-ok and MAY sleep. MAY be called in any interface state once the driver is fully initialized ("ready").
Parameters
devpointer to IEEE 802.15.4 driver device
Return values
0The driver was successfully stopped.
-EWOULDBLOCKThe operation is called from ISR context but temporarily cannot be executed without blocking.
-EALREADYThe driver was already "DOWN".
-EIOThe driver could not be stopped.

◆ tx

int(* ieee802154_radio_api::tx) (const struct device *dev, enum ieee802154_tx_mode mode, struct net_pkt *pkt, struct net_buf *frag)

Transmit a packet fragment as a single frame.

Depending on the level of offloading features supported by the driver, the frame MAY not be fully encrypted/authenticated or it MAY not contain an FCS. It is the responsibility of L2 implementations to prepare the frame according to the offloading capabilities announced by the driver and to decide whether CCA, CSMA/CA, ACK or retransmission procedures need to be executed outside ("soft MAC") or inside ("hard MAC") the driver .

All frames originating from L2 SHALL have all required IEs pre-allocated and pre-filled such that the driver does not have to parse and manipulate IEs at all. This includes ACK packets if the driver does not have the IEEE802154_HW_RX_TX_ACK capability. Also see IEEE802154_CONFIG_ENH_ACK_HEADER_IE for drivers that have the IEEE802154_HW_RX_TX_ACK capability.

IEs that cannot be prepared by L2 unless the TX time is known (e.g. CSL IE, Rendezvous Time IE, Time Correction IE, ...) SHALL be sent in any of the timed TX modes with appropriate timing information pre-filled in the IE such that drivers do not have to parse and manipulate IEs at all unless the frame is generated by the driver itself.

In case any of the timed TX modes is supported and used (see ieee802154_hw_caps and ieee802154_tx_mode), the driver SHALL take responsibility of scheduling and sending the packet at the precise programmed time autonomously without further interaction by upper layers. The call to tx() will block until the package has either been sent successfully (possibly including channel acquisition and packet acknowledgment) or a terminal transmission error occurred. The driver SHALL sleep and keep power consumption to the lowest possible level until the scheduled transmission time arrives or during any other idle waiting time.

Warning
The driver SHALL NOT take ownership of the given network packet and frame (fragment) buffer. Any data required by the driver including the actual frame content must be read synchronously and copied internally if needed at a later time (e.g. the contents of IEs required for protocol configuration, states of frame counters, sequence numbers, etc). Both, the packet and the buffer MAY be re-used or released by upper layers immediately after the function returns.
Note
Implementations MAY sleep and will usually NOT be isr-ok - especially when timed TX, CSMA/CA, retransmissions, auto-ACK or any other offloading feature is supported that implies considerable idle waiting time. SHALL return -ENETDOWN unless the interface is "UP".
Parameters
devpointer to IEEE 802.15.4 driver device
modethe transmission mode, some of which require specific offloading capabilities.
pktpointer to the network packet to be transmitted.
fragpointer to a network buffer containing a single fragment with the frame data to be transmitted
Return values
0The frame was successfully sent or scheduled. If the driver supports ACK offloading and the frame requested acknowledgment (AR bit set), this means that the packet was successfully acknowledged by its peer.
-EINVALInvalid packet (e.g. an expected IE is missing or the encryption/authentication state is not as expected).
-EBUSYThe frame could not be sent because the medium was busy (CSMA/CA or CCA offloading feature only).
-ENOMSGThe frame was not confirmed by an ACK packet (TX ACK offloading feature only) or the received ACK packet was invalid.
-ENOBUFSThe frame could not be scheduled due to missing internal resources (timed TX offloading feature only).
-ENETDOWNThe interface is not "UP".
-ENOTSUPThe given TX mode is not supported.
-EIOThe frame could not be sent due to some unspecified driver error (e.g. the driver being busy).

The documentation for this struct was generated from the following file: