event_machine_core_mask.h

Go to the documentation of this file.

/*
 *   Copyright (c) 2015-2026, 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 core mask manipulation APIs
 */
 
#ifndef EVENT_MACHINE_CORE_MASK_H
#define EVENT_MACHINE_CORE_MASK_H
 
#pragma GCC visibility push(default)
 
#include <event_machine/api/event_machine_config.h>
#include <event_machine/api/event_machine_types.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/**
 * EM 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.
 *
 * Use the functions in event_machine_core_mask.h to manipulate the
 * core masks.
 *
 * @see em_queue_group_create()
 */
typedef struct {
        odp_cpumask_t odp_cpumask;
} em_core_mask_t;
 
/** Number of chars needed to hold core mask as a string:'0xcoremask' + '\0' */
#define EM_CORE_MASK_STRLEN  ((EM_MAX_CORES + 3) / 4 + 3)
 
/**
 * Zero the whole mask.
 *
 * @param[out] mask  Core mask to zero (clear)
 */
void em_core_mask_zero(em_core_mask_t *mask);
 
/**
 * Set a bit in the mask.
 *
 * @param      core  Core id
 * @param[out] mask  Core mask
 */
void em_core_mask_set(int core, em_core_mask_t *mask);
 
/**
 * Clear a bit in the mask.
 *
 * @param      core  Core id
 * @param[out] mask  Core mask
 */
void em_core_mask_clr(int core, em_core_mask_t *mask);
 
/**
 * Test if a bit is set in the mask.
 *
 * @param core  Core id
 * @param mask  Core mask
 *
 * @return Non-zero if core id is set in the mask
 */
int em_core_mask_isset(int core, const em_core_mask_t *mask);
 
/**
 * Test if the mask is all zero.
 *
 * @param mask  Core mask
 *
 * @return Non-zero if the mask is all zero
 */
int em_core_mask_iszero(const em_core_mask_t *mask);
 
/**
 * Test if two masks are equal
 *
 * @param mask1  First core mask
 * @param mask2  Second core mask
 *
 * @return Non-zero if the two masks are equal
 */
int em_core_mask_equal(const em_core_mask_t *mask1,
                       const em_core_mask_t *mask2);
 
/**
 * Set a range (0...count-1) of bits in the mask.
 *
 * @param      count  Number of bits to set
 * @param[out] mask   Core mask
 */
void em_core_mask_set_count(int count, em_core_mask_t *mask);
 
/**
 * Copy core mask
 *
 * @param[out] dst  Destination core mask
 * @param      src  Source core mask
 */
void em_core_mask_copy(em_core_mask_t *dst, const em_core_mask_t *src);
 
/**
 * Count the number of bits set in the mask.
 *
 * @param mask  Core mask
 *
 * @return Number of bits set
 */
int em_core_mask_count(const em_core_mask_t *mask);
 
/**
 * Set specified bits from 'bits[]' in core mask.
 *
 * core 0:  bits[0] = 0x1 (len = 1)
 * core 1:  bits[0] = 0x2 (len = 1)
 * ...
 * core 64: bits[0] = 0x0, bits[1] = 0x1 (len = 2)
 * core 65: bits[0] = 0x0, bits[1] = 0x2 (len = 2)
 * ...
 * cores 0-127: bits[0]=0xffffffffffffffff, bits[1]=0xffffffffffffffff (len=2)
 * ...
 * @param      bits  Array of uint64_t:s with the bits to set in the core mask
 * @param      len   Number of array elements in bits[].
 * @param[out] mask  Core mask to set.
 *
 * @note bits ar 'or'ed into mask, so any previously set bits will remain set.
 */
void em_core_mask_set_bits(const uint64_t bits[], int len,
                           em_core_mask_t *mask);
 
/**
 * Get core mask, stored in a uint64_t array for the user
 *
 * core 0:  bits[0] = 0x1 (len = 1)
 * core 1:  bits[0] = 0x2 (len = 1)
 * ...
 * core 64: bits[0] = 0x0, bits[1] = 0x1 (len = 2)
 * core 65: bits[0] = 0x0, bits[1] = 0x2 (len = 2)
 * ...
 * cores 0-127: bits[0]=0xffffffffffffffff, bits[1]=0xffffffffffffffff (len=2)
 * ...
 * @param[out] bits  Array of uint64_t:s that the core mask will be stored in.
 * @param      len   Number of array elements in bits[].
 * @param      mask  Core mask to get bits from.
 *
 * @return The number of uint64_t:s written into bits[].
 */
int em_core_mask_bits(uint64_t bits[/*out*/], int len,
                      const em_core_mask_t *mask);
 
/* Backwards compatible naming ("get") */
#define em_core_mask_get_bits em_core_mask_bits
 
/**
 * Set bits in a mask according to a given string.
 *
 * @param      mask_str  String containing '0xcoremask' to set
 * @param[out] mask      Core mask to set
 *
 * @return Zero (0) on success, non-zero on error.
 *
 * @note bits ar 'or'ed into mask, so any previously set bits will remain set.
 */
int em_core_mask_set_str(const char *mask_str, em_core_mask_t *mask);
 
/**
 * Get core mask in string format
 *
 * @param[out] mask_str  String into which the core mask will be printed
 * @param      len       Length of 'mask_str'
 * @param      mask      Core mask to convert to string format
 */
void em_core_mask_tostr(char *mask_str /*out*/, int len,
                        const em_core_mask_t *mask);
 
/**
 * Return the index (position) of the Nth set bit in the core mask
 *
 * @param n     Nth set bit, note n=1 means first set bit, n=[1...MaxCores]
 * @param mask  Core mask
 *
 * @return  Index of the Nth set bit
 * @retval  <0 if no Nth bit set
 */
int em_core_mask_idx(int n, const em_core_mask_t *mask);
 
/**
 * Return the index of the first set bit in the core mask
 *
 * @param mask    Core mask
 *
 * @return  Index of the first set bit
 * @retval  <0 if no bit set
 */
int em_core_mask_first(const em_core_mask_t *mask);
 
/**
 * Return the index of the last set bit in the core mask
 *
 * @param mask    Core mask
 *
 * @return Index of the last set bit
 * @retval <0 if no bit set
 */
int em_core_mask_last(const em_core_mask_t *mask);
 
/**
 * Return the index of the next set bit in the core mask
 *
 * Finds the next index in the core mask, starting after the index passed.
 * Use with em_core_mask_first() to traverse a core mask, e.g.
 *
 * int idx = em_core_mask_first(&mask);
 * while (idx >= 0) {
 *     ...
 *     idx = em_core_mask_next(&mask, idx);
 * }
 *
 * @param mask  Core mask
 * @param idx   Index after which to look for the next set bit
 *
 * @return Index of the next set bit
 * @retval <0 if no next set bit found
 *
 * @see em_core_mask_first()
 */
int em_core_mask_next(const em_core_mask_t *mask, int idx);
 
/**
 * Bitwise AND operation on two masks, store the result in 'dst'
 *
 * dst = src1 & src2
 *
 * @param[out] dst   Destination core mask, result is stored here
 * @param      src1  Source mask #1
 * @param      src2  Source mask #2
 */
void em_core_mask_and(em_core_mask_t *dst, const em_core_mask_t *src1,
                      const em_core_mask_t *src2);
 
/**
 * Bitwise OR operation on two masks, store the result in 'dst'
 *
 * dst = src1 | src2
 *
 * @param[out] dst   Destination core mask, result is stored here
 * @param      src1  Source mask #1
 * @param      src2  Source mask #2
 */
void em_core_mask_or(em_core_mask_t *dst, const em_core_mask_t *src1,
                     const em_core_mask_t *src2);
 
/**
 * Bitwise XOR operation on two masks, store the result in 'dst'
 *
 * dst = src1 ^ src2
 *
 * @param[out] dst   Destination core mask, result is stored here
 * @param      src1  Source mask #1
 * @param      src2  Source mask #2
 */
void em_core_mask_xor(em_core_mask_t *dst, const em_core_mask_t *src1,
                      const em_core_mask_t *src2);
 
#ifdef __cplusplus
}
#endif
 
#pragma GCC visibility pop
#endif /* EVENT_MACHINE_CORE_MASK_H */