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. If your application supports logging, make sure to call etcpal_init_log_handler() before the first call to etcpal_init() so that critical assertions within EtcPal can be logged (then remember to specify the logging feature in the first call to etcpal_init()).

#include "etcpal/common.h"
 
EtcPalLogParams log_params = ETCPAL_LOG_PARAMS_INIT;
// Initialize log_params...
etcpal_error_t result = etcpal_init_log_handler(&log_params);
 
if (result == kEtcPalErrOk)
  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.
#define	ETCPAL_NO_WAIT   0
	For etcpal_ functions that take a millisecond timeout, this means do not wait at all.

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.

For each feature, this must be called the same number of times as etcpal_init() was called for that feature. The feature will be deinitialized on the final call.

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. Counters are tracked for each feature so that etcpal_init() and etcpal_deinit() can be called multiple times for the same feature(s) (useful if running multiple libraries that depend on common EtcPal features).

If you are using a library that depends on EtcPal, and not using EtcPal directly, please refer to that library's documentation to determine if you need to call this with the features the library needs.

If you've set up a handler for logs from the library via etcpal_init_log_handler(), make sure to enable the logging feature in the first call to etcpal_init() - otherwise an error will be returned.

It's highly recommended to call etcpal_init_log_handler() before this, since it will enable the application to log critical assertions that may occur within EtcPal.

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.

kEtcPalErrInvalid: A log handler was enabled via etcpal_init_log_handler(), but the logging feature is not enabled and was not specified in the feature mask.

Various error codes possible from initialization of feature modules.