Chapter

1
Overview

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-1

Overview
1.1 Integration Issues VxWorks Boot Sequence Tornado Directory Structure Conventions and Validation

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-2

What is a BSP?
Provides VxWorks with primary interface to hardware environment. BSP Responsibilities:
q q

Hardware initialization on power-up. Support for VxWorks access to hardware drivers. Integration of hardware-dependent and hardwareindependent software in VxWorks. Source, include, and make les. Derived les. Binary driver modules.

Components consist of:

q q

May be validated to be WRS compliant.

Tornado BSP Training Workshop Copyright Wind River Systems Wind River Systems

1-3

What a BSP is Not

A BSP is not a hardware driver:
q

A hardware driver accesses hardware.

Hardware drivers are classied as generic or BSP specic:

q

Generic drivers manage devices which can be moved from one target environment to another (e.g. LAN chip). BSP drivers manage devices which are specic to the target environment (e.g. interrupt controller). Complete support for BSP specic drivers. Integration of generic device drivers.
Copyright Wind River Systems

BSP developer responsible for:

q q

Tornado BSP Training Workshop

Wind River Systems

1-4

A BSP provides support for accessing drivers through VxWorks. This is how a BSP provides access to the system hardware environment.

BSPs and VxWorks

Hardware-independent Software

Tools - Application I/O System File System

Hardware-Dependent Software

VxWorks Libraries

TCP/IP MUX

wind Kernel
SCSI Driver

BSP
Hardware SCC Timer

LAN Driver

SCSI Controller

LAN Controller
1-5

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

BSP Responsibility: Hardware Initialization

VxWorks boot sequence specics will vary with processors and hardware environments. Common initialization requirements:
q

Provide code at specic location in memory which processor will jump to on reset or power-up. Set processor in a specic state. Initialize memory and memory addressing. Disable interrupts. Pass control to additional bootstrapping code. Load required VxWorks segment(s) into RAM. Place hardware in quiescent state before initializing VxWorks kernel.
Copyright Wind River Systems Wind River Systems

Tornado BSP Training Workshop

1-6

BSP Responsibility: VxWorks Access To Hardware Drivers

Some driver support is provided by BSP. Examples:
q

Driver denes ISR(s), but BSP connects ISR(s) to interrupt vector table. BSP creates structures (objects) which are passed to driver for initialization. Offset constants and access macros for hardware registers provided by BSP and used by driver.

Provides portability for hardware driver code. Device conguration management:

q

Access to full range of device features (possibly at a later time). Separate development/production congurations.
Copyright Wind River Systems Wind River Systems

Tornado BSP Training Workshop

1-7

Example - Portability for LAN driver code would allow developer to:
q q

Transport LAN driver to new hardware environment. Provide new LAN driver for familiar hardware environment.

BSP Responsibility: Integration of Hardware Dependent Software

Provides code exibility and portability:
q q

Compile-time exibility. Run-time portability. Uses preprocessor macros to customize system. Provides ability to produce optimized modules without changing source code. Uses pointers to access routines. Provides portability for compiled object modules.

Compile-time exibility:
q q

Run-time portability:
q q

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-8

Combining techniques allows compile-time macros to implement runtime vectored routines. This is the preferred method at WRS.

BSP Components: Primary Files

Primary BSP les:
q q

Source les. Include les. Make les. Generic code is written in C. Architecture specic and performance optimized code is assembly. All includes and denitions specic to a CPU board are localized in two les. Controls building of all images.
Copyright Wind River Systems Wind River Systems

Source les:
q

Include les:
q

Make le:
q

Tornado BSP Training Workshop

1-9

The two BSP specic include les are distinguished by denitions which are xed once the physical hardware environment is xed, and denitions which allow conguration of the hardware environment after the physical hardware environment is xed. All images are built using a compact primary makele which accesses make sub-les.

BSP Components: Derived Files

Derived BSP les are created using:
q q

Primary BSP les. Driver source les. Modules in VxWorks archive libraries. Hardware initialization object modules. VxWorks boot object modules. VxWorks images. VxWorks binary symbol table.

Derived BSP les are classied as:

q q

A complete BSP port will generate all of these les. End users will recreate some of these les when conguring the system.
Tornado BSP Training Workshop Copyright Wind River Systems Wind River Systems

1-10

There are two non-standard derived BSP les:

q

If text segment write protection for VxWorks has been activated, there is an object module to guarantee that text and data do not share a common memory page. This functionality supports VxVMI. If this functionality has not been included this will be a null object module, however, it is still required. There is an ASCII le derived from an nroff le containing BSP specic information.

BSP Development
Development should occur in incremental steps:
q

First set up development environment (down-load path(s), debug strategies, etc.). Write pre-kernel initialization code. Optionally activate WDB agent and Tornado tools using polled serial or ethernet interface. Start minimal VxWorks kernel adding support for a system clock, and install interrupts. Complete BSP providing all necessary support for hardware environment (full network support etc.). Clean-up, testing and documentation.

Course material will be presented following this sequence as closely as possible.

Tornado BSP Training Workshop Copyright Wind River Systems

Wind River Systems

1-11

Pre-kernel Tornado ethernet interface provided by NetROM which will be discussed later in the course.

BSP Development - cont.

Development time may be reduced by purchasing:
q q

The BSP Developers Kit. Appropriate reference BSP. A Validation Test Suite (VTS). Template BSP (all architectures). Template device drivers.

BSP Developers Kit provides:

q q

Purchasing a reference BSP which most closely matches target environment:

q

Specic device drivers which are not part of reference BSP can also be purchased from WRS.

Reference BSP obtained when Tornado is purchased.

Tornado BSP Training Workshop Copyright Wind River Systems Wind River Systems

1-12

BSP Validation
BSP validation:
q q

WRS validated. Non WRS validated. Classied as Tornado Certied, and may be distributed displaying this information. Contact WRS to obtain validation requirements. Automated test suite which runs on host and target to exercise BSP and report defects. Included in BSP Developers Kit. VTS distribution includes source to allow extension.
Copyright Wind River Systems Wind River Systems

A WRS validated BSP:

q

BSP validation uses a Validation Test Suite (VTS):

q

Tornado BSP Training Workshop

1-13

BSP Porting Kit includes:

q q

Validation Test Suite. BSP Porting Kit Manual. Sample driver source code. Template BSP les (all architectures).

Optional enhanced features - Engineering Services development support.

Overview
Integration Issues 1.2 VxWorks Boot Sequence Tornado Directory Structure Conventions and Validation

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-14

VxWorks Image Types

There are three classes of VxWorks images:
q q

Loadable images. ROM-based images - compressed/uncompressed. ROM-Resident images. Boot code is burned into ROM or Flash. Boot code is a stand-alone VxWorks application.

Loadable images are loaded into RAM by boot code.

q q

ROM-based images load themselves into RAM from ROM or Flash. ROM-resident images execute out of ROM or Flash.
q

Only the data segment of the VxWorks image is loaded into RAM.
Copyright Wind River Systems Wind River Systems

Tornado BSP Training Workshop

1-15

VxWorks images consist of:

q q

Text segment - Executable instructions. Data Segment - Initialized global and static variables. BSS (Block Started by Symbol) Segment - Un-initialized global and static variables. (ANSI C/C++ requires these variables to be initialized to zero.).

These are generic components common to all VxWorks images. Component details will depend on the Object Module Format for the image:
q q

a.out COFF ELF

BSS segments of VxWorks images are zeroed by initialization code after appropriate image segments are relocated.

Some Terminology
VxWorks boot image - A VxWorks image designed to load another VxWorks image containing application code (often referred to as boot code).
q q

Burned into ROM or loaded into Flash. May execute in ROM/Flash (ROM-resident). May execute out of RAM.

VxWorks image - A VxWorks image containing end-user code. Sub-types:

q

Loadable VxWorks image - VxWorks images loaded by VxWorks boot image. VxWorks ROM image - VxWorks image burned into ROM or loaded into Flash. May execute in ROM/Flash (ROM-resident) or RAM.
Copyright Wind River Systems Wind River Systems

Tornado BSP Training Workshop

1-16

VxWorks Startup Sequence

The sequence of events which occur at power-up are a function of the type of VxWorks image which will run. The initial phase of the start-up sequence is the same across all VxWorks image types. Processor is jumped to the entry point of boot-strap code in ROM or Flash. This code:
q q

Disables interrupts (via the processor). Initializes target memory. Loads appropriate VxWorks image segments. Jumps to code to place target in a quiet state.

Various startup sequences are discussed next.

Tornado BSP Training Workshop Copyright Wind River Systems

Wind River Systems

1-17

Boot Sequence - Loadable VxWorks Image

Bootstrap code executes and loads text and data segments of boot code (from ROM or Flash) into RAM. Scenarios are:
q q

Boot code compressed - Decompression during copy Boot code uncompressed - Copy Boot code is ROM-resident - Copy data segment only

Boot program executes and loads VxWorks image into RAM. Jumps to VxWorks load point. System initialization code statically linked into loaded VxWorks image executes and completes initialization.

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-18

Memory allocated in RAM for boot code is reclaimed by VxWorks. VxWorks startup sequence is sometimes referred to as a boot sequence. Image stored in ROM/Flash is a boot-ROM image. Loaded image will be a end-user or application image.

Loadable VxWorks Image

ROM/Flash BootStrap Programs VxWorks ROM Boot Program
FREE_RAM_ADRS

RAM
LOCAL_MEM_LOCAL_ADRS

RAM_LOW_ADRS

RAM_HIGH_ADRS

Boot Program

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-19

LOCAL_MEM_LOCAL_ADRS is the beginning of RAM. RAM_LOW_ADRS is the load point for VxWorks. It is also the start of the text segment of VxWorks. FREE_RAM_ADRS marks the end of the VxWorks image. Usually the system memory pool or the target server memory pool begins here. RAM_HIGH_ADRS is the load point for the boot program. It is also the start of the text segment for the boot program unless the boot image is ROM-resident, in which case it is the start of the data segment for the boot module.

Startup Sequence - ROM-based VxWorks Image

Bootstrap code executes and loads text and data segments of VxWorks (from ROM or Flash) into RAM. Scenarios are:
q q

VxWorks compressed - Decompression during copy VxWorks uncompressed - Copy

Control transfers to VxWorks initialization code in RAM. System initialization code statically linked into VxWorks image executes (in RAM) and completes initialization.

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-20

ROM-based VxWorks Image

ROM/Flash BootStrap Programs VxWorks ROMbased VxWorks Image
FREE_RAM_ADRS

RAM
LOCAL_MEM_LOCAL_ADRS

RAM_LOW_ADRS

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-21

LOCAL_MEM_LOCAL_ADRS is the beginning of RAM. RAM_LOW_ADRS is the load point for VxWorks. It is also the start of the text segment of VxWorks. FREE_RAM_ADRS marks the end of the VxWorks image. Usually the system memory pool or the target server memory pool begins here.

Startup Sequence - ROM-resident VxWorks Image

Bootstrap code executes and loads data segment of VxWorks image (from ROM or Flash) into RAM. Control branches to VxWorks initialization code in ROM or Flash. System initialization code statically linked into VxWorks image executes (in ROM or Flash) and completes initialization.

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-22

ROM-resident VxWorks Image

ROM/Flash BootStrap Programs VxWorks Text VxWorks
Data + BSS

RAM
LOCAL_MEM_LOCAL_ADRS

RAM_LOW_ADRS

VxWorks Data + BSS

FREE_RAM_ADRS

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-23

LOCAL_MEM_LOCAL_ADRS is the beginning of RAM. RAM_LOW_ADRS is the load point for VxWorks. It is also the start of the data segment of VxWorks. FREE_RAM_ADRS marks the end of the VxWorks image. Usually the system memory pool or the target server memory pool begins here.

Startup Sequence - VxWorks Initialization

After (end-user) VxWorks segment(s) are loaded into RAM, system initialization code statically linked into VxWorks image executes to complete the boot sequence. This code will:
q q

Place hardware environment in a quiet state. Initialize and start the wind kernel. Spawn a task to complete system initialization.

System initialization task will initialize support for enduser specied facilities, and start the end-users application.
Tornado BSP Training Workshop Copyright Wind River Systems Wind River Systems

1-24

Loadable VxWorks images do not assume that they have been loaded by VxWorks boot code, so most initialization performed by boot-strap code must be duplicated in loaded image. The system initialization task will install drivers and ISRs, create devices, initialize the I/O system, etc. Usually, it will spawn a user application initialization task just before it terminates. The specics of a VxWorks boot image will be discussed later in the course.

Overview
Integration Issues VxWorks Boot Sequence 1.3 Tornado Directory Structure Conventions and Validation

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-25

Tornado Modularity
Tornado is composed of a set of modular components. Modularity aids in portability, exibility of use, and maintenance. Tornado modules are:
q q

Host Support Package (HSP). Generic (target independent) VxWorks. Architecture Module. Board Support Package. Wind Debug Agent (WDB Agent).

Tornado modules have been designed to minimize interdependence.

Tornado BSP Training Workshop Copyright Wind River Systems

Wind River Systems

1-26

The Host Support Package is the host-specic component of Tornado (cross-compiler, dynamic loader, Tornado tools, etc.). The generic VxWorks component is independent of host or target environments (wind kernel, semaphore libraries, I/O system, etc.). The architecture module provides support for target processor(s). The Board Support Package provides support for target hardware. The WDB agent provides target agency for the host resident Tornado tools. Because it is independent of VxWorks it can be run as task or a virtual ROM monitor.

Tornado Modularity
HSP

Generic VxWorks

WDB Agent

Arch BSP

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-27

Tornado Modularity and the Tornado Directory Tree

Files which make up Tornado are organized to reect Tornados component modularity. At the highest level les (relevant for BSP development) are separated into host and target directories. All BSP specic les are in the target directory. However, many tools useful in developing a BSP are in the host directory. Files which will be modied in developing a BSP are in a conguration sub-directory of the target directory.

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-28

Tornado Directory Tree

host Tornado hostresident tools

Tornado

share Shared XDR code target VxWorks OS

Board support package

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-29

The shared XDR code is used in the transfer of data between tools and the target. The Tornado directory tree can be installed anywhere that is convenient.

Host Directory Tree

include host-os lib Header les for Tornado tools Host-specic tools Tornado and GNU host executables Tornado Tool libraries GNU man pages

bin

host

man resource tcl man src

GUI, Tcl, and Help support les Standard Tcl distribution UNIX man pages on Tornado tools Source for VxColor demo

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-30

The directory host-os is named for your hosts hardware and operating system.

Target Directory Tree

cong all h lib Files to congure and build VxWorks Generic conguration les VxWorks header les Libraries provided by VxWorks bspName Board Support Package (BSP)

target

man UNIX man pages src Partial VxWorks source code unsupported Tools, drivers

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-31

The directory bspName is named for your targets Board Support Package.

BSP Relevant Files

All code which executes at power-up is in les within the cong directory. BSP code vs. generic driver code:
q

Generic device driver code is designed to be usable with multiple BSPs (network drivers, serial drivers, etc.). BSP (device driver) code is tightly coupled to the target environment and is not designed to be used with other BSPs.

BSP specic code will always reside in ../<bspName>. Generic device driver code not supplied by WRS will reside in the <bspName> directory or a subdirectory of <bspName>.
Tornado BSP Training Workshop Copyright Wind River Systems Wind River Systems

1-32

Generic device driver code supplied by WRS will reside in subdirectories under ../src/drv and ../h/drv.

Overview
Integration Issues VxWorks Boot Sequence Tornado Directory Structure 1.4 Conventions and Validation

Tornado BSP Training Workshop

Copyright Wind River Systems

Wind River Systems

1-33

BSP Conventions and Validation

BSP conventions and validation procedures are designed to help guarantee integrity of BSP. BSP conventions fall into categories:
q q

Coding conventions Documentation guidelines. BSP packaging. Driver guidelines. Package validation. Installation test. Functional test (VTS). Code review process and WRS validation process.
Copyright Wind River Systems Wind River Systems

Validation test:
q q

Tornado BSP Training Workshop

1-34

Users guide in BSP development kit contains discussion of BSP conventions and validation issues.

Summary
BSP responsible for supporting system hardware environment:
q q

Initialization of hardware environment. VxWorks/application access to hardware drivers. Hardware/software integration.

Provides VxWorks with primary interface to hardware environment. Components consist of:
q q

Source, include, and make les. Derived les.

May be validated to be WRS compliant.

Tornado BSP Training Workshop Copyright Wind River Systems

Wind River Systems

1-35