VxWorks

Programmer's Guide

5.5

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.3 Intertask Communications

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

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

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.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

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 Host Shell 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

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

10 Distributed Message Queues

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