# # (C) Copyright 2002 # Ron Lockwood-Childs, VCT Labs, rchilds@vctlabs.com. # # See file CREDITS for the list of contributors to this project. # # This program is free software; you can redistribute it and/or # modify it under the terms of the GNU General Public License as # published by the Free Software Foundation; either version 2 of # the License, or (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place, Suite 330, Boston, # MA 02111-1307 USA # PPC Diagnostics --------------- From the diagnostics user's guide (documents/diag_guide.txt): ----------------------------------------------------------------------------- ** start of excerpt ** ----------------------------------------------------------------------------- Diagnostics Principles 1.1 Test coverage 1.1.1 Limitations The diagnostics suite requires the following board elements to work properly, and cannot, or does not, test the operation of these elements: * CPU/CPM: The CPU must execute instructions properly. Since the MPC860/855T processors contain the CPM module within the chip, the CPM must also operate correctly. * Clocks: The diagnostics cannot verify that oscillator frequencies operate within their respective tolerances. Clocks should be verified using an oscilloscope or logic analyzer. * Boot PROM: These diagnostics rely upon the firmware environment to initialize the CPM memory parameters, clocks, timers, etc. correctly, and initialize basic CPU parameters. * External cabling: Serial cables, ethernet cables or loopbacks and so forth should be tested independently for reliability. * Serial connection: The diagnostics suite requires a working serial port to communicate with the user. 1.1.2 Diagnostics coverage Within the given limitations, the diagnostics shall be expected to provide the following services: * Identify and locate common memory device faults. * Identify and locate crossed wires, shorts, and broken traces between the processor and peripherals. * Test the functionality of attached peripherals, up to and including interface connections. * Minimally test each peripheral upon power-up, to verify the hardware functions required by higher-level applications. * Provide fuller test coverage with operator input via a user interface. * Provide burn-in test capability for embedded PowerPC board manufacturing facilities. * Preserve a log of each failure (up to a point) to allow for unattended operation. * Assist embedded PowerPC hardware engineers with design verification testing. * Provide an EMI test mode that exercises as many components as possible at once. ----------------------------------------------------------------------------- ** end excerpt ** ----------------------------------------------------------------------------- Motivation ---------- I have yet to see another free software project that provides comprehensive testing of embedded hardware. With Linux becoming the embedded kernel of choice for many embedded hardware developers, the time is right to open source the test tools so necessary for building confidence in the quality of the underlying hardware the kernel depends upon. Additionally, the presence of a boot-time diagnostic adds the following benefits to any project: * lends it respectability in the eyes of the end user * if it finds hardware faults before an end user can run software on it, it makes the support engineer's life much easier. * if it exercises the hardware features used by the application engineers sufficiently and doesn't find faults, the application engineers can trust the hardware they are testing their code on. ppc_diag Documentation ---------------------- See the file documents/diag_guide.txt for information about using the diagnostics environment. See documents/diag_developer_guide.txt for information about tailoring the diagnostics environment to a particular PowerPC system, and how to build them to run on it. For developers who wish to modify the documentation, it has been written using the open-source document processing tool "lyx", which can be retrieved from www.lyx.org. The source of the *.{txt,ps} files may be found in documents/*.lyx. Building and Porting the Diagnostics ------------------------------------ 1) Download, build, and install PPCBoot (www.denx.de) 2) Download, build, and install the Power PC GCC cross-compiler and binutils package if necessary (www.gnu.org) 3) Get hold of the mkdep utility from the linux kernel source package (one method is by downloading and building the kernel (www.kernel.org)) 4) Install the Ruby interpreter (http://www.ruby-lang.org/en) 5) Optional: install a TFTP server 6) Read the diagnostics user guide (and send your comments, or better yet, patches to the document). This is the document you should send to your hardware and test teams, so make sure you are keeping it up to date as you add/modify/remove diagnostics tests. 7) Read the diagnostics developer guide (again, send comments/patches). 8) Unpack the diagnostics package if you haven't already, then: * Edit build/Makefile: Change PPCBOOT_INCLUDES to the PPCBoot include directory path on your system. Change the CROSS_COMPILE path to the prefix of the (cross-)compiler utilities on your system. Change the MKDEP path to the path of the linux kernel mkdep utility on your system. The diagnostics get statically linked -- therefore, examine the *_BASE and *_SIZE constants at the top of the file to make sure these program segments are placed properly on your system (i.e. where there's RAM you can freely modify). The stack is handled specially (BSS_BASE, BSS_SIZE, and STACK_BASE). The crucial address is STACK_BASE -- it specifies the upper 16 bits of the top of the stack (which grows downward). The setting 0x0010 is therefore short for 0x00100000, which is the start of the second megabyte from address 0. * Create system/config_yourboard.h and link it to system/config.h See other config_*.h files for examples. Examine the *_SUPPORT constants; #undef the devices not found/not supported on your embedded hardware under "ENABLED FEATURES". Under "COMMON BOARD CONSTANTS", change the base addresses to point to the addresses set by the system boot ROM. Also, examine the memory test range constants and modify if necessary for your system. Under "BOARD-SPECIFIC CONSTANTS", #undef unneeded constants (especially those referencing GB, GREEN_BOX, and XILINX). This is a convenient area to put *_SUPPORT and *_ADDR constants for the components on your custom hardware. This enables you to easily compile in or out component support for different "flavors" of the embedded board, if any. * From the base diagnostics path, run the following commands: $ cd build (only if retrieved from CVS) $ make sub_make $ make hfiles (all cases) $ make depend $ make * Optional: Create a diagnostics image loadable by PPCBoot or U-Boot using the mkimage tool built in PPCBoot (in tools/ subdirectory); set the MKIMAGE variable to the full pathname where this utility is found on your build system. See the mkimage information in the U-Boot source and edit build/gendiags.sh where mkimage is called, to give it the proper -O and -T options. Note: The `standalone' target calls the build/gendiags.sh script. $ make standalone MKIMAGE=/path/to/mkimage The diagnostic executable object can be found in build/ppc_diag. This file can be copied into the system's RAM directly by a suitable hardware debugger (we recommend the Abatron BDI 2000, http://www.abatron.ch). PPCBoot tip: When loading the diagnostics image file via the boot loader, try using 0x200000 as the tftp address. This leaves enough room for the diagnostics elf image to be placed in the default statically-linked addresses.