Contents of /trunk/mkinitrd-magellan/klibc/usr/klibc/arch/README

To port klibc to a new architecture, you need:

a) A directory structure

Each archtecture has a klibc/arch/ directory, which should include an
MCONFIG and a Makefile.inc file, and an include/arch/ directory, which
includes some architecture-specific header files, including
klibc/archconfig.h.


b) Architecture-specific configuration
   (include/arch/*/klibc/sysconfig.h)

This file can set configuration variables from
include/klibc/sysconfig.h.


c) Startup code
   (klibc/arch/*/crt0.S)

The crt0.S assembly routine typically corresponds to the following
pseudo-C code.  In addition, each architecture needs any support
routines that gcc-generated code expects to find in the system library
-- Alpha, for example, needs divide subroutines.

The "getenvtest" test program is a very good test for proper crt0.S
functionality.


extern __noreturn __libc_init(void *, void *);

__noreturn _start(void)
{
  void *elf_data   = get_elf_data_address(); /* Usually the stack address */
  void *atexit_ptr = get_atexit_ptr();       /* Usually in a register */

  /* Some architectures need this for debugging to work */
  setup_null_stack_frame_if_necessary();

  __libc_init(elf_data, atexit_ptr);
}


d) A setenv implementation
   (klibc/arch/*/setjmp.S, include/arch/*klibc/archsetjmp.h)

On most (but not all!) architectures, this entails creating a setjmp
buffer big enough to hold all callee-saved registers, plus the stack
pointer and the return address.  In setjmp.S you have:

* A "setjmp" function that writes out the callee-saved registers, the
  stack pointer and the return address to the buffer pointed to by the
  first argument, and then returns zero normally.

  On some architectures you need to take some kind of action to make
  sure the contents of the stack is actually manifest in memory and
  not cached in the CPU.  In some cases (e.g. on SPARC) this will
  automatically spill the registers onto the stack; then they don't
  need to be spilled into the jmp_buf.

* A "longjmp" function that read back these same registers from the
  jmp_buf pointed to by the first argument, and returns the second
  argument *to the address specified in the jmp_buf*.

  On some architectures you need to take some kind of action to flush
  any cached stack data or return stack.


e) Any support functions needed by gcc, *unless* they are in libgcc
  *and* libgcc is usable for klibc on your particular platform.  If
  libgcc isn't usable for klibc (on MIPS, for example, libgcc is
  compiled in a way that is not compatible with klibc) there are
  reasonably good clones of most of the libgcc functions in the libgcc
  directory.  To use them, add them to ARCHOBJS in
  klibc/arch/*/Makefile.inc.


f) A link location for the shared klibc.  This should be specified in
  SHAREDFLAGS in klibc/arch/*/MCONFIG.

  This is not applicable to no-MMU architectures.
1	To port klibc to a new architecture, you need:
2
3	a) A directory structure
4
5	Each archtecture has a klibc/arch/ directory, which should include an
6	MCONFIG and a Makefile.inc file, and an include/arch/ directory, which
7	includes some architecture-specific header files, including
8	klibc/archconfig.h.
9
10
11	b) Architecture-specific configuration
12	(include/arch/*/klibc/sysconfig.h)
13
14	This file can set configuration variables from
15	include/klibc/sysconfig.h.
16
17
18	c) Startup code
19	(klibc/arch/*/crt0.S)
20
21	The crt0.S assembly routine typically corresponds to the following
22	pseudo-C code. In addition, each architecture needs any support
23	routines that gcc-generated code expects to find in the system library
24	-- Alpha, for example, needs divide subroutines.
25
26	The "getenvtest" test program is a very good test for proper crt0.S
27	functionality.
28
29
30	extern __noreturn __libc_init(void , void );
31
32	__noreturn _start(void)
33	{
34	void elf_data = get_elf_data_address(); / Usually the stack address */
35	void atexit_ptr = get_atexit_ptr(); / Usually in a register */
36
37	/* Some architectures need this for debugging to work */
38	setup_null_stack_frame_if_necessary();
39
40	__libc_init(elf_data, atexit_ptr);
41	}
42
43
44	d) A setenv implementation
45	(klibc/arch//setjmp.S, include/arch/klibc/archsetjmp.h)
46
47	On most (but not all!) architectures, this entails creating a setjmp
48	buffer big enough to hold all callee-saved registers, plus the stack
49	pointer and the return address. In setjmp.S you have:
50
51	* A "setjmp" function that writes out the callee-saved registers, the
52	stack pointer and the return address to the buffer pointed to by the
53	first argument, and then returns zero normally.
54
55	On some architectures you need to take some kind of action to make
56	sure the contents of the stack is actually manifest in memory and
57	not cached in the CPU. In some cases (e.g. on SPARC) this will
58	automatically spill the registers onto the stack; then they don't
59	need to be spilled into the jmp_buf.
60
61	* A "longjmp" function that read back these same registers from the
62	jmp_buf pointed to by the first argument, and returns the second
63	argument to the address specified in the jmp_buf.
64
65	On some architectures you need to take some kind of action to flush
66	any cached stack data or return stack.
67
68
69	e) Any support functions needed by gcc, unless they are in libgcc
70	and libgcc is usable for klibc on your particular platform. If
71	libgcc isn't usable for klibc (on MIPS, for example, libgcc is
72	compiled in a way that is not compatible with klibc) there are
73	reasonably good clones of most of the libgcc functions in the libgcc
74	directory. To use them, add them to ARCHOBJS in
75	klibc/arch/*/Makefile.inc.
76
77
78	f) A link location for the shared klibc. This should be specified in
79	SHAREDFLAGS in klibc/arch/*/MCONFIG.
80
81	This is not applicable to no-MMU architectures.