The Colilo HOWTO
Ken Treis (ken@reasonability.net)
Last updated: Fri May 2 09:15:00 PDT 2003
1. Acknowledgements
The colilo bootloader was originally written by Greg Ungerer, although it was not known by that name until Chris Johns took over maintenance of the code. Chris named the bootloader "CoLiLo", for "ColdFire Linux Loader". It was later updated by Ken Treis, Travis Griggs, and Steve Wagner.
Ken Treis is the current maintainer. Never being one who liked mixed-case acronyms, Ken renamed the bootloader to "colilo", dropping the reference to Linux because the bootloader is not at all Linux-specific. Colilo can boot Linux, a second-stage bootloader (such as PPCboot), or any other basic ColdFire program.
Contributions have also been made by a number of others, as indicated in colilo's Changelog file.
2. Disclaimer and License
Colilo is covered by the GNU General Public License (GPL). You should have received a copy of the GPL along with this program source code (see the file called COPYING). If not, you can always find it at http://www.gnu.org/copyleft/gpl.html.
3. Introduction
3.1 What is Colilo?
The ColdFire Linux Loader (colilo) is a bootloader for embedded systems based on the Motorola ColdFire processor. As the name implies, it is primarily used to boot uClinux. However, no colilo code is uClinux-specific, and it should be quite possible to boot other ColdFire operating systems using colilo.
3.2 How Does Colilo Work?
After a ColdFire reset, the ColdFire begins to execute code beginning at address 0x400 from the memory on Chip Select (CS) 0. This is usually a flash memory, and the entry point of colilo resides at this address.
Colilo configures the CS registers on the ColdFire. These describe a mapping between address ranges in the ColdFire's 32-bit address space and the memory chips wired on the board. There are also some registers that control SDRAM (which is usually on CS7). Configuration of the CS and SDRAM control registers is board-specific (see board.c for details).
Next, colilo sets up a proper C execution environment for itself. This involves copying any initialized data out of flash and into SDRAM and zeroing the area of SDRAM (known as the BSS) that contains uninitialized variable data.
Once the C environment is set up, colilo expands a gzip-compressed operating system image into SDRAM. The source address (of the compressed data in flash) and destination address (in SDRAM) are also board-specific (see board.c, setImageParams(), source_addr and dest_addr).
Lastly, it begins executing the operating system code in SDRAM.
4. Configuring and Building Colilo
Colilo's configuration mechanism is rather primitive, but there really isn't much to configure in a simple bootloader such as this. All configuration options are set in the top-level Makefile, so you must edit the Makefile in order to change configurations.
4.1 Selecting Architecture and Board
The first three definitions in the colilo Makefile specify the architecture- and board-specific source files.
- ARCH Specifies a directory under arch/ for the target board's ColdFire architecture. For example, a board that uses the ColdFire 5272 chip would set ARCH to 5272. Currently supported architectures can by viewing a directory listing of the arch/ subdirectory.
- VENDOR and BOARD Specifies a directory under vendors/ (specifically, vendors/VENDOR/BOARD). This directory contains board-specific source code and linker command scripts. Explore the vendors/ tree to view possible combinations.
TODO: add a check to the Makefile; make sure that these directories exist and provide a helpful message if they don't. This is too easy to mess up with a typo.
4.2 Configuration Options
- CONFIG_FLASH Specifies whether to link using the flash.ld or ram.ld file. Unless you're debugging colilo, you probably want to enable this option (and thus build colilo to run from flash).
- BOOTDEBUG Provide additional diagnostic output while booting. Useful during development, because colilo tells you what it's doing.
- CONFIG_UI Provide a basic command-interpreter interface. Can also be useful during development. If you don't have an operating system image to boot and you simply want to see colilo work, turn this option on. Implies BOOTDEBUG. Warning: this code needs some work; no guarantee that all functions work. Note also that you may not have enough flash to do this, or you might have to tweak the flash.ld file.
- MCF_FAST_CLK Make the 5249 run at 140MHz, the default is 72MHz. (This option only works with the 5249)
4.3 Building Colilo
Type make and press Enter. This builds a files called colilo.elf, colilo.bin, and colilo.s19.
Other make options here; make clean is the only one so far; maybe should add make colilo.S for assembly dump
5. Installing Colilo
Of course, it can't do much without an operating system image also having been installed. You can set CONFIG_UI, though, and play with the colilo UI a little.
5.1 Using the P&E Micro Flash Programmer (PROGCFZ)
Warning: this clobbers dBUG on eval boards. Thankfully, you can always download it again from Motorola.
- Open the programmer.
- Select a flash algorithm. This is dependent on your flash chip, and you can download a lot of them from pemicro.com.
- Specify a base address. See vendors/VENDOR/BOARD/Makefile, i.e. ffe00000 for the 5272C3.
- Erase Module. This can take a minute or two.
- Specify S-Record. (colilo.s19)
- Program Module.
If you have not yet programmed an S-record for your operating system, you should do so now. The S-record file needs to have its addresses adjusted into the proper range in order for the flash programmer. If, for example, you're using uClinux and your source address is 0xffe40000, then your S-record operating system file should be created like this:
gzip -9 image.bin m68k-elf-objcopy -I binary -O srec --adjust-vma 0xffe40000 image.bin.gz imagegz.s19You can then program the imagegz.s19 file with:
- Specify S-Record (imagegz.s19)
- Program Module
6. Porting Colilo to New Hardware
6.1 New ColdFire Architectures
To port colilo to a new ColdFire architecture (for example, to the 5407 -- any volunteers?), you need to make a new directory under arch/. Add an arch.h and cache.S file and code them appropriately for the new chip.
6.2 New Boards
As mentioned earlier, the configuration options VENDOR and BOARD specify a directory under vendors/. To port colilo to a new board, make an appropriate directory under vendors (if necessary) and add a subdirectory for your board. Add a Makefile with the proper rules for generating the .s19 file. You then need to build a board.c file and configure the linker command files ram.ld and flash.ld appropriately.
For most board ports, you can start by copying one of the existing board configurations directories. Then, change the files as you need to.
7. Support
Colilo is an open-source project. Programmers with some experience in embedded systems should feel right at home diving into the code. However, if you need more assistance than the code itself can provide, you do have a few other options.
7.1 Email
You may always feel free to email Ken Treis, the current maintainter of colilo. You might get an answer that says, in effect, "read the code" or refers to you a website with more information. Be prepared!
7.2 Commercial Support
Reasonability offers consulting services for Coldfire-based uClinux systems and can provide commercial support for colilo.
8. Specific Boards
Colilo is an open-source project. Programmers with some experience in embedded systems should feel right at home diving into the code. However, if you need more assistance than the code itself can provide, you do have a few other options.
8.1 Motorola M5249C3
Courtesy of Jeremy Andrus (jeremy@jeremya.com):
Right now only the M5249C3-1MB board is available. This build allows CoLiLo to boot from the 1.7MB of flash designated as "user flash". The binary image created (colilo.bin) will be linked to run from 0xfff00000, and can be programed directly into flash at this address. However, the easiest way to get the image into flash is to use the 'upuser' provided by the Motorola dBUG program.
To do this, download the s-record (colilo.s19) into RAM (dn -s colilo.s19), and then use the upuser command with no options. The s-record will download into ram starting at address 0xe0000. The upuser command begins reading from RAM at 0x20000, and writing flash at 0xffe40000. By placing the colilo image at 0xe0000, we ensure that it will be written to 0xfff00000. After the image has been successfully placed in flash, move JP12 into the 2-3 position (this ties AD[21] high forcing flash accesses to the bottom half) and reset the board.
Note: You need version 3a_1b_1c of the Motorola dBUG program (released on March 4, 2003)! Previous version of dBUG did not implement the upuser command properly.
