Functions
void	HardwareSetup ()
	Initializes the system hardware such as the timer, cache and clock speed.

void	PostConfigHardwareInit ()
	Initializes the system hardware that depend on config variables such as the watchdog.

void	ForceReboot (bool bFromException=false)
	Forces the system hardware to perform a soft reset.

int	HalStorage_Save (uint8_t area, void *pData, int len, int offset=0)
	Save a blob to a specific persistent storage area as defined by the platform. This routine will perform all storage maintenance routines necessary to ensure a valid write.

int	HalStorage_SavePartial (uint8_t area, void *pData, int len, int offset)
	Save a blob to a specific persistent storage area as defined by the platform. This routine requires that any maintenance required for a valid write be explicitly performed prior to being called.

int	HalStorage_Prepare (uint8_t area, int len, int offset=0)
	Prepare a storage area for writing new data. For platforms with direct flash mapping this function is an alias for HalStorage_Erase.

int	HalStorage_Finalize (uint8_t area)
	Finalize a storage area after writing new data. This will perform any final completion or cleanup routines required to persist the previously saved data from HalStorage_SavePartial calls.

int	HalStorage_Erase (uint8_t area, int len=-1, int offset=0)
	Erase all or part of a storage area. Note: due to physical storage granularities, the total area erased may extend beyond the requested area.

int	HalStorage_GetAllocated (uint8_t area)
	Obtain the total size allocated to the given persistent storage area.

int	HalStorage_GetMaxAllocation (uint8_t area)
	Obtain the maximum size that may be allocated to the given persistent storage area. For direct flash mapped platforms, this is aliased to HalStorage_GetAllocated.

int	HalStorage_RemainingSpace (uint8_t area)
	Obtain the number of remaining bytes available to be written in the given persistent storage area.

int	HalStorage_WriteOffset (uint8_t area)
	Get the offset of the next byte that can be written in the given persistent storage area.

int	HalStorage_AddressOffset (uint8_t area, void *pWhere)
	Get the offset within a persistent storage area of an address. A platform may map any address to any offset of its choosing for a given storage area, and my modify its behavior on an area by area basis.

void	FlashErase (void *pWhere, int len)
	Erases the flash memory.

void	FlashProgram (void pWhere, void pWhat, int len)
	Program flash memory.

void	FlashProgramAppImage (void pWhere, void pWhat, int len)
	Write an application image to flash memory.

void	DisableCache ()
	Disable the instruction and data cache.

void	EnableCache ()
	Enable the instruction and data cache.

uint32_t	spaceleft ()
	Report how much free unallocated space is left in dynamic memory.

uint16_t	HalGetTickFraction (void)
	Returns the fraction of the current system time tick.

void	StdioCheckIntc (void)
	Check STDIO interrupt sources.

void	SysLogCheckIntc (void)
	This is just like the StdioCheckIntc() function, except that the results are displayed via UDP.

bool	HalDeviceCertValid ()
	Determine if the stored certificate is valid.

uint8_t *	HalGetDeviceCert ()
	Get a pointer to the stored certificate.

uint16_t	HalGetDeviceCertLen ()
	Get the length of the stored certificate.

uint8_t *	HalGetDeviceKey ()
	Get a pointer to the stored certificate.

uint16_t	HalGetDeviceKeyLen ()
	Get the length of the stored key.

bool	HalSaveNewDeviceCert (const uint8_t *cert, uint16_t certlen, uint8_t format=SSL_FILETYPE_PEM)
	Save a device certificate in persistent storage.

bool	HalSaveNewDeviceKey (const uint8_t *key, uint16_t keylen, uint8_t format=SSL_FILETYPE_PEM)
	Save a device key in persistent storage.

void	HalEraseDeviceCertAndKey ()
	Clear the device certificate and key from persistent storage.

Variables
void(*	watchdog_service_function )(void)
	Watchdog callback service function.

uint32_t	HalTickMaxCount
	Rollover value for the system hardware tick timer.

Detailed Description

#include< hal.h >

The HAL provides a common function name interface to the various NetBurner hardware platforms. Other than the ForceReboot() and spaceleft() functions, these are advanced functions that should only be used by developers experienced with NetBurner hardware, firmware and memory maps.

Function Documentation

◆ FlashErase()

void FlashErase	(	void *	pWhere,
		int	len )

#include <hal.h>

Erases the flash memory.

Parameters

pWhere	The starting location in flash memory to begin the erasure
len	Specified the number of bytes to erase

◆ FlashProgram()

void FlashProgram	(	void *	pWhere,
		void *	pWhat,
		int	len )

#include <hal.h>

Program flash memory.

Parameters

pWhere	Pointer to the starting location in flash to begin programming
pWhat	Pointer to the content that will be programmed into flash
len	Number of bytes to program

◆ FlashProgramAppImage()

void FlashProgramAppImage	(	void *	pWhere,
		void *	pWhat,
		int	len )

#include <hal.h>

Write an application image to flash memory.

On some platforms writing the application image may require calling ProgramImage even though it may only call FlashErase and FlashProgram. As a result, ProgramImage should always be used when updating the application image.

Parameters

pWhere	Pointer to the starting location in flash to begin the programming
pWhat	Pointer to the content that will be programmed into flash
len	Number of bytes to write

◆ HalDeviceCertValid()

bool HalDeviceCertValid ( )

#include <hal.h>

Determine if the stored certificate is valid.

This is the only function recommended to be used to determine the validity of the stored certificate. Is is not recommended to use HalGetDeviceCert() nor HalGetDeviceCertLen() to determine validity. For safest use of the cert/key getter functions, use HalDeviceCertValid() prior.

Return values

true	if the certificate is valid false otherwise

◆ HalEraseDeviceCertAndKey()

void HalEraseDeviceCertAndKey ( )

#include <hal.h>

Clear the device certificate and key from persistent storage.

HalEraseDeviceCertAndKey() is recommended instead of HalStorage_Erase() to clear the stored certificate and key.

◆ HalGetDeviceCert()

uint8_t * HalGetDeviceCert ( )

#include <hal.h>

Get a pointer to the stored certificate.

It is recommended to use HalDeviceCertValid() prior to calling this function.

Return values

pointer to the certificate storage location in memory.

◆ HalGetDeviceCertLen()

uint16_t HalGetDeviceCertLen ( )

#include <hal.h>

Get the length of the stored certificate.

It is recommended to use HalDeviceCertValid() prior to calling this function.

Return values

length of the stored certificate. 0 or 65535 if no certificates is stored.

◆ HalGetDeviceKey()

uint8_t * HalGetDeviceKey ( )

#include <hal.h>

Get a pointer to the stored certificate.

It is recommended to use HalDeviceCertValid() prior to calling this function.

Return values

pointer to the certificate storage location in memory.

◆ HalGetDeviceKeyLen()

uint16_t HalGetDeviceKeyLen ( )

#include <hal.h>

Get the length of the stored key.

It is recommended to use HalDeviceCertValid() prior to calling this function.

Return values

length of the stored key. 0 or 65535 if no key is stored.

◆ HalGetTickFraction()

uint16_t HalGetTickFraction ( void )

extern

#include <hal.h>

Returns the fraction of the current system time tick.

return - The current counter value used to generate tick count

◆ HalSaveNewDeviceCert()

bool HalSaveNewDeviceCert	(	const uint8_t *	cert,
		uint16_t	certlen,
		uint8_t	format = SSL_FILETYPE_PEM )

#include <hal.h>

Save a device certificate in persistent storage.

Parameters

cert	Pointer to the buffer containing the certificate
certlen	length of the certificate
format	filetype (SSL_FILETYPE_PEM, or SSL_FILETYPE_ASN1)

Return values

true	if the certificate was successfully stored
false	otherwise

◆ HalSaveNewDeviceKey()

bool HalSaveNewDeviceKey	(	const uint8_t *	key,
		uint16_t	keylen,
		uint8_t	format = SSL_FILETYPE_PEM )

#include <hal.h>

Save a device key in persistent storage.

Parameters

key	Pointer to the buffer containing the key
keylen	length of the key
format	filetype (SSL_FILETYPE_PEM, or SSL_FILETYPE_ASN1)

Return values

true	if the key was successfully stored
false	otherwise

◆ HalStorage_AddressOffset()

int HalStorage_AddressOffset	(	uint8_t	area,
		void *	pWhere )

#include <hal.h>

Get the offset within a persistent storage area of an address. A platform may map any address to any offset of its choosing for a given storage area, and my modify its behavior on an area by area basis.

Parameters

area	The storage area being queried
pWhere	An address value to be translated

Returns: Offset of the requested address within the storage area. Returns negative on error.

◆ HalStorage_Erase()

int HalStorage_Erase	(	uint8_t	area,
		int	len = -1,
		int	offset = 0 )

#include <hal.h>

Erase all or part of a storage area. Note: due to physical storage granularities, the total area erased may extend beyond the requested area.

Parameters

area	The storage area to be erased
len	Number of bytes to be erased (a negative length will erase the entire area)
offset	The location within the area that the erasure should begin

Returns: Number of bytes erased. Returns negative on error.

See also: HalEraseDeviceCertAndKey()

◆ HalStorage_Finalize()

int HalStorage_Finalize ( uint8_t area )

#include <hal.h>

Finalize a storage area after writing new data. This will perform any final completion or cleanup routines required to persist the previously saved data from HalStorage_SavePartial calls.

Parameters

area	The storage area to finalize

Returns: Returns negative on error.

◆ HalStorage_GetAllocated()

int HalStorage_GetAllocated ( uint8_t area )

#include <hal.h>

Obtain the total size allocated to the given persistent storage area.

Parameters

area	The storage area being queried

Returns: Number of bytes allocated. Returns negative on error.

◆ HalStorage_GetMaxAllocation()

int HalStorage_GetMaxAllocation ( uint8_t area )

#include <hal.h>

Obtain the maximum size that may be allocated to the given persistent storage area. For direct flash mapped platforms, this is aliased to HalStorage_GetAllocated.

Parameters

area	The storage area being queried

Returns: Number of bytes allocated. Returns negative on error.

◆ HalStorage_Prepare()

int HalStorage_Prepare	(	uint8_t	area,
		int	len,
		int	offset = 0 )

#include <hal.h>

Prepare a storage area for writing new data. For platforms with direct flash mapping this function is an alias for HalStorage_Erase.

Parameters

area	The storage area to be readied
len	Number of bytes to be written by later HalStorage_SavePartial calls
offset	The location within the area that the readying should begin

Returns: Number of bytes readied. Returns negative on error.

◆ HalStorage_RemainingSpace()

int HalStorage_RemainingSpace ( uint8_t area )

#include <hal.h>

Obtain the number of remaining bytes available to be written in the given persistent storage area.

Parameters

area	The storage area being queried

Returns: Number of bytes available. Returns negative on error.

◆ HalStorage_Save()

int HalStorage_Save	(	uint8_t	area,
		void *	pData,
		int	len,
		int	offset = 0 )

#include <hal.h>

Save a blob to a specific persistent storage area as defined by the platform. This routine will perform all storage maintenance routines necessary to ensure a valid write.

Parameters

area	The storage area to be used. A platform is only required to support the areas as defined by HalStorage_t, however it may define additional areas as needed
pData	Pointer to the data to be written
len	Number of bytes to be written to the storage area
offset	Where in the storage area the first byte should be written. Default is 0.

Returns: Number of bytes written. Returns negative on error.

◆ HalStorage_SavePartial()

int HalStorage_SavePartial	(	uint8_t	area,
		void *	pData,
		int	len,
		int	offset )

#include <hal.h>

Save a blob to a specific persistent storage area as defined by the platform. This routine requires that any maintenance required for a valid write be explicitly performed prior to being called.

Parameters

area	The storage area to be used. A platform is only required to support the areas as defined by HalStorage_t, however it may define additional areas as needed.
pData	Pointer to the data to be written
len	Number of bytes to be written to the storage area
offset	Where in the storage area the first byte should be written.

Returns: Number of bytes written. Returns negative on error.

◆ HalStorage_WriteOffset()

int HalStorage_WriteOffset ( uint8_t area )

#include <hal.h>

Get the offset of the next byte that can be written in the given persistent storage area.

Parameters

area	The storage area being queried

Returns: Offset of the next byte that can be written. Returns negative on error.

◆ spaceleft()

uint32_t spaceleft ( )

#include <hal.h>

Report how much free unallocated space is left in dynamic memory.

Returns: Number of bytes unallocated in dynamic memory

◆ StdioCheckIntc()

void StdioCheckIntc ( void )

#include <hal.h>

Check STDIO interrupt sources.

Checks the interrupt sources used in the system along with their associated interrupt level and priority, and also checks for any conflicts in using the same level and priority between different sources. These results are sent to stdout.

See also: SysLogCheckIntc()

◆ SysLogCheckIntc()

void SysLogCheckIntc ( void )

#include <hal.h>

This is just like the StdioCheckIntc() function, except that the results are displayed via UDP.

See also: StdioCheckIntc()

Variable Documentation

◆ HalTickMaxCount

uint32_t HalTickMaxCount

extern

#include <hal.h>

Rollover value for the system hardware tick timer.

Returns: The max/rollover counter value used to generate the tick count

◆ watchdog_service_function

void(* watchdog_service_function) (void) ( void )

extern

#include <hal.h>

Watchdog callback service function.

If the following function pointer is set to point at a function of the form:

void YourFunc( void );

Then the system will call this function throughout the AutoUpdate/TCPUpdate process to make sure that the watchdog timer is serviced.

Functions

Variables

Detailed Description

Function Documentation

◆ FlashErase()

◆ FlashProgram()

◆ FlashProgramAppImage()

◆ HalDeviceCertValid()

◆ HalEraseDeviceCertAndKey()

◆ HalGetDeviceCert()

◆ HalGetDeviceCertLen()

◆ HalGetDeviceKey()

◆ HalGetDeviceKeyLen()

◆ HalGetTickFraction()

◆ HalSaveNewDeviceCert()

◆ HalSaveNewDeviceKey()

◆ HalStorage_AddressOffset()

◆ HalStorage_Erase()

◆ HalStorage_Finalize()

◆ HalStorage_GetAllocated()

◆ HalStorage_GetMaxAllocation()

◆ HalStorage_Prepare()

◆ HalStorage_RemainingSpace()

◆ HalStorage_Save()

◆ HalStorage_SavePartial()

◆ HalStorage_WriteOffset()

◆ spaceleft()

◆ StdioCheckIntc()

◆ SysLogCheckIntc()

Variable Documentation

◆ HalTickMaxCount

◆ watchdog_service_function