event_machine_config.h

Go to the documentation of this file.

/*
 *   Copyright (c) 2012, Nokia Siemens Networks
 *   Copyright (c) 2015-2025, Nokia Solutions and Networks
 *   All rights reserved.
 *
 *   Redistribution and use in source and binary forms, with or without
 *   modification, are permitted provided that the following conditions
 *   are met:
 *
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the copyright holder nor the names of its
 *       contributors may be used to endorse or promote products derived
 *       from this software without specific prior written permission.
 *
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
/**
 * @file
 *
 * Event Machine configuration options
 */
 
#ifndef EVENT_MACHINE_CONFIG_H
#define EVENT_MACHINE_CONFIG_H
 
#pragma GCC visibility push(default)
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifdef EM_64_BIT
/**
 * @page page_version 64-bit version
 * This documentation represent the 64-bit version of Event Machine API.
 * Define EM_64_BIT or EM_32_BIT to select between 64- and 32-bit versions.
 */
#elif defined(EM_32_BIT)
/**
 * @page page_version 32-bit version
 * This documentation represent the 32-bit version of Event Machine API.
 * Define EM_64_BIT or EM_32_BIT to select between 64- and 32-bit versions.
 */
#else
#error Missing architecture definition. Define EM_64_BIT or EM_32_BIT!
/**
 * @page page_version 64/32-bit version not selected
 * This documentation has not selected between 64/32-bit version of
 * the Event Machine API. Some types might be missing.
 * Define EM_64_BIT or EM_32_BIT to select between 64- and 32-bit
 * versions.
 */
#endif
 
/**
 * Support C++ static casts in EM API files
 */
#ifndef __cplusplus
#define EM_STATIC_CAST(type, value)  ((type)(value))
#else
#define EM_STATIC_CAST(type, value)  (static_cast < type > (value))
#endif
 
/**
 * Support C++ reinterpret casts in EM API files
 */
#ifndef __cplusplus
#define EM_REINTERPRET_CAST(type, value)  ((type)(value))
#else
#define EM_REINTERPRET_CAST(type, value)  (reinterpret_cast < type > (value))
#endif
 
/**
 * Compile-time upper limit for the maximum number of EM-cores.
 *
 * Sets the maximum number of EM-cores that can be requested to be supported by
 * EM at startup, i.e. sets a limit for the em_conf_t::core_count parameter.
 * This is a compile time upper limit for the number of EM-cores of type
 * EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL.
 */
#ifndef EM_MAX_CORES
#define EM_MAX_CORES  64
#endif
 
/**
 * Max number of EM external threads/processes supported,
 * i.e. EM external threads/processes of type EM_CORE_TYPE_EXTERNAL.
 */
#ifndef EM_MAX_EXTTHRS
#define EM_MAX_EXTTHRS  32
#endif
 
/**
 * Maximum number of EM atomic groups
 */
#ifndef EM_MAX_ATOMIC_GROUPS
#define EM_MAX_ATOMIC_GROUPS  128
#endif
 
/**
 * Max atomic group name length
 */
#ifndef EM_ATOMIC_GROUP_NAME_LEN
#define EM_ATOMIC_GROUP_NAME_LEN  32
#endif
 
/**
 * Maximum total number of EOs
 */
#ifndef EM_MAX_EOS
#define EM_MAX_EOS  512
#endif
 
/**
 * Maximum EO name string length
 */
#ifndef EM_EO_NAME_LEN
#define EM_EO_NAME_LEN  32
#endif
 
/**
 * Maximum number of event groups
 */
#ifndef EM_MAX_EVENT_GROUPS
#define EM_MAX_EVENT_GROUPS  1024
#endif
 
/**
 * Maximum number of notifications
 */
#ifndef EM_EVENT_GROUP_MAX_NOTIF
#define EM_EVENT_GROUP_MAX_NOTIF  6
#endif
 
/**
 * Maximum queue name string length
 */
#ifndef EM_QUEUE_NAME_LEN
#define EM_QUEUE_NAME_LEN  32
#endif
 
/**
 * Maximum number of output queues
 */
#ifndef EM_MAX_OUTPUT_QUEUES
#define EM_MAX_OUTPUT_QUEUES  64
#endif
 
/**
 * Number of queue scheduling priorities, normal default is 8.
 * @see em_queue_prio_e
 */
#ifndef EM_QUEUE_PRIO_NUM
#define EM_QUEUE_PRIO_NUM  8
#endif
 
/**
 * Determines the EM queue handles range to use.
 * Note: value must be >= 1 and <= 'UINT16_MAX - em_queue_max_num() + 1'
 *   idx     EM Queue handle
 *    0   ->   0 + offset
 *    1   ->   1 + offset
 *   ...
 *  max-1 ->   max-1 + offset
 */
#ifndef EM_QUEUE_RANGE_OFFSET
#define EM_QUEUE_RANGE_OFFSET  1
#endif
 
/**
 * The maximum number of aggregator queues that can be created for a single
 * EM queue. An aggregator queue allows multiple events to be aggregated into
 * a vector event before enqueueing to the parent queue.
 * @see em_queue_aggr_conf_t and em_queue_param_t.
 *
 * @note The actual maximum number of aggregator queues that can be created for
 *       a single EM queue is determined by the minimum of this value and the
 *       ODP implementation limits for event aggregators, which can be queried
 *       with odp_queue_capability() for plain queues or with
 *       odp_schedule_capability() for scheduled queues, and are checked by EM
 *       at queue creation time.
 */
#ifndef EM_QUEUE_MAX_AGGR
#define EM_QUEUE_MAX_AGGR  4
#endif
 
/**
 * Maximum number of EM queue groups
 */
#ifndef EM_MAX_QUEUE_GROUPS
#define EM_MAX_QUEUE_GROUPS  (EM_MAX_CORES + 64)
#endif
 
/**
 * Default queue group for EM
 */
#define EM_QUEUE_GROUP_DEFAULT  EM_REINTERPRET_CAST(em_queue_group_t, EM_MAX_QUEUE_GROUPS)
 
/**
 * Max queue group name length
 */
#ifndef EM_QUEUE_GROUP_NAME_LEN
#define EM_QUEUE_GROUP_NAME_LEN  32
#endif
 
/**
 * The name of the EM default queue group
 */
#define EM_QUEUE_GROUP_DEFAULT_NAME  "default"
 
/**
 * Base-name of EM core-specific queue groups (one per EM-core),
 * if created by EM (note: see the EM runtime config file for option).
 * The full queue group name for a single-core group is: "core" + "%d",
 * which gives "core0", "core1", ... "core99", ...
 * EM earlier relied on these queue groups for internal core specific
 * messaging and also allowed applications to use them. Currently EM
 * does not internally need these groups but will create them based on
 * an EM config file option for applications relying on their existence.
 *
 * Example: Find the queue group that includes only this core.
 *          (EM single-core queue group creation enabled in config file)
 * @code
 *      char qgrp_name[EM_QUEUE_GROUP_NAME_LEN];
 *      int core = em_core_id();
 *      em_queue_group_t qgrp_core;
 *
 *      snprintf(qgrp_name, sizeof(qgrp_name), "%s%d",
 *               EM_QUEUE_GROUP_CORE_BASE_NAME, core);
 *      ...
 *      qgrp_core = em_queue_group_find(qgrp_name);
 *      ...
 * @endcode
 */
#define EM_QUEUE_GROUP_CORE_BASE_NAME  "core"
 
/**
 * Maximum number of EM pools
 */
#ifndef EM_CONFIG_POOLS
#define EM_CONFIG_POOLS  16
#endif
 
/**
 * Define the EM default event pool
 */
#define EM_POOL_DEFAULT  EM_REINTERPRET_CAST(em_pool_t, 1)
 
/**
 * Max event pool name length
 */
#ifndef EM_POOL_NAME_LEN
#define EM_POOL_NAME_LEN  32
#endif
 
/**
 * @brief The maximum number of subpools in each EM pool.
 *        The subpool is a pool with buffers of only one size.
 */
#ifndef EM_MAX_SUBPOOLS
#define EM_MAX_SUBPOOLS  4
#endif
 
/**
 * The name of the EM default event pool
 */
#define EM_POOL_DEFAULT_NAME  "default"
 
/**
 * Reserve for EM pool subpool statistic internal use
 */
#define EM_POOL_SUBPOOL_STAT_INTERNAL  129
 
/**
 * The maximum size in bytes that can be configured for the event user area.
 * The user area is located outside of the payload in the event metadata (hdr)
 * and can be used to store event related state without affecting the payload.
 */
#ifndef EM_EVENT_USER_AREA_MAX_SIZE
#define EM_EVENT_USER_AREA_MAX_SIZE  256
#endif
 
/**
 * The maximum number of events to request from the scheduler and then
 * dispatch in one burst.
 *
 * @note the odp sched burst size is determined by the odp-config-file values:
 *       sched_basic: burst_size_default[...] and burst_size_max[...]
 */
#ifndef EM_SCHED_MULTI_MAX_BURST
#define EM_SCHED_MULTI_MAX_BURST  32
#endif
 
/**
 * The maximum number of events from an atomic group to dispatch in one burst.
 */
#ifndef EM_SCHED_AG_MULTI_MAX_BURST
#define EM_SCHED_AG_MULTI_MAX_BURST  32
#endif
 
/**
 * The maximum number of events from a local queue (EM_QUEUE_TYPE_LOCAL) to
 * dispatch in one burst.
 */
#ifndef EM_QUEUE_LOCAL_MULTI_MAX_BURST
#define EM_QUEUE_LOCAL_MULTI_MAX_BURST  32
#endif
 
/**
 * The default maximum number of events passed to the EO's multi-event
 * receive function (when the EO has been created with em_eo_create_multircv()).
 * This value is used by EM as a default if the user does not specify
 * a value (i.e. gives '0') for 'em_eo_multircv_param_t::max_events' when
 * calling em_eo_create_multircv()
 */
#ifndef EM_EO_MULTIRCV_MAX_EVENTS
#define EM_EO_MULTIRCV_MAX_EVENTS  32
#endif
 
/**
 * Maximum number of EM callbacks/hooks that can be registered.
 *
 * The user may register up to the number 'EM_CALLBACKS_MAX' of each
 * callback/hook. API-hooks, such as the alloc-, free- and send-hook, or
 * dispatcher callbacks, such as the enter- and exit-callbacks as well as
 * idle-hooks can be registered each up to this limit.
 */
#ifndef EM_CALLBACKS_MAX
#define EM_CALLBACKS_MAX  8
#endif
 
/**
 *   '0': allow EM to buffer events sent to output queues before calling the
 *        user provided output callback to improve throughput
 *   '1': each em_send/_multi() will immediately call the user provided output
 *        queue callback with no EM internal buffering
 * This define mostly affects behaviour and performance when sending events from
 * an ordered scheduling context where EM needs to ensure event ordering before
 * calling the user provided output callback function.
 */
#ifndef EM_OUTPUT_QUEUE_IMMEDIATE
#define EM_OUTPUT_QUEUE_IMMEDIATE  0
#endif
 
/*
 * Enable dispatcher callback functions
 */
#ifndef EM_DISPATCH_CALLBACKS_ENABLE
#define EM_DISPATCH_CALLBACKS_ENABLE  1
#endif
 
/**
 * Enable the usage of EM API hooks
 *
 * User provided API hook functions can be provided via em_init(). EM will
 * call the given hooks each time the corresponding API function is called.
 */
#ifndef EM_API_HOOKS_ENABLE
#define EM_API_HOOKS_ENABLE  1
#endif
 
/**
 * Guards event groups in undefined and error situations
 *
 * Excess and aborted group events don't belong to a valid group when received.
 * Most event group APIs check if the core local event group has expired during
 * receive function. Impacts performance when event groups are used.
 */
#ifndef EM_EVENT_GROUP_SAFE_MODE
#define EM_EVENT_GROUP_SAFE_MODE  1
#endif
 
/**
 * Enable the usage of EM idle hooks
 *
 * User provided idle hook functions can be provided via em_conf_t::idle_hooks
 * when calling em_init() or via their register functions. EM will call the
 * given hooks in the dispatcher depending on whether there are events to be
 * processed by the core.
 *
 * @note em-odp: the 'EM_IDLE_HOOKS_ENABLE' value is set/changed by a
 *               command-line option to the 'configure' script, e.g.:
 *               $build> ../configure ... --enable-idle-hooks[=yes|no]
 */
#ifndef EM_IDLE_HOOKS_ENABLE
#define EM_IDLE_HOOKS_ENABLE  1
#endif
 
/**
 * Enable the EM dispatcher/scheduler to set the time (in ns) the scheduler
 * should wait for events before returning (when no events are immediately
 * available). Waiting for events, rather than busy-waiting, might save power.
 * The EM dispatch loop will call odp_schedule_multi(..., sched_wait_ns, ...)
 * when EM_SCHED_WAIT_ENABLE=1.
 * The EM dispatch loop will call odp_schedule_multi_no_wait()
 * when EM_SCHED_WAIT_ENABLE=0.
 * The 'sched_wait_ns' value can be set via an EM config file option:
 * config/em-odp.conf: dispatch.sched_wait_ns = value
 *
 * @note em-odp: the 'EM_SCHED_WAIT_ENABLE' value is set/changed by a
 *               command-line option to the 'configure' script, e.g.:
 *               $build> ../configure ... --enable-sched-wait[=yes|no]
 */
#ifndef EM_SCHED_WAIT_ENABLE
#define EM_SCHED_WAIT_ENABLE  1
#endif
 
/**
 * EM Error check level
 *
 * Conditionally compiled error checking level, range 0...3
 * Level 0 does not do any runtime argument checking (be careful!)
 * Level 1 adds minimum checks
 * Level 2 adds most checks except the slowest ones
 * Level 3 adds all checks and gives lowest performance
 *
 * @note em-odp: the 'EM_CHECK_LEVEL' value is set/changed by a command-line
 *               option to the 'configure' script, e.g.:
 *               $build> ../configure ... --enable-check-level=3
 */
#ifndef EM_CHECK_LEVEL
#define EM_CHECK_LEVEL  3
#endif
 
/**
 * Event State Verification (ESV)
 *
 * '0': disabled
 * '1': enabled - event state is verified when the event is passed from EM to
 *                the user (e.g. dispatch) and from the user to EM (e.g. send)
 *                to catch illegal usage patterns like double-send, double-free,
 *                usage-after-send etc.
 *
 * Also see the config/em-odp.conf file for ESV runtime options!
 *
 * @note em-odp: the 'EM_ESV_ENABLE' value is set/changed by a command-line
 *               option to the 'configure' script, e.g.:
 *               $build> ../configure ... --enable-esv[=yes|no]
 */
#ifndef EM_ESV_ENABLE
#define EM_ESV_ENABLE  1
#endif
 
/**
 * EM debug printouts - enable/disable all debug printouts
 *
 * '0': disabled
 * '1': enabled
 *
 * The EM_DEBUG_PRINT_ALL define is a convenience define that, if set via
 * 'configure --enable-debug-print/-all', will set all individual debug print
 * options to 'enabled' (1).
 * Summary of configure interactions:
 *   Default: EM_DEBUG_PRINT_ALL   = 0,
 *            Subflags:
 *            EM_DEBUG_PRINT_TIMER = 0,
 *            EM_DEBUG_PRINT_BASE  = 0
 *   --enable-debug-print-all (alias: --enable-debug-print): _ALL=1 seeds
 *     _TIMER=1 & _BASE=1 (unless individually disabled).
 *   --disable-debug-print-all: _ALL=0, subflags keep explicitly set values,
 *     otherwise they are set to 0.
 *   --enable-debug-print-timer/base: set that subflag to 1 (_ALL unchanged).
 *   --disable-debug-print-timer/base: set that subflag to 0 and force _ALL=0.
 *   Disabling any subflag after enabling _ALL clears _ALL (non-uniform state).
 */
#ifndef EM_DEBUG_PRINT_ALL
#define EM_DEBUG_PRINT_ALL  0
#endif
 
/**
 * EM debug printouts - enable/disable timer debug printouts
 *
 * '0': disabled
 * '1': enabled
 *
 * The 'EM_DEBUG_PRINT_TIMER' value is set/changed by a command-line option to
 * the 'configure' script, e.g.:
 * $build> ../configure ... --enable-debug-print-timer[=yes|no]
 *
 * Note: seeded to 1 by --enable-debug-print/-all unless overridden.
 */
#ifndef EM_DEBUG_PRINT_TIMER
#define EM_DEBUG_PRINT_TIMER  0
#endif
 
/**
 * EM debug printouts - enable/disable base level debug printouts
 *
 * '0': disabled
 * '1': enabled
 *
 * The 'EM_DEBUG_PRINT_BASE' value is set/changed by a command-line option to
 * the 'configure' script, e.g.:
 * $build> ../configure ... --enable-debug-print-base[=yes|no]
 *
 * Note: seeded to 1 by --enable-debug-print/-all unless overridden.
 */
#ifndef EM_DEBUG_PRINT_BASE
#define EM_DEBUG_PRINT_BASE  0
#endif
 
/**
 * Debug Timestamps for timing analysis.
 *
 * Enabling may reduce performance but allows to trace dispatcher timings.
 * Timestamps are per dispatcher (thread local).
 *
 * '0': disabled (default)
 * '1': enabled, lower overhead but potentially inaccurate (no HW barriers)
 * '2': enabled, strict version with full HW barriers
 *
 * Use value 1 for lower overhead timestamps and value 2 for strict timestamp
 * with HW barriers.
 *
 * The 'EM_DEBUG_TIMESTAMP_ENABLE' value is set/changed by a command-line option
 * to the 'configure' script, e.g.:
 * $build> ../configure ... --enable-debug-timestamps=0...2
 *
 * @see event_machine_helper.h
 */
#ifndef EM_DEBUG_TIMESTAMP_ENABLE
#define EM_DEBUG_TIMESTAMP_ENABLE  0
#endif
 
#ifdef __cplusplus
}
#endif
 
#pragma GCC visibility pop
#endif /* EVENT_MACHINE_CONFIG_H */