EtcPal

Overview

ETC Platform Abstraction Layer (EtcPal): A set of platform abstraction and utility modules used by ETC software libraries.

EtcPal supports the writing of platform-neutral C and C++ libraries by providing a set of modules to abstract common system calls. There are also a few platform-neutral utilities (e.g. data structures, logging) thrown in here and there for convenience. EtcPal headers can be either platform-neutral (contained in include/) or platform-specific (contained in include/os/[platform]). All platform-specific headers of the same EtcPal module will conform to an identical interface.

Some EtcPal modules must be initialized before use. These modules have a prominent notice in the "detailed description" portion of their documentation. To initialize the EtcPal library, call etcpal_init() with a mask of your desired features. The feature masks can be combined with a bitwise OR.

#include "etcpal/common.h"
 
etcpal_error_t result = etcpal_init(ETCPAL_FEATURE_SOCKETS | ETCPAL_FEATURE_LOGGING);

etcpal_init() can be called multiple times for the same or different sets of features, with no adverse effects. At deinitialization time, there should be a paired call to etcpal_deinit() with the same mask that was passed to the corresponding call to etcpal_init().

etcpal_deinit(ETCPAL_FEATURE_SOCKETS | ETCPAL_FEATURE_LOGGING);

Modules
	Core Modules
	EtcPal modules that exist independently of OS or network targets.
	OS Abstraction Modules
	Modules that abstract OS functionality, excluding networking.
	Network Abstraction Modules
	Modules that abstract networking functionality.
	C++ Wrappers
	C++ Wrappers for EtcPal modules.
	EtcPal config options
	Compile-time configuration options for EtcPal.

Macros
#define	ETCPAL_WAIT_FOREVER   -1
	For etcpal_ functions that take a millisecond timeout, this means to wait indefinitely.

Typedefs
typedef uint32_t	etcpal_features_t
	A mask of desired EtcPal features. More...

Functions
etcpal_error_t	etcpal_init (etcpal_features_t features)
	Initialize the EtcPal library. More...
void	etcpal_deinit (etcpal_features_t features)
	Deinitialize the EtcPal library. More...

EtcPal feature masks
Pass one or more of these to etcpal_init() to initialize the relevant EtcPal feature. Multiple features can be requested using logical OR. EtcPal modules not represented here require no initialization and are enabled by default.
#define	ETCPAL_FEATURE_SOCKETS   ((etcpal_features_t)(1u << 0))
	Use the etcpal/socket module.
#define	ETCPAL_FEATURE_NETINTS   ((etcpal_features_t)(1u << 1))
	Use the etcpal/netint module.
#define	ETCPAL_FEATURE_TIMERS   ((etcpal_features_t)(1u << 2))
	Use the etcpal/timer module.
#define	ETCPAL_FEATURE_LOGGING   ((etcpal_features_t)(1u << 3))
	Use the etcpal/log module.
#define	ETCPAL_FEATURES_ALL   0xffffffffu
	Use every available module.
#define	ETCPAL_FEATURES_ALL_BUT(mask)   (((uint32_t)ETCPAL_FEATURES_ALL) & ((uint32_t)(~((uint32_t)(mask)))))
	Use every available module except the ones passed in mask. More...

Macro Definition Documentation

ETCPAL_FEATURES_ALL_BUT

#define ETCPAL_FEATURES_ALL_BUT

(

mask

)

(((uint32_t)ETCPAL_FEATURES_ALL) & ((uint32_t)(~((uint32_t)(mask)))))

Use every available module except the ones passed in mask.

Parameters

mask	Mask of ETCPAL_FEATURE_* macros to not include in the feature mask.

Returns

Resulting EtcPal feature mask to pass to etcpal_init().

Typedef Documentation

etcpal_features_t

typedef uint32_t etcpal_features_t

A mask of desired EtcPal features.

See "EtcPal feature masks".

Function Documentation

etcpal_deinit()

void etcpal_deinit

(

etcpal_features_t

features

)

Deinitialize the EtcPal library.

This must be called with the same argument as the corresponding call to etcpal_init() to clean up resources held by the feature modules.

Parameters

[in]

features

Feature mask that was previously passed to etcpal_init().

etcpal_init()

etcpal_error_t etcpal_init

(

etcpal_features_t

features

)

Initialize the EtcPal library.

Use a bitwise OR to select from the set of modules which require initialization; for example:

etcpal_init(ETCPAL_FEATURE_SOCKETS | ETCPAL_FEATURE_NETINTS);

This function can be called multiple times from the same application. Each call to etcpal_init() must be paired with a call to etcpal_deinit() with the same argument for features.

If you are using a library that depends on EtcPal, and not using EtcPal directly, that library will call this function for you with the features it needs; you do not need to call it explicitly.

etcpal_init() and etcpal_deinit() are not thread-safe; you should make sure your init-time and deinit-time code is serialized.

Parameters

[in]

features

Mask of EtcPal features required.

Returns

kEtcPalErrOk: EtcPal library initialized successfully.

Various error codes possible from initialization of feature modules.