VxWorks BSP Developer's Guide VxWorks 6.
Copyright © 2005 Wind River Systems, Inc. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means without the prior written permission of Wind River Systems, Inc. Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. Any third-party trademarks referenced are the property of their respective owners. For further information regarding Wind River trademarks, please see: http://www.windriver.
Contents 1 2 Introduction .......................................................................................... 1 1.1 About This Document ........................................................................................... 1 1.2 The Board Support Package ................................................................................. 2 1.3 BSP Development Process .................................................................................... 3 1.4 Terminology ...............
VxWorks BSP Developer’s Guide, 6.0 Makefile ..................................................................................................... config.h ...................................................................................................... bspname.h ................................................................................................. sysALib.s .................................................................................................... romInit.s ........................
Contents On-Chip Debugging (OCD) Devices ..................................................... Logic Analyzer .......................................................................................... In-Circuit Emulator .................................................................................. 45 46 46 2.4.2 WDB Debugging Interface ..................................................................... 47 2.4.3 The Wind River IDE ................................................................
VxWorks BSP Developer’s Guide, 6.0 4 3.3.2 Projects ....................................................................................................... 73 3.3.3 Adding Other Timers .............................................................................. 73 3.3.4 NVRAM .................................................................................................... 74 3.3.5 Cache, MMU, and DMA Devices ........................................................... 75 3.3.6 Boot ROMs .
Contents 4.2.3 Verifying RAM .......................................................................................... 121 Runtime Execution .................................................................................. 121 4.2.4 Verifying the Image and OS Configuration .......................................... 123 Post-Processed Compiler Output ......................................................... 123 Operating System Components Built Into the Image ........................ 123 4.
VxWorks BSP Developer’s Guide, 6.0 Punctuation and Spelling ........................................................................ Headings .................................................................................................... Special Words ............................................................................................ Lists and Tables ......................................................................................... Code Examples, Syntax Displays, and Diagrams .........
1 Introduction 1.1 About This Document 1 1.2 The Board Support Package 2 1.3 BSP Development Process 3 1.4 Terminology 4 1.1 About This Document This document describes, in general terms, the elements that make up a board support package (BSP), the requirements for a VxWorks BSP, and the general behavior of a BSP during the boot process.
VxWorks BSP Developer’s Guide, 6.0 BSP, there are template files available for use in lieu of the reference BSP. However, a template BSP is generally not as complete as a reference BSP. During BSP development, you may want to consult the following VxWorks companion documents in addition to this manual: ■ VxWorks Device Driver Developer’s Guide—This document discusses issues related to writing and porting device drivers to VxWorks.
1 Introduction 1.3 BSP Development Process Wind River provides processor-dependent software as part of each reference BSP. That is, the portions of the BSP that depend only on processor type are done for you. In addition, many hardware drivers are available for each processor type. You can often use these drivers without change or, in most other cases, you can easily modify the drivers to suit specific hardware. 1.
VxWorks BSP Developer’s Guide, 6.0 developer. However, a typical development process is more likely to take several months. Once the minimal kernel is running, additional drivers may be required for the intended application. In most cases, these drivers can be added at a later date, concurrent with application development. For more information on developing and using drivers with your BSP, see the VxWorks Device Driver Developer’s Guide. 1.
2 Overview of a BSP 2.1 Introduction 5 2.2 Boot Sequence 7 2.3 Components of a BSP 20 2.4 The Development Environment 43 2.5 Avoiding Common Problems 50 2.1 Introduction This chapter begins by introducing the BSP routines in the context of the VxWorks boot sequence. Later sections provide descriptions of each of the files containing the BSP routines and the standard preprocessor macros used to configure VxWorks.
VxWorks BSP Developer’s Guide, 6.0 Before describing the steps in the boot process, it is worth noting the files you must write or modify during BSP development. Most of the work involved in developing a BSP is accomplished by writing the following three routines: ■ romInit( ) in romInit.s - initializes the CPU and memory ■ sysHwInit( ) in sysLib.c - ensures that all board hardware is initialized to a quiescent state ■ sysHwInit2( ) in sysLib.
2 Overview of a BSP 2.2 Boot Sequence target/src/drv/mem target/src/drv/parallel 2 target/src/drv/pci target/src/drv/pcmcia target/src/drv/serial target/src/drv/sio target/src/drv/other VxWorks Configuration Directories: target/config/all target/src/config target/config/comps target/config/comps/src target/config/comps/vxWorks NOTE: The list of files and directories provided above is not a complete list.
VxWorks BSP Developer’s Guide, 6.0 2.2.1 Sequence Overview Minimally, initializing a processor consists of providing a portion of code, and possibly some tables, that are located at the specific location in memory that the processor “jumps” to upon reset or power-up of the target system. This code sets the processor to a specific state, initializes memory and memory addressing, disables interrupts, and then passes control to additional bootstrapping code.
2 Overview of a BSP 2.2 Boot Sequence Figure 2-1 Boot Sequence Using a VxWorks Image 2 sysInit sysAlib.s RAM-based loadable Initializes CPU. Initializes RAM (controller). Initializes Stack - Quiets CPU (disables interrupts). boot specific usrInit Hooks Provided in target/config/all/usrConfig.c. boot generic Performs minimal kernel initialization. usrInit calls Configures kernel data structures. usrInit calls usrKernelInit Provided in target/config/bsp/sysLib.c.
VxWorks BSP Developer’s Guide, 6.0 Figure 2-2 illustrates the boot sequence used when VxWorks is booted from a boot ROM. Figure 2-2 Boot Sequence Using a Boot ROM romInit romInit.s ROM-based image Initializes CPU Initializes RAM (controller) Initializes Stack - Quiets CPU (disable interrupts) provided in target/config/all/bootInit.c Copies ROM image to RAM Clears unused RAM Decompression (if required) romStart provided in target/config/all/bootConfig.
2 Overview of a BSP 2.2 Boot Sequence 2.2.2 Boot Sequence Configurations There are several boot sequence configurations that are commonly supported. For BSPs intended for specific applications only, one or more of the methods are supported. General-purpose BSPs support all boot methods. For development, the most common boot method is through the presence of a ROM-based boot loader.
VxWorks BSP Developer’s Guide, 6.0 An image that continues running from flash and is built from a project is normally called vxWorks_romResident. Such an image built from the command line is typically called one of the following image types: ■ ■ ■ ■ ■ ■ vxWorks.res_rom vxWorks.res_rom_res_low vxWorks.res_rom_nosym vxWorks.res_rom_nosym_res_low bootrom_res bootrom_res_high An image that copies itself from flash to RAM and is built from a project is normally called vxWorks_rom.
2 Overview of a BSP 2.2 Boot Sequence over the network. This image requires a large ROM space and a large RAM space. This image can not be run from ROM. vxWorks.st_rom A VxWorks standalone image programmed into flash that decompresses itself to RAM for execution. This image includes a linked-in symbol table so that a complete VxWorks image with shell and symbol table is put into ROM. Because these systems tend to be large, ROM compression is used. This rule also creates vxImage.
VxWorks BSP Developer’s Guide, 6.0 bootrom_uncmp A VxWorks image with a boot loader application that is programmed into flash. This image copies itself into RAM for execution. This image requires a large amount of both RAM and ROM but executes quickly. bootrom_res A VxWorks image with a boot loader application that is programmed into flash. This image copies its data segment into RAM for execution, but continues fetching instructions from flash. This image requires a large ROMN space and little RAM space.
2 Overview of a BSP 2.2 Boot Sequence The MIPS processor uses a ModeIn input pin to set 256 bits of initialization information. This information is stored in non-volatile memory, usually somewhere other than on the processor chip. Board designers have the option of providing this information in a special part of ROM or NVRAM dedicated to this purpose. However, they might also design the board to gate this information from the boot flash.
VxWorks BSP Developer’s Guide, 6.0 The purpose of this routine is to initialize the CPU and some portion of memory. It does the absolute minimum amount of initialization—that is, the initialization of essential hardware only—before jumping to romStart( ). If romInit( ) is working correctly, the memory from LOCAL_MEM_LOCAL_ADRS through (LOCAL_MEM_LOCAL_ADRS + LOCAL_MEM_SIZE) should be readable and writable. If this is not the case, romInit( ) is not working properly.
2 Overview of a BSP 2.2 Boot Sequence This routine must duplicate much of the hardware initialization done by romInit( ) in order to set the run-time state rather than the boot state. Keep in mind that the board may have been booted using a ROM monitor or hardware debugger. In this case, the VxWorks boot ROM code, where romInit( ) is located, is not executed and VxWorks system initialization is not performed. Therefore, failure to duplicate the initialization code from romInit( ) may result in BSP failure.
VxWorks BSP Developer’s Guide, 6.0 ■ Initializing Interrupt Vectors—The exception vectors must be initialized before enabling interrupts and starting the kernel. First, intVecBaseSet( ) is called to establish the vector table base address. NOTE: The intVecBaseSet( ) routine is not called first on all architectures. For more information, see the appropriate VxWorks Architecture Supplement. After intVecBaseSet( ) is called, the routine excVecInit( ) initializes all exception vectors to default handlers.
2 Overview of a BSP 2.2 Boot Sequence allocated to the system memory pool, which is managed by memPartLib. All cached dynamic allocations are derived from this memory pool. Step 5: – the top of cached memory as indicated by sysMemTop( ) – the interrupt stack size. The interrupt stack corresponds to the largest amount of stack space that can be used by any interrupt-level routine that may be called, plus a safety margin for the nesting of interrupts. – the interrupt lockout level.
VxWorks BSP Developer’s Guide, 6.0 responsible for any board initialization not completed in sysHwInit( ), such as the connection of interrupt sources using intConnect( ). Next, the usrRoot( ) routine continues the clock initialization. It sets the default clock rate to the value of the macro SYS_CLK_RATE, typically 60 Hz. usrRoot( ) then enables the system clock with a call to sysClkEnable( ). NOTE: The system clock can be dynamically changed from the shell or from an application.
2 Overview of a BSP 2.3 Components of a BSP files, a custom usrAppInit.c file, another makefile for use with the project facility, and directories containing object modules. In addition to the BSP directory, there are several other directories that contain files related to the BSP. The target/config/all directory contains some source and header files that are used by the BSPs for default configuration. The files in this directory should never be changed.
VxWorks BSP Developer’s Guide, 6.0 sysDev.c If used, this file contains the device driver interface to the physical hardware device, Dev. Note that the actual device driver files are kept in target/src/drv/drvType. For example, target/src/drv/sio contains serial drivers. There may be multiple sysDev.c files. target.ref BSP documentation file (uses the apigen markup language). For more information on BSP documentation files, see B. Documentation Guidelines, or the reference entry for apigen (VxWorks 5.
2 Overview of a BSP 2.3 Components of a BSP vtsLogs Starting with VxWorks 6.0, Wind River recommends, but does not require, that VxWorks validation test suite (VTS) test logs for the most recent BSP revision be shipped with the BSP. The VTS test log files are kept in the BSP directory in a vtsLogs subdirectory. In addition to the automatic log files, it is also appropriate to keep the console output from any test runs and any supporting, BSP-specific test information (for example, .T1 files).
VxWorks BSP Developer’s Guide, 6.0 This file is intended for constant information that is not subject to user configuration. If any macros or values defined in this file can be changed to customize this system, define those macros or values in config.h instead. NOTE: In general, use the config.h file to define configurable values and the bspname.h file to define values fixed in hardware. When developing your BSP, it is helpful to use a sample header file as a starting point.
2 Overview of a BSP 2.3 Components of a BSP romInit.s This assembly file contains the romInit( ) routine, which is the entry point for bootstrapping, plus any romInit( ) subroutines. The romInit( ) routine must be the first routine in the text segment of romInit.s. At power-up (cold start) the processor begins execution at romInit( ). For warm starts, the processor begins execution at romInit( ) plus a small offset (see sysToMonitor( ) in sysLib.c).
VxWorks BSP Developer’s Guide, 6.0 sysHwInit2( ). These routines are described in 2.3.4 Required Routines, p.32. Also see the source code in your reference BSP or the template BSP. While sysLib.c is the largest BSP file, in the early phases of BSP development it is advisable to implement only the basics, including sysModel( ), sysBspRev( ), sysHwInit( ), sysHwInit2( ), and sysMemTop( ). The file sysLib.c also includes the following NVRAM stub drivers during initial development: #include "mem/nullNvram.
2 Overview of a BSP 2.3 Components of a BSP sysSerial.c would identify network interface and serial port drivers, respectively. Some device drivers are optional and the standard drivers provided in target/src/drv can be used. In some cases, custom device drivers must be created for a BSP, and these custom drivers should reside in the BSP directory (although this is not a requirement). Device driver files are detailed in the following sections of this guide: ■ 3.2.10 Minimum Required Drivers, p.70 ■ 3.2.
VxWorks BSP Developer’s Guide, 6.0 NOTE: The bootInit.c file is shared by all BSPs. Because of this, you must ensure that changes made to bootInit.c do not impact the functionality of other BSPs. The routine romStart( ) is essentially a loader. It performs the necessary decompression and relocation for the ROM images. First, it copies the text and data segments from ROM to RAM. Then, it clears those parts of the main RAM not otherwise used.
2 Overview of a BSP 2.3 Components of a BSP #include "sysIOPort.c" This means that the BSP contains a source file sysIOPort.c that does not have a corresponding object module. Instead of a separate object module, that object code is included in sysLib.o. Another source of derived files is the target.ref (or target.nr) documentation file in the BSP directory. This file is maintained in an unprocessed form that is difficult to read. To process the target.
VxWorks BSP Developer’s Guide, 6.0 initialized statically during compile time, but it may also be initialized dynamically early in the boot process. Values for statically defined sysPhysMemDesc[ ] entries are assigned using descriptive macro names.
2 Overview of a BSP 2.3 Components of a BSP The following state values are available: VM_STATE_VALID VM_STATE_WRITABLE VM_STATE_CACHEABLE VM_STATE_MEM_COHERENCY VM_STATE_GUARDED 2 Additional state values may be available on some architectures. Check vmLib.h and the appropriate architecture supplement for more information. sysPhysMemDescNumEnt int sysPhysMemDescNumEnt The sysPhysMemDescNumEnt variable contains the number of entries in sysPhysMemDesc[ ].
VxWorks BSP Developer’s Guide, 6.0 sysFlags int ; sysFlags /* boot flags */ The sysFlags variable holds the boot flags, which control factors such as whether to perform an autoboot or whether to use TFTP as the boot device. This is used extensively by bootrom. The value of sysFlags is initialized in bootConfig.c. 2.3.4 Required Routines The following routines must be present in your BSP. Failure to provide any of these routines results in unresolved references at link time.
2 Overview of a BSP 2.3 Components of a BSP development effort. The following pages describe the initial code for each required routine, and the file in which it is usually included. 2 sysBspRev( ) The routine sysBspRev( ) is identical in all BSPs. This routine can be taken directly from the reference or template BSP and does not require modification.
VxWorks BSP Developer’s Guide, 6.0 sysMemTop( ) The sysMemTop( ) routine returns the address of the top of VxWorks memory. During early BSP development, the sysMemTop( ) routine in sysLib.c simply returns a constant value based on LOCAL_MEM_LOCAL_ADRS, LOCAL_MEM_SIZE, PM_RESERVED_MEM (VxWorks 6.0 only), and USER_RESERVED_MEM. In most implementations, sysMemTop( ) calls sysPhysMemTop( ) to obtain the address at the top of physical memory (for more information, see sysPhysMemTop( ), p.35).
2 Overview of a BSP 2.3 Components of a BSP sysPhysMemTop( ) The sysPhysMemTop( ) routine in sysLib.c returns the address of the top of physical memory. This routine is required for VxWorks 6.0 BSPs and, although it is not strictly required for VxWorks 5.5 BSPs, it is included in most. This routine can be enhanced to allow automatic memory sizing.
VxWorks BSP Developer’s Guide, 6.0 /**************************************************************************** * * sysModel - return the model name of the CPU board * * This routine returns the model name of the CPU board. * * RETURNS: A pointer to the string. */ char * sysModel (void) { return (SYS_MODEL); } sysNvRamGet( ), sysNvRamSet( ) The sysNvRamSet( ) and sysNvRamGet( ) routines can be provided initially by nullNvRam.c, which is included from sysLib.c.
2 Overview of a BSP 2.3 Components of a BSP supported, this routine returns a pointer to a statically allocated structure.
VxWorks BSP Developer’s Guide, 6.
2 Overview of a BSP 2.3 Components of a BSP 2.3.5 Required Macros BSP macros are defined in either Makefile or config.h, with some macros defined in both files. The following macros are required for all BSPs unless otherwise specified: CPU (Defined in Makefile) The target CPU, which must be the same as for the reference BSP. CPU_VARIANT The target CPU variant (for example, _bcm125x for MIPS Broadcom devices). This macro is not required for all architectures.
VxWorks BSP Developer’s Guide, 6.0 ROM_WARM_ADRS (Optional. Defined in both Makefile and config.h, or in either) The boot ROM warm boot entry address in hexadecimal form. This is usually a fixed offset beyond the cold boot entry point, ROM_TEXT_ADRS. The offset is architecture-dependent, and can be obtained from the reference BSP or from the bcopyLong( ) or copyLong( ) call in bootInit.c (located in the target/config/all directory).
2 Overview of a BSP 2.3 Components of a BSP These macros must be defined before the configAll.h file is included. Note that BSP_VERSION and BSP_REV should contain strings. 2 NOTE: The BSP version and revision must be included in the BSP README file as well as in the config.h file. The definitions in these two files must agree. LOCAL_MEM_LOCAL_ADRS (Defined in config.h) The start of the on-board memory area. LOCAL_MEM_AUTOSIZE or LOCAL_MEM_SIZE (Defined in config.
VxWorks BSP Developer’s Guide, 6.0 boot record. For architecture-specific information, see the appropriate VxWorks Architecture Supplement and the VxWorks Hardware Considerations Guide. 2.3.6 Optional Routines Most BSPs provide routines beyond those that are required. Typically, an auxiliary clock and a serial port are provided. In addition, some kind of Ethernet interface is supported. Other hardware is often made available as well.
2 Overview of a BSP 2.4 The Development Environment linked with the boot ROM image. For more information, see the memory controller section of the VxWorks Device Driver Developer’s Guide. 2 2.4 The Development Environment The development environment consists of a mechanism to build an object module, a method to download the image to the target, and a mechanism for testing the downloaded code.
VxWorks BSP Developer’s Guide, 6.0 directories; each library file contains object modules for individual components. In VxWorks 6.0, processor variants have been eliminated. For example, all PowerPC processors are now indicated using PPC32. For more information, see the appropriate VxWorks Architecture Supplement. 2.4.1 BSP Debugging Methods Part of setting up your development environment is choosing a BSP debugging method.
2 Overview of a BSP 2.4 The Development Environment Native Debug ROMs In some cases, the board manufacturer provides flash software that can be used to help debug the VxWorks BSP. To be useful, a ROM monitor must have breakpoint support. It is also helpful to have a mechanism by which to download the image. An example of a debug ROM is ppcbug, which is provided by Motorola. ROM Emulator A ROM emulator is a device that plugs into a ROM socket on your target system and emulates the behavior of a ROM part.
VxWorks BSP Developer’s Guide, 6.0 During development, the OCD is used like a standard software debugger—that is, it is used to trace and modify program execution, examine and sometimes modify register contents, set breakpoints, and so forth. In addition, the OCD can be used to program flash devices, which saves time each time a new version of the BSP under development must be tested.
2 Overview of a BSP 2.4 The Development Environment An in-circuit emulator provides all the advantages of an on-chip debugging (OCD) device and may include additional features and abilities beyond the OCD capabilities. The disadvantages of an in-circuit emulator include cost and limited processor support. However, for processors with no OCD interface capability, an in-circuit emulator is sometimes the only viable solution for finding and fixing certain problems.
VxWorks BSP Developer’s Guide, 6.0 selected parts of the OS (such as individual tasks), without affecting the rest of the system. ■ Because the Wind River development tools let you download and execute code dynamically, you can download extensions and use the WDB agent to debug the extensions. The downloadable extensions include application code, new drivers, extra hardware initialization code, and so on. How you download the WDB agent and the VxWorks kernel depends on your phase of development.
2 Overview of a BSP 2.4 The Development Environment ■ ■ It must be able to generate code that works with the debugger, if any, that is to be used for BSP development. It should also work with the debugger(s) that will be used during application development. It must not generate code that silently performs certain activities such as memory allocation.
VxWorks BSP Developer’s Guide, 6.0 ■ Use a ROM emulator (such as NetROM from AMC). The drawback of this approach is that it can take time for you to learn how to use the tool. The advantages include fast download times, portability to most boards, and a communication protocol that lets debugging messages pass from the target to the host through the ROM socket. For more information on ROM emulators, see ROM Emulator, p.45). ■ Use an OCD device (see On-Chip Debugging (OCD) Devices, p.45).
2 Overview of a BSP 2.5 Avoiding Common Problems For example, the routine sysPhysMemTop( ) indicates the highest addressable memory present on the system. If autosizing is not used, such as during early parts of BSP development, this routine can be written to return a constant value.
VxWorks BSP Developer’s Guide, 6.0 Modified Drivers Located in the Wrong Directory BSP writers frequently modify Wind River device drivers, as well as provide their own drivers. These BSP-specific drivers must be delivered in BSP-specific directories and not in the Wind River directories target/src/drv and target/h/drv. BSP-specific code belongs in the BSP-specific directory target/config/bspname.
2 Overview of a BSP 2.5 Avoiding Common Problems Incorrect example 3: /* WRONG: DO NOT use a magic number in assembly source! */ lis r6, 0 /* load r6 with the address */ addi r6, r6, 0 /* of ROM_TEXT_ADRS */ Incorrect example 4: /* WRONG: DO NOT define a macro as a magic number! */ #define BRGCLK_RATE 0x16e3600 ppc860Chan [i].
VxWorks BSP Developer’s Guide, 6.
3 Porting a BSP to Custom Hardware 3.1 Introduction 55 3.2 Getting a Minimal Kernel Running 56 3.3 Finalizing Your BSP 72 3.1 Introduction This chapter describes the BSP porting process in detail. Before beginning this process, be sure your development environment is set up and properly configured. You should also have a basic understanding of how VxWorks is initialized.
VxWorks BSP Developer’s Guide, 6.0 5. Complete the BSP. This can include adding support for busses, networking, boot ROMs, SCSI, caches, MMU initialization, and direct memory access (DMA). 6. Generate a default project for use with the project facility. The goal of this procedure is not only to create a new BSP, but also to minimize the time during which you do not have access to the Wind River development tools— in particular, the Wind Debug target agent (WDB agent).
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running in romInit( ). The selection of processor registers that must be set early in development depends on the processor family and your specific processor. In addition to the minimum set of required processor registers, some board registers must be initialized. The selection of board control registers that must be set at this point is determined by the board design.
VxWorks BSP Developer’s Guide, 6.0 On a well-designed board, the LEDs are addressable without having too many processor or board registers configured and without very much additional bus configuration. The LED code should be simple. The following is an example of C source code for a simple LED system (you may also use LED code from your reference BSP): /* sysLed.c - Wind River 8260 User LED driver */ /* Copyright 1984-2003 Wind River Systems, Inc. */ #include "copyright_wrs.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running * Write to LED. */ BSCR_LED_REGISTER = sysLed; } /*********************************************************************** * * sysLedOff - Turn selected LED off. * * This routine set the selected LED to off. * * RETURNS: N/A. * * SEE ALSO: sysLedInit(), sysLedOff(), sysLedControl(). */ void sysLedOff ( UINT8 led ) { sysLed &= ~led; /* * Write to LED.
VxWorks BSP Developer’s Guide, 6.0 /*********************************************************************** * * sysLedControl - Turn selected LED(s) on or off. * * This routine sets the selected LED on or off. * * RETURNS: N/A. * * SEE ALSO: sysLedInit(), sysLedOff(), sysLedOn(). */ void sysLedControl ( int ledOn, UINT8 led ) { /* * Check led state. */ if (ledOn) sysLed |= led; else sysLed &= ~led; /* Set LED on. */ /* Set LED off. */ /* * Write to LED.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running are provided in 2.2 Boot Sequence, p.7. This section reviews the steps of the initialization sequence and supplies tips on what to check if a failure occurs at a particular step. 3 Initializing ROM-Based Image Types This section describes the initialization sequence for the ROM-based VxWorks images vxWorks_rom and vxWorks_resrom_nosym. romInit.s: romInit( ) At power-up (cold start) the processor begins execution at romInit( ).
VxWorks BSP Developer’s Guide, 6.0 After the copy action, verify that the data segment is properly initialized. For example: int thisVal = 17; /* some data segment variable */ ... if (thisVal != 17) somethingIsWrong(); If something is wrong, check whether RAM access is working properly. For example: int dummy; ... dummy = 17; if (dummy != 17) somethingIsWrong(); If RAM access is working, check that the data segment was copied into memory at the right offset.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running Console Output Routines In addition to the LED routines described above, it may also be helpful to have a polled-mode serial output routine. The first step in producing this routine is to create a more basic routine, possibly called something such as outConsole( ), that does unformatted polled-mode serial output. This does not allow numbers to be displayed easily, but it does allow diagnostic output.
VxWorks BSP Developer’s Guide, 6.0 Copying Additional Code From the Reference BSP If you followed the guidelines provided in earlier sections, your initial development for processor and memory initialization consisted of a number of files containing empty stub routines. At this point, you can copy relevant material from the reference BSP to your BSP directory. It is also common practice for developers to copy usrConfig.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running Initializing All Image Types The remainder of the initialization code is common to both ROM- and RAM-based images. usrConfig.c: usrInit( ) From a BSP writer’s point of view, the main significance of usrInit( ) is that it clears the bss segment so that uninitialized C global variables are now zero, and then calls sysHwInit( ) (in sysLib.c) to initialize the hardware.
VxWorks BSP Developer’s Guide, 6.0 mistake in BSP development is the failure to ensure that all interrupt sources are quiescent prior to enabling interrupts. If this is not done before the call to kernelInit( ), the system typically hangs or fails, causing confusion for the BSP developer because the source of the problem is not obvious.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running ROM as early as possible and thus save download cycles. In this case, starting the WDB agent before the kernel is desirable. Keep in mind, there are several disadvantages to starting the agent before the kernel. These are: ■ Once the hardware initialization code is written, bringing up the kernel takes less time than bringing up the agent.
VxWorks BSP Developer’s Guide, 6.0 void (*myHwInit2Hook)(void); ... void sysHwInit2 (void) { if (myHwInit2Hook != NULL) { myHwInit2Hook(); return; } ... } /* declare a hook routine */ /* and conditionally call it */ /* default code */ Adding hooks allows you to replace the routine from the debugger dynamically. For example, to override the behavior of sysHwInit2( ) above, create a new version of it called myHwInit2( ) in a module called myLib.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running 3.2.6 Building and Downloading VxWorks The VxWorks image you load to the target depends on the download method you use. The primary images are as follows: vxWorks This image starts execution from RAM. It must be loaded into RAM by some external means such as the board’s native debug ROMs. vxWorks_rom This image starts execution from ROM, but its text and data segments are linked to RAM addresses.
VxWorks BSP Developer’s Guide, 6.0 3.2.7 Interrupt Controllers The generic interrupt controller device drivers reside in the directory target/src/drv/intrCtl. See the template driver, templateIntrCtl.c, for detailed information on interrupt controller driver design and construction. Certain CPU architectures use external interrupt controllers to receive and prioritize external device interrupts. Wind River has prepared a draft document to define a standard interrupt controller device interface.
3 Porting a BSP to Custom Hardware 3.2 Getting a Minimal Kernel Running do is to perform board-specific hardware initialization in sysHwInit( ) and to connect the interrupt by calling intConnect( ) in sysHwInit2( ). The timer drivers are simple devices that can be tested by modifying usrRoot( ) to perform some action periodically, such as blinking an LED.
VxWorks BSP Developer’s Guide, 6.0 compatibility, these drivers are available in target/src/drv/serial. However, no new development should be done with these drivers. If serious problems are encountered with the old serial driver, it is recommended that you convert the BSP to use an SIO driver. 3.3 Finalizing Your BSP This section summarizes the remaining tasks essential to completing your BSP port. Included is a discussion of cleanup, timers, networking, and other issues. 3.3.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP However, this file should not be used by default. The file may also be commented out in the source file using a macro such as #ifdef POLLED_CONSOLE_OUTPUT. 3 3.3.2 Projects The Wind River Workbench documentation contains the necessary information for creating, configuring, and building projects. These steps can all be handled through the project facility. For more information, see the Wind River Workbench User’s Guide or online help. 3.3.
VxWorks BSP Developer’s Guide, 6.0 3.3.4 NVRAM VxWorks defines an interface for reading and writing to a persistent storage area. This interface is called the non-volatile memory library. VxWorks uses this library to store boot information. Early in the development process, it is recommended that you include nullNvRam.c in sysLib.c. When you finalize your BSP, it is best to replace nullNvRam.c with a more appropriate interface so that boot information can be kept after the board is powered off.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP 3.3.5 Cache, MMU, and DMA Devices The next step in the BSP development process is to get the BSP working with cache and MMU enabled. The standard cache and MMU libraries are enabled and initialized by the usrInit( ) code in usrConfig.c. The call to cacheLibInit( ) is marked by #ifdef INCLUDE_CACHE_SUPPORT. To enable cache, define INCLUDE_CACHE_SUPPORT, and define USER_I_CACHE_MODE and USER_D_CACHE_MODE to CACHE_ENABLED in config.h.
VxWorks BSP Developer’s Guide, 6.0 For L2 cache support, the following routines must be supplied and added to sysCache.c: sysL2CacheInit( ) initialize L2 cache library sysL2CacheEnable( ) enable L2 cache sysL2CacheDisable( ) disable L2 cache sysL2CacheFlush( ) flush L2 cache sysL2CacheInvFunc( ) invalidate L2 cache For cache lock support, the following routines must be supplied and added to sysCacheLockLib.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP The L2 cache initialization routine sysL2CacheInit( ) should be called from sysHwInit( ). This routine must not enable the L2 cache when cache is enabled, as this is done by sysL2CacheEnable( ) later in the boot process. If your reference BSP calls sysL2cacheInit( ) from sysHwInit2( ), it should be considered a bug in the BSP. 3.3.6 Boot ROMs Boot ROMs use the VxWorks kernel.
VxWorks BSP Developer’s Guide, 6.0 sysPciAutoConfig( ) routine (located in sysBusPci.c) that makes a call to pciAutoCfg( ). If PCI autoconfiguration is not desired but one or more devices on the PCI bus are to be supported, manual PCI configuration must be done. Normally, this requires a sysPciConfig( ) routine, which makes the appropriate calls to configure the bus and devices. However, it is recommended that autoconfiguration be used instead. In order to support PCI autoconfiguration, the sysBusPci.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP In addition, PCI support requires routines for low-level reads and writes to the PCI configuration space. These routines are referenced from the PCI configuration files through macros.
VxWorks BSP Developer’s Guide, 6.0 The modern interface to the PCI autoconfiguration library, starting with VxWorks 5.5, uses an initialization routine, a routine to set configuration options, and a routine to do the actual configuration. This differs from past versions, which created a structure with configuration options and passed a pointer to that structure when calling the routine that does the actual configuration. Many reference BSPs are written with the older interface.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP PCI_FBB_ENABLE and PCI_FBB_DISABLE enable and disable the routines that check fast back-to-back (FBB) functionality. PCI_FBB_UPDATE is for use with dynamic or high availability (HA) applications. PCI_FBB_UPDATE first disables FBB on all routines, then enables FBB on all routines, if appropriate. In HA applications, this option must be called any time a card is added or removed.
VxWorks BSP Developer’s Guide, 6.0 The default value of the MAX_LAT routine is NULL. Unless the MAX_LAT routine is changed, MAX_LAT values are set according to the value of PCI_MAX_LAT_ALL_SET during autoconfiguration. The following routines pertain to the user-supplied argument discussed above: PCI_MAX_LATENCY_ARG_SET When the routine PCI_MAX_LATENCY_FUNC_SET is called, PCI_MAX_LATENCY_ARG_SET is passed to the routine as the user-supplied argument. The default value is 0.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP Bus Numbering PCI_MAX_BUS_GET int * pArg During autoconfiguration, the library maintains a counter with the highest numbered bus. After configuration is complete, the counter value is retrieved as follows: pciAutoCfgCtl(pCookie, PCI_MAX_BUS_GET, &maxBus) Cache Line Size PCI_CACHE_SIZE_SET int pArg PCI_CACHE_SIZE_SET int pArg PCI_CACHE_SIZE_SET This routine sets the PCI cache line size to the value specified in pArg.
VxWorks BSP Developer’s Guide, 6.0 Base Addressing 32-Bit Memory Space Address Register (Prefetchable) PCI_MEM32_LOC_SET UINT32 pArg PCI_MEM32_SIZE_SET UINT32 pArg PCI_MEM32_SIZE_GET UINT32 * pArg ■ PCI_MEM32_LOC_SET This routine sets the base address of the PCI 32-bit memory space. This is an alternative to setting the address using the BSP constant PCI_MEM_ADRS. The default value is 0.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP ■ PCI_MEMIO32_SIZE_SET This routine sets the maximum size memory chunk allowable for the PCI 32-bit non-prefetchable memory space. This is an alternative to setting the size using the BSP constant PCI_MEMIO_SIZE. The default value is 0. ■ PCI_MEMIO32_SIZE_GET After autoconfiguration is complete, this routine retrieves the amount of memory used for PCI 32-bit non-prefetchable memory.
VxWorks BSP Developer’s Guide, 6.0 ■ PCI_IO16_LOC_SET This routine sets the base address of the PCI 16-bit I/O space. This is an alternative to setting the address using the BSP constant PCI_ISA_IO_ADRS The default value is 0. ■ PCI_IO16_SIZE_SET This routine sets the maximum size memory chunk allowable for the PCI 16-bit I/O space. This is an alternative to setting the size using the BSP constant PCI_ISA_IO_SIZE The default value is 0.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP This routine can use any combination of this input data to ascertain any special initialization requirements of a particular type of bridge at a specified location on the PCI bus hierarchy. The default value is NULL, so no pre-enumeration configuration is done.
VxWorks BSP Developer’s Guide, 6.0 The default value is NULL, so that no roll call delay is introduced before PCI configuration.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP PCI_INT_ASSIGN_FUNC_SET This interrupt assignment routine is specified by assigning a function pointer with the PCI_INCLUDE_FUNC_SET pciAutoCfgCtl( ) command as follows: pciAutoCfgCtl(pCookie, PCI_INT_ASSIGN_FUNC_SET, sysPciAutoconfigIntrAssign); This optional routine takes as input both the bus-device-function tuple, and an 8-bit quantity that contains the contents of the interrupt pin register from the PCI configuration header of the device.
VxWorks BSP Developer’s Guide, 6.0 Example 3-1 Basic PCI Configuration /* sysBusPci.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP pciAutoCfgCtl(pCookie, PCI_FBB_ENABLE, (void *)NULL); return; } 3 /************************************************************ * sysPciMemCfg - BSP support routine to specify PCI MEM/IO * * This routine calls pciAutoCfgCtl() to specify the memory * and I/O addresses and ranges for the four PCI address * spaces.
VxWorks BSP Developer’s Guide, 6.0 /************************************************************ * sysPciAutocinfigInclude - Specify devices to configure * * This routine returns TRUE for each device that the * BSP needs to have configured. * * This hypothetical board had on-board power management * controller as a PCI device and on-board video controller. * Neither of those devices are supported by the BSP, but * we want to configure everything else.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP struct PciIntIrq { UINT8 bus; UINT8 device; UINT8 intPin; UINT8 irq; }; 3 static struct PciIntIrq intIrqTable[] = { /* on-board Ethernet */ { MAIN_BUS, MAIN_DEV_ETHER, PCI_INT_LINE_A, INUM_TO_IRQ(INTVEC_ETHER_NUM) }, /* on-board USB */ { MAIN_BUS, MAIN_DEV_USB, PCI_INT_LINE_A, INUM_TO_IRQ(INTVEC_USB_NUM) }, /* 3.
VxWorks BSP Developer’s Guide, 6.0 * the interrupt assignment correctly. The design of this * routine should handle any board design.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP #ifdef INCLUDE_PCI sysPciAutoConfig (); /* prepare BSP support for callouts from supported END driver */ #if defined(INCLUDE_END) && defined(INCLUDE_FEI_END) sys557PciInit (); #endif /* defined(INCLUDE_END) && defined(INCLUDE_FEI_END) */ #endif /* INCLUDE_PCI */ To include the PCI support code, #include sysBusPci.c from sysLib.c. As with the call to sysPciAutoConfig( ), the #include sysBusPci.
VxWorks BSP Developer’s Guide, 6.0 bar0 in 32-bit mem space @ 0x80002000 [0,18,0] type=P2P BRIDGE to [1,0,0] base/limit: mem= 0x80100000/0x800fffff preMem=0x0000000090000000/0x000000008fffffff I/O= 0x00000000/0x00000fff status=0x02b0 ( CAP 66MHZ FBTB DEVSEL=1 ) command=0x0007 ( IO_ENABLE MEM_ENABLE MASTER_ENABLE ) value = 0 = 0x0 -> This example uses a wrPpmc440gp board and BSP, with a USB adapter plugged into a PCI slot. The host bridge, [0,0,0] is shown twice. This is intentional. The USB 2.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP All values are numeric—pciHeaderShow( ) does not make any attempt to interpret register values.
VxWorks BSP Developer’s Guide, 6.0 VME_A24_MSTR_SIZE, VME_A16_MSTR_LOCAL, and VME_A16_MSTR_SIZE must be defined. However, this requirement can vary depending on the specific VME controller driver used. Other configuration—such as data width, cycle type, and other VME-specific details—may also be required. Refer to the VME bus controller driver for information on exactly what routines must be called during initialization and what macros must be defined. The sysBusTas( ) routine is required by the BSP.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP Wind River Workbench User’s Guide (or, for Tornado users, the Tornado User’s Guide) for more information on command-line setup and capabilities. For a complete information regarding the target.ref file, see B. Documentation Guidelines. Updating target.nr Documentation Files Many existing BSPs used an older format documentation file called target.nr to describe the hardware configuration. This file uses a different markup syntax than the target.
VxWorks BSP Developer’s Guide, 6.0 parameter to the devEndLoad( ) routine is a character pointer. In order for each Ethernet device to be controlled by a given driver, the devEndLoad( ) routine is called twice. The first time, it is called with a pointer to a zero-length string. At this time, the driver is required to copy its own device name into the string. The network stack then fills in the unit number and initialization string from a table provided by the BSP and calls the devEndLoad( ) routine again.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP Media Access Controller (MAC) Address for Ethernet Devices Most modern Ethernet devices require the hardware address (MAC address) to be specified externally from the Ethernet controller chip. For peripheral boards, such as PCI network cards, the MAC address is supplied in ROM on the board and configured into the Ethernet controller during board power-up.
VxWorks BSP Developer’s Guide, 6.0 For more information about adding support for devices, refer to the VxWorks Device Driver Developer’s Guide. Generic Driver Introduction This section provides guidelines for writing generic drivers for the handful of devices that are common to most BSPs. Although BSPs can differ considerably in detail, there are some needs that are common to almost all BSPs. For example, most BSPs require a serial device driver or a timer driver.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP Multi-Mode Serial (SIO) Drivers The generic multi-mode serial drivers reside in the directory target/src/drv/sio. These drivers are called SIO drivers to distinguish them from the older serial drivers, which have only a single interrupt mode of operation. For more information on the older serial driver design, see Serial Drivers, p.106.
VxWorks BSP Developer’s Guide, 6.0 int (*callbackInstall) ( SIO_CHAN * pSioChan, int callbackType, STATUS (*callback)(), void * callbackArg ); int (*pollInput) ( SIO_CHAN * char * ); int (*pollOutput) ( SIO_CHAN * char outChar ); }; pSioChan, inChar pSioChan, The members of the SIO_DRV_FUNCS structure are as follows: ioctl( ) This routine points to the standard I/O control interface routine for the driver. This routine provides the primary control interface for any driver.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP SIO_OPEN Opens a channel. SIO_HUP Closes a channel. 3 txStartup( ) This routine provides a pointer to the routine that the system calls when new data is available for transmission. Typically, this routine is called only from the ttyDrv.o module. This module provides a higher level of functionality that makes a raw serial channel behave with line control and canonical character processing.
VxWorks BSP Developer’s Guide, 6.0 Serial Drivers The old style of serial drivers, those used before VxWorks 5.3, reside in the target/src/drv/serial directory. NOTE: These serial drivers are provided for backward compatibility with VxWorks 5.2 and earlier. All current generation BSPs should use SIO drivers instead. To manage information about a serial device, sysLib.c uses a device descriptor. This device descriptor also encapsulates board-specific information.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP AUX_CLK_RATE_MIN Defines the minimum rate at which the auxiliary clock can run. To support spy( ), AUX_CLK_RATE_MIN must be less than or equal to 100 Hz. 3 AUX_CLK_RATE_MAX Defines the maximum rate at which the auxiliary clock can run. To support spy( ), AUX_CLK_RATE_MAX must be greater than or equal to 100 Hz. Power Management In order to support the long power management features of VxWorks 6.0, a BSP must provide a one-shot timer.
VxWorks BSP Developer’s Guide, 6.0 sysOneShotInit( ) This routine is called during board initialization. It configures the one-shot timer and sets the system power management mode. Sleep cycles can occur rarely or frequently depending on system load. Three load conditions must be considered when designing a one-shot timer: ■ An I/O intensive environment with little computation.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP match value is advanced. To implement the one-shot timer, a match count value is computed for N ticks. When the system wakes up, the number of ticks slept is computed using the timer count register. It should be noted that this time computation requires a divide operation. Depending on your core hardware design, this operation may be time consuming, but it cannot be avoided.
VxWorks BSP Developer’s Guide, 6.0 Thus, the offset parameter is biased so that an offset of 0 points to the first byte of the VxWorks boot line. This is always true even if the boot line is not at the beginning of the non-volatile memory area. All BSPs must define the following macros: NV_RAM_SIZE Defines the total bytes of NVRAM available. Define NV_RAM_SIZE in config.h, or bspname.h. For boards without NVRAM, define NV_RAM_SIZE as NONE.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP In addition to modifications to sysMemTop( ), you must also modify the sysPhysMemDesc[ ] array in sysLib.c, and possibly other parts of sysLib.cas well, depending on your processor architecture. The sysPhysMemDesc[ ] array contains information about address ranges on the system as well as the cache and MMU initialization options that each region requires. Refer to the reference BSP or template for an example of sysPhysMemDesc[ ] usage.
VxWorks BSP Developer’s Guide, 6.0 With separate drivers for different functional areas, users can scale out support for functional areas that are not used by their application.
3 Porting a BSP to Custom Hardware 3.3 Finalizing Your BSP Data Address in Virtual Memory Environments If the CPU board has a memory management unit (MMU), the driver developer must be careful when setting data address pointers during direct memory access (DMA) transfers. When DMA is used in this environment, the physical memory address must be used instead of the virtual memory address.
VxWorks BSP Developer’s Guide, 6.
4 Debugging Your BSP 4.1 Introduction 115 4.2 Basic Debugging Techniques 116 4.3 Advanced Debugging Techniques 126 4.1 Introduction This chapter presents common debugging methods used during BSP development. Many of these methods are presented in earlier chapters of this document as part of the development process. This chapter is intended to provide you with an overview of the debugging methods available and describe how and why each method is typically used.
VxWorks BSP Developer’s Guide, 6.0 Board Bringup During board bringup, the target hardware is still under development. Because of this, some components of the board may not yet be included, and others may not be complete. The major aspects of board initialization are determined at this stage. Once board bringup is complete, the hardware is fully stable. At this point, an OCD register file is typically available to initialize the board. This register file is used during subsequent BSP development.
4 Debugging Your BSP 4.2 Basic Debugging Techniques information on debugging using an OCD, see 4.3 Advanced Debugging Techniques, p.126. 4.2.1 Using LEDs as a Diagnostic Tool 4 As outlined in 3.2.3 Using Debug Routines in the Initialization Code, p.57, it is usually best to start the development process by writing code to manipulate an LED device on your target hardware. If no LED is available, it may be possible to manipulate the state of an externally available pin or trace.
VxWorks BSP Developer’s Guide, 6.0 Finding Code Block Addresses You can use objdumparch when you need to find the code that resides at a particular RAM address. For example, the following command shows the entire contents of a vxWorks image file: objdumpppc --disassemble-all --show-raw-insn vxWorks Finding Addresses in the Flash image A common problem with the development environment is that the process of programming the image into flash does not put the data at the correct location.
4 Debugging Your BSP 4.2 Basic Debugging Techniques S21400002057696E64205269766572205379737465D9 ... ...
VxWorks BSP Developer’s Guide, 6.0 In this example, you have 0x036670 - 0x000000 = 0x036670. Notice that edata - romInit (that is, 0x36670 - 0x000000) is 0x033670 from the above nmarch -n output. To verify that this is correct, you can check the output of sizearch. For example: C:\T22\ppc\host\x86-win32\bin\sizeppc bootrom text data bss dec hex filename 186422 36410 38544 261376 3fd00 bootrom In this case, add the text and data sizes.
4 Debugging Your BSP 4.2 Basic Debugging Techniques Looking at the disassembly of an object file is helpful when, given the address of an exception, you need to find out where the exception took place in your code. The following command is helpful in this situation: objdumparch --disassemble-all --show-raw-insn tmp.o 4 Finding Addresses in RAM The previous sections describe several ways to determine what should be in RAM. However, this information must be correlated with what is actually there.
VxWorks BSP Developer’s Guide, 6.0 one LED available on your target hardware or a port pin that can be connected to a logic analyzer. One useful bit of code that you can add to the bootConfig.c file or the bootInit.c file are LED routines such as those presented in 3.2.3 Using Debug Routines in the Initialization Code, p.57.
4 Debugging Your BSP 4.2 Basic Debugging Techniques void sysPrintDebug(char *msg) { unsigned long msgIx; int pollStatus; for (msgIx = 0; msgIx < strlen(msg); msgIx++) { do pollStatus = sioPollOutput (sysSerialChanGet(0), msg[msgIx]); while ( pollStatus == EAGAIN ); } } To produce both carriage return and line feed, format your end lines with “\r\n”. For example: sysPrintDebug("Made it to sysHwInit2().\r\n"); 4.2.
VxWorks BSP Developer’s Guide, 6.0 NOTE: You must set up the VxWorks environment variables in order to run the tools specified below. The easiest way to do this is to use the configuration script created during your installation. For VxWorks 6.0, this is the wrEnv script. For previous versions of VxWorks, this is the torVars script. The configuration script is located in installDir/host/hostType/bin for all VxWorks versions.
4 Debugging Your BSP 4.2 Basic Debugging Techniques Another way to see if components are included is to look at the nmarch -n output. For example: C:\T22\ppc\target\config\wrSbc824x>nmppc -n bootrom 00100000 T _romInit 00100000 T _wrs_kernel_text_start 00100000 T romInit 00100000 T wrs_kernel_text_start 00100038 t cold 00100044 t warm 00100048 t start 001000a4 t ifpdr_value 00100230 t romInit824x 00100680 t romInvalidateTLBs 00100694 t tlbloop 001006a8 t romMinimumBATsInit 0010073c t gcc2_compiled.
VxWorks BSP Developer’s Guide, 6.0 image instead of the bootrom image. If bootrom_uncmp is the target image, the image contains the full information and no tmp.o is available. 4.3 Advanced Debugging Techniques This section presents the more advanced debugging techniques available to a BSP developer. NOTE: The methods discussed in this section require an on-chip debugging (OCD) device. For more information on basic debugging techniques, see 4.2 Basic Debugging Techniques, p.116. 4.3.
4 Debugging Your BSP 4.3 Advanced Debugging Techniques Software Breakpoints The type of breakpoints typically used during application development are software breakpoints. With software breakpoints, the debugger takes an opcode from RAM and replaces it with a special instruction that causes a debug exception, and sets up a handler to be executed when the debug exception occurs. When the handler runs, it checks to see if the developer has a breakpoint set at that location at the time.
VxWorks BSP Developer’s Guide, 6.0 If you want to debug an image during boot, there are two different conditions to be aware of: ■ ■ code running directly from flash code that is copied into RAM and executed Setting an Initial Breakpoint in a Flash Image When the code is running directly from flash, opcodes are fetched from flash and executed. Because it is not possible to modify the flash to insert the special opcode that is used to generate the debug exception, software breakpoints are not available.
4 Debugging Your BSP 4.3 Advanced Debugging Techniques execution. Most other boot loaders provide similar functionality, though the commands may be different. In this case, the sequence is to start the boot loader and use it to load the VxWorks image. Next, use the OCD device to stop the processor and set the desired software breakpoints, then resume operation. At this point, the boot loader is again executing. Use the boot loader go command to start VxWorks.
VxWorks BSP Developer’s Guide, 6.
A Common Development Issues A.1 Introduction 131 A.2 The Development Environment 132 A.3 Cache and MMU 133 A.4 Reusing Unportable Code 135 A.5 Volatile Variables 135 A.6 Conflicts Between Virtual and Physical Memory 135 A.1 Introduction This appendix presents a summary of common issues and concerns encountered during BSP development. Many of these problems are discussed in 2.5 Avoiding Common Problems, p.50, and throughout the main chapters of this document as part of the development process.
VxWorks BSP Developer’s Guide, 6.0 A.2 The Development Environment There are a number of problems that can occur due to your choice of development environment. Many of these problems are related to the relationship between the addresses where the linker expects the code to run and the addresses at which the code is actually located. In most situations, these addresses should be identical. However, for a short period of time, the locations can be different.
A Common Development Issues A.3 Cache and MMU If your system becomes unresponsive, verify that the RAM addresses the code is actually loaded at match the addresses used in the code. Position-Independent Code One exception to the matching RAM addresses rule is the PIC instructions at the beginning of the flash image. In VxWorks, there is a short section of PIC that copies the image from flash to RAM and then transfers execution to the copy in RAM.
VxWorks BSP Developer’s Guide, 6.0 cache entry points to. In this case, the modification that was made by the device is never visible to the processor. When cache is enabled, the initial setting should be to write-through mode if possible. In this mode, the processor does not write to cache without modifying RAM. If problems occur, they are likely caused by failure to invalidate the cache before reading a device register.
A Common Development Issues A.4 Reusing Unportable Code A.4 Reusing Unportable Code A common problem when creating BSPs is that code for some devices may have been taken from other sources, and that code may not have been written with portability in mind. When using code from other sources, you can prevent problems by examining the code for portability before including it in your BSP. For information about issues related to writing portable code, refer to the VxWorks Hardware Interface Validation Guide.
VxWorks BSP Developer’s Guide, 6.0 However, there are several reasons why this is not good programming practice. In many modern processors, the physical address space has grown from 32 bits to a larger number such as 36 bits or even 64 bits. However, because VxWorks is still essentially a 32-bit operating system, the virtual address is limited to 32 bits. This means that drivers written without regard to the difference between virtual and physical memory cannot be used on these systems.
B Documentation Guidelines B.1 Introduction 138 B.2 Written Style 138 B.3 Sections for Libraries and Subroutines 145 B.4 Sections for target.ref 153 B.5 Format and Style 155 B.6 Directives 167 B.7 Converting target.nr Files 170 B.8 Generating Reference Entries 171 NOTE: The instructions in this chapter are applicable to both VxWorks 5.5 and VxWorks 6.0 users unless otherwise noted. However, the documentation tool provided for the VxWorks 5.5 release is called refgen.
VxWorks BSP Developer’s Guide, 6.0 B.1 Introduction Reference documentation for Wind River board support packages (BSPs) consists of UNIX-style reference entries (formerly known as man pages) for the module sysLib.c and the file target.ref. Documentation in HTML format is generated from these files with the Wind River tool apigen. During a BSP build, make runs apigen and places the HTML output in the docs directory of your installation.
B Documentation Guidelines B.2 Written Style Punctuation ■ Always use a colon after the phrase or sentence introducing an example, display, itemized list, or table. ■ A comma should always precede the conjunction and, or, or nor when it separates the last of a series of three or more words or phrases. This comma is not optional. For example: apples, oranges, and bananas ■ B Avoid the use of quotation marks. If they are necessary, form quotations using the straight double-quote ( " ) only.
VxWorks BSP Developer’s Guide, 6.0 Table B-1 Spelling Conventions (cont’d) Use... Not... boot ROM bootrom, boot rom, bootROM bring up (v.) bringup, bring-up bring-up (n., adj.
B Documentation Guidelines B.2 Written Style Table B-1 Spelling Conventions (cont’d) Use... Not... file system filesystem flash (n.) Flash, flash (v. or gerund) for example e.g. FTP ftp HP-UX HP/UX, HPUX hardcopy hard copy home page homepage hot swap hotswap I/O i/o, IO, io ID id Internet internet interprocess inter-process intertask inter-task inline in-line ioctl( ) IOCTL, IOctl, IOCtl, ioctl Iostreams (no bold) IOStreams, iostreams, IoStreams KB Kb, Kbyte log in (v.
VxWorks BSP Developer’s Guide, 6.0 Table B-1 Spelling Conventions (cont’d) Use... Not...
B Documentation Guidelines B.2 Written Style Table B-1 Spelling Conventions (cont’d) Use... Not... scalable scaleable SCSI Scsi, scsi set up (v.) set-up setup (n., adj.) set-up shell script shellscript single-stepping single stepping standalone stand-alone start up (v.) startup, start-up startup (n., adj.) start-up STDIO stdio subclass sub-class subdirectory sub-directory SunOS SUN OS superclass super-class task ID task id Tcl TCL, tcl TFTP tftp that is i.e.
VxWorks BSP Developer’s Guide, 6.0 Table B-1 Spelling Conventions (cont’d) Use... Not... uppercase upper-case, upper case Users’ Group User’s Group, Users Group VxWorks VxWORKS, VXWORKS, vxWorks Web web Web site website Wind River WindRiver workaround (n.) work-around write-through, write-back writethrough, writeback Acronyms Define acronyms at first usage, except for widely recognized acronyms (see Table B-2).
B Documentation Guidelines B.
VxWorks BSP Developer’s Guide, 6.0 In the examples that follow, mfr&board means the manufacturer’s name plus the full model name of the board, as described in Board Names, p.145. A template showing documentation for sysLib.c is provided in target/config/templateCPU/sysLib.c. Reference entries for libraries and subroutines always contain the sections shown in Table B-3 in the order shown; other sections can be included as needed.
B Documentation Guidelines B.3 Sections for Libraries and Subroutines ■ Libraries Describe briefly what this collection of routines does. The hyphen must appear exactly as indicated (space-hyphen-space)—do not use backslashes or double hyphens. The general format is: nameLib.c - the such-and-such library For example: sysALib.s - mfr&board system-dependent assembly routines sysLib.c - mfr&board system-dependent library Be sure to include the filename extension (.c, .
VxWorks BSP Developer’s Guide, 6.0 Tcl Procedures, Scripts, Commands For Tcl procedures, scripts, and other commands, this section is the execution syntax; it must be typed manually, using the following conventions: ■ Enter the calling syntax and parameters between the tags \ss and \se. ■ Show parameters that are optional in square brackets. ■ Use the bar character (|) to indicate “or”. ■ Represent a variable list of arguments with three dots (...).
B Documentation Guidelines B.3 Sections for Libraries and Subroutines comment for each parameter, which serves as a useful overview or memory jogger. However, these short comments are typically not sufficient for thorough documentation. The parameter list in the DESCRIPTION section should provide more information and detail. Begin the parameter list with the word “Parameters” followed by a colon.
VxWorks BSP Developer’s Guide, 6.0 bytesPerBlk The size of each logical block on the disk. If zero, the default is 512. blksPerTrack The number of blocks on each logical track of the disk. If zero, the count of blocks per track is set to nBlocks; that is, the disk is defined as having only a single track. nBlocks The size of the disk in blocks. If zero, a default size is used; the default is calculated as the size of the UNIX disk divided by the number of bytes per block.
B Documentation Guidelines B.3 Sections for Libraries and Subroutines ■ Mention only true returns in this section, not values copied to a buffer given as an argument. (However, do describe the latter in the DESCRIPTION section.) ■ Despite the general rule of style, we do not treat return values as complete sentences; the subject and verb are understood. However, always start the return-value statement with a capital and end it with a period; and again, do not use abbreviated English.
VxWorks BSP Developer’s Guide, 6.0 Format the list with the item-list tags \is, \i, and \ie (for more information, see Item Lists (Definition Lists or Terms Lists), p.163.) Tag each error name with the \i tag. For example: ERRNO \is \i S_objLib_OBJ_ID_ERROR is invalid. \i S_objLib_OBJ_Deleted The message queue was deleted while waiting to receive a message. \i S_objLib_OBJ_TIMEOUT No messages were received in ticks. \ie SEE ALSO Section The SEE ALSO section is optional.
B Documentation Guidelines B.4 Sections for target.ref book on a line by itself—this approach is preferable when there are three or more books. B.4 Sections for target.ref B The target-information reference entry is generated from the file target.ref, located in the target/config/bspname directory. This file contains board-specific information necessary to run VxWorks. Table B-4 lists the subsections included in a typical target.ref file. Table B-4 Sections for target.
VxWorks BSP Developer’s Guide, 6.0 INTRODUCTION Section This section includes getting-started information, including subsections detailing ROM installation, boot ROM flash instructions, and jumper settings for VxWorks operation. FEATURES Section This section describes all the features of the board. Every feature should be identified under either the Supported Features or Unsupported Features subheadings. Each board configuration option should be considered a feature.
B Documentation Guidelines B.5 Format and Style Use the \bs and \be tags to display board diagrams. See the template BSP for guidelines on diagramming jumper positions. SEE ALSO Section For VxWorks 5.5 BSPs, this section always references the Setup and Startup chapter of the Tornado User’s Guide (VxWorks 6.0 BSPs do not include any automatic references). Other Wind River manuals can be referenced as necessary. Use the \tb tag for titles of manuals.
VxWorks BSP Developer’s Guide, 6.0 Formatting is controlled by special text markup, summarized in Table B-5. Some markup consists of format commands called tags, which begin with a backslash and are followed by letters. Some markup elements are inline; that is, they can appear anywhere in the line of text. Other markup elements must start in text column 1. Format tags, except \lib, always start in column 1. See the following note.
B Documentation Guidelines B.5 Format and Style Table B-5 Apigen Markup Location Markup Description Mangen Equiv. inline ‘text’ or ’text’ same Bold text, for literal names: filenames, commands, keywords, global variables, structure members, and so on. Text can be multiple words if on the same input line. inline same Italic text, for arguments, placeholders, emphasis, special terms. Text can be multiple words if on the same input line.
VxWorks BSP Developer’s Guide, 6.0 Table B-5 Apigen Markup Location Markup Description Mangen Equiv. col 1 only \is \i item \ie Item list, also known as a definition .iP or .IP list. Each item is a word or phrase followed by an explanation starting on the next line. col 1 only \ml \m mark \me Numbered or dash list (marker list). .iP or .IP col 1 only \ts ... \te Table .TS ... .TE inline | Column delimiter in a table. N/A inline \| The character | in a table.
B Documentation Guidelines B.5 Format and Style ■ A group of all-uppercase words on a line by itself. Underscores and numbers are also permitted. For example: THIS IS A HEADING This is the text that follows.... ■ A group of all-uppercase words at the start of a line and followed by a colon, optionally followed by non-heading text on the same line. For example: THIS IS A HEADING: This is the text that follows....
VxWorks BSP Developer’s Guide, 6.0 Example input: When semTake() returns due to timeout, it sets ’errno’ to S_objLib_OBJ_TIMEOUT (defined in objLib.h). Resulting output: When semTake( ) returns due to timeout, it sets errno to S_objLib_OBJ_TIMEOUT (defined in objLib.h). Some library names do not end in the standard suffixes listed above. Flag such names with the \lib tag. Note that unlike all other tags, the \lib tag can be inline.
B Documentation Guidelines B.5 Format and Style Placeholder Text A placeholder (also known as a text variable) is a word that represents a value that is to be supplied by the user, such as a command argument, routine parameter, or a portion of a directory path. Text variables are employed most frequently in syntax displays or pathnames. Surround placeholder words with the angle brackets < and >.
VxWorks BSP Developer’s Guide, 6.0 Cross-References to Other Reference Entries Do not use the UNIX-style parentheses-plus-number scheme to cross-reference the documentation sections for libraries and routines: CORRECT: sysLib, vxTas() INCORRECT: sysLib(1), vxTas(2) Special Terms When introducing or defining a special term, bracket the word in angle brackets (< and >) at first usage. In output, these words will appear in italics.
B Documentation Guidelines B.5 Format and Style Lists and Tables NOTE: Do not use the \cs and \ce tags to build lists or tables. ! CAUTION: Nesting of lists is not supported. Short Word Lists B A simple list of words or short phrases can be created simply by putting each word on a line by itself and indenting it with space characters. Any line that begins with a space causes a line breaks to be preserved for that line only. The line remains part of the paragraph, and so no vertical space is added.
VxWorks BSP Developer’s Guide, 6.0 Resulting output: FIODISKFORMAT Formats the entire disk with appropriate hardware track and sector marks. No file system is initialized on the disk by this request. FIODISKINIT Initializes a DOS file system on the disk volume. Marker Lists (Dash or Numbered Lists) Use the marker list tags to create lists with a specified “mark,” typically a number or hyphen (apigen does not recognize any symbol for a bullet or en- or em-dash). Introduce a marker list with the \ml tag.
B Documentation Guidelines B.5 Format and Style Example input: \ts Key | Name | Meaning ----|------------+-------\& | ampersand | bitwise AND \| | pipe / bar | bitwise OR # | pound sign | bitwise NAND \te Resulting output: B Key Name Meaning & | # ampersand pipe / bar pound sign bitwise AND bitwise OR bitwise NAND Code Examples, Syntax Displays, and Diagrams Code Examples Display code or terminal input/output with the \cs and \ce tags.
VxWorks BSP Developer’s Guide, 6.0 Because backslashes are not interpreted as an escape in \cs blocks, the backslash itself must not be escaped. For example: \cs -> copy < DOS1:\subdir\file1 \ce Resulting output: -> copy < DOS1:\subdir\file1 The \cs and \ce tags can also serve as a general mechanism for creating ASCII diagrams. Command Syntax Set off command syntax (for example, in shell scripts or Tcl procedures) with the \ss and \se tags.
B Documentation Guidelines B.6 Directives NOTE: The image notation should include text describing the port as well as a circle (in white or black) surrounding the port or an arrow (in white or black) pointing to the connector. ■ If ports are stacked, be sure that your notation includes a description of which port is the relevant one (for example, “serial console (top connector)”).
VxWorks BSP Developer’s Guide, 6.0 The backslash is a significant deviation from refgen, apigen’s predecessor. Most refgen directives required no backslash. However, the backslash requirement makes the markup considerably more resistant to ambiguities. NOTE: For backward compatibility, directives that were supported by refgen are by default converted internally to the new form, and thus still work. However, they should be changed when encountered and avoided in future work.
B Documentation Guidelines B.6 Directives Note that these directives should not be used to suppress the publication of an entire file. The standard way to prevent a file from being processed is to omit it from the Wind River makefile variable DOC_FILES. \INTERNAL [title] This directive specifies that the following section is internal documentation and should not be output. An internal section ends with the next heading or the end of the comment block.
VxWorks BSP Developer’s Guide, 6.0 new name is used in searching for possible hyperlinks to the output file, but does not affect the name of the output file. Example: \TITLE pc386/486 - BSP for PC 386/486 NOTE: This directive must include the backslash in both apigen and refgen. Including Image Files The \IMAGE directive provides a means for including an image from another file. \IMAGE filename This directive specifies an image file.
B Documentation Guidelines B.8 Generating Reference Entries This will generate a target.ref file in the current directory. The resulting target.ref files will require some cleanup, however minimal. Tables will always require that columns be manually aligned using the column delimiter (pipe character, |). If the target.nr included nroff-style column format commands, these will be left behind and must be removed manually.
VxWorks BSP Developer’s Guide, 6.0 and model of the board. For example: mv2603 = Motorola MVME2603. The files relevant to documentation are: Makefile Master makefile for building BSP and VxWorks modules. Three constants must be defined for documentation: TARGET_DIR, VENDOR, and BOARD. See Processing, p.173, for more information. sysLib.c Library of board-dependent C routines. target.
B Documentation Guidelines B.8 Generating Reference Entries Tools host/host/bin/apigen The apigen tool is a Perl script (refgen is a Tcl script) that generates HTML files from specially formatted source code, which may be C language modules, assembly language modules, target.ref files, or target.nr files. The command-line syntax and options for apigen are summarized in the reference entry.
VxWorks BSP Developer’s Guide, 6.0 The flow chart in Figure B-1 shows how the make process distributes BSP reference entries in the docs directory. Figure B-1 Production Flow for BSP Documentation target/config/bspname target.ref sysLib.c sysTffs.c make man (apigen or refgen -mg) docs/.../bspname 174 bspname.html sysLib.html libIndex.html rtnIndex.html sysTffs.
Index Symbols _romInit( ) 8 _sysInit( ) 8, 24 A adding other timers 73 ambaTimer.c 108 apigen tool 173 architecture considerations 14 avoiding common problems 50 B board initialization 56 board support package (BSP) see BSP boards see target hardware boot image 11 boot ROMs 77 boot sequence 7–20 configurations 11 overview 8 step-by-step 15 BOOTCONFIG 21 bootConfig.c BOOTCONFIG 21 BOOTINIT 21 bootInit.
VxWorks BSP Developer’s Guide, 6.0 BSP development process 3 time required 3 BSP directories vtsLogs 23 BSP files bootInit.c 27 bspname.h 23 config.h 23 configAll.h 27 Makefile 23 README 22 romInit.s 25 sysALib.s 24 sysDev.c 26 sysLb.c 25 target.nr 26 target.ref 26 usrConfig.
Index debugging 44 advanced techniques 126 basic techniques 116 breakpoints 126 forever loop 129 in-circuit emulator (ICE) 46 logic analyzer 46 on-chip debugging (OCD) 45 oscilloscope 46 ROM emulator 45 ROM monitor 45 ROM-based image initialization code 61 stages of BSP debugging 115 system-mode debugging techniques 67 using LEDs 44, 117 using NVRAM 44 WDB agent 47 with LEDs 57, 121 derived files images 28 development environment 43 common problems 132 device drivers generic 102 interrupt controller 70 dia
VxWorks BSP Developer’s Guide, 6.0 H L header files bspname.h 23 config.h 23 configAll.h 27 latency timer 81 LEDs 57, 117, 121 debugging with 44 LOCAL_MEM_LOCAL_ADRS LOCAL_MEM_SIZE 41 logic analyzer 46 50 I ICE 46 IDE 48 image types 28 vxWorks 77 in-circuit emulator (ICE) see ICE include files 21 INCLUDE_MMU_FULL 75 initialization generic 65 RAM 64 interrupt controllers 70 interrupts finding the source of 66 intLock( ) 53 ioctl( ) 104 ISRs 70 J JTAG 45 M m8260Timer.
Index sysFlashSet( ) 74 O objdump 117 OCD 45, 126 on-chip debugging (OCD) see OCD one-shot timer 107 examples 108 OS image 11 outConsole( ) 63 P PCI autoconfiguration 78 automatic interrupt binding 83 base addressing 84 16-bit I/O space 85 32-bit I/O space 85 32-bit memory space, non-prefetchable 84 32-bit memory space, prefetchable 84 bus support 77 cache line size 83 configuration example 89 custom bridge initialization 86 delay before initialization 87 error messages 82 fast back-to-back transmission
VxWorks BSP Developer’s Guide, 6.0 required macros 39 see also macros, BSP macros required routines 32 see also routines reusing code 135 ROM emulator 45 ROM monitor 45 ROM-based image type initialization 61 romInit( ) 6, 15, 25, 61 executing 15 romInit.s 25, 51 romInit( ) 25, 61 romStart( ) 16, 27, 61 executing 16 see also bootInit.
Index sysNvRamGet( ) 32, 36, 74, 109 sysNvRamSet( ) 32, 36, 74, 109 sysOneShotDisable( ) 107 sysOneShotEnable( ) 107 sysOneShotInit( ) 108 sysPciAutoConfig( ) 78 sysPciAutoconfigInclude( ) 78 sysPciAutoConfigIntAssign( ) 78 sysPciAutoconfigIntrAssign( ) 78 sysPciAutoconfigPostEnumBridgeInit( ) 78 sysPciAutoconfigPreEnumBridgeInit( ) 78 sysPciConfig( ) 78 sysPciHostBridgeInit( ) 78 sysPciInByte( ) 79 sysPciInLong( ) 79 sysPciInWord( ) 79 sysPciOutByte( ) 79 sysPciOutLong( ) 79 sysPciOutWord( ) 79 sysPciRead
