Data Structures | Defines | Typedefs | Enumerations | Functions

Generic API

Generic declarations. More...

Data Structures

struct  em_notif_t

Defines

#define EM_CORE_MASK_SIZE   64
#define EM_EO_NAME_LEN   (32)
#define EM_EO_UNDEF   EM_UNDEF_U32
#define EM_ERROR   0xffffffff
#define EM_ERROR_FATAL_MASK   (0x80000000u)
#define EM_ERROR_IS_FATAL(error)   (EM_ERROR_FATAL_MASK & (error))
#define EM_ERROR_SET_FATAL(error)   (EM_ERROR_FATAL_MASK | (error))
#define EM_ESCOPE(escope)   (EM_ESCOPE_BIT & (escope))
#define EM_ESCOPE_ALLOC   (EM_ESCOPE_API_MASK | 0x0401)
#define EM_ESCOPE_API(escope)   (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_API_MASK)
#define EM_ESCOPE_API_MASK   (EM_ESCOPE_BIT | (EM_ESCOPE_API_TYPE << 24))
#define EM_ESCOPE_API_TYPE   (0xFFu)
#define EM_ESCOPE_ATOMIC_PROCESSING_END   (EM_ESCOPE_API_MASK | 0x0404)
#define EM_ESCOPE_BIT   (0x80000000u)
#define EM_ESCOPE_CORE_COUNT   (EM_ESCOPE_API_MASK | 0x0302)
#define EM_ESCOPE_CORE_ID   (EM_ESCOPE_API_MASK | 0x0301)
#define EM_ESCOPE_EO_ADD_QUEUE   (EM_ESCOPE_API_MASK | 0x0204)
#define EM_ESCOPE_EO_CREATE   (EM_ESCOPE_API_MASK | 0x0201)
#define EM_ESCOPE_EO_DELETE   (EM_ESCOPE_API_MASK | 0x0202)
#define EM_ESCOPE_EO_GET_NAME   (EM_ESCOPE_API_MASK | 0x0203)
#define EM_ESCOPE_EO_REGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0206)
#define EM_ESCOPE_EO_REMOVE_QUEUE   (EM_ESCOPE_API_MASK | 0x0205)
#define EM_ESCOPE_EO_START   (EM_ESCOPE_API_MASK | 0x0208)
#define EM_ESCOPE_EO_STOP   (EM_ESCOPE_API_MASK | 0x0209)
#define EM_ESCOPE_EO_UNREGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0207)
#define EM_ESCOPE_ERROR   (EM_ESCOPE_API_MASK | 0x0503)
#define EM_ESCOPE_FREE   (EM_ESCOPE_API_MASK | 0x0402)
#define EM_ESCOPE_INTERNAL(escope)   (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_INTERNAL_MASK)
#define EM_ESCOPE_INTERNAL_MASK   (EM_ESCOPE_BIT | (EM_ESCOPE_INTERNAL_TYPE << 24))
#define EM_ESCOPE_INTERNAL_TYPE   (0x00u)
#define EM_ESCOPE_MASK   (0xFF000000)
#define EM_ESCOPE_QUEUE_CREATE   (EM_ESCOPE_API_MASK | 0x0001)
#define EM_ESCOPE_QUEUE_CREATE_STATIC   (EM_ESCOPE_API_MASK | 0x0002)
#define EM_ESCOPE_QUEUE_DELETE   (EM_ESCOPE_API_MASK | 0x0003)
#define EM_ESCOPE_QUEUE_DISABLE   (EM_ESCOPE_API_MASK | 0x0006)
#define EM_ESCOPE_QUEUE_DISABLE_ALL   (EM_ESCOPE_API_MASK | 0x0007)
#define EM_ESCOPE_QUEUE_ENABLE   (EM_ESCOPE_API_MASK | 0x0004)
#define EM_ESCOPE_QUEUE_ENABLE_ALL   (EM_ESCOPE_API_MASK | 0x0005)
#define EM_ESCOPE_QUEUE_GET_CONTEXT   (EM_ESCOPE_API_MASK | 0x0009)
#define EM_ESCOPE_QUEUE_GET_GROUP   (EM_ESCOPE_API_MASK | 0x000D)
#define EM_ESCOPE_QUEUE_GET_NAME   (EM_ESCOPE_API_MASK | 0x000A)
#define EM_ESCOPE_QUEUE_GET_PRIORITY   (EM_ESCOPE_API_MASK | 0x000B)
#define EM_ESCOPE_QUEUE_GET_TYPE   (EM_ESCOPE_API_MASK | 0x000C)
#define EM_ESCOPE_QUEUE_GROUP_CREATE   (EM_ESCOPE_API_MASK | 0x0101)
#define EM_ESCOPE_QUEUE_GROUP_DELETE   (EM_ESCOPE_API_MASK | 0x0102)
#define EM_ESCOPE_QUEUE_GROUP_FIND   (EM_ESCOPE_API_MASK | 0x0104)
#define EM_ESCOPE_QUEUE_GROUP_MASK   (EM_ESCOPE_API_MASK | 0x0105)
#define EM_ESCOPE_QUEUE_GROUP_MODIFY   (EM_ESCOPE_API_MASK | 0x0103)
#define EM_ESCOPE_QUEUE_SET_CONTEXT   (EM_ESCOPE_API_MASK | 0x0008)
#define EM_ESCOPE_REGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0501)
#define EM_ESCOPE_SEND   (EM_ESCOPE_API_MASK | 0x0403)
#define EM_ESCOPE_UNREGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0502)
#define EM_EVENT_GROUP_MAX_NOTIF   (8)
#define EM_EVENT_GROUP_UNDEF   EM_UNDEF_U32
#define EM_EVENT_UNDEF   (0x00000000u)
#define EM_MAX_EOS   (256)
#define EM_MAX_EVENT_GROUPS   (1024)
#define EM_MAX_QUEUE_GROUPS   (16u)
#define EM_MAX_QUEUES   (TI_EM_QUEUE_SET_NUM * TI_EM_QUEUE_NUM_IN_SET)
#define EM_OK   0
#define EM_POOL_DEFAULT   (0u)
#define EM_QUEUE_GROUP_DEFAULT   (1u)
#define EM_QUEUE_GROUP_NAME_LEN   (8u)
#define EM_QUEUE_GROUP_UNDEF   EM_UNDEF_U32
#define EM_QUEUE_NAME_LEN   (32)
#define EM_QUEUE_STATIC_MAX   ((TI_EM_QUEUE_SET_NUM * TI_EM_STATIC_QUEUE_NUM_IN_SET) - 1)
#define EM_QUEUE_STATIC_MIN   (1)
#define EM_QUEUE_STATIC_NUM   (EM_QUEUE_STATIC_MAX - EM_QUEUE_STATIC_MIN + 1)
#define EM_QUEUE_UNDEF   EM_UNDEF_U32
#define EM_UNDEF_U16   (0x0000u)
#define EM_UNDEF_U32   (0x00000000u)
#define EM_UNDEF_U64   (0x0000000000000000u)
#define EM_UNDEF_U8   (0x00u)
#define PRI_EGRP   PRIu32
#define PRI_EO   PRIu32
#define PRI_QGRP   PRIu32
#define PRI_QUEUE   PRIu32

Typedefs

typedef union em_core_mask_t em_core_mask_t
typedef uint32_t em_eo_t
typedef em_status_t(* em_error_handler_t )(em_eo_t eo, em_status_t error, em_escope_t escope, va_list args)
typedef uint32_t em_escope_t
typedef uint32_t em_event_group_t
typedef uint32_t em_event_t
typedef enum em_event_type_major_e em_event_type_major_e
typedef enum
em_event_type_sw_minor_e 
em_event_type_sw_minor_e
typedef uint32_t em_event_type_t
typedef struct em_notif_t em_notif_t
typedef uint32_t em_pool_id_t
typedef uint32_t em_queue_group_t
typedef enum em_queue_prio_e em_queue_prio_e
typedef uint32_t em_queue_prio_t
typedef uint32_t em_queue_t
typedef enum em_queue_type_e em_queue_type_e
typedef uint32_t em_queue_type_t
typedef void(* em_receive_func_t )(void *eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void *q_ctx)
typedef em_status_t(* em_start_func_t )(void *eo_ctx, em_eo_t eo)
typedef em_status_t(* em_start_local_func_t )(void *eo_ctx, em_eo_t eo)
typedef enum em_status_e em_status_e
typedef uint32_t em_status_t
typedef em_status_t(* em_stop_func_t )(void *eo_ctx, em_eo_t eo)
typedef em_status_t(* em_stop_local_func_t )(void *eo_ctx, em_eo_t eo)

Enumerations

enum  em_event_type_major_e
enum  em_event_type_sw_minor_e
enum  em_queue_prio_e
enum  em_queue_type_e
enum  em_status_e

Functions

em_event_t em_alloc (size_t size, em_event_type_t type, em_pool_id_t pool_id)
void em_atomic_processing_end (void)
int em_core_count (void)
int em_core_id (void)
int em_core_id_get_physical (int core)
static void em_core_mask_clr (int core, em_core_mask_t *mask)
static void em_core_mask_copy (em_core_mask_t *dest, const em_core_mask_t *src)
static int em_core_mask_count (const em_core_mask_t *mask)
static int em_core_mask_equal (const em_core_mask_t *mask1, const em_core_mask_t *mask2)
void em_core_mask_get_physical (em_core_mask_t *phys, const em_core_mask_t *logic)
static int em_core_mask_isset (int core, const em_core_mask_t *mask)
static int em_core_mask_iszero (const em_core_mask_t *mask)
static void em_core_mask_set (int core, em_core_mask_t *mask)
static void em_core_mask_set_count (int count, em_core_mask_t *mask)
static void em_core_mask_zero (em_core_mask_t *mask)
em_status_t em_eo_add_queue (em_eo_t eo, em_queue_t queue)
em_eo_t em_eo_create (const char *name, em_start_func_t start, em_start_local_func_t local_start, em_stop_func_t stop, em_stop_local_func_t local_stop, em_receive_func_t receive, const void *eo_ctx)
em_status_t em_eo_delete (em_eo_t eo)
size_t em_eo_get_name (em_eo_t eo, char *name, size_t maxlen)
em_status_t em_eo_register_error_handler (em_eo_t eo, em_error_handler_t handler)
em_status_t em_eo_remove_queue (em_eo_t eo, em_queue_t queue, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_eo_start (em_eo_t eo, em_status_t *result, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_eo_stop (em_eo_t eo, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_eo_unregister_error_handler (em_eo_t eo)
void em_error (em_status_t error, em_escope_t escope,...)
int em_error_format_string (char *str, size_t size, em_eo_t eo, em_status_t error, em_escope_t escope, va_list args)
em_status_t em_event_group_apply (em_event_group_t group, int count, int num_notif, const em_notif_t *notif_tbl)
em_event_group_t em_event_group_create (void)
em_event_group_t em_event_group_current (void)
em_status_t em_event_group_delete (em_event_group_t event_group)
em_status_t em_event_group_increment (int count)
void * em_event_pointer (const em_event_t event)
void em_free (em_event_t event)
em_event_type_t em_get_type_major (em_event_type_t type)
em_event_type_t em_get_type_minor (em_event_type_t type)
em_queue_t em_queue_create (const char *name, em_queue_type_t type, em_queue_prio_t prio, em_queue_group_t group)
em_status_t em_queue_create_static (const char *name, em_queue_type_t type, em_queue_prio_t prio, em_queue_group_t group, em_queue_t queue)
em_status_t em_queue_delete (em_queue_t queue)
em_status_t em_queue_disable (em_queue_t queue, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_queue_disable_all (em_eo_t eo, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_queue_enable (em_queue_t queue)
em_status_t em_queue_enable_all (em_eo_t eo)
void * em_queue_get_context (em_queue_t queue)
em_queue_group_t em_queue_get_group (em_queue_t queue)
size_t em_queue_get_name (em_queue_t queue, char *name, size_t maxlen)
em_queue_prio_t em_queue_get_priority (em_queue_t queue)
em_queue_type_t em_queue_get_type (em_queue_t queue)
em_queue_group_t em_queue_group_create (const char *name, const em_core_mask_t *mask, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_queue_group_delete (em_queue_group_t group, int num_notif, const em_notif_t *notif_tbl)
em_queue_group_t em_queue_group_find (const char *name)
em_status_t em_queue_group_mask (em_queue_group_t group, em_core_mask_t *mask)
em_status_t em_queue_group_modify (em_queue_group_t group, const em_core_mask_t *new_mask, int num_notif, const em_notif_t *notif_tbl)
em_status_t em_queue_set_context (em_queue_t queue, const void *context)
em_status_t em_register_error_handler (em_error_handler_t handler)
em_status_t em_send (em_event_t event, em_queue_t queue)
em_status_t em_send_group (em_event_t event, em_queue_t queue, em_event_group_t group)
em_status_t em_unregister_error_handler (void)

Detailed Description

Generic declarations.


Define Documentation

#define EM_CORE_MASK_SIZE   64

Size of the core mask in bits

#define EM_EO_NAME_LEN   (32)

Max EO name string lenght.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_EO_UNDEF   EM_UNDEF_U32

Invalid EO id

#define EM_ERROR   0xffffffff

Operation not successful

#define EM_ERROR_FATAL_MASK   (0x80000000u)

Fatal error mask

#define EM_ERROR_IS_FATAL (   error)    (EM_ERROR_FATAL_MASK & (error))

Test if error is fatal

#define EM_ERROR_SET_FATAL (   error)    (EM_ERROR_FATAL_MASK | (error))

Set a fatal error code

#define EM_ESCOPE (   escope)    (EM_ESCOPE_BIT & (escope))

Test if the error scope identifies an EM function (API or other internal)

#define EM_ESCOPE_ALLOC   (EM_ESCOPE_API_MASK | 0x0401)

Error scope for the em_alloc API.

#define EM_ESCOPE_API (   escope)    (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_API_MASK)

Test if the error scope identifies an API function

#define EM_ESCOPE_API_MASK   (EM_ESCOPE_BIT | (EM_ESCOPE_API_TYPE << 24))

EM API functions error scope mask

#define EM_ESCOPE_API_TYPE   (0xFFu)

EM API functions error scope type

#define EM_ESCOPE_ATOMIC_PROCESSING_END   (EM_ESCOPE_API_MASK | 0x0404)

Error scope for the em_atomic_processing_end API.

#define EM_ESCOPE_BIT   (0x80000000u)

All EM internal error scopes should have bit 31 set NOTE: High bit is RESERVED for EM internal escopes and should not be used by the application.

#define EM_ESCOPE_CORE_COUNT   (EM_ESCOPE_API_MASK | 0x0302)

Error scope for the em_core_count API.

#define EM_ESCOPE_CORE_ID   (EM_ESCOPE_API_MASK | 0x0301)

Error scope for the em_core_id API.

#define EM_ESCOPE_EO_ADD_QUEUE   (EM_ESCOPE_API_MASK | 0x0204)

Error scope for the em_eo_add_queue API.

#define EM_ESCOPE_EO_CREATE   (EM_ESCOPE_API_MASK | 0x0201)

Error scope for the em_eo_create API.

#define EM_ESCOPE_EO_DELETE   (EM_ESCOPE_API_MASK | 0x0202)

Error scope for the em_eo_delete API.

#define EM_ESCOPE_EO_GET_NAME   (EM_ESCOPE_API_MASK | 0x0203)

Error scope for the em_eo_get_name API.

#define EM_ESCOPE_EO_REGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0206)

Error scope for the em_eo_register_error_handler API.

#define EM_ESCOPE_EO_REMOVE_QUEUE   (EM_ESCOPE_API_MASK | 0x0205)

Error scope for the em_eo_remove_queue API.

#define EM_ESCOPE_EO_START   (EM_ESCOPE_API_MASK | 0x0208)

Error scope for the em_eo_start API.

#define EM_ESCOPE_EO_STOP   (EM_ESCOPE_API_MASK | 0x0209)

Error scope for the em_eo_stop API.

#define EM_ESCOPE_EO_UNREGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0207)

Error scope for the em_eo_unregister_error_handler API.

#define EM_ESCOPE_ERROR   (EM_ESCOPE_API_MASK | 0x0503)

Error scope for the em_error API.

#define EM_ESCOPE_FREE   (EM_ESCOPE_API_MASK | 0x0402)

Error scope for the em_free API.

#define EM_ESCOPE_INTERNAL (   escope)    (((escope) & EM_ESCOPE_MASK) == EM_ESCOPE_INTERNAL_MASK)

Test if the error scope identifies an EM Internal function

#define EM_ESCOPE_INTERNAL_MASK   (EM_ESCOPE_BIT | (EM_ESCOPE_INTERNAL_TYPE << 24))

EM internal error scope type

#define EM_ESCOPE_INTERNAL_TYPE   (0x00u)

EM internal error scope mask

#define EM_ESCOPE_MASK   (0xFF000000)

Mask selects the high byte of the 32-bit escope

#define EM_ESCOPE_QUEUE_CREATE   (EM_ESCOPE_API_MASK | 0x0001)

Error scope for the em_queue_create API.

#define EM_ESCOPE_QUEUE_CREATE_STATIC   (EM_ESCOPE_API_MASK | 0x0002)

Error scope for the em_queue_create_static API.

#define EM_ESCOPE_QUEUE_DELETE   (EM_ESCOPE_API_MASK | 0x0003)

Error scope for the em_queue_delete API.

#define EM_ESCOPE_QUEUE_DISABLE   (EM_ESCOPE_API_MASK | 0x0006)

Error scope for the em_queue_disable API.

#define EM_ESCOPE_QUEUE_DISABLE_ALL   (EM_ESCOPE_API_MASK | 0x0007)

Error scope for the em_queue_disable_all API.

#define EM_ESCOPE_QUEUE_ENABLE   (EM_ESCOPE_API_MASK | 0x0004)

Error scope for the em_queue_enable API.

#define EM_ESCOPE_QUEUE_ENABLE_ALL   (EM_ESCOPE_API_MASK | 0x0005)

Error scope for the em_queue_enable_all API.

#define EM_ESCOPE_QUEUE_GET_CONTEXT   (EM_ESCOPE_API_MASK | 0x0009)

Error scope for the em_queue_get_context API.

#define EM_ESCOPE_QUEUE_GET_GROUP   (EM_ESCOPE_API_MASK | 0x000D)

Error scope for the em_queue_group_create API.

#define EM_ESCOPE_QUEUE_GET_NAME   (EM_ESCOPE_API_MASK | 0x000A)

Error scope for the em_queue_get_name API.

#define EM_ESCOPE_QUEUE_GET_PRIORITY   (EM_ESCOPE_API_MASK | 0x000B)

Error scope for the em_queue_get_priority API.

#define EM_ESCOPE_QUEUE_GET_TYPE   (EM_ESCOPE_API_MASK | 0x000C)

Error scope for the em_queue_get_type API.

#define EM_ESCOPE_QUEUE_GROUP_CREATE   (EM_ESCOPE_API_MASK | 0x0101)

Error scope for the em_queue_group_create API.

#define EM_ESCOPE_QUEUE_GROUP_DELETE   (EM_ESCOPE_API_MASK | 0x0102)

Error scope for the em_queue_group_delete API.

#define EM_ESCOPE_QUEUE_GROUP_FIND   (EM_ESCOPE_API_MASK | 0x0104)

Error scope for the em_queue_group_find API.

#define EM_ESCOPE_QUEUE_GROUP_MASK   (EM_ESCOPE_API_MASK | 0x0105)

Error scope for the em_queue_group_mask API.

#define EM_ESCOPE_QUEUE_GROUP_MODIFY   (EM_ESCOPE_API_MASK | 0x0103)

Error scope for the em_queue_group_modify API.

#define EM_ESCOPE_QUEUE_SET_CONTEXT   (EM_ESCOPE_API_MASK | 0x0008)

Error scope for the em_queue_set_context API.

#define EM_ESCOPE_REGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0501)

Error scope for the em_register_error_handler API.

#define EM_ESCOPE_SEND   (EM_ESCOPE_API_MASK | 0x0403)

Error scope for the em_send API.

#define EM_ESCOPE_UNREGISTER_ERROR_HANDLER   (EM_ESCOPE_API_MASK | 0x0502)

Error scope for the em_unregister_error_handler API.

#define EM_EVENT_GROUP_MAX_NOTIF   (8)

Maximum number of event notifications supported by one event group.

#define EM_EVENT_GROUP_UNDEF   EM_UNDEF_U32

Invalid event group id

#define EM_EVENT_UNDEF   (0x00000000u)

Undefined event

#define EM_MAX_EOS   (256)

Maximum number of execution objects supported by the event machine. EM_MAX_EOS <= TI_EM_EO_NUM_MAX.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_MAX_EVENT_GROUPS   (1024)

Maximum number of event groups supported by the event machine. EM_MAX_EVENT_GROUPS <= TI_EM_EVENT_GROUP_NUM_MAX.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_MAX_QUEUE_GROUPS   (16u)

Maximum number of queue groups supported by the event machine.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_MAX_QUEUES   (TI_EM_QUEUE_SET_NUM * TI_EM_QUEUE_NUM_IN_SET)

Maximum number of queues supported by the event machine.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_OK   0

Operation successful

#define EM_POOL_DEFAULT   (0u)

Define default memory pool

#define EM_QUEUE_GROUP_DEFAULT   (1u)

Default queue group for EM

#define EM_QUEUE_GROUP_NAME_LEN   (8u)

Max queue group name string lenght.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_QUEUE_GROUP_UNDEF   EM_UNDEF_U32

Invalid queue group id

#define EM_QUEUE_NAME_LEN   (32)

Max queue name string length.

Note:
This value can be modified by an application. But the event machine library needs to be recompiled.
#define EM_QUEUE_STATIC_MAX   ((TI_EM_QUEUE_SET_NUM * TI_EM_STATIC_QUEUE_NUM_IN_SET) - 1)

Static queues: maximal value

#define EM_QUEUE_STATIC_MIN   (1)

Static queues: minimal value

#define EM_QUEUE_STATIC_NUM   (EM_QUEUE_STATIC_MAX - EM_QUEUE_STATIC_MIN + 1)

Static queues: number of status queues

#define EM_QUEUE_UNDEF   EM_UNDEF_U32

Invalid queue

#define EM_UNDEF_U16   (0x0000u)

Invalid identifier (16-bit)

#define EM_UNDEF_U32   (0x00000000u)

Invalid identifier (32-bit)

#define EM_UNDEF_U64   (0x0000000000000000u)

Invalid identifier (64-bit)

#define EM_UNDEF_U8   (0x00u)

Invalid identifier (8-bit)

#define PRI_EGRP   PRIu32

em_event_group_t printf format

#define PRI_EO   PRIu32

em_eo_t printf format

#define PRI_QGRP   PRIu32

em_queue_group_t printf format

#define PRI_QUEUE   PRIu32

em_queue_t printf format


Typedef Documentation

Type for queue group core mask. Each bit represents one core, core 0 is the lsb (1 << em_core_id()) Note, that EM will enumerate the core identifiers to always start from 0 and be contiguous meaning the core numbers are not necessarily physical. This type can handle up to 64 cores.

See also:
em_queue_group_create()
typedef uint32_t em_eo_t

Execution Object identifier

See also:
em_eo_create()
typedef em_status_t(* em_error_handler_t)(em_eo_t eo, em_status_t error, em_escope_t escope, va_list args)

Error handler.

Error handler maybe called after EM notices an error or user have called em_error().

User can register EO specific and/or EM global error handlers. When an error is noticed, EM calls EO specific error handler, if registered. If there's no EO specific handler registered (for the EO) or the error is noticed outside of an EO context, EM calls the global error handler (if registered). If no error handlers are found, EM just returns an error code depending on the API function.

Error handler is called with the original error code from the API call or em_error(). Error scope identifies the source of the error and how the error code and variable arguments should be interpreted (number of arguments and types).

Parameters:
eoExecution object id
errorThe error code
escopeError scope. Identifies the scope for interpreting the error code and variable arguments.
argsVariable number and type of arguments
Returns:
The function may not return depending on implementation/error code/error scope. If it returns, it can return the original or modified error code or even EM_OK, if it could fix the problem.
See also:
em_register_error_handler(), em_eo_register_error_handler()
typedef uint32_t em_escope_t

Error scope.

Identifies the error scope for interpreting error codes and variable arguments.

See also:
em_error_handler_t(), em_error()
typedef uint32_t em_event_group_t

Event group id. This is used for fork-join event handling.

See also:
em_event_group_create()
typedef uint32_t em_event_t

Event type

In Event Machine application processing is driven by events. An event describes a piece of work. Structure of an event is implementation and event type specific. It may be a directly accessible buffer of memory, a descriptor containing a list of buffer pointers, a descriptor of a packet buffer, etc.

Applications use event type to interpret the event structure.

Since em_event_t may not carry a direct pointer value to the event structure, em_event_pointer() must be used to translate an event to an event structure pointer (for maintaining portability).

See also:
em_event_pointer()

The structure describes the major event types

The structure describes the Minor event types for the major EM_EVENT_TYPE_SW type

typedef uint32_t em_event_type_t

Event type. This is given to application for each received event and also needed for event allocation. It's an integer, but split into major and minor part. major-field categorizes the event and minor is more detailed system specific description. Major-part will not change by HW, but minor can be HW/SW platform specific and thus could be split into more sub-fields as needed. Application should use the access functions for reading major and minor part.

The only event type with defined content is EM_EVENT_TYPE_SW with minor type 0, which needs to be portable (direct pointer to data).

See also:
em_get_type_major(), em_get_type_minor(), em_receive_func_t()
typedef struct em_notif_t em_notif_t

Notification structure allows user to define a notification event and destination queue pair. EM will notify user by sending the event into the queue.

typedef uint32_t em_pool_id_t

Memory pool id.

Defines memory pool in em_alloc(). Default pool id is defined by EM_POOL_DEFAULT.

See also:
em_alloc(), event_machine_hw_config.h
typedef uint32_t em_queue_group_t

Queue group identifier

Each queue belongs to one queue group, that defines a core mask for scheduling events, i.e. define which cores participate in the load balancing. Group can also allow only a single core for no load balancing.

Groups needs to be created as needed. One default group (EM_QUEUE_GROUP_DEFAULT) always exists, and that allows scheduling to all the cores running this execution binary instance.

See also:
em_queue_group_create()

The structure describes the portable queue priorities

typedef uint32_t em_queue_prio_t

Queue priority class

Queue priority defines a system dependent QoS class, not just an absolute priority. EM gives freedom to implement the actual scheduling disciplines and the corresponding numeric values as needed, i.e. the actual values are system dependent and thus not portable, but the 5 pre-defined enums (em_queue_prio_e) are always valid. Application platform or middleware needs to define and distribute the other available values.

See also:
em_queue_create(), event_machine_hw_config.h
typedef uint32_t em_queue_t

Queue identifier

See also:
em_queue_create(), em_receive_func_t(), em_send()

The structure describes the queue types

typedef uint32_t em_queue_type_t

Queue type.

Affects the scheduling principle

See also:
em_queue_create(), event_machine_hw_config.h
typedef void(* em_receive_func_t)(void *eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void *q_ctx)

Receive event

Application receives events through the EO receive function. It implements main part of the application logic. EM calls the receive function when it has dequeued an event from one of the EO's queues. Application processes the event and returns immediately (in run-to-completion fashion).

On multicore systems several events (from the same or different queues) may be dequeued in parallel and thus same receive function may be executed concurrently on several cores. Parallel execution may be limited by queue group setup or using queues with atomic scheduling mode.

EO and queue context pointers are user defined (in EO and queue creation time) and may be used any way needed. For example, EO context may be used to store global EO state information, which is common to all queues and events. In addition, queue context may be used to store queue (or user data flow) specific state data. EM never touches the data, just passes the pointers.

Event (handle) must be converted to an event structure pointer with em_event_pointer(). Event type specifies the event structure, which is implementation or application specific. Queue id specifies the queue which the event was dequeued from.

Parameters:
eo_ctxEO context data. The pointer is passed in em_eo_create(), EM does not touch the data.
eventEvent handle
typeEvent type
queueQueue from which this event came from
q_ctxQueue context data. The pointer is passed in em_queue_set_context(), EM does not touch the data.
See also:
em_event_pointer(), em_free(), em_alloc(), em_send(), em_queue_set_context(), em_eo_create()
typedef em_status_t(* em_start_func_t)(void *eo_ctx, em_eo_t eo)

Execution object start, global.

If load balancing/several cores share the EO, this function is called once on one core only (any). Purpose of this global start is to provide a placeholder for first level initialization, like allocating memory and initializing shared data. After this global start returns, the core local version (if defined), is called (see em_start_local_func_t below). If there is no core local start, then event dispatching is immediately enabled.

If Execution object does not return EM_OK, the system will not call the core local init and will not enable event dispatching.

This function should never be called directly from the application, but using the, which maintains state information!

Parameters:
eo_ctxExecution object internal state/instance data
eoExecution object id
Returns:
EM_OK if successful.
See also:
em_eo_start(), em_eo_create()
typedef em_status_t(* em_start_local_func_t)(void *eo_ctx, em_eo_t eo)

Execution object start, core local.

This is similar to the global start above, but this one is called after the global start has completed and is called on all cores.

Purpose of this optional local start is to work as a placeholder for core local initialization, e.g. allocating core local memory for example. The global start is only called on one core. The use of local start is optional. Note, that application should never directly call this function, this will be called via em_eo_start().

If this does not return EM_OK on all involved cores, the event dispatching is not enabled.

Parameters:
eo_ctxExecution object internal state/instance data
eoExecution object id
Returns:
EM_OK if successful.
See also:
em_eo_start(), em_eo_create()
typedef enum em_status_e em_status_e

The structure lists the error codes

typedef uint32_t em_status_t

Error/Status code. EM_OK (0) is the general code for success, other values describe failed operation.

See also:
event_machine_hw_config.h, em_error_handler_t(), em_error()
typedef em_status_t(* em_stop_func_t)(void *eo_ctx, em_eo_t eo)

Execution object stop, global.

If load balancing/several cores share the EO, this function is called once on one core (any) after the (optional) core local stop return on all cores. System disables event dispatching before calling this and also makes sure this does not get called before all cores have been notified the stop condition for this EO (can't dispatch new events) event if there is no core local stop defined. Return value is only for logging purposes, EM does not use it currently.

Note, that application should never directly call this stop function, but use the em_eo_stop() instead, which maintains state information and guarantees synchronized operation.

Parameters:
eo_ctxExecution object internal state data
eoExecution object id
Returns:
EM_OK if successful.
See also:
em_eo_stop(), em_eo_create()
typedef em_status_t(* em_stop_local_func_t)(void *eo_ctx, em_eo_t eo)

Execution object stop, core local.

If load balancing/several cores share the EO, this function is called once on each core before the global stop (reverse order of start). System disables event dispatching before calling this and also makes sure this does not get called before the core has been notified the stop condition for this EO (won't dispatch new events) Return value is only for logging purposes, EM does not use it currently.

Note, that application should never directly call this stop function, em_eo_stop() will trigger this.

Parameters:
eo_ctxExecution object internal state data
eoExecution object id
Returns:
EM_OK if successful.
See also:
em_eo_stop(), em_eo_create()

Enumeration Type Documentation

The structure describes the major event types

Enumerator:
EM_EVENT_TYPE_SW 

event from SW (EO)

EM_EVENT_TYPE_PACKET 

event from packet HW

EM_EVENT_TYPE_TIMER 

event from timer HW

EM_EVENT_TYPE_CRYPTO 

event from crypto HW

The structure describes the Minor event types for the major EM_EVENT_TYPE_SW type

The structure describes the portable queue priorities

Enumerator:
EM_QUEUE_PRIO_UNDEF 

Undefined.

EM_QUEUE_PRIO_LOWEST 

lowest priority

EM_QUEUE_PRIO_LOW 

low priority

EM_QUEUE_PRIO_NORMAL 

normal priority

EM_QUEUE_PRIO_HIGH 

high priority

EM_QUEUE_PRIO_HIGHEST 

highest priority

The structure describes the queue types

Enumerator:
EM_QUEUE_TYPE_UNDEF 

Application receives events one by one, non-concurrently to guarantee exclusive processing and ordering.

EM_QUEUE_TYPE_ATOMIC 

Application receives events one by one, non-concurrently to guarantee exclusive processing and ordering.

EM_QUEUE_TYPE_PARALLEL 

Application may receive events fully concurrently, egress event ordering (when processed in parallel) not guaranteed.

EM_QUEUE_TYPE_PARALLEL_ORDERED 

Application may receive events concurrently, but system takes care of egress order (between two queues)

The structure lists the error codes

Enumerator:
EM_ERR_BAD_CONTEXT 

Illegal context for this function call.

EM_ERR_BAD_STATE 

Illegal (eo, queue, ...) state for this function call.

EM_ERR_BAD_ID 

ID not from a valid range.

EM_ERR_ALLOC_FAILED 

Resource allocation failed.

EM_ERR_NOT_FREE 

Resource already reserved by someone else.

EM_ERR_NOT_FOUND 

Resource not found.

EM_ERR_TOO_LARGE 

Value over the limit.

EM_ERR_LIB_FAILED 

Failure in a library function.

EM_ERR_NOT_IMPLEMENTED 

Implementation missing (placeholder)

EM_ERR_BAD_POINTER 

Pointer from bad memory area (e.g. NULL)

EM_ERR 

Other error. This is the last error code (for bounds checking).


Function Documentation

em_event_t em_alloc ( size_t  size,
em_event_type_t  type,
em_pool_id_t  pool_id 
)

Allocate an event.

Memory address of the allocated event is system specific and can depend on given pool id, event size and type. Returned event (handle) may refer to a memory buffer or a HW specific descriptor, i.e. the event structure is system specific.

Use em_event_pointer() to convert an event (handle) to a pointer to the event structure.

EM_EVENT_TYPE_SW with minor type 0 is reserved for direct portability. It is always guaranteed to return a 64-bit aligned contiguous data buffer, that can directly be used by the application up to the given size (no HW specific descriptors etc are visible).

EM_POOL_DEFAULT can be used as pool id if there's no need to use any specific memory pool.

Additionally it is guaranteed, that two separate buffers never share a cache line to avoid false sharing.

Parameters:
sizeEvent size in octets
typeEvent type to allocate
pool_idEvent pool id
Returns:
the allocated event or EM_EVENT_UNDEF on an error
See also:
em_free(), em_send(), em_event_pointer(), em_receive_func_t()
void em_atomic_processing_end ( void  )

Release atomic processing context.

When an event was received from an atomic queue, the function can be used to release the atomic context before receive function return. After the call, scheduler is allowed to schedule another event from the same queue to another core. This increases parallelism and may improve performance - however the exclusive processing and ordering (!) might be lost after the call.

Can only be called from within the event receive function!

The call is ignored, if current event was not received from an atomic queue.

Pseudo-code example:

  receive_func(void* eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void* q_ctx);
  {
      if(is_my_atomic_queue(q_ctx))
      {
          update_sequence_number(event);  // this needs to be done atomically
          em_atomic_processing_end();
          ...                             // do other processing (potentially) in parallel
      }
   }
See also:
em_receive_func_t()
int em_core_count ( void  )

The number of cores running within the same EM instance (sharing the EM state).

Returns:
Number of EM cores (or HW threads)
See also:
em_core_id()
int em_core_id ( void  )

Logical core id.

Returns the logical id of the current core. EM enumerates cores (or HW threads) to always start from 0 and be contiguous, i.e. valid core identifiers are 0...em_core_count()-1

Returns:
Current logical core id
See also:
em_core_count()
int em_core_id_get_physical ( int  core)

Converts a logical core id to a physical core id

Mainly needed when interfacing HW specific APIs

Parameters:
corelogical (Event Machine) core id
Returns:
Physical core id
static void em_core_mask_clr ( int  core,
em_core_mask_t mask 
) [inline, static]

Clear a bit in the mask.

Parameters:
coreCore id
maskCore mask
static void em_core_mask_copy ( em_core_mask_t dest,
const em_core_mask_t src 
) [inline, static]

Copy core mask

Parameters:
destDestination core mask
srcSource core mask
static int em_core_mask_count ( const em_core_mask_t mask) [inline, static]

Count the number of bits set in the mask.

Parameters:
maskCore mask
Returns:
Number of bits set
static int em_core_mask_equal ( const em_core_mask_t mask1,
const em_core_mask_t mask2 
) [inline, static]

Test if two masks are equal

Parameters:
mask1First core mask
mask2Second core mask
Returns:
Non-zero if the two masks are equal
void em_core_mask_get_physical ( em_core_mask_t phys,
const em_core_mask_t logic 
)

Converts a logical core mask to a physical core mask

Mainly needed when interfacing HW specific APIs

Parameters:
physCore mask of physical core ids
logicCore mask of logical (Event Machine) core ids
static int em_core_mask_isset ( int  core,
const em_core_mask_t mask 
) [inline, static]

Test if a bit is set in the mask.

Parameters:
coreCore id
maskCore mask
Returns:
Non-zero if core id is set in the mask
static int em_core_mask_iszero ( const em_core_mask_t mask) [inline, static]

Test if the mask is all zero.

Parameters:
maskCore mask
Returns:
Non-zero if the mask is all zero
static void em_core_mask_set ( int  core,
em_core_mask_t mask 
) [inline, static]

Set a bit in the mask.

Parameters:
coreCore id
maskCore mask
static void em_core_mask_set_count ( int  count,
em_core_mask_t mask 
) [inline, static]

Set a range (0...count-1) of bits in the mask.

Parameters:
countNumber of bits to set
maskCore mask
static void em_core_mask_zero ( em_core_mask_t mask) [inline, static]

Zero the whole mask.

Parameters:
maskCore mask
em_status_t em_eo_add_queue ( em_eo_t  eo,
em_queue_t  queue 
)

Add a queue to an EO.

Note, that this does not enable the queue. Although queues added in (or before) the start function will be enabled automatically.

Parameters:
eoEO id
queueQueue id
Returns:
EM_OK if successful.
See also:
em_queue_create(), em_eo_create(), em_queue_enable(), em_eo_remove_queue()
em_eo_t em_eo_create ( const char *  name,
em_start_func_t  start,
em_start_local_func_t  local_start,
em_stop_func_t  stop,
em_stop_local_func_t  local_stop,
em_receive_func_t  receive,
const void *  eo_ctx 
)

Create Execution Object (EO).

This will allocate identifier and initialize internal data for a new EO. It is left in a non-active state, i.e. no events are dispatched before em_eo_start() has called. Start, stop and receive callback function pointers are mandatory parameters.

The name given is copied to EO internal data and can be used e.g. for debugging. The maximum length stored is EM_EO_NAME_LEN.

Parameters:
nameName of the EO (NULL if no name)
startStart function
local_startCore local start function (NULL if no local start)
stopStop function
local_stopCore local stop function (NULL if no local stop)
receiveReceive function
eo_ctxUser defined EO context data, EM just passes the pointer (NULL if not context)
Returns:
New EO id if successful, otherwise EM_EO_UNDEF
See also:
em_eo_start(), em_eo_delete(), em_queue_create(), em_eo_add_queue()
em_start_func_t(), em_stop_func_t(), em_receive_func_t()
em_status_t em_eo_delete ( em_eo_t  eo)

Delete Execution Object (EO).

This will immediately delete the given EO and free the identifier.

NOTE, that EO can only be deleted after it has been stopped using em_eo_stop(), otherwise another core might still access the EO data! Deletion will fail, if the EO is not stopped.

This will delete all possibly remaining queues.

Parameters:
eoEO id to delete
Returns:
EM_OK if successful.
See also:
em_eo_stop(), em_eo_create()
size_t em_eo_get_name ( em_eo_t  eo,
char *  name,
size_t  maxlen 
)

Returns the name given to the EO when it was created.

A copy of the name string (up to 'maxlen' characters) is written to the user buffer 'name'. String is always null terminated even if the given buffer length is less than the name length.

If the EO has no name, function returns 0 and writes empty string.

This is only for debugging purposes.

Parameters:
eoEO id
nameDestination buffer
maxlenMaximum length (including the terminating '0')
Returns:
Number of characters written (excludes the terminating '0')
See also:
em_eo_create()
em_status_t em_eo_register_error_handler ( em_eo_t  eo,
em_error_handler_t  handler 
)

Register EO specific error handler.

The EO specific error handler is called if error is noticed or em_error() is called in the context of the EO. Note, the function will override any previously registered error hanler.

Parameters:
eoEO id
handlerNew error handler.
Returns:
EM_OK if successful.
See also:
em_register_error_handler(), em_error_handler_t()
em_status_t em_eo_remove_queue ( em_eo_t  eo,
em_queue_t  queue,
int  num_notif,
const em_notif_t notif_tbl 
)

Removes a queue from an EO.

Function disables scheduling of the queue and removes the queue from the EO. The operation is asynchronous, to quarantee that all cores have completed processing of events from the queue (i.e. there's no cores in middle of the receive function) before removing it.

If the caller needs to know when the context deletion actually occurred, the num_notif and notif_tbl can be used. The given notification event(s) will be sent to given queue(s), when the removal has completed. If such notification is not needed, use 0 as num_notif.

If the queue to be removed is still enabled, it will first be disabled.

Parameters:
eoEO id
queueQueue id to remove
num_notifHow many notification events given, 0 for no notification
notif_tblArray of pairs of event and queue identifiers
Returns:
EM_OK if successful.
See also:
em_eo_add_queue(), em_queue_disable(), em_queue_delete()
em_status_t em_eo_start ( em_eo_t  eo,
em_status_t result,
int  num_notif,
const em_notif_t notif_tbl 
)

Start Execution Object (EO).

Calls global EO start function. If that returns EM_OK, an internal event to trigger local start is sent to all cores belonging to the queue group of this EO. If the global start function does not return EM_OK the local start is not called and event dispatching is not enabled for this EO.

If the caller needs to know when the EO start was actually completed on all cores, the num_notif and notif_tbl can be used. The given notification event(s) will be sent to given queue(s), when the start is completed on all cores. If local start does not exist the notification(s) are sent as the global start returns. If such notification is not needed, use 0 as num_notif.

Parameters:
eoEO id
resultOptional pointer to em_status_t, which gets updated to the return value of the actual EO global start function
num_notifIf not 0, defines the number of events to send as all cores have returned from the start function (in notif_tbl).
notif_tblArray of em_notif_t, the optional notification events (data copied)
Returns:
EM_OK if successful.
See also:
em_start_func_t(), em_start_local_func_t(), em_eo_stop()
em_status_t em_eo_stop ( em_eo_t  eo,
int  num_notif,
const em_notif_t notif_tbl 
)

Stop Execution Object (EO).

Disables event dispatch from all related queues, calls core local stop on all cores and finally calls the global stop function of the EO, when all cores have returned from the (optional) core local stop. Call to the global EO stop is asynchronous and only done, when all cores have completed processing of the receive function and/or core local stop. This guarantees no core is accessing EO data during EO global stop function.

This function returns immediately.

If the caller needs to know when the EO stop was actually completed, the num_notif and notif_tbl can be used. The given notification event(s) will be sent to given queue(s), when the stop actually completes. If such notification is not needed, use 0 as num_notif.

Parameters:
eoEO id
num_notifHow many notification events given, 0 for no notification
notif_tblArray of pairs of event and queue identifiers
Returns:
EM_OK if successful.
See also:
em_stop_func_t(), em_stop_local_func_t(), em_eo_start()
em_status_t em_eo_unregister_error_handler ( em_eo_t  eo)

Unregister EO specific error handler.

Removes previously registered EO specific error handler.

Parameters:
eoEO id
Returns:
EM_OK if successful.
void em_error ( em_status_t  error,
em_escope_t  escope,
  ... 
)

Report an error.

Reported errors are handled by the appropriate (EO specific or the global) error handler.

Depending on the error/scope/implementation, the function call may not return.

Parameters:
errorError code
escopeError scope. Identifies the scope for interpreting the error code and variable arguments.
...Variable number and type of arguments
See also:
em_register_error_handler(), em_error_handler_t()
int em_error_format_string ( char *  str,
size_t  size,
em_eo_t  eo,
em_status_t  error,
em_escope_t  escope,
va_list  args 
)

Format error string

Creates an implementation dependent error report string from EM internal errors.

Parameters:
strOutput string pointer
sizeMaximum string lenght in characters
eoEO id
errorError code (EM internal)
escopeError scope (EM internal)
argsVariable arguments
Returns:
Output string length
em_status_t em_event_group_apply ( em_event_group_t  group,
int  count,
int  num_notif,
const em_notif_t notif_tbl 
)

Apply event group configuration.

The function sets (or resets) the event count and notification parameters for the event group. After it returns events sent to the group are counted against the (updated) count. Notification events are sent when all (counted) events have been processed. A new apply call is needed to reset the event group (counting).

Parameters:
groupGroup id
countNumber of events in the group
num_notifNumber of noticifation events to send
notif_tblTable of notifications (events and target queues)
Returns:
EM_OK if successful.
See also:
em_event_group_create(), em_send_group()
em_event_group_t em_event_group_create ( void  )

Create new event group id for fork-join.

Returns:
New event group id or EM_EVENT_GROUP_UNDEF
See also:
em_event_group_delete(), em_event_group_apply()
em_event_group_t em_event_group_current ( void  )

Current event group

Returns the event group of the currently received event or EM_EVENT_GROUP_UNDEF if the current event does not belong into any event group. Current group is needed when sending new events into the group.

Returns:
Current event group id or EM_EVENT_GROUP_UNDEF
See also:
em_event_group_create()
em_status_t em_event_group_delete ( em_event_group_t  event_group)

Delete (unallocate) an event group id

An event group must not be deleted before it has been completed (notifications sent) or canceled.

Parameters:
event_groupEvent group to delete
Returns:
EM_OK if successful.
See also:
em_event_group_create()
em_status_t em_event_group_increment ( int  count)

Increment event group count

Increments event count of the current event group. Enables sending new events into the current group. Must be called before sending. Note that event count cannot be decremented.

Parameters:
countNumber of events to add in the group
Returns:
EM_OK if successful.
See also:
em_send_group()
void* em_event_pointer ( const em_event_t  event)

Get pointer to event structure

Returns pointer to the event structure or NULL. Event structure is implementation and event type specific. It may be a directly accessible buffer of memory, a descriptor containing a list of buffer pointers, a descriptor of a packet buffer, etc.

Parameters:
eventEvent from receive/alloc
Returns:
Event pointer or NULL
void em_free ( em_event_t  event)

Free an event.

It is assumed the implementation can detect from which memory area/pool the event was originally allocated from.

Free transfers the ownership of the event to the system and application must not touch the event (or related memory buffers) after calling it.

Application must only free events it owns. For example, sender must not free an event after sending it.

Parameters:
eventEvent to be freed
See also:
em_alloc(), em_receive_func_t()
em_event_type_t em_get_type_major ( em_event_type_t  type)

Get major event type.

Event type includes major and minor part. This function returns the major part. It can be compared against enumeration em_event_type_major_e.

Parameters:
typeEvent type
Returns:
Major event type

em_event_type_t em_get_type_minor ( em_event_type_t  type)

Get minor event type.

Event type includes major and minor part. This function returns the minor part. It can be compared against the enumeration specified by the major part.

EM_EVENT_TYPE_SW_DEFAULT is reserved for (SW) events that are generic and directly accessible buffers of memory.

Parameters:
typeEvent type
Returns:
Minor event type

em_queue_t em_queue_create ( const char *  name,
em_queue_type_t  type,
em_queue_prio_t  prio,
em_queue_group_t  group 
)

Create a new queue with a dynamic queue id.

The given name string is copied to EM internal data structure. The maximum string length is EM_QUEUE_NAME_LEN.

Parameters:
nameQueue name for debugging purposes (optional, NULL ok)
typeQueue scheduling type
prioQueue priority
groupQueue group for this queue
Returns:
New queue id or EM_QUEUE_UNDEF on an error
See also:
em_queue_group_create(), em_queue_delete()
em_status_t em_queue_create_static ( const char *  name,
em_queue_type_t  type,
em_queue_prio_t  prio,
em_queue_group_t  group,
em_queue_t  queue 
)

Create a new queue with a static queue id.

Note, that system may have limited amount of static identifiers, so unless really needed use dynamic queues instead. The range of static identifiers is system dependent, but macros EM_QUEUE_STATIC_MIN and EM_QUEUE_STATIC_MAX can be used to abstract, i.e. use EM_QUEUE_STATIC_MIN+x for the application.

The given name string is copied to EM internal data structure. The maximum string length is EM_QUEUE_NAME_LEN.

Parameters:
nameQueue name for debugging purposes (optional, NULL ok)
typeQueue scheduling type
prioQueue priority
groupQueue group for this queue
queueRequested queue id from the static range
Returns:
EM_OK if successful.
See also:
em_queue_group_create(), em_queue_delete()
em_status_t em_queue_delete ( em_queue_t  queue)

Delete a queue.

Unallocates the queue id. NOTE: this is an immediate deletion and can *only* be done after the queue has been removed from scheduling using em_eo_remove_queue() !

Parameters:
queueQueue id to delete
Returns:
EM_OK if successful.
See also:
em_eo_remove_queue(), em_queue_create(), em_queue_create_static()
em_status_t em_queue_disable ( em_queue_t  queue,
int  num_notif,
const em_notif_t notif_tbl 
)

Disable scheduling for the queue.

Note, that this might be an asynchronous operation and actually complete later as other cores may still be handling existing events. If application needs to know exactly when all processing is completed, it can use the notification arguments - the given notification(s) are sent after all cores have completed.

Implicit disable is done for all queues, that are mapped to an EO when it's stop-function is called (via em_eo_stop()).

All events sent to a non-enabled queue may get discarded or held depending on the system. Queue enable/disable is not meant to be used for additional scheduling nor used frequently. Main purpose is to synchronize startup or recovery actions.

Parameters:
queueQueue to disable
num_notifNumber of entries in notif_tbl, use 0 for no notification
notif_tblNotification events to send
Returns:
EM_OK if successful.
See also:
em_eo_stop(), em_queue_disable_all(), em_queue_enable()
em_status_t em_queue_disable_all ( em_eo_t  eo,
int  num_notif,
const em_notif_t notif_tbl 
)

Disable scheduling for all the EO's queues.

Otherwise identical to em_queue_disable().

Parameters:
eoEO id
num_notifNumber of entries in notif_tbl, use 0 for no notification
notif_tblNotification events to send
Returns:
EM_OK if successful.
See also:
em_eo_stop(), em_queue_disable(), em_queue_enable_all()
em_status_t em_queue_enable ( em_queue_t  queue)

Enable event scheduling for the queue.

All events sent to a non-enabled queue may get discarded or held depending on the system. Queue enable/disable is not meant to be used for additional scheduling nor used frequently. Main purpose is to synchronize startup or recovery actions.

Parameters:
queueQueue to enable
Returns:
EM_OK if successful.
See also:
em_eo_start(), em_queue_enable_all(), em_queue_disable()
em_status_t em_queue_enable_all ( em_eo_t  eo)

Enable event scheduling for all the EO's queues.

Otherwise identical to em_queue_enable().

Parameters:
eoEO id
Returns:
EM_OK if successful.
See also:
em_queue_enable(), em_queue_disable_all()
void* em_queue_get_context ( em_queue_t  queue)

Get queue specific (application) context.

Returns the value application has earlier set with em_queue_set_context().

Parameters:
queueQueue which context is requested
Returns:
Queue specific context pointer or NULL on an error
See also:
em_queue_set_context()
em_queue_group_t em_queue_get_group ( em_queue_t  queue)

Get queue's queue group

Parameters:
queueQueue identifier
Returns:
Queue group or EM_QUEUE_GROUP_UNDEF on error.
See also:
em_queue_create(), em_queue_group_create(), em_queue_group_modify()
size_t em_queue_get_name ( em_queue_t  queue,
char *  name,
size_t  maxlen 
)

Get queue name.

Returns the name given to a queue when it was created. A copy of the queue name string (up to 'maxlen' characters) is written to the user given buffer. String is always null terminated even if the given buffer length is less than the name length.

If the queue has no name, function returns 0 and writes empty string.

This is only for debugging purposes.

Parameters:
queueQueue id
nameDestination buffer
maxlenMaximum length (including the terminating '0')
Returns:
Number of characters written (excludes the terminating '0').
See also:
em_queue_create()
em_queue_prio_t em_queue_get_priority ( em_queue_t  queue)

Get queue priority.

Parameters:
queueQueue identifier
Returns:
Priority class or EM_QUEUE_PRIO_UNDEF on an error
See also:
em_queue_create()
em_queue_type_t em_queue_get_type ( em_queue_t  queue)

Get queue type (scheduling mode).

Parameters:
queueQueue identifier
Returns:
Queue type or EM_QUEUE_TYPE_UNDEF on an error
See also:
em_queue_create()
em_queue_group_t em_queue_group_create ( const char *  name,
const em_core_mask_t mask,
int  num_notif,
const em_notif_t notif_tbl 
)

Create a new queue group to control queue to core mapping.

Allocates a new queue group identifier with a given core mask. The group name can have max EM_QUEUE_GROUP_NAME_LEN characters and must be unique since it's used to identify the group. Cores added to the queue group can be changed later with em_queue_group_modify().

This operation may be asynchronous, i.e. the creation may complete well after this function has returned. Provide notification events, if application cares about the actual completion time. EM will send notifications when the operation has completed.

The core mask is visible through em_queue_group_mask() only after the create operation is complete.

Note, that depending on the system, the operation can also happen one core at a time, so an intermediate mask may be active momentarily.

Only manipulate the core mask with the access macros defined in event_machine_core_mask.h as the implementation underneath may change.

EM has a default group (EM_QUEUE_GROUP_DEFAULT) containing all cores. It's named "default", otherwise naming scheme is system specific.

Note, some systems may have a low number of queue groups available.

Attention:
Only call em_queue_enable() after em_queue_group_create() has completed - use notifications to synchronize.
Parameters:
nameQueue group name. Unique name for identifying the group.
maskCore mask for the queue group
num_notifNumber of entries in notif_tbl (use 0 for no notification)
notif_tblArray of notifications to send to signal completion of operation
Returns:
Queue group or EM_QUEUE_GROUP_UNDEF on error.
See also:
em_queue_group_find(), em_queue_group_modify(), em_queue_group_delete()
em_status_t em_queue_group_delete ( em_queue_group_t  group,
int  num_notif,
const em_notif_t notif_tbl 
)

Delete the queue group.

Removes all cores from the queue group and free's the identifier for re-use. All queues in the group must be deleted with em_queue_delete() before deleting the group.

Parameters:
groupQueue group to delete
num_notifNumber of entries in notif_tbl (use 0 for no notification)
notif_tblArray of notifications to send to signal completion of operation
Returns:
EM_OK if successful.
See also:
em_queue_group_create(), em_queue_group_modify(), em_queue_delete()
em_queue_group_t em_queue_group_find ( const char *  name)

Finds queue group by name.

This returns the situation at the moment of the inquiry. If another core is modifying the group at the same time the result may not be up-to-date. Application may need to synchronize group modifications.

Parameters:
nameName of the queue qroup to find
Returns:
Queue group or EM_QUEUE_GROUP_UNDEF on an error
See also:
em_queue_group_create(), em_queue_group_modify()
em_status_t em_queue_group_mask ( em_queue_group_t  group,
em_core_mask_t mask 
)

Get current core mask for a queue group.

This returns the situation at the moment of the inquiry. If another core is modifying the group at the same time the result may not be up-to-date. Application may need to synchronize group modifications.

Parameters:
groupQueue group
maskCore mask for the queue group
Returns:
EM_OK if successful.
See also:
em_queue_group_create(), em_queue_group_modify()
em_status_t em_queue_group_modify ( em_queue_group_t  group,
const em_core_mask_t new_mask,
int  num_notif,
const em_notif_t notif_tbl 
)

Modify core mask of an existing queue group.

The function compares the new core mask to the current mask and changes the queue group to core mapping accordingly.

This operation may be asynchronous, i.e. the change may complete well after this function has returned. Provide notification events, if application cares about the actual completion time. EM will send notifications when the operation has completed.

The new core mask is visible through em_queue_group_mask() only after the modify operation is complete.

Note, that depending on the system, the change can also happen one core at a time, so an intermediate mask may be active momentarily.

Only manipulate core mask with the access macros defined in event_machine_core_mask.h as the implementation underneath may change.

Parameters:
groupQueue group to modify
new_maskNew core mask
num_notifNumber of entries in notif_tbl (use 0 for no notification)
notif_tblArray of notifications to send
Returns:
EM_OK if successful.
See also:
em_queue_group_create(), em_queue_group_find(), em_queue_group_delete(), em_queue_group_mask()
em_status_t em_queue_set_context ( em_queue_t  queue,
const void *  context 
)

Set queue specific (application) context.

This is just a single pointer associated with a queue. Application can use it to access some context data quickly (without a lookup). The context is given as argument for the receive function. EM does not use the value, it just passes it.

Parameters:
queueQueue to which associate the context
contextContext pointer
Returns:
EM_OK if successful.
See also:
em_receive_func_t(), em_queue_get_context()
em_status_t em_register_error_handler ( em_error_handler_t  handler)

Register the global error handler.

The global error handler is called on errors (or em_error() calls) outside of any EO context or if there's no EO specific error handler registered. Note, the function will override any previously registered global error handler.

Parameters:
handlerError handler.
Returns:
EM_OK if successful.
See also:
em_eo_register_error_handler(), em_unregister_error_handler(), em_error_handler_t()
em_status_t em_send ( em_event_t  event,
em_queue_t  queue 
)

Send an event to a queue.

Event must have been allocated with em_alloc(), or received via receive-function. Sender must not touch the event after calling em_send as the ownership is moved to system and then to the receiver. If return status is *not* EM_OK, the ownership has not moved and the application is still responsible for the event (e.g. may free it).

EM does not define guaranteed event delivery, i.e. EM_OK return value only means the event was accepted for delivery. It could still be lost during the delivery (e.g. due to disabled/removed queue, queue or system congestion, etc).

Parameters:
eventEvent to be sent
queueDestination queue
Returns:
EM_OK if successful (accepted for delivery).
See also:
em_alloc()
em_status_t em_send_group ( em_event_t  event,
em_queue_t  queue,
em_event_group_t  group 
)

Send event with group number.

Any valid event and destination queue parameters can be used. Event group id indicates which event group the event belongs to. Event group has to be first created and applied.

Parameters:
eventEvent to send
queueDestination queue
groupEvent group
Returns:
EM_OK if successful.
See also:
em_send(), em_event_group_create(), em_event_group_apply(), em_event_group_increment()
em_status_t em_unregister_error_handler ( void  )

Unregister the global error handler.

Removes previously registered global error handler.

Returns:
EM_OK if successful.
See also:
em_register_error_handler()