OS abstraction layer for Libmultimac. More...

#include <stdint.h>

Data Structures
struct	osal_radio_params_t

struct	osal_radio_status_t

struct	osal_job_t

Macros
#define	ms2us(ms) ((osal_time_t) (((osal_time_t) (ms))*((osal_time_t) 1000)))

#define	us2ms(us) ((osal_time_t) (((osal_time_t) (us))/((osal_time_t) 1000)))

#define	us2ms_round(us) ((osal_time_t) (((osal_time_t) (us) + ((osal_time_t) 500))/((osal_time_t) 1000)))

#define	OSAL_TIME_MAX ((osal_time_t) 0x7FFFFFFFFFFFFFFFLL)

Typedefs
typedef int64_t	osal_time_t

Enumerations
enum	osal_cr_t { OSAL_CR4_5 = 0, OSAL_CR4_6 = 1, OSAL_CR4_7 = 2, OSAL_CR4_8 = 3 }

enum	osal_sf_t { OSAL_SF6 = 0, OSAL_SF7 = 1, OSAL_SF8 = 2, OSAL_SF9 = 3, OSAL_SF10 = 4, OSAL_SF11 = 5, OSAL_SF12 = 6 }

enum	osal_bw_t { OSAL_BW62_5 = 0, OSAL_BW125 = 1, OSAL_BW250 = 2, OSAL_BW500 = 3 }

enum	osal_crc_t { OSAL_CRC_OFF = 0, OSAL_CRC_ON = 1 }

enum	osal_iq_t { OSAL_IQ_NORMAL = 0, OSAL_IQ_INVERTED = 1 }

enum	osal_crc_ok_t { OSAL_CRC_NOK = 0, OSAL_CRC_OK = 1 }

enum	osal_radio_state_t { OSAL_RADIO_STOP = 0, OSAL_RADIO_START_TX = 1, OSAL_RADIO_START_RX_SINGLE = 2, OSAL_RADIO_START_RX = 3 }

Functions
osal_time_t	osal_get_time (void)
	Returns the elapsed time since the device has been powered-up. More...

osal_time_t	osal_get_radio_wakeup_latency (void)
	Returns the maximum time the radio can take before being actually receiving (usually sleep to RX transition). More...

osal_time_t	osal_get_additional_cpu_wakeup_latency (void)
	Returns an offset that will be removed to the deadlines of timing critical tasks in case the OS scheduler is not able to start the tasks on-time (for instance, in case of wakeup latency from a low power state). More...

void	osal_post_job (osal_job_t job, void(cb)(osal_job_t *))
	Queue a job for immediate execution (but after any other job already in the queue). More...

void	osal_post_delayed_job (osal_job_t job, osal_time_t time, void(cb)(osal_job_t *))
	Queue a job for scheduled execution. More...

void	osal_cancel_job (osal_job_t *job)
	Cancel a queued job. More...

void	osal_lowpower_sleep_lock (void)
	Prevents the device from going to lowpower and/or sleep mode (if the device supports a lowpower and/or a sleep mode inducing a latency). More...

void	osal_lowpower_sleep_unlock (void)
	Allows the device to go to lowpower and/or sleep mode (if the device supports a lowpower and/or a sleep mode inducing a latency). More...

void	osal_memcpy (void dst, const void src, uint16_t size)
	Copies a memory area. More...

void	osal_memcpy_reverse (void dst, const void src, uint16_t size)
	Copies a memory area in reverse order (last byte of the source area copied to the first byte of the destination area). More...

void	osal_memset (void *dst, uint8_t byte, uint16_t size)
	Fills a memory area with a constant value. More...

uint8_t	osal_rand8 (void)
	Returns a random byte. More...

uint16_t	osal_rand16 (void)
	Returns a random half-word. More...

void	osal_aes_setkey (const uint8_t *key)
	Sets the AES key to use for encryption and decryption. More...

void	osal_aes_encrypt (const uint8_t in, uint8_t out, uint32_t len)
	Encrypts a buffer using the AES algorithm (ECB mode). More...

void	osal_aes_decrypt (const uint8_t in, uint8_t out, uint32_t len)
	Decrypts a buffer using the AES algorithm (ECB mode). More...

void	osal_set_radio_params (osal_radio_params_t *params)
	Sets the radio parameters. More...

void	osal_set_radio_callback (void(*cb)(void))
	Sets a radio callback that will be called once the radio has received or transmitted a buffer. More...

void	osal_clear_radio_callback (void)
	Clears the radio callback. More...

int8_t	osal_get_max_power (void)
	Returns the maximum available power. More...

int8_t	osal_get_min_power (void)
	Returns the minimum available power. More...

int8_t	osal_get_antenna_gain (void)
	Returns the antenna gain in dBi. More...

int8_t	osal_radio_SF_supported (enum osal_sf_t sf)
	Checks if a given SF is supported. More...

int8_t	osal_is_freq_calibration_enabled (void)
	Tells if frequency calibration should be used. More...

void	osal_get_radio_status (osal_radio_status_t *status)
	Retrieves the radio status related to the last reception or transmission. More...

uint8_t *	osal_get_radio_buffer (void)
	Retrieves the pointer to the radio buffer. More...

uint8_t	osal_get_radio_buffer_length (void)
	Retrieves the length of the data inside the radio buffer. More...

void	osal_write_radio_buffer (uint8_t *src, uint8_t length)
	Fills the radio buffer with data to transmit. More...

int16_t	osal_read_radio_rssi (void)
	Returns the RSSI currently perceived by the radio. More...

void	osal_radio (enum osal_radio_state_t state)
	Sets the new state of the radio. More...

void	osal_printf (const char *fmt,...)
	Formats and prints data. More...

uint16_t	osal_read16_le (const uint8_t *buf)
	Reads data as little-endian half-word. More...

uint32_t	osal_read32_le (const uint8_t *buf)
	Reads data as little-endian word. More...

uint32_t	osal_read32_be (const uint8_t *buf)
	Reads data as big-endian word. More...

void	osal_write16_le (uint8_t *buf, uint16_t v)
	Writes data as little-endian half-word. More...

void	osal_write32_le (uint8_t *buf, uint32_t v)
	Writes data as little-endian word. More...

void	osal_write32_be (uint8_t *buf, uint32_t v)
	Writes data as big-endian word. More...

Detailed Description

OS abstraction layer for Libmultimac.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Archos nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND AND EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ARCHOS S.A. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Enumeration Type Documentation

enum osal_radio_state_t

Enumerator
OSAL_RADIO_STOP	Stop the radio.
OSAL_RADIO_START_TX	Start the transmission.
OSAL_RADIO_START_RX_SINGLE	Start the reception of one packet.
OSAL_RADIO_START_RX	Start the reception.

Function Documentation

void osal_aes_decrypt	(	const uint8_t *	in,
		uint8_t *	out,
		uint32_t	len
	)

Decrypts a buffer using the AES algorithm (ECB mode).

Note

The last key set with osal_aes_setkey() must be used.
The size of the in and out buffers will always be a multiple of 16 bytes.

Parameters

in	buffer to encrypt.
out	pointer to the memory area where the decrypted buffer will be stored.
len	length of the in and out buffers.

Return values

None

void osal_aes_encrypt	(	const uint8_t *	in,
		uint8_t *	out,
		uint32_t	len
	)

Encrypts a buffer using the AES algorithm (ECB mode).

Note

The last key set with osal_aes_setkey() must be used.
The size of the in and out buffers will always be a multiple of 16 bytes.

Parameters

in	buffer to encrypt.
out	pointer to the memory area where the encrypted buffer will be stored.
len	length of the in and out buffers.

Return values

None

void osal_aes_setkey ( const uint8_t * key )

Sets the AES key to use for encryption and decryption.

Note

This key stays valid for any call to osal_aes_encrypt() or osal_aes_decrypt() until a new key is set.
The key will always be 16 bytes long.

Parameters

key	AES key to set.

Return values

None

void osal_cancel_job ( osal_job_t * job )

Cancel a queued job.

Note

All jobs are statically allocated, so their pointers can be used to identify them.
The osal_job_t object has a data field of 32 bytes that can be used to store any relevant information.

Parameters

job	pointer to the job to cancel.

Return values

None

void osal_clear_radio_callback ( void )

Clears the radio callback.

Note: This function must ensure that no further call to the radio callback will be made, including any call that could have been already scheduled.

Return values

None

osal_time_t osal_get_additional_cpu_wakeup_latency ( void )

Returns an offset that will be removed to the deadlines of timing critical tasks in case the OS scheduler is not able to start the tasks on-time (for instance, in case of wakeup latency from a low power state).

Note: Ideally, the OS scheduler should handle any CPU latency, meaning this should be set to zero.

Return values

osal_time_t latency in us.

int8_t osal_get_antenna_gain ( void )

Returns the antenna gain in dBi.

Note: Antenna gain rounded down.

Return values

int8_t antenna gain in dBi.

int8_t osal_get_max_power ( void )

Returns the maximum available power.

Note: Without additional PA, the SX1276 maximum power is 20 dBm using the PA_BOOST pin, and 14 dBm using the RFO pin.

Return values

int8_t maximum available power.

int8_t osal_get_min_power ( void )

Returns the minimum available power.

Note: Without additional PA, the SX1276 minimum power is 2 dBm using the PA_BOOST pin, and 0 dBm using the RFO pin.

Return values

int8_t minimum available power.

uint8_t* osal_get_radio_buffer ( void )

Retrieves the pointer to the radio buffer.

Note: Data can be read from or written to it.

Return values

uint8_t* : pointer to the radio buffer.

uint8_t osal_get_radio_buffer_length ( void )

Retrieves the length of the data inside the radio buffer.

Note: This is the length of the received or transmitted data.

Return values

uint8_t length of the data.

void osal_get_radio_status ( osal_radio_status_t * status )

Retrieves the radio status related to the last reception or transmission.

Note: The osal_radio_status_t structure is explained in osal.h.

Parameters

status pointer to the osal_radio_status_t structure that will hold the result.

Return values

None

osal_time_t osal_get_radio_wakeup_latency ( void )

Returns the maximum time the radio can take before being actually receiving (usually sleep to RX transition).

Note: This is around 3000 us for the SX1276.

Return values

osal_time_t latency in us.

osal_time_t osal_get_time ( void )

Returns the elapsed time since the device has been powered-up.

Return values

osal_time_t current time in us.

int8_t osal_is_freq_calibration_enabled ( void )

Tells if frequency calibration should be used.

Note: This will detect and correct any frequency offset introduced by the XTAL used for RF. It should not be needed if the board has a TCXO.

Return values

int8_t 1 if enabled, 0 if not.

void osal_lowpower_sleep_lock ( void )

Prevents the device from going to lowpower and/or sleep mode (if the device supports a lowpower and/or a sleep mode inducing a latency).

Note: Once called, the device must work as fast as possible until the osal_lowpower_sleep_unlock() counterpart function is called.

Return values

None

void osal_lowpower_sleep_unlock ( void )

Allows the device to go to lowpower and/or sleep mode (if the device supports a lowpower and/or a sleep mode inducing a latency).

Note: Once called, the device has no more constraint related to speed or latency.

Return values

None

void osal_memcpy	(	void *	dst,
		const void *	src,
		uint16_t	size
	)

Copies a memory area.

Parameters

dst	destination pointer.
src	source pointer.
size	size of the memory area to copy.

Return values

None

void osal_memcpy_reverse	(	void *	dst,
		const void *	src,
		uint16_t	size
	)

Copies a memory area in reverse order (last byte of the source area copied to the first byte of the destination area).

Parameters

dst	destination pointer.
src	source pointer.
size	size of the memory area to copy.

Return values

None

void osal_memset	(	void *	dst,
		uint8_t	byte,
		uint16_t	size
	)

Fills a memory area with a constant value.

Parameters

dst	destination pointer.
byte	value used to fill the area.
size	size of the memory area to fill.

Return values

None

void osal_post_delayed_job	(	osal_job_t *	job,
		osal_time_t	time,
		void()(osal_job_t )	cb
	)

Queue a job for scheduled execution.

Note

The immediate queue has priority over the scheduled queue.
All jobs are statically allocated, so their pointers can be used to identify them.
If the job is already queued, its deadline must be updated to the new value.
The osal_job_t object has a data field of 32 bytes that can be used to store any relevant information.

Parameters

job	pointer to the job to queue.
time	timestamp at which the job must be executed.
cb	pointer to the function to call once the job must be executed.

Return values

None

void osal_post_job	(	osal_job_t *	job,
		void()(osal_job_t )	cb
	)

Queue a job for immediate execution (but after any other job already in the queue).

Note

The immediate queue has priority over the scheduled queue.
All jobs are statically allocated, so their pointers can be used to identify them.
If the job is already queued, this job must be moved to the end of the queue.
The osal_job_t object has a data field of 32 bytes that can be used to store any relevant information.

Parameters

job	pointer to the job to queue.
cb	pointer to the function to call once the job must be executed.

Return values

None

void osal_printf	(	const char *	fmt,
			...
	)

Formats and prints data.

Note: This optional function is expected to behave like printf().

Parameters

fmt	formatted string.
...	list of arguments.

Return values

None

void osal_radio ( enum osal_radio_state_t state )

Sets the new state of the radio.

Note: This function changes the hardware state of the radio (TX/RX/IDLE).

Parameters

state state to set.

Return values

None

int8_t osal_radio_SF_supported ( enum osal_sf_t sf )

Checks if a given SF is supported.

Note: SF12 at lower bandwidth requires good frequency stability, so usually a TCXO is needed.

Return values

int8_t 1 if supported, 0 if not.

uint16_t osal_rand16 ( void )

Returns a random half-word.

Return values

uint16_t random half-word.

uint8_t osal_rand8 ( void )

Returns a random byte.

Return values

uint8_t random byte.

uint16_t osal_read16_le ( const uint8_t * buf )

Reads data as little-endian half-word.

Parameters

buf	pointer to the data to read.

Return values

uint16_t read half-word

uint32_t osal_read32_be ( const uint8_t * buf )

Reads data as big-endian word.

Parameters

buf	pointer to the data to read.

Return values

uint32_t read word

uint32_t osal_read32_le ( const uint8_t * buf )

Reads data as little-endian word.

Parameters

buf	pointer to the data to read.

Return values

uint32_t read word

int16_t osal_read_radio_rssi ( void )

Returns the RSSI currently perceived by the radio.

Note: This function will be called only if the radio is in RX mode.

Return values

int16_t perceived RSSI.

void osal_set_radio_callback ( void(*)(void) cb )

Sets a radio callback that will be called once the radio has received or transmitted a buffer.

Parameters

cd	pointer to the callback.

Return values

None

void osal_set_radio_params ( osal_radio_params_t * params )

Sets the radio parameters.

Note

The osal_radio_params_t structure is explained in osal.h.
These parameters must stay valid until new ones are set.

Parameters

params parameters to set.

Return values

None

void osal_write16_le	(	uint8_t *	buf,
		uint16_t	v
	)

Writes data as little-endian half-word.

Parameters

buf	pointer to the memory area where the data will be written.
v	half-word to write.

Return values

none

void osal_write32_be	(	uint8_t *	buf,
		uint32_t	v
	)

Writes data as big-endian word.

Parameters

buf	pointer to the memory area where the data will be written.
v	word to write.

Return values

none

void osal_write32_le	(	uint8_t *	buf,
		uint32_t	v
	)

Writes data as little-endian word.

Parameters

buf	pointer to the memory area where the data will be written.
v	word to write.

Return values

none

void osal_write_radio_buffer	(	uint8_t *	src,
		uint8_t	length
	)

Fills the radio buffer with data to transmit.

Note: This function does not send anything, but must copies the data to the radio buffer and sets its length.

Parameters

src	pointer to the data to send.
length	length of the data to send.

Return values

None

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation