VxWorks BSP Developer'sGuide, 6.9
VxWorks
®
BSP DEVELOPER'S GUIDE
6.9
Copyright © 2011 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, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc.
The Wind River logo is a trademark 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:
ww w.windriver.com/company/terms/trademark.html
This product may includ e software licensed to Wind River by third parties. Relevant
notices (if any) are provided in your product installation at the following location:
installDir/product_name/3rd_party_licensor_notice.pdf.
Wind River may refer to third-party docum entation by listing pu blications or providing
links to third-party Web sites for informational purposes. Wind River accepts no
responsibility for the information provided in such third-party documentation.
Corporate Headquarters
Wind River
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.
Toll free (U.S.A.): 800-545-WIND
Telephone:
Facsimile:
510-748-4100
510-749-2010
For add itional contact information, see the Wind River Web site:
ww w.windriver.com
For information on how to contact Customer Supp ort, see:
ww w.windriver.com/support
VxWorks
BSP Developer's Guide
6.9
11 Feb 11
Contents
1
Introduction ..........................................................................................................
1.1
1.2
1.3
1.4
About This Document
.................................................................................................
The Board Support Package .......................................................................................
The BSP Development Process ..................................................................................
Terminology
.................................................................................................................
2
Overview of a BSP ..............................................................................................
2.1
2.2
2.3
Introduction ...................................................................................................................
Boot Sequence ...............................................................................................................
Sequence Overview ......................................................................................
2.2.1
2.2.2
Boot Sequence Configurations
.....................................................................
Architecture Considerations .........................................................................
2.2.3
2.2.4
Detailed Boot Sequence .................................................................................
Components of a BSP ..................................................................................................
Source and Include Files
...............................................................................
2.3.1
README .........................................................................................................
...........................................................................................................
Makefile
config.h
...........................................................................................................
......................................................................................................
bspname.h
sysALib.s
........................................................................................................
romInit.s ...........................................................................................................
sysLib.c
...........................................................................................................
target.ref ...........................................................................................................
board.jpg ..........................................................................................................
sysDev.c
..........................................................................................................
hwconf.c ...........................................................................................................
configAll.h .......................................................................................................
bootInit.c ..........................................................................................................
usrConfig.c ......................................................................................................
1
1
2
2
3
5
5
7
7
10
13
14
19
19
20
21
21
21
22
22
23
23
23
23
24
24
24
24
iii
VxWorks
BSP Developer's Guide, 6.9
2.3.2
2.3.3
2.3.4
2.3.5
2.3.6
2.3.7
2.3.8
...................................................................................................
Derived Files
..............................................................................
Required Data Variables
................................................................
sysPhysMemDesc[ ] (32-bit only)
sysPhysMemDescNumEnt (32-bit only) ......................................................
.................................................................
sysPhysRamDesc[ ] (64-bit only)
..........................................................
sysPhysRamDescCount (64-bit only)
sysDma32MemDesc[ ] (64-bit only)
............................................................
sysDma32MemDescCount (64-bit only)
.....................................................
sysUserMemDesc[ ] (64-bit only) ..................................................................
.........................................................
sysUserMemDescCount (64-bit only)
sysPmMemDesc[ ] (64-bit only)
...................................................................
sysPmMemDescCount (64-bit only) .............................................................
sysBootLine .....................................................................................................
sysExcMsg .......................................................................................................
sysFlags ............................................................................................................
hcfDeviceList[ ] ...............................................................................................
hcfDeviceNum ................................................................................................
devUnitCfgData[ ] ..........................................................................................
Required Routines ..........................................................................................
sysBspRev( )
....................................................................................................
.................................................................................
Timer Driver Routines
sysMemDescInit( ) (64-bit only)
...................................................................
sysMemDescGet( ) (64-bit only) ...................................................................
sysMemTop( ) (32-bit only)
...........................................................................
sysPhysMemTop( ) (32-bit only)
..................................................................
sysModel( ) ......................................................................................................
..........................................................................................
NVRAM Routines
Hardw are Initialization Routines
................................................................
sysSerialChanGet( ) ........................................................................................
sysToMonitor( ) ................................................................................................
...........................................................................................
Required Macros
Optional Routines
..........................................................................................
Optional Macros
.............................................................................................
Hardware Considerations .............................................................................
2.4
The Development Environment ................................................................................
..............................................................................
2.4.1
BSP Debugging Methods
..............................................................................................
Primitive Tools
....................................................................................
Native Debug ROMs
ROM Emulator
............................................................................................
On-Chip Debugging (OCD) Devices ............................................................
Logic Analyzer ................................................................................................
In-Circuit Emulator
........................................................................................
2.4.2 WDB Debugging Interface
..........................................................................
2.4.3 Workbench Libraries and Tools .....................................................................
2.4.4
..........................................................................
.............................................................................................
2.4.5
Compiler and Tool Choice
Download Path
2.5
Common Problems
.....................................................................................................
25
25
26
27
27
28
28
29
29
30
30
31
31
31
31
31
31
32
32
33
33
34
35
36
37
38
38
39
39
40
41
44
44
44
45
46
46
46
46
47
47
48
48
49
49
50
51
iv
Contents
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5
Failing to Include LOCAL_MEM_LOCAL_ADRS .....................................
Providing Too Much Device Initialization in romInit.s
...........................
Providing Insufficient Initialization in sysALib.s .......................................
Including Confusing Configuration Options
............................................
................................................................
Using Non-Maskable Interrupts
51
51
52
52
53
3
Porting a BSP to Custom Hardware ...............................................................
55
Introduction ...................................................................................................................
3.1
3.2
3.3
Getting a Default Kernel Running
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
.........................................................................
.....................................................................................
Initializing the Board
.....................................................................................
Initializing Memory
.....................................
Using Debug Routines in the Initialization Code
.....................................................................
VxBus Initialization Sequence
..............................................................
Debugging the Initialization Code
.........................................................
Initializing ROM-Based Image Types
Creating Additional Diagnostic Routines
................................................
Copying Additional Code From the Reference BSP .................................
Initializing RAM-Based Image Types
.........................................................
.......................................................................
Initializing All Image Types
Starting the WDB Agent Before the Kernel
..............................................
........................................................
Building and Downloading VxWorks
Interrupt Controllers
....................................................................................
DMA ...............................................................................................................
.........................................................................
...............................................................................................
......................................................................
3.2.6
3.2.7
3.2.8
3.2.9
3.2.10 Minimum Required Drivers
3.2.11
3.2.12 VxBus Initialization Routines
Serial Drivers
Finalizing Your BSP
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
...................................................................................................
Removing Development-Related Changes
................................................
Creating Workbench Projects
.......................................................................
Adding Other Timers
...................................................................................
Enabling NVRAM ........................................................................................
Enabling Cache and MMU Devices ..............................................................
Cache and MMU BSP Development Overview .........................................
Managing Cache and MMU During Reset and Initialization ...................
..............................
Initialize VxWorks Cache and MMU Support Layers
Providing Architecture-Specific Cache and MMU Support
.....................
Supporting L2 and L3 Cache (Optional) ....... ..............................................
.........................................................
Supporting Cache Locking (Optional)
Defining the Cache and MMU Configuration
...........................................
Additional Information .................................................................................
55
56
56
57
57
59
60
60
62
63
63
63
65
67
68
68
68
68
69
70
71
71
71
72
73
73
74
75
82
82
84
85
93
v
VxWorks
BSP Developer's Guide, 6.9
3.3.6
3.3.7
3.3.8
3.3.9
3.3.10
.......................................................................................
Testing Boot ROMs
............. .....................................................
Providing Bus Interface Support
..............................................................................................
VxBus Support
.............................................................................
PCI Bus Interface Support
........................................................................
VME Bus Interface Support
...........................................................................
USB Bus Interface Support
....................................................
Updating BSP-Specific Documentation
.....................................
Providing Additional Optional Device Support
................................................................................
Adding VxBus Devices
Adding Ethernet Devices
............................................................................
Adding Other Devices ...................................................................................
Troubleshooting and Debugging
...............................................................
............................................................................................................................. 99
SCSI Cables and Termination
Data Coherency Problems
Data Address in Virtual Memory Environments
................. ...................................................
...........................................................................
....................................
94
94
95
95
95
96
96
96
96
97
98
99
99
99
4
Adding BSP Support for VxWorks Features ............................................... 101
4.1
4.2
4.3
Introduction ................................................................................................................... 101
Power Management
..................................................................................................... 101
PROFILE_BOOTAPP ...................................................................................................
4.3.1
103
Adding PROFILE_BOOTAPP Support to a BSP ......................................... 104
Loading the ROM Compress Image to the Boot Device ............................ 106
Migrating Boot Loader Customizations to PROFILE_BOOTAPP ........... 106
4.3.2
5
Debugging Your BSP ......................................................................................... 107
5.1
5.2
Introduction ................................................................................................................... 107
................................................................ 108
Applying Basic Debugging Techniques
108
...............................................................
Using LEDs as a Diagnostic Tool
5.2.1
Verifying the Image Location
....................................................................... 108
5.2.2
Finding Addresses in the Image File ............................................................ 108
109
Finding Addresses in the Flash image
......................................................
111
Finding Addresses in RAM ..........................................................................
Verifying RAM ................................................................................................
112
Verifying the Image and OS Configuration ................................................. 113
113
Post-Processed Compiler Output
Operating System Components Built Into the Image
113
..............................................................
..............................
5.2.3
5.2.4
5.3
Applying Advanced Debugging Techniques
5.3.1
5.3.2
.......................................................
Symbols ............................................................................................................
Breakpoints
..................................................................................................
115
115
116
vi
Contents
Types of Breakpoints ......................................................................................
The Boot Procedure as It Relates to OCD ...................................................
Initial Breakpoints in Flash Images
...........................................................
Initial Breakpoints in Downloaded Images .................................................
116
116
117
117
6
Extending a BSP to an SMP System ............................................................. 119
6.1
6.2
6.3
6.4
6.5
6.6
Introduction ................................................................................................................... 119
About VxWorks SMP ...................................................................................................
120
Development Overview .............................................................................................
120
Development Prerequisites
6.4.1
6.4.2
6.4.3
6.4.4
6.4.5
........................................................................................ 121
Hardw are Documentation ............................................................................ 121
Hardware Support
121
VxWorks SMP Architecture Support
............................................................ 122
..................................................................................... 122
Existing BSP Support
VxBus Support
................................................................................................ 123
........................................................................................
Implementation Overview ........................................................................................
123
Implementation Details
6.6.1
6.6.2
6.6.3
6.6.4
6.6.5
6.6.6
6.6.7
6.6.8
.............................................................................................
125
Creating the Initial BSP ................................................................................. 125
Using Component and Configuration Preprocessor Macros .................... 125
Updating and Adding CDF Code ................................................................. 126
127
Mandatory changes ........................................................................................
127
Optional Changes ...........................................................................................
Implementing a Boot Loader Strategy ........................................................
128
.................................................................... 129
Implementing SMP Boot Logic
130
Booting the Bootstrap CPU ...........................................................................
Booting the Secondary CPUs ........................................................................
131
131
Holding a Secondary CPU in Startup or Reset
........................................
Prioritizing Interprocessor Interrupts (IPIs) ................................................
133
Modifying Cache Handling
........................................................................
134
cacheEnable( ) and cacheDisable( ) ................ .............................................. 134
cacheClear( ), cacheFlush( ), and cacheInvalidate( )
.................................. 134
cacheLock( ) and cacheUnlock( ) ................................................................... 135
Modifying Cache Modes to Support Coherency .......................................
135
Implementing SMP BSP Routines ................................................................. 135
CPU Index and CPU ID .................................................................................
135
Logical and Physical CPU Index in VxWorks 6.8 Update Pack 1
....................................................................................................
and Beyond
..................................................................................
vxCpuPhysIndexGet( )
vxCpuIdGet( )
.................................................................................................
vxCpuIndexGet( ) ...........................................................................................
136
136
137
137
vii