Linux for PowerPC Embedded Systems HOWTO Boas Betzler
21 August 2001
A distillation of the collective wisdom from the &mailinglist; on how to build an embedded PowerPC-based Linux system. Introduction This document is an attempt to tell you what you need to know to use Linux on an embedded PowerPC-based system, and is a distillation of the collective wisdom from the &mailinglist;. Comments, feedback and corrections to this document are invited via e-mail to the author. Some of the information here is in the form of references to the mailing list archives. Follow the threads in the archive to get more information. This document is laid out roughly in the order of the steps necessary to implement a complete system, which is similar to boot order starting at the lowest level and working upwards. Copyright Copyright © 2001, IBM Corp. Copyright © 2000, Canon Information Systems Research Australia. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in The views expressed here are not necessarily those of CISRA or Canon Inc or IBM Corp. Updates The latest HTML version of this document is available online at http://penguinppc.org/embedded/howto/PowerPC-Embedded-HOWTO.html If you want to print or reformat this document, you might find the SGML source useful at http://penguinppc.org/embedded/howto/PowerPC-Embedded-HOWTO.sgml Credits Based on the original HOWTO which was written by Graham Stoney, now Boas Betzler is maintaining this document. It is assembled utilising the wisdom dispensed by many others, particularly the gurus in the field: Dan Malek, Cort Dougan, Marcus Sundberg, Wolfgang Denk, Richard Hendricks, Matt Porter, Grant Erickson, Darvis Nevil, Murray Jensen, Matthew Locke and others. They deserve the credit - I doubt you'll find a more helpful group of people. Resources The most relevant net resources are: Home Page http://penguinppc.org/embedded Introductory stuff. FTP site The MontaVista FTP site is a good starting point. Mailing List http://lists.linuxppc.org/lists/linuxppc-embedded The archive contains indispensable wisdom answering most of your questions before you knew you needed to ask them. Browse it heavily. In particular, look for any articles by the individual gurus mentioned in . Unfortunately you can't search the archives by From: line to do this yet. You are encouraged to subscribe by visiting http://lists.linuxppc.org/listarcs/linuxppc-embedded/info.html However, please search the archives before asking questions. Instructions like "Search for ..." in this document refer directly to the search engine at the mailing list archives for the specified keyword. Follow the keyword link to perform the search. Home of the linux/ppc port http://penguinppc.org/ PowerPC Programming The ABI and EABI documentation describing register usage and C linkage conventions are available at: http://www.esofta.com/softspecs.html There is lots of invaluable information about optimisations for the PowerPC architecture in the IBM PowerPC Compiler Writer's Guide at: http://www.chips.ibm.com/products/powerpc/tools/compiler/cover.html Usenet Groups comp.sys.powerpc. tech PowerPC technical discussion comp.os.linux. embedded General discussion of all flavours of embedded Linux comp.arch.embedded General embedded system discussion Other Useful Resources Leif Lindholm's in-depth report on porting Linux 2.2 to a custom MPC860 platform: http://www.realtimelogic.com/staff/leif/linux/ linux_860_report.pdf.gz Matt Porter's Linux page: http://members. home.net/mmporter/linux/ LinuxPPC Solutions offered by DENX Software Engineering: http://www.denx. de/solutions-en.html Target Hardware Start by picking the processor which most closely matches your I/O requirements, and work out roughly how much RAM and ROM space you need. Then see if you can find an off-the-shelf board which also most closely matches what you need. CPU 4xx http://www.borg.umn.edu/~grant/Linux/ IBM 405GP http://www.mvista.com/news/2000/IBM_405.html, http://www-3.ibm.com/chips/techlib/techlib.nsf/products/PowerPC_405GP_Embedded_Processor , and http://www.chips.ibm.com/products/powerpc/linux/ 7xx ftp://ftp.mvista.com/pub/Area51/ppc-7xx and http://www.chips.ibm.com/products/powerpc/linux/ These devices are all covered in the MontaVista kernel. Motorola 8xx http://e-www.motorola.com/webapp/sps/prod_cat/sel_guide.jsp?catId=M98655 Information from Motorola is fragmented, because the 850/860 and 823 are handled by different groups. Information about the bits they have in common is generally equally applicable to both, so it's worth perusing the 823 resources even if you're using an 850/860. These devices are all covered in the MontaVista kernel. 823 See the 823 Engineer's Toolbox at: http://www.motorola.com/SPS/ADC/pps/subpgs/etoolbox/823/index.html 850/855/860 http://www.motorola.com/SPS/RISC/cgi-bin/ncsp/ncsp.cgi 603e See: ftp://vlab1.iram.es/pub/linux-2.2/ Motorola 82xx See http://www.mvista.com/ 8240 See ftp://ftp.mvista.com/pub/Area51/sandpoint-8240 8260 See: http://lists.linuxppc.org/listarcs/linuxppc-embedded/200002/msg00123.html and http://lists.linuxppc.org/listarcs/linuxppc-embedded/200008/msg00107.html AltiVec AltiVec is Motorola's answer to Intel's MMX. See http://www.altivec.com/ See ftp://ftp.mvista.com/pub/Area51/ppc-altivec RAM and ROM space Linux has a slightly larger memory footprint than most conventional embedded operating systems when configured with equivalent options. This is the price you pay to leverage the advantages of its enormous desktop user base, and being able to share a common desktop and embedded environment. For most applications the difference is insignificant, but if every last byte counts in your application, you might want to consider RTEMs or eCos instead. Beware that commercial embedded operating system vendors often make meaningless claims regarding the footprint of their micro-kernel, and the total memory footprint (and often the royalties payable) increases substantially once all the optional packages needed to provide the required functionality for a typical networked device are included. Work out what functionality you need before attempting to make valid comparisons. For good architectural reasons, Linux isn't a micro-kernel. However, it does allow large chunks of code to be removed easily at configuration time. In practice the architectural distinction between micro and monolithic kernels makes little difference to total memory requirements of the overall system. Minimum memory requirement when using an initrd based root filesystem is generally 2 MB of flash ROM and 8 MB of RAM, and here's what you can expect to fit in: 8xxROM Monitor Linux-2.2.13 kernel minimal compressed initrd root filesystem with /dev, /etc, /var and so forth. glibc-2.1.3 Shared C library, including pthreads support. inetd Internet server ftpd FTP server (for field flash ROM upgrades) Medium sized Embedded C++ application (~200 Kb) This is the most common configuration because it attempts to minimize ROM space at the expense of RAM, since ROM is generally more expensive. However, you can trade off ROM space to reduce RAM usage by using a compressed flash file system and/or running the kernel directly from ROM. Both these options are more difficult, but have been successfully deployed and discussed on the &mailinglist;. Commercially available boards There are many off-the-shelf options including systems from Motorola and other parties. If you're planning on building your own custom hardware, consider using one of the Single Board Computer systems listed below instead. You might get by with just a custom daughter card, or might not need to do any hardware of your own at all. All the boards listed below are known to run Linux, although the degree of support can vary. Mention to the vendor that you want to run Linux on the board, and they should be able to point you to the relevant files you need. The best supported boards are supported directly in the main kernel development tree, which is most evident by having a dedicated _MACH_... constant already assigned in include/asm-ppc/processor.h. If you still think you want to do a full custom design, pick a board from one of the following sources with the closest feature match to what you plan to kick start your software development while your custom board is being designed and built: Embedded Planet http://www.embeddedplanet.com/ These boards are officially supported by the MontaVista kernel. Use the new PlanetCore bootloader, as the old RPXU monitor times out on large tftp downloads. Linux Planet This is a complete development kit, including hardware and software. CLLF See: http://lists.linuxppc.org/listarcs/linuxppc-embedded/199910/msg00055.html CLLF-860T users should see: http://lists.linuxppc.org/listarcs/linuxppc-embedded/200001/msg00143.html Bright Star Engineering http://www.brightstareng.com/ Has an onboard FPGA for configuring hardware, making it extremely flexible for interfacing to exotic devices. They have a Linux development kit available for it too. If using a 2.2.x kernel, see: http://lists.linuxppc.org/listarcs/linuxppc-embedded/199912/msg00088.html Simple Network Magic Corporation http://www.snmc.com/ QS850 QuickStack Network Interface/Network Management Module http://www.snmc.com/products.html The QS850 is a highly integrated and compact module for adding networking features to any embedded system. It provides a complete hardware and Linux-based software solution for Internet connectivity, Network Management, and Non-volatile File System services. See QSLinux. TQComponents http://www.tqc.de/ Have a range of very small mini-modules suitable for integration in a larger system, plus a starter kit for development. Supported by Denx Software Engineering, with pictures at: http://www.denx.de/embedded-ppc-en.html Also, see: http://lists.linuxppc.org/listarcs/linuxppc- embedded/199910/msg00088.html MicroSys http://www.microsys.de/html/linux-e.html A VMEBus board vendor who now provides Linux ports for their boards. Motorola Computer Group http://www.mcg.mot.com/ MBX http://www.mcg.mot.com/cfm/templates/product.cfm?PageID=217&ProductID=51&PageTypeID=1 Before choosing this, see: http://lists.linuxppc.org/listarcs/linuxppc-embedded/200010/msg00037.html PowerPlus SBC http://members.home.net/mmporter/linux/ MVME2600 ftp://vlab1.iram.es/pub/linux-2.2/ AG Electronics http://www.agelectronics.co.uk/prod_ppc.html A range of high-performance PowerPC-based products. Force Computers http://www.forcecomputers.com/ A range of high-performance PowerPC-based products. Actis Computer - VSBC-6862 http://www.actis-computer.com VSBC-6862 http://www.actis-computer.com/asp/vsbc6862.asp?adv=100 A VME based single board computer based on the Motorola MPC8260. Total Impact - the briQ http://www.totalimpact.com/ The briQ is a PowerPC based network appliance computer the size of a standard CD-ROM drive targetted at a range of applications such as firewalls, routers, security devices and web servers. It is available with either a PowerPC 750 (G3) or 7400 (G4) processor and can run any PowerPC-based Linux distribution available. Motorola Semiconductor Family Application Development System Before you choose this one, see: http://lists.linuxppc.org/listarcs/linuxppc-embedded/199909/msg00007.html Nevertheless, it is possible to use Linux PowerPC with (F)ADS. Search for FADS. Also, see Solutions4Linux ADS/FADS 8xx: http://www.solutions4linux.de/powerpc.html Sandpoint http://www.motorola.com/SPS/PowerPC/teksupport/refdesigns/sandpoint.html Contact MontaVista software. Yellowknife http://www.motorola.com/SPS/PowerPC/teksupport/refdesigns/yk.html Contact MontaVista software . WindRiver (formerly EST Corporation) http://www.windriver.com/products/html/embed_dev_tools.html A number of development boards, including the MPC8260 based SBC8260. Haedong Information & Communications http://www.headtel.com/ MPC860 Processor Modules. Cogent Computer Systems http://www.cogcomp.com/ Modular development architecture including many varieties of PowerPC processor. Host Development Platform Embedded Linux's compelling advantage over other Embedded OS's is that your development host and target are the same. While you could theoretically develop your embedded Linux target system software on any host OS, Linux is the only sensible choice. Even Cygwin/UWIN is likely to waste more of your time. PowerPC Using a PowerPC based development host platform makes life easier, since the same binaries will run on your host and target. However, if your choice of host platform is restricted to non-PowerPC, cross compiling adds some minor inconvenience, primarily in finding or building your own toolset. You can take binaries from a standard PowerPC-based G4 Macintosh Linux distribution and run them unmodified on a PowerPC embedded system provided: The binaries are dynamically linked. You use the modified dynamic runtime glibc C library, but compiled with You include the floating point math emulator in the kernel for processors such as the 8xx series that lack a real floating point unit. Note that for floating-point intensive applications this will invoke a performance penalty over re-compiling all the binaries and libraries; but recompiling is what you're trying to avoid, right? Also note that standard Macintosh binaries won't work with the runtime library in the Hard Hat distribution on 8xx processors, because they've been compiled with to give optimum performance. In this case just use the equivalent Hard Hat binaries instead. x86 There is a mini-howto intended for developers who wish to build kernels and/or application on a Linux/x86 platform targeted for a Linux/PPC platform. Often this is desirable if one has a faster x86 host system or the target environment is not practical to host a development environment http://penguinppc.org/embedded/cross-compiling/. Wolfgang Denk also has put together a document and scripts to build a PPC Cross Development Kit for MPC8xx CPUs. His objective was to build the cross development tools to compile code for (embedded) PowerPC systems using Linux on an Intel PC. The documents and scripts can be found at http://www.denx.de/cdk-en.html. Compiler Toolset You'll need the GNU toolchain to compile the kernel, particularly gcc and binutils. As a general rule for working with GNU software, the latest official release is the best supported, has the most features and is usually the most stable. Also, you must use compatible versions, and there is generally no easy way to know which binutils version matches which arbitrary gcc version as their releases aren't synchronised. Hence, the best approach is generally to start by using the latest official release of any given package from your nearest GNU ftp site listed at http://www.gnu.org/order/ ftp.html Many people use a particular version simply because they already have the source for it lying around, and waste a lot of time tracking down problems that were fixed by others months or even years ago. Grab the latest version at the outset, and you'll save an enormous amount of effort. If you need newer features that are not in an official release yet, you may need to move forward to the latest development snapshot from http://sources.redhat.com Building the toolchain Instructions A set of complete instructions for building a Cross Development system for Linux/PPC is available at: http://members.home.net/mmporter/linux/cross/ Build Scripts For pre-packaged scripts to build a PPC Cross Development Kit for MPC8xx, see: ftp://ftp.denx.de/pub/LinuxPPC/usr/src/CD-README and ftp://ftp.denx.de/pub/LinuxPPC/usr/src/CDK.tar.gz SPARC/Solaris Hosted For a guide to building the PowerPC/Linux cross compiler for a SPARC/Solaris host (if you can't use a Linux development host), see: http://www.borg.umn.edu/~grant/Linux/cross.html Getting Help If you want to build a more exotic or unusual cross development environment, or need more help building the cross development tools, check out the crossgcc FAQ and mailing list at: http://www.objsw.com/CrossGCC/ gcc Check that you have the latest gcc (2.95.2). Don't waste your time with any of the egcs releases as they've now been superseded by gcc. If you're using gcc-2.95.2 with binutils-, you'll need a minor change to the gcc specs file regarding the linker emulation. You're better off just using binutils-2.10 though. binutils There are currently two branches of binutils development to choose from. Each have pro's and con's, and in many cases either one will work for you. They are typically referred to as the official "GNU binutils" and the "Linux binutils," although both are GPL'd GNU software, and both versions configure, build, and work fine on Linux. I suggest you use the official GNU version, unless you encounter a problem which requires the "Linux binutils" version. Official GNU binutils This tends to be the most stable version. The last release was 2.10, which is your best bet. It works well with gcc-2.95.2, whereas the 2.9.1 needed a tweak. If you must use the bleeding edge, the development snapshots on sources.redhat.comare quite stable. The most recent snapshot is available at ftp://sources.redhat.com/pub/binutils/snapshots/binutils.tar.bz H. J. Lu's "Linux binutils" At any given point in time, this version is based on recent official GNU development snapshot, but with more experimental features and hastily implemented bugfixes. It is shipped with many Linux distributions. However, the changes in this version aren't as thoroughly reviewed and tested as those in the official version, and the less well-implemented features probably won't make it back into the official GNU version, so it's a good idea not to rely on them. Version numbering is somewhat confusing. The Linux binutils 2.9.5.x versions are based on snapshots of the official development post 2.9.1. In particular, any given version of Linux binutils numbered 2.9.5.x is not necessarily a later version than an official GNU development snapshot numbered 2.9.1.x. Beware that Linux binutils- thru 29 will give you multiple definitions of when building glibc-2.1.2. Try the official binutils-2.10 instead, or Linux binutils- Precompiled/Prepackaged Kits There are kits available which will save you the time of building your own tools, to get bootstrapped faster. MontaVista Software Hard Hat Linux http://www.mvista.com/ http://www.hardhatlinux.com/ They have a complete 8xx cross-development kit described in ftp://ftp.mvista.com/pub/CDKit/1.2/README available at: ftp://ftp.mvista.com/pub/CDKit/1.2/ You can also purchase this kit as an integrated part of their Hard Hat Linux distribution and buy support for it directly from MontaVista. It's also available as part of the Linux Planet kit from Embedded Planet. QuickStack Linux http://qslinux.com/ ftp://qslinux.com/pub/qslinux This version of Linux is based on the PPC 2.2.5 kernel. It has been heavily modified and targeted specifically to SNMC's MPC850-based product. It includes: Subsystem for configuring and controlling I/O pins (qspin) Hardware Watchdog support Flash Filesystem (layered under Ext2FS) Compressed Ext2FS (e2compr) HDLC/PPP Driver ATM Utopia Network Driver (AAL5/IP) Multiple serial consoles Denx Software Engineering http://www.denx.de/solutions-en.html ftp site ftp://ftp.denx.de/pub/LinuxPPC/usr/src/ CD-ROMs Offer a CD-ROM with LinuxPPC for MPC8xx Systems, especially for TQM8xxL Modules. It includes: Sources and tools for a Cross Development Kit (CDK) for MPC8xx Embedded PowerPC Controllers on x86 Linux hosts Pre-built, ready-to-run binaries of the CDK Linux-2.2.13 kernel source tree for MPC8xx systems. There are also pre-built images for TQM8xxL modules. Pre-installed native LinuxPPC root filesystem with all standard Linux tools to be exported on a NFS server and used as root filesystem for Embedded PPC systems. Boards They also ship hardware with PPCboot , kernel , and root filesystem pre-installed. Just connect the power supply, and Linux is booting. The Embedded Debian Project http://www.emdebian.org/ Debian project philosophy applied to the embedded space. Especially good for developers already running Debian on the desktop. Bright Star Engineering http://www.brightstareng.com You may get a kickstart by purchasing Bright Star's SDK, particularly if you're using one of their boards. For comments, see: http://lists.linuxppc.org/listarcs/linuxppc-embedded/199912/msg00075.html Lineo Embedix http://www.lineo.com/ Lineo Embedix Linux is an embedded Linux-based software solution that adds the power and connectivity of Linux to customized embedded devices. Embedix Linux is engineered specifically for the unique speed, memory and storage requirements of embedded devices. Lineo provides embedded development kits for several PPC processors and boards. Additional information can be found at: http://www.lineo.com/products/processors/embedix_sdk/white_paper.html and http://www.lineo.com/products/embedix_sdk/datasheet.html Red Hat Embedded DevKit http://www.it.redhat.com/products/embedded/edk/ Gets you started with embedded Linux development using Red Hat Linux. The box product includes a complete toolkit with IDE and ethernet-based debugging and supports development of PowerPC architecture systems, along with the x86 architecture. Oddly enough, the minimum target CPU required by the x86 binaries in the kit is a Pentium/586, whereas the minimum desktop CPU for Red Hat Linux is only a 386. Embedded systems most often have less powerful CPUs than desktop ones, not more powerfuld ones. This mistake doesn't affect PowerPC users at all, but you might want to consider whether this supplier is the best choice given such a fundamental error. Programming the Target Beware that many commercial tools will not handle the Linux zImage correctly. They often ignore the .image and .initrd sections (containing the compressed kernel and initial ram disk images respectively), because these sections aren't marked with the LOAD attribute. Whether this is a bug in the tools or in the zImage build process is debatable. Many developers avoid the problem by simply skipping the 64K ELF header, treating the rest as a binary image and jumping to the first byte to enter the kernel loader. If you want your debugger to have access to kernel symbols, use the conventional uncompressed vmlinux ELF image rather than zImage. BDM/JTAG Downloading If your board is wired correctly, and you're using Flash memory, you can program it on your board using Background Debug Mode (BDM), described later under Debugging. BDM isn't the fastest method, but it's by far the easiest. TFTP If your ROM monitor supports Trivial File Transfer Protocol (TFTP), this is the fastest and easiest way to download code to your target during development. A a program that will hack the headers such that the VxWorks TFTP loader would load the zImage is available at: ftp://ftp.mvista.com/pub/Area51/ppc-8xx/vxhack.c Flash/EPROM Programmers You will need socketed flash to make this viable. There are sockets available even for surface mount flash devices which preserve the device footprint, but they consume extra space on your board, even when you go to production and leave them off. Some commercial EPROM programming units only support Windows, which may be a problem if you have access only to Linux machines. The Data I/O units have a terminal mode and an onboard floppy so they could be used from Linux without a problem. The general consensus is that anything with serial/parallel support and a DOS binary should be able to be used from DOSEMU. There are some options to allow direct parport access to RTFM on DOSEMU. VMWare hosting one of these should be no problem at all. Once you have a basic kernel booting on your board, you can use a flash driver to reflash a new kernel quickly. You need to be confident that the new one will boot though, or have some alternative method of recovering if it doesn't, like socketed ROMs or a BDM flash programmer. Boot Sequence The Linux boot sequence is more complicated than your average embedded operating system, and there are many more options for configuring things. In general, the boot sequence goes like this: Processor comes out of reset and branches to the ROM startup code. The ROM startup code initializes the CPU and memory controller, performing only minimal initialization of on-chip devices, such as the console serial port (typically SMC1 on 8xx devices) to provide boot diagnostic messages. It also sets up the memory map for the kernel to use in a format that is consistent across platforms, and then jumps to the boot loader. The boot loader decompresses the kernel into RAM, and jumps to it. The kernel sets up the caches, initializes each of the hardware devices via the init function in each driver, mounts the root filesystem and execs the init process, which is the ultimate parent of all user mode processes, typically /sbin/initd. Executing the first program linked against the shared C runtime library (often init) causes the shared runtime library to be loaded. In a typical Linux system, init reads /etc/inittab to execute the appropriate run control script from /etc/rc.d, which execute the start scripts to initialize networking and other system services. In minimal embedded systems, init is commonly replaced with a simple C program or shell script to start the appropriate services and application programs, since the conventional rc scripts are often overkill. ROM Monitor If you're using custom hardware, you'll need a ROM monitor to help bring it up. A monitor generally provides a simple command prompt, with options for reading/writing memory and perhaps some power-on testing facilities which are useful before the kernel boots. ROM monitors invariably include boot loader functionality, but if your device goes into production you may want a standalone boot loader or a stripped-down ROM monitor. There are several available on the net: PPCBOOT http://ppcboot.sourceforge.net/ This is an actively developed ROM monitor and Linux boot loader ideal for custom boards, derived from 8xxROM and FADSROM. It includes support for BOOTP, RARP and TFTP image downloading and booting. LiMon http://www.thinsys.com/limon.html The Linux Monitor (LiMon) is a low level system start utility for the SBC8260. It also includes BOOTP and TFTP support. PMON/2000 http://pmon.groupbsd.org/ The PMON/2000 BootROM Monitor (PMON/2000) permits full-featured debugging to be performed on a target board that has a serial port, 512KB of ROM, and 128KB of RAM that can be dedicated to the Prom Monitor software. PPCForth http://ppcforth.sourceforge.net/ It is currently targeted for the IBM 403, 8xx is a goal for the future. It is ROM-able so you can boot directly from it, and has some ifdef's to slim the code down to as little as 10K or as large as 30K. It accepts S records over the serial port for loading other software. Unfortunately it is written in assembly, but then it's really small and is released under the GPL. It is a small implementation of FORTH which is handy for testing and small programs, although the author went overboard and included multitasking and a lot of low-level device control words. DINK32 http://www.mot.com/SPS/PowerPC/teksupport/tools/DINK32/VERSION12/dinkindex.htm DINK32 was developed as an internal Motorola PowerPC tool to help debug silicon as well as code. It runs on a variety of boards including the Yellowknife, Sandpoint, Excimer and Maximer. DINK32 has the full complement of commands. DINK32 supports all of the currently available PowerPC microprocessors including the 603, 603e, 604 family, the integrated processor, 8200 the 8240, the 7xx family and the 7400. DINK32 is a great source for example code when initializing the MPC105, MPC106, MPC107 memory controllers/bridge chips. DINK32 source code also includes sample code for the MPC8240 subsystems, DMA, EPIC, I2C, and I2O. 8xxROM http://www.s4l.de/powerpc.html Derived from FADSROM. No longer actively developed, and only really of historical interest as it has been superseded by ppcboot. FADSROM An old ROM monitor and loader written for the FADS board: http://lists.linuxppc.org/listarcs/linuxppc-embedded/199912/msg00045.html FADSROM has been superseded by ppcboot. Boot Loader If you're using custom hardware, or want to replace the ROM monitor on your board, you'll need a boot loader that knows how to decompress and transfer control to the kernel. The current trend is to include this functionality in the ROM monitor, as is the case with ppcboot. Although some of the data is board specific, you can assemble the bits from information available on the net: http://lists.linuxppc.org/listarcs/linuxppc-embedded/199911/msg00034.html bugboot For PreP and PowerPlus SBC's, see: http://members.home.net/mmporter/linux/ http://members.home.net/mmporter/linux/ linuxppc/preploader.tgz http://members.home.net/mmporter/linux/ linuxppc/bugboot-0.3.tar.gz mbxboot The old bootloader included in the kernel source tree, originally written for the Motorola MBX board, and since ported to a wide range of platforms. This is the start-up component of the zImage that knows how to decompress the kernel. mbxboot is now being rendered obsolete by ppcboot. Kernel Series You will need to decide whether to use a tried-and-tested, stable series kernel, or a development kernel. The choice will depend on your project requirements and how much work you want to do to port and maintain the kernel on your hardware. For any non-trivial project, you can expect several major kernel releases during the project's life. Consider the availability of the features you need, how leading edge you want to be, and the likely status of each kernel series by the time you're ready to ship. You are probably best off using the stable version, unless you want to actively participate in future development of Linux itself, or require features or board support only present in the development series. Stable Montavista The latest stable kernel from the MontaVista Hard Hat Linux kit is probably your best bet. Also, check for later updates in ftp://ftp.mvista.com/pub/CDKit/updates/ For the very latest work-in-progress, see: ftp://ftp.mvista.com/pub/ CDKit/wip/ppc_8xx/RPMS Denx Software Engineering ftp://ftp.denx.de/pub/LinuxPPC/usr/src/ Development http://www.kernel.org/ and http://penguinppc.org Work is ongoing to merge the embedded PowerPC changes into the current development tree, but the latest PPC changes take some time to propagate here. Memory Map The boot loader is responsible for configuring the memory map before jumping to the Linux kernel. Embedded PowerPC processors provide extreme flexibility for address mapping of internal and external devices. You should use this flexibitily to configure the memory map of your board to match the needs of the Linux kernel, rather than modify the Linux kernel MMU handling to match some arbitrary addressing scheme. See: http://lists.linuxppc.org/listarcs/linuxppc-embedded/200005/msg00157.html also check out Documentation/IO-mapping.txt in the kernel source tree. Porting Provided that the CPU you are using is already supported in the kernel, most of the work involved in porting Linux to a new platform actually involves changes to the ROM startup code, rather than the kernel itself. The other major kernel effort required is in device drivers for new hardware devices. Patches Once you've got something working, there's an abundance of kernel patches available on the Internet which can help customize the kernel to your application. Patches are generally issued against a particular kernel version, but can often be applied against other versions either automatically or with manual assistance. The latest patches are usually available from the &mailinglist;. Peter Allworth has some kernel patches at http://www.zeta.org.au/ ~linsol/ Contributing The people who actively contribute to open source development are also the ones who benefit the most from it, so it makes sense to actively contribute wherever you can. Virtually all the existing embedded Linux code is covered by the GPL, which requires you to redistribute any changes you make. Contributing your work offers an invaluable opportunity for peer review far beyond what is normally possible within a single organization and can save countless hours of unnecessary debugging. Submitting Patches In general, patches should be submitted in unidiff format to the mailing list. Even if you submit them directly to the maintainer, remember to cc: a copy to the mailing list, to keep everyone else informed of what's going on. If it's large, put it up for ftp and post a pointer instead. Coding Style When working on an existing code base, you should always use whatever coding style is used in the existing code. Consistency here is better than your subjective notion of correctness. When working on the kernel, follow the guidelines in Documentation/CodingStyle. When working on other GNU software, follow the guidelines at http://www.gnu.org/prep/standards_toc.html Device Drivers The kernel already includes device drivers for the on-chip serial and ethernet ports. Examples For helpful MPC8xx-specific device driver examples, see http://lists.linuxppc.org/listarcs/linuxppc-embedded/200001/msg00221.html ftp://ftp.denx.de/pub/LinuxPPC/usr/src/drivers.tar.gz Flash memory Flash Device Driver ftp://ftp.denx.de/pub/LinuxPPC/usr/src/CDK.tar.gz A flash driver will give you access to /dev/flash devices, which are useful during development and for field upgrades and are ideal for storing fixed size persistent configuration data like your board's Ethernet MAC address. This is true for drivers supporting a number of vendors' devices. The flash driver does auto-erase when the length of data written per write() is exactly the corresponding erase block size. So usually you just need to do: open (/dev/flash???) lseek(specific erase region) write(data, region size) QSLinux Flash Driver http://qslinux.org and ftp://qslinux.org QSLinux contains a fully functioning FLASH driver, and an interface to the Ext2FS filesystem, with compression. Memory Technology Device (MTD) Subsystem http://www.linux-mtd.infradead.org/ The MTD subsystem offers a more general solution which allows you to treat the flash as a regular block device on which you can mount a filesystem. It's ideal for large amounts of variable sized data or applications requiring a traditional writable filesystem, provided by the Journaling Flash Filesystem. However, some work is required to get the MTD to run on PowerPC, as it does not yet support big endian. M-Systems Disk-On-Chip http://www.linux-mtd.infradead.org/doc2000.html This is supported via the Memory Technology Device Subsystem. PCMCIA Cards For a PCMCIA driver, see http://lists.linuxppc.org/listarcs/linuxppc-embedded/200002/msg00093.html There are also some fairly detailed notes available at ftp://ftp.absoval.com/pub/rpxlite/ and http://lists.linuxppc.org/listarcs/linuxppc-embedded/200005/msg00227.html For generic Linux PCMCIA info, see http://pcmcia.sourceforge.org/ftp/doc/PCMCIA-PROG.html IDE/ATA Disk Drives There are lots of options for connecting IDE drives. You need to at least configure CONFIG_BLK_DEV_IDE and CONFIG_BLK_DEV_IDEDISK. Search for IDE. Also, see http://www.bluebutton.com/proj/mbxlinux/ PCI Bridge Search for QSPAN or PowerSpan. Watchdog Using the on-chip watchdog to provide the basic "write kicked" /dev/watchdog interface described in Documentation/watchdog.txt is problematic, because the SYPCR register controlling it can only be written once after reset to both set the timeout and enable the watchdog. Once enabled, the boot loader and kernel must keep it from expiring up until the point where the user application opens /dev/watchdog. Littering the generic kernel decompress and startup codes with watchdog kicks to do this isn't acceptable to other Linux users. Hence, hardware watchdog support hasn't been implemented yet. The general plan to solve this problem is described in http://lists.linuxppc.org/listarcs/ linuxppc-embedded/199910/msg00026.html You can probably use Linux's software watchdog in the meantime. USB for MPC850/823 http://www.honeywell.se/inu/usb/ These devices can be made to operate as a USB host or slave. Search for USB. Also see the Programming Guide for Linux USB Device Drivers at http://usb.in.tum.de/ usbdoc/ A/D and D/A Use something that "frames" the data and the SI/TDM interface works really sweet. Take a look at the CS4218 audio codec driver for the Embedded Planet boards. It's floating around in the 2.2.13 kernels on the MontaVista site. VME Numerous VME board vendors offer Linux support through software partners such as Denx. Some older patches and tarballs to use Linux on VME boards and simplify the access to the VME bus are available at ftp://vlab1.iram.es/ pub/linux-vme/ HDLC/PPP http://qslinux.org/docs/snmc/hdlc/index.html Provides support for the HDLC protocol, running the PPP layer in order to transport IP packets across a synchronous serial link. SPI This driver is an interface for the SPI controller in MPC8xx. The driver is written to work with the microcode patches to correct the parameter RAM problems. The driver supports basic init, open, close, read, and write functions. Linux STREAMS (LiS) http://www.gcom.com/home/linux/lis/ LiS is a software package that comprises an implementation of SVR4-compatible STREAMS for Linux in the form of a loadable kernel module. A patch to port it to MPC8xx based Embedded PowerPC systems is available at ftp://ftp.denx.de/pub/LinuxPPC/usr/src/LiS/ Runtime Library glibc http://www.gnu.org/software/libc/ and http://sources.redhat.com/glibc/ Modern releases of glibc are very large for a traditional embedded system. If your application requires only one or two user programs, you can statically link them to avoid requiring the entire dynamic library. Another option is to hand-strip the dynamic library to a bare minimum. Some modifications are required to the official glibc-2.1.x releases to make them work in the embedded PowerPC environment, such as cache line size modifications. See http://lists.linuxppc.org/listarcs/linuxppc-embedded/199909/msg00000.html After applying these modifications, glibc-2.1.x can be configured for cross-compiling with: #!/bin/sh export PATH=/path/to/local/i686-pc-linux-gnu/bin:$PATH export CFLAGS="-msoft-float -O2 -DNDEBUG=1" export CC=powerpc-linux-gcc export AR=powerpc-linux-ar export RANLIB=powerpc-linux-ranlib configure --host=powerpc-linux --prefix=/path/to/local/powerpc-linux \ --with-headers=/path/to/linux-2.2.13/include --enable-add-ons=linuxthreads \ --with-gnu-as --with-gnu-ld --disable-sanity-checks --without-fp There is a magic script named mklibs.sh which removes unused functions from the shared C library in the Debian Boot Floppies package, at ftp://ftp.us.debian.org/debian/dists/potato/main/source/admin/boot-floppies_2.2.23.tar.gz sglibc http://sourceforge.net/projects/sglibc and http://external-lists.varesearch.com/lists/listinfo/sglibc This is an attempt to produce a small glibc-compatible C runtime library subset suitable for embedded systems. To cut down some of the bloat in glibc, apply the patches at http://external-lists.varesearch.com/archives/sglibc/1999-September/000007.html uClibc http://opensource.lineo.com/cgi-bin/cvsweb/uClibc/ uC-Libc is a C library for embedded systems developed originally for uClinux and now being ported to other architectures including PowerPC. It has a different set of design goals from GNU libc, but for many embedded systems it is a sensible choice. dietlibc http://www.fefe.de/dietlibc/ The diet libc is a libc that is optimized for small size. It can be used to create small statically linked binaries for Linux on alpha, arm, mips, sparc, ppc and x86. newlib http://sources.redhat.com/newlib/ Newlib is a free C library intended for use on embedded systems, with less restrictive licensing than the GPL. However, it currently lacks the libgloss layer necessary to use it as the C library under Linux. libc5 Older Linux libc's are often quite small, but generally not supported by anyone now. Root Filesystem The kernel needs a root filesystem to mount at startup. There are many options, and the best one will generally depend on whether your system needs to be able to store persistent data (which must survive power cycling) in the field. See http://lists.linuxppc.org/listarcs/linuxppc-embedded/ 200003/msg00067.html Your best bet is likely to be the root filesystem from Hard Hat Linux. Extract all the RPMs matching *.noarch.rpm, and use the image in opt/hardhat/devkit/ppc/8xx/target as the root filesystem. NFS Mounted During development, the embedded system can NFS-mount its root filesystem from your file sever to provide a complete diskless Linux system. The file server need not be the same architecture as the embedded client. Answer "Y" to the kernel configuration questions regarding NFS client and root filesystem via NFS, and "make zImage". The embedded system will attempt to mount its root filesystem from the server as /tftpboot/<ipaddress>, where <ipaddress> is its IP address. Install your root filesystem image in this directory as root on the server, and export the directory tree with an entry in /etc/exports on the server, like: /tftpboot (rw,no_root_squash) If your system has a hard disk, you can start by using NFS then build a root file system on the disk and boot from that. If your system has no network, you may want to start developing on a board that does. Initial Ramdisk: initrd To make a diskless system standalone, you need an initial ramdisk image containing an ext2 filesystem to put in arch/ppc/mbxboot/ramdisk.image.gz. Then, build with make zImage.initrd and the ramdisk image will be mounted as the root filesystem at startup. See Documentation/initrd.txt in the kernel source tree. You need to select both CONFIG_BLK_DEV_RAM and CONFIG_BLK_DEV_INITRD to build zImage.initrd. You also need a file in arch/ppc/mbxboot called ramdisk.image.gz. When you build zImage.initrd, the secondary boot loader is re-compiled with INITRD_OFFSET and INITRD_SIZE set, which are used to locate the start and end of the ramdisk.image.gz file in memory. The start and end are passed to the kernel in registers (r4/r5??), which it saves into the variables initrd_start and initrd_end. The secondary boot loader also changes the kernel command line arguments so that root=/dev/ram instead of root=/dev/nfs The kernel does various things if initrd_start is non-zero, but the main one is to decompress the ramdisk.image.gz data into ramdisk 0, and because root=/dev/ram this is then mounted as the root filesystem. If your ramdisk is larger than 4 MB, you will need to add ramdisk=xxxx to the kernel command line at boot time, or modify drivers/block/rd.c. Beware that the CPU6 workarounds in the MontaVista 2.2.x kernel clobber the kernel command line, and cause the initial ramdisk mount to fail. See the thread at http://lists.linuxppc.org/listarcs/ linuxppc-embedded/200004/msg00103.html A number of ways to create an initial ramdisk image are described below. For more information on building a root filesystem, see the Bootdisk HOWTO at http://www.linux.org/docs/ldp/howto/ Bootdisk-HOWTO/buildroot.html Examples An example ramdisk.image.gz is already included in the Hard Hat kit. A simple ramdisk for use with ppcboot is available at the Denx ftp site. Using a ramdisk You can also create your own on your development machine in a filesystem on /dev/ram. If your ramdisk is larger than 4 MB, you will need to increase the default ramdisk size on your development machine accordingly. LILO users can do this by adding the following line to the first section of /etc/lilo.conf: ramdisk=65536 There is no real harm in asking for an excessive size, as /dev/ram* only allocates pages it actually needs to the ramdisk. However, you should use the blocks-count parameter to limit the filesystem size when you run mke2fs to prevent it creating unnecessarily large filesystem structures. Using the loop device Another approach is to use the loop device on your Linux development host to mount the ramdisk image as a local filesystem, and then copy the files you require into it. To allow users to mount the ramdisk.image on /mnt/loop with mount /mnt/loop add the following entry to your /etc/fstab: /path/to/ramdisk.image /mnt/loop auto user,noauto,rw,loop 0 0 Note that the minix file system code in Linux is not endian-independant, so you can't build a minix file system image on an x86 machine and expect to read it on a PowerPC machine. ext2 does not suffer from this problem. For more info, see the Loopback-Root-FS HOWTO at http://linuxdoc.org/HOWTO/mini/Loopback-Root-FS.html ROMFS Flash Filesystem Search for ROMFS. cramfs The 2.4 kernel series has a compressed read-only filesystem (cramfs) aimed at embedded systems, which can be back-ported to 2.2 kernels. If you're cross- developing, you need to modify mkcramfs to swap between little and big endian. It turns out that cramfs is not supported for a root fs or initrd. Basically, the kernel checks a hardcoded list of supported filesystems and if the MAGIC number doesn't match it bails. ramfs ramfs from the 2.4 kernel is a simple filesystem ideal for use in a ramdisk. It can be used in combination with a cramfs read-only root filesystem, to mount writable filesystems on /tmp and /var, which typically need to be writable. This combination is ideal for systems which don't require persistent storage. Journaling Flash FileSystem(JFFS) http://www.developer.axis.com/software/jffs/ JFFS allows persistent storage, optimised for flash memories rather than block devices like hard disks. It is aimed at providing a crash/powerdown-safe filesystem for disk-less embedded devices and is a better option than the cramfs/ramfs combination if your application requires persistent storage. You use it with the MTD subsystem. Floating Point Some of the embedded PowerPC processors do not have a floating point unit(FPU), and so must perform all floating point operations in software. Others do have a hardware FPU unit and may perform operations in hardware. Software If your application has very intensive floating point requirements, you may need to switch to fixed point or choose a target processor which does have an FPU. Floating point can be performed either by instruction emulation in the kernel, or by compiling everything with . In particular, it's important that all the libraries, whether dynamically or statically linked are compiled with the same options as the binaries that use them. Unless you're using a toolkit where this has already been done for you, this will generally mean that if you wish to use to gain maximum performance, you need to (re)compile everything, including: All static and shared libraries The compiler's internal libraries, such as libgcc.a All executables You will almost certainly not get this right first time. The primary symptom is that printf gives bogus numbers for simple floating point values. However, if you succeed, you can save space by configuring the kernel without floating point emulation. See http://lists.linuxppc.org/listarcs/ linuxppc-embedded/199911/msg00056.html To add kernel math emulation to the 2.2.13 kernel, see http://lists.linuxppc.org/listarcs/ linuxppc-embedded/199912/msg00017.html The "paranoia" test should give no complaints if everything is working correctly. See http://www.enseeiht.fr/NetLib/paranoia/index.html Hardware If your CPU has an FPU, you'll want to use it. Make sure that everything is consistently compiled for hardware floating point, especially if you've assembled your toolkit yourself, or are using an 8xx toolkit to compile for the 8260. Programs compiled for hardware floating point can still run on a CPU without an FPU, provided the kernel is built with the floating point instruction emulator. This incurs a further performance penalty on CPUs lacking an FPU. Mixed If you are using a single set of shared libraries, you cannot mix the two techniques in the one system. If you link statically or try really hard by creating two sets of shared libraries, the two can co-exist since programs compiled with never generate floating point instructions requiring kernel emulation. In general, you're better off choosing one or the other, and choosing hardware floating point with kernel instruction emulation is much easier to get working correctly. Realtime Response Check out MontaVista's Linux Real-Time characterisation projects at http://www.mvista.com/realtime Soft For many applications a soft realtime user space thread is adequate, particularly if you minimize kernel scheduling latency with the patches at http://www.redhat.com/~mingo/lowlatency-patches/ Also, see http://lists.linuxppc.org/listarcs/linuxppc-embedded/ 199912/msg00006.html Hard If your application requires a hard real time response with guaranteed low latency, you may need to encapsulate the realtime aspects in a device driver. This is how devices that have realtime constraints such as serial ports and disk drives are traditionally handled under most non-realtime operating systems, including Linux. Interrupt Latency The realtime response of a driver will still be affected by other kernel code which may disable interrupts for unknown periods, increasing effective interrupt latency. For some tools to help measure interrupt latency, see http://www.drfruitcake.com/linux/irq_blk.html RTLinux - Real-Time Linux http://www.rtlinux.com/ If you need better latency guarantees than offerred by the kernel, use Real-Time Linux to decouple the hard realtime portion from the rest of your application. v3.0 includes support for PowerPC. Also, search for RTLinux. RTAI - Real Time Application Interface http://www.aero.polimi.it/projects/rtai/ The Real Time Application Interface is a kernel module which uses a hardware abstraction layer to add typical features from an industrial realtime operating system to Linux. It consists basically of an interrupt dispatcher and mainly traps the peripherals interrupts and if necessary re-routes them to Linux. RTAI is supported on a number of MPC8xx systems by people like Denx. Threads If you need multithreading, using POSIX threads will give your application portability, even to non-Linux embedded systems. For example, they're supported by EL/IX (see http://sources.redhat.com/ elix/), eCos, RTEMs, and virtually all desktop systems. POSIX threads support is supplied with glibc2 as an add-on, enabled by configuring with '--enable-add-ons=linuxthreads'. It is also possible to build older (i.e. smaller) libc5 with LinuxThreads. See http://pauillac.inria.fr/~xleroy/linuxthreads/faq.html LinuxThread support has now been integrated into the official gdb release (currently 5.0), which makes thread debugging much easier. Versions of gdb prior to 5.0 did not support threads directly, although you can 'attach' to the thread processes individually. The courageous can also call clone() directly. Applications Standard GNU tools Standard GNU tools (such as bash, ls, etc) are available in the MontaVista distribution at ftp://ftp.mvista.com/pub/CDKit/1.2/latest/PowerPC Even if you are compiling them yourself, you can use the recipe in the %build portion of the SPEC files in the SRPMs to help. Standalone Shell Also known as sash, this is a small standalone shell with minimal versions of the most useful commands from /bin built in. See http://www.canb.auug.org.au/~dbell/programs/sash-3.4.tar.gz Not to be confused with the configuration option in many kernels, which starts a shell at bootup with the proper process group settings, so that signals like interrupt on CTRL-C work. Note that the two are often used together. BusyBox http://busybox.lineo.com/ BusyBox combines tiny versions of many common UNIX utilities into a single small executable. It provides minimalist replacements for most of the utilities you usually find in fileutils, shellutils, findutils, textutils, grep, gzip , tar, etc. BusyBox provides a fairly complete POSIX environment for any small or embedded system. The utilities in BusyBox generally have fewer options than their full-featured GNU cousins; however, the options that are included provide the expected functionality and behave very much like their GNU counterparts. Web Servers There are stacks to choose from. Here are just a few, which seem particularly well-suited to embedded Linux work. Pick the one that has the features you need. Boa http://www.boa.org/ Boa is a single-tasking HTTP server. That means that unlike traditional web servers, it does not fork for each incoming connection, nor does it fork many copies of itself to handle multiple connections. It internally multiplexes all of the ongoing HTTP connections, and forks only for CGI programs (which must be separate processes), automatic directory generation, and automatic file gunzipping. Preliminary tests show Boa is capable of handling several thousand hits per second on a 300 MHz Pentium and dozens of hits per second on a lowly 20 MHz 386/SX. thttpd, mini_httpd, micro_httpd http://www.acme.com/ A collection of very small web servers, with varying degrees of functionality. Graphical User Interface Microwindows http://microwindows.censoft.com/ Microwindows is an Open Source project aimed at bringing the features of modern graphical windowing environments to smaller devices and platforms. It allows applications to be built and tested on the Linux desktop, as well as cross-compiled for the target device. PicoGUI http://pgui.sourceforge.net/ A small, portable, client/server GUI designed to work on many types of hardware including handheld computers. Includes layout manager and widgets. Java Virtual Machine(JVM) MontaVista have several JVM solutions for HardHat Linux. A list of Java virtual machines, some of which are suitable for embedded PowerPC systems, is available at http://www.geocities.com/marcoschmidt.geo/java.html Debugging BDM BDM is way cool, especially if you are bringing up a custom board and don't want to invest in an In Circuit Emulator. You should definitely include a BDM connector on any custom hardware, and all off-the-shelf boards have it. For a broad introduction, see http://www.macraigor.com/zenofbdm.pdf Be careful to ensure that the CPU watchdog is disabled in the configuration file for your BDM probes, otherwise it will continually reset the CPU and nothing will work. In particular, the watchdog is enabled at reset and must be disabled if you wish to single step from reset. Also check that DER is zero'd when running with the debugger. Leaving the BDM probe connected can interfere with the target if it is not configured absolutely correctly, which usually involves the BDM probe being completely passive once the kernel is running. Symptoms are that the kernel crashes with the BDM probe connected, but runs fine without it. If you are using BDM and experience unexpected kernel crashes, try disconnecting the BDM probe. If you're using an off-the-shelf board which already has a working rom monitor, you generally won't need to use BDM at all, as you can get by fine with just the serial console. Many developers, particularly those bringing up a custom board from scratch, find BDM invaluable; to others it can be more trouble than it's worth. One advantage of a BDM interface over a kernel debugger is that you can really "freeze" the CPU including all timers, interrupts etc. MMU Support Some BDM debuggers are capable of performing MMU table walks, which is essential for debugging in virtual memory environments such as Linux because otherwise the BDM port merely deals with raw physical addresses. However, many BDM systems can't do this, so check with the vendor that they support MMU table walks on the particular CPU you're interested in before committing to one; otherwise it will be almost impossible to use once the kernel has turned the MMU on. See http://lists.linuxppc.org/listarcs/linuxppc-embedded/199909/msg00021.html Once the kernel is running you can use gdb remotely or even run it natively on the target hardware if you have enough RAM. It may be worth providing extra RAM on some of your development boards to allow for this. GDB on BDM See "Using GDB for Remote Debugging: BDM Support" in the CrossGCC FAQ at http://www.objsw.com/CrossGCC/FAQ-7.html BDM debugging under gdb is not supported by all BDM hardware vendors. See the thread http://www.oarcorp.com/rtems/maillistArchives/rtems-users/1999/july/msg00057.html To support BDM debugging under gdb requires the appropriate remote-* device in gdb, and possibly a kernel driver. If you are cross-developing, you must configure gdb as follows to include the appropriate devices: % configure --target=powerpc-linux The following systems currently support BDM debugging on gdb: BDM4GDB http://bdm4gdb.sourceforge.net/ An open user-supported project to build your own PowerPC BDM interface at extremely low cost. Supports extensible Flash programming and implements software-tablewalk so you have MMU support. You can use gdb to debug kernel code (single stepping, breakpoints, etc.) and/or inspect kernel data. If you don't want to build it yourself, the adapter is available at cost from Denx, subject to availability. MPCBDM http://www.vas-gmbh.de/software/mpcbdm/ The precursor to the BDM4GDB project, courtesy of Frank Przybylski. PPCBDM http://cyclone.parad.ru/ppcbdm/ The ultra low hardware cost precursor to MPCBDM and BDM4GDB, courtesy of Sergey Drazhnikov. Abatron http://www.abatron.ch/BDI/bdiGDB.html Has an ideal BDM/JTAG emulation solution for Linux hosting, with Linux MMU support specifically in mind. It is an Ethernet-based unit which has a telnet interface with which one can program various popular flash parts. This is ideal for Linux since one can build a kernel and expect script the programming process automagically. Their external box implements the standard gdb remote protocol allowing you to host debugging on any platform that can host gdb. Avocet Systems (formerly Huntsville Microsystems) http://www.hmi.com/bmd.htm Patches to add support to gdb are available in ftp://ftp.hmi.com/pub/gdb/ Macraigor Systems http://www.macraigor.com/ Currently only support Windows platform, but say Linux support for the Kestrel device (but not the Wiggler, Raven, etc) should be available sometime in September 2000. OCD Commander is a free assembly level debugger for Windows, which may work under VMWare. I couldn't get it to work with the Raven/Blackbird interface on the Embedded Planet CLLF under Windows; it wouldn't single-step correctly. Beware that the 1999 version of OCD Commander silently truncates S-records longer than 20 bytes during download, so you'll need to patch objcopy or write your own S-record generator to work around this. They have flash programming software available for download, but the Web site doesn't mention that it isn't actually free: you have to pay for the key to use it. If you're prepared to do your debugging under Windows, you can use the Cygwin tools from http://sources.redhat.com/cygwin/ to build a gdb cross-debugger which runs under Windows and uses the Wigglers.dll to talk to the target. Note that Wigglers.dll also loads other DLLs, so copy all the DLLs that come with OCD Commander from http://www.macraigor.com/" into your gdb directory and use the command: (gdb) target ocd wiggler You can also do this remotely, by using rproxy, described below. RISCWatch Debugger for PowerPC Processors http://www.chips.ibm.com/products/powerpc/riscwtch/ RISCWatch is a hardware and software development tool for the PowerPC 600/700 Family of microprocessors and the PowerPC 400Series of Embedded Controllers. The source-level debugger and processor-control features provide developers with the tools needed to develop and debug hardware and software. WindRiver (formerly EST Corporation) http://www.windriver.com/products/html/embed_dev_tools.html They've ported their VisionXD UNIX debugger to Linux and it is available with their parallel port of Ethernet-based probe. It can program flash parts and do source level debugging. It costs $6k or $8k depending on parport or Ethernet connection. The Windows version is only $4k. :-/ Beware that the EST tools don't handle the Linux zImage properly. See http://lists.linuxppc.org/listarcs/ linuxppc-embedded/200002/msg00073.html Other debuggers There are many other sources of BDM hardware probes and debuggers, but many vendors still lag way behind as far as Linux support. Commercial solutions which do not support a Linux development host include: Mentor (X-ray) http://www.mentor.com/embedded/ xray/index.html Avocet Systems (SourceGate) http://www.hmi.com/bmd.htm Tasking (CrossView Pro) http://www.tasking.com/technology/xvwp.html WindRiver (SingleStep) http://www.windriver.com/products/html/singlestep_suite_ds.html Applied Microsystems (PowerTap) http://www.amc.com/products/ powertap.html Lauterbach http://www.lauterbach.com/ Serial Console Virtually all boards use a serial console on SMC1 for boot messages and general debugging. Connect it to a serial port on your Linux development machine, where you can run minicom to interact with the board. GDB Once the kernel is running, you can use gdb in several different ways to debug user space programs: gdbserver You can run gdbserver on your target and run gdb back on your development machine, even if you're cross-developing. This requires far less resources than running all of gdb on your target. See http://qslinux.org/docs/cross/gdb/index.html If you're cross-developing, remember to configure your gdb as described earlier. rproxy http://www.std.com/qqi/labslave/rproxy.html This in an extended/enhanced gdbserver, which can also run on Windows and talk to BDM devices not yet supported by Linux. native If you have lots of RAM, you can run gdb directly on your target. If you are cross-developing, you need to configure gdb with: % configure --host=powerpc-linux Kernel Some kernels include kgdb support for using gdb for kernel debugging, enabled by configuring with . Oops Messages You get these whenever something truly bad happens in the kernel. Learn to know and respect them -- they are your friends, not your enemies. For general info on how to understand them, see the file Documentation/oops-tracing.txt in the kernel source tree. You'll get a long way just by looking up the instructions at the address indicated by NIP on the first line of the Oops in the output of: objdump --disassemble vmlinux This will show you the instruction causing the fault. Work backwards to find the line of C source code associated with it, and add printk's around it to find what is going wrong. For more help with decoding kernel panic messages, see http://lists.linuxppc.org/listarcs/ linuxppc-embedded/199912/msg00090.html printk printk is an indispensible tool. You can use it to add checkpointing, print kernel values that you can't get to via /proc, etc. It can be called anywhere, including interrupt routines, provided you're prepared for some interesting output. Note that during the boot process, the kernel "prints" lots of stuff, and it all goes into a buffer, to emerge quite late in the boot process when the serial console port is initialized with the call to . This eventually calls which will dump out the logged messages. So you can't necessarily assume that the kernel didn't get to your checkpoint just because the printk message didn't appear on the serial port during this part of the boot sequence. Performance CPU core Cache Ensure you have both the I and D caches enabled! Also, make sure you have serialization disabled (Set ICTRL to 0x7). To get maximum performance, you need to enable copyback data cache. This can be disabled in order to make the standard Linux/PPC libraries work without recompiling. If you build your own glibc as described under Runtime Library, you can enable copyback. Look for a option, or grep for DC_SFWT in arch/ppc/kernel/head.S and change the #if 0 to #if 1. BogoMIPS The BogoMIPS value on 8xx processors should be within 1% or so of the actual CPU core frequency, allowing for rounding and minor timing calculation errors. This makes it a useful sanity check to verify that the internal clock multiplier is set correctly and that the I-cache is turned on. However, note that the calculation of the BogoMIPS value is still tied to the external clock source and internal prescaler settings, so it shouldn't be solely relied on to verify that the core frequency really is what you think it should be. A simple cross-check is to perform a 'sleep 10' at the shell prompt, and time it with a watch to check that you're at least in the ballpark. It's wise to measure your system more accurately than this with a CRO at least once. Also, beware that the BogoMIPS rating should not be used as a general CPU performance measure. See http://linuxdoc.org/HOWTO/mini/BogoMips.html Profiling There are numerous options available for system profiling, depending on what you wish to measure, and how invasive you are prepared to be. /proc/profile /proc/profile is a standard kernel feature which provides simple kernel profiling based on Instruction Pointer sampling in the periodic timer interrupt routine. It's simplistic but effective, and low overhead since the interrupt is going to happen anyway. The data is processed with readprofile which looks up the System.map to show which kernel functions are using the most CPU time. It doesn't work for modules yet so at present you need to compile them in for profiling. You need to enable this at boot time by passing profile=2 on the command line. The number gives the power of 2 granularity used for the counters -- 2 will give you a seperate counter for each PowerPC instruction (each 4 bytes). Higher numbers consume less memory and give less precise results. The data from /proc/profile will be in target byte order, so if you're cross-developing you may need to either byte swap it, or compile readprofile to run on your target. The PowerPC branch of the Linux kernel has been slow to implement the Instruction Pointer sampling function necessary to generate the /proc/profile data. If it isn't implemented in your kernel, you'll see that readprofile always shows zero time for every kernel function. Linux Trace Toolkit http://www.opersys.com/LTT The Linux Trace Toolkit works with an instrumented Linux kernel by saving time-stamped records of important kernel events to a binary data file. A data decoder converts the binary data to text and calculates statistical summaries, such as percent processor utilization by each process. The toolkit also includes an integrated environment that graphically displays the results and provides search capability. A version for embedded PowerPC targets is now available from ftp://ftp.mvista.com/pub/LTT gprof All the usual Linux user mode profiling tools like gprof are available. kernprof http://oss.sgi.com/projects/kernprof This project aims to make full gprof profiling available for the kernel. However, it hasn't been ported to the PowerPC architecture yet. IDMA Beware that IDMA on the 860 is not designed for high performance, and the CPU gets better throughput with explicit cache-bursted programmed I/O. Search for IDMA for more discussion. Confusion sometimes arises because DMA transfers in most systems are faster than CPU transfers, whereas here the reverse is generally true. Furthermore, IDMA transfers eat into CPM processing time, limiting throughput on other communications modules at the same time. Network To get good TCP/IP performance, you need a fast CPU. Using the FEC, a 50 MHz 860P will run about 30 Mbits/sec TCP/IP, and a 100 MHz 860P will run about 60 Mbits/sec TCP/IP. The bottleneck is the protocol and application processing in the PPC core. The performance of a TCP/IP connection scales nearly linearly with the processor speed. If you need to go faster, use the 8260. Optimization Optimizing everything for space using gcc's option is likely to provide both the smallest code size and best performance, because it inhibits loop unrolling optimisation which tends to have a negative effect on embedded processors with relatively small cache sizes. Furthermore, PowerPC processors can speculatively execute branches overlapped with other loop instructions, making the branch effectively execute in zero cycles so loop unrolling is unnecessary in many circumstances. Common Mistakes and Problems Many new developers are likely to encounter at least half of the following common problems, which are raised often on the mailing list. Keep this section in mind to refer to when you spot the symptom. Changing KERNELBASE/KERNELLOAD You don't ever want to change KERNELLOAD or KERNELBASE, otherwise the virtual memory and MMU code will all break. Search for KERNELBASE. Leaving the Watchdog enabled The watchdog is enabled by default, and needs to be disabled at reset for anything including BDM to work. Mixing code compiled for software and hardware floating point The usual non-obvious cause of this is combining executables compiled with and shared libraries compiled with , or vice-versa. See floating point. Using an unmodified glibc In particular, remember to remove (or correct the cache line assumptions in) sysdeps/powerpc/memset.S before building glibc-2.1.3. "Kernel Mode Software FPU Emulation" panic This has little to do with floating point. Nearly all instructions the processor can't decode are vectored to this function. It assumes the primary reason you are here is to emulate floating point instructions. If the function can't decode the instruction as a floating point operation, it is really something the processor can't execute, so the panic message spews forth. This can be either a software or hardware bug. If it is a software bug, just unravel the stack backtrace and debug it. It could be a trashed stack frame, resulting in a bad function return address, or some indirect function call that was not properly computed. It could also happen because of a hardware bug while fetching instructions from memory. Verify the NIP instruction that it tried to decode is what is really supposed to be at that location in memory. This is a typical failure when the UPM is not programmed correctly. On a custom board in particular, verify all memory cycles an a logic analyser. Disable the cache and try again, you will probably get a different result. NFS gives "neighbour table overflow" This message is the result of some changes to the IP stack software in Linux version 2.2.x +. This simply means that you are unable to connect to your NFS server. It may be related to the driver, but it may also be related to other issues, such as NFS server not running or incorrectly installed, no physical connectivity to NFS server, etc. Check the configuration of your NFS server and IP network before diving into the driver. "Kernel panic: No init found..." on startup Either you don't have an init program of some type (even /bin/sh) in your root filesystem, or you don't have enough shared libraries and the program can't be loaded properly, although you often get messages about not able to load some .so. Usually the problem is missing or misplaced shared libraries. To start up /bin/sh, which is a good thing to try initially, you need the entire set of glibc shared libraries and libtermcap.so. If you're using the MontaVista CDK, you get these from the glibc and termcap RPMs, and remember you also need that funky sym link: /opt/hardhat/devkit/ppc/8xx/powerpc-hardhat-linux -> / in the target filesystem. You can find out which shared libraries any binary requires using ldd(1), but it only runs on the target and isn't much use if you're cross-developing and can't even start a shell yet. A shell script which runs on the host and does much the same thing is available at http://lists.linuxppc.org/listarcs/linuxppc-embedded/200102/msg00011.html Alternatives There are too many commercial embedded operating systems to list here, but if Linux isn't to your liking, here are some other open source operating systems which share some of the same benefits, and have been ported to embedded PowerPC processors: eCos - Embedded Configurable Operating System http://sources.redhat.com/ecos/ eCos is an open-source, royalty-free, highly configurable, application-specific operating system ideal for embedded systems development. It is targeted at high-volume applications in consumer electronics, telecommunications, automotive, and other deeply embedded applications. RTEMs - Real Time Executive for Multiprocessor Systems http://www.rtems.com/ RTEMS is a real-time executive which provides a high performance environment for embedded applications including a POSIX 1003.1b API, TCP/IP stack, multitasking, debugging and filesystem support. Glossary ABI Application Binary Interface The convention for register usage and C linkage commonly used on desktop PowerPC machines. Similar, but not identical to the EABI. BDM - Background Debug Mode An on-chip debugging interface, largely eliminating the need for expensive In-Circuit Emulators. CPM - Communications Processor Module The magic communications co-processor in Motorola PowerQUICC devices. It contains SCCs and SMCs, and performs SDMA and IDMA. CPU - Central Processor Unit Depending on the context, this may refer to the PowerPC core itself, or the physical processor device (including CPM, SIU, packaging etc) as a single unit. DMA - Direct Memory Access A form a data transfer directly between memory and a peripheral or between memory and memory, without normal program intervention. EABI - Embedded Application Binary Interface The convention for register usage and C linkage commonly used on embedded PowerPC machines, derived from the ABI. FEC - Fast Ethernet Controller The 100 Mbps (100Base) Ethernet controller, present on 'T' devices such as the 860T and 855T. GPL/LGPL - GNU General Public License/Lesser General Public License http://www.gnu.org/copyleft/gpl.html The licenses under which the Linux kernel and much of the utility and library code necessary to build a complete system may be copied, distributed and modified. Each portion of the software is copyright by its respected copyright holder, and you must comply with the terms of the license in order to legally copy (and hence use) it. One significant requirement is that you freely redistribute any modifications you make; if you can't cope with this, embedded Linux isn't for you. IDMA - Independent DMA A general purpose DMA engine with relatively limited throughput provided by the microcoded CPM, for use with external peripherals or memory-to-memory transfers. MII - Media Independent Interface The IEEE Ethernet standard control interface used to communicate between the on-chip Ethernet controller and the external PHY. MMU - Memory Management Unit CPU component which maps kernel- and user-space virtual addresses to physical addresses, and is an integral part of Linux kernel operation. PHY - Physical Interface The IEEE Ethernet standard interface between the external physical layer transceiver and the on-chip ethernet controller in a PowerQUICC device. Often used to refer to the external transceiver itself, the PHY is controlled more or less transparently to software via the MII. SCC - Serial Communications Controller The high performance module(s) within the CPM which implement the lowest layer of various serial protocols, such as Asynchronous serial (UART), 10 Mbps Ethernet, HDLC etc. SDMA - Serial DMA DMA used to transfer data to and from the SCCs. SIU - System Interface Unit Provides much of the external interfacing logic. It's the other major module on Motorola PowerQUICC devices alongside the CPU core and CPM. SPI - Serial Peripheral Interface A relatively simple synchronous serial interface for connecting low speed external devices using minimal wires. SMC - Serial Management Controller A lower performance version of the SCCs with more limited functionality, particularly useful for serial debug ports and low throughput serial protocols. UART - Universal Asynchronous Receiver Transmitter Generically, this refers to any device capable of implementing a variety of asynchronous serial protocols, such as RS-232, HDLC and SDLC. In this context, it refers to the operating mode of the SCCs which provides this functionality. UPM - User Programmable Machine A highly flexible bus interfacing machine unit allowing external peripherals with an extremely wide variety of interfacing requirements to be connected directly to the CPU. GNU Free Documentation License Version 1.1, March 2000
Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). State on the Title page the name of the publisher of the Modified Version, as the publisher. Preserve all the copyright notices of the Document. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. Include an unaltered copy of this License. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License".
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.