VxWorks

Programmer's Guide

5.4

Edition 1

[Copyright][Online Manuals]

Contents

1 Overview
1.1 Introduction
1.2 Getting Started with the Tornado Development System
1.3 VxWorks: A Partner in the Real-time Development Cycle
1.4 VxWorks Facilities: An Overview
Multitasking and Intertask Communications
POSIX Interfaces
I/O System
Local File Systems
Virtual Memory (Including VxVMI Option)
Shared-Memory Objects (VxMP Option)
Target-Resident Tools
C++ Development (including Wind Foundation Classes Option)
Utility Libraries
Performance Evaluation
Target Agent
Board Support Packages (BSPs)
VxWorks Simulator (VxSim Option)
1.5 Customer Services
1.6 Documentation Conventions
2 Basic OS
2.1 Introduction
2.2 Wind Features and POSIX Features
2.3 Tasks
2.3.1 Multitasking
2.3.2 Task State Transition
2.3.3 Wind Task Scheduling
Preemptive Priority Scheduling
Round-Robin Scheduling
Preemption Locks
2.3.4 Tasking Control
Task Creation and Activation
Task Names and IDs
Task Options
Task Information
Task Deletion and Deletion Safety
Task Control
2.3.5 Tasking Extensions
2.3.6 POSIX Scheduling Interface
Differences Between POSIX and Wind Scheduling
Getting and Setting POSIX Task Priorities
Getting and Displaying the Current Scheduling Policy
Getting Scheduling Parameters: Priority Limits and Time Slice
2.3.7 Task Error Status: errno
Layered Definitions of errno
A Separate errno Value for Each Task
Error Return Convention
Assignment of Error Status Values
2.3.8 Task Exception Handling
2.3.9 Shared Code and Reentrancy
Dynamic Stack Variables
Guarded Global and Static Variables
Task Variables
Multiple Tasks with the Same Main Routine
2.3.10 VxWorks System Tasks
2.4 Intertask Communications
2.4.1 Shared Data Structures
2.4.2 Mutual Exclusion
Interrupt Locks and Latency
Preemptive Locks and Latency
2.4.3 Semaphores
Semaphore Control
Binary Semaphores
Mutual-Exclusion Semaphores
Counting Semaphores
Special Semaphore Options
POSIX Semaphores
2.4.4 Message Queues
Wind Message Queues
POSIX Message Queues
Comparison of POSIX and Wind Message Queues
Displaying Message Queue Attributes
Servers and Clients with Message Queues
2.4.5 Pipes
2.4.6 Network Intertask Communication
Sockets
Remote Procedure Calls (RPC)
2.4.7 Signals
Basic Signal Routines
POSIX Queued Signals
Signal Configuration
2.5 Interrupt Service Code
2.5.1 Connecting Application Code to Interrupts
2.5.2 Interrupt Stack
2.5.3 Special Limitations of ISRs
2.5.4 Exceptions at Interrupt Level
2.5.5 Reserving High Interrupt Levels
2.5.6 Additional Restrictions for ISRs at High Interrupt Levels
2.5.7 Interrupt-to-Task Communication
2.6 Watchdog Timers
2.7 POSIX Clocks and Timers
2.8 POSIX Memory-Locking Interface
3 I/O System
3.1 Introduction
3.2 Files, Devices, and Drivers
3.2.1 File Names and the Default Device
3.3 Basic I/O
3.3.1 File Descriptors
3.3.2 Standard Input, Standard Output, and Standard Error
Global Redirection
Task-Specific Redirection
3.3.3 Open and Close
3.3.4 Create and Remove
3.3.5 Read and Write
3.3.6 File Truncation
3.3.7 I/O Control
3.3.8 Pending on Multiple File Descriptors: The Select Facility
3.4 Buffered I/O: Stdio
3.4.1 Using Stdio
3.4.2 Standard Input, Standard Output, and Standard Error
3.5 Other Formatted I/O
3.5.1 Special Cases: printf( ), sprintf( ), and sscanf( )
3.5.2 Additional Routines: printErr( ) and fdprintf( )
3.5.3 Message Logging
3.6 Asynchronous Input/Output
3.6.1 The POSIX AIO Routines
3.6.2 AIO Control Block
3.6.3 Using AIO
AIO with Periodic Checks for Completion
Alternatives for Testing AIO Completion
3.7 Devices in VxWorks
3.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
3.7.2 Pipe Devices
Creating Pipes
Writing to Pipes from ISRs
I/O Control Functions
3.7.3 Pseudo Memory Devices
Installing the Memory Driver
I/O Control Functions
3.7.4 Network File System (NFS) Devices
Mounting a Remote NFS File System from VxWorks
I/O Control Functions for NFS Clients
3.7.5 Non-NFS Network Devices
Creating Network Devices
I/O Control Functions
3.7.6 Block Devices
File Systems
RAM Disk Drivers
SCSI Drivers
3.7.7 Sockets
3.8 Differences Between VxWorks and Host System I/O
3.9 Internal Structure
3.9.1 Drivers
The Driver Table and Installing Drivers
Example of Installing a Driver
3.9.2 Devices
The Device List and Adding Devices
Example of Adding Devices
3.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
3.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)
3.9.5 Driver Support Libraries
4 Local File Systems
4.1 Introduction
4.2 MS-DOS-Compatible File System: dosFs
4.2.1 Disk Organization
Clusters
Boot Sector
File Allocation Table
Root Directory
Subdirectories
Files
Volume Label
4.2.2 Initializing the dosFs File System
4.2.3 Initializing a Device for Use with dosFs
4.2.4 Volume Configuration
DOS_VOL_CONFIG Fields
Calculating Configuration Values
Standard Disk Configurations
4.2.5 Changes In Volume Configuration
4.2.6 Using an Already Initialized Disk
4.2.7 Accessing Volume Configuration Information
4.2.8 Mounting Volumes
4.2.9 File I/O
4.2.10 Opening the Whole Device (Raw Mode)
4.2.11 Creating Subdirectories
4.2.12 Removing Subdirectories
4.2.13 Directory Entries
4.2.14 Reading Directory Entries
4.2.15 File Attributes
4.2.16 File Date and Time
4.2.17 Changing Disks
Unmounting Volumes
Announcing Disk Changes with Ready-Change
Disks with No Change Notification
Synchronizing Volumes
Auto-Sync Mode
4.2.18 Long Name Support
4.2.19 Contiguous File Support
4.2.20 I/O Control Functions Supported by dosFsLib
4.2.21 Booting from a Local dosFs File System Using SCSI
4.3 RT-11-Compatible File System: rt11Fs
4.3.1 Disk Organization
4.3.2 Initializing the rt11Fs File System
4.3.3 Initializing a Device for Use with rt11Fs
4.3.4 Mounting Volumes
4.3.5 File I/O
4.3.6 Opening the Whole Device (Raw Mode)
4.3.7 Reclaiming Fragmented Free Disk Space
4.3.8 Changing Disks
Announcing Disk Changes with Ready-Change
Disks with No Change Notification
4.3.9 I/O Control Functions Supported by rt11FsLib
4.4 Raw File System: rawFs
4.4.1 Disk Organization
4.4.2 Initializing the rawFs File System
4.4.3 Initializing a Device for Use with the rawFs File System
4.4.4 Mounting Volumes
4.4.5 File I/O
4.4.6 Changing Disks
Unmounting Volumes
Announcing Disk Changes with Ready-Change
Disks with No Change Notification
Synchronizing Volumes
4.4.7 I/O Control Functions Supported by rawFsLib
4.5 Tape File System: tapeFs
4.5.1 Tape Organization
4.5.2 Using the tapeFs File System
Initializing the tapeFs File System
Initializing a Device for Use with the tapeFs File System
Mounting Volumes
Modes of Operation
File I/O
Changing Tapes
I/O Control Functions Supported by tapeFsLib
4.6 CD-ROM File System: cdromFs
4.7 The Target Server File System: TSFS
How It Works
Security Considerations
5 C++ Development
5.1 Introduction
5.2 C++ Development Under Tornado
5.2.1 Tools Support
WindSh
Debugger
5.2.2 Programming Issues
Making C++ Entry Points Accessible to C Code
5.2.3 Compiling C++ Applications
5.2.4 Configuration Constants
5.2.5 Munching C++ Application Modules
5.2.6 Static Constructors and Destructors
Calling Static Constructors and Destructors Interactively
Constructors and Destructors in System Startup and Shutdown
5.2.7 Template Instantiation
5.3 C++ Language and Library Support
5.3.1 Language Features
Exception Handling
Run-Time Type Information (RTTI)
5.3.2 Standard Template Library (STL)
Iostream Library
String and Complex Number Classes
5.4 Example
5.5 Wind Foundation Classes
5.5.1 VxWorks Wrapper Class Library
5.5.2 Tools.h++ Library
6 Shared-Memory Objects
6.1 Introduction
6.2 Using Shared-Memory Objects
6.2.1 Name Database
6.2.2 Shared Semaphores
6.2.3 Shared Message Queues
6.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
6.3 Internal Considerations
6.3.1 System Requirements
6.3.2 Spin-lock Mechanism
6.3.3 Interrupt Latency
6.3.4 Restrictions
6.3.5 Cache Coherency
6.4 Configuration
6.4.1 Shared-Memory Objects and Shared-Memory Network Driver
6.4.2 Shared-Memory Region
6.4.3 Initializing the Shared-Memory Objects Package
6.4.4 Configuration Example
6.4.5 Initialization Steps
6.5 Troubleshooting
6.5.1 Configuration Problems
6.5.2 Troubleshooting Techniques
7 Virtual Memory Interface
7.1 Introduction
7.2 Basic Virtual Memory Support
7.3 Virtual Memory Configuration
7.4 General Use
7.5 Using the MMU Programmatically
7.5.1 Virtual Memory Contexts
Global Virtual Memory
Initialization
Page States
7.5.2 Private Virtual Memory
7.5.3 Noncacheable Memory
7.5.4 Nonwritable Memory
7.5.5 Troubleshooting
7.5.6 Precautions
8 Configuration and Build
8.1 Introduction
8.2 The Board Support Package (BSP)
The System Library
Virtual Memory Mapping
The Serial Driver
BSP Initialization Modules
BSP Documentation
8.3 VxWorks Initialization Timeline
The VxWorks Entry Point: sysInit( )
The Initial Routine: usrInit( )
Initializing the Kernel
Initializing the Memory Pool
The Initial Task: usrRoot( )
The System Clock Routine: usrClock( )
Initialization Summary
8.4 Building, Loading, and Unloading Application Modules
8.4.1 Using VxWorks Header Files
VxWorks Header File: vxWorks.h
Other VxWorks Header Files
ANSI Header Files
The -I Compiler Flag
VxWorks Nested Header Files
Internal Header Files
VxWorks Private Header Files
8.4.2 Compiling Application Modules
The GNU Tools
Cross-Development Commands
Defining the CPU Type
Compiling C Modules
Compiling C++ Modules
8.4.3 Static Linking (Optional)
8.4.4 Downloading an Application Module
8.4.5 Module IDs and Group Numbers
8.4.6 Unloading Modules
8.5 Configuring VxWorks
8.5.1 The Environment Variables
8.5.2 The Configuration Header Files
The Global Configuration Header File: configAll.h
The BSP-specific Configuration Header File: config.h
Selection of Optional Features
8.5.3 The Configuration Module: usrConfig.c
8.6 Alternative VxWorks Configurations
8.6.1 Scaling Down VxWorks
Excluding Kernel Facilities
Excluding Network Facilities
Option Dependencies
8.6.2 Executing VxWorks from ROM
8.6.3 Initialization Sequence for ROM-Based VxWorks
8.7 Building a VxWorks System Image
8.7.1 Available VxWorks Images
8.7.2 Rebuilding VxWorks with make
Making on UNIX Hosts
Making on Windows Hosts
8.7.3 Including Customized VxWorks Code
8.7.4 Linking the System Modules
8.7.5 Creating the System Symbol Table Module
8.8 Makefiles for BSPs and Applications
8.8.1 Make Variables
Variables for Compilation Options
Variables for BSP Parameters
Variables for Customizing the Run-Time
8.8.2 Using Makefile Include Files for Application Modules
8.8.3 Makefile for SIO Drivers
8.9 Creating Bootable Applications
8.9.1 Creating a Standalone VxWorks System with a Built-in Symbol Table
8.9.2 Creating a VxWorks System in ROM
General Procedures
Boot ROM Compression
9 Target Shell
9.1 Introduction
9.2 Target-Resident Shell
9.2.1 Creating the Target Shell
9.2.2 Using the Target Shell
9.2.3 Debugging with the Target Shell
9.2.4 Aborting the Target Shell
9.2.5 Remote Login to the Target Shell
Remote Login From Host: telnet and rlogin
Remote Login Security
9.2.6 Summary of Target and Host Shell Differences
9.3 Other Target-Resident Facilities
9.3.1 Target Symbol Table, Module Loader, and Module Unloader
9.3.2 Show Routines
Appendices
A Motorola MC680x0
A.1 Introduction
A.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C or C++ Modules
A.3 Interface Variations
CPU-Specific Interfaces
a.out-Specific Tools
A.4 Architecture Considerations
MC68060 Unimplemented Integer Instructions
Double-word Integers: long long
Interrupt Stack
MC68060 Superscalar Pipeline
Caches
Memory Management Unit
Floating-Point Support
Memory Layout
B Sun SPARC, SPARClite
B.1 Introduction
B.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C or C++ Modules
B.3 Interface Variations
a.out-Specific Tools for SPARC and SPARClite
B.4 Architecture Considerations
Reserved Registers
Processor Mode
Vector Table Initialization
Double-word Integers: long long
Interrupt Handling
Floating-Point Support
Stack Pointer Usage
SPARClite Overview
Memory Layout
C Intel i960
C.1 Introduction
C.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C or C++ Modules
Boot Loader Changes
C.3 Interface Variations
Initialization
Data Breakpoint Routine bh( )
Parameter Change for intLevelSet( )
Results Change for memLib
Math Routines
Adding in Unresolved Routines
Floating-Point Task Option: VX_FP_TASK
COFF-Specific Tools For i960
Limitation on d( ) in WindSh
C.4 Architecture Considerations
Byte Order
Double-word Integers: long long
VMEbus Interrupt Handling
Memory Layout
D Intel x86
D.1 Introduction
D.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C and C++ Modules
D.3 Interface Variations
Supported Routines in mathALib
Architecture-Specific Global Variables
Architecture-Specific Routines
a.out-Specific Tools for x86
D.4 Architecture Considerations
Operating Mode, Privilege Protection, and Byte Order
Memory Segmentation
I/O Mapped Devices
Memory Mapped Devices
Memory Considerations for VME
Interrupts and Exceptions
Registers
Counters
Double-word Integers: long long
Context Switching
ISA/EISA Bus
PC104 Bus
PCI Bus
Software Floating-Point Emulation
VxWorks Memory Layout
D.5 Board Support Packages
Boot Considerations for PC Targets
Mounting a DOS File System
DMA Buffer Alignment and cacheLib
Support for Third-Party BSPs
VxWorks Images
BSP-Specific Global Variables for 386 and 486
Configuring the Pentium BSP
Configuring the PentiumPro BSP
ROM Card and EPROM Support
Device Drivers
E MIPS R3000, R4000, R4650
E.1 Introduction
E.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C or C++ Modules
E.3 Interface Variations
cacheR3kLib and cacheR4kLib
dbgLib
intArchLib
mathALib
taskArchLib
MMU Support
ELF-specific Tools
E.4 Architecture Considerations
Gprel Addressing
Reserved Registers
Floating-Point Support
Interrupts
Virtual Memory Mapping
64-bit Support (R4000 Targets Only)
Memory Layout
F PowerPC
F.1 Introduction
F.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C and C++ Modules
Compiling Modules for GDB
Unsupported Features
F.3 Interface Changes
Memory Management Unit
HI and HIADJ Macros
ELF-Specific Tools
F.4 Architecture Considerations
Processor Mode
24-bit Addressing
Byte Order
PowerPC Register Usage
Caches
Memory Management Unit
Floating-Point Support
VxMP Support for Motorola PowerPC Boards
Memory Layout
G ARM
G.1 Introduction
G.2 Building Applications
Defining the CPU Type
Configuring the GNU ToolKit Environment
Compiling C and C++ Modules
Boot Loader Changes
G.3 Toolchain Information
Assembler Pseudo Operations
Additional ARM Compiler Options
CrossWind and GDB
G.4 Interface Variations
Restrictions on cret( ) and  tt( )
cacheLib
dbgLib
dbgArchLib
intALib
intArchLib
mmuALib
usrLib
vmLib
vxALib
vxLib
COFF-Specific Tools For ARM
G.5 Architecture Considerations
Processor Mode and Byte Order
ARM/Thumb State
Interrupts and Exceptions
Floating-Point Support
Caches
Memory Management Unit
Memory Layout
H VxSim
H.1 Introduction
H.2 The Built-in Simulator
Installation and Configuration
Starting VxSim
Rebooting VxSim
Exiting VxSim
System-Mode Debugging
File Systems
H.3 Building Applications
Defining the CPU Type
The Toolkit Environment
Compiling C and C++ Modules
Linking an Application to VxSim
Architecture-Specific Tools
H.4 Architecture Considerations
Supported Configurations
The BSP Directory
Interrupts
Clock and Timing Issues
H.5 VxSim Networking Component
Installing VxSim Network Drivers
Configuring VxSim for Networking
Running Multiple Simulators
System Mode Debugging
IP Addressing
Choosing Processor Numbers for Distinct Devices
Setting Up Remote Access
Setting up the Shared Memory Network (UNIX only)
I Coding Conventions
I.1 Introduction
I.2 File Heading
I.3 C Coding Conventions
I.3.1 C Module Layout
I.3.2 C Subroutine Layout
I.3.3 C Declaration Formats
Variables
Subroutines
I.3.4 C Code Layout
Vertical Spacing
Horizontal Spacing
Indentation
Comments
I.3.5 C Naming Conventions
I.3.6 C Style
I.3.7 C Header File Layout
Structural
Order of Declaration
I.3.8 Documentation Format Conventions for C
Layout
Format Commands
Special Elements
Formatting Displays
Index