2 files changed, 209 insertions, 0 deletions

diff --git a/Documentation/mn10300/ABI.txt b/Documentation/mn10300/ABI.txt
new file mode 100644
index 000000000000..1fef1f06dfd2
--- /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 000000000000..8958b51dac4b
--- /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.