Autodoc corrections.
[cake.git] / README.new.ppc
blob944930528c25933974cb312f55e5d0cd86263203
1 Here are some modifications of AROS structure.
3 !NOTE!
4 ------
5 This version of Aros build for ppc machines, requires gcc version 3.2 or
6 newer. It requires also some patching in compiler as it uses "stackparm"
7 function attribute proposed by Fabio and extended by me.
9 configure.in
10 ------------
11 New target is added. Currently, in order to build Aros for PReP (PowerPC
12 Reference Platform) machine, one can specify either --target=prep if the
13 code is compiled on PPC based machine, or --target=prep-cross, if the
14 code is compiled on other architecture (like x86 for example).
16 config/target.cfg.in
17 --------------------
18 Added some target related definitions for objcopy, objdump and strip.
20 Directory layout
21 ----------------
22 New directories are added. The "arch" is containing stuff which varies
23 between different architectures. /arch/common contains code which may be
24 shared between different architectures and platforms. /arch/ppc contains
25 all ppc-reladed files. Similarly, /arch/ppc/prep contains PReP specific
26 code, /arch/ppc/chrp contains CHRP (and probably also Pegasos!) related
27 code, while /arch/ppc/common contains common code shared among this 
28 platforms.
30 /drivers directory is supposed to contain hardware-independant drivers 
31 shared among platforms. They cannot contain and direct IO/Bus activity.
32 Everything *HAS TO* be passed through openpci.library and kernel.resource.
33 Breaking this rule may produce driver which is totally unusable, so don't
34 do that!
36 /kernel directory contains all the things that are needed to launch the
37 kernel. Please note, that by term "kernel" I understand such piece of 
38 software, which is able to maintain multitasking, memory, messaging system
39 and perhaps basic low-level activity. It means in Aros case the following
40 modules:
42 * exec.library
43 * kernel.resource
44 * openpci.library
46 Later modifications of this list are possible. Note, that all other modules
47 may be loaded by bootstrap code (bootstrap talking with OpenFirmware in case
48 of PPC machines).
50 Please note, that this version of exec.library doesn't allow any function
51 replacing. It is also not functional. IT WILL NOT WORK without kernel.resource!
52 Another important issue is, that this version of exec is suppost to have
53 API which is 100% compatible with AmigaOS 3.1. Some additional functions are
54 also provided. See docs for more details.
57 System Calling ABI
58 ------------------
59 In order to allow future m68k emulation, special ABI is proposed for PPC
60 machines. With exception of varargs functions, the new ABI doesn't require
61 any changes in gcc.
63 The Include/aros/abi.h contains CallOS structure definition. It is used to
64 pass parameters to all functions in libraries/devices/resources. It is also
65 used to pass parameters to functions which are expecting them in given m68k
66 virtual registers. Every task contains its own CallOS structure with r2
67 pointing to it. You may ever trust the contents of %r2 and you shoud never
68 modify it!
70 In order to pass return value in m68k-like virtual register D0, there is also
71 return(val) macro defined if compiling kernel-related code (__KERNEL__ symbol
72 defined)
74 the Include/asm/macros.h contains some usefull macros. Few of them make some
75 effect on non-ppc architectures only. Important one is STACKPARM, which is
76 used for functions expecting their parameters on the stack.
78 Startup
79 -------
80 Because of lack of any stardart regarding parameter passing to kernel, I have
81 written bootstrap code which talks directly with OpenFirmware, and delivers
82 to kernel parameters in the same form as GRUB does. Because it's not too
83 handy to fabricate them, we could provide our own standard. The startup is
84 responsible for setting the machine correctly up, and fire the kernel. Exec's
85 entry point is now
87 void STDCALL NORETURN LaunchKernel(ULONG, ULONG);
89 where the two parameters passed have the same meaning as by Multiboot standard.
90 Allthough this is not yet fulfilled, the startup code has to exclude kernel
91 from memory map delivered to LaunchKernel code. It's just easier to do on the
92 architecture specific side than later from running exec.
94 Configuration memory
95 --------------------
96 The kernel contains two different configuration memory areas, which has to be
97 writable. The configuration areas should be locked after the initialization.
98 The memory map and bootloader informations are stored inside, together with 
99 information about loaded modules and memory areas which has to be scanned by
100 RomTag scanner.
102 This area is (or has to be) the only writable part of kernel. It may be
103 redirected to RAM on embedded systems (only the linking rule has to be
104 changed).
106 Please note, that allthough kernel supports .bss section clearing, it's not
107 welcomed in code. If AmigaOS kickstart was able to live without, we can also!
109 Porting to other architectures
110 ------------------------------
111 In order to port Aros to other architectures, one has to:
113 * write few include files describing new platform/architecture
114 * write bootstrap code which will deliver some basic system information to
115   kernel
116 * write kernel.resource, which will take some original exec's job (like
117   creating first task, handling interrupts and so on) and will patch the exec
118   library so that it be 100% usable.
120 If only hardware drivers are here, it should work then.