Dear fellow developers, Here is the second revision of the ABI extension specification previously posted, incorporating feedback received for the first revision. Changes have been made to Section 4 "Implementation Notes", the remaining parts have stayed the same. The master copy of this document is available at: <https://dmz-portal.mips.com/wiki/MIPS_ABI_-_NaN_Interlinking> Please let me know if you have any questions, comments or concerns about this updated version. Otherwise I will wait a short while and then follow up with an updated implementation. Thanks to all of you who took time to read the first revision and comment on it, and especially Joseph Myers. Maciej -------------------------------------------------------------------------- MIPS ABI Extension for IEEE Std 754 Non-Compliant Interlinking 1. Introduction The MIPS architecture has supported IEEE Std 754 floating-point arithmetic since its beginning in 1985. Naturally as initial support was for the original 1985 revision of the standard then particular choices were made for the architecture where freedom was given by that revision. This was the case with not-a-number (NaN) symbolic data and the bit patterns chosen to represent them. Later on this choice turned out to be different from ones used by all other IEEE Std 754 implementers. Hardware implementing this original MIPS architecture definition and corresponding software and ABIs will be referred across this document as legacy-NaN hardware, software and ABIs respectively, and the NaN patterns themselves as legacy NaN patterns. The patterns originally chosen had their advantage in the MIPS architecture, however an updated revision of IEEE Std 754 released in 2008 made the NaN patterns chosen by other implementers preferred. MIPS architecture overseers decided to follow the recommendation and update the architecture definition accordingly. Consequently a set of amended ABIs has been created to provide for software execution on hardware implementing the updated architecture. Such hardware, software and ABIs will be referred across this document to as 2008-NaN hardware, software and ABIs respectively, and the NaN patterns themselves as to 2008 NaN patterns. The legacy and 2008 NaN patterns are not compatible with each other and therefore the respective ABIs and software binaries are not. To keep all software compliant to IEEE Std 754 a decision was made to disallow mixing legacy-NaN and 2008-NaN software modules in static linking and dynamic loading, and at the OS level disallow execution of 2008-NaN software on legacy-NaN hardware and vice versa. 2. Statement of the Problem The decisions made so far about the MIPS architecture and ABIs have led to a situation where the large existing base of software binaries cannot execute on current hardware. And this applies regardless of whether it relies on the use of NaN data or IEEE Std 754 arithmetic in the first place. Rebuilding all of the existing software for 2008-NaN hardware is infeasible and additionally such software, rebuilt or new, will not run on legacy-NaN hardware that is widely deployed, so maintaining two binary versions of the same piece of software would often be required. 3. Solution The solution described here has been prepared with the Linux environment in mind, although where applicable individual changes are also appropriate for bare-metal environments. A number of changes are made at different levels to make the transition to 2008-NaN hardware easier as well as long-term support for legacy-NaN hardware that is undoubtedly going to stay around for a while. They are detailed from the hardware level up in the following sections. 3.1 Hardware and Operating System Interface The operating system tells legacy-NaN and 2008-NaN software apart by examining the state of the EF_MIPS_NAN2008 flag in the ELF file header of individual binaries requested for execution with the execve(2) system call. The value of `0' of the flag denotes legacy-NaN software and the value of `1' denotes 2008-NaN software. 3.1.1 Floating-Point Emulation Where possible both legacy-NaN and 2008-NaN software will be supported. The MIPS architecture itself makes it possible and therefore the FPU emulator used on hardware that does not implement an FPU will set itself to the right mode individually for every legacy-NaN or 2008-NaN program executed. On Linux the FPU emulator can also be enabled unconditionally even on hardware that does implement an FPU, with the use of the `nofpu' kernel option. In this case both legacy-NaN and 2008-NaN software will be automatically supported, although at a performance loss compared to FPU hardware. 3.1.2 Global IEEE Std 754 Compliance Mode A new `ieee754=' kernel option is provided for cases where strict IEEE Std 754 compliance is not required. This makes it possible to use binaries from existing Linux distributions on new 2008-NaN hardware making the transition easier. At least two values are accepted on the right hand side of this option, `strict' and `relaxed', to select between IEEE Std 754 compliance modes. These modes shall only affect software that does not make an explicit mode selection as noted in Section 3.1.3 below. In the `strict' mode, which is the default in the absence of an explicit `ieee754=' option, only software compatible with the NaN patterns handled by FPU hardware shall be accepted for execution, that is legacy-NaN software on legacy-NaN hardware and 2008-NaN software on 2008-NaN hardware. In the `relaxed' mode any software shall be accepted for execution, regardless of whether it is compatible with FPU hardware. Additionally, in the `relaxed' mode, even if enabled with the FCSR.Enables.V bit, any IEEE Std 754 Invalid Operation exceptions triggered with an sNaN instruction operand shall not result in a SIGFPE signal being issued to the originating process and a qNaN (encoded according to the current mode set in the floating-point environment) shall be substituted and propagated through the arithmetic operation requested as with a qNaN operand. Additionally, to make the dynamic loader aware that the `relaxed' IEEE Std 754 compliance mode is in effect, bit #25 shall be set in the `a_val' member of the AT_FLAGS entry of the auxiliary vector created by the kernel on program execution for any program accepted for this mode. This bit is in the part of the flag word reserved for system semantic by the MIPS psABI[1]. This bit shall be set to `0' in the `strict' mode and `1' in the `relaxed' mode. Additional values may be accepted with the kernel option and consequently modes provided now or in the future, but they are beyond the scope of this document. 3.1.3 Per Program Individual IEEE Std 754 Compliance Mode Individual programs can select their required IEEE Std 754 compliance mode regardless of the global mode. Individual selection takes precedence over the global selection. Programs that select their individual mode shall have a PT_MIPS_ABIFLAGS segment and shall have bit #1 set in its `flags1' member. The specific mode selected is then determined by the value of bit #1 in this segment's `flags2' member, `0' for the `strict' mode and `1' for the `relaxed' mode. The semantics of such individually selected IEEE Std 754 compliance mode is the same as that of the corresponding global mode. See Section 3.1.2 above for further details. 3.1.4 Dynamic IEEE Std 754 Compliance Mode Control A new request is provided via the prctl(2) system call to let a process switch its own IEEE Std 754 compliance mode. This is for example to let a dynamic loader invoked manually set the compliance mode for an executable requested as if the executable was run directly and its compliance mode preset by the kernel. The request shall be made as follows: int result; result = prctl(PR_SET_IEEE754_MODE, mode, what); In this request `mode' shall be set to one of the following: * PR_IEEE754_MODE_LEGACY -- to set the compliance mode used with programs which do not make an individual IEEE Std 754 compliance mode selection, * PR_IEEE754_MODE_STRICT -- to set the `strict' compliance mode, * PR_IEEE754_MODE_RELAXED -- to set the `relaxed' compliance mode, and `what' shall be set to either of: * PR_IEEE754_MODE_NAN_LEGACY -- to select the legacy-NaN encoding mode, * PR_IEEE754_MODE_NAN_2008 -- to select the 2008-NaN encoding mode. The kernel shall execute the request according to the rules set out in Subsection 3.1.2 and Subsection 3.1.3 for the ELF file flag settings corresponding to the respective IEEE Std 754 compliance and NaN encoding modes requested. If the request is successful a non-negative value shall be assigned to `result', in which bits 7:0 are set to a pattern that would be placed in bits 31:24, in the same bit order, of the `a_val' member of the AT_FLAGS entry of the auxiliary vector created by the kernel on program execution for the mode selected. 3.2 Dynamic Loading The dynamic loader shall recognise IEEE Std 754 compliance modes and resolve main executable's dependencies according to rules set below. For the purpose of these rules a main executable is the binary named in an execve(2) call to the operating system, and a dependency is any dynamic shared object additionally loaded, via any means including but not necessarily limited to a DT_NEEDED dynamic segment entry, an LD_PRELOAD environment variable or a dlopen(3) library call. 3.2.1 IEEE Std 754 Compliance Mode Selection Both executables and dynamic shared objects can select their required IEEE Std 754 compliance mode. A binary requiring a specific compliance mode shall have a PT_MIPS_ABIFLAGS segment and shall have its contents set according to rules set out in Section 3.1.3. Such a binary will be referred to as `strict' or `relaxed'. Binaries that have no PT_MIPS_ABIFLAGS segment or have one that does not request a specific compliance mode will be referred to as `legacy'. 3.2.2 Dynamic Dependency Acceptance Rules The IEEE Std 754 compliance mode requested is determined by the main executable. Any dynamic shared objects loaded in addition shall respect the mode according to the rules set below. For `strict' executables all the dynamic shared objects shall follow the same legacy-NaN or 2008-NaN ABI, as denoted by the EF_MIPS_NAN2008 flag described in Section 3.1. The value of the flag shall be the same across the executable and all the dynamic shared objects loaded together. Both `strict' and `legacy' dynamic shared objects shall be accepted, however `relaxed' ones shall be rejected regardless of the value of their EF_MIPS_NAN2008 flag. For `relaxed' executables any dynamic shared objects shall be accepted, `strict', `relaxed' and `legacy' alike, regardless of the value of their EF_MIPS_NAN2008 flag. For `legacy' executables the compliance mode is determined by the value of bit #25 in the `a_val' member of the AT_FLAGS entry of the auxiliary vector received from the kernel. The value of `0' shall make the dynamic loader follow the rules for `strict' executables. The value of `1' shall make the dynamic loader follow the rules for `relaxed' executables. 3.2.3 Dynamic Loading Compatibility Considerations The encoding for the PT_MIPS_ABIFLAGS segment has been selected such that old versions of the dynamic loader will reject `relaxed' binaries because of an unknown `flags2' bit set. This is to prevent execution in an environment that does not follow the rules set out in this specification and to signify the need to upgrade. Both `strict' and `legacy' binaries will run correctly as they follow the rules defined for old versions of the dynamic loader. Older versions of the dynamic loader will not process a PT_MIPS_ABIFLAGS segment and will only examine the EF_MIPS_NAN2008 flag. Very old versions of the dynamic loader will not even process the flag. It is therefore not possible to guarantee that the rules set out here will be followed or an error triggered with older systems. 3.3 Static Linking The static linker shall recognise IEEE Std 754 compliance modes and enforce the rules set below for all static links, both final ones that produce an executable or a dynamic shared object and incremental ones that produce a relocatable object. 3.3.1 IEEE Std 754 Compliance Mode Selection All relocatable objects can select their required IEEE Std 754 compliance mode. An object requiring a specific compliance mode shall have an SHT_MIPS_ABIFLAGS section called `.MIPS.abiflags' and shall have its contents set according to rules set out for the PT_MIPS_ABIFLAGS segment in Section 3.1.3. Such an object will be referred to as `strict' or `relaxed'. Objects that have no SHT_MIPS_ABIFLAGS section or have one that does not request a specific compliance mode will be referred to as `legacy'. On making an executable or a dynamic shared object the linker shall map an SHT_MIPS_ABIFLAGS section to a PT_MIPS_ABIFLAGS segment. 3.3.2 Static Linking Object Acceptance Rules The static linker shall follow the user selection as to the linking mode used, either of `strict' and `relaxed'. The selection will be made according to the usual way assumed for the environment used, which may be a command-line option, a property setting, etc. In the `strict' linking mode both `strict' and `legacy' objects can be linked together. All shall follow the same legacy-NaN or 2008-NaN ABI, as denoted by the EF_MIPS_NAN2008 flag described in Section 3.1. The value of the flag shall be the same across all the objects linked together. The output of a link involving any `strict' objects shall be marked as `strict'. No `relaxed' objects shall be allowed in the same link. In the `relaxed' linking mode any `strict', `relaxed' and `legacy' objects can be linked together, regardless of the value of their EF_MIPS_NAN2008 flag. If the flag has the same value across all objects linked, then the value shall be propagated to the binary produced. The output shall be marked as `relaxed'. It is recommended that the linker provides a way to warn the user whenever a `relaxed' link is made of `strict' and `legacy' objects only. 3.3.3 Static Linking Compliance Mode Warnings A flag shall be defined in bit #0 of the `flags2' member of the PT_MIPS_ABIFLAGS section, determining the warning mode for IEEE Std 754 compliance in static linking. This bit shall be set to `0' to enable the warning mode (`warn' mode) and `1' to disable it (`nowarn' mode). The bit shall propagate through an incremental static link in an implementation-defined manner, however it shall be set to `0' in a final static link. 3.3.4 Static Linking Compatibility Considerations The encoding for the SHT_MIPS_ABIFLAGS section has been selected such that old versions of the static linker will reject `relaxed' binaries because of an unknown `flags2' bit set. This is to prevent incorrectly annotated objects from being produced that would not guarantee IEEE Std 754 compliance. The encoding has also been selected such that old versions of the static linker will merge the `flags1' bit used to tell `legacy' objects and `strict'/`relaxed' ones apart, automatically marking the output of links involving any `strict' objects as `strict' as well. Older versions of the static linker will not process an SHT_MIPS_ABIFLAGS section and will only examine the EF_MIPS_NAN2008 flag. Consequently they may allow `relaxed' objects in a single link with `strict' and `legacy' ones. 3.4 Relocatable Object Generation Tools that produce relocatable objects such as the assembler shall always produce a SHT_MIPS_ABIFLAGS section according to the IEEE Std 754 compliance mode selected. In the absence of any explicit user instructions the `strict' mode shall be assumed. No new `legacy' objects shall be produced. 3.5 No-float Modules Certain modules used in dynamic loading or static linking may be marked as containing no floating-point code, in a way defined by a separate specification. Such modules shall always be accepted for dynamic loading and static linking, and for the purpose of IEEE Std 754 compliance checks treated as if absent. 3.6 Definitions The following macros shall be defined for the flags introduced by this document: /* `flags1' member of the PT_MIPS_ABIFLAGS/SHT_MIPS_ABIFLAGS structure. */ #define MIPS_AFL_FLAGS1_IEEE 2 /* IEEE Std 754 mode defined. */ /* `flags2' members of the PT_MIPS_ABIFLAGS/SHT_MIPS_ABIFLAGS structure. */ #define MIPS_AFL_FLAGS2_NOWARN 1 /* Suppress IEEE Std 754 warnings. */ #define MIPS_AFL_FLAGS2_RELAXED 2 /* Relaxed IEEE Std 754 mode. */ /* `a_val' member of the AT_FLAGS entry. */ #define AV_FLAGS_MIPS_RELAXED (1 << 25) /* Relaxed IEEE Std 754 mode. */ It is unspecified at this time whether the bits referred to with MIPS_AFL_FLAGS2_RELAXED and AV_FLAGS_MIPS_RELAXED are single-bit bitfields or the least significant bits of a larger enumeration, to be defined later. The following macros shall be defined for the prctl(2) interface introduced by this document: /* Control MIPS IEEE 754 compliance modes. */ #define PR_SET_IEEE754_MODE TBA #define PR_IEEE754_MODE_LEGACY 0 /* Legacy mode. */ #define PR_IEEE754_MODE_STRICT 1 /* Strict mode. */ #define PR_IEEE754_MODE_RELAXED 2 /* Relaxed mode. */ #define PR_IEEE754_MODE_NAN_LEGACY 0 /* Set legacy NaN encoding. */ #define PR_IEEE754_MODE_NAN_2008 1 /* Set 2008 NaN encoding. */ 4. Implementation Notes For the GNU linker the command-line options to select between the `strict' and the `relaxed' IEEE Std 754 compliance modes will be `--ieee=strict' and `--ieee=relaxed', respectively. The latter will issue a compliance warning in the case where all input objects were either `strict' and `warn' or `legacy' mode, unless a `--ieee=nowarn' option has also been used. There will be a `--ieee=warn' option as well to revert the effect of the former option. For the GNU assembler the directives to select between the `strict' and the `relaxed' IEEE Std 754 compliance modes will be `.ieee strict' and `.ieee relaxed', respectively. Equivalent command-line options will be present, `-mieee=strict' and `-mieee=relaxed', respectively. There will be `.ieee nowarn' and `.ieee warn' directives as well to set and clear the IEEE Std 754 warning flag respectively in the SHT_MIPS_ABIFLAGS section. Their corresponding command-line options will be `-mieee=nowarn' and `-mieee=warn' respectively. For the GNU Compiler Collection (GCC) the following target-specific command-line options will be accepted: * `-mieee=strict', making the toolchain produce `strict' binaries, * `-mieee=relaxed-exec', making the toolchain produce `strict' shared libraries and `relaxed' executables, * `-mieee=relaxed', making the toolchain produce `relaxed' binaries, * `-mieee=force-relaxed', making the toolchain produce `relaxed' binaries, while suppressing IEEE Std 754 static linking warnings. Any or all of these options may have target-specific effects beyond propagating the IEEE Std 754 compliance mode down to the assembler and the linker. It is expected that `-mieee=strict' and `-mieee=relaxed-exec' options will be set by appropriate generic `-fieee' options, to be defined, which will be also available for selection as configuration defaults at the GCC build time. It is also expected that along `-mieee=strict' the relevant `-fieee' option and its corresponding configuration default will set the compiler into a mode in which it will produce strictly compliant code, which in the context of this specification is defined as: following IEEE Std 754 as closely as the programming language binding to the standard (defined in the relevant language standard), the compiler implementation and target hardware permit. This means that the use of `-fieee' options may affect code produced in ways beyond NaN representation only. There may be further GCC options to control IEEE Std 754 compliance, to be defined. 5. Future Considerations While at the time of this writing the `strict' and `relaxed' IEEE Std 754 compliance modes only apply to NaN representation patterns, it is possible that in the future other IEEE Std 754 compliance matters may require communicating through linking and loading down to the operating system kernel. Therefore a decision has been made to use generic names for the modes, macros, directives and option names defined here. If such a need arises in the future, then the meaning of these names may be extended to cover other compliance aspects and further modes can be added that are intermediate between `strict' and `relaxed', to be used with the `.ieee' directive and the `-mieee=' command-line options. References: [1] "SYSTEM V APPLICATION BINARY INTERFACE, MIPS RISC Processor Supplement, 3rd Edition", Section "Process Stack", pp. 3-33, 3-34
