aboutsummaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/mn10300/ABI.txt149
-rw-r--r--Documentation/mn10300/compartmentalisation.txt60
2 files changed, 209 insertions, 0 deletions
diff --git a/Documentation/mn10300/ABI.txt b/Documentation/mn10300/ABI.txt
new file mode 100644
index 00000000000..1fef1f06dfd
--- /dev/null
+++ b/Documentation/mn10300/ABI.txt
@@ -0,0 +1,149 @@
+ =========================
+ MN10300 FUNCTION CALL ABI
+ =========================
+
+=======
+GENERAL
+=======
+
+The MN10300/AM33 kernel runs in little-endian mode; big-endian mode is not
+supported.
+
+The stack grows downwards, and should always be 32-bit aligned. There are
+separate stack pointer registers for userspace and the kernel.
+
+
+================
+ARGUMENT PASSING
+================
+
+The first two arguments (assuming up to 32-bits per argument) to a function are
+passed in the D0 and D1 registers respectively; all other arguments are passed
+on the stack.
+
+If 64-bit arguments are being passed, then they are never split between
+registers and the stack. If the first argument is a 64-bit value, it will be
+passed in D0:D1. If the first argument is not a 64-bit value, but the second
+is, the second will be passed entirely on the stack and D1 will be unused.
+
+Arguments smaller than 32-bits are not coelesced within a register or a stack
+word. For example, two byte-sized arguments will always be passed in separate
+registers or word-sized stack slots.
+
+
+=================
+CALLING FUNCTIONS
+=================
+
+The caller must allocate twelve bytes on the stack for the callee's use before
+it inserts a CALL instruction. The CALL instruction will write into the TOS
+word, but won't actually modify the stack pointer; similarly, the RET
+instruction reads from the TOS word of the stack, but doesn't move the stack
+pointer beyond it.
+
+
+ Stack:
+ | |
+ | |
+ |---------------| SP+20
+ | 4th Arg |
+ |---------------| SP+16
+ | 3rd Arg |
+ |---------------| SP+12
+ | D1 Save Slot |
+ |---------------| SP+8
+ | D0 Save Slot |
+ |---------------| SP+4
+ | Return Addr |
+ |---------------| SP
+ | |
+ | |
+
+
+The caller must leave space on the stack (hence an allocation of twelve bytes)
+in which the callee may store the first two arguments.
+
+
+============
+RETURN VALUE
+============
+
+The return value is passed in D0 for an integer (or D0:D1 for a 64-bit value),
+or A0 for a pointer.
+
+If the return value is a value larger than 64-bits, or is a structure or an
+array, then a hidden first argument will be passed to the callee by the caller:
+this will point to a piece of memory large enough to hold the result of the
+function. In this case, the callee will return the value in that piece of
+memory, and no value will be returned in D0 or A0.
+
+
+===================
+REGISTER CLOBBERING
+===================
+
+The values in certain registers may be clobbered by the callee, and other
+values must be saved:
+
+ Clobber: D0-D1, A0-A1, E0-E3
+ Save: D2-D3, A2-A3, E4-E7, SP
+
+All other non-supervisor-only registers are clobberable (such as MDR, MCRL,
+MCRH).
+
+
+=================
+SPECIAL REGISTERS
+=================
+
+Certain ordinary registers may carry special usage for the compiler:
+
+ A3: Frame pointer
+ E2: TLS pointer
+
+
+==========
+KERNEL ABI
+==========
+
+The kernel may use a slightly different ABI internally.
+
+ (*) E2
+
+ If CONFIG_MN10300_CURRENT_IN_E2 is defined, then the current task pointer
+ will be kept in the E2 register, and that register will be marked
+ unavailable for the compiler to use as a scratch register.
+
+ Normally the kernel uses something like:
+
+ MOV SP,An
+ AND 0xFFFFE000,An
+ MOV (An),Rm // Rm holds current
+ MOV (yyy,Rm) // Access current->yyy
+
+ To find the address of current; but since this option permits current to
+ be carried globally in an register, it can use:
+
+ MOV (yyy,E2) // Access current->yyy
+
+ instead.
+
+
+===============
+SYSTEM CALL ABI
+===============
+
+System calls are called with the following convention:
+
+ REGISTER ENTRY EXIT
+ =============== ======================= =======================
+ D0 Syscall number Return value
+ A0 1st syscall argument Saved
+ D1 2nd syscall argument Saved
+ A3 3rd syscall argument Saved
+ A2 4th syscall argument Saved
+ D3 5th syscall argument Saved
+ D2 6th syscall argument Saved
+
+All other registers are saved. The layout is a consequence of the way the MOVM
+instruction stores registers onto the stack.
diff --git a/Documentation/mn10300/compartmentalisation.txt b/Documentation/mn10300/compartmentalisation.txt
new file mode 100644
index 00000000000..8958b51dac4
--- /dev/null
+++ b/Documentation/mn10300/compartmentalisation.txt
@@ -0,0 +1,60 @@
+ =========================================
+ PART-SPECIFIC SOURCE COMPARTMENTALISATION
+ =========================================
+
+The sources for various parts are compartmentalised at two different levels:
+
+ (1) Processor level
+
+ The "processor level" is a CPU core plus the other on-silicon
+ peripherals.
+
+ Processor-specific header files are divided among directories in a similar
+ way to the CPU level:
+
+ (*) include/asm-mn10300/proc-mn103e010/
+
+ Support for the AM33v2 CPU core.
+
+ The appropriate processor is selected by a CONFIG_MN10300_PROC_YYYY option
+ from the "Processor support" choice menu in the arch/mn10300/Kconfig file.
+
+
+ (2) Unit level
+
+ The "unit level" is a processor plus all the external peripherals
+ controlled by that processor.
+
+ Unit-specific header files are divided among directories in a similar way
+ to the CPU level; not only that, but specific sources may also be
+ segregated into separate directories under the arch directory:
+
+ (*) include/asm-mn10300/unit-asb2303/
+ (*) arch/mn10300/unit-asb2303/
+
+ Support for the ASB2303 board with an ASB2308 daughter board.
+
+ (*) include/asm-mn10300/unit-asb2305/
+ (*) arch/mn10300/unit-asb2305/
+
+ Support for the ASB2305 board.
+
+ The appropriate processor is selected by a CONFIG_MN10300_UNIT_ZZZZ option
+ from the "Unit type" choice menu in the arch/mn10300/Kconfig file.
+
+
+============
+COMPILE TIME
+============
+
+When the kernel is compiled, symbolic links will be made in the asm header file
+directory for this arch:
+
+ include/asm-mn10300/proc => include/asm-mn10300/proc-YYYY/
+ include/asm-mn10300/unit => include/asm-mn10300/unit-ZZZZ/
+
+So that the header files contained in those directories can be accessed without
+lots of #ifdef-age.
+
+The appropriate arch/mn10300/unit-ZZZZ directory will also be entered by the
+compilation process; all other unit-specific directories will be ignored.