rflib
|
Modules | |
Rf_driver_cc13x2_cc26x2 | |
Data Structures | |
struct | RF_TxPowerTable_Value |
PA configuration value for a certain power level. More... | |
struct | RF_TxPowerTable_Entry |
TX power configuration entry in a TX power table. More... | |
struct | RF_Mode |
Specifies a RF core firmware configuration. More... | |
struct | RF_CoexOverride |
Runtime coexistence override parameters. More... | |
struct | RF_CoexOverride_BLEUseCases |
Coexistence override settings for BLE5 application scenarios. More... | |
union | RF_RadioSetup |
A unified type for radio setup commands of different PHYs. More... | |
union | RF_InfoVal |
Stores output parameters for RF_getInfo(). More... | |
struct | RF_ScheduleMapElement |
RF schedule map entry structure. More... | |
struct | RF_ScheduleMap |
RF schedule map structure. More... | |
struct | RF_Params |
RF driver configuration parameters. More... | |
struct | RF_Cmd_s |
struct | RFCC26XX_HWAttrsV2 |
RF Hardware attributes. More... | |
struct | RFCC26XX_SchedulerPolicy |
RF scheduler policy. More... | |
struct | RF_ScheduleCmdParams |
struct | RF_AccessParams |
RF request access parameter struct. More... | |
struct | RF_RatConfigCapture |
RF_ratCapture parameter structure. More... | |
struct | RF_RatConfigCompare |
RF_ratCompare parameter structure. More... | |
struct | RF_RatConfigOutput |
RAT related IO parameter structure. More... | |
struct | RF_Object |
Stores the client's internal configuration and states. More... | |
Typedefs | |
typedef rfc_radioOp_t | RF_Op |
Base type for all radio operation commands. More... | |
typedef uint64_t | RF_EventMask |
Data type for events during command execution. More... | |
typedef uint32_t | RF_ClientEventMask |
Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask. More... | |
typedef uint32_t | RF_GlobalEventMask |
Event mask for combining RF_GlobalEvent event flags in RFCC26XX_HWAttrsV2::globalEventMask. More... | |
typedef int16_t | RF_CmdHandle |
Command handle that is returned by RF_postCmd(). More... | |
typedef RF_Object * | RF_Handle |
A handle that is returned by to RF_open(). More... | |
typedef int8_t | RF_RatHandle |
RAT handle that is returned by RF_ratCompare() or RF_ratCapture(). More... | |
typedef void(* | RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e) |
Handles events related to RF command execution. More... | |
typedef void(* | RF_RatCallback) (RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime) |
Handles events related to the Radio Timer (RAT). More... | |
typedef void(* | RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg) |
Handles events related to a driver instance. More... | |
typedef void(* | RF_GlobalCallback) (RF_Handle h, RF_GlobalEvent event, void *arg) |
Handles global events as part of PHY configuration. More... | |
typedef struct RF_Cmd_s | RF_Cmd |
typedef RF_ScheduleStatus(* | RF_SubmitHook) (RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue) |
Handles the queue sorting algorithm when a new command is submitted to the driver from any of the active clients. More... | |
typedef RF_ExecuteAction(* | RF_ExecuteHook) (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue, bool bConflict, RF_Cmd *conflictCmd) |
Defines the execution and conflict resolution hook at runtime. More... | |
Functions | |
RF_Handle | RF_open (RF_Object *pObj, RF_Mode *pRfMode, RF_RadioSetup *pRadioSetup, RF_Params *params) |
Creates a a new client instance of the RF driver. More... | |
void | RF_close (RF_Handle h) |
Close client connection to RF driver. More... | |
uint32_t | RF_getCurrentTime (void) |
Return current radio timer value. More... | |
RF_CmdHandle | RF_postCmd (RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent) |
Appends RF operation commands to the driver's command queue and returns a command handle. More... | |
RF_ScheduleStatus | RF_defaultSubmitPolicy (RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue) |
Sorts and adds commands to the RF driver internal command queue. More... | |
RF_ExecuteAction | RF_defaultExecutionPolicy (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue, bool bConflict, RF_Cmd *conflictCmd) |
Makes a final decision before dispatching a scheduled command. More... | |
void | RF_ScheduleCmdParams_init (RF_ScheduleCmdParams *pSchParams) |
Initialize the configuration structure to default values to be used with the RF_scheduleCmd() API. More... | |
RF_CmdHandle | RF_scheduleCmd (RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent) |
Schedule an RF operation (chain) to the command queue. More... | |
RF_EventMask | RF_pendCmd (RF_Handle h, RF_CmdHandle ch, RF_EventMask bmEvent) |
Synchronizes the calling task to an RF operation command ch and returns accumulated event flags. More... | |
RF_EventMask | RF_runCmd (RF_Handle h, RF_Op *pOp, RF_Priority ePri, RF_Callback pCb, RF_EventMask bmEvent) |
Runs synchronously an RF operation command or a chain of commands and returns the termination reason. More... | |
RF_EventMask | RF_runScheduleCmd (RF_Handle h, RF_Op *pOp, RF_ScheduleCmdParams *pSchParams, RF_Callback pCb, RF_EventMask bmEvent) |
Runs synchronously a (chain of) RF operation(s) for dual or single-mode. More... | |
RF_Stat | RF_cancelCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode) |
Abort/stop/cancel single command in command queue. More... | |
RF_Stat | RF_flushCmd (RF_Handle h, RF_CmdHandle ch, uint8_t mode) |
Abort/stop/cancel command and any subsequent commands in command queue. More... | |
RF_Stat | RF_runImmediateCmd (RF_Handle h, uint32_t *pCmdStruct) |
Send any Immediate command. More... | |
RF_Stat | RF_runDirectCmd (RF_Handle h, uint32_t cmd) |
Send any Direct command. More... | |
void | RF_yield (RF_Handle h) |
Signal that radio client is not going to issue more commands in a while. More... | |
void | RF_Params_init (RF_Params *params) |
Function to initialize the RF_Params struct to its defaults. More... | |
RF_Stat | RF_getInfo (RF_Handle h, RF_InfoType type, RF_InfoVal *pValue) |
Get value for some RF driver parameters. More... | |
int8_t | RF_getRssi (RF_Handle h) |
Get RSSI value. More... | |
RF_Op * | RF_getCmdOp (RF_Handle h, RF_CmdHandle cmdHnd) |
Get command structure pointer. More... | |
void | RF_RatConfigCompare_init (RF_RatConfigCompare *channelConfig) |
Initialize the configuration structure to be used to set up a RAT compare event. More... | |
void | RF_RatConfigCapture_init (RF_RatConfigCapture *channelConfig) |
Initialize the configuration structure to be used to set up a RAT capture event. More... | |
void | RF_RatConfigOutput_init (RF_RatConfigOutput *ioConfig) |
Initialize the configuration structure to be used to set up a RAT IO. More... | |
RF_RatHandle | RF_ratCompare (RF_Handle rfHandle, RF_RatConfigCompare *channelConfig, RF_RatConfigOutput *ioConfig) |
Setup a Radio Timer (RAT) channel in compare mode. More... | |
RF_RatHandle | RF_ratCapture (RF_Handle rfHandle, RF_RatConfigCapture *channelConfig, RF_RatConfigOutput *ioConfig) |
Setup a Radio Timer (RAT) channel in capture mode. More... | |
RF_Stat | RF_ratDisableChannel (RF_Handle rfHandle, RF_RatHandle ratHandle) |
Disable a RAT channel. More... | |
RF_Stat | RF_control (RF_Handle h, int8_t ctrl, void *args) |
Set RF control parameters. More... | |
RF_Stat | RF_requestAccess (RF_Handle h, RF_AccessParams *pParams) |
Request radio access. More... | |
RF_TxPowerTable_Value | RF_getTxPower (RF_Handle h) |
Returns the currently configured transmit power configuration. More... | |
RF_Stat | RF_setTxPower (RF_Handle h, RF_TxPowerTable_Value value) |
Updates the transmit power configuration of the RF core. More... | |
int8_t | RF_TxPowerTable_findPowerLevel (RF_TxPowerTable_Entry table[], RF_TxPowerTable_Value value) |
Retrieves a power level in dBm for a given power configuration value. More... | |
RF_TxPowerTable_Value | RF_TxPowerTable_findValue (RF_TxPowerTable_Entry table[], int8_t powerLevel) |
Retrieves a power configuration value for a given power level in dBm. More... | |
RF_Stat | RF_enableHPOSCTemperatureCompensation (void) |
Enables temperature monitoring and temperature based drift compensation. More... | |
typedef rfc_radioOp_t RF_Op |
Base type for all radio operation commands.
All radio operation commands share a common part. That includes the command id, a status field, chaining properties and a start trigger. Whenever an RF operation command is used with the RF driver, it needs to be casted to an RF_Op.
More information about RF operation commands can be found in the Proprietary RF User's Guide.
typedef uint64_t RF_EventMask |
Data type for events during command execution.
Possible event flags are listed in RF_Core_Events and RF_Driver_Events.
typedef uint32_t RF_ClientEventMask |
Event mask for combining RF_ClientEvent event flags in RF_Params::nClientEventMask.
typedef uint32_t RF_GlobalEventMask |
Event mask for combining RF_GlobalEvent event flags in RFCC26XX_HWAttrsV2::globalEventMask.
typedef int16_t RF_CmdHandle |
Command handle that is returned by RF_postCmd().
A command handle is an integer number greater equals zero and identifies a command container in the RF driver's internal command queue. A client can dispatch a command with RF_postCmd() and use the command handle later on to make the RF driver interact with the command.
A negative value has either a special meaning or indicates an error.
A handle that is returned by to RF_open().
RF_Handle is used for further RF client interaction with the RF driver. An invalid handle has the value NULL.
typedef int8_t RF_RatHandle |
RAT handle that is returned by RF_ratCompare() or RF_ratCapture().
An RF_RatHandle is an integer number with value greater than or equal to zero and identifies a Radio Timer Channel in the RF driver's internal RAT module. A client can interact with the RAT module through the RF_ratCompare(), RF_ratCapture() or RF_ratDisableChannel() APIs.
A negative value indicates an error. A typical example when RF_ratCompare() returns with RF_ALLOC_ERROR.
typedef void(* RF_Callback) (RF_Handle h, RF_CmdHandle ch, RF_EventMask e) |
Handles events related to RF command execution.
RF command callbacks notify the application of any events happening during RF command execution. Events may either refer to RF core interrupts (RF_Core_Events) or may be generated by the RF driver (RF_Driver_Events).
RF command callbacks are set up as parameter to RF_postCmd() or RF_runCmd() and provide:
RF command callbacks are executed in Software Interrupt (SWI) context and must not perform any blocking operation. The priority is configurable via RFCC26XX_HWAttrsV2 in the board file or RF_CTRL_SET_SWI_PRIORITY in RF_control().
The RF_Callback function type is also used for signaling power events and errors. These are set in RF_Params::pPowerCb and RF_Params::pErrCb respectively. In case of a power event, ch can be ignored and e has RF_EventPowerUp set. In case of an error callback, ch contains an error code instead of a command handle and e has the RF_EventError flag set.
typedef void(* RF_RatCallback) (RF_Handle h, RF_RatHandle rh, RF_EventMask e, uint32_t compareCaptureTime) |
Handles events related to the Radio Timer (RAT).
The RF driver provides an interface to the Radio Timer through RF_ratCompare(), RF_ratCapture() and RF_ratDisableChannel() APIs. Each API call receives an optional input argument of the type RF_RatCallback. When a timer event occurs (compare, capture or error events), the registered callback is invoked.
The RF_RatCallback provides the following argument:
typedef void(* RF_ClientCallback) (RF_Handle h, RF_ClientEvent event, void *arg) |
Handles events related to a driver instance.
The RF driver produces additional events that are not directly related to the execution of a certain command, but happen during general RF driver operations. This includes power-up events, client switching events and others.
A client callback provides the following arguments:
RF client callbacks are executed in Software Interrupt (SWI) context and must not perform any blocking operation. The priority is configurable via RFCC26XX_HWAttrsV2 in the board file or RF_CTRL_SET_SWI_PRIORITY in RF_control().
typedef void(* RF_GlobalCallback) (RF_Handle h, RF_GlobalEvent event, void *arg) |
Handles global events as part of PHY configuration.
The RF driver serves additional global, client independent events by invoking the RF_GlobalCallback function registered through RFCC26XX_HWAttrsV2::globalCallback in the board file. The function can subscribe to particular events through the RFCC26XX_HWAttrsV2::globalEventMask, and receives the following arguments:
If multiple events happen at the same time, the callback is always invoked separately for each event. Depending on the event, the callback might be invoked in SWI or HWI context.
typedef RF_ScheduleStatus(* RF_SubmitHook) (RF_Cmd *pCmdNew, RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue) |
Handles the queue sorting algorithm when a new command is submitted to the driver from any of the active clients.
The function is invoked within the RF_scheduleCmd API.
The default algorithm is subscribed through the RFCC26XX_SchedulerPolicy::submitHook and implemented in the RF driver. The arguments are:
In case the radio APIs do not distinguish between background and foreground contexts, the active operation will be returned within the pCmdBg pointer. If there are no commands being executed, both the pCmdBg and pCmdFg pointers are returned as NULL.
typedef RF_ExecuteAction(* RF_ExecuteHook) (RF_Cmd *pCmdBg, RF_Cmd *pCmdFg, List_List *pPendQueue, List_List *pDoneQueue, bool bConflict, RF_Cmd *conflictCmd) |
Defines the execution and conflict resolution hook at runtime.
The function is invoked before a scheduled command is about to be executed. If a conflict is identified before the start-time of the next radio command in the pending queue, this information is passed to the hook. The return value of type RF_ExecuteAction determines the policy to be followed by the RF driver.
The arguments are:
Selects a power amplifier path in a TX power value.
RF_TxPowerTable_PAType selects one of the available power amplifiers on the RF core. It is usually included in a RF_TxPowerTable_Value.
Enumerator | |
---|---|
RF_TxPowerTable_DefaultPA | Default PA. |
RF_TxPowerTable_HighPA | High-power PA. |
enum RF_Priority |
Scheduling priority of RF operation commands.
When multiple RF driver instances are used at the same time, commands from different clients may overlap. If an RF operation with a higher priority than the currently running operation is scheduled by RF_scheduleCmd(), then the running operation is interrupted.
In single-client applications, RF_PriorityNormal should be used.
enum RF_PriorityCoex |
Priority level for coexistence priority signal.
When the RF driver is configured for three-wire coexistence mode, one of the output wires will signal the priority level of the coexistence request. When RF operations are scheduled with RF_scheduleCmd(), the scheduler can be configured to override the default coexistence priority level for the RF operation.
The coexistence priority level is binary because it translates to a high/low output signal.
enum RF_RequestCoex |
Behavior for coexistence request signal.
When the RF driver is configured for three-wire coexistence mode, one of the output wires will signal the request level of the coexistence request. When RF operations are scheduled with RF_scheduleCmd(), the scheduler can be configured to override the default coexistence request line behavior for the RF operation in RX.
This override will be ignored if the option to set request for an entire chain is active.
enum RF_Stat |
Status codes for various RF driver functions.
RF_Stat is reported as return value for RF driver functions which execute direct and immediate commands. Such commands are executed by RF_runDirectCmd() and RF_runImmediateCmd() in the first place, but also by some convenience functions like RF_cancelCmd(), RF_flushCmd(), RF_getInfo() and others.
enum RF_ClientEvent |
Client-related RF driver events.
Events originating in the RF driver but not directly related to a specific radio command, are called client events. Clients may subscribe to these events by specifying a callback function RF_Params::pClientEventCb. Events are activated by specifying a bitmask RF_Params::nClientEventMask. The callback is called separately for every event providing an optional argument.
enum RF_GlobalEvent |
Global RF driver events.
The RF driver provides an interface through the global RFCC26XX_hwAttrs
struct to register a global, client independent callback. This callback is typically used to control board related configurations such as antenna switches.
For the coexistence (coex) feature, some of the events are used to handle the I/O muxing of the GPIO signals for REQUEST, PRIORITY and GRANT.
Enumerator | |
---|---|
RF_GlobalEventRadioSetup | The RF core is being reconfigured through a setup command. The arg argument is a pointer to the setup command. HWI context. |
RF_GlobalEventRadioPowerDown | The RF core is being powered down. The arg argument is empty. SWI context. |
RF_GlobalEventInit | RF_open() is called for the first time (number of registered clients changes from 0 to 1). The arg argument is empty. Task context. |
RF_GlobalEventCmdStart | A command chain is being dispatched to the radio. The arg argument is a pointer to the current command. HWI context. |
RF_GlobalEventCmdStop | Command termination event is handled. The arg argument is a pointer to the current command. HWI context. |
RF_GlobalEventCoexControl | Change to coex configuration is requested The arg argument is pointer to at least 8-bit wide int with value 1=enable, or 0=disable Task/HWI context. |
RF_GlobalEventTempNotifyFail | Registration of temperature notification was unsuccessful (failure returned from temperature driver) The arg argument is empty. HWI context |
enum RF_InfoType |
Selects the entry of interest in RF_getInfo().
enum RF_StartType |
Controls the behavior of the RF_scheduleCmd() API.
Enumerator | |
---|---|
RF_StartNotSpecified | |
RF_StartAbs |
enum RF_EndType |
Controls the behavior of the RF_scheduleCmd() API.
Enumerator | |
---|---|
RF_EndNotSpecified | |
RF_EndAbs | |
RF_EndRel | |
RF_EndInfinit |
enum RF_ExecuteAction |
Controls the behavior of the state machine of the RF driver when a conflict is identified run-time between the commands waiting on the pend queue and the commands being actively executed by the radio.
enum RF_ScheduleStatus |
enum RF_AllowDelay |
Controls the behavior of the RF_scheduleCmd() API.
Enumerator | |
---|---|
RF_AllowDelayNone | |
RF_AllowDelayAny |
enum RF_RatSelectChannel |
Select the preferred RAT channel through the configuration of RF_ratCompare() or RF_ratCapture().
If RF_RatChannelAny is provided within the channel configuration (default), the API will allocate the first available channel. Otherwise, it tries to allocate the requested channel, and if it is not available, returns with RF_ALLOC_ERROR.
Enumerator | |
---|---|
RF_RatChannelAny | Chose the first available channel. |
RF_RatChannel0 | Use RAT user channel 0. |
RF_RatChannel1 | Use RAT user channel 1. |
RF_RatChannel2 | Use RAT user channel 2. |
enum RF_RatCaptureSource |
Selects the source signal for RF_ratCapture().
The source of a capture event can be selected through the source field of the RF_RatConfigCapture configuration structure.
enum RF_RatCaptureMode |
Selects the mode of RF_ratCapture().
The trigger mode of a capture event can be selected through the mode field of RF_RatConfigCapture configuration structure.
Selects the repetition of RF_ratCapture().
The configuration of a capture channel also defines whether the channel should be freed or automatically rearmed after a capture event occurred. In the latter case, the user needs to free the channel manually through the RF_ratDisableChannel() API.
Enumerator | |
---|---|
RF_RatCaptureSingle | Free the channel after the first capture event. |
RF_RatCaptureRepeat | Rearm the channel after each capture events. |
enum RF_RatOutputMode |
Selects the mode of the RAT_GPO[x] for RF_ratCompare() or RF_ratCapture().
In case of compare mode, the channel can generate an output signal of the selected mode on the configured RAT_GPO[x] interface, and can be interconnected with other subsystems through the RFC_GPO[x] or Event Fabric. An example use case is to generate a pulse on a GPIO.
In case of capture mode, the channel can also generate an output signal of the selected mode on the configured RAT_GPO[x] interface. Note that the configuration of this output event is independent of the source signal of the capture event. An example use case is to generate a pulse on a GPIO on each raising edge of another GPIO source.
enum RF_RatOutputSelect |
Selects GPO to be used with RF_ratCompare() or RF_ratCapture().
RAT_GPO[0] - Reserved by the RF core. User shall not modify the configuration, but can observe the signal through any of RFC_GPO[0:3]. RAT_GPO[1] - Reserved by the RF core only if sync word detection is enabled. Otherwise can be used through RFC_GPO[0:3]. RAT_GPO[2:3] - Available and can be used through any of the RFC_GPO[0:3]. RAT_GPO[4:7] - Available and can be used through the Event fabric.
RF_Handle RF_open | ( | RF_Object * | pObj, |
RF_Mode * | pRfMode, | ||
RF_RadioSetup * | pRadioSetup, | ||
RF_Params * | params | ||
) |
Creates a a new client instance of the RF driver.
This function initializes an RF driver client instance using pObj as storage. It does not power up the RF core. Once the client starts the first RF operation command later in the application, the RF core is powered up and set into a PHY mode specified by pRfMode. The chosen PHY is then configured by a radio setup command pRadioSetup. Whenever the RF core is powered up, the RF driver re-executes the radio setup command pRadioSetup. Additional driver behavior may be set by an optional params.
pObj | Pointer to a RF_Object that will hold the state for this RF client. The object must be in persistent and writable memory. |
pRfMode | Pointer to a RF_Mode struct holding PHY information |
pRadioSetup | Pointer to the radio setup command used for this client. This is re-executed by the RF Driver on each power-up. |
params | Pointer to an RF_Params object with the desired driver configuration. A NULL pointer results in the default configuration being loaded. |
void RF_close | ( | RF_Handle | h | ) |
Close client connection to RF driver.
Allows a RF client (high-level driver or application) to close its connection to the RF driver. RF_close pends on all commands in the command queue before closing the connection. If a client has access to the radio by using RF_RequestAccess API, and the same client calls RF_close, then the connection to the RF driver is closed immediately without waiting for the access duration to be over.
h | Handle previously returned by RF_open() |
uint32_t RF_getCurrentTime | ( | void | ) |
Return current radio timer value.
If the radio is powered returns the current radio timer value, if not returns a conservative estimate of the current radio timer value
RF_CmdHandle RF_postCmd | ( | RF_Handle | h, |
RF_Op * | pOp, | ||
RF_Priority | ePri, | ||
RF_Callback | pCb, | ||
RF_EventMask | bmEvent | ||
) |
Appends RF operation commands to the driver's command queue and returns a command handle.
The RF operation pOp may either represent a single operation or may be the first operation in a chain. If the command queue is empty, the pCmd is dispatched immediately. If there are other operations pending, then pCmd is processed after all other commands have been finished. The RF operation command must be compatible to the RF_Mode selected by RF_open(), e.g. proprietary commands can only be used when the RF core is configured for proprietary mode.
The returned command handle is an identifier that can be used to control command execution later on, for instance with RF_pendCmd() or RF_cancelCmd(). It is a 16 Bit signed integer value, incremented on every new command. If the RF driver runs out of command containers, RF_ALLOC_ERROR is returned.
The priority ePri is only relevant in multi-client applications where commands of distinct clients may interrupt each other. Only commands started by RF_scheduleCmd() can preempt running commands. RF_postCmd() or RF_runCmd() do never interrupt a running command. In single-client applications, ePri is ignored and should be set to RF_PriorityNormal.
A callback function pCb might be specified to get notified about events during command execution. Events are subscribed by the bit mask bmEvent. Valid event flags are specified in RF_Core_Events and RF_Driver_Events. If no callback is set, RF_pendCmd() can be used to synchronize the current task to command execution. For this it is necessary to subscribe all relevant events. The termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted and RF_EventCmdStopped are always implicitly subscribed.
The following limitations apply to the execution of command chains:
h | Driver handle previously returned by RF_open() |
pOp | Pointer to the RF operation command. |
ePri | Priority of this RF command (used for arbitration in multi-client systems) |
pCb | Callback function called during command execution and upon completion. If RF_postCmd() fails, no callback is made. |
bmEvent | Bitmask of events that will trigger the callback or that can be pended on. |
RF_ScheduleStatus RF_defaultSubmitPolicy | ( | RF_Cmd * | pCmdNew, |
RF_Cmd * | pCmdBg, | ||
RF_Cmd * | pCmdFg, | ||
List_List * | pPendQueue, | ||
List_List * | pDoneQueue | ||
) |
Sorts and adds commands to the RF driver internal command queue.
pCmdNew | Pointer to the command to be submitted. |
pCmdBg | Running background command. |
pCmdFg | Running foreground command. |
pPendQueue | Pointer to the head structure of pend queue. |
pDoneQueue | Pointer to the head structure of done queue.. |
RF_ExecuteAction RF_defaultExecutionPolicy | ( | RF_Cmd * | pCmdBg, |
RF_Cmd * | pCmdFg, | ||
List_List * | pPendQueue, | ||
List_List * | pDoneQueue, | ||
bool | bConflict, | ||
RF_Cmd * | conflictCmd | ||
) |
Makes a final decision before dispatching a scheduled command.
pCmdBg | Running background command. |
pCmdFg | Running foreground command. |
pPendQueue | Pointer to the head structure of pend queue. |
pDoneQueue | Pointer to the head structure of done queue. |
bConflict | Whether the incoming command conflicts with the ongoing. |
conflictCmd | Command that conflicts with ongoing. |
void RF_ScheduleCmdParams_init | ( | RF_ScheduleCmdParams * | pSchParams | ) |
Initialize the configuration structure to default values to be used with the RF_scheduleCmd() API.
pSchParams | Pointer to the configuration structure. |
RF_CmdHandle RF_scheduleCmd | ( | RF_Handle | h, |
RF_Op * | pOp, | ||
RF_ScheduleCmdParams * | pSchParams, | ||
RF_Callback | pCb, | ||
RF_EventMask | bmEvent | ||
) |
Schedule an RF operation (chain) to the command queue.
Schedule an RF_Op to the RF command queue of the client with handle h.
The command can be the first in a chain of RF operations or a standalone RF operation. If a chain of operations are posted they are treated atomically, i.e. either all or none of the chained operations are run.
All operations must be posted in strictly increasing chronological order. Function returns immediately.
Limitations apply to the operations posted:
h | Handle previously returned by RF_open() |
pOp | Pointer to the RF_Op. Must normally be in persistent and writable memory |
pSchParams | Pointer to the schedule command parameter structure |
pCb | Callback function called upon command completion (and some other events). If RF_scheduleCmd() fails no callback is made |
bmEvent | Bitmask of events that will trigger the callback. |
RF_EventMask RF_pendCmd | ( | RF_Handle | h, |
RF_CmdHandle | ch, | ||
RF_EventMask | bmEvent | ||
) |
Synchronizes the calling task to an RF operation command ch and returns accumulated event flags.
After having dispatched an RF operation represented by ch with RF_postCmd(), the command is running in parallel on the RF core. Thus, it might be desirable to synchronize the calling task to the execution of the command. With RF_pendCmd(), the application can block until one of the events specified in bmEvent occurs or until the command finishes. The function consumes and returns all accumulated event flags that occurred during execution if they have been previously subscribed by RF_postCmd(). Possible events are specified in RF_Core_Events and RF_Driver_Events. The termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted and RF_EventCmdStopped are always implicitly subscribed and can not be masked.
RF_pendCmd() may be called multiple times for the same command.
If RF_pendCmd() is called for a command handle representing a finished command, then only the RF_EventLastCmdDone flag is returned, regardless of how the command finished.
If the command has also a callback set, the callback is executed before RF_pendCmd() returns.
Example:
h | Driver handle previously returned by RF_open() |
ch | Command handle previously returned by RF_postCmd(). |
bmEvent | Bitmask of events that make RF_pendCmd() return. Termination events are always implicitly subscribed. |
RF_EventMask RF_runCmd | ( | RF_Handle | h, |
RF_Op * | pOp, | ||
RF_Priority | ePri, | ||
RF_Callback | pCb, | ||
RF_EventMask | bmEvent | ||
) |
Runs synchronously an RF operation command or a chain of commands and returns the termination reason.
This function appends an RF operation command or a chain of commands to the RF driver's command queue and then waits for it to complete. A command is completed if one of the termination events RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted, RF_EventCmdStopped occurred.
This function is a combination of RF_postCmd() and RF_pendCmd(). All options and limitations for RF_postCmd() apply here as well.
An application should always ensure that the command completed in the expected way and with an expected status code.
h | Driver handle previously returned by RF_open() |
pOp | Pointer to the RF operation command. |
ePri | Priority of this RF command (used for arbitration in multi-client systems) |
pCb | Callback function called during command execution and upon completion. If RF_runCmd() fails, no callback is made. |
bmEvent | Bitmask of events that will trigger the callback or that can be pended on. |
RF_EventMask RF_runScheduleCmd | ( | RF_Handle | h, |
RF_Op * | pOp, | ||
RF_ScheduleCmdParams * | pSchParams, | ||
RF_Callback | pCb, | ||
RF_EventMask | bmEvent | ||
) |
Runs synchronously a (chain of) RF operation(s) for dual or single-mode.
Allows a (chain of) operation(s) to be scheduled to the command queue and then waits for it to complete.
A command is completed if one of the RF_EventLastCmdDone, RF_EventCmdCancelled, RF_EventCmdAborted, RF_EventCmdStopped occurred.
h | Handle previously returned by RF_open() |
pOp | Pointer to the RF_Op. Must normally be in persistent and writable memory |
pSchParams | Pointer to the schedule command parameter structure |
pCb | Callback function called upon command completion (and some other events). If RF_runScheduleCmd() fails, no callback is made. |
bmEvent | Bitmask of events that will trigger the callback. |
RF_Stat RF_cancelCmd | ( | RF_Handle | h, |
RF_CmdHandle | ch, | ||
uint8_t | mode | ||
) |
Abort/stop/cancel single command in command queue.
If command is running, aborts/stops it and posts callback for the aborted/stopped command.
If command has not yet run, cancels it it and posts callback for the canceled command.
If command has already run or been aborted/stopped/canceled, has no effect.
If RF_cancelCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.
h | Handle previously returned by RF_open() |
ch | Command handle previously returned by RF_postCmd(). |
mode | 1: Stop gracefully, 0: abort abruptly |
RF_Stat RF_flushCmd | ( | RF_Handle | h, |
RF_CmdHandle | ch, | ||
uint8_t | mode | ||
) |
Abort/stop/cancel command and any subsequent commands in command queue.
If command is running, aborts/stops it and then cancels all later commands in queue.
If command has not yet run, cancels it and all later commands in queue.
If command has already run or been aborted/stopped/canceled, has no effect.
The callbacks for all canceled commands are issued in chronological order.
If RF_flushCmd is called from a Swi context with same or higher priority than RF Driver Swi, when the RF core is powered OFF -> the cancel callback will be delayed until the next power-up cycle.
h | Handle previously returned by RF_open() |
ch | Command handle previously returned by RF_postCmd(). |
mode | 1: Stop gracefully, 0: abort abruptly |
Send any Immediate command.
Immediate Command is send to RDBELL, if radio is active and the RF_Handle points to the current client.
In other appropriate RF_Stat values are returned.
h | Handle previously returned by RF_open() |
pCmdStruct | Pointer to the immediate command structure |
Send any Direct command.
Direct Command value is send to RDBELL immediately, if radio is active and the RF_Handle point to the current client.
In other appropriate RF_Stat values are returned.
h | Handle previously returned by RF_open() |
cmd | Direct command value. |
void RF_yield | ( | RF_Handle | h | ) |
Signal that radio client is not going to issue more commands in a while.
Hint to RF driver that, irrespective of inactivity timeout, no new further commands will be issued for a while and thus the radio can be powered down at the earliest convenience. In case the RF_yield() is called within a callback, the callback will need to finish and return before the power down sequence is initiated. Posting new commands to the queue will cancel any pending RF_yield() request.
h | Handle previously returned by RF_open() |
void RF_Params_init | ( | RF_Params * | params | ) |
RF_Stat RF_getInfo | ( | RF_Handle | h, |
RF_InfoType | type, | ||
RF_InfoVal * | pValue | ||
) |
Get value for some RF driver parameters.
h | Handle previously returned by RF_open() |
type | Request value parameter defined by RF_InfoType |
pValue | Pointer to return parameter values specified by RF_InfoVal |
int8_t RF_getRssi | ( | RF_Handle | h | ) |
Get RSSI value.
h | Handle previously returned by RF_open() |
RF_Op* RF_getCmdOp | ( | RF_Handle | h, |
RF_CmdHandle | cmdHnd | ||
) |
Get command structure pointer.
h | Handle previously returned by RF_open() |
cmdHnd | Command handle returned by RF_postCmd() |
void RF_RatConfigCompare_init | ( | RF_RatConfigCompare * | channelConfig | ) |
Initialize the configuration structure to be used to set up a RAT compare event.
channelConfig | Pointer to the compare configuration structure. |
void RF_RatConfigCapture_init | ( | RF_RatConfigCapture * | channelConfig | ) |
Initialize the configuration structure to be used to set up a RAT capture event.
channelConfig | Pointer to the capture configuration structure. |
void RF_RatConfigOutput_init | ( | RF_RatConfigOutput * | ioConfig | ) |
Initialize the configuration structure to be used to set up a RAT IO.
ioConfig | Pointer to the IO configuration structure. |
RF_RatHandle RF_ratCompare | ( | RF_Handle | rfHandle, |
RF_RatConfigCompare * | channelConfig, | ||
RF_RatConfigOutput * | ioConfig | ||
) |
Setup a Radio Timer (RAT) channel in compare mode.
The RF_ratCompare() API sets up one of the three available RAT channels in compare mode. When the compare event happens at the given compare time, the registered callback is invoked.
The RF driver handles power management. If the provided compare time is far into the future (and there is no other constraint set i.e. due to radio command execution), the RF core will be powered OFF and the device will enter the lowest possible power state. The RF core will be automatically powered ON just before the registered compare event. The callback function is served upon expiration of the allocated channel. The function is invoked with event type RF_EventRatCh and runs in SWI context.
The API generates a "one-shot" compare event. Since the channel is automatically freed before the callback is served, the same channel can be reallocated from the callback itself through a new API call.
In case there were no available channels at the time of API call, the function returns with RF_ALLOC_ERROR and no callback is invoked.
In case a runtime error occurs after the API successfully allocated a channel, the registered callback is invoked with event type RF_EventError. A typical example is when the provided compare time is in the past and rejected by the RF core itself.
The events issued by the RAT timer can be output from the timer module through the RAT_GPO interface, and can be interconnected with other parts of the system through the RFC_GPO or the Event Fabric. The mapping between the allocated RAT channel and the selected RAT_GPO can be controlled through the optional ioConfig argument of RF_ratCompare(). The possible RAT_GPO[x] are defined in RF_RatOutputSelect.
rfHandle | Handle previously returned by RF_open(). |
channelConfig | Pointer to configuration structure needed to set up a channel in compare mode. |
ioConfig | Pointer to a configuration structure to set up the RAT_GPOs for the allocated channel (optional). |
RF_RatHandle RF_ratCapture | ( | RF_Handle | rfHandle, |
RF_RatConfigCapture * | channelConfig, | ||
RF_RatConfigOutput * | ioConfig | ||
) |
Setup a Radio Timer (RAT) channel in capture mode.
The RF_ratCapture() API sets up one of the three available RAT channels in capture mode. The registered callback is invoked on the capture event.
The RF driver handles power management. If the RF core is OFF when the RF_ratCapture() is called, it will be powered ON immediately and the RAT channel will be configured to capture mode. As long as at least one of the three RAT channels are in capture mode, the RF core will be kept ON. The callback function is served upon a capture event occurs. The function is invoked with event type RF_EventRatCh and runs in SWI context.
In case the channel is configured into single capture mode, the channel is automatically freed before the callback is called. In repeated capture mode, the channel remains allocated and automatically rearmed.
In case there were no available channels at the time of API call, the function returns with RF_ALLOC_ERROR and no callback is invoked.
In case a runtime error occurs after the API successfully allocated a channel, the registered callback is invoked with event type RF_EventError. A typical example is when the provided compare time is in the past and rejected by the RF core itself.
The events issued by the RAT timer can be output from the timer module through the RAT_GPO interface, and can be interconnected with other parts of the system through the RFC_GPO or the Event Fabric. The mapping between the allocated RAT channel and the selected RAT_GPO can be controlled through the optional ioConfig argument of RF_ratCapture(). The possible RAT_GPO[x] are defined in RF_RatOutputSelect. Note that this configuration is independent of the source signal of the capture event.
rfHandle | Handle previously returned by RF_open(). |
channelConfig | Pointer to configuration structure needed to set up a channel in compare mode. |
ioConfig | Pointer to a configuration structure to set up the RAT_GPO for the allocated channel (optional). |
RF_Stat RF_ratDisableChannel | ( | RF_Handle | rfHandle, |
RF_RatHandle | ratHandle | ||
) |
Disable a RAT channel.
The RF_RatHandle returned by the RF_ratCompare() or RF_ratCapture() APIs can be used for further interaction with the Radio Timer. Passing the handle to RF_ratDisableChannel() will abort a compare/capture event, and the provided channel is deallocated. No callback is invoked. This API can be called both if the RF core is ON or OFF. After the channel is freed, the next radio event will be rescheduled. A typical use case if a channel is configured in repeated capture mode, and the application decides to abort this operation.
rfHandle | Handle previously returned by RF_open(). |
ratHandle | RF_RatHandle returned by RF_ratCompare() or RF_ratCapture(). |
Set RF control parameters.
h | Handle previously returned by RF_open() |
ctrl | Control codes |
args | Pointer to control arguments |
RF_Stat RF_requestAccess | ( | RF_Handle | h, |
RF_AccessParams * | pParams | ||
) |
Request radio access.
Scope:
h | Handle previously returned by RF_open() |
pParams | Pointer to RF_AccessRequest parameters |
RF_TxPowerTable_Value RF_getTxPower | ( | RF_Handle | h | ) |
Returns the currently configured transmit power configuration.
This function returns the currently configured transmit power configuration under the assumption that it has been previously set by RF_setTxPower(). The value might be used for reverse lookup in a TX power table. If no power has been programmed, it returns an invalid value.
h | Handle previously returned by RF_open() |
RF_Stat RF_setTxPower | ( | RF_Handle | h, |
RF_TxPowerTable_Value | value | ||
) |
Updates the transmit power configuration of the RF core.
This function programs a new TX power value and returns a status code. The API will return with RF_StatBusyError if there are still pending commands in the internal queue. In case of success, RF_StatSuccess is returned and the new configuration becomes effective from the next radio operation.
Some devices provide an integrated high-power PA in addition to the Default PA. On these devices the API accepts configurations for both, and if value selects a different PA, the globalCallback is invoked. The implementation of globalCallback is board specific and can be used to reconfigure the external RF switches (if any).
h | Handle previously returned by RF_open() |
value | TX power configuration value. |
int8_t RF_TxPowerTable_findPowerLevel | ( | RF_TxPowerTable_Entry | table[], |
RF_TxPowerTable_Value | value | ||
) |
Retrieves a power level in dBm for a given power configuration value.
RF_TxPowerTable_findPowerLevel
() searches in a lookup table for a given transmit power configuration value and returns the power level in dBm if a matching configuration is found. If value can not be found, RF_TxPowerTable_INVALID_DBM is returned.
This function does a reverse lookup compared to RF_TxPowerTable_findValue() and has O(n). It is assumed that table is terminated by a RF_TxPowerTable_TERMINATION_ENTRY.
table | List of RF_TxPowerTable_Entry entries, terminated by RF_TxPowerTable_TERMINATION_ENTRY. |
value | Power configuration value. |
RF_TxPowerTable_Value RF_TxPowerTable_findValue | ( | RF_TxPowerTable_Entry | table[], |
int8_t | powerLevel | ||
) |
Retrieves a power configuration value for a given power level in dBm.
RF_TxPowerTable_findValue
() searches in a lookup table for a given transmit power level powerLevel in dBm and returns a matching power configuration. If powerLevel can not be found, RF_TxPowerTable_INVALID_VALUE is returned.
This function performs a linear search in table and has O(n). It is assumed that table is defined in ascending order and is terminated by a RF_TxPowerTable_TERMINATION_ENTRY.
The following special values for powerLevel are also accepted:
table | List of RF_TxPowerTable_Entry entries, terminated by RF_TxPowerTable_TERMINATION_ENTRY. |
powerLevel | Human-readable power level in dBm. |
RF_Stat RF_enableHPOSCTemperatureCompensation | ( | void | ) |
Enables temperature monitoring and temperature based drift compensation.