pal.h File Reference

PAL related APIs.

This header file declares prototypes of PAL APIs, enumerations used by TAL and MAC.

Id:

pal.h 27828 2011-07-25 09:33:49Z agasthian.s

Author

Microchip Technology Inc: http://www.microchip.com

Support: https://www.microchip.com/support/

#include <stdbool.h>
#include <stdint.h>
#include "pal_types.h"
#include "pal_config.h"
#include "pal_mcu_generic.h"
#include "app_config.h"

Macros
#define	ADD_TIME(a, b)   ((a) + (b))
	Adds two time values. More...
#define	PAL_RST_HIGH()   RST_HIGH()
	Macro to set Reset pin to high. More...
#define	PAL_RST_LOW()   RST_LOW()
	Macro to set Reset pin to low. More...
#define	PAL_SLP_TR_HIGH()   SLP_TR_HIGH()
	Macro to set SLP_TR pin to high. More...
#define	PAL_SLP_TR_LOW()   SLP_TR_LOW()
	Macro to set SLP_TR pin to low. More...
#define	pal_trx_irq_dis()   DISABLE_TRX_IRQ()
	Disables the transceiver main interrupt. More...
#define	pal_trx_irq_dis_tstamp()   DISABLE_TRX_IRQ_TSTAMP()
	Disables the transceiver timestamp interrupt. More...
#define	pal_trx_irq_en()   ENABLE_TRX_IRQ()
	Enables the transceiver main interrupt. More...
#define	pal_trx_irq_en_tstamp()   ENABLE_TRX_IRQ_TSTAMP()
	Enables the transceiver timestamp interrupt. More...
#define	pal_trx_irq_flag_clr()   CLEAR_TRX_IRQ()
	Clears the transceiver main interrupt. More...
#define	pal_trx_irq_flag_clr_awake()   (CLEAR_TRX_IRQ_AWAKE())
	Clears the transceiver AWAKE interrupt. More...
#define	pal_trx_irq_flag_clr_cca_ed()   (CLEAR_TRX_IRQ_CCA_ED())
	Clears the transceiver CCA_ED_END interrupt. More...
#define	pal_trx_irq_flag_clr_rx_end()   (CLEAR_TRX_IRQ_RX_END())
	Clears the transceiver RX_END interrupt. More...
#define	pal_trx_irq_flag_clr_tstamp()   CLEAR_TRX_IRQ_TSTAMP()
	Clears the transceiver timestamp interrupt. More...
#define	pal_trx_irq_flag_clr_tx_end()   (CLEAR_TRX_IRQ_TX_END())
	Clears the transceiver TX_END interrupt. More...
#define	PAL_TRX_IRQ_HIGH()   IRQ_PINGET()
	Macro to get the transceiver's main IRQ status. More...
#define	SUB_TIME(a, b)   ((a) - (b))
	Subtracts two time values. More...
#define	U16_TO_TARGET(x)   (x)
	This macro is used for handling endianness among the different CPUs. More...

Typedefs
typedef enum button_state_tag	button_state_t
	Button action. More...
typedef enum led_action_tag	led_action_t
	LED action. More...
typedef enum pin_state_tag	pin_state_t
	Pin State. More...
typedef enum ps_id_tag	ps_id_t
	IDs for persistence storage access. More...
typedef enum ps_type_tag	ps_type_t
	IDs for persistence storage type. More...
typedef enum pwr_mode_tag	pwr_mode_t
	Power modes. More...
typedef enum source_type_tag	source_type_t
	Timer clock source type. More...
typedef enum timeout_type_tag	timeout_type_t
	Timeout type. More...

Enumerations
enum	button_state_tag {   BUTTON_PRESSED,   BUTTON_OFF }
	Button action. More...
enum	led_action_tag {   LED_ON,   LED_OFF,   LED_TOGGLE }
	LED action. More...
enum	pin_state_tag {   LOW,   HIGH }
	Pin State. More...
enum	ps_id_tag {   PS_IEEE_ADDR,   PS_XTAL_TRIM }
	IDs for persistence storage access. More...
enum	ps_type_tag {   INTERN_EEPROM,   EXTERN_EEPROM }
	IDs for persistence storage type. More...
enum	pwr_mode_tag { SYSTEM_SLEEP }
	Power modes. More...
enum	source_type_tag {   TMR_CLK_SRC_DURING_TRX_SLEEP,   TMR_CLK_SRC_DURING_TRX_AWAKE }
	Timer clock source type. More...
enum	timeout_type_tag {   TIMEOUT_RELATIVE,   TIMEOUT_ABSOLUTE }
	Timeout type. More...

Functions
static uint32_t	pal_add_time_us (uint32_t a, uint32_t b)
	Adds two time values. More...
void	pal_alert (void)
	Alert indication. More...
void	pal_button_init (void)
	Button initialization. More...
button_state_t	pal_button_read (button_id_t button_no)
	Button handling. More...
bool	pal_calibrate_rc_osc (void)
	Calibrates the internal RC oscillator. More...
uint16_t	pal_generate_rand_seed (void)
	Generation of random seed for function srand() in case this is not supported by the transceiver (e.g. More...
void	pal_get_current_time (uint32_t *current_time)
	Gets current time. More...
static void	pal_global_irq_disable (void)
	Disables the global interrupt. More...
static void	pal_global_irq_enable (void)
	Enables the global interrupt. More...
retval_t	pal_init (void)
	Initialization of PAL. More...
bool	pal_is_timer_running (uint8_t timer_id)
	Checks if the timer of requested timer identifier is running. More...
void	pal_led (led_id_t led_no, led_action_t led_setting)
	LED handling. More...
void	pal_led_init (void)
	LED initialization. More...
retval_t	pal_ps_get (ps_type_t ps_type, uint16_t start_addr, uint16_t length, void *value)
	Get data from persistence storage. More...
retval_t	pal_ps_set (uint16_t start_addr, uint16_t length, void *value)
	Write data to persistence storage. More...
void	pal_sleep_mode (uint8_t sleep_mode)
	Sleep/Power handling. More...
static uint32_t	pal_sub_time_us (uint32_t a, uint32_t b)
	Subtracts two time values. More...
void	pal_task (void)
	Services timer and sio handler. More...
void	pal_timer_delay (uint16_t delay)
	Generates blocking delay. More...
void	pal_timer_source_select (source_type_t source)
	Selects timer clock source. More...
retval_t	pal_timer_start (uint8_t timer_id, uint32_t timer_count, timeout_type_t timeout_type, FUNC_PTR timer_cb, void *param_cb)
	Start regular timer. More...
retval_t	pal_timer_stop (uint8_t timer_id)
	Stops a running timer. More...
void	pal_trx_irq_init (FUNC_PTR trx_irq_cb)
	Initializes the transceiver main interrupt. More...
void	pal_trx_irq_init_awake (FUNC_PTR trx_irq_cb)
	Initializes the transceiver AWAKE interrupt. More...
void	pal_trx_irq_init_cca_ed (FUNC_PTR trx_irq_cb)
	Initializes the transceiver CCA ED END interrupt. More...
void	pal_trx_irq_init_rx_end (FUNC_PTR trx_irq_cb)
	Initializes the transceiver RX END interrupt. More...
void	pal_trx_irq_init_tstamp (FUNC_PTR trx_irq_cb)
	Initializes the transceiver timestamp interrupt. More...
void	pal_trx_irq_init_tx_end (FUNC_PTR trx_irq_cb)
	Initializes the transceiver TX END interrupt. More...
void	pal_trx_read_timestamp (uint32_t *timestamp)
	Provides timestamp of the last received frame. More...

#define ADD_TIME	(		a,
			b
	)		((a) + (b))

Adds two time values.

Referenced by pal_add_time_us().

#define PAL_RST_HIGH

(

)

RST_HIGH()

Macro to set Reset pin to high.

#define PAL_RST_LOW

(

)

RST_LOW()

Macro to set Reset pin to low.

#define PAL_SLP_TR_HIGH

(

)

SLP_TR_HIGH()

Macro to set SLP_TR pin to high.

#define PAL_SLP_TR_LOW

(

)

SLP_TR_LOW()

Macro to set SLP_TR pin to low.

#define pal_trx_irq_dis

(

)

DISABLE_TRX_IRQ()

Disables the transceiver main interrupt.

This macro is only available for non-single chip transceivers, since in single chip transceivers there is no separation between disabling transceiver interrupts at the transceiver, and clearing the IRQ mask at the MCU. Therefore the transceiver interrupts in single chips are disabled by clearing the MCU IRQ mask.

#define pal_trx_irq_dis_tstamp

(

)

DISABLE_TRX_IRQ_TSTAMP()

Disables the transceiver timestamp interrupt.

This macro is only available for non-single chip transceivers, since in single chip transceivers there is no separation between disabling transceiver interrupts at the transceiver, and clearing the IRQ mask at the MCU. Therefore the transceiver interrupts in single chips are disabled by clearing the MCU IRQ mask.

#define pal_trx_irq_en

(

)

ENABLE_TRX_IRQ()

Enables the transceiver main interrupt.

This macro is only available for non-single chip transceivers, since in single chip transceivers there is no separation between enabling transceiver interrupts at the transceiver, and setting the IRQ mask at the MCU. Therefore the transceiver interrupts in single chips are enabled by setting the MCU IRQ mask.

#define pal_trx_irq_en_tstamp

(

)

ENABLE_TRX_IRQ_TSTAMP()

Enables the transceiver timestamp interrupt.

This macro is only available for non-single chip transceivers, since in single chip transceivers there is no separation between enabling transceiver interrupts at the transceiver, and setting the IRQ mask at the MCU. Therefore the transceiver interrupts in single chips are enabled by setting the MCU IRQ mask.

#define pal_trx_irq_flag_clr

(

)

CLEAR_TRX_IRQ()

Clears the transceiver main interrupt.

#define pal_trx_irq_flag_clr_awake

(

)

(CLEAR_TRX_IRQ_AWAKE())

Clears the transceiver AWAKE interrupt.

#define pal_trx_irq_flag_clr_cca_ed

(

)

(CLEAR_TRX_IRQ_CCA_ED())

Clears the transceiver CCA_ED_END interrupt.

#define pal_trx_irq_flag_clr_rx_end

(

)

(CLEAR_TRX_IRQ_RX_END())

Clears the transceiver RX_END interrupt.

#define pal_trx_irq_flag_clr_tstamp

(

)

CLEAR_TRX_IRQ_TSTAMP()

Clears the transceiver timestamp interrupt.

#define pal_trx_irq_flag_clr_tx_end

(

)

(CLEAR_TRX_IRQ_TX_END())

Clears the transceiver TX_END interrupt.

#define PAL_TRX_IRQ_HIGH

(

)

IRQ_PINGET()

Macro to get the transceiver's main IRQ status.

#define SUB_TIME	(		a,
			b
	)		((a) - (b))

Subtracts two time values.

Referenced by pal_sub_time_us().

#define U16_TO_TARGET

(

x

)

(x)

This macro is used for handling endianness among the different CPUs.

typedef enum button_state_tag button_state_t

Button action.

typedef enum led_action_tag led_action_t

LED action.

typedef enum pin_state_tag pin_state_t

Pin State.

typedef enum ps_id_tag ps_id_t

IDs for persistence storage access.

typedef enum ps_type_tag ps_type_t

IDs for persistence storage type.

typedef enum pwr_mode_tag pwr_mode_t

Power modes.

typedef enum source_type_tag source_type_t

Timer clock source type.

typedef enum timeout_type_tag timeout_type_t

Timeout type.

enum button_state_tag

Button action.

Enumerator
BUTTON_PRESSED	Button is pressed.
BUTTON_OFF	Button is released.

enum led_action_tag

LED action.

Enumerator
LED_ON	Switch LED on.
LED_OFF	Switch LED off.
LED_TOGGLE	Toggle LED.

enum pin_state_tag

Pin State.

Enumerator
LOW	Pin state low.
HIGH	Pin state high.

enum ps_id_tag

IDs for persistence storage access.

Enumerator
PS_IEEE_ADDR
PS_XTAL_TRIM

enum ps_type_tag

IDs for persistence storage type.

Enumerator
INTERN_EEPROM	MCU Internal EEPROM.
EXTERN_EEPROM	External EEPROM.

enum pwr_mode_tag

Power modes.

Enumerator
SYSTEM_SLEEP

enum source_type_tag

Timer clock source type.

Enumerator
TMR_CLK_SRC_DURING_TRX_SLEEP	Identifier for timer clock source during sleep.
TMR_CLK_SRC_DURING_TRX_AWAKE	Identifier for timer clock source while being awake.

enum timeout_type_tag

Timeout type.

Enumerator
TIMEOUT_RELATIVE	The timeout is relative to the current time.
TIMEOUT_ABSOLUTE	The timeout is an absolute value.

static uint32_t pal_add_time_us ( uint32_t  a, uint32_t  b  )

inlinestatic

Adds two time values.

Parameters

a	Time value 1
b	Time value 2

Returns

Addition of a and b

References ADD_TIME.

void pal_alert

(

void

)

Alert indication.

This Function can be used by any application to indicate an error condition. The function is blocking and does never return.

Referenced by main().

void pal_button_init

(

void

)

Button initialization.

button_state_t pal_button_read

(

button_id_t

button_no

)

Button handling.

Parameters

button_no

Button id

Returns

• BUTTON_PRESSED if button is pressed,
• BUTTON_OFF if button is not pressed.

bool pal_calibrate_rc_osc

(

void

)

Calibrates the internal RC oscillator.

Returns

True if calibration is successful, false otherwise.

uint16_t pal_generate_rand_seed

(

void

)

Generation of random seed for function srand() in case this is not supported by the transceiver (e.g.

AT86RF230)

Returns

uint16_t Random number to be used as seed for function srand()

void pal_get_current_time

(

uint32_t *

current_time

)

Gets current time.

This function returns the current time.

Parameters

[out]

current_time

Returns current system time

static void pal_global_irq_disable ( void  )

inlinestatic

Disables the global interrupt.

References DISABLE_GLOBAL_IRQ.

static void pal_global_irq_enable ( void  )

inlinestatic

Enables the global interrupt.

References ENABLE_GLOBAL_IRQ.

Referenced by main().

retval_t pal_init

(

void

)

Initialization of PAL.

This function initializes the PAL. The RC Oscillator is calibrated.

Returns

MAC_SUCCESS if PAL initialization is successful, FAILURE otherwise

bool pal_is_timer_running

(

uint8_t

timer_id

)

Checks if the timer of requested timer identifier is running.

This function checks if the timer of requested timer identifier is running.

Parameters

timer_id

Timer identifier

Returns

• true if timer with requested timer id is running,
• false otherwise.

void pal_led	(	led_id_t	led_no,
		led_action_t	led_setting
	)

LED handling.

Parameters

led_no	LED id
led_setting	LED action

Referenced by led_handling(), main(), nlme_set_confirm(), pbp_pair_confirm(), Receive_Message(), and zrc_cmd_indication().

void pal_led_init

(

void

)

LED initialization.

Referenced by main().

retval_t pal_ps_get	(	ps_type_t	ps_type,
		uint16_t	start_addr,
		uint16_t	length,
		void *	value
	)

Get data from persistence storage.

Parameters

[in]	ps_type	Persistence storage type
[in]	start_addr	Start offset within EEPROM
[in]	length	Number of bytes to read from EEPROM
[out]	value	Data from persistence storage

Returns

MAC_SUCCESS if everything went OK else FAILURE

retval_t pal_ps_set	(	uint16_t	start_addr,
		uint16_t	length,
		void *	value
	)

Write data to persistence storage.

Parameters

[in]	start_addr	Start address offset within EEPROM
[in]	length	Number of bytes to be written to EEPROM
[in]	value	Data to persistence storage

Returns

MAC_SUCCESS if everything went OK else FAILURE

Referenced by main().

void pal_sleep_mode

(

uint8_t

sleep_mode

)

Sleep/Power handling.

Handles sleep/power modes for entire system

Parameters

sleep_mode

desired sleep/power mode, see sleep.h

static uint32_t pal_sub_time_us ( uint32_t  a, uint32_t  b  )

inlinestatic

Subtracts two time values.

Parameters

a	Time value 1
b	Time value 2

Returns

Difference between a and b

References SUB_TIME.

void pal_task

(

void

)

Services timer and sio handler.

This function calls sio & timer handling functions.

void pal_timer_delay

(

uint16_t

delay

)

Generates blocking delay.

This functions generates a blocking delay of specified time.

Parameters

delay

in microseconds

void pal_timer_source_select

(

source_type_t

source

)

Selects timer clock source.

This function selects the clock source of the timer.

Parameters

source

TMR_CLK_SRC_DURING_TRX_SLEEP if clock source during sleep is to be selected, and TMR_CLK_SRC_DURING_TRX_AWAKE if clock source while being awake is selected.

retval_t pal_timer_start	(	uint8_t	timer_id,
		uint32_t	timer_count,
		timeout_type_t	timeout_type,
		FUNC_PTR	timer_cb,
		void *	param_cb
	)

Start regular timer.

This function starts a regular timer and installs the corresponding callback function handle the timeout event.

Parameters

timer_id	Timer identifier
timer_count	Timeout in microseconds
timeout_type	TIMEOUT_RELATIVE or TIMEOUT_ABSOLUTE
timer_cb	Callback handler invoked upon timer expiry
param_cb	Argument for the callback handler

Returns

• PAL_TMR_INVALID_ID if the timer identifier is undefined,
• MAC_INVALID_PARAMETER if the callback function for this timer is NULL,
• PAL_TMR_ALREADY_RUNNING if the timer is already running.
• MAC_SUCCESS if timer is started or
• PAL_TMR_INVALID_TIMEOUT if timeout is not within timeout range.

Referenced by led_handling(), and nlme_set_confirm().

retval_t pal_timer_stop

(

uint8_t

timer_id

)

Stops a running timer.

This function stops a running timer with specified timer_id

Parameters

timer_id

Timer identifier

Returns

• MAC_SUCCESS if timer stopped successfully,
• PAL_TMR_NOT_RUNNING if specified timer is not running,
• PAL_TMR_INVALID_ID if the specifed timer id is undefined.

Referenced by led_handling().

void pal_trx_irq_init

(

FUNC_PTR

trx_irq_cb

)

Initializes the transceiver main interrupt.

This function sets the microcontroller specific registers responsible for handling the transceiver main interrupt

Parameters

trx_irq_cb

Callback function for the transceiver main interrupt

void pal_trx_irq_init_awake

(

FUNC_PTR

trx_irq_cb

)

Initializes the transceiver AWAKE interrupt.

This function sets the microcontroller specific registers responsible for handling the transceiver AWAKE interrupt

Parameters

trx_irq_cb

Callback function for the transceiver AWAKE interrupt

void pal_trx_irq_init_cca_ed

(

FUNC_PTR

trx_irq_cb

)

Initializes the transceiver CCA ED END interrupt.

This function sets the microcontroller specific registers responsible for handling the transceiver CCA ED END interrupt

Parameters

trx_irq_cb

Callback function for the transceiver CCA ED END interrupt

void pal_trx_irq_init_rx_end

(

FUNC_PTR

trx_irq_cb

)

Initializes the transceiver RX END interrupt.

This function sets the microcontroller specific registers responsible for handling the transceiver RX END interrupt

Parameters

trx_irq_cb

Callback function for the transceiver RX END interrupt

void pal_trx_irq_init_tstamp

(

FUNC_PTR

trx_irq_cb

)

Initializes the transceiver timestamp interrupt.

This function sets the microcontroller specific registers responsible for handling the transceiver timestamp interrupt

Parameters

trx_irq_cb

Callback function for the transceiver timestamp interrupt

void pal_trx_irq_init_tx_end

(

FUNC_PTR

trx_irq_cb

)

Initializes the transceiver TX END interrupt.

This function sets the microcontroller specific registers responsible for handling the transceiver TX END interrupt

Parameters

trx_irq_cb

Callback function for the transceiver TX END interrupt

void pal_trx_read_timestamp

(

uint32_t *

timestamp

)

Provides timestamp of the last received frame.

This function provides the timestamp (in microseconds) of the last received frame.

Parameters

[out]

timestamp

in microseconds