1 /* 2 * Copyright (c) 2014-2017, Siemens AG. All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are met: 6 * 7 * 1. Redistributions of source code must retain the above copyright notice, 8 * this list of conditions and the following disclaimer. 9 * 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 15 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 18 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24 * POSSIBILITY OF SUCH DAMAGE. 25 */ 26 27 #ifndef EMBB_BASE_C_CORE_SET_H_ 28 #define EMBB_BASE_C_CORE_SET_H_ 29 30 #include <stdint.h> 31 32 /** 33 * \defgroup C_BASE_CORESET Core Set 34 * 35 * Core sets for thread-to-core affinities 36 * 37 * \ingroup C_BASE 38 * \{ 39 */ 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 46 /** 47 * Opaque type representing a set of processor cores. 48 * 49 * An instance of this type represents a subset of processor cores. Core sets 50 * can be used to set thread-to-core affinities. A core in a core set might 51 * just represent a logical core (hyper-thread), depending on the underlying 52 * hardware. Each core is identified by a unique integer starting with 0. 53 * For example, the cores of a quad-core system are represented by the set 54 * {0,1,2,3}. 55 * 56 * \see embb_core_count_available() 57 */ 58 #ifdef DOXYGEN 59 typedef opaque_type embb_core_set_t; 60 #else 61 typedef struct embb_core_set_t { 62 uint64_t rep; 63 } embb_core_set_t; 64 #endif /* else defined(DOXYGEN) */ 65 66 /** 67 * Returns the number of available processor cores. 68 * 69 * If the processor supports hyper-threading, each hyper-thread is treated as a 70 * separate processor core. 71 * 72 * \return Number of cores including hyper-threads 73 * 74 * \notthreadsafe 75 */ 76 unsigned int embb_core_count_available(); 77 78 /** 79 * Initializes the specified core set. 80 * 81 * The second parameter specifies whether the set is initially empty or contains 82 * all cores. 83 * 84 * \pre \c core_set is not NULL. 85 * 86 * \notthreadsafe 87 */ 88 void embb_core_set_init( 89 embb_core_set_t* core_set, 90 /**< [OUT] Core set to initialize */ 91 int initializer 92 /**< [IN] The set is initially empty if initializer == 0, otherwise it 93 contains all available processor cores. */ 94 ); 95 96 /** 97 * Adds a core to the specified set. 98 * 99 * If the core is already contained in the set, the operation has no effect. 100 * 101 * \pre \c core_set is not NULL and \c core_number is smaller than 102 * embb_core_count_available(). 103 * 104 * \notthreadsafe 105 * \see embb_core_set_remove() 106 */ 107 void embb_core_set_add( 108 embb_core_set_t* core_set, 109 /**< [IN/OUT] Core set to be manipulated */ 110 unsigned int core_number 111 /**< [IN] Number of core to be added. */ 112 ); 113 114 /** 115 * Removes a core from the specified set. 116 * 117 * If the core is not in the set, the operation has no effect. 118 * 119 * \pre \c core_set is not NULL and \c core_number is smaller than 120 * embb_core_count_available(). 121 * 122 * \notthreadsafe 123 * \see embb_core_set_add() 124 */ 125 void embb_core_set_remove( 126 embb_core_set_t* core_set, 127 /**< [IN/OUT] Core set to be manipulated */ 128 unsigned int core_number 129 /**< [IN] Number of core to be removed */ 130 ); 131 132 /** 133 * Determines whether a core is contained in the specified set. 134 * 135 * \pre \c core_set is not NULL and \c core_number is smaller than 136 * embb_core_count_available(). 137 * 138 * \return 0 if the core is not contained in the set, otherwise a number 139 * greater than zero. 140 * \notthreadsafe 141 */ 142 int embb_core_set_contains( 143 const embb_core_set_t* core_set, 144 /**< [IN] Core set */ 145 unsigned int core_number 146 /**< [IN] Number of core */ 147 ); 148 149 /** 150 * Computes the intersection of core \c set1 and \c set2. 151 * 152 * The result is stored in \c set1. 153 * 154 * \pre \c set1 and \c set2 are not NULL. 155 * 156 * \notthreadsafe 157 * \see embb_core_set_union() 158 */ 159 void embb_core_set_intersection( 160 embb_core_set_t* set1, 161 /**< [IN/OUT] First set, gets overwritten by the result */ 162 const embb_core_set_t* set2 163 /**< [IN] Second set */ 164 ); 165 166 /** 167 * Computes the union of core \c set1 and \c set2. 168 * 169 * The result is stored in \c set1. 170 * 171 * \pre \c set1 and \c set2 are not NULL. 172 * 173 * \notthreadsafe 174 * \see embb_core_set_intersection() 175 */ 176 void embb_core_set_union( 177 embb_core_set_t* set1, 178 /**< [IN/OUT] First set */ 179 const embb_core_set_t* set2 180 /**< [IN] Second set */ 181 ); 182 183 /** 184 * Returns the number of cores contained in the specified set. 185 * 186 * \pre \c core_set is not NULL. 187 * 188 * \notthreadsafe 189 * \return Number of cores in \c core_set 190 */ 191 unsigned int embb_core_set_count( 192 const embb_core_set_t* core_set 193 /**< [IN] Core set whose elements are counted */ 194 ); 195 196 #ifdef __cplusplus 197 } /* Close extern "C" { */ 198 #endif 199 200 /** 201 * \} 202 */ 203 204 #endif /* EMBB_BASE_C_CORE_SET_H_ */ 205