1 /* Copyright 2013 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 /* common.h - Common includes for Chrome EC */ 7 8 #ifndef __CROS_EC_COMMON_H 9 #define __CROS_EC_COMMON_H 10 11 #include <stdbool.h> 12 #include <stddef.h> 13 #include <stdint.h> 14 #include <inttypes.h> 15 #include "compile_time_macros.h" 16 17 /* 18 * Macros to concatenate 2 - 4 tokens together to form a single token. 19 * Multiple levels of nesting are required to convince the preprocessor to 20 * expand currently-defined tokens before concatenation. 21 * 22 * For example, if you have 23 * #define FOO 1 24 * #define BAR1 42 25 * Then 26 * #define BAZ CONCAT2(BAR, FOO) 27 * Will evaluate to BAR1, which then evaluates to 42. 28 */ 29 #define CONCAT_STAGE_1(w, x, y, z) w ## x ## y ## z 30 #define CONCAT2(w, x) CONCAT_STAGE_1(w, x, , ) 31 #define CONCAT3(w, x, y) CONCAT_STAGE_1(w, x, y, ) 32 #define CONCAT4(w, x, y, z) CONCAT_STAGE_1(w, x, y, z) 33 34 /* 35 * Macros to turn the argument into a string constant. 36 * 37 * Compared to directly using the preprocessor # operator, this 2-stage macro 38 * is safe with regards to using nested macros and defined arguments. 39 */ 40 #define STRINGIFY0(name) #name 41 #define STRINGIFY(name) STRINGIFY0(name) 42 43 /* Macros to access registers */ 44 #define REG32_ADDR(addr) ((volatile uint32_t *)(addr)) 45 #define REG16_ADDR(addr) ((volatile uint16_t *)(addr)) 46 #define REG8_ADDR(addr) ((volatile uint8_t *)(addr)) 47 48 #define REG32(addr) (*REG32_ADDR(addr)) 49 #define REG16(addr) (*REG16_ADDR(addr)) 50 #define REG8(addr) (*REG8_ADDR(addr)) 51 52 /* 53 * Define __aligned(n) and __packed if someone hasn't beat us to it. Linux 54 * kernel style checking prefers these over __attribute__((packed)) and 55 * __attribute__((aligned(n))). 56 */ 57 #ifndef __aligned 58 #define __aligned(n) __attribute__((aligned(n))) 59 #endif 60 61 #ifndef __packed 62 #define __packed __attribute__((packed)) 63 #endif 64 65 /* 66 * Define __unused in the same manner. 67 */ 68 #ifndef __unused 69 #define __unused __attribute__((unused)) 70 #endif 71 72 /* 73 * __maybe_unused is equivalent to the Linux kernel definition, so we 74 * can follow the Kernel style guide more closely. 75 * 76 * An example use case is a function which is only used under certain 77 * CONFIG options. 78 */ 79 #ifndef __maybe_unused 80 #define __maybe_unused __attribute__((unused)) 81 #endif 82 83 /* 84 * externally_visible is required by GCC to avoid kicking out memset. 85 */ 86 #ifndef __visible 87 #ifndef __clang__ 88 #define __visible __attribute__((externally_visible)) 89 #else 90 #define __visible __attribute__((used)) 91 #endif 92 #endif 93 94 /* 95 * Force the toolchain to keep a symbol even with Link Time Optimization 96 * activated. 97 * 98 * Useful for C functions called only from assembly or through special sections. 99 */ 100 #ifndef __keep 101 #define __keep __attribute__((used)) __visible 102 #endif 103 104 /* 105 * Place the object in the .bss.slow region. 106 * 107 * On boards with unoptimized RAM there is no penalty and it simply is appended 108 * to the .bss section. 109 */ 110 #ifndef __bss_slow 111 #define __bss_slow __attribute__((section(".bss.slow"))) 112 #endif 113 114 /* gcc does not support __has_feature */ 115 #ifndef __has_feature 116 #define __has_feature(x) 0 117 #endif 118 119 /* 120 * Use this to prevent AddressSanitizer from putting guards around some global 121 * variables (e.g. hook/commands "arrays" that are put together at link time). 122 */ 123 #ifndef __no_sanitize_address 124 #if __has_feature(address_sanitizer) 125 #define __no_sanitize_address __attribute__((no_sanitize("address"))) 126 #else 127 #define __no_sanitize_address 128 #endif 129 #endif 130 131 #ifndef __warn_unused_result 132 #define __warn_unused_result __attribute__((warn_unused_result)) 133 #endif 134 135 #ifdef TEST_PINWEAVER_FUZZ 136 /** 137 * Workaround: Clang incorrectly handles profiling information 138 * used for fuzzing with __attribute__((always_inline)). 139 */ 140 #undef __always_inline 141 #define __always_inline static inline 142 #else 143 #ifndef __always_inline 144 #define __always_inline __inline __attribute__((always_inline)) 145 #endif 146 #endif 147 148 /* 149 * Macros for combining bytes into larger integers. _LE and _BE signify little 150 * and big endian versions respectively. 151 */ 152 #define UINT16_FROM_BYTES(lsb, msb) ((lsb) | (msb) << 8) 153 #define UINT16_FROM_BYTE_ARRAY_LE(data, lsb_index) \ 154 UINT16_FROM_BYTES((data)[(lsb_index)], (data)[(lsb_index) + 1]) 155 #define UINT16_FROM_BYTE_ARRAY_BE(data, msb_index) \ 156 UINT16_FROM_BYTES((data)[(msb_index) + 1], (data)[(msb_index)]) 157 158 #define UINT32_FROM_BYTES(lsb, byte1, byte2, msb) \ 159 ((lsb) | (byte1) << 8 | (byte2) << 16 | (msb) << 24) 160 #define UINT32_FROM_BYTE_ARRAY_LE(data, lsb_index) \ 161 UINT32_FROM_BYTES((data)[(lsb_index)], (data)[(lsb_index) + 1], \ 162 (data)[(lsb_index) + 2], (data)[(lsb_index) + 3]) 163 #define UINT32_FROM_BYTE_ARRAY_BE(data, msb_index) \ 164 UINT32_FROM_BYTES((data)[(msb_index) + 3], (data)[(msb_index) + 2], \ 165 (data)[(msb_index) + 1], (data)[(msb_index)]) 166 167 /* There isn't really a better place for this */ 168 #define C_TO_K(temp_c) ((temp_c) + 273) 169 #define K_TO_C(temp_c) ((temp_c) - 273) 170 #define CELSIUS_TO_DECI_KELVIN(temp_c) ((temp_c) * 10 + 2731) 171 #define DECI_KELVIN_TO_CELSIUS(temp_dk) ((temp_dk - 2731) / 10) 172 173 /* Calculate a value with error margin considered. For example, 174 * TARGET_WITH_MARGIN(X, 5) returns X' where X' * 100.5% is almost equal to 175 * but does not exceed X. */ 176 #define TARGET_WITH_MARGIN(target, tenths_percent) \ 177 (((target) * 1000) / (1000 + (tenths_percent))) 178 179 /* Include top-level configuration file */ 180 #include "config.h" 181 182 /* Canonical list of module IDs */ 183 #include "module_id.h" 184 185 /* List of common error codes that can be returned */ 186 enum ec_error_list { 187 /* Success - no error */ 188 EC_SUCCESS = 0, 189 /* Unknown error */ 190 EC_ERROR_UNKNOWN = 1, 191 /* Function not implemented yet */ 192 EC_ERROR_UNIMPLEMENTED = 2, 193 /* Overflow error; too much input provided. */ 194 EC_ERROR_OVERFLOW = 3, 195 /* Timeout */ 196 EC_ERROR_TIMEOUT = 4, 197 /* Invalid argument */ 198 EC_ERROR_INVAL = 5, 199 /* Already in use, or not ready yet */ 200 EC_ERROR_BUSY = 6, 201 /* Access denied */ 202 EC_ERROR_ACCESS_DENIED = 7, 203 /* Failed because component does not have power */ 204 EC_ERROR_NOT_POWERED = 8, 205 /* Failed because component is not calibrated */ 206 EC_ERROR_NOT_CALIBRATED = 9, 207 /* Failed because CRC error */ 208 EC_ERROR_CRC = 10, 209 /* Invalid console command param (PARAMn means parameter n is bad) */ 210 EC_ERROR_PARAM1 = 11, 211 EC_ERROR_PARAM2 = 12, 212 EC_ERROR_PARAM3 = 13, 213 EC_ERROR_PARAM4 = 14, 214 EC_ERROR_PARAM5 = 15, 215 EC_ERROR_PARAM6 = 16, 216 EC_ERROR_PARAM7 = 17, 217 EC_ERROR_PARAM8 = 18, 218 EC_ERROR_PARAM9 = 19, 219 /* Wrong number of params */ 220 EC_ERROR_PARAM_COUNT = 20, 221 /* Interrupt event not handled */ 222 EC_ERROR_NOT_HANDLED = 21, 223 /* Data has not changed */ 224 EC_ERROR_UNCHANGED = 22, 225 /* Memory allocation */ 226 EC_ERROR_MEMORY_ALLOCATION = 23, 227 /* Invalid to configure in the current module mode/stage */ 228 EC_ERROR_INVALID_CONFIG = 24, 229 /* something wrong in a HW */ 230 EC_ERROR_HW_INTERNAL = 25, 231 232 /* Sometimes operation is expected to have to be repeated. */ 233 EC_ERROR_TRY_AGAIN = 26, 234 235 /* Verified boot errors */ 236 EC_ERROR_VBOOT_SIGNATURE = 0x1000, /* 4096 */ 237 EC_ERROR_VBOOT_SIG_MAGIC = 0x1001, 238 EC_ERROR_VBOOT_SIG_SIZE = 0x1002, 239 EC_ERROR_VBOOT_SIG_ALGORITHM = 0x1003, 240 EC_ERROR_VBOOT_HASH_ALGORITHM = 0x1004, 241 EC_ERROR_VBOOT_SIG_OFFSET = 0x1005, 242 EC_ERROR_VBOOT_DATA_SIZE = 0x1006, 243 244 /* Verified boot key errors */ 245 EC_ERROR_VBOOT_KEY = 0x1100, 246 EC_ERROR_VBOOT_KEY_MAGIC = 0x1101, 247 EC_ERROR_VBOOT_KEY_SIZE = 0x1102, 248 249 /* Verified boot data errors */ 250 EC_ERROR_VBOOT_DATA = 0x1200, 251 EC_ERROR_VBOOT_DATA_VERIFY = 0x1201, 252 EC_ERROR_VBOOT_DATA_INCOMPATIBLE = 0x1202, 253 EC_ERROR_VBOOT_DATA_UNDERSIZED = 0x1203, 254 255 /* Module-internal error codes may use this range. */ 256 EC_ERROR_INTERNAL_FIRST = 0x10000, 257 EC_ERROR_INTERNAL_LAST = 0x1FFFF 258 }; 259 260 /* 261 * Define test_mockable and test_mockable_static for mocking 262 * functions. 263 */ 264 #ifdef TEST_BUILD 265 #define test_mockable __attribute__((weak)) 266 #define test_mockable_static __attribute__((weak)) 267 #define test_export_static 268 #else 269 #define test_mockable 270 #define test_mockable_static static 271 #define test_export_static static 272 #endif 273 274 /* 275 * Attribute to define functions to only be used in test code, causing 276 * a compiler error if used without TEST_BUILD defined. 277 * 278 * Example usage (add to prototype in header): 279 * __test_only void foo(void); 280 */ 281 #ifdef TEST_BUILD 282 #define __test_only 283 #else 284 #define __test_only __error("This function should only be used by tests") 285 #endif 286 287 /* 288 * Weak symbol markers 289 * 290 * These macros are used to annotate weak definitions, their declarations, and 291 * overriding definitions. 292 * 293 * __override_proto: declarations 294 * __override: definitions which take precedence 295 * __overridable: default (weak) definitions 296 * 297 * For example, in foo.h: 298 * __override_proto void foo(void); 299 * 300 * and in foo.c: 301 * __overridable void foo(void) { 302 * ... 303 * } 304 * 305 * and in board.c: 306 * __override void foo(void) { 307 * ... 308 * } 309 */ 310 #define __override_proto 311 #define __override 312 #define __overridable __attribute__((weak)) 313 314 /* 315 * Mark functions that collide with stdlib so they can be hidden when linking 316 * against libraries that require stdlib. HIDE_EC_STDLIB should be defined 317 * before including common.h from code that links to cstdlib. 318 */ 319 #ifdef TEST_FUZZ 320 #define __stdlib_compat __attribute__((visibility("hidden"))) 321 #else /* TEST_FUZZ */ 322 #define __stdlib_compat 323 #endif /* TEST_FUZZ */ 324 325 /* 326 * __cfg_select(CONFIG_NAME, EMPTY, OTHERWISE) is a macro used for 327 * defining other macros which conditionally select code based on a 328 * config option. It will generate the argument passed as EMPTY 329 * when CONFIG_NAME was defined to the empty string, and OTHERWISE 330 * when the argument was not defined or defined to something 331 * non-empty. 332 * 333 * Generally speaking, macros which use this should make some sort of 334 * context-dependent assertion in OTHERWISE that CONFIG_NAME is 335 * undefined, rather than defined to something else. This usually 336 * involves tricks with __builtin_strcmp. 337 */ 338 #define __cfg_select(cfg, empty, otherwise) \ 339 __cfg_select_1(cfg, empty, otherwise) 340 #define __cfg_select_placeholder_ _, 341 #define __cfg_select_1(value, empty, otherwise) \ 342 __cfg_select_2(__cfg_select_placeholder_##value, empty, otherwise) 343 #define __cfg_select_2(arg1_or_junk, empty, otherwise) \ 344 __cfg_select_3(arg1_or_junk _, empty, otherwise) 345 #define __cfg_select_3(_ignore1, _ignore2, select, ...) select 346 347 /* 348 * This version concatenates a BUILD_ASSERT(...); before OTHERWISE, 349 * handling the __builtin_strcmp trickery where a BUILD_ASSERT is 350 * appropriate in the context. 351 */ 352 #define __cfg_select_build_assert(cfg, value, empty, undef) \ 353 __cfg_select( \ 354 value, \ 355 empty, \ 356 BUILD_ASSERT( \ 357 __builtin_strcmp(cfg, #value) == 0); \ 358 undef) 359 360 /* 361 * Attribute for generating an error if a function is used. 362 * 363 * Clang does not have a function attribute to do this. Rely on linker 364 * errors. :( 365 */ 366 #ifdef __clang__ 367 #define __error(msg) __attribute__((section("/DISCARD/"))) 368 #else 369 #define __error(msg) __attribute__((error(msg))) 370 #endif 371 372 /* 373 * Getting something that works in C and CPP for an arg that may or may 374 * not be defined is tricky. 375 * 376 * Compare the option name with the value string in the OTHERWISE to 377 * __cfg_select. If they are identical we assume that the value was 378 * undefined and return 0. If the value happens to be anything else we 379 * call an undefined method that will raise a compiler error. This 380 * technique requires that the optimizer be enabled so it can remove 381 * the undefined function call. 382 */ 383 #define __config_enabled(cfg, value) \ 384 __cfg_select( \ 385 value, 1, ({ \ 386 int __undefined = __builtin_strcmp(cfg, #value) == 0; \ 387 extern int IS_ENABLED_BAD_ARGS(void) __error( \ 388 cfg " must be <blank>, or not defined."); \ 389 if (!__undefined) \ 390 IS_ENABLED_BAD_ARGS(); \ 391 0; \ 392 })) 393 394 /** 395 * Checks if a config option is enabled or disabled 396 * 397 * Enabled examples: 398 * #define CONFIG_FOO 399 * 400 * Disabled examples: 401 * #undef CONFIG_FOO 402 * 403 * If the option is defined to any value a compiler error will be thrown. 404 * 405 * Note: This macro will only function inside a code block due to the way 406 * it checks for unknown values. 407 */ 408 #define IS_ENABLED(option) __config_enabled(#option, option) 409 410 /** 411 * Makes a global variable static when a config option is enabled, 412 * extern otherwise (with the intention to cause linker errors if the 413 * variable is used outside of a config context, for example thru 414 * IS_ENABLED, that it should be). 415 * 416 * This follows the same constraints as IS_ENABLED, the config option 417 * should be defined to nothing or undefined. 418 */ 419 #define STATIC_IF(option) \ 420 __cfg_select_build_assert(#option, option, static, extern) 421 422 /** 423 * STATIC_IF_NOT is just like STATIC_IF, but makes the variable static 424 * only if the config option is *not* defined, extern if it is. 425 * 426 * This is to assert that a variable will go unused with a certain 427 * config option. 428 */ 429 #define STATIC_IF_NOT(option) \ 430 __cfg_select_build_assert(#option, option, extern, static) 431 432 #endif /* __CROS_EC_COMMON_H */ 433