Microchip® Advanced Software Framework

tal.h File Reference

This file contains TAL API function declarations.

Copyright (c) 2013-2018 Microchip Technology Inc. and its subsidiaries.

#include <stdint.h>
#include <stdbool.h>
#include "pal.h"
#include "tal_config.h"
#include "tal_generic.h"
#include "bmm.h"
#include "stack_config.h"
#include "return_val.h"
#include "tal_types.h"
#include "mac_build_config.h"
#include "qmm.h"

Data Structures

struct  frame_info_tag
 Globally used frame information structure. More...
 
struct  tal_pib_tag
 

Macros

#define BAND_2400   (1)
 2.4 GHz (channels 11 through 26) More...
 
#define BAND_900   (0)
 868 / 910 MHz (channels 0 through 10) using BPSK More...
 
#define BAND_MULTIPLE   (2)
 450 / 900 MHz and 2.4 GHz - Multiple band support More...
 
#define mac_i_pan_coordinator   (0x0B)
 Attribute id of mac_i_pan_coordinator PIB. More...
 
#define MAX_CHANNEL   (26)
 Maximum channel. More...
 
#define MAX_FRAME_DURATION
 Maximum number of symbols in a frame for the current PHY. More...
 
#define MAX_SYMBOL_TIME   (0x0FFFFFFF)
 The maximum time in symbols for a 32 bit timer. More...
 
#define MIN_CHANNEL   (11)
 Minimum channel. More...
 
#define NO_OF_SYMBOLS_PREAMBLE_SFD
 Number of symbols forming the synchronization header (SHR) for the current PHY. More...
 
#define NO_SYMBOLS_PREAMBLE   (8)
 Number of symbols included in the preamble. More...
 
#define NO_SYMBOLS_SFD   (2)
 Number of symbols included in the SFD field. More...
 
#define NUM_TRX   1
 
#define RF_BAND   BAND_2400
 RF band. More...
 
#define SYMBOL_MASK   (0x0FFFFFFF)
 Symbol mask for ignoring most significant nibble. More...
 
#define SYMBOLS_PER_OCTET   (2)
 Symbols per octet. More...
 
#define TAL_BIT_MASK(ADDR, MASK, POS)   MASK
 Get bit mask from sub register definition. More...
 
#define TAL_BIT_POS(ADDR, MASK, POS)   POS
 Get bit position from sub register definition. More...
 
#define TAL_CONVERT_SYMBOLS_TO_US(symbols)
 Conversion of symbols to microseconds. More...
 
#define TAL_CONVERT_US_TO_SYMBOLS(time)   ((time) >> 4)
 Conversion of microseconds to symbols. More...
 
#define TAL_GET_BEACON_INTERVAL_TIME(BO)   ((1UL * aBaseSuperframeDuration) << (BO))
 Beacon Interval time in symbols. More...
 
#define TAL_GET_SUPERFRAME_DURATION_TIME(SO)   ((1UL * aBaseSuperframeDuration) << (SO))
 Superframe Duration time in symbols. More...
 
#define VALID_CHANNEL_MASK   (0x07FFF800UL)
 Valid channel masks for scanning. More...
 

Typedefs

typedef enum csma_mode_tag csma_mode_t
 CSMA Mode supported by transceiver. More...
 
typedef struct frame_info_tag frame_info_t
 Globally used frame information structure. More...
 
typedef enum sleep_mode_tag sleep_mode_t
 Sleep Mode supported by transceiver. More...
 
typedef __PACK__DATA__ struct
tal_pib_tag 
tal_pib_t
 

Enumerations

enum  csma_mode_tag {
  NO_CSMA_NO_IFS,
  NO_CSMA_WITH_IFS,
  CSMA_UNSLOTTED,
  CSMA_SLOTTED
}
 CSMA Mode supported by transceiver. More...
 
enum  SHORTENUM {
  ASSOCIATIONREQUEST = (0x01),
  ASSOCIATIONRESPONSE,
  DISASSOCIATIONNOTIFICATION,
  DATAREQUEST,
  PANIDCONFLICTNOTIFICAION,
  ORPHANNOTIFICATION,
  BEACONREQUEST,
  COORDINATORREALIGNMENT,
  GTSREQUEST,
  ORPHANREALIGNMENT,
  BEACON_MESSAGE,
  DATAREQUEST_IMPL_POLL,
  NULL_FRAME,
  MCPS_MESSAGE,
  STB_CCM_OK = 0,
  STB_CCM_ILLPARM,
  STB_CCM_KEYMISS,
  STB_CCM_MICERR,
  SECURITY_00_LEVEL = 0x00,
  SECURITY_01_LEVEL,
  SECURITY_02_LEVEL,
  SECURITY_03_LEVEL,
  SECURITY_04_LEVEL,
  SECURITY_05_LEVEL,
  SECURITY_06_LEVEL,
  SECURITY_07_LEVEL
}
 MAC Message types. More...
 
enum  sleep_mode_tag { SLEEP_MODE_1 }
 Sleep Mode supported by transceiver. More...
 

Functions

static uint32_t tal_add_time_symbols (uint32_t a, uint32_t b)
 Adds two time values. More...
 
void tal_ed_end_cb (uint8_t energy_level)
 User call back function for finished ED Scan. More...
 
retval_t tal_ed_start (uint8_t scan_duration)
 Starts ED Scan. More...
 
void tal_generate_rand_seed (void)
 Generates a 16-bit random number used as initial seed for srand() More...
 
retval_t tal_init (void)
 Initializes the TAL. More...
 
retval_t tal_pib_get (uint8_t attribute, uint8_t *value)
 Gets a TAL PIB attribute. More...
 
retval_t tal_pib_set (uint8_t attribute, pib_value_t *value)
 Sets a TAL PIB attribute. More...
 
retval_t tal_reset (bool set_default_pib)
 Resets TAL state machine and sets the default PIB values if requested. More...
 
uint8_t tal_rx_enable (uint8_t state)
 Switches receiver on or off. More...
 
void tal_rx_frame_cb (frame_info_t *rx_frame)
 User call back function for frame reception. More...
 
static uint32_t tal_sub_time_symbols (uint32_t a, uint32_t b)
 Subtract two time values. More...
 
void tal_task (void)
 TAL task handling. More...
 
retval_t tal_trx_sleep (sleep_mode_t mode)
 Sets the transceiver to sleep. More...
 
retval_t tal_trx_wakeup (void)
 Wakes up the transceiver from sleep. More...
 
void tal_tx_beacon (frame_info_t *tx_frame)
 Beacon frame transmission. More...
 
retval_t tal_tx_frame (frame_info_t *tx_frame, csma_mode_t csma_mode, bool perform_frame_retry)
 Requests to TAL to transmit frame. More...
 
void tal_tx_frame_done_cb (retval_t status, frame_info_t *frame)
 User call back function for frame transmission. More...
 

Variables

tal_pib_t tal_pib
 

#define BAND_2400   (1)

2.4 GHz (channels 11 through 26)

#define BAND_900   (0)

868 / 910 MHz (channels 0 through 10) using BPSK

#define BAND_MULTIPLE   (2)

450 / 900 MHz and 2.4 GHz - Multiple band support

#define mac_i_pan_coordinator   (0x0B)

Attribute id of mac_i_pan_coordinator PIB.

Referenced by mlme_start_request(), and tal_pib_set().

#define MAX_CHANNEL   (26)

Maximum channel.

Referenced by scan_proceed().

#define MAX_FRAME_DURATION
Value:
#define aMaxPHYPacketSize
Maximum size of PHY packet.
Definition: ieee_const.h:81
#define NO_OF_SYMBOLS_PREAMBLE_SFD
Number of symbols forming the synchronization header (SHR) for the current PHY.
Definition: tal.h:839
#define SYMBOLS_PER_OCTET
Symbols per octet.
Definition: tal.h:777

Maximum number of symbols in a frame for the current PHY.

This value is the base for the PHY PIB attribute phyMaxFrameDuration.

Referenced by recalc_macMaxFrameTotalWaitTime().

#define MAX_SYMBOL_TIME   (0x0FFFFFFF)

The maximum time in symbols for a 32 bit timer.

Referenced by tal_sub_time_symbols().

#define MIN_CHANNEL   (11)

Minimum channel.

Referenced by mac_awake_scan().

#define NO_OF_SYMBOLS_PREAMBLE_SFD
Value:
#define NO_SYMBOLS_PREAMBLE
Number of symbols included in the preamble.
Definition: tal.h:779
#define NO_SYMBOLS_SFD
Number of symbols included in the SFD field.
Definition: tal.h:781

Number of symbols forming the synchronization header (SHR) for the current PHY.

This value is the base for the PHY PIB attribute phySHRDuration.

#define NO_SYMBOLS_PREAMBLE   (8)

Number of symbols included in the preamble.

#define NO_SYMBOLS_SFD   (2)

Number of symbols included in the SFD field.

#define NUM_TRX   1
#define RF_BAND   BAND_2400

RF band.

#define SYMBOL_MASK   (0x0FFFFFFF)

Symbol mask for ignoring most significant nibble.

Referenced by tal_add_time_symbols(), and tal_sub_time_symbols().

#define SYMBOLS_PER_OCTET   (2)

Symbols per octet.

Referenced by mac_process_beacon_frame(), and tx_done_handling().

#define TAL_BIT_MASK (   ADDR,
  MASK,
  POS 
)    MASK

Get bit mask from sub register definition.

#define TAL_BIT_POS (   ADDR,
  MASK,
  POS 
)    POS

Get bit position from sub register definition.

#define TAL_GET_BEACON_INTERVAL_TIME (   BO)    ((1UL * aBaseSuperframeDuration) << (BO))
#define TAL_GET_SUPERFRAME_DURATION_TIME (   SO)    ((1UL * aBaseSuperframeDuration) << (SO))
#define VALID_CHANNEL_MASK   (0x07FFF800UL)

Valid channel masks for scanning.

typedef enum csma_mode_tag csma_mode_t

CSMA Mode supported by transceiver.

typedef struct frame_info_tag frame_info_t

Globally used frame information structure.

Sleep Mode supported by transceiver.

CSMA Mode supported by transceiver.

Enumerator
NO_CSMA_NO_IFS 
NO_CSMA_WITH_IFS 
CSMA_UNSLOTTED 
CSMA_SLOTTED 
enum SHORTENUM

MAC Message types.

Enumerator
ASSOCIATIONREQUEST 
ASSOCIATIONRESPONSE 
DISASSOCIATIONNOTIFICATION 
DATAREQUEST 
PANIDCONFLICTNOTIFICAION 
ORPHANNOTIFICATION 
BEACONREQUEST 
COORDINATORREALIGNMENT 
GTSREQUEST 
ORPHANREALIGNMENT 
BEACON_MESSAGE 
DATAREQUEST_IMPL_POLL 
NULL_FRAME 
MCPS_MESSAGE 
STB_CCM_OK 

CCM en/decryption OK.

STB_CCM_ILLPARM 

Illegal parameter value in stb_ccm_secure()

STB_CCM_KEYMISS 

No previous key init in stb_ccm_secure()

STB_CCM_MICERR 

MIC error detected in stb_ccm_secure()

SECURITY_00_LEVEL 

Security Level 0.

SECURITY_01_LEVEL 

Security Level 1.

SECURITY_02_LEVEL 

Security Level 2.

SECURITY_03_LEVEL 

Security Level 3.

SECURITY_04_LEVEL 

Security Level 4.

SECURITY_05_LEVEL 

Security Level 5.

SECURITY_06_LEVEL 

Security Level 6.

SECURITY_07_LEVEL 

Security Level 7.

Sleep Mode supported by transceiver.

Enumerator
SLEEP_MODE_1 

static uint32_t tal_add_time_symbols ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Adds two time values.

This function adds two time values

Parameters
aTime value 1
bTime value 2
Returns
value of a + b

References SYMBOL_MASK.

Referenced by check_beacon_reception(), csma_backoff_calculation(), mlme_rx_enable_request(), process_data_ind_not_transient(), and tal_tx_frame().

void tal_ed_end_cb ( uint8_t  energy_level)

User call back function for finished ED Scan.

Parameters
energy_levelMeasured energy level during ED Scan

User call back function for finished ED Scan.

This function is a callback function from the TAL after ED scan is performed on a specified channel.

Parameters
energy_levelMaximum energy on the channel

References BMM_BUFFER_POINTER, scan_result_list_t::ed_value, mac_conf_buf_ptr, MAKE_MAC_NOT_BUSY, MLME_SCAN_TYPE_ED, mlme_scan_conf_tag::ResultListSize, scan_curr_channel, scan_proceed(), mlme_scan_conf_tag::scan_result_list, and mlme_scan_conf_tag::UnscannedChannels.

Referenced by ed_scan_done().

retval_t tal_pib_get ( uint8_t  attribute,
uint8_t *  value 
)

Gets a TAL PIB attribute.

This function is called to retrieve the transceiver information base attributes.

Parameters
[in]attributeTAL infobase attribute ID
[out]valueTAL infobase attribute value
Returns
MAC_UNSUPPORTED_ATTRIBUTE if the TAL infobase attribute is not found MAC_SUCCESS otherwise
uint8_t tal_rx_enable ( uint8_t  state)

Switches receiver on or off.

This function switches the receiver on (PHY_RX_ON) or off (PHY_TRX_OFF).

Parameters
stateNew state of receiver
Returns
  • TAL_BUSY if the TAL state machine cannot switch receiver on or off,
  • PHY_TRX_OFF if receiver has been switched off, or
  • PHY_RX_ON otherwise.

References CMD_RX_AACK_ON, CMD_RX_ON, CMD_TRX_OFF, PHY_TRX_OFF, RX_ON, set_trx_state(), TAL_BUSY, TAL_IDLE, tal_pib, tal_rx_buffer, tal_rx_on_required, TAL_SLOTTED_CSMA, tal_state, and TRX_OFF.

Referenced by mac_rx_enable(), mac_soft_reset(), mac_t_rx_off_cb(), mac_t_tracking_beacons_cb(), mlme_set(), mlme_start_request(), mlme_sync_request(), process_data_ind_not_transient(), and scan_set_complete().

void tal_rx_frame_cb ( frame_info_t frame)

User call back function for frame reception.

Parameters
rx_framePointer to received frame structure of type frame_info_t or to received frame array

User call back function for frame reception.

This function pushes an event into the TAL-MAC queue, indicating a frame reception.

Parameters
framePointer to recived frame

References Assert, frame_info_tag::buffer_header, frame_info_tag::msg_type, qmm_queue_append(), TAL_DATA_INDICATION, and tal_mac_q.

Referenced by process_incoming_frame().

static uint32_t tal_sub_time_symbols ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Subtract two time values.

This function subtracts two time values taking care of roll over.

Parameters
aTime value 1
bTime value 2
Returns
value a - b

References MAX_SYMBOL_TIME, and SYMBOL_MASK.

Referenced by csma_backoff_calculation(), mac_start_beacon_timer(), mlme_rx_enable_request(), process_data_ind_not_transient(), and tal_tx_frame().

void tal_task ( void  )

TAL task handling.

This function

  • Checks and allocates the receive buffer.
  • Processes the TAL incoming frame queue.
  • Implements the TAL state machine.

References Assert, bmm_buffer_alloc(), CMD_RX_AACK_ON, CMD_RX_ON, ed_scan_done(), LARGE_BUFFER_SIZE, process_incoming_frame(), qmm_queue_remove(), set_trx_state(), queue_tag::size, slotted_csma_state_handling(), TAL_ED_DONE, TAL_ED_RUNNING, TAL_IDLE, tal_pib, tal_rx_on_required, TAL_SLOTTED_CSMA, tal_state, TAL_TX_AUTO, TAL_TX_DONE, and tx_done_handling().

Referenced by wpan_task().

retval_t tal_trx_sleep ( sleep_mode_t  mode)

Sets the transceiver to sleep.

This function sets the transceiver to sleep state.

Parameters
modeDefines sleep mode of transceiver SLEEP or PHY_TRX_OFF)
Returns
TAL_BUSY - The transceiver is busy in TX or RX MAC_SUCCESS - The transceiver is put to sleep TAL_TRX_ASLEEP - The transceiver is already asleep MAC_INVALID_PARAMETER - The specified sleep mode is not supported

References CMD_DEEP_SLEEP, CMD_SLEEP, CMD_TRX_OFF, MAC_INVALID_PARAMETER, MAC_SUCCESS, pal_timer_source_select(), pal_timer_stop(), set_trx_state(), SLEEP_MODE_1, stb_restart(), TAL_BUSY, TAL_IDLE, tal_rx_on_required, tal_state, TAL_TRX_ASLEEP, tal_trx_status, TMR_CLK_SRC_DURING_TRX_SLEEP, TRX_DEEP_SLEEP, TRX_OFF, and TRX_SLEEP.

Referenced by mac_trx_init_sleep(), and mlme_set().

retval_t tal_trx_wakeup ( void  )

Wakes up the transceiver from sleep.

This function awakes the transceiver from sleep state.

Returns
TAL_TRX_AWAKE - The transceiver is already awake MAC_SUCCESS - The transceiver is woken up from sleep FAILURE - The transceiver did not wake-up from sleep

References Assert, CMD_TRX_OFF, FAILURE, FUNC_PTR, MAC_SUCCESS, pal_timer_source_select(), pal_timer_start(), set_trx_state(), TAL_TRX_AWAKE, tal_trx_status, TIMEOUT_RELATIVE, TMR_CLK_SRC_DURING_TRX_AWAKE, TRX_DEEP_SLEEP, TRX_OFF, and TRX_SLEEP.

Referenced by mac_trx_wakeup(), mlme_set(), stb_ccm_secure(), and tal_pib_set().

void tal_tx_beacon ( frame_info_t tx_frame)

Beacon frame transmission.

Parameters
tx_framePointer to the frame_info_t structure

References Assert, CMD_PLL_ON, frame_info_tag::mpdu, pal_trx_irq_dis, pal_trx_irq_en, PAL_WAIT_65_NS, PLL_ON, set_trx_state(), tal_beacon_transmission, tal_state, TAL_TX_AUTO, trx_frame_write(), TRX_SLP_TR_HIGH, and TRX_SLP_TR_LOW.

Referenced by mac_t_beacon_cb().

retval_t tal_tx_frame ( frame_info_t tx_frame,
csma_mode_t  csma_mode,
bool  perform_frame_retry 
)

Requests to TAL to transmit frame.

This function is called by the MAC to deliver a frame to the TAL to be transmitted by the transceiver.

Parameters
tx_framePointer to the frame_info_t structure or to frame array to be transmitted
csma_modeIndicates mode of csma-ca to be performed for this frame
perform_frame_retryIndicates whether to retries are to be performed for this frame
Returns
MAC_SUCCESS if the TAL has accepted the data from the MAC for frame transmission TAL_BUSY if the TAL is busy servicing the previous MAC request

References aUnitBackoffPeriod, calculate_transaction_duration(), CSMA_SLOTTED, last_frame_length, MAC_CHANNEL_ACCESS_FAILURE, mac_frame_ptr, MAC_INVALID_PARAMETER, MAC_SUCCESS, frame_info_tag::mpdu, NO_CSMA_WITH_IFS, NON_BEACON_NWK, pal_get_current_time(), send_frame(), slotted_csma_start(), tal_add_time_symbols(), TAL_BUSY, TAL_CONVERT_US_TO_SYMBOLS, tal_frame_to_tx, TAL_GET_BEACON_INTERVAL_TIME, TAL_IDLE, tal_pib, tal_state, tal_sub_time_symbols(), and transaction_duration_periods.

Referenced by mac_awake_disassociate(), mac_build_and_tx_beacon(), mac_build_and_tx_data_req(), mac_handle_tx_null_data_frame(), mac_process_data_request(), mac_tx_coord_realignment_command(), mac_tx_gts_data(), mac_tx_pending_bc_data(), mcps_data_request(), mlme_associate_request(), mlme_gts_request(), send_scan_cmd(), and tx_pan_id_conf_notif().

void tal_tx_frame_done_cb ( retval_t  status,
frame_info_t frame 
)

User call back function for frame transmission.

Parameters
statusStatus of frame transmission attempt
framePointer to frame structure of type frame_info_t

User call back function for frame transmission.

This is a callback function from the TAL. It is used when an attempt to transmit a frame is finished.

Parameters
statusStatus of transmission
frameSpecifies pointer to the transmitted frame

References BEACONREQUEST, mac_process_tal_tx_status(), MAC_SCAN_ACTIVE, MAC_SCAN_ORPHAN, mac_scan_send_complete(), mac_scan_state, MAKE_MAC_NOT_BUSY, frame_info_tag::msg_type, and ORPHANNOTIFICATION.

Referenced by tx_done(), and tx_done_handling().

tal_pib_t tal_pib