|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [xen master] docs/misra: document the C dialect and translation toolchain assumptions.
commit 3c911be55f1c4e0063e690fb61223df21511b5bb
Author: Roberto Bagnara <roberto.bagnara@xxxxxxxxxxx>
AuthorDate: Wed Jun 21 17:47:56 2023 +0200
Commit: Stefano Stabellini <stefano.stabellini@xxxxxxx>
CommitDate: Tue Jul 11 13:15:52 2023 -0700
docs/misra: document the C dialect and translation toolchain assumptions.
This document specifies the C language dialect used by Xen and
the assumptions Xen makes on the translation toolchain.
Signed-off-by: Roberto Bagnara <roberto.bagnara@xxxxxxxxxxx>
Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
---
docs/misra/C-language-toolchain.rst | 468 ++++++++++++++++++++++++++++++++++++
1 file changed, 468 insertions(+)
diff --git a/docs/misra/C-language-toolchain.rst
b/docs/misra/C-language-toolchain.rst
new file mode 100644
index 0000000000..8651f59118
--- /dev/null
+++ b/docs/misra/C-language-toolchain.rst
@@ -0,0 +1,468 @@
+=============================================
+C Dialect and Translation Assumptions for Xen
+=============================================
+
+This document specifies the C language dialect used by Xen and
+the assumptions Xen makes on the translation toolchain.
+It covers, in particular:
+
+1. the used language extensions;
+2. the translation limits that the translation toolchains must be able
+ to accommodate;
+3. the implementation-defined behaviors upon which Xen may depend.
+
+All points are of course relevant for portability. In addition,
+programming in C is impossible without a detailed knowledge of the
+implementation-defined behaviors. For this reason, it is recommended
+that Xen developers have familiarity with this document and the
+documentation referenced therein.
+
+This document needs maintenance and adaptation in the following
+circumstances:
+
+- whenever the compiler is changed or updated;
+- whenever the use of a certain language extension is added or removed;
+- whenever code modifications cause exceeding the stated translation limits.
+
+
+Applicable C Language Standard
+______________________________
+
+Xen is written in C99 with extensions. The relevant ISO standard is
+
+ *ISO/IEC 9899:1999/Cor 3:2007*: Programming Languages - C,
+ Technical Corrigendum 3.
+ ISO/IEC, Geneva, Switzerland, 2007.
+
+
+Reference Documentation
+_______________________
+
+The following documents are referred to in the sequel:
+
+GCC_MANUAL:
+ https://gcc.gnu.org/onlinedocs/gcc-12.1.0/gcc.pdf
+CPP_MANUAL:
+ https://gcc.gnu.org/onlinedocs/gcc-12.1.0/cpp.pdf
+ARM64_ABI_MANUAL:
+
https://github.com/ARM-software/abi-aa/blob/60a8eb8c55e999d74dac5e368fc9d7e36e38dda4/aapcs64/aapcs64.rst
+X86_64_ABI_MANUAL:
+
https://gitlab.com/x86-psABIs/x86-64-ABI/-/jobs/artifacts/master/raw/x86-64-ABI/abi.pdf?job=build
+
+
+C Language Extensions
+_____________________
+
+
+The following table lists the extensions currently used in Xen.
+The table columns are as follows:
+
+ Extension
+ a terse description of the extension;
+ Architectures
+ a set of Xen architectures making use of the extension;
+ References
+ when available, references to the documentation explaining
+ the syntax and semantics of (each instance of) the extension.
+
+
+.. list-table::
+ :widths: 30 15 55
+ :header-rows: 1
+
+ * - Extension
+ - Architectures
+ - References
+
+ * - Non-standard tokens
+ - ARM64, X86_64
+ - _Static_assert:
+ see Section "2.1 C Language" of GCC_MANUAL.
+ asm, __asm__:
+ see Sections "6.48 Alternate Keywords" and "6.47 How to Use Inline
Assembly Language in C Code" of GCC_MANUAL.
+ __volatile__:
+ see Sections "6.48 Alternate Keywords" and "6.47.2.1 Volatile" of
GCC_MANUAL.
+ __const__, __inline__, __inline:
+ see Section "6.48 Alternate Keywords" of GCC_MANUAL.
+ typeof, __typeof__:
+ see Section "6.7 Referring to a Type with typeof" of GCC_MANUAL.
+ __alignof__, __alignof:
+ see Sections "6.48 Alternate Keywords" and "6.44 Determining the
Alignment of Functions, Types or Variables" of GCC_MANUAL.
+ __attribute__:
+ see Section "6.39 Attribute Syntax" of GCC_MANUAL.
+ __builtin_types_compatible_p:
+ see Section "6.59 Other Built-in Functions Provided by GCC" of
GCC_MANUAL.
+ __builtin_va_arg:
+ non-documented GCC extension.
+ __builtin_offsetof:
+ see Section "6.53 Support for offsetof" of GCC_MANUAL.
+
+ * - Empty initialization list
+ - ARM64, X86_64
+ - Non-documented GCC extension.
+
+ * - Arithmetic operator on pointer to void
+ - ARM64, X86_64
+ - See Section "6.24 Arithmetic on void- and Function-Pointers" of
GCC_MANUAL."
+
+ * - Statements and declarations in expressions
+ - ARM64, X86_64
+ - See Section "6.1 Statements and Declarations in Expressions" of
GCC_MANUAL.
+
+ * - Structure or union definition with no members
+ - ARM64, X86_64
+ - See Section "6.19 Structures with No Members" of GCC_MANUAL.
+
+ * - Zero size array type
+ - ARM64, X86_64
+ - See Section "6.18 Arrays of Length Zero" of GCC_MANUAL.
+
+ * - Binary conditional expression
+ - ARM64, X86_64
+ - See Section "6.8 Conditionals with Omitted Operands" of GCC_MANUAL.
+
+ * - 'Case' label with upper/lower values
+ - ARM64, X86_64
+ - See Section "6.30 Case Ranges" of GCC_MANUAL.
+
+ * - Unnamed field that is not a bit-field
+ - ARM64, X86_64
+ - See Section "6.63 Unnamed Structure and Union Fields" of GCC_MANUAL.
+
+ * - Empty declaration
+ - ARM64, X86_64
+ - Non-documented GCC extension.
+ Note: an empty declaration is caused by a semicolon at file scope
+ with nothing before it (not to be confused with an empty statement).
+
+ * - Incomplete enum declaration
+ - ARM64
+ - See Section "6.49 Incomplete enum Types" of GCC_MANUAL.
+
+ * - Implicit conversion from a pointer to an incompatible pointer
+ - ARM64, X86_64
+ - Non-documented GCC extension. The documentation for option
+ -Wincompatible-pointer-types in Section
+ "3.8 Options to Request or Suppress Warnings" of GCC_MANUAL
+ is possibly relevant.
+
+ * - Pointer to a function is converted to a pointer to an object or a
pointer to an object is converted to a pointer to a function
+ - X86_64
+ - Non-documented GCC extension. The information provided in
+ https://gcc.gnu.org/bugzilla/show_bug.cgi?id=83584
+ is possibly relevant.
+
+ * - Token pasting of ',' and __VA_ARGS__
+ - ARM64, X86_64
+ - See Section "6.21 Macros with a Variable Number of Arguments" of
GCC_MANUAL.
+
+ * - Named variadic macro arguments
+ - ARM64, X86_64
+ - See Section "6.21 Macros with a Variable Number of Arguments" of
GCC_MANUAL.
+
+ * - No arguments for '...' parameter of variadic macro
+ - ARM64, X86_64
+ - See Section "6.21 Macros with a Variable Number of Arguments" of
GCC_MANUAL.
+
+ * - void function returning void expression
+ - ARM64, X86_64
+ - See the documentation for -Wreturn-type in Section "3.8 Options to
Request or Suppress Warnings" of GCC_MANUAL.
+
+ * - GNU statement expressions from macro expansion
+ - ARM64, X86_64
+ - See Section "6.1 Statements and Declarations in Expressions" of
GCC_MANUAL.
+
+ * - Invalid application of sizeof to a void type
+ - ARM64, X86_64
+ - See Section "6.24 Arithmetic on void- and Function-Pointers" of
GCC_MANUAL.
+
+ * - Redeclaration of already-defined enum
+ - ARM64, X86_64
+ - See Section "6.49 Incomplete enum Types" of GCC_MANUAL.
+
+ * - struct with flexible array member nested in a struct
+ - ARM64, X86_64
+ - See Section "6.18 Arrays of Length Zero" of GCC_MANUAL.
+
+ * - struct with flexible array member used as an array element
+ - ARM64, X86_64
+ - See Section "6.18 Arrays of Length Zero" of GCC_MANUAL.
+
+ * - enumerator value outside the range of int
+ - ARM64, X86_64
+ - Non-documented GCC extension.
+
+ * - Extended integer types
+ - X86_64
+ - See Section "6.9 128-bit Integers" of GCC_MANUAL.
+
+
+Translation Limits
+__________________
+
+The following table lists the translation limits that a toolchain has
+to satisfy in order to translate Xen. The numbers given are a
+compromise: on the one hand, many modern compilers have very generous
+limits (in several cases, the only limitation is the amount of
+available memory); on the other hand we prefer setting limits that are
+not too high, because compilers do not have any obligation of
+diagnosing when a limit has been exceeded, and not too low, so as to
+avoid frequently updating this document. In the table, only the
+limits that go beyond the minima specified by the relevant C Standard
+are listed.
+
+The table columns are as follows:
+
+ Limit
+ a terse description of the translation limit;
+ Architectures
+ a set relevant of Xen architectures;
+ Threshold
+ a value that the Xen project does not wish to exceed for that limit
+ (this is typically below, often much below what the translation
+ toolchain supports);
+ References
+ when available, references to the documentation providing evidence
+ that the translation toolchain honors the threshold (and more).
+
+.. list-table::
+ :widths: 30 15 10 45
+ :header-rows: 1
+
+ * - Limit
+ - Architectures
+ - Threshold
+ - References
+
+ * - Size of an object
+ - ARM64, X86_64
+ - 8388608
+ - The maximum size of an object is defined in the MAX_SIZE macro, and for
a 32 bit architecture is 8MB.
+ The maximum size for an array is defined in the PTRDIFF_MAX and in a 32
bit architecture is 2^30-1.
+ See occurrences of these macros in GCC_MANUAL.
+
+ * - Characters in one logical source line
+ - ARM64
+ - 5000
+ - See Section "11.2 Implementation limits" of CPP_MANUAL.
+
+ * - Characters in one logical source line
+ - X86_64
+ - 12000
+ - See Section "11.2 Implementation limits" of CPP_MANUAL.
+
+ * - Nesting levels for #include files
+ - ARM64
+ - 24
+ - See Section "11.2 Implementation limits" of CPP_MANUAL.
+
+ * - Nesting levels for #include files
+ - X86_64
+ - 32
+ - See Section "11.2 Implementation limits" of CPP_MANUAL.
+
+ * - case labels for a switch statement (excluding those for any nested
switch statements)
+ - X86_64
+ - 1500
+ - See Section "4.12 Statements" of GCC_MANUAL.
+
+ * - Number of significant initial characters in an external identifier
+ - ARM64, X86_64
+ - 63
+ - See Section "4.3 Identifiers" of GCC_MANUAL.
+
+
+Implementation-Defined Behaviors
+________________________________
+
+The following table lists the C language implementation-defined behaviors
+relevant for MISRA C:2012 Dir 1.1 upon which Xen may possibly depend.
+
+The table columns are as follows:
+
+ I.-D.B.
+ a terse description of the implementation-defined behavior;
+ Architectures
+ a set relevant of Xen architectures;
+ Value(s)
+ for i.-d.b.'s with values, the values allowed;
+ References
+ when available, references to the documentation providing details
+ about how the i.-d.b. is resolved by the translation toolchain.
+
+.. list-table::
+ :widths: 30 15 10 45
+ :header-rows: 1
+
+ * - I.-D.B.
+ - Architectures
+ - Value(s)
+ - References
+
+ * - Allowable bit-field types other than _Bool, signed int, and unsigned int
+ - ARM64, X86_64
+ - All explicitly signed integer types, all unsigned integer types,
+ and enumerations.
+ - See Section "4.9 Structures, Unions, Enumerations, and Bit-Fields".
+
+ * - #pragma preprocessing directive that is documented as causing
translation failure or some other form of undefined behavior is encountered
+ - ARM64, X86_64
+ - pack, GCC visibility
+ - #pragma pack:
+ see Section "6.62.11 Structure-Layout Pragmas" of GCC_MANUAL.
+ #pragma GCC visibility:
+ see Section "6.62.14 Visibility Pragmas" of GCC_MANUAL.
+
+ * - The number of bits in a byte
+ - ARM64
+ - 8
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "8.1 Data types"
of ARM64_ABI_MANUAL.
+
+ * - The number of bits in a byte
+ - X86_64
+ - 8
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "3.1.2 Data
Representation" of X86_64_ABI_MANUAL.
+
+ * - Whether signed integer types are represented using sign and magnitude,
two's complement, or one's complement, and whether the extraordinary value is a
trap representation or an ordinary value
+ - ARM64, X86_64
+ - Two's complement
+ - See Section "4.5 Integers" of GCC_MANUAL.
+
+ * - Any extended integer types that exist in the implementation
+ - X86_64
+ - __uint128_t
+ - See Section "6.9 128-bit Integers" of GCC_MANUAL.
+
+ * - The number, order, and encoding of bytes in any object
+ - ARM64
+ -
+ - See Section "4.15 Architecture" of GCC_MANUAL and Chapter 5 "Data types
and alignment" of ARM64_ABI_MANUAL.
+
+ * - The number, order, and encoding of bytes in any object
+ - X86_64
+ -
+ - See Section "4.15 Architecture" of GCC_MANUAL and Section "3.1.2 Data
Representation" of X86_64_ABI_MANUAL.
+
+ * - Whether a bit-field can straddle a storage-unit boundary
+ - ARM64
+ -
+ - See Section "4.9 Structures, Unions, Enumerations, and Bit-Fields of
GCC_MANUAL and Section "8.1.8 Bit-fields" of ARM64_ABI_MANUAL.
+
+ * - Whether a bit-field can straddle a storage-unit boundary
+ - X86_64
+ -
+ - See Section "4.9 Structures, Unions, Enumerations, and Bit-Fields" of
GCC_MANUAL and Section "3.1.2 Data Representation" of X86_64_ABI_MANUAL.
+
+ * - The order of allocation of bit-fields within a unit
+ - ARM64
+ -
+ - See Section "4.9 Structures, Unions, Enumerations, and Bit-Fields of
GCC_MANUAL and Section "8.1.8 Bit-fields" of ARM64_ABI_MANUAL.
+
+ * - The order of allocation of bit-fields within a unit
+ - X86_64
+ -
+ - See Section "4.9 Structures, Unions, Enumerations, and Bit-Fields" of
GCC_MANUAL and Section "3.1.2 Data Representation" of X86_64_ABI_MANUAL.
+
+ * - What constitutes an access to an object that has volatile-qualified type
+ - ARM64, X86_64
+ -
+ - See Section "4.10 Qualifiers" of GCC_MANUAL.
+
+ * - The values or expressions assigned to the macros specified in the
headers <float.h>, <limits.h>, and <stdint.h>
+ - ARM64
+ -
+ - See Section "4.15 Architecture" of GCC_MANUAL and Chapter 5 "Data types
and alignment" of ARM64_ABI_MANUAL.
+
+ * - The values or expressions assigned to the macros specified in the
headers <float.h>, <limits.h>, and <stdint.h>
+ - X86_64
+ -
+ - See Section "4.15 Architecture" of GCC_MANUAL and Section "3.1.2 Data
Representation" of X86_64_ABI_MANUAL.
+
+ * - Character not in the basic source character set is encountered in a
source file, except in an identifier, a character constant, a string literal, a
header name, a comment, or a preprocessing token that is never converted to a
token
+ - ARM64
+ - UTF-8
+ - See Section "1.1 Character sets" of CPP_MANUAL.
+ We assume the locale is not restricting any UTF-8 characters being part
of the source character set.
+
+ * - The value of a char object into which has been stored any character
other than a member of the basic execution character set
+ - ARM64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "8.1 Data types"
of ARM64_ABI_MANUAL.
+
+ * - The value of a char object into which has been stored any character
other than a member of the basic execution character set
+ - X86_64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "3.1.2 Data
Representation" of X86_64_ABI_MANUAL.
+
+ * - The value of an integer character constant containing more than one
character or containing a character or escape sequence that does not map to a
single-byte execution character
+ - ARM64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "8.1 Data types"
of ARM64_ABI_MANUAL.
+
+ * - The value of an integer character constant containing more than one
character or containing a character or escape sequence that does not map to a
single-byte execution character
+ - X86_64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "3.1.2 Data
Representation" of X86_64_ABI_MANUAL.
+
+ * - The mapping of members of the source character set
+ - ARM64, X86_64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and the documentation for
-finput-charset=charset in the same manual.
+
+ * - The members of the source and execution character sets, except as
explicitly specified in the Standard
+ - ARM64, X86_64
+ - UTF-8
+ - See Section "4.4 Characters" of GCC_MANUAL
+
+ * - The values of the members of the execution character set
+ - ARM64, X86_64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and the documentation for
-fexec-charset=charset in the same manual.
+
+ * - How a diagnostic is identified
+ - ARM64, X86_64
+ -
+ - See Section "4.1 Translation" of GCC_MANUAL.
+
+ * - The places that are searched for an included < > delimited header, and
how the places are specified or the header is identified
+ - ARM64, X86_64
+ -
+ - See Chapter "2 Header Files" of CPP_MANUAL.
+
+ * - How the named source file is searched for in an included " " delimited
header
+ - ARM64, X86_64
+ -
+ - See Chapter "2 Header Files" of CPP_MANUAL.
+
+ * - How sequences in both forms of header names are mapped to headers or
external source file names
+ - ARM64, X86_64
+ -
+ - See Chapter "2 Header Files" of CPP_MANUAL.
+
+ * - Whether the # operator inserts a \ character before the \ character
that begins a universal character name in a character constant or string literal
+ - ARM64, X86_64
+ -
+ - See Section "3.4 Stringizing" of CPP_MANUAL.
+
+ * - The current locale used to convert a wide string literal into
corresponding wide character codes
+ - ARM64, X86_64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "11.1
Implementation-defined behavior" of CPP_MANUAL.
+
+ * - The value of a string literal containing a multibyte character or
escape sequence not represented in the execution character set
+ - X86_64
+ -
+ - See Section "4.4 Characters" of GCC_MANUAL and Section "11.1
Implementation-defined behavior" of CPP_MANUAL.
+
+ * - The behavior on each recognized #pragma directive
+ - ARM64, X86_64
+ - pack, GCC visibility
+ - See Section "4.13 Preprocessing Directives" of GCC_MANUAL and Section
"7 Pragmas" of CPP_MANUAL.
+
+ * - The method by which preprocessing tokens (possibly resulting from macro
expansion) in a #include directive are combined into a header name
+ - X86_64
+ -
+ - See Section "4.13 Preprocessing Directives" of GCC_MANUAL and Section
"11.1 Implementation-defined behavior" of CPP_MANUAL.
+
+
+END OF DOCUMENT.
--
generated by git-patchbot for /home/xen/git/xen.git#master
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |