This file contains TAL API function declarations.

#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 (tal_pib.CurrentPage == 0 ? 32 : 8)
	Number of symbols included in the preamble. More...

#define	NO_SYMBOLS_SFD (tal_pib.CurrentPage == 0 ? 8 : 2)
	Number of symbols included in the SFD field. More...

#define	NUM_TRX 1

#define	RF_BAND BAND_900

#define	SYMBOL_MASK (0x0FFFFFFF)
	Symbol mask for ignoring most significant nibble. More...

#define	SYMBOLS_PER_OCTET (tal_pib.CurrentPage == 0 ? 8 : 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)
	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_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...

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:

(NO_OF_SYMBOLS_PREAMBLE_SFD + \

(aMaxPHYPacketSize + 1) * SYMBOLS_PER_OCTET)

aMaxPHYPacketSize

#define aMaxPHYPacketSize

Maximum size of PHY packet.

Definition: ieee_const.h:81

NO_OF_SYMBOLS_PREAMBLE_SFD

#define NO_OF_SYMBOLS_PREAMBLE_SFD

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

Definition: tal.h:839

SYMBOLS_PER_OCTET

#define SYMBOLS_PER_OCTET

Symbols per octet.

Definition: tal.h:794

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

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

Referenced by apply_channel_page_configuration(), and 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:

(NO_SYMBOLS_PREAMBLE + \

NO_SYMBOLS_SFD)

NO_SYMBOLS_PREAMBLE

#define NO_SYMBOLS_PREAMBLE

Number of symbols included in the preamble.

Definition: tal.h:799

NO_SYMBOLS_SFD

#define NO_SYMBOLS_SFD

Number of symbols included in the SFD field.

Definition: tal.h:804

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

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

Referenced by apply_channel_page_configuration().

#define NO_SYMBOLS_PREAMBLE (tal_pib.CurrentPage == 0 ? 32 : 8)

Number of symbols included in the preamble.

#define NO_SYMBOLS_SFD (tal_pib.CurrentPage == 0 ? 8 : 2)

Number of symbols included in the SFD field.

#define NUM_TRX 1

#define RF_BAND BAND_900

#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 (tal_pib.CurrentPage == 0 ? 8 : 2)

Symbols per octet.

Referenced by apply_channel_page_configuration(), calc_frame_transmit_duration(), calculate_transaction_duration(), 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_CONVERT_SYMBOLS_TO_US ( symbols )

Value:

(tal_pib.CurrentPage == 0 ? \
    (tal_pib.CurrentChannel == \
    0 ? ((uint32_t)(symbols) * 50) : ((uint32_t)(symbols) * \
    25)) : \
    (tal_pib.CurrentChannel == \
    0 ? ((uint32_t)(symbols) * 40) : ((uint32_t)(symbols) << \
    4)) \
    )

Conversion of symbols to microseconds.

Referenced by csma_backoff_calculation(), handle_gts_data_req(), handle_rx_on(), mac_process_beacon_frame(), mac_process_tal_tx_status(), mac_scan_send_complete(), mac_start_missed_beacon_timer(), mac_t_gts_cb(), mac_t_response_wait_cb(), mlme_rx_enable_request(), perform_cca_twice(), process_data_ind_not_transient(), scan_set_complete(), send_frame(), start_beacon_loss_timer(), tal_convert_symbols_to_us_def(), and tx_done_handling().

#define TAL_CONVERT_US_TO_SYMBOLS ( time )

Value:

(tal_pib.CurrentPage == 0 ? \
    (tal_pib.CurrentChannel == 0 ? ((time) / 50) : ((time) / 25)) : \
    (tal_pib.CurrentChannel == 0 ? ((time) / 40) : ((time) >> 4)) \
    )

Conversion of microseconds to symbols.

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

#define TAL_GET_BEACON_INTERVAL_TIME ( BO ) ((1UL * aBaseSuperframeDuration) << (BO))

Beacon Interval time in symbols.

Referenced by check_beacon_reception(), mac_start_missed_beacon_timer(), mlme_rx_enable_request(), process_data_ind_not_transient(), start_beacon_loss_timer(), and tal_tx_frame().

#define TAL_GET_SUPERFRAME_DURATION_TIME ( SO ) ((1UL * aBaseSuperframeDuration) << (SO))

Superframe Duration time in symbols.

Referenced by csma_backoff_calculation(), handle_gts_data_req(), mac_t_gts_cb(), and process_data_ind_not_transient().

#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.

typedef enum sleep_mode_tag sleep_mode_t

Sleep Mode supported by transceiver.

typedef __PACK__DATA__ struct tal_pib_tag tal_pib_t

enum csma_mode_tag

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.

enum sleep_mode_tag

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

a	Time value 1
b	Time 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().

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]	attribute	TAL infobase attribute ID
[out]	value	TAL 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

state New 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_frame Pointer 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

frame Pointer 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

a	Time value 1
b	Time value 2

Returns: value a - b

References MAX_SYMBOL_TIME, and SYMBOL_MASK.

Referenced by csma_backoff_calculation(), 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, LARGE_BUFFER_SIZE, process_incoming_frame(), qmm_queue_remove(), set_trx_state(), queue_tag::size, slotted_csma_state_handling(), 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

mode	Defines 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_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_OFF, and TRX_SLEEP.

Referenced by mac_trx_init_sleep(), mlme_set(), and trx_config().

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_OFF, and TRX_SLEEP.

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

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_frame	Pointer to the frame_info_t structure or to frame array to be transmitted
csma_mode	Indicates mode of csma-ca to be performed for this frame
perform_frame_retry	Indicates 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_data_req(), mac_tx_gts_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

status	Status of frame transmission attempt
frame	Pointer 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

status	Status of transmission
frame	Specifies 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

Referenced by apply_channel_page_configuration(), build_data_frame(), check_beacon_reception(), check_for_pan_id_conflict_non_pc(), convert_phyTransmitPower_to_reg_value(), csma_backoff_calculation(), csma_param_init(), handle_gts_data_req(), handle_gts_sync_loss(), handle_received_frame_irq(), init_tal_pib(), limit_tx_pwr(), mac_awake_disassociate(), mac_awake_scan(), mac_build_and_tx_data_req(), mac_coord_realignment_command_tx_success(), mac_parse_bcn_gts_info(), mac_prep_disassoc_conf(), mac_process_beacon_frame(), mac_process_tal_data_ind(), mac_sleep_trans(), mac_start_missed_beacon_timer(), mac_sync_loss(), mac_t_gts_cb(), mcps_data_request(), mlme_associate_request(), mlme_disassociate_request(), mlme_get(), mlme_gts_request(), mlme_rx_enable_request(), mlme_scan_request(), mlme_start_request(), normalize_lqi(), parse_mpdu(), process_data_ind_not_transient(), process_incoming_frame(), recalc_macMaxFrameTotalWaitTime(), send_frame(), send_scan_cmd(), set_default_tx_pwr(), slotted_csma_start(), slotted_csma_state_handling(), start_beacon_loss_timer(), tal_get_rssi_base_val(), tal_init(), tal_pib_set(), tal_rx_enable(), tal_task(), tal_tx_frame(), tx_done_handling(), tx_pan_id_conf_notif(), and write_all_tal_pib_to_trx().

Microchip® Advanced Software Framework

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables