porting.rst

  1=======
  2Porting
  3=======
  4
  5Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html
  6
  7Initial definitions
  8-------------------
  9
 10The following symbol definitions rely on you knowing the translation that
 11__virt_to_phys() does for your machine.  This macro converts the passed
 12virtual address to a physical address.  Normally, it is simply:
 13
 14		phys = virt - PAGE_OFFSET + PHYS_OFFSET
 15
 16
 17Decompressor Symbols
 18--------------------
 19
 20ZTEXTADDR
 21	Start address of decompressor.  There's no point in talking about
 22	virtual or physical addresses here, since the MMU will be off at
 23	the time when you call the decompressor code.  You normally call
 24	the kernel at this address to start it booting.  This doesn't have
 25	to be located in RAM, it can be in flash or other read-only or
 26	read-write addressable medium.
 27
 28ZBSSADDR
 29	Start address of zero-initialised work area for the decompressor.
 30	This must be pointing at RAM.  The decompressor will zero initialise
 31	this for you.  Again, the MMU will be off.
 32
 33ZRELADDR
 34	This is the address where the decompressed kernel will be written,
 35	and eventually executed.  The following constraint must be valid:
 36
 37		__virt_to_phys(TEXTADDR) == ZRELADDR
 38
 39	The initial part of the kernel is carefully coded to be position
 40	independent.
 41
 42INITRD_PHYS
 43	Physical address to place the initial RAM disk.  Only relevant if
 44	you are using the bootpImage stuff (which only works on the old
 45	struct param_struct).
 46
 47INITRD_VIRT
 48	Virtual address of the initial RAM disk.  The following  constraint
 49	must be valid:
 50
 51		__virt_to_phys(INITRD_VIRT) == INITRD_PHYS
 52
 53PARAMS_PHYS
 54	Physical address of the struct param_struct or tag list, giving the
 55	kernel various parameters about its execution environment.
 56
 57
 58Kernel Symbols
 59--------------
 60
 61PHYS_OFFSET
 62	Physical start address of the first bank of RAM.
 63
 64PAGE_OFFSET
 65	Virtual start address of the first bank of RAM.  During the kernel
 66	boot phase, virtual address PAGE_OFFSET will be mapped to physical
 67	address PHYS_OFFSET, along with any other mappings you supply.
 68	This should be the same value as TASK_SIZE.
 69
 70TASK_SIZE
 71	The maximum size of a user process in bytes.  Since user space
 72	always starts at zero, this is the maximum address that a user
 73	process can access+1.  The user space stack grows down from this
 74	address.
 75
 76	Any virtual address below TASK_SIZE is deemed to be user process
 77	area, and therefore managed dynamically on a process by process
 78	basis by the kernel.  I'll call this the user segment.
 79
 80	Anything above TASK_SIZE is common to all processes.  I'll call
 81	this the kernel segment.
 82
 83	(In other words, you can't put IO mappings below TASK_SIZE, and
 84	hence PAGE_OFFSET).
 85
 86TEXTADDR
 87	Virtual start address of kernel, normally PAGE_OFFSET + 0x8000.
 88	This is where the kernel image ends up.  With the latest kernels,
 89	it must be located at 32768 bytes into a 128MB region.  Previous
 90	kernels placed a restriction of 256MB here.
 91
 92DATAADDR
 93	Virtual address for the kernel data segment.  Must not be defined
 94	when using the decompressor.
 95
 96VMALLOC_START / VMALLOC_END
 97	Virtual addresses bounding the vmalloc() area.  There must not be
 98	any static mappings in this area; vmalloc will overwrite them.
 99	The addresses must also be in the kernel segment (see above).
100	Normally, the vmalloc() area starts VMALLOC_OFFSET bytes above the
101	last virtual RAM address (found using variable high_memory).
102
103VMALLOC_OFFSET
104	Offset normally incorporated into VMALLOC_START to provide a hole
105	between virtual RAM and the vmalloc area.  We do this to allow
106	out of bounds memory accesses (eg, something writing off the end
107	of the mapped memory map) to be caught.  Normally set to 8MB.
108
109Architecture Specific Macros
110----------------------------
111
112BOOT_MEM(pram,pio,vio)
113	`pram` specifies the physical start address of RAM.  Must always
114	be present, and should be the same as PHYS_OFFSET.
115
116	`pio` is the physical address of an 8MB region containing IO for
117	use with the debugging macros in arch/arm/kernel/debug-armv.S.
118
119	`vio` is the virtual address of the 8MB debugging region.
120
121	It is expected that the debugging region will be re-initialised
122	by the architecture specific code later in the code (via the
123	MAPIO function).
124
125BOOT_PARAMS
126	Same as, and see PARAMS_PHYS.
127
128FIXUP(func)
129	Machine specific fixups, run before memory subsystems have been
130	initialised.
131
132MAPIO(func)
133	Machine specific function to map IO areas (including the debug
134	region above).
135
136INITIRQ(func)
137	Machine specific function to initialise interrupts.