VxWorks
KERNEL PROGRAMMER'S GUIDE
6.9
® VxWorks Kernel Programmer's Guide, 6.9trademarks referenced are the property of their respective owners. For further information regarding Wind River trademarks, please see:
www.windriver.com/company/terms/trademark.html
This product may include software licensed to Wind River by third parties. Relevant notices (if any) are provided in your product installation at one of the following locations:
installDir/product_name/3rd_party_licensor_notice.pdf installDir/legal-notices/
Wind River may refer to third-party documentation by listing publications 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: 510-748-4100 Facsimile: 510-749-2010
For additional contact information, see the Wind River Web site: www.windriver.com
For information on how to contact Customer Support, see: www.windriver.com/support
VxWorks
Kernel Programmer's Guide 6.9
Contents
PART I: CORE TECHNOLOGIES
1
Overview ...
3
1.1 Introduction ... 3
1.2 Kernel Architecture ... 3
1.3 Related Documentation Resources ... 4
1.4 VxWorks Configuration and Build ... 5
2
VxWorks Configuration ...
7
2.1 Introduction ... 7
2.2 About VxWorks Configuration ... 7
2.2.1 Default Configuration and Images ... 8
2.2.2 Configuration With VxWorks Image Projects ... 8
2.2.3 Configuration With VxWorks Source Build Projects ... 8
2.2.4 Configuration and Customization ... 8
2.2.5 Configuration Tools: Workbench and vxprj ... 9
2.3 VxWorks Image Projects: VIPs ... 9
2.3.1 VxWorks Components ... 10
Component Names ... 10
Basic VxWorks Components ... 11
2.3.2 Device Driver Selection ... 13
2.3.3 Component Bundles and Configuration Profiles ... 14
Inconsistent Cache Mode Support ... 17
System Viewer Instrumentation Support ... 17
Real-Time Process Support ... 17
Object Management Support ... 18
Error Detection and Reporting Policy Hooks ... 18
Task Switch Hook Support ... 18
Task Create Hook Support ... 19
CPU Power Management Support ... 19
Advanced Options ... 19
VxWorks BSP Validation Test Suite Support ... 20
Symmetric Multiprocessor (SMP) Support ... 20
SMP Determinism ... 20
MIPC Support ... 20
WRLOAD Support ... 20
2.4.2 VSB Profiles ... 20
2.4.3 Using VSB Projects to Create VxWorks Systems: Basic Steps ... 20
2.4.4 Developing Kernel Applications for VSB Systems ... 21
2.5 VxWorks Without Networking ... 21
2.6 Small-Footprint VxWorks Configuration ... 21
2.6.1 About Small-Footprint VxWorks ... 22
Kernel Facilities ... 22
Unsupported Facilities ... 22
BSPs ... 22
2.6.2 Configuring Small Footprint VxWorks ... 23
Small-Footprint VSB Profile and Options ... 23
VSB Options Specific to the Small-Footprint Profile ... 24
Small-Footprint VIP Profile and Components ... 24
Optional Components for a Small Footprint VIP Project ... 24
2.6.3 Configuration and Build Steps for Small-Footprint VxWorks ... 25
2.6.4 Writing Applications for Small-Footprint VxWorks ... 25
2.6.5 Example Application ... 26
2.6.6 Debugging Small-Footprint VxWorks ... 27
2.7 Power Management Facilities ... 27
2.7.1 Light Power Management ... 28
2.8 VxWorks Image Types ... 28
2.8.1 Default VxWorks Images ... 29
2.8.2 VxWorks Images for Development and Production Systems ... 29
2.8.3 Boot Parameter Configuration for Standalone VxWorks Images ... 30
3
Boot Loader ...
31
Contents
3.2 Using a Default Boot Loader ... 32
3.3 Boot Loader Image Types ... 33
3.4 Boot Loader Shell ... 33
3.4.1 Boot Loader Shell Commands ... 34
3.5 Boot Parameters ... 37
3.5.1 Displaying Current Boot Parameters ... 38
3.5.2 Description of Boot Parameters ... 39
3.5.3 Changing Boot Parameters Interactively ... 42
3.6 Rebooting VxWorks ... 43
3.7 Configuring and Building Boot Loaders ... 43
3.7.1 Boot Loader Profiles ... 44
3.7.2 Boot Loader Components ... 45
3.7.3 Configuring Boot Parameters Statically ... 45
3.7.4 Enabling Networking for Non-Boot Interfaces ... 46
3.7.5 Selecting a Boot Device ... 46
3.7.6 Reconfiguring Boot Loader Memory Layout for 32-Bit VxWorks ... 48
Redefining the Boot Loader Link Address for Custom Boot Loaders ... 48
Reconfiguring Memory Layout for a Persistent Memory Region ... 49
3.7.7 Reconfiguring Boot Loader Memory Layout for 64-Bit VxWorks ... 51
3.7.8 Building Boot Loaders ... 51
3.8 Installing Boot Loaders ... 51
3.9 Booting From a Network ... 51
3.10 Booting From a Target File System ... 53
3.11 Booting From the Host File System Using TSFS ... 53
4
Kernel Applications ...
55
4.1 Introduction ... 55
4.2 About Kernel Applications ... 56
4.3 C and C++ Libraries ... 57
4.5.3 ANSI Header Files ... 59
4.5.4 ANSI C++ Header Files ... 59
4.5.5 The -I Compiler Flag ... 59
4.5.6 VxWorks Nested Header Files ... 59
4.5.7 VxWorks Private Header Files ... 60
4.6 Custom Header Files ... 60
4.7 Static Instantiation of Kernel Objects ... 61
4.7.1 About Static Instantiation of Kernel Objects ... 61
Kernel Objects That can be Instantiated Statically ... 62
Static Instantiation and Code Size ... 62
Advantages of Static Instantiation ... 62
Applications and Static Instantiation ... 62
4.7.2 Scope Of Static Declarations ... 63
4.7.3 Caveat With Regard to Macro Use ... 63
4.7.4 Static Instantiation of Tasks ... 63
4.7.5 Static Instantiation Of Semaphores ... 64
4.7.6 Static Instantiation of Message Queues ... 65
4.7.7 Static Instantiation of Watchdog Timers ... 65
4.8 Kernel Applications and Kernel Component Requirements ... 66
4.9 Building Kernel Application Modules ... 66
4.10 Downloading Kernel Application Object Modules to a Target ... 67
4.11 Linking Kernel Application Object Modules with VxWorks ... 67
4.12 Configuring VxWorks to Run Applications Automatically ... 67
4.13 Image Size Considerations ... 68
4.13.1 Boot Loader and Downloadable Image ... 68
4.13.2 Self-Booting Image ... 68
5
C++ Development ...
71
5.1 Introduction ... 71
5.2 Configuring VxWorks for C++ ... 72
5.3 C++ Header Files ... 72
5.4 Spawning Tasks That Use C++ ... 72
5.5 Calls Between C and C++ Code ... 73
Contents
5.7 Using C++ in Signal Handlers and ISRs ... 73
5.8 Downloadable Kernel Modules in C++ ... 74
5.8.1 Use a Single C++ Module ... 74
5.8.2 Munching a C++ Application Module ... 74
5.8.3 Calling Static Constructors and Destructors Interactively ... 76
5.9 C++ Compiler Differences ... 77
5.9.1 Template Instantiation ... 77
5.9.2 Run-Time Type Information ... 78
5.10 Namespaces ... 79
5.11 C++ Exception Handling ... 79
5.12 C++ Demo Example ... 80
6
Multitasking ...
81
6.1 Introduction ... 81
6.2 About Tasks and Multitasking ... 82
6.2.1 Task States and Transitions ... 83
Tasks States and State Symbols ... 83
Illustration of Basic Task State Transitions ... 84
6.3 VxWorks System Tasks ... 85
Basic VxWorks Tasks ... 86
Tasks for Optional Components ... 88
6.4 Task Scheduling ... 90
6.4.1 Task Priorities ... 91
6.4.2 VxWorks Traditional Scheduler ... 91
Priority-Based Preemptive Scheduling ... 91
Scheduling and the Ready Queue ... 92
Round-Robin Scheduling ... 93
6.5 Task Creation and Management ... 94
6.5.1 Task Creation and Activation ... 95
Static instantiation of Tasks ... 96
6.5.2 Task Names and IDs ... 96
Task Stack Protection ... 99
6.5.6 Task Information ... 100
6.5.7 Task Deletion and Deletion Safety ... 101
6.5.8 Task Execution Control ... 102
6.5.9 Task Scheduling Control ... 103
6.5.10 Tasking Extensions: Hook Routines ... 103
6.6 Task Error Status: errno ... 105
6.6.1 Layered Definitions of errno ... 105
6.6.2 A Separate errno Value for Each Task ... 106
6.6.3 Error Return Convention ... 106
6.6.4 Assignment of Error Status Values ... 107
6.7 Task Exception Handling ... 107
6.8 Shared Code and Reentrancy ... 107
6.8.1 Dynamic Stack Variables ... 109
6.8.2 Guarded Global and Static Variables ... 109
6.8.3 Task-Specific Variables ... 109
Thread-Local Variables: __thread Storage Class ... 110
taskVarLib and Task Variables ... 111
6.8.4 Multiple Tasks with the Same Main Routine ... 111
7
Intertask and Interprocess Communication ... 113
7.1 Introduction ... 113
7.2 About Intertask and Interprocess Communication ... 114
7.3 Shared Data Structures ... 115
7.4 Interrupt Locks ... 116
7.5 Task Locks ... 117
7.6 Semaphores ... 118
7.6.1 Inter-Process Communication With Public Semaphores ... 119
7.6.2 Semaphore Creation and Use ... 119
Options for Scalable and Inline Semaphore Routines ... 121
Static Instantiation of Semaphores ... 121
Scalable and Inline Semaphore Take and Give Routines ... 122
7.6.3 Binary Semaphores ... 122
Mutual Exclusion ... 123
Synchronization ... 124
Contents
Priority Inversion and Priority Inheritance ... 125
Deletion Safety ... 127
Recursive Resource Access ... 127
7.6.5 Counting Semaphores ... 128
7.6.6 Read/Write Semaphores ... 129
Specification of Read or Write Mode ... 129
Precedence for Write Access Operations ... 130
Read/Write Semaphores and System Performance ... 130
7.6.7 Special Semaphore Options ... 131
Semaphore Timeout ... 131
Semaphores and Queueing ... 131
Semaphores and VxWorks Events ... 132
7.7 Message Queues ... 132
7.7.1 Inter-Process Communication With Public Message Queues ... 133
7.7.2 Message Creation and Use ... 133
Static Instantiation of Message Queues ... 134
Message Queue Timeout ... 134
Message Queue Urgent Messages ... 134
Message Queues and Queuing Options ... 135
7.7.3 Displaying Message Queue Attributes ... 135
7.7.4 Servers and Clients with Message Queues ... 135
7.7.5 Message Queues and VxWorks Events ... 136
7.8 Pipes ... 136
7.9 VxWorks Events ... 137
7.9.1 Configuring VxWorks for Events ... 137
7.9.2 About Event Flags and the Task Events Register ... 138
7.9.3 Receiving Events ... 139
7.9.4 Sending Events ... 140
7.9.5 Inter-Process Communication With Events ... 142
7.9.6 Events Routines ... 142
7.9.7 Code Example ... 142
7.9.8 Show Routines and Events ... 143
7.10 Inter-Process Communication With Public Objects ... 143
Creating and Naming Public and Private Objects ... 143
8.2 Signals ... 148
8.2.1 Configuring VxWorks for Signals ... 149
8.2.2 Basic Signal Routines ... 150
8.2.3 Queued Signal Routines ... 151
8.2.4 Signal Events ... 154
8.2.5 Signal Handlers ... 155
8.3 Interrupt Service Routines: ISRs ... 157
8.3.1 Configuring VxWorks for ISRs ... 158
Configuring the Interrupt Stack ... 158
Adding Show Routine Support ... 159
8.3.2 Writing ISRs ... 159
Restrictions on ISRs ... 159
Facilities Available for ISRs ... 160
Reserving High Interrupt Levels ... 162
8.3.3 System Clock ISR Modification ... 163
8.3.4 Connecting ISRs to Interrupts ... 163
8.3.5 Getting Information About ISRs ... 164
8.3.6 Debugging ISRs ... 164
8.4 Watchdog Timers ... 166
Static Instantiation of Watchdog Timers ... 167
8.4.1 Inter-Process Communication With Public Watchdog Timers ... 167
9
POSIX Facilities ... 169
9.1 Introduction ... 170
9.2 Configuring VxWorks with POSIX Facilities ... 171
9.2.1 VxWorks Components for POSIX Facilities ... 171
9.3 General POSIX Support ... 172
9.4 POSIX Header Files ... 173
9.5 POSIX Namespace ... 175
9.6 POSIX Clocks and Timers ... 175
9.7 POSIX Asynchronous I/O ... 178
9.8 POSIX Advisory File Locking ... 178
9.9 POSIX Page-Locking Interface ... 179
Contents
9.10.1 POSIX Thread Attributes ... 180
9.10.2 VxWorks-Specific Pthread Attributes ... 180
9.10.3 Specifying Attributes when Creating Pthreads ... 181
9.10.4 POSIX Thread Creation and Management ... 182
9.10.5 POSIX Thread Attribute Access ... 182
9.10.6 POSIX Thread Private Data ... 183
9.10.7 POSIX Thread Cancellation ... 184
9.11 POSIX Thread Mutexes and Condition Variables ... 185
9.11.1 Thread Mutexes ... 185
Protocol Mutex Attribute ... 186
Priority Ceiling Mutex Attribute ... 187
9.11.2 Condition Variables ... 187
9.12 POSIX and VxWorks Scheduling ... 188
9.12.1 Differences in POSIX and VxWorks Scheduling ... 189
9.12.2 POSIX and VxWorks Priority Numbering ... 190
9.12.3 Default Scheduling Policy ... 190
9.12.4 VxWorks Traditional Scheduler ... 190
9.12.5 POSIX Threads Scheduler ... 191
9.12.6 POSIX Scheduling Routines ... 195
9.12.7 Getting Scheduling Parameters: Priority Limits and Time Slice ... 195
9.13 POSIX Semaphores ... 196
9.13.1 Comparison of POSIX and VxWorks Semaphores ... 197
9.13.2 Using Unnamed Semaphores ... 198
9.13.3 Using Named Semaphores ... 200
9.14 POSIX Message Queues ... 203
9.14.1 Comparison of POSIX and VxWorks Message Queues ... 204
9.14.2 POSIX Message Queue Attributes ... 204
9.14.3 Displaying Message Queue Attributes ... 206
9.14.4 Communicating Through a Message Queue ... 206
9.14.5 Notification of Message Arrival ... 209
9.15 POSIX Signals ... 213
10.2 32-Bit VxWorks Memory Layout ... 216
10.2.1 Displaying Information About Memory Layout ... 216
10.2.2 System Memory Map Without RTP Support ... 216
10.2.3 System Memory Map with RTP Support ... 218
10.2.4 System RAM Autosizing ... 220
10.2.5 Reserved Memory: User-Reserved Memory and Persistent Memory ... 220
10.3 64-Bit VxWorks Memory Layout ... 221
10.3.1 Displaying Information About Memory Layout ... 221
10.3.2 Virtual Memory Regions ... 222
Kernel System Virtual Memory Region ... 223
Kernel Virtual Memory Pool Region ... 224
Kernel Reserved Memory Region ... 224
Shared User Virtual Memory Region ... 224
RTP Private Virtual Memory Region ... 224
10.3.3 Global RAM Pool ... 225
10.3.4 Kernel Memory Map ... 225
Kernel System Memory ... 227
Kernel Common Heap ... 227
DMA32 Heap ... 227
User-Reserved Memory ... 227
Persistent Memory ... 227
10.3.5 Reserved Memory Configuration: User-Reserved Memory and Persistent Memory ... 228
10.3.6 System RAM Autosizing ... 228
10.4 About VxWorks Memory Allocation Facilities ... 228
10.5 32-Bit VxWorks Heap and Memory Partition Management ... 229
10.5.1 Configuring the Kernel Heap and the Memory Partition Manager ... 230
10.5.2 Basic Heap and Memory Partition Manager ... 230
10.5.3 Full Heap and Memory Partition Manager ... 230
10.6 64-Bit VxWorks Heap and Memory Partition Management ... 231
10.6.1 Kernel Common Heap ... 231
10.6.2 Kernel Proximity Heap ... 232
10.6.3 DMA32 Heap ... 232
10.7 Memory Pools ... 233
10.8 POSIX Memory Management ... 233
10.8.1 POSIX Memory Management APIs ... 233
10.8.2 POSIX Memory Mapping ... 235
Contents
10.8.4 POSIX Memory Locking ... 235
10.9 Memory Mapping Facilities ... 235
10.9.1 POSIX Memory-Mapped Files ... 237
10.9.2 POSIX Shared Memory Objects ... 238
10.9.3 Anonymous Memory Mapping ... 238
10.9.4 Device Memory Objects ... 239
10.9.5 Shared Data Regions ... 239
10.10 Virtual Memory Management ... 240
10.10.1 Configuring Virtual Memory Management ... 240
10.10.2 Managing Virtual Memory Programmatically ... 242
Modifying Page States ... 243
Making Memory Non-Writable ... 244
Invalidating Memory Pages ... 245
Locking TLB Entries ... 246
Page Size Optimization ... 246
Setting Page States in ISRs ... 246
10.10.3 Troubleshooting ... 247
10.11 Additional Memory Protection Features ... 248
10.11.1 Configuring VxWorks for Additional Memory Protection ... 248
10.11.2 Stack Overrun and Underrun Detection ... 249
10.11.3 Non-Executable Task Stack ... 249
10.11.4 Text Segment Write Protection ... 249
10.11.5 Exception Vector Table Write Protection ... 249
10.12 Memory Error Detection ... 249
10.12.1 Heap and Partition Memory Instrumentation ... 250
10.12.2 Compiler Instrumentation: 32-Bit VxWorks ... 254
11
I/O System ... 259
11.1 Introduction ... 259
11.2 About the VxWorks I/O System ... 260
Differences Between VxWorks and Host System I/O ... 260
11.3 Configuring VxWorks With I/O Facilities ... 261
File Descriptor Table ... 266
11.6.2 Standard Input, Standard Output, and Standard Error ... 266
11.6.3 Standard I/O Redirection ... 266
Issues with Standard I/O Redirection ... 267
11.6.4 Open and Close ... 268
11.6.5 Create and Remove ... 270
11.6.6 Read and Write ... 271
11.6.7 File Truncation ... 271
11.6.8 I/O Control ... 272
11.6.9 Pending on Multiple File Descriptors with select( ) ... 272
11.6.10 POSIX File System Routines ... 274
11.7 Standard I/O ... 275
11.7.1 Configuring VxWorks With Standard I/O ... 275
11.7.2 About printf( ), sprintf( ), and scanf( ) ... 276
11.7.3 About Standard I/O and Buffering ... 276
11.7.4 About Standard Input, Standard Output, and Standard Error ... 277
11.8 Other Formatted I/O ... 277
11.8.1 Output in Serial I/O Polled Mode: kprintf( ) ... 277
Writing to User-Defined Storage Media With kprintf( ) and kputs( ) ... 278
11.8.2 Additional Formatted I/O Routines ... 279
11.8.3 Message Logging ... 279
11.9 Asynchronous Input/Output ... 279
11.9.1 The POSIX AIO Routines ... 279
11.9.2 AIO Control Block ... 281
11.9.3 Using AIO ... 282
AIO with Periodic Checks for Completion ... 282
Alternatives for Testing AIO Completion ... 284
12
Devices ... 287
12.1 Introduction ... 287
12.2 About Devices in VxWorks ... 288
12.3 Serial I/O Devices: Terminal and Pseudo-Terminal Devices ... 289
tty Options ... 289
12.3.1 Raw Mode and Line Mode ... 290
12.3.2 tty Special Characters ... 290
Contents
12.4 Pipe Devices ... 292
12.4.1 Creating Pipes ... 292
12.4.2 Writing to Pipes from ISRs ... 292
12.4.3 I/O Control Functions ... 293
12.5 Pseudo I/O Device ... 293
12.5.1 I/O Control Functions ... 293
12.6 Null Devices ... 294
12.7 Block Devices ... 294
12.7.1 XBD RAM Disk ... 295
12.7.2 SCSI Drivers ... 296
Configuring SCSI Drivers ... 296
Structure of the SCSI Subsystem ... 297
Booting and Initialization ... 298
Device-Specific Configuration Options ... 299
SCSI Configuration Examples ... 300
Troubleshooting ... 302
12.8 Extended Block Device Facility: XBD ... 303
12.8.1 XBD Disk Partition Manager ... 304
12.8.2 XBD Block Device Wrapper ... 304
12.8.3 XBD TRFS Component ... 305
12.9 PCMCIA ... 305
12.10 Peripheral Component Interconnect: PCI ... 305
12.11 Network File System (NFS) Devices ... 306
12.11.1 Mounting a Remote NFS File System from VxWorks ... 306
12.11.2 I/O Control Functions for NFS Clients ... 306
12.12 Non-NFS Network Devices ... 307
12.12.1 Creating Network Devices ... 307
12.12.2 I/O Control Functions ... 308
12.13 Sockets ... 308
12.14 Internal I/O System Structure ... 308
12.14.1 Drivers ... 310
Deleting Devices ... 314
12.14.3 File Descriptors ... 316
File Descriptor Table ... 317
Example of Opening a File ... 317
Example of Reading Data from the File ... 319
Example of Closing a File ... 320
Implementing select( ) ... 320
Cache Coherency ... 323
13
Local File Systems ... 327
13.1 Introduction ... 327
13.2 File System Monitor ... 329
Device Insertion Events ... 330
XBD Name Mapping Facility ... 331
13.3 Virtual Root File System: VRFS ... 331
13.4 Highly Reliable File System: HRFS ... 332
13.4.1 Configuring VxWorks for HRFS ... 333
13.4.2 Configuring HRFS ... 334
13.4.3 Creating an HRFS File System ... 334
Overview of HRFS File System Creation ... 335
HRFS File System Creation Steps ... 335
13.4.4 HRFS, ATA, and RAM Disk Examples ... 336
13.4.5 Optimizing HRFS Performance ... 341
13.4.6 Transactional Operations and Commit Policies ... 341
Automatic Commit Policy ... 341
High-Speed Commit Policy ... 342
Mandatory Commits ... 342
Rollbacks ... 342
Programmatically Initiating Commits ... 343
13.4.7 File Access Time Stamps ... 343
13.4.8 Maximum Number of Files and Directories ... 343
13.4.9 Working with Directories ... 343
Creating Subdirectories ... 343
Removing Subdirectories ... 344
Reading Directory Entries ... 344
13.4.10 Working with Files ... 344
File I/O Routines ... 344
File Linking and Unlinking ... 344
File Permissions ... 345
13.4.11 I/O Control Functions Supported by HRFS ... 345
Contents
Crash Recovery ... 346
Consistency Checking ... 346
13.4.13 File Management and Full Devices ... 346
13.5 MS-DOS-Compatible File System: dosFs ... 347
13.5.1 Configuring VxWorks for dosFs ... 348
13.5.2 Configuring dosFs ... 349
13.5.3 Creating a dosFs File System ... 350
Overview of dosFs File System Creation ... 350
dosFs File System Creation Steps ... 350
13.5.4 dosFs, ATA Disk, and RAM Disk Examples ... 353
13.5.5 Optimizing dosFs Performance ... 357
13.5.6 Working with Volumes and Disks ... 357
Accessing Volume Configuration Information ... 358
Synchronizing Volumes ... 358
13.5.7 Working with Directories ... 358
Creating Subdirectories ... 358
Removing Subdirectories ... 358
Reading Directory Entries ... 359
13.5.8 Working with Files ... 359
File I/O Routines ... 359
File Attributes ... 359
13.5.9 Disk Space Allocation Options ... 361
Choosing an Allocation Method ... 361
Using Cluster Group Allocation ... 362
Using Absolutely Contiguous Allocation ... 362
13.5.10 Crash Recovery and Volume Consistency ... 364
13.5.11 I/O Control Functions Supported by dosFsLib ... 364
13.5.12 Booting from a Local dosFs File System Using SCSI ... 365
13.6 Transaction-Based Reliable File System Support for dosFs: TRFS ... 367
13.6.1 Configuring VxWorks With TRFS ... 368
13.6.2 Automatic Instantiation of TRFS ... 368
13.6.3 Formatting a Device for TRFS ... 368
13.6.4 Using TRFS in Applications ... 369
TRFS Code Examples ... 370
13.7.5 I/O Control Functions Supported by rawFsLib ... 373
13.8 CD-ROM File System: cdromFs ... 374
13.8.1 Configuring VxWorks for cdromFs ... 375
13.8.2 Creating and Using cdromFs ... 376
13.8.3 I/O Control Functions Supported by cdromFsLib ... 378
13.8.4 Version Numbers ... 378
13.9 Read-Only Memory File System: ROMFS ... 379
13.9.1 Configuring VxWorks with ROMFS ... 379
13.9.2 Building a System With ROMFS and Files ... 379
13.9.3 Accessing Files in ROMFS ... 380
13.9.4 Using ROMFS to Start Applications Automatically ... 380
13.10 Target Server File System: TSFS ... 380
Socket Support ... 381
Error Handling ... 382
Configuring VxWorks for TSFS Use ... 382
Security Considerations ... 382
Using the TSFS to Boot a Target ... 383
14
Flash File System Support: TrueFFS ... 385
14.1 Introduction ... 385
14.2 Overview of Implementation Steps ... 386
14.3 Creating a VxWorks System with TrueFFS ... 387
14.3.1 Selecting an MTD ... 388
14.3.2 Identifying the Socket Driver ... 388
14.3.3 Configuring VxWorks with TrueFFS and File System ... 388
Including the Core TrueFFS Component ... 389
Including the MTD Component ... 389
Including the Translation Layer Component ... 390
Including the Socket Driver ... 390
Including the XBD Wrapper Component ... 391
Including File System Components ... 391
Including Utility Components ... 391
14.3.4 Building the System ... 392
14.3.5 Formatting the Flash ... 392
Formatting With sysTffsFormat( ) ... 392
Formatting With tffsDevFormat( ) ... 393
14.3.6 Reserving a Region in Flash for a Boot Image ... 394
Reserving a Fallow Region ... 395
Contents
14.3.7 Mounting the Drive ... 397
14.3.8 Creating a File System ... 397
14.3.9 Testing the Drive ... 398
14.4 Using TrueFFS Shell Commands ... 398
14.5 Using TrueFFS With HRFS ... 399
14.5.1 TrueFFS With HRFS Code Example ... 399
14.5.2 TrueFFS With HRFS Shell Command Example ... 400
14.6 Using TrueFFS with dosFs ... 401
15
Network File System: NFS ... 403
15.1 Introduction ... 403
15.2 Configuring VxWorks for an NFS Client ... 403
Core NFS Client ... 404 NFS Client All ... 404 NFS v2 Client ... 404 NFS v3 Client ... 406 NFS Mount All ... 407 15.3 Creating an NFS Client ... 408
Exporting File Systems from the Remote NFS Server ... 408
Setting Your NFS Client Name, User ID, and Group ID ... 409
Mounting a Remote File System ... 409
Using ioctl( ) With Open Files from a Mounted Directory ... 411
15.4 Configuring VxWorks for an NFS Server ... 412
NFS Server ... 412
NFS server All ... 413
NFS server V2 ... 413
NFS server V3 ... 414
15.5 Creating an NFS Server ... 415
Initializing an NFS File System for Export ... 415
Exporting a File System through NFS ... 416
16
Kernel Core Dumps ... 417
16.1 Introduction ... 417
16.2 About Kernel Core Dumps ... 418
16.4 Configuring Persistent Memory-Region Storage ... 423
16.4.1 Configuring the VxWorks Components ... 424
About Persistent Memory Uses ... 424
Configuring Persistent Memory for Core Dump Use ... 425
16.4.2 Verifying Persistent Memory Configuration ... 425
16.4.3 Configuring the 32-Bit Boot Loader ... 426
16.5 Enabling Core Dump File Compression ... 427
16.6 Changing the Areas of Memory Captured by Core Dumps ... 428
16.6.1 Including the Kernel Text Section in Core Dumps ... 428
16.6.2 Excluding User Reserved Memory From Core Dumps ... 428
16.6.3 Filtering Selected Memory Areas From Core Dumps ... 429
16.6.4 Adding Additional Memory Areas to Core Dumps ... 429
16.7 Using the Core Dump Hook Routine Manager ... 429
16.8 Initializing the Kernel Core Dump Facility ... 430
16.9 Generating Kernel Core Dumps ... 431
16.10 Managing Kernel Core Dump Files ... 431
16.11 Analyzing Kernel Core Dumps ... 434
17
Core Dump Raw Device Interface ... 435
17.1 Introduction ... 435
17.2 Creating Custom Raw Device Storage Support ... 436
17.3 Coding a Raw Device-Driver Interface ... 436
17.3.1 Coding Guidelines ... 436
17.3.2 Required Routines ... 437
Device-Driver Interface Initialization Routine ... 437
sysCoreDumpDevWrite( ) ... 438
sysCoreDumpRawDevRead( ) ... 438
17.3.3 Optional Routines ... 439
sysCoreDumpDevErase( ) ... 439
sysCoreDumpDevFlush( ) ... 439
17.4 Using a Custom Component for the Raw Device-Driver Interface ... 439
17.5 Adding the Raw Device-Driver Interface to a BSP ... 440
18
Error Detection and Reporting ... 443
Contents
18.2 Configuring Error Detection and Reporting Facilities ... 444
18.2.1 Configuring VxWorks ... 444
18.2.2 Configuring the Persistent Memory Region ... 444
18.2.3 Configuring Responses to Fatal Errors ... 445
18.3 Error Records ... 445
18.4 Displaying and Clearing Error Records ... 447
18.5 About Fatal Error Response Modes ... 448
18.6 Setting Fatal Error Handling Mode ... 449
18.7 Using Error Reporting APIs in Application Code ... 449
18.8 Sample Error Record ... 450
PART II: VXWORKS CUSTOMIZATION
19
Custom Components and CDFs ... 455
19.1 Introduction ... 455
19.2 Code Development for Components ... 456
19.3 Code Installation Directories ... 456
19.4 CDF Objects and Properties ... 457
19.4.1 Reserved Object Name Prefixes ... 458
19.4.2 Underscore Operator and Object Relationships ... 458
19.4.3 Component Object and Properties ... 459
Component Template ... 459
Component Name ... 460
Component Properties ... 460
Component Example ... 467
19.4.4 Parameter Object and Properties ... 468
Parameter Template ... 468
Parameter Name ... 468
Parameter Properties ... 469
Parameter Example ... 469
19.4.5 Initialization Group Object and Properties ... 470
Initialization Group Objects ... 471
Bundle Template ... 474 Bundle Name ... 474 Bundle Properties ... 474 Bundle Example ... 474 19.4.7 Profile Object and Properties ... 475 Profile Template ... 475 Profile Name ... 475 Profile Properties ... 476 Profile Example ... 476 19.4.8 Workbench Folder Object and Properties ... 476 Folder Template ... 477 Folder Name ... 477 Folder Properties ... 477 Folder Example ... 478 19.4.9 Workbench Selection Object and Properties ... 478 Selection Template ... 479 Selection Name ... 479 Selection Properties ... 479 Selection Example ... 480 19.4.10 BSP Object and Properties ... 480 BSP Template ... 480 BSP Name ... 480 BSP Properties ... 481 BSP Example ... 482 19.5 CDF File Names and Precedence ... 482 19.6 CDF Installation Directories and Precedence ... 483 Precedence of configAll.h and config.h Over CDF Files ... 483 About CDF Precedence ... 483 CDF Directories and Precedence ... 483 Overriding Wind River Component Properties ... 484 19.7 CDF Testing ... 484 19.8 About CDFs, VxWorks Configuration, and Build ... 486
20
Custom System Calls ... 487
20.1 Introduction ... 487 20.2 About System Calls ... 488 20.3 System Call Requirements ... 488 20.3.1 System Call Naming Rules ... 488 20.3.2 System Call Numbering Rules ... 489 20.3.3 System Call Argument Rules ... 490 20.3.4 System Call Return Value Rules ... 491
Contents
20.4 System Call Handler Requirements ... 492 20.4.1 System Call Handler Naming Rules ... 492 20.4.2 System Call Parameter ... 492 20.4.3 System Call Handler Argument Validation ... 493 20.4.4 System Call Handler Error Reporting ... 493 20.5 Example System Call Handler ... 493 20.6 Example System Call Handler Header File ... 495 20.7 Example System Call Header File ... 496 20.8 Adding System Calls Statically ... 496 20.8.1 Overview of Adding System Calls Statically ... 497 20.8.2 Procedure for Adding System Calls Statically ... 497 20.9 Adding System Calls Dynamically ... 503 20.9.1 Requirements for Dynamic Registration ... 503 System Call Handler Routine Table ... 503 System Call Handler Argument Structure ... 504 Registration of System Call ... 505 20.9.2 Building the System Call Handler ... 506 20.9.3 Downloading the Module and Registering the System Calls ... 506 20.10 About Testing System Calls from an RTP Application ... 506 20.11 Example RTP Application Using Custom System Calls ... 507 20.12 Monitoring And Debugging System Calls ... 508 20.13 Documenting Custom System Calls ... 510
21
Custom Scheduler ... 511
21.1 Introduction ... 511 21.2 About the Traditional VxWorks Scheduler ... 512 21.2.1 Scheduler Initialization ... 512 21.2.2 Multi-way Queue Structure ... 512 21.3 Requirements for a Custom Scheduler ... 517 21.3.1 Code Requirements ... 517 21.3.2 Configuration Requirements ... 519
PART III: MULTIPROCESSING TECHNOLOGIES
22
Overview of Multiprocessing Technologies ... 523
22.1 Introduction ... 523 22.2 VxWorks SMP ... 523 22.3 VxWorks AMP ... 524 22.4 Shared Memory Objects ... 524 22.5 Message Channels ... 524
23
VxWorks SMP ... 525
23.1 Introduction ... 526 23.2 About VxWorks SMP ... 526 23.2.1 Terminology ... 526 23.2.2 VxWorks SMP Operating System Features ... 527 23.2.3 VxWorks SMP Hardware ... 528 23.2.4 Comparison of VxWorks SMP and AMP ... 530 23.3 VxWorks SMP Configuration ... 531 23.4 VxWorks SMP Configuration for Multicore AMP Systems ... 533 23.5 Booting VxWorks SMP ... 534 23.6 Programming for VxWorks SMP ... 535 23.7 Spinlocks for Mutual Exclusion and Synchronization ... 537 23.7.1 ISR-Callable Spinlocks ... 538 Deterministic ISR-Callable Spinlocks ... 539 Non-Deterministic ISR-Callable Spinlocks ... 539 23.7.2 Task-Only Spinlocks ... 540 23.7.3 Caveats With Regard to Spinlock Use ... 540 23.7.4 Debug Versions of Spinlocks ... 541 23.7.5 Routines Restricted by Spinlock Use ... 541 23.8 CPU-Specific Mutual Exclusion ... 543 23.8.1 CPU-Specific Mutual Exclusion for Interrupts ... 543 23.8.2 CPU-Specific Mutual Exclusion for Tasks ... 543 23.9 Memory Barriers ... 544 Read Memory Barrier ... 545 Write Memory Barrier ... 545
Contents
Read/Write Memory Barrier ... 546 23.10 Atomic Memory Operations ... 546 23.11 CPU Affinity ... 547 23.11.1 Task CPU Affinity ... 547 23.11.2 Interrupt CPU Affinity ... 549 23.12 CPU Reservation for CPU-Affinity Tasks ... 550 23.13 CPU Information and Management ... 551 CPU Information and Management Routines ... 551 CPU Set Variables and Macros ... 553 23.14 Debugging SMP Code ... 554 23.15 Optimizing SMP Performance ... 555 23.16 Sample Programs ... 557 23.17 Migrating Code to VxWorks SMP ... 558 23.17.1 Code Migration Path ... 558 23.17.2 Overview of Migration Issues ... 559 23.17.3 RTP Applications and SMP ... 560 23.17.4 Implicit Synchronization of Tasks ... 561 23.17.5 Synchronization and Mutual Exclusion Facilities ... 561 23.17.6 VxWorks SMP Variants of Uniprocessor Routines ... 562 cacheLib Restrictions ... 562 vmBaseLib Restrictions ... 563 23.17.7 Unsupported Uniprocessor Routines and SMP Alternatives ... 563 Interrupt Locking: intLock( ) and intUnlock( ) ... 563 Task Locking: taskLock( ) and taskUnlock( ) ... 564 Task Locking in RTPs: taskRtpLock( ) and taskRtpUnlock( ) ... 565 Task Variable Management: taskVarLib ... 565 Task Local Storage: tlsLib ... 565 23.17.8 SMP CPU-Specific Variables and Uniprocessor Global Variables ... 565 SMP Per-CPU Variables ... 566 Uniprocessor-Only Global Variables ... 566 23.17.9 Memory-Access Attributes ... 567 23.17.10 Drivers and BSPs ... 567
24.3 VxWorks AMP and MIPC ... 570 24.4 VxWorks AMP with SMP ... 570 24.5 Terminology: Nodes and CPUs ... 571 24.6 Architectural Overview of AMP with MIPC ... 572 24.7 The wrload Utility for Booting VxWorks on Multiple CPUs ... 572 24.8 Restrictions on the Use of AMP ... 573 24.9 Organization of Chapters on VxWorks AMP ... 573
25
Configuring VxWorks for AMP ... 575
25.1 Introduction ... 575 25.2 BSP Support for AMP ... 575 25.3 Configuring AMP for a BSP ... 577 25.4 Configuring Raza Processors for AMP ... 579 25.4.1 Assigning a Raza Image to a CPU ... 580
BSPs rmi_xls_lte_AMP_mipsi64sf and rmi_xlr_AMP_mipsi64sf: Assigning Images to CPUs ... 580 BSPs rmi_xls_lte_mipsi64sf and rmi_xlr_mipsi64sf: Assigning Images to CPUs
581
25.4.2 Assigning Serial Ports for the Raza Processors ... 582 25.4.3 Assigning Ethernet Ports for the Raza Processors ... 583 rmi_xls_lte_AMP_mipsi64sf and rmi_xlr_AMP_mipsi64sf: Assigning Ports to
CPUs ... 583 rmi_xls_lte_mipsi64sf and rmi_xlr_mipsi64sf: Assigning Ports to CPUs . 584 25.5 Configuring Cavium Processors for AMP ... 585 25.5.1 Assigning a Cavium Image to a CPU ... 585
BSPs cav_cn3xxx_AMP_mipsi64r2sf and cav_cn58xx_AMP_mipsi64r2sf: Assigning Images to CPUs ... 585 BSPs cav_cn3xxx_mipsi64r2sf and cav_cn58xx_mipsi64r2sf: Assigning Images to
CPUs ... 585 25.5.2 Assigning Cavium UP and SMP Images to CPUs: An Example ... 586 25.5.3 Assigning UARTs to Cavium Images ... 586 25.6 Configuring AMP for VxMP (PowerPC) ... 587 25.7 Configuring WDB over MIPC for Debugging AMP ... 587 Including WDB Agent Proxy for MIPC in a Build ... 588 Including the WDB Target Agent in a Build with VxWorks AMP and MIPC 588 Starting the Target Server for MIPC Communication ... 589
Contents
26
Booting VxWorks for AMP ... 591
26.1 Introduction ... 591 26.2 Using the wrload Utility to Boot VxWorks on Secondary Nodes ... 592 26.2.1 Processors that Support an Ethernet Connection to a Secondary Node ... 592 26.2.2 Processors that Do Not Support an Ethernet Connection to a Secondary Node
593
26.3 Invoking wrload from an Application ... 594 26.4 Rebooting VxWorks on a Node ... 594
27
The VxWorks tip Utility ... 595
27.1 Introduction ... 595 27.2 Configuring tip in a VxWorks Image Project ... 596 27.3 The tip Command ... 596 27.3.1 Shortcuts for Entering tip Commands ... 598 27.3.2 tip Subcommands ... 600 27.4 Examples ... 600
28
MIPC Serial Devices (MSD) ... 603
28.1 Introduction ... 603 28.2 MSD Build Component and Configuration Parameters ... 604 28.2.1 Configuring MSD for the VxWorks tip Utility ... 605 28.2.2 Setting the MSD_NUM_DEVS Parameter for tip ... 606 28.2.3 Setting the MSD Configuration String ... 607 Manual MSD Assignment ... 607 Automatic MSD Assignment ... 608 28.3 File-System Operations ... 608 28.3.1 MSD ioctl( ) Options ... 609 MSD_GET_ENDPOINT ioctl( ) Option ... 610 MSD_SET_ENDPOINT ioctl( ) Option ... 610
29
MND: Simulating an Ethernet Connection Between Nodes ... 613
29.4 Configuring Interfaces and Segments Through the MND Configuration String 616 29.5 MND Configuration Parameters ... 617 29.6 Verifying That Your MIPC and MND Configurations Match ... 620 29.7 Configuring MND Interfaces for Sending and Receiving Packets ... 620 29.8 Configuring MND Interfaces for IPv4 and IPv6 ... 620 29.9 Configuring MND Interfaces for TIPC ... 621
30
MIPC File System (MFS) ... 623
30.1 Introduction ... 623 30.2 Components and Parameters for Configuring MFS ... 624 30.2.1 The INCLUDE_MFS Component and Its Parameters ... 624 30.2.2 The INCLUDE_MFS_SERVER Component and its Parameters ... 625 30.2.3 The INCLUDE_MFS_SERVER_FD_CACHE Component and its Parameters 625 30.2.4 The INCLUDE_MFS_CLIENT Component and Its Parameter ... 626 30.3 MFS Server API ... 626 30.4 MFS Client API ... 627
31
Shared-Memory Objects: VxMP ... 629
31.1 Introduction ... 629 31.2 Using Shared-Memory Objects ... 630 31.2.1 Multiprocessing and Byte Ordering ... 632 31.2.2 Restrictions on Shared Memory Object Use ... 632 31.2.3 Publishing Objects With the Name Database ... 632 31.2.4 Shared Semaphores ... 634 31.2.5 Shared Message Queues ... 637 31.2.6 Shared-Memory Allocator ... 641 Shared-Memory System Partition ... 643 User-Created Partitions ... 643 Using the Shared-Memory System Partition ... 644 Using User-Created Partitions ... 646 Side Effects of Shared-Memory Partition Options ... 648 31.3 System Requirements ... 649 31.4 Performance Considerations ... 650 31.5 Configuring VxWorks for Shared Memory Objects ... 651
Contents
31.5.1 Maximum Number of CPUs ... 651 31.5.2 Cache Coherency ... 651 31.5.3 Mailbox Interrupts and Bus Interrupts ... 652 31.5.4 Shared-Memory Anchor ... 652 31.5.5 Shared-Memory Region ... 653 31.5.6 Numbers of Shared Memory Objects ... 653 31.5.7 Dual-Port or External Memory ... 654 31.5.8 Configuration Example ... 656 31.6 Displaying Information About Shared Memory Objects ... 657 31.7 Troubleshooting ... 657 31.7.1 Configuration Problems ... 658 31.7.2 Troubleshooting Techniques ... 658
32
Message Channels ... 661
32.1 Introduction ... 661 32.2 Message Channel Facilities ... 662 32.3 Multi-Node Communication with TIPC ... 663 32.4 Single-Node Communication with COMP and DSI ... 664 Express Messaging ... 665 Show Routines ... 665 32.4.1 COMP Socket Support with DSI ... 665 32.5 Socket Name Service ... 667 32.5.1 Multi-Node Socket Name Service ... 668 32.5.2 snsShow( ) Example ... 669 32.6 Socket Application Libraries ... 670 32.6.1 SAL Server Library ... 670 32.6.2 SAL Client Library ... 672 32.7 Configuring VxWorks for Message Channels ... 673 COMP, DSI, and SAL Components ... 673 SNS Component Options ... 673 Show Routines ... 675 32.8 Comparison of Message Channels and Message Queues ... 675
PART IV: APPENDICES
A
Porting C Code from 32-Bit to 64-Bit ... 679
A.1 Introduction ... 679 A.2 About the VxWorks 32-Bit and 64-Bit Data Models ... 679 A.3 Using the Compiler to Identify Porting Issues ... 681 A.4 Making C Code 32-bit/64-Bit Portable ... 682 A.4.1 Check int and long Declarations ... 683 A.4.2 Check All Assignments ... 683 A.4.3 Check for Data Type Promotion ... 683 A.4.4 Check Use of Pointers ... 683 A.4.5 Check use of sizeof( ) ... 684 A.4.6 Check Use of Type Casting ... 684 A.4.7 Check Format String Conversions ... 684 A.4.8 Check Use of Constants ... 684 A.4.9 Check Structures and Unions ... 685 A.4.10 Use Function Prototypes ... 686 A.4.11 Use Portable Data Types ... 686 A.4.12 As a Last Resort: Use Conditional Compilation Macro ... 686
B
VT-100 Color Management for tip ... 687
B.1 Introduction ... 687 B.2 Changing Text and Color Display for tip ... 687
C
Atomic Operators for AMP ... 689
C.1 Introduction ... 689 C.2 AMP Atomic Operator APIs ... 689 C.3 AMP Memory Barrier Macros ... 690
D
Spinlocks for AMP ... 693
D.1 Introduction ... 693 D.2 AMP Spinlock APIs ... 693
E
WDB Target Agent ... 695
Contents
E.2 About WDB Target Agent ... 695 E.3 Configuring VxWorks with the WDB Target Agent ... 697 E.3.1 Basic WDB Configuration ... 697 E.3.2 Host-Target WDB Communication Options ... 697 WDB Enhanced Network Driver Connection Configuration ... 699 WDB Standard Network Connection Configuration ... 699 WDB TIPC Network Connection Configuration ... 700 WDB Serial Connection Configuration ... 700 WDB Wind River ICE Connection Configuration ... 701 WDB Pipe Connection Configuration ... 701 E.3.3 Debugging Mode Options ... 701 System Mode Debugging Configuration ... 702 Task Mode Debugging Configuration ... 702 E.3.4 Process Management Options ... 703 E.3.5 Initialization Options ... 703 E.3.6 Additional Options ... 703 E.3.7 Statically Enablement ... 705 E.4 Enabling the WDB Target Agent ... 706 E.5 WDB Target Agent and VxWorks SMP ... 706 E.6 Using the WDB Target Agent with a TIPC Network ... 707 E.6.1 Target System Configuration ... 707 E.6.2 Establishing a Host-Target Connection ... 708 E.7 Scaling the WDB Target Agent ... 708 E.8 WDB Target Agent and Exceptions ... 709 E.9 Starting the WDB Target Agent Before the VxWorks Kernel ... 709 VxWorks Configuration ... 709 Run-time Operation ... 710 E.10 Creating a Custom WDB Communication Component ... 711
P A R T I
Core Technologies
1
Overview ...
3
2
VxWorks Configuration ...
7
3
Boot Loader ... 31
4
Kernel Applications ... 55
5
C++ Development ... 71
6
Multitasking ... 81
7
Intertask and Interprocess Communication ... 113
8
Signals, ISRs, and Watchdog Timers ... 147
9
POSIX Facilities ... 169
10
Memory Management ... 215
11
I/O System ... 259
12
Devices ... 287
13
Local File Systems ... 327
14
Flash File System Support: TrueFFS ... 385
15
Network File System: NFS ... 403
16
Kernel Core Dumps ... 417
17
Core Dump Raw Device Interface ... 435
1
Overview
1.1 Introduction 3 1.2 Kernel Architecture 3
1.3 Related Documentation Resources 4 1.4 VxWorks Configuration and Build 5
1.1 Introduction
This guide describes the VxWorks operating system, and how to use VxWorks facilities in the development of real-time systems and applications.
1.2 Kernel Architecture
Prior to VxWorks 6.0, the operating system provided a single memory space with no segregation of the operating system from user applications. All tasks ran in supervisor mode.1 Although this model afforded performance and flexibility when developing applications, only skilled programming could ensure that kernel facilities and applications coexisted in the same memory space without interfering with one another.
With the release of VxWorks 6.0, the operating system provides support for
NOTE: This book provides information about facilities available in the VxWorks kernel. For information about facilities available to real-time processes, see the
kernel and applications. This architecture is often referred to as the process model. VxWorks has adopted this model with a design specifically aimed to meet the requirements of determinism and speed that are required for hard real-time systems. (For information about VxWorks processes and developing applications to run in processes, see VxWorks Application Programmer’s Guide.) VxWorks 6.x provides full MMU-based protection of both kernel and user space.
At the same time, VxWorks 6.x maintains a high level of backward compatibility with VxWorks 5.5. Applications developed for earlier versions of VxWorks, and designed to run in kernel space, can be migrated to VxWorks 6.x kernel space with minimal effort (in most cases, merely re-compilation). For more information on this topic, see the VxWorks Application Programmer’s Guide.
Naturally, new applications can be designed for kernel space as well, when other considerations outweigh the advantages of protection that executing applications as processes affords. These considerations might include:
■ Size. The overall size of a system is smaller without components that provided
for processes and MMU support.
■ Speed. Depending on the number of system calls an application might make,
or how much I/O it is doing when running as a process in user space, it might be faster running in the kernel.
■ Kernel-only features. Features such as watchdog timers, ISRs, and VxMP are
available only in the kernel. In some cases, however, there are alternatives for process-based applications (POSIX timers, for example).
■ Hardware access. If the application requires direct access to hardware, it can
only do so from within the kernel.
VxWorks is flexible in terms of both the modularity of its features and extensibility. It can be configured as a minimal kernel, or a full-featured operating system with user mode applications, file systems, networking, error detection and reporting, and so on, or anything in between.
The operating system can also be extended by adding custom components or application modules to the kernel itself (for example, for new file systems, networking protocols, or drivers). The system call interface can also be extended by adding custom APIs, which makes them available to process-based
applications.
1.3 Related Documentation Resources
The companion volume to this book, the VxWorks Application Programmer’s Guide, provides material specific process-based (RTP) applications and process
management.
Detailed information about VxWorks libraries and routines is provided in the VxWorks API references. Information specific to target architectures is provided in the VxWorks BSP references and in the VxWorks Architecture Supplement.
For information about BSP and driver development, see the VxWorks BSP
1 Overview 1.4 VxWorks Configuration and Build
The VxWorks networking facilities are documented in the Wind River Network
Stack Programmer’s Guide and the VxWorks PPP Programmer’s Guide.
For information about migrating applications, BSPs, drivers, and projects from previous versions of VxWorks and the host development environment, see the
VxWorks Migration Guide and the Wind River Workbench Migration Guide.
The Wind River IDE and command-line tools are documented in the Wind River
Workbench by Example guide, your Platform user’s guide, the Wind River compiler
and GNU compiler guides, and the Wind River tools API and command-line references.
1.4 VxWorks Configuration and Build
This document describes VxWorks features; it does not go into detail about the mechanisms by which VxWorks-based systems and applications are configured and built. The tools and procedures used for configuration and build are described in the Wind River Workbench by Example guide and your Platform user’s guide.
NOTE: In this guide, as well as in the VxWorks API references, VxWorks
components and their configuration parameters are identified by the names used in component description files. The names take the form, for example, of
INCLUDE_FOO and NUM_FOO_FILES (for components and parameters, respectively).
You can use these names directly to configure VxWorks using the command-line configuration facilities.
Wind River Workbench displays descriptions of components and parameters, as well as their names, in the Components tab of the Kernel Configuration Editor. You can use the Find dialog to locate a component or parameter using its name or description. To access the Find dialog from the Components tab, type CTRL+F, or right-click and select Find.
! CAUTION: Code built for variants of VxWorks or for different releases of VxWorks is not binary compatible between variants or releases. Code must be built
specifically for uniprocessor (UP) VxWorks, VxWorks SMP, 32-bit VxWorks, 64-bit VxWorks, or for a VxWorks system based on variant libraries produced with a VxWorks source build (VSB) project—or for any supported combination of these variants. The only exception to this rule is that RTP application executables can be run on both UP VxWorks and VxWorks SMP (when all else is the same).
2
VxWorks Configuration
2.1 Introduction 7
2.2 About VxWorks Configuration 7 2.3 VxWorks Image Projects: VIPs 9
2.4 VxWorks Source Build Projects: VSBs 14 2.5 VxWorks Without Networking 21
2.6 Small-Footprint VxWorks Configuration 21 2.7 Power Management Facilities 27
2.8 VxWorks Image Types 28
2.1 Introduction
VxWorks is a highly scalable operating system that can be easily configured for diverse purposes with facilities packaged as individual components. Custom variants of VxWorks libraries can also be created, and used as an alternate basis for configuration. This chapter discusses basic VxWorks configuration, as well as the small-footprint configuration of VxWorks, the power management facility, and the types of VxWorks system images that can be produced.
2.2 About VxWorks Configuration
VxWorks is a flexible, scalable operating system with numerous facilities that can included, excluded, variously configured, and extended with customized
The primary means for configuring VxWorks are VxWorks image projects (VIPs) and
VxWorks source build projects (VSBs). Both the Wind River Workbench
development suite and the vxprj command-line configuration tool can be used to work with these project types. For information about Wind River Workbench and
vxprj, see the Wind River Workbench by Example guide and your Platform user’s guide.
2.2.1 Default Configuration and Images
VxWorks distributions include default system images for each supported BSP. Each system image is a binary module that can be booted and run on a target system. A system image consists of a set of components linked together into a single non-relocatable object module with no unresolved external references. The default system images are designed for the development environment. They contain the basic set of components that are necessary to interact with the system using host development tools. In most cases, you will find the supplied system image adequate for initial development (provided the default drivers are appropriate). Using a default VxWorks image, you can interactively download and run kernel applications.
For information about setting up your development environment, see the
Wind River Workbench by Example guide. For information about VxWorks image
types, see 2.8 VxWorks Image Types, p.28.
2.2.2 Configuration With VxWorks Image Projects
VxWorks image projects are used for configuring systems with a variety of components. VxWorks components provide units of operating system functionality based on pre-compiled libraries (archives) that are linked into a system by way of symbolic references. For more information about VIPs, see 2.3 VxWorks Image Projects: VIPs, p.9.
2.2.3 Configuration With VxWorks Source Build Projects
For systems with stringent performance requirements or resource constraints, VxWorks source build (VSB) projects can be used to create specialized (and frequently smaller) variants of VxWorks libraries and to employ various optimizations. VSB options and the associated conditionalized code provide the means for configuration at the source-code level. Once the VxWorks libraries are rebuilt from source, a VIP project can be used to configure the system itself. For more information about VSBs, see 2.4 VxWorks Source Build Projects: VSBs, p.14.
2.2.4 Configuration and Customization
If the VxWorks components provided by Wind River do not provide all the facilities required for your system, you can create custom facilities, such as new file systems and networking protocols, and package them as components (see 19. Custom Components and CDFs), add new system calls for process-based applications (see 20. Custom System Calls), or create your own scheduler (see 21. Custom Scheduler).
2 VxWorks Configuration 2.3 VxWorks Image Projects: VIPs
2.2.5 Configuration Tools: Workbench and vxprj
The tools provided for working with both VxWorks image projects (VIPs) and VxWorks source build projects (VSBs) are the Wind River Workbench
development suite and the vxprj command-line configuration facility. Workbench and vxprj can be used to configure and build VxWorks systems, and otherwise manage VIP, VSB, and other sorts of projects.
For information about using Workbench and vxprj, see the Wind River Workbench
by Example guide and your Platform user’s guide, respectively.
2.3 VxWorks Image Projects: VIPs
VxWorks image projects are used to configure VxWorks systems with a variety of components. VxWorks components provide units of operating system
functionality based on pre-compiled libraries (archives) that are linked into a system by way of symbolic references. VIPs can be based on a default configuration of VxWorks or configuration profiles. Configuration profiles provide sets of components designed for specific purposes, such as the development environment, DO-178B certification, and so on. In addition, component bundles can be used to configure a system with related sets of components, such as those that provide POSIX support.
During the development cycle you may want to reconfigure and rebuild VxWorks with components specifically selected to support your applications and
development requirements. For example, you may want to include the kernel shell and error detection and reporting facilities, and to exclude other components that are provided in the default system images.
For production systems, you will want to reconfigure VxWorks with only those components needed for deployed operation, and to build it as the appropriate type of system image (see 2.8 VxWorks Image Types, p.28). You will likely want to remove components required for host development support, such as the WDB target agent and debugging components (INCLUDE_WDB and
INCLUDE_DEBUG), as well as to remove any other operating system
components not required to support your application. Other considerations may include reducing the memory requirements of the system, speeding up boot time, and security issues.
Wind River Workbench and the vxprj command-line tool can be used to configure VxWorks based on component selection and de-selection. The Workbench configuration facility displays graphical information about the components included in, and otherwise available to, as system. The vxprj tool can also be used to list various kinds of information about components. In addition, the VxWorks
Component Reference provides detailed information about all components and their
2.3.1 VxWorks Components
A VxWorks component is the basic unit of functionality with which VxWorks can be configured. Components are designed for real-time systems, with an emphasis on determinism and performance. Each component provides one or more pre-compiled static library (archive), and often one or more configuration parameters. Components are linked into a system by way of symbolic references. While some components are autonomous, others may have dependencies on other components, which must be included in the configuration of the operating system for run-time operation. The kernel shell is an example of a component with many dependencies. The symbol table is an example of a component upon which other components depend (the kernel shell and module loader; for more information, see the VxWorks Kernel Shell User’s Guide). Component dependencies are determined automatically by the VxWorks kernel configuration facilities (Wind River Workbench and the vxprj command-line tool).
Component Names
VxWorks components are packaged using component description files (CDFs), which identify components with macro names that begin with INCLUDE_, as well as with user-friendly descriptions. (For information about configuration files, see 19Custom Components and CDFs, p.455.)
The names, descriptions, and configurable features of VxWorks components can be displayed with the GUI configuration facilities in Workbench. Workbench provides facilities for configuring VxWorks with selected components, setting component parameters, as well as automated mechanisms for determining dependencies between components during the configuration and build process. The command-line operating system configuration tool—vxprj—uses the naming convention that originated with configuration macros to identify individual operating system components. The convention identifies components with names that begin with INCLUDE. For example, INCLUDE_MSG_Q is the message queue component. In addition to configuration facilities, the vxprj tool provides
associated features for listing the components included in a project, configuration parameters, and so on.
! CAUTION: When VxWorks is configured with the WDB target agent, it is enabled on UDP port 17185. This service provides full access to VxWorks memory, and allows for writing to memory as well as for calling routines. Wind River recommends removing WDB from VxWorks for production systems. For information about WDB, see E. WDB Target Agent.
NOTE: In this book, components are identified by their macro name. The GUI configuration facilities provide a search facility for finding individual components in the GUI component tree based on the macro name.
2 VxWorks Configuration 2.3 VxWorks Image Projects: VIPs
Basic VxWorks Components
Some of the commonly used VxWorks components are described in Table 2-1. Names that end in XXX represent families of components, in which the XXX is replaced by a suffix for individual component names. For example,
INCLUDE_CPLUS_XXX refers to a family of components that includes
INCLUDE_CPLUS_MIN and others.
Note that Table 2-1 does not include all components provided in the default configuration of VxWorks. For detailed reference information about all components and their parameters, see the VxWorks Component Reference.
Table 2-1 Key VxWorks Components
Component Default Description
INCLUDE_ANSI_XXX * Various ANSI C library options
INCLUDE_BOOTLINE_INIT Parse boot device configuration
information
INCLUDE_BOOTP * BOOTP support
INCLUDE_CACHE_SUPPORT * Cache support
INCLUDE_CPLUS * Bundled C++ support
INCLUDE_CPLUS_XXX Various C++ support options
INCLUDE_DEBUG Kernel shell debugging facilities
INCLUDE_EDR_XXX Error detection and reporting facilities.
INCLUDE_DOSFS DOS-compatible file system
INCLUDE_FLOATING_POINT * Floating-point I/O
INCLUDE_FORMATTED_IO * Formatted I/O
INCLUDE_FTP_SERVER FTP server support
INCLUDE_IO_SYSTEM * I/O system and associated interfaces.
Directory and path manipulation APIs.
INCLUDE_LOADER Target-resident kernel object module
loader package
INCLUDE_LOGGING * Logging facility
INCLUDE_MEM_MGR_BASIC * Core partition memory manager
INCLUDE_MEM_MGR_FULL * Full-featured memory manager
INCLUDE_NETWORK * Network subsystem code
INCLUDE_NFS Network File System (NFS)
INCLUDE_NFS_SERVER NFS server
INCLUDE_PIPES * Pipe driver
INCLUDE_POSIX_XXX Various POSIX options
INCLUDE_PROTECT_TEXT Text segment write protection
INCLUDE_PROTECT_VEC_TABLE Vector table write protection
INCLUDE_PROXY_CLIENT * Proxy ARP client support
INCLUDE_PROXY_SERVER Proxy ARP server support
INCLUDE_RAWFS Raw file system
INCLUDE_RLOGIN Remote login with rlogin
INCLUDE_ROMFS ROMFS file system
INCLUDE_RTP Real-time process support.
INCLUDE_SCSI SCSI support (not provided for 64-bit
VxWorks with this release)
INCLUDE_SCSI2 SCSI-2 extensions (not provided for
64-bit VxWorks with this release)
INCLUDE_SECURITY Remote login security package
INCLUDE_SELECT Select facility
INCLUDE_SEM_BINARY * Binary semaphore support
INCLUDE_SEM_COUNTING * Counting semaphore support
INCLUDE_SEM_MUTEX * Mutual exclusion semaphore
support
INCLUDE_SHELL Kernel (target) shell
INCLUDE_XXX_SHOW Various system object show facilities
INCLUDE_SIGNALS * Software signal facilities
INCLUDE_SM_OBJ Shared memory object support
(requires VxMP)
INCLUDE_SNMPD SNMP agent
Table 2-1 Key VxWorks Components (cont’d)
2 VxWorks Configuration 2.3 VxWorks Image Projects: VIPs
2.3.2 Device Driver Selection
Device drivers are provided as VxWorks components that can be added to or removed from a system using Workbench and vxprj. Some drivers are VxBus-compliant, and others (legacy drivers) are not.
Note that the component names for VxBus drivers do not have the leading
INCLUDE_SPY Task activity monitor
INCLUDE_STDIO * Standard buffered I/O package
INCLUDE_SW_FP Software floating point emulation
package
INCLUDE_SYM_TBL Target-resident symbol table support
INCLUDE_TASK_HOOKS * Kernel call-out support
INCLUDE_TASK_VARS * Task variable support
INCLUDE_IPTELNETS Remote login with telnet
INCLUDE_TFTP_CLIENT * TFTP client support
INCLUDE_TFTP_SERVER TFTP server support
INCLUDE_TIMEX * Function execution timer
INCLUDE_TRIGGERING Function execution timer
INCLUDE_UNLOADER Target-resident kernel object module
unloader package
INCLUDE_VXEVENTS VxWorks events support.
INCLUDE_WATCHDOGS * Watchdog support
INCLUDE_WDB * WDB target agent
INCLUDE_WDB_TSFS * Target server file system
INCLUDE_WINDVIEW System Viewer command server (see
the Wind River System Viewer User’s
Guide)
Table 2-1 Key VxWorks Components (cont’d)
Component Default Description
NOTE: Only VxBus-compatible drivers can be used with the symmetric
multiprocessing (SMP) configuration of VxWorks. For general information about VxWorks SMP and about migration, see 23. VxWorks SMP and 23.17 Migrating Code to VxWorks SMP, p.558.