aboutsummaryrefslogtreecommitdiff
path: root/arch/all/core/BITS.md
diff options
context:
space:
mode:
Diffstat (limited to 'arch/all/core/BITS.md')
-rw-r--r--arch/all/core/BITS.md152
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.