Merge pull request #196 from riscv-non-isa/mapping-symbol

Proposal: Add mapping symbol

Author: kito-cheng

riscv-elf.adoc

@@ -1164,6 +1164,44 @@ Merge policy:::
 The linker should report errors if object files of different privileged
 specification versions are merged.
 
+
+=== Mapping Symbol
+
+The section can have a mixture of code and data or code with different ISAs.
+A number of symbols, named mapping symbols, describe the boundaries.
+
+[%autowidth]
+|===
+| Symbol Name | Meaning
+| $d          | Start of a sequence of data.
+| $x          | Start of a sequence of instructions.
+| $x<ISA>     | Start of a sequence of instructions with <ISA> extension.
+|===
+
+The mapping symbol should set the type to `STT_NOTYPE`, binding to `STB_LOCAL`,
+and the size of symbol to zero.
+
+The mapping symbol for data(`$d`) indicates the start of a sequence of data bytes.
+
+The mapping symbol for instruction(`$x`) indicates the start of a sequence of
+instructions.
+and it has an optional ISA string, which means the following code regions are
+using ISA is different than the ISA recorded in the arch attribute;
+the ISA information will used until the next instruction mapping symbol;
+an instruction mapping symbol without ISA string means using ISA configuration
+from ELF attribute.
+
+Format and rule of the optional ISA string are same as `Tag_RISCV_arch`, must
+having explicit version, more detailed rule please refer to <<Attributes>>.
+
+NOTE: The use case for mapping symbol for instruction(`$x`) with ISA information
+is used with ifunc, e.g. libraries are built with `rv64gc`, but few functions
+like memcpy provides two versions, one built with `rv64gc`, and one built with
+`rv64gcv`, and select by ifunc mechanism at run-time; however, the arch
+attribute is recording for minimal execution environment requirements, so the
+ISA information from arch attribute is not enough for the disassembler to
+disassemble the `rv64gcv` version correctly.
+
 == Linker Relaxation
 
 At link time, when all the memory objects have been resolved, the code sequence