2 files changed, 209 insertions, 0 deletions
diff --git a/kernel/Documentation/mn10300/ABI.txt b/kernel/Documentation/mn10300/ABI.txt
new file mode 100644
index 000000000..d3507bad4
--- /dev/null
+++ b/kernel/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 coalesced 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/kernel/Documentation/mn10300/compartmentalisation.txt b/kernel/Documentation/mn10300/compartmentalisation.txt
new file mode 100644
index 000000000..8958b51da
--- /dev/null
+++ b/kernel/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.