Summary:
========
-This directory contains the source code for PPCBOOT, a monitor for
+This directory contains the source code for PPCBoot, a monitor for
Embedded PowerPC boards, which can be installed in a boot ROM and
used to test the hardware or download and run application code.
-The development of PPCBOOT is closely related to Linux: some parts of
+The development of PPCBoot is closely related to Linux: some parts of
the source code originate in the Linux source tree, we still have
some header files in common, and special provision has been made to
support booting of Linux images.
- CFG_LONGHELP: Defined when you want long help messages included;
undefine this when you're short of memory.
-- CFG_PROMPT: This is what PPCBOOT prints on the console to
+- CFG_PROMPT: This is what PPCBoot prints on the console to
prompt for user input.
- CFG_CBSIZE: Buffer size for input from the Console
Building the Software:
======================
-Building PPCBOOT has been tested in native PPC environments (on a
+Building PPCBoot has been tested in native PPC environments (on a
PowerBook G# running LinuxPPC 2000) and in cross environments
(running RedHat 6.0 and 6.2 Linux on x86, and Solaris 2.6 on a
SPARC).
-Especially after installing the PPCBOOT sources to a new directory
+Especially after installing the PPCBoot sources to a new directory
hierarchy it is important to re-build all Makefile dependencies by
running:
For now: just type "help <command>".
+Environment Variables:
+======================
+
+PPCBoot supports user configuration using Environment Variables which
+can be made persistent by saving to Flash memory.
+
+Environment Variables are set using "setenv", printed using
+"printenv", and saved to Flash using "saveenv". Using "setenv"
+without a value can be used to delete a variable from the
+environment. As long as you don't save the environment you are
+working with an in-memory copy. In case the Flash area containing the
+environment is erased by accident, a default environment is provided.
+
+Some configuration options can be set using Environment Variables:
+
+bootdelay - see CONFIG_8xx_BOOTDELAY
+bootcmd - see CONFIG_8xx_BOOTCOMMAND
+baudrate - see CONFIG_8xx_BAUDRATE
+bootargs - Boot arguments when booting an RTOS image
+
+There are two special Environment Variables:
+
+serial# - contains hardware identification information such
+ as type string and/or serial number
+ethaddr - Ethernet address
+
+These variables can be set only once (usually during manufacturing of
+the board). PPCBoot refuses to delete or overwrite these variables
+once they have been set once.
+
+Please note that changes to configuration parameters usually take
+only effect after the next boot (yes, that's just like Windoze :-).
+
+
+
Image Formats:
==============
Linux Support:
==============
-Although PPCBOOT should support any OS or standalone application
+Although PPCBoot should support any OS or standalone application
easily, Linux has always been in the focus during the design of
-PPCBOOT.
+PPCBoot.
-PPCBOOT includes many features that so far have been part of some
+PPCBoot includes many features that so far have been part of some
special "boot loader" code within the Linux kernel. Also, any
"initrd" images to be used are no longer part of one big Linux image;
instead, kernel and "initrd" are separate images. This implementation
Flash memory footprint)
- it becomes much easier to port new Linux kernel versions because
- lots of low-level, hardware dependend stuff are done by PPCBOOT
+ lots of low-level, hardware dependend stuff are done by PPCBoot
- the same Linux kernel image can now be used with different "initrd"
images; of course this also means that different kernel images can
Linux HOWTO:
============
-Porting Linux to PPCBOOT based systems:
+Porting Linux to PPCBoot based systems:
---------------------------------------
-PPCBOOT cannot save you from doing all the necessary modifications to
+PPCBoot cannot save you from doing all the necessary modifications to
configure the Linux device drivers for use with your target hardware
(no, we don't intend to provide a full virtual machine interface to
Linux :-).
Configuring the Linux kernel:
-----------------------------
-No specific requirements for PPCBOOT. Make sure you have some root
+No specific requirements for PPCBoot. Make sure you have some root
device (initial ramdisk, NFS) for your target system.
Building a Linux Image:
-----------------------
-No specific requirements for PPCBOOT. There is no need to add a
+No specific requirements for PPCBoot. There is no need to add a
"ramdisk.image.gz" file when building the kernel, even when you
intend to run it with initial ramdisk.
There is a special tool (in 'tools/mkimage') to encapsulate this
image with header information, CRC32 checksum etc. for use with
-PPCBOOT:
+PPCBoot:
In the first form (with "-l" option) mkimage lists the information
-contained in the header of an existing PPCBOOT image; this includes
+contained in the header of an existing PPCBoot image; this includes
checksum verification:
tools/mkimage -l image
-l ==> list image header information
-The second form (with "-d" option) is used to build a PPCBOOT image
+The second form (with "-d" option) is used to build a PPCBoot image
from a "data file" which is used as image payload:
tools/mkimage -A arch -O os -T type -C comp -a addr -e ep \
Right now, all Linux kernels use the same load address (0x00000000)
and entry point address (0x0000000C). So a typical call to build a
-PPCBOOT image would read:
+PPCBoot image would read:
-> tools/mkimage -n '2.2.13 for initrd on TQM850L' \
> -A ppc -O linux -T kernel -C gzip -a 00000000 -e 0000000C \
Entry Point: 0x0000000c
-Similar you can build PPCBOOT images from a 'ramdisk.image.gz' file
+Similar you can build PPCBoot images from a 'ramdisk.image.gz' file
when your kernel is intended to use an initial ramdisk:
-> tools/mkimage -n 'Simple Ramdisk Image' \
Installing a Linux Image:
-------------------------
-To downloading a PPCBOOT image over the serial (console) interface,
+To downloading a PPCBoot image over the serial (console) interface,
you must convert the image to S-Record format:
objcopy -I binary -O srec examples/image examples/image.srec
-The 'objcopy' does not understand the information in the PPCBOOT
+The 'objcopy' does not understand the information in the PPCBoot
image header, so the resulting S-Record file will be relative to
address 0x00000000. To load it to a given address, you need to
specify the target address as 'offset' parameter with the 'loads'
Standalone HOWTO:
=================
-One of the features of PPCBOOT is that you can dynamically load and
+One of the features of PPCBoot is that you can dynamically load and
run "standalone" applications, which can use some resources of
-PPCBOOT like console I/O functions or interrupt services.
+PPCBoot like console I/O functions or interrupt services.
Two simple examples are included with the sources:
-------------------
'examples/hello_world.c' contains a small "Hello World" Demo
-application; it is automatically compiled when you build PPCBOOT.
+application; it is automatically compiled when you build PPCBoot.
It's configured to run at address 0x00040004, so you can play with it
like that:
## Application terminated, rc = 0x0
Another example, which demonstrates how to register a CPM interrupt
-handler with the PPCBOOT code, can be found in 'examples/timer.c'.
+handler with the PPCBoot code, can be found in 'examples/timer.c'.
Here, a CPM timer is set up to generate an interrupt every second.
The interrupt service routine is trivial, just printing a '.'
character, but this is just a demo program. The application can be
The following is not intended to be a complete description of every
implementation detail. However, it should help to understand the
-inner workings of PPCBOOT and make it easier to port it to custom
+inner workings of PPCBoot and make it easier to port it to custom
hardware.
Memory Management:
------------------
-PPCBOOT runs in system state and uses physical addresses, i.e. the
+PPCBoot runs in system state and uses physical addresses, i.e. the
MMU is not used either for address mapping nor for memory protection.
The available memory is mapped to fixed addresses usuing the memory
memory type (Flash, SDRAM, SRAM), even when it consists out of
several physical memory banks.
-PPCBOOT is installed in the first 128 kB of the first Flash bank (on
+PPCBoot is installed in the first 128 kB of the first Flash bank (on
TQM8xxL modules this is the range 0x40000000 ... 0x4001FFFF). After
booting and sizing and initializing DRAM, the code relocates itself
-to the upper end of DRAM. Immediately below the PPCBOOT code some
+to the upper end of DRAM. Immediately below the PPCBoot code some
memory is reserved for use by malloc() [see CFG_MALLOC_LEN
configuration setting]. Below that, a structure with global Board
Info data is placed, followed by the stack (growing downward).
System Initialization:
----------------------
-In the reset configuration, PPCBOOT starts at address 0x00000100.
+In the reset configuration, PPCBoot starts at address 0x00000100.
Because of the reset configuration for CS0# this is a mirror of the
-onboard Flash memory. To be able to re-map memory PPCBOOT then jumps
+onboard Flash memory. To be able to re-map memory PPCBoot then jumps
to it's link address. To be able to implement the initialization code
in C, a (small!) initial stack is set up in the internal Dual Ported
-RAM of the MPC8xx. After that, PPCBOOT initialises the CPU core, the
+RAM of the MPC8xx. After that, PPCBoot initialises the CPU core, the
caches and the SIU.
Next, all (potentially) available memory banks are mapped using a
projects / users / rw / ppcboot.git / commitdiff