VxWorks Programmer's Guide
Contents
1 Introduction
1.1 Overview
1.2 Related Documentation Resources
1.3 VxWorks Configuration and Build
1.4 Wind River Coding Conventions
1.5 Documentation Conventions
2 Basic OS
2.1 Introduction
2.2 VxWorks Tasks
2.2.1 Multitasking
2.2.2 Task State Transition
2.2.3 Wind Task Scheduling
Preemptive Priority Scheduling
Round-Robin Scheduling
Preemption Locks
A Comparison of taskLock() and intLock()
Driver Support Task Priority
2.2.4 Task Control
Task Creation and Activation
Task Stack
Task Names and IDs
Task Options
Task Information
Task Deletion and Deletion Safety
Task Control
2.2.5 Tasking Extensions
2.2.6 Task Error Status: errno
Layered Definitions of errno
A Separate errno Value for Each Task
Error Return Convention
Assignment of Error Status Values
2.2.7 Task Exception Handling
2.2.8 Shared Code and Reentrancy
Dynamic Stack Variables
Guarded Global and Static Variables
Task Variables
Multiple Tasks with the Same Main Routine
2.2.9 VxWorks System Tasks
2.3 Intertask Communications
2.3.1 Shared Data Structures
2.3.2 Mutual Exclusion
Interrupt Locks and Latency
Preemptive Locks and Latency
2.3.3 Semaphores
Semaphore Control
Binary Semaphores
Mutual-Exclusion Semaphores
Counting Semaphores
Special Semaphore Options
Semaphores and VxWorks Events
2.3.4 Message Queues
Wind Message Queues
Displaying Message Queue Attributes
Servers and Clients with Message Queues
Message Queues and VxWorks Events
2.3.5 Pipes
2.3.6 Network Intertask Communication
Sockets
Remote Procedure Calls (RPC)
2.3.7 Signals
Basic Signal Routines
Signal Configuration
2.4 VxWorks Events
2.4.1 pSOS Events
Sending and Receiving Events
Waiting for Events
Registering for Events
Freeing Resources
pSOS Events API
2.4.2 VxWorks Events
Free Resource Definition
VxWorks Enhancements to pSOS Events
Task Events Register
VxWorks Events API
Show Routines
2.4.3 API Comparison
2.5 Watchdog Timers
2.6 Interrupt Service Code: ISRs
2.6.1 Connecting Routines to Interrupts
2.6.2 Interrupt Stack
2.6.3 Writing and Debugging ISRs
2.6.4 Special Limitations of ISRs
2.6.5 Exceptions at Interrupt Level
2.6.6 Reserving High Interrupt Levels
2.6.7 Additional Restrictions for ISRs at High Interrupt Levels
2.6.8 Interrupt-to-Task Communication
3 POSIX Standard Interfaces
3.1 Introduction
3.2 POSIX Clocks and Timers
3.3 POSIX Memory-Locking Interface
3.4 POSIX Threads
3.4.1 POSIX Thread Attributes
Stack Size
Stack Address
Detach State
Contention Scope
Inherit Scheduling
Scheduling Policy
Scheduling Parameters
Specifying Attributes when Creating pThreads
3.4.2 Thread Private Data
3.4.3 Thread Cancellation
3.5 POSIX Scheduling Interface
3.5.1 Comparison of POSIX and Wind Scheduling
3.5.2 Getting and Setting POSIX Task Priorities
3.5.3 Getting and Displaying the Current Scheduling Policy
3.5.4 Getting Scheduling Parameters: Priority Limits and Time Slice
3.6 POSIX Semaphores
3.6.1 Comparison of POSIX and Wind Semaphores
3.6.2 Using Unnamed Semaphores
3.6.3 Using Named Semaphores
3.7 POSIX Mutexes and Condition Variables
3.8 POSIX Message Queues
3.8.1 Comparison of POSIX and Wind Message Queues
3.8.2 POSIX Message Queue Attributes
3.8.3 Displaying Message Queue Attributes
3.8.4 Communicating Through a Message Queue
3.8.5 Notifying a Task that a Message is Waiting
3.9 POSIX Queued Signals
4 I/O System
4.1 Introduction
4.2 Files, Devices, and Drivers
4.2.1 Filenames and the Default Device
4.3 Basic I/O
4.3.1 File Descriptors
4.3.2 Standard Input, Standard Output, and Standard Error
Global Redirection
Task-Specific Redirection
4.3.3 Open and Close
4.3.4 Create and Delete
4.3.5 Read and Write
4.3.6 File Truncation
4.3.7 I/O Control
4.3.8 Pending on Multiple File Descriptors: The Select Facility
4.4 Buffered I/O: stdio
4.4.1 Using stdio
4.4.2 Standard Input, Standard Output, and Standard Error
4.5 Other Formatted I/O
4.5.1 Special Cases: printf(), sprintf(), and sscanf()
4.5.2 Additional Routines: printErr() and fdprintf()
4.5.3 Message Logging
4.6 Asynchronous Input/Output
4.6.1 The POSIX AIO Routines
4.6.2 AIO Control Block
4.6.3 Using AIO
AIO with Periodic Checks for Completion
Alternatives for Testing AIO Completion
4.7 Devices in VxWorks
4.7.1 Serial I/O Devices (Terminal and Pseudo-Terminal Devices)
tty Options
Raw Mode and Line Mode
Tty Special Characters
I/O Control Functions
4.7.2 Pipe Devices
Creating Pipes
Writing to Pipes from ISRs
I/O Control Functions
4.7.3 Pseudo Memory Devices
Installing the Memory Driver
I/O Control Functions
4.7.4 Network File System (NFS) Devices
Mounting a Remote NFS File System from VxWorks
I/O Control Functions for NFS Clients
4.7.5 Non-NFS Network Devices
Creating Network Devices
I/O Control Functions
4.7.6 CBIO Interface
CBIO Disk Cache
CBIO Disk Partition Handler
CBIO RAM Disk
I/O Control Functions for CBIO Devices
4.7.7 Block Devices
Block Device File Systems
Block Device RAM Disk Drivers
SCSI Drivers
4.7.8 Sockets
4.8 Differences Between VxWorks and Host System I/O
4.9 Internal Structure
4.9.1 Drivers
The Driver Table and Installing Drivers
Example of Installing a Driver
4.9.2 Devices
The Device List and Adding Devices
Example of Adding Devices
4.9.3 File Descriptors
The Fd Table
Example of Opening a File
Example of Reading Data from the File
Example of Closing a File
Implementing select()
Cache Coherency
4.9.4 Block Devices
General Implementation
Low-Level Driver Initialization Routine
Device Creation Routine
Read Routine (Direct-Access Devices)
Read Routine (Sequential Devices)
Write Routine (Direct-Access Devices)
Write Routine (Sequential Devices)
I/O Control Routine
Device-Reset Routine
Status-Check Routine
Write-Protected Media
Change in Ready Status
Write-File-Marks Routine (Sequential Devices)
Rewind Routine (Sequential Devices)
Reserve Routine (Sequential Devices)
Release Routine (Sequential Devices)
Read-Block-Limits Routine (Sequential Devices)
Load/Unload Routine (Sequential Devices)
Space Routine (Sequential Devices)
Erase Routine (Sequential Devices)
4.9.5 Driver Support Libraries
4.10 PCMCIA
4.11 Peripheral Component Interconnect: PCI
5 Local File Systems
5.1 Introduction
5.2 MS-DOS-Compatible File System: dosFs
5.2.1 Creating a dosFs File System
5.2.2 Configuring Your System
5.2.3 Initializing the dosFs File System
5.2.4 Creating a Block Device
5.2.5 Creating a Disk Cache
5.2.6 Creating and Using Partitions
5.2.7 Creating a dosFs Device
5.2.8 Formatting the Volume
File Allocation Table (FAT) Formats
Directory Formats
5.2.9 Mounting Volumes
5.2.10 Demonstrating with Examples
5.2.11 Working with Volumes and Disks
Announcing Disk Changes with Ready-Change
Accessing Volume Configuration Information
Synchronizing Volumes
5.2.12 Working with Directories
Creating Subdirectories
Removing Subdirectories
Reading Directory Entries
5.2.13 Working with Files
File I/O
File Attributes
5.2.14 Disk Space Allocation Options
Choosing an Allocation Method
Using Cluster Group Allocation
Using Absolutely Contiguous Allocation
5.2.15 Crash Recovery and Volume Consistency
5.2.16 I/O Control Functions Supported by dosFsLib
5.3 Booting from a Local dosFs File System Using SCSI
5.4 Raw File System: rawFs
5.4.1 Disk Organization
5.4.2 Initializing the rawFs File System
5.4.3 Initializing a Device for Use With rawFs
5.4.4 Mounting Volumes
5.4.5 File I/O
5.4.6 Changing Disks
Un-mounting Volumes
Announcing Disk Changes with Ready-Change
Synchronizing Volumes
5.4.7 I/O Control Functions Supported by rawFsLib
5.5 Tape File System: tapeFs
5.5.1 Tape Organization
5.5.2 Initializing the tapeFs File System
Initializing a Device for Use With tapeFs
Systems with Fixed Block and Variable Block Devices
5.5.3 Mounting Volumes
5.5.4 File I/O
5.5.5 Changing Tapes
5.5.6 I/O Control Functions Supported by tapeFsLib
5.6 CD-ROM File System: cdromFs
5.7 The Target Server File System: TSFS
Socket Support
Error Handling
TSFS Configuration
Security Considerations
6 Target Tools
6.1 Introduction
6.2 Target-Resident Shell
6.2.1 Summarizing the Target and HostShell Differences
6.2.2 Configuring VxWorks With the Target Shell
6.2.3 Using Target Shell Help and Control Characters
6.2.4 Loading and Unloading Object Modules from the Target Shell
6.2.5 Debugging with the Target Shell
6.2.6 Aborting Routines Executing from the Target Shell
6.2.7 Using a Remote Login to the Target Shell
Remote Login From Host: telnet and rlogin
Remote Login Security
6.2.8 Distributing the Demangler
6.3 Target-Resident Loader
6.3.1 Configuring VxWorks with the Loader
6.3.2 Target-Loader API
6.3.3 Summary List of Loader Options
6.3.4 Loading C++ Modules
6.3.5 Specifying Memory Locations for Loading Objects
6.3.6 Constraints Affecting Loader Behavior
Relocatable Object Files
Object Module Formats
Linking and Reference Resolution
The Sequential Nature of Loading
Resolving Common Symbols
6.4 Target-Resident Symbol Tables
Symbol Entries
Symbol Updates
Searching the Symbol Library
6.4.1 Configuring VxWorks with Symbol Tables
Basic Configuration
System Symbol Table Configuration
6.4.2 Creating a Built-In System Symbol Table
Generating the Symbol Information
Compiling and Linking the Symbol File
Advantages of Using a Built-in System Symbol Table
6.4.3 Creating a Loadable System Symbol Table
Creating the .sym File
Loading the .sym File
Advantages of Using the Loadable System Symbol Table
6.4.4 Using the VxWorks System Symbol Table
6.4.5 Synchronizing Host and Target-Resident Symbol Tables
6.4.6 Creating User Symbol Tables
6.5 Show Routines
6.6 Common Problems
Target Shell Debugging Never Hits a Breakpoint
Insufficient Memory
“Relocation Does Not Fit” Error Message
Missing Symbols
Loader is Using Too Much Memory
Symbol Table Unavailable
7 C++ Development
7.1 Introduction
7.2 Working with C++ under VxWorks
7.2.1 Making C++ Accessible to C Code
7.2.2 Adding Support Components
Basic Support Components
C++ Library Components
7.2.3 The C++ Demangler
7.3 Initializing and Finalizing Static Objects
7.3.1 Munching C++ Application Modules
Using GNU
Using Diab
Using a Generic Rule
7.3.2 Calling Static Constructors and Destructors Interactively
7.4 Programming with GNU C++
7.4.1 Template Instantiation
-fimplicit-templates
-fmerge-templates
-fno-implicit-templates
-frepo
7.4.2 Exception Handling
Using the Pre-Exception Model
Exception Handling Overhead
Unhandled Exceptions
7.4.3 Run-Time Type Information
7.4.4 Namespaces
7.5 Programming with Diab C++
7.5.1 Template Instantiation
-Ximplicit-templates
-Ximplicit-templates-off
-Xcomdat
-Xcomdat-off
7.5.2 Exception Handling
7.5.3 Run-Time Type Information
7.6 Using C++ Libraries
String and Complex Number Classes
iostreams Library
Standard Template Library (STL)
7.7 Running the Example Demo
8 Flash Memory Block Device Driver
8.1 Introduction
8.1.1 Choosing TrueFFS as a Medium
8.1.2 TrueFFS Layers
8.2 Building Systems with TrueFFS
8.3 Selecting an MTD Component
8.4 Identifying the Socket Driver
8.5 Configuring and Building the Project
8.5.1 Including File System Components
8.5.2 Including the Core Component
8.5.3 Including Utility Components
8.5.4 Including the MTD Component
8.5.5 Including the Translation Layer
8.5.6 Adding the Socket Driver
8.5.7 Building the System Project
8.6 Formatting the Device
8.6.1 Specifying the Drive Number
8.6.2 Formatting the Device
8.7 Creating a Region for Writing a Boot Image
8.7.1 Write Protecting Flash
8.7.2 Creating the Boot Image Region
Formatting at an Offset
Using a BSP Helper Routine
8.7.3 Writing the Boot Image to Flash
8.8 Mounting the Drive
8.9 Running the Shell Commands with Examples
8.10 Writing Socket Drivers
8.10.1 Porting the Socket Driver Stub File
Call the Socket Register Routines
Implement the Socket Structure Member Functions
8.10.2 Understanding Socket Driver Functionality
Socket Registration
Socket Member Functions
Socket Windowing and Address Mapping
8.11 Using the MTD-Supported Flash Devices
8.11.1 Supporting the Common Flash Interface (CFI)
Common Functionality
CFI/SCS Flash Support
AMD/Fujitsu CFI Flash Support
8.11.2 Supporting Other MTDs
Intel 28F016 Flash Support
Intel 28F008 Flash Support
AMD/Fujitsu Flash Support
8.11.3 Obtaining Disk On Chip Support
8.12 Writing MTD Components
8.12.1 Writing the MTD Identification Routine
Initializing the FLFLash Structure Members
Call Sequence
8.12.2 Writing the MTD Map Function
8.12.3 Writing the MTD Read, Write, and Erase Functions
Read Routine
Write Routine
Erase Routine
8.12.4 Defining Your MTD as a Component
Adding Your MTD to the Project Facility
Defining the MTD in the Socket Driver File
8.12.5 Registering the Identification Routine
8.13 Flash Memory Functionality
8.13.1 Block Allocation and Data Clusters
Block Allocation Algorithm
Benefits of Clustering
8.13.2 Read and Write Operations
Reading from Blocks
Writing to Previously Unwritten Blocks
Writing to Previously Written Blocks
8.13.3 Erase Cycles and Garbage Collection
Erasing Units
Reclaiming Erased Blocks
Over-Programming
8.13.4 Optimization Methods
Wear Leveling
Garbage Collection
8.13.5 Fault Recovery in TrueFFS
Recovering During a Write Operation
Recovering Mapping Information
Recovering During Garbage Collection
Recovering During Formatting
9 VxDCOM Applications
9.1 Introduction
9.2 An Overview of COM Technology
9.2.1 COM Components and Software Reusability
COM Interfaces
CoClasses
Interface Pointers
VxDCOM Tools
9.2.2 VxDCOM and Real-time Distributed Technology
9.3 Using the Wind Object Template Library
9.3.1 WOTL Template Class Categories
9.3.2 True CoClass Template Classes
CComObjectRoot – IUnknown Implementation Support Class
CComCoClass – CoClass Class Template
9.3.3 Lightweight Object Class Template
9.3.4 Single Instance Class Macro
9.4 Reading WOTL-Generated Code
9.4.1 WOTL CoClass Definitions
9.4.2 Macro Definitions Used in Generated Files
Mapping IDL Definitions to Interface Header Prototypes
Mapping Interface Prototypes to CoClass Method Definitions
Defining CoClass Methods in Implementation Files
9.4.3 Interface Maps
9.5 Configuring DCOM Properties’ Parameters
9.6 Using the Wind IDL Compiler
9.6.1 Command-Line Syntax
9.6.2 Generated Code
9.6.3 Data Types
Automation Data Types
Non-Automation Data Types
SAFEARRAY with VARIANTS
HRESULT Return Values
9.7 Reading IDL Files
9.7.1 IDL File Structure
The import Directive
The Interface Definition
Library and CoClass Definitions
9.7.2 Definition Attributes
IDL File Attributes
Attribute Restrictions for VxDCOM
Directional Attributes for Interface Method Parameters
9.8 Adding Real-Time Extensions
9.8.1 Using Priority Schemes on VxWorks
Second Parameter Priority Scheme
Third Parameter Priority Level
9.8.2 Configuring Client Priority Propagation on Windows
9.8.3 Using Threadpools
9.9 Using OPC Interfaces
9.10 Writing VxDCOM Servers and Client Applications
9.10.1 Programming Issues
9.10.2 Writing a Server Program
Server Interfaces
Client Interaction
9.10.3 Writing Client Code
Determining the Client Type
Creating and Initializing the Client
9.10.4 Querying the Server
9.10.5 Executing the Client Code
9.11 Comparing VxDCOM and ATL Implementations.
9.11.1 CComObjectRoot
9.11.2 CComClassFactory
9.11.3 CComCoClass
9.11.4 CComObject
9.11.5 CComPtr
9.11.6 CComBSTR
9.11.7 VxComBSTR
9.11.8 CComVariant
10 Distributed Message Queues
10.1 Introduction
10.2 Configuring VxWorks with VxFusion
10.3 Using VxFusion
10.3.1 VxFusion System Architecture
10.3.2 VxFusion Initialization
10.3.3 Configuring VxFusion
10.3.4 Working with the Distributed Name Database
10.3.5 Working with Distributed Message Queues
10.3.6 Working with Group Message Queues
10.3.7 Working with Adapters
10.4 System Limitations
10.5 Node Startup
10.6 Telegrams and Messages
10.6.1 Telegrams Versus Messages
10.6.2 Telegram Buffers
10.7 Designing Adapters
10.7.1 Designing the Network Header
10.7.2 Writing an Initialization Routine
Using the DIST_IF Structure
10.7.3 Writing a Startup Routine
10.7.4 Writing a Send Routine
10.7.5 Writing an Input Routine
10.7.6 Writing an I/O Control Routine
11 Shared-Memory Objects
11.1 Introduction
11.2 Using Shared-Memory Objects
11.2.1 Name Database
11.2.2 Shared Semaphores
11.2.3 Shared Message Queues
11.2.4 Shared-Memory Allocator
Shared-Memory System Partition
User-Created Partitions
Using the Shared-Memory System Partition
Using User-Created Partitions
Side Effects of Shared-Memory Partition Options
11.3 Internal Considerations
11.3.1 System Requirements
11.3.2 Spin-lock Mechanism
11.3.3 Interrupt Latency
11.3.4 Restrictions
11.3.5 Cache Coherency
11.4 Configuration
11.4.1 Shared-Memory Objects and Shared-Memory Network Driver
11.4.2 Shared-Memory Region
11.4.3 Initializing the Shared-Memory Objects Package
11.4.4 Configuration Example
11.4.5 Initialization Steps
11.5 Troubleshooting
11.5.1 Configuration Problems
11.5.2 Troubleshooting Techniques
12 Virtual Memory Interface
12.1 Introduction
12.2 Basic Virtual Memory Support
12.3 Virtual Memory Configuration
12.4 General Use
12.5 Using the MMU Programmatically
12.5.1 Virtual Memory Contexts
Global Virtual Memory
Initialization
Page States
12.5.2 Private Virtual Memory
12.5.3 Noncacheable Memory
12.5.4 Nonwritable Memory
12.5.5 Troubleshooting
12.5.6 Precautions
Index