Detailed Description

This API provides abstraction from the underlying hardware/BSP.

Modules
	Morse Micro Abstraction Layer API for UART
	This provides an abstraction layer for a UART.

	WLAN HAL
	API for communicating with the WLAN transceiver.

Macros
#define	LED_OFF 0
	A value of 0 turns OFF an LED. More...

#define	LED_ON 255
	A value of 255 turns an LED ON fully. More...

#define	MMHAL_DEBUG_PIN(_pin_num) (1ul << (_pin_num))
	Macro to simplify debug pin mask/value definition. More...

#define	MMHAL_ALL_DEBUG_PINS (UINT32_MAX)
	Bit mask with all debug pins selected. More...

Typedefs
typedef void(*	mmhal_button_state_cb_t) (enum mmhal_button_id button_id, enum mmhal_button_state button_state)
	Button state callback function prototype. More...

Enumerations
enum	mmhal_isr_state { MMHAL_NOT_IN_ISR , MMHAL_IN_ISR , MMHAL_ISR_STATE_UNKNOWN }
	Enumeration of ISR states (i.e., whether in ISR or not). More...

enum	mmhal_led_id { LED_RED , LED_GREEN , LED_BLUE , LED_WHITE }
	Enumeration for different LED's on the board. More...

enum	mmhal_sleep_state { MMHAL_SLEEP_DISABLED , MMHAL_SLEEP_SHALLOW , MMHAL_SLEEP_DEEP }
	Enumeration of MCU sleep state. More...

enum	mmhal_button_id { BUTTON_ID_USER0 }
	Enumeration for buttons on the board. More...

enum	mmhal_button_state { BUTTON_RELEASED , BUTTON_PRESSED }
	Enumeration for button states. More...

enum	mmhal_veto_id { MMHAL_VETO_ID_APP_MIN = 0 , MMHAL_VETO_ID_APP_MAX = 7 , MMHAL_VETO_ID_HAL_MIN = 8 , MMHAL_VETO_ID_HAL_MAX = 15 , MMHAL_VETO_ID_MORSELIB_MIN = 16 , MMHAL_VETO_ID_MORSELIB_MAX = 19 , MMHAL_VETO_ID_DATALINK = 20 , MMHAL_VETO_ID_MMCONFIG = 21 , MMHAL_VETO_ID_RESERVED_MIN = 22 , MMHAL_VETO_ID_RESERVED_MAX = 31 }
	Enumeration of veto_id ranges for use with mmhal_set_deep_sleep_veto() and mmhal_clear_deep_sleep_veto(). More...

Functions
void	mmhal_early_init (void)
	Initialization before RTOS scheduler starts.

void	mmhal_init (void)
	Initialization after RTOS scheduler started.

enum mmhal_isr_state	mmhal_get_isr_state (void)
	Get the current ISR state (i.e., whether in ISR or not). More...

void	mmhal_log_write (const uint8_t *data, size_t len)
	Write to the debug log. More...

void	mmhal_log_flush (void)
	Flush the debug log before returning. More...

uint32_t	mmhal_random_u32 (uint32_t min, uint32_t max)
	Generate a random 32 bit integer within the given range. More...

void	mmhal_reset (void)
	Reset the microcontroller.

void	mmhal_set_led (uint8_t led, uint8_t level)
	Set the specified LED to the requested level. More...

void	mmhal_set_error_led (bool state)
	Set the error LED to the requested state. More...

bool	mmhal_set_button_callback (enum mmhal_button_id button_id, mmhal_button_state_cb_t button_state_cb)
	Registers a callback handler for button state changes. More...

mmhal_button_state_cb_t	mmhal_get_button_callback (enum mmhal_button_id button_id)
	Returns the registered callback handler for button state changes. More...

enum mmhal_button_state	mmhal_get_button (enum mmhal_button_id button_id)
	Reads the state of the specified button. More...

bool	mmhal_get_hardware_version (char *version_buffer, size_t version_buffer_length)
	Reads information that can be used to identify the hardware platform, such as hardware ID and version number, in the form of a user readable string. More...

void	mmhal_set_debug_pins (uint32_t mask, uint32_t values)
	Set the value one or more debug pins. More...

time_t	mmhal_get_time (void)
	Returns the time of day as set in the RTC. More...

void	mmhal_set_time (time_t epoch)
	Sets the RTC to the specified time in UTC. More...

enum mmhal_sleep_state	mmhal_sleep_prepare (uint32_t expected_idle_time_ms)
	Function to prepare MCU to enter sleep. More...

uint32_t	mmhal_sleep (enum mmhal_sleep_state sleep_state, uint32_t expected_idle_time_ms)
	Function to enter MCU sleep. More...

void	mmhal_sleep_abort (enum mmhal_sleep_state sleep_state)
	Function to abort the MCU sleep state. More...

void	mmhal_sleep_cleanup (void)
	Function to cleanup on exit from the MCU sleep state.

void	mmhal_set_deep_sleep_veto (uint8_t veto_id)
	Sets a deep sleep veto that will prevent the device from entering deep sleep. More...

void	mmhal_clear_deep_sleep_veto (uint8_t veto_id)
	Clears a deep sleep veto that was preventing the device from entering deep sleep (see mmhal_set_deep_sleep_veto()). More...

const struct mmhal_flash_partition_config *	mmhal_get_mmconfig_partition (void)
	Get MMCONFIG flash partition configuration. More...

int	mmhal_flash_erase (uint32_t block_address)
	Erases a block of Flash pointed to by the block_address. More...

uint32_t	mmhal_flash_getblocksize (uint32_t block_address)
	Returns the size of the Flash block at the specified address. More...

int	mmhal_flash_read (uint32_t read_address, uint8_t *buf, size_t size)
	Read a block of data from the specified Flash address into the buffer. More...

int	mmhal_flash_write (uint32_t write_address, const uint8_t *data, size_t size)
	Write a block of data to the specified Flash address. More...

const struct lfs_config *	mmhal_get_littlefs_config (void)
	Get LittleFS configuration. More...

#define	MMHAL_FLASH_ERASE_VALUE 0xFF
	() More...

#define	MMHAL_FLASH_PARTITION_CONFIG_DEFAULT { 0, 0, false }
	Initial values for mmhal_flash_partition_config. More...

Macro Definition Documentation

◆ LED_OFF

#define LED_OFF 0

A value of 0 turns OFF an LED.

Definition at line 66 of file mmhal.h.

◆ LED_ON

#define LED_ON 255

A value of 255 turns an LED ON fully.

Some boards support varying an LED's brightness. For these boards a value between 1 and 255 will result in proportionately varying levels of brightness. LED's that do not have a brightness control feature will just turn ON fully for any non zero value.

Definition at line 75 of file mmhal.h.

◆ MMHAL_ALL_DEBUG_PINS

#define MMHAL_ALL_DEBUG_PINS (UINT32_MAX)

Bit mask with all debug pins selected.

Definition at line 217 of file mmhal.h.

◆ MMHAL_DEBUG_PIN

#define MMHAL_DEBUG_PIN ( _pin_num ) (1ul << (_pin_num))

Macro to simplify debug pin mask/value definition.

Parameters

_pin_num The pin number to set in the mask. Must be 0-31 (inclusive).

Example:

mmhal_set_debug_pins(MMHAL_DEBUG_PIN(0), MMHAL_DEBUG_PIN(0));

Definition at line 214 of file mmhal.h.

◆ MMHAL_FLASH_ERASE_VALUE

#define MMHAL_FLASH_ERASE_VALUE 0xFF

()

This API provides abstraction from the underlying flash hardware/. This is the value erased flash bytes are set to. This shall be 0xFF as this is the value that hardware flash erases to.

Definition at line 31 of file mmhal_flash.h.

◆ MMHAL_FLASH_PARTITION_CONFIG_DEFAULT

#define MMHAL_FLASH_PARTITION_CONFIG_DEFAULT { 0, 0, false }

Initial values for mmhal_flash_partition_config.

Definition at line 64 of file mmhal_flash.h.

Typedef Documentation

◆ mmhal_button_state_cb_t

typedef void(* mmhal_button_state_cb_t) (enum mmhal_button_id button_id, enum mmhal_button_state button_state)

Button state callback function prototype.

Definition at line 157 of file mmhal.h.

Enumeration Type Documentation

◆ mmhal_button_id

enum mmhal_button_id

Enumeration for buttons on the board.

Note: The support for each button is platform dependent.

Definition at line 142 of file mmhal.h.

◆ mmhal_button_state

enum mmhal_button_state

Enumeration for button states.

Definition at line 150 of file mmhal.h.

◆ mmhal_isr_state

enum mmhal_isr_state

Enumeration of ISR states (i.e., whether in ISR or not).

Enumerator
MMHAL_NOT_IN_ISR	The function was not executed from ISR context.
MMHAL_IN_ISR	The function was executed from ISR context.
MMHAL_ISR_STATE_UNKNOWN	The HAL does not support checking ISR state.

Definition at line 36 of file mmhal.h.

◆ mmhal_led_id

enum mmhal_led_id

Enumeration for different LED's on the board.

Note: Some of these LED's may not be available on all boards and some of these values may refer to the same LED.

Definition at line 49 of file mmhal.h.

◆ mmhal_sleep_state

enum mmhal_sleep_state

Enumeration of MCU sleep state.

Enumerator
MMHAL_SLEEP_DISABLED	Disable MCU sleep.
MMHAL_SLEEP_SHALLOW	MCU to enter shallow sleep.
MMHAL_SLEEP_DEEP	MCU can enter deep sleep.

Definition at line 58 of file mmhal.h.

◆ mmhal_veto_id

enum mmhal_veto_id

Enumeration of veto_id ranges for use with mmhal_set_deep_sleep_veto() and mmhal_clear_deep_sleep_veto().

Enumerator
MMHAL_VETO_ID_APP_MIN	Start of deep sleep veto ID range that is available for application use.
MMHAL_VETO_ID_APP_MAX	End of deep sleep veto ID range that is available for application use.
MMHAL_VETO_ID_HAL_MIN	Start of deep sleep veto ID range that is available for HAL use.
MMHAL_VETO_ID_HAL_MAX	End of deep sleep veto ID range that is available for HAL use.
MMHAL_VETO_ID_MORSELIB_MIN	Start of deep sleep veto ID range that is allocated for morselib use. Note that this must not be changed as it is built into morselib.
MMHAL_VETO_ID_MORSELIB_MAX	End of deep sleep veto ID range that is allocated for morselib use. Note that this must not be changed as it is built into morselib.
MMHAL_VETO_ID_DATALINK	Deep sleep veto ID for data-link subsystem.
MMHAL_VETO_ID_MMCONFIG	Deep sleep veto ID allocated to Morse Micro Persistent Configuration Store.
MMHAL_VETO_ID_RESERVED_MIN	Start of deep sleep veto ID range reserved for future use.
MMHAL_VETO_ID_RESERVED_MAX	End of deep sleep veto ID range reserved for future use.

Definition at line 297 of file mmhal.h.

Function Documentation

◆ mmhal_clear_deep_sleep_veto()

void mmhal_clear_deep_sleep_veto ( uint8_t veto_id )

Clears a deep sleep veto that was preventing the device from entering deep sleep (see mmhal_set_deep_sleep_veto()).

If the given veto was not already set then this has no effect.

Parameters

veto_id The veto identifier. Valid values are 0-31, and these are split up into ranges for use by different subsystems – see mmhal_veto_id.

◆ mmhal_flash_erase()

int mmhal_flash_erase ( uint32_t block_address )

Erases a block of Flash pointed to by the block_address.

The block address may be anywhere within the block to erase. The entire block gets erased. Once erased all bytes in the block shall be MMHAL_FLASH_ERASE_VALUE (0xFF).

Parameters

block_address The address of the block of Flash to erase.

Returns: 0 on success, negative number on failure

◆ mmhal_flash_getblocksize()

uint32_t mmhal_flash_getblocksize ( uint32_t block_address )

Returns the size of the Flash block at the specified address.

Parameters

block_address The address of the Flash block.

Returns: The size of the Flash block in bytes. Returns 0 if an invalid address is specified.

◆ mmhal_flash_read()

int mmhal_flash_read	(	uint32_t	read_address,
		uint8_t *	buf,
		size_t	size
	)

Read a block of data from the specified Flash address into the buffer.

Parameters

read_address	The address in Flash to read from.
buf	The buffer to read into.
size	The number of bytes to read.

Returns: 0 on success, or a negative number on failure.

◆ mmhal_flash_write()

int mmhal_flash_write	(	uint32_t	write_address,
		const uint8_t *	data,
		size_t	size
	)

Write a block of data to the specified Flash address.

There is no alignment or minimum size requirement. This function will take care of aligning the data and merging with existing Flash contents. The Flash block is not erased, it is up to the application to determine if the block needs to be erased before programming.

Parameters

write_address	The address in Flash to write to.
data	A pointer to the block of data to write.
size	The number of bytes to write.

Returns: 0 on success, or a negative number on failure.

◆ mmhal_get_button()

enum mmhal_button_state mmhal_get_button ( enum mmhal_button_id button_id )

Reads the state of the specified button.

Parameters

button_id The button state to read

Returns: The current button state, or BUTTON_RELEASED if not supported

◆ mmhal_get_button_callback()

mmhal_button_state_cb_t mmhal_get_button_callback ( enum mmhal_button_id button_id )

Returns the registered callback handler for button state changes.

Parameters

button_id The button whose callback should be returned

Returns: The registered callback or NULL if no callback registered

◆ mmhal_get_hardware_version()

bool mmhal_get_hardware_version	(	char *	version_buffer,
		size_t	version_buffer_length
	)

Reads information that can be used to identify the hardware platform, such as hardware ID and version number, in the form of a user readable string.

This function attempts to detect the correct hardware and version. The actual means of detecting the correct hardware and version will vary from implementation to implementation and may use means such as identification information stored in EEPROM or devices detected on GPIO, SPI or I2C interfaces. Returns false if the hardware could not be identified correctly.

Parameters

version_buffer	The pre-allocated buffer to return the hardware ID and version in.
version_buffer_length	The length of the pre-allocated buffer.

Returns: True if the hardware was correctly identified and returned.

◆ mmhal_get_isr_state()

enum mmhal_isr_state mmhal_get_isr_state ( void )

Get the current ISR state (i.e., whether in ISR or not).

Returns: the current ISR state, or MMHAL_ISR_STATE_UNKNOWN if the HAL does not support checking ISR state.

◆ mmhal_get_littlefs_config()

const struct lfs_config * mmhal_get_littlefs_config ( void )

Get LittleFS configuration.

LittleFS initialization is done by littlefs_init() in mmosal_shim_fileio.c. which in turn calls this function to fetch the hardware configuration for LittleFS from the HAL layer. The LittleFS configuration will vary from platform to platform. If LittleFS is not supported by the platform then we just return NULL. This function returns a static pointer to struct lfs_config which is defined in lfs.h.

See mmhal_littlefs.c for the full HAL layer implementation for your platform. See mmosal_shim_fileio.c for the libc shims for LittleFS. See README.md in the src/littlefs folder for detailed information on LittleFS.

Returns: A static pointer to the LittleFS config structure, or NULL if not supported.

◆ mmhal_get_mmconfig_partition()

const struct mmhal_flash_partition_config * mmhal_get_mmconfig_partition ( void )

Get MMCONFIG flash partition configuration.

MMCONFIG initialization is done by mmconfig_init() in mmconfig.c. which in turn calls this function to fetch the partition configuration for config store from the HAL layer. If config store is not supported by the platform then we just return NULL. This function returns a static pointer to struct mmhal_flash_partition_config.

Returns: A static pointer to the partition config for MMCONFIG, or NULL if not supported.

◆ mmhal_get_time()

time_t mmhal_get_time ( void )

Returns the time of day as set in the RTC.

Time is in UTC.

Returns: Epoch time (seconds since 1 Jan 1970) or 0 on failure.

◆ mmhal_log_flush()

void mmhal_log_flush ( void )

Flush the debug log before returning.

Warning: Implementations of this function must support being invoked with interrupts disabled.

◆ mmhal_log_write()

void mmhal_log_write	(	const uint8_t *	data,
		size_t	len
	)

Write to the debug log.

It is assumed the caller will have mechanisms in place to prevent concurrent access.

Parameters

data	Buffer containing data to write.
len	Length of data in buffer.

◆ mmhal_random_u32()

uint32_t mmhal_random_u32	(	uint32_t	min,
		uint32_t	max
	)

Generate a random 32 bit integer within the given range.

Parameters

min	Minimum value (inclusive).
max	Maximum value (inclusive).

Returns: a randomly generated integer (min <= i <= max).

◆ mmhal_set_button_callback()

bool mmhal_set_button_callback	(	enum mmhal_button_id	button_id,
		mmhal_button_state_cb_t	button_state_cb
	)

Registers a callback handler for button state changes.

Note: The callback will be executed in an Interrupt Service Routine context

Parameters

button_id	The button whose state should be reported to the callback
button_state_cb	The function to call on button state change, or NULL to disable.

Returns: True if the callback is registered successfully, False if not supported

◆ mmhal_set_debug_pins()

void mmhal_set_debug_pins	(	uint32_t	mask,
		uint32_t	values
	)

Set the value one or more debug pins.

Each platform can define up to 32 GPIOs for application use. If a GPIO is not supported by a platform then attempts to set it will be silently ignored. These GPIOs are intended for debug/test purposes.

Parameters

mask	Mask of GPIOs to modify. Each bit in this mask that is set will result in the corresponding GPIO being being set to the corresponding value given in `values`.
values	Bit field, where each bit corresponds to a GPIO, specifying the direction to drive each GPIO with 1 meaning drive high and 0 meaning drive low. Only GPIOs with the corresponding bit set in `mask` will be modified.

See also: MM_DEBUG_PIN_MASK

◆ mmhal_set_deep_sleep_veto()

void mmhal_set_deep_sleep_veto ( uint8_t veto_id )

Sets a deep sleep veto that will prevent the device from entering deep sleep.

The device will not enter deep sleep until there are no vetoes remaining. This veto can be cleared by a call to mmhal_clear_deep_sleep_veto() with the same veto_id.

Up to 32 vetoes are supported (ID numbers 0-31). Each veto should be used exclusively by a given aspect of the system (e.g., to prevent deep sleep when a DMA transfer is in progress, or to prevent deep sleep when there is log data buffered for transmit, etc.).

Parameters

veto_id The veto identifier. Valid values are 0-31, and these are split up into ranges for use by different subsystems – see mmhal_veto_id.

◆ mmhal_set_error_led()

void mmhal_set_error_led ( bool state )

Set the error LED to the requested state.

Note: This function is called by the bootloader and so needs to do all the initialization required to set the LED's as the bootloader does not use the regular BSP initialization located in main.c for configuring GPIO's and setting clock gates as required.

Parameters

state Set to true if the LED needs to be turned on, or false if the led needs to be turned off.

◆ mmhal_set_led()

void mmhal_set_led	(	uint8_t	led,
		uint8_t	level
	)

Set the specified LED to the requested level.

Do nothing if the requested LED does not exist.

Parameters

led	The LED to set, if the platform supports it. See mmhal_led_id
level	The level to set it to. 0 means OFF and non-zero means ON. If the platform supports brightness levels then 255 is full. Defines LED_ON and LED_OFF are provided for ease of use.

◆ mmhal_set_time()

void mmhal_set_time ( time_t epoch )

Sets the RTC to the specified time in UTC.

Note: While Unix epoch time supports years from 1970, most Real Time Clock chips support years from 2000 only as they store the year as years from 2000. So do not attempt to set any years below 2000 as this could cause the year to wrap around to an unreasonably high value. Definitely do not do:
mmhal_set_time(0);

mmhal_set_time
void mmhal_set_time(time_t epoch)
Sets the RTC to the specified time in UTC.

Parameters

epoch Time in Unix epoch time (seconds since 1 Jan 1970).

◆ mmhal_sleep()

uint32_t mmhal_sleep	(	enum mmhal_sleep_state	sleep_state,
		uint32_t	expected_idle_time_ms
	)

Function to enter MCU sleep.

Parameters

sleep_state	Sleep state to enter into.
expected_idle_time_ms	Expected time to sleep in milliseconds.

Returns: Elapsed sleep time in milliseconds.

◆ mmhal_sleep_abort()

void mmhal_sleep_abort ( enum mmhal_sleep_state sleep_state )

Function to abort the MCU sleep state.

Note: This must only be invoked after mmhal_sleep_prepare() and before mmhal_sleep().

Parameters

sleep_state Sleep state to abort.

◆ mmhal_sleep_prepare()

enum mmhal_sleep_state mmhal_sleep_prepare ( uint32_t expected_idle_time_ms )

Function to prepare MCU to enter sleep.

This will halt the timer that generates the RTOS tick.

Parameters

expected_idle_time_ms Expected time to sleep in milliseconds.

Returns: the type of sleep permitted by the current system state.

Detailed Description

Modules

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ LED_OFF

◆ LED_ON

◆ MMHAL_ALL_DEBUG_PINS

◆ MMHAL_DEBUG_PIN

◆ MMHAL_FLASH_ERASE_VALUE

◆ MMHAL_FLASH_PARTITION_CONFIG_DEFAULT

Typedef Documentation

◆ mmhal_button_state_cb_t

Enumeration Type Documentation

◆ mmhal_button_id

◆ mmhal_button_state

◆ mmhal_isr_state

◆ mmhal_led_id

◆ mmhal_sleep_state

◆ mmhal_veto_id

Function Documentation

◆ mmhal_clear_deep_sleep_veto()

◆ mmhal_flash_erase()

◆ mmhal_flash_getblocksize()

◆ mmhal_flash_read()

◆ mmhal_flash_write()

◆ mmhal_get_button()

◆ mmhal_get_button_callback()

◆ mmhal_get_hardware_version()

◆ mmhal_get_isr_state()

◆ mmhal_get_littlefs_config()

◆ mmhal_get_mmconfig_partition()

◆ mmhal_get_time()

◆ mmhal_log_flush()

◆ mmhal_log_write()

◆ mmhal_random_u32()

◆ mmhal_set_button_callback()

◆ mmhal_set_debug_pins()

◆ mmhal_set_deep_sleep_veto()

◆ mmhal_set_error_led()

◆ mmhal_set_led()

◆ mmhal_set_time()

◆ mmhal_sleep()

◆ mmhal_sleep_abort()

◆ mmhal_sleep_prepare()