diff options
Diffstat (limited to 'arch/all/core/BITS.md')
-rw-r--r-- | arch/all/core/BITS.md | 152 |
1 files changed, 0 insertions, 152 deletions
diff --git a/arch/all/core/BITS.md b/arch/all/core/BITS.md deleted file mode 100644 index b015cde..0000000 --- a/arch/all/core/BITS.md +++ /dev/null @@ -1,152 +0,0 @@ -# Extending libcarrot to another compiler/architecture/platform. -This core module includes bits which define the compiler, architecture or -platform specific macros and types, so the core can centralize all of the -standard headers. - -This file is a description of all of these specific subheaders. - -Some higher-level modules (architecture and platform modules for compiler -headers, platform modules for architecture headers) can set these headers and -expect other headers instead. -**Read the higher modules documentation before you implement these!** - -## Compiler-specific headers -### `bits/compiler.h` -- check the compiler. -This header checks if the compiler can be used with the other compiler-specific -headers, and define the `__<COMPILER>_PREREQ(major, minor)` macro, which -evaluates at compile-time, as 1 if we are indeed using this compiler and the -current version is at least `major.minor`, or as 0 otherwise. - -It should also define the attributes, if an implementation of it exists with -the compiler. Attributes are those things you append to your element's -declaration and/or definition to produce more warnings, assumptions or other -cool things. The name is inspired from GCC's implementation, in which the -utility for this is called `__attribute__`. The attributes will be used like -this for functions: - - extern __my_attr void bake_bread(int bread); - - __my_attr void bake_bread(int bread) - { - /* ... */ - } - -Here are the different attributes you can set: - -- `__inline`: force the inlining of a function; -- `__pure`: produce a value out of others, with no side effect whatsoever; -- `__wur`: warn if the result is unused (might have side effects); -- `__malloc`: is a memory allocation function; -- `__deprecated`: this function or element should not be used; -- `__noreturn`: the function doesn't return (makes a long jump); -- `__nothrow`: the function won't throw (C++ thingy); -- `__unroll_loops`: should unroll the loops with constant number of passes - if possible; -- `__nonnull(index, name)`: - an argument with name `name` and index `index` (starting from 1) should not - have an invalid pointer value; -- `__printf_format(format_index, args_index)`: - the function is a printf-like function, where `format_index` is the index - (starting from 1) of the format string, and `args_index` is the index - (also starting from 1) of the `...`; - -You can also set some utilities among these: - -- `likely(expr)`, `unlikely(expr)`: - optimize the branching structure for a likely or unlikely condition. - -### `bits/endian.h` -- endianness identification. -This header defines the `__BYTE_ORDER` macro, which can expand to those values: - -- `__LITTLE_ENDIAN`: the architecture is little endian; -- `__BIG_ENDIAN`: the architecture is big endian; -- `__PDP_ENDIAN`: the architecture is PDP endian. - -### `bits/stdarg.h` -- ISO variable argument lists. -This header defines the ISO C-like `stdarg.h` internal macros: - -- `__stdarg_va_start(ap, param)`; -- `__stdarg_va_end(ap)`; -- `__stdarg_va_arg(ap, arg_type)`; -- `__stdarg_va_copy(dest, src)`. - -### `bits/types.h` -- architecture types. -This subheader should define the following types (**N** represents 8, 16 or 32): - -- `__intN_t`, `__uintN_t`: - signed and unsigned integer type with width `N`; -- `__int_leastN_t`, `__uint_leastN_t`: - signed and unsigned integer type with at least `N` as the width, such that - no integer type with lesser size has at least the specified width; -- `__int_fastN_t`, `__uint_fastN_t`: - signed and unsigned fastest integer type with a width of at least `N`. -- `__intptr_t`, `__uintptr_t`: - signed and unsigned integer type which are exactly the same width as - a pointer; -- `__intmax_t`, `__uintmax_t`: - signed and unsigned greatest-width integer type; - -For each of the **signed version of the types**, it should also define the -following macros, leading to constant expressions (where `<type>` represents -the all caps type without the `__` prefix and the `_t` suffix, -e.g. `INT_FAST8` for `__int_fast8_t`, and `<suffix>` represents the type suffix, -so what's after `__int_` and before the `_t` for the `__intN_t`, -`__int_leastN_t` and `__int_fastN_t` types, `PTR` for `__intptr_t`, and -`MAX` for `__intmax_t`): - -- `__<type>_WIDTH`: the number of bits of the type - (e.g. `16` for a 16-bit type); -- `__<type>_MIN`: the minimum of the signed version of the type; -- `__<type>_MAX`: the maximum of the signed version of the type; -- `__U<type>_MIN`: the minimum of the unsigned version of the type - (usually 0 with a suffix); -- `__U<type>_MAX`: the maximum of the unsigned version of the type; -- `__PRI<suffix>`: the `printf`/`scanf` type prefix. - -The `__int_fastN_t`/`__uint_fastN_t` types should also have the -`__INT<N>_C`/`__UINT<N>_C` macros defined, plus the `__INTMAX_C`/`__UINTMAX_C` -macros, which should return the values with the eventual prefix/suffix. - -For example, for `__int_least32_t`: - - typedef char __int32_t; - typedef unsigned char __uint32_t; - - #define __INT32_WIDTH ( 32) - #define __INT32_MIN (-2147483647-1) - #define __INT32_MAX (+2147483647) - #define __UINT32_MAX ( 4294967295) - #define __PRI32 "l" - - #define __INT32_C(_X) _X ## L - #define __UINT32_C(_X) _X ## UL - -You should also define: - -- `__CHAR_BIT`: the char bit; -- `__CHAR_IS_SIGNED`: 1 if the char bit is signed by default, - 0 if it isn't; - -And the following constants for `char` (`CHAR`), `short` (`SHRT`), -`int` (`INT`), `long` (`LONG`) and `long long` (`LLONG`): - -- `__<type>_WIDTH`: the number of bits of the type; -- `__<type>_MIN`: the minimum value of the signed version of the type; -- `__<type>_MAX`: the maximum value of the signed version of the type; -- `__U<type>_MIN`: the minimum value of the unsigned version of the type; -- `__U<type>_MAX`: the maximum value of the unsigned version of the type. - -## Architecture-specific headers -### `bits/byteswap.h` -- byteswap utilities. -This header can define the `__bswap_16` and `__bswap_32` macros, optimized -for the platform. If the architecture also provides the `bswap_16` function, -it should define the `__BYTESWAP_SUB16` macro, and if it provides the `bswap_32` -function, it should define the `__BYTESWAP_SUB32` macro. - -### `bits/setjmp.h` -- long jumps. -This header defines the `jmp_buf` type for `setjmp.h`. - -## Platform-specific headers -### `bits/time.h` -- platform-specific time constants. -This header must define the `CLOCKS_PER_SEC` constant, which corresponds -to the number of ticks per second. |