Vxworks Migration Guide 6.2

VxWorks Migration Guide
VxWorks
MIGRATION GUIDE
6.2
Copyright 2005 Wind River Systems, Inc. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means without the prior written permission of Wind River Systems, Inc. Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. Any third-party trademarks referenced are the property of their respective owners. For further information regarding Wind River trademarks, please see: http://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 the following location: installDir/product_name/3rd_party_licensor_notice.pdf. 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 Systems, Inc. 500 Wind River Way Alameda, CA 94501-1153 U.S.A. toll free (U.S.): (800) 545-WIND telephone: (510) 748-4100 facsimile: (510) 749-2010 For additional contact information, please visit the Wind River URL: http://www.windriver.com For information on how to contact Customer Support, please visit the following URL: http://www.windriver.com/support
VxWorks Migration Guide, 6.2 18 Nov 05 Part #: DOC-15598-ZD-00
Contents
Overview ...............................................................................................
1.1 1.2 1.3 1.4 1.5 1.6 Introduction ............................................................................................................. Documentation ....................................................................................................... Key Concepts ........................................................................................................... Terminology ............................................................................................................. Target Requirements .............................................................................................. Summary of Contents ............................................................................................ 1.6.1 1.6.2 1.6.3 1.6.4 1.6.5 1.6.6 1.6.7 Changes in the VxWorks Environment ................................................. Porting a BSP to VxWorks 6.2 ................................................................. Migrating VxWorks 5.5 Applications to the 6.2 Kernel ...................... Migrating Applications to RTPs ............................................................. Migrating Applications From VxWorks AE to VxWorks 6.2 ............. Migrating To the New VxBus ................................................................. Conversion to apigen ...............................................................................
1
1 2 3 3 5 6 6 6 6 7 7 7 7
iii
VxWorks Migration Guide, 6.2
Changes in the VxWorks Environment .............................................

2.1 2.2 Introduction ............................................................................................................. Configuring Your System ..................................................................................... 2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 2.3 Default Features ........................................................................................ Configuration Process .............................................................................. Obsolete C++ Components Removed ................................................... Changed Scheduler Configuration Parameters ................................... Wind River PPP Replaced .......................................................................
9
9 11 11 12 12 12 12 13 13 13 14 14 15 15 15 15 16 16 17 18 18 19 19 20 20 20 21
Building Your System and Applications ........................................................... 2.3.1 2.3.2 2.3.3 Header Trees ............................................................................................. Directory Changes .................................................................................... Compiler and Build Changes ................................................................. Default Compiler Change ....................................................................... Extra Compiler Command-line Flags .................................................... Setting Additional Build Flags ............................................................... C++ and STL ............................................................................................. SH C++ Libraries ...................................................................................... Compiler Warning and Error Levels ..................................................... GNU Compiler Changes ......................................................................... torVars Replaced ....................................................................................... 2.3.4 2.3.5 Building Real-Time Process (RTP) Applications .................................. Migrating Custom BSP Makefiles ..........................................................
2.4
Writing Applications in C and C++ .................................................................... 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 New C/C++ Libraries .............................................................................. Access to the TCB ..................................................................................... No activeQhead ........................................................................................ Standard Template Library ..................................................................... Stricter Syntax ...........................................................................................
iv
Contents
2.5
Accommodating New Features Introduced in VxWorks 6.0 .......................... 2.5.1 2.5.2 Including New Features .......................................................................... Changed Memory Mapping ................................................................... Driver Access to User-mode Memory ................................................... Protected Real-time Process Requires MMU ........................................ Error Detection and Reporting Requires Reserved Memory ............. 2.5.3 2.5.4 2.5.5 2.5.6 2.5.7 2.5.8 2.5.9 Boot Loaders ............................................................................................. RTP Startup Facility ................................................................................. Wind River System Viewer ..................................................................... Power Management ................................................................................. RTPs Replace VxVMI ............................................................................... Message Channels Replace VxFusion ................................................... Networking Changes ...............................................................................
21 22 22 23 23 23 24 25 25 26 26 27 27 27 27 29 30 30 30 31 31 31 31 32 32 33 33 33 34
2.6
Changes Introduced in VxWorks 6.1 .................................................................. 2.6.1 2.6.2 2.6.3 2.6.4 2.6.5 2.6.6 2.6.7 2.6.8 2.6.9 2.6.10 Loader Changes ........................................................................................ Task Stack Overrun and Underrun ........................................................ File Descriptors Inheritance .................................................................... RTP Initial Task Names ........................................................................... Multiple Sessions of the Kernel Shell .................................................... unld( ) and reld( ) Available In Shell Only ........................................... ISR Objects ................................................................................................. Object Ownership Tracking .................................................................... Resource Reclamation .............................................................................. Driver Changes ......................................................................................... Drivers Source Compatible Only ........................................................... No BSD-Style Drivers .............................................................................. Modified smEnd ....................................................................................... 2.6.11 2.6.12 Task Self-destruction ................................................................................ Stricter Error Checking on Semaphores ................................................
2.6.13
Message Channel API .............................................................................. sockOpt Structure Changed .................................................................... backlog Parameter Added ......................................................................
34 34 35 35 35 36 36 36 37 37 37 38 38 38 38 40
2.7
Changes Introduced in VxWorks 6.2 .................................................................. 2.7.1 File System Changes ................................................................................ Extended Block Device (XBD) ................................................................ File System Monitor ................................................................................. Highly Reliable File System .................................................................... Discontinued Features ............................................................................. Deprecated Features ................................................................................. 2.7.2 2.7.3 2.7.4 2.7.5 Expanded POSIX Support ....................................................................... Changes To Memory Partition Options ................................................ Scalability ................................................................................................... VxBus .........................................................................................................
2.8 2.9
Determining If a BSP Requires Migration ........................................................ Architecture-Specific Issues .................................................................................
Porting a BSP to VxWorks 6.2 ............................................................. 43

3.1 3.2 3.3 3.4 Introduction ............................................................................................................. Features Supported ................................................................................................ Porting a BSP to VxWorks 6.2 .............................................................................. Booting a VxWorks 5.5 BSP .................................................................................. 3.4.1 Command-Line Build and Boot ............................................................. Build Environment ................................................................................... Customizing VxWorks ............................................................................. Building VxWorks .................................................................................... Starting VxWorks ...................................................................................... 3.4.2 Wind River Workbench Build and Boot ................................................ Build Environment ................................................................................... Customizing VxWorks ............................................................................. 43 44 44 55 55 55 56 57 57 59 59 60
vi
Contents
Building VxWorks .................................................................................... Starting VxWorks ..................................................................................... Starting the Target Server ........................................................................
61 61 63
Migrating VxWorks 5.5 Applications To the 6.2 Kernel .....................

4.1 4.2 4.3 Introduction ............................................................................................................. Migration Checklist ............................................................................................... Build Changes ......................................................................................................... 4.3.1 4.3.2 Recompiling Source Code ....................................................................... Header File Changes ................................................................................ Type Changes ............................................................................................ IPv6 Stack Headers Directory Change .................................................. isascii( ), toascii( ) Relocated ................................................................... objLib Macro Moved ................................................................................ 4.3.3 4.4 Compiling for Both VxWorks 6.x and VxWorks 5.5 ............................
65
65 67 68 68 68 68 69 69 69 69 70 70 71 71 71 73 73 73 74 74 74 74 75 75
Internal Changes .................................................................................................... 4.4.1 4.4.2 Initialization Routines ............................................................................. Loader Changes ........................................................................................ Backward Compatibility ......................................................................... Changed Symbol Type Values ................................................................ Resolving Common Symbols ................................................................. Symbol Tables and Modules Not Objects .............................................
4.5
System Changes ...................................................................................................... 4.5.1 Tasks and the TCB .................................................................................... Accessing the TCB .................................................................................... Changed Components and Macros ....................................................... taskSwitchHookAdd( ) Behavior Modified .......................................... taskCreat( ) Deprecated ........................................................................... 4.5.2 _func_excBaseHook Daisy Chaining .....................................................
vii
4.5.3
Memory Partition Options ...................................................................... New Options ............................................................................................. Deprecated Options ................................................................................. Changed Default Options ....................................................................... Restoring Prior Options ...........................................................................
76 76 76 77 77 78 78 79 79 79 79 79 80 80 80 81 81 81 81 81 82 82 82 82 83 85 85 86 86 87 87 89 90
4.5.4 4.5.5 4.5.6
Caching ...................................................................................................... Scalability Changes .................................................................................. Other System API Changes ..................................................................... Newly Public Libraries and APIs ........................................................... Newly Private Structures and Routines ................................................ New APIs and Libraries .......................................................................... Parameter Change .................................................................................... Deprecated Library and APIs ................................................................. Deprecated APIs ....................................................................................... Removed APIs ..........................................................................................
4.6
Networking Changes ............................................................................................. Deprecated Header Files ......................................................................... Unneeded Header Files Removed ......................................................... No _KERNEL Flag ................................................................................... IPv4 FTP Server Replaced ....................................................................... etherAddrResolve( ) Removed ............................................................... IP Forwarding ...........................................................................................
4.7
Driver Changes ....................................................................................................... END-Style Drivers Replace BSD Drivers .............................................. Modified smEnd .......................................................................................
4.8
I/O System Changes ............................................................................................... I/O Error Code Value Changes .............................................................. I/O Device Control APIs .........................................................................
4.9
File System Changes .............................................................................................. 4.9.1 Extended Block Device (XBD) Support ................................................. XBD Replaces CBIO ................................................................................. Fallback to rawFs ...................................................................................... ATA Driver Changes ................................................................................
viii
Contents
Disk Formatting ........................................................................................ Changes to ioctl( ) Commands ............................................................... 4.9.2 4.9.3 HRFS .......................................................................................................... dosFS .......................................................................................................... Migrating From dosFs 1.0 to 2.0 ............................................................. Changed APIs ........................................................................................... 4.9.4 4.10 File System-Related APIs and Libraries Removed ..............................
90 90 91 92 92 93 93 93 94 94 94 95 95 95 96 97 98 98 99 99 99 99
Changes in POSIX Support .................................................................................. 4.10.1 Changes in POSIX Facilities in VxWorks 6.0 ........................................ POSIX Message Queues .......................................................................... POSIX Thread Support ............................................................................ POSIX Semaphores .................................................................................. 4.10.2 Changes in POSIX APIs in VxWorks 6.2 ............................................... New POSIX APIs ...................................................................................... Changes in Existing POSIX APIs ........................................................... Modified Signal APIs ............................................................................... Modified I/O system Device Control APIs .......................................... New I/O System Device Control APIs ................................................. Modified Macros and Parameters ..........................................................
4.11
Changes To VxWorks Components .................................................................... 4.11.1 4.11.2 4.11.3 4.11.4 VxFusion No Longer Available .............................................................. Migrating From VxVMI To RTPs ...........................................................
PPP ............................................................................................................. 102 Wind River System Viewer ..................................................................... 102 APIs Changed ........................................................................................... 103 APIs Removed .......................................................................................... 103
Migrating Applications to RTPs .......................................................... 105

5.1 5.2 Introduction ............................................................................................................. 105 Issues In Moving Applications to RTPs ............................................................ 106 5.2.1 Compiling Code for Both User and Kernel Mode ............................... 106
ix
5.2.2 5.2.3
Reducing Library Size ............................................................................. 107 RTP Scope .................................................................................................. 107 Communicating Between Applications ................................................ 107 Communicating Between an Application and the Operating System ......................................................................................... 108
5.2.4 5.2.5 5.2.6
Initialization and Finalization Code in C++ ......................................... 108 Eliminating Hardware Access ................................................................ 109 No Interrupt Context In RTPs ................................................................ 110 POSIX Signals ........................................................................................... 110 No Watchdogs ........................................................................................... 110 No Drivers ................................................................................................. 111
5.2.7 5.2.8
I/O Redirection ........................................................................................ 111 Process and Task API Differences .......................................................... 113 Task Naming Changed ............................................................................ Changes in Scope Between Kernel and User Modes ........................... Task Locking and Unlocking .................................................................. Private and Public Objects ...................................................................... 113 113 114 114
5.2.9 5.2.10
Semaphore Differences ............................................................................ 114 POSIX Signal Differences ........................................................................ 115 Signal Generation ..................................................................................... Signal Delivery ......................................................................................... Scope Of Signal Handlers ....................................................................... Default Handling Of Signals .................................................................. Default Signal Mask For New Tasks ...................................................... Signals Sent To Blocked Tasks ................................................................ Signal API Behavior ................................................................................. 115 115 116 116 116 116 117
5.2.11 5.2.12
Networking Issues ................................................................................... 117 Header File Differences ........................................................................... 118 RTPs Compared to VxWorks 5.5 ............................................................ 118 New or Changed Header Files for VxWorks 6.2 .................................. 118
5.3
Changes to User APIs For RTPs in VxWorks 6.0 .............................................. 119 5.3.1 5.3.2 APIs Not Present In User Mode ............................................................. 119 APIs Added For RTPs Only .................................................................... 120
Contents
5.3.3 5.3.4 5.3.5 5.3.6 5.4
APIs That Work Differently In RTPs ..................................................... 120 ANSI vs. POSIX API Differences ........................................................... 121 Kernel Calls Require Kernel Facilities ................................................... 121 Other API Issues ....................................................................................... 121
Enhanced Support for POSIX Applications in VxWorks 6.2 ......................... 121 5.4.1 5.4.2 POSIX Thread Scheduling ...................................................................... 122 POSIX-Related Changes in Libraries and APIs ................................... 124 New POSIX APIs ...................................................................................... 124 Changes in Existing POSIX APIs ........................................................... 125 5.4.3 POSIX-Related Header File Changes .................................................... 133 New POSIX Header Files ........................................................................ 133 New Version Header File ........................................................................ 133 Changes In Existing POSIX Header Files ............................................. 134 5.4.4 POSIX Configuration Components and Parameters ........................... 136 New Components and Parameters ........................................................ 136 Changed Configuration Parameters ...................................................... 136 Addition of sysctl Identifiers .................................................................. 137
5.5
Changed Memory Partition Options in VxWorks 6.2 ..................................... 137 5.5.1 5.5.2 5.5.3 5.5.4 New Options ............................................................................................. 137 Deprecated Options ................................................................................. 138 Changed Default Options ....................................................................... 138 Restoring Prior Options .......................................................................... 139
5.6 5.7
File System-Related Changes in VxWorks 6.2 .................................................. 139 Component Changes .............................................................................................. 139 5.7.1 5.7.2 5.7.3 5.7.4 RTPs Replace VxVMI ............................................................................... 139 PPP ............................................................................................................. 140 Network Clients and Servers .................................................................. 140 System Viewer .......................................................................................... 140
xi
Migrating Applications From VxWorks AE to VxWorks 6.x .............. 141

A.1 A.2 Introduction ............................................................................................................. 141 Changes .................................................................................................................... 141 A.2.1 A.2.2 A.2.3 A.2.4 Application Model ................................................................................... 142 Memory Model ......................................................................................... 142 Entry Points ............................................................................................... 143 Memory Management ............................................................................. 143 Similarities ................................................................................................. 144 Differences ................................................................................................. 144 A.2.5 A.2.6 A.3 A.4 Module Management ............................................................................... 146 CDF Components ..................................................................................... 146
Compiler ................................................................................................................... 147 User and Kernel APIs ............................................................................................ 147 A.4.1 A.4.2 A.4.3 Kernel API Differences ............................................................................ 148 Task State ................................................................................................... 148 Host and Kernel Shell .............................................................................. 148 Shared Libraries ........................................................................................ 149 Shared Data Regions ................................................................................ 150 A.4.4 Other Differences ...................................................................................... 151
Migrating to the New VxBus ................................................................ 153

B.1 Introduction ............................................................................................................. 153 B.1.1 B.1.2 Glossary ..................................................................................................... 154 Overview of VxBus .................................................................................. 156 Participants ................................................................................................ Configuration ............................................................................................ BSP Requirements .................................................................................... Source files ................................................................................................. 156 158 159 159
xii
Contents
B.2
Device Driver Interface ......................................................................................... 160 B.2.1 B.2.2 Driver Registration and Initialization Mechanism .............................. 160 Register Access Routines ......................................................................... 163 Standard Access Routines ....................................................................... 163 BSP-Specific Optimized Register Access Routines .............................. 163 B.2.3 B.2.4 B.2.5 Interrupt Handling ................................................................................... 164 Driver Methods ........................................................................................ 165 Compilation Context ............................................................................... 165 Generic Drivers ......................................................................................... 166 BSP-Specific Optimized Access .............................................................. 166 B.2.6 Instance Creation ...................................................................................... 166 Automatic Procedures ............................................................................. 166 Driver-Provided Probe ............................................................................ 167
B.3
Bus Type Requirements and Interface ............................................................... 168 B.3.1 B.3.2 PLB Bus Type ............................................................................................ 168 PCI Bus Type ............................................................................................. 169
B.4 B.5
BSP Modifications .................................................................................................. 169 Driver Modifications ............................................................................................. 171 B.5.1 B.5.2 Registration Only ..................................................................................... 171 Full Participation ...................................................................................... 172
B.6 B.7
Initialization Sequence ......................................................................................... 173 Hardware Configuration File ............................................................................... 176 B.7.1 Structures ................................................................................................... 176 hcfResource[ ] Parameters ....................................................................... 176 B.7.2 Interrupt Information .............................................................................. 177
B.8
Optimization Issues ............................................................................................... 178 B.8.1 B.8.2 Internal Optimization .............................................................................. 178 BSP-supplied Optimization .................................................................... 179
xiii
Conversion to apigen ........................................................................... 181

Summary of apigen Markup .................................................................. 181
Index .............................................................................................................. 183
xiv
1
Overview
1.1 Introduction 1 1.2 Documentation 2 1.3 Key Concepts 3 1.4 Terminology 3 1.5 Target Requirements 5 1.6 Summary of Contents 6
1.1 Introduction
One of the original goals for VxWorks 6.0 was that existing VxWorks 5.5 kernel applications and BSPs should be source-compatible. This goal has not changed forVxWorks 6.2. Most applications will still work after recompiling them for VxWorks 6.2. This VxWorks Migration Guide focuses primarily on migration from VxWorks 5.5 to VxWorks 6.2. In most cases, the migration issues from VxWorks 5.5 to VxWorks 6.2 are the same as those for migrating from VxWorks 5.5 to VxWorks 6.0 or 6.1. In general, the Migration Guide refers to migrating to VxWorks 6.x. If there are significant differences that necessitate additional work to migrate from VxWorks 6.0 to VxWorks 6.1, or from VxWorks 6.1 to VxWorks 6.2, then these cases are highlighted and specific instructions provided as necessary.
The VxWorks Migration Guide is intended for several groups of developers:
BSP developers who want to migrate existing VxWorks 5.5 BSPs to VxWorks 6.x. Application developers who want to migrate existing VxWorks 5.5 kernel applications to the VxWorks 6.x kernel. Application developers who want to migrate existing VxWorks 5.5 kernel applications to a VxWorks 6.x real-time process (RTP). VxWorks AE developers who want to migrate existing VxWorks AE applications from a protection domain to an RTP. System developers who want to configure VxWorks 6.x to run ported applications using new capabilities.
In general, the migration path to VxWorks 6.2 is easy; VxWorks 5.5 kernel applications are source-compatible with the VxWorks 6.x kernel. On the other hand, VxWorks 6.x provides both a traditional kernel-mode development environment and a new user-mode application development environment, supported by full memory protection. This migration guide examines these two modes, and gives specific guidance on the use of header files and other considerations for moving applications between modes.
1.2 Documentation
The installed location of the online API documentation and the VxWorks manuals has changed with this release. The documentation is available by selecting Help > Help Contents from Workbench. The reference entries are available in Wind River Documentation > References and the manuals in Wind River Documentation > Guides. In addition, UNIX-style man pages are available. For instructions on creating an alias for quick access, see your product getting started. To view the HTML reference entries directly, see: installDir/docs/extensions/eclipse/plugins/com.windriver.ide.doc.xxx To view the man pages directly, see: installDir/vxworks-6.x/man/cat
1 Overview 1.3 Key Concepts
1.3 Key Concepts

You may be interested in migrating applications which have been written for a previous version of VxWorks out of the kernel and into a user-mode application. When considering this, it is important to understand how your application might be affected. Unlike applications developed for kernel mode, a VxWorks executable developed for user mode runs in a protected memory space. In order to ensure system stability and reliability, the application is not allowed to access system resources, such as hardware, directly. Specifically:
It is not possible to access hardware- or processor-specific features directly. Any code that would typically be found in a BSP directory is unlikely to work from user mode. Direct access to drivers is not available from user mode. Some VxWorks features, in particular layer 2 networking capabilities, have a close connection with I/O devices; as a result, these features are not available in user mode. It is not possible to access kernel object structures such as semaphore objects directly from user mode. The user-mode versions of APIs, such as semTake( ) for semaphores, should be used rather than attempting to use kernel-mode APIs. The user-mode APIs provide access to kernel functions without compromising the integrity of the kernel or of other applications. User-mode objects do not reside within an RTPs memory space. It is not possible to access the contents of these structures directly from within the RTP.
1.4 Terminology
VxWorks Terms
Real-time process (RTP): The user-mode application execution environment provided by VxWorks 6.x. Each process has its own address space, containing the executable program, the programs data, execution and exception stacks
for each task, the heap, and resources associated with the management of the process itself. Project: A collection of source code, binary files, and build specifications within the Workbench development environment. Workspace: A collection of projects in the Workbench development environment. Component: A VxWorks facility that can be included or excluded, making VxWorks scalable. Error detection and reporting The facility for detecting errors, logging error information, and making that information available across a warm reboot.
Types of Projects
VxWorks image project: The project type used to configure and build VxWorks images. Downloadable kernel module project: The project type used to manage and build dynamically linked application modules that run in kernel mode. Real-time process project: The project type used to manage and build statically or dynamically linked application modules into an executable that can be dynamically downloaded and run as a real-time process (RTP). Shared-library project: The project type used to manage and build dynamically linked shared libraries.
Tool-related Terms
Toolchain: A collection of development tools for a specific target CPU; includes compiler, linker, assembler, and so on. Build specification: User-specified settings and rules which are used to build a project.
1 Overview 1.5 Target Requirements
Graphical User Interface (GUI):
The interactive, graphical face of Workbench. Workbench also offers a command-line interface. For more information on Workbench, see the Wind River Workbench Users Guide. For more information on the command line, see the VxWorks Command-Line Tools Users Guide.
Release-related Terms
Deprecated: Wind River intends to discontinue an API in a future release; it currently works for the benefit of existing applications, but it should not be used in new applications and existing applications should be migrated away from it as soon as convenient.
1.5 Target Requirements

The target is the computer for which you are developing. This section lists the minimum requirements for running a target with your product in the standard configuration, in which the host and target are separate computers. The target system must be either the Wind River VxWorks Simulator or a supported target board with the following:
8 MB RAM for systems with small demands (more if a RAM disk is used). All supported reference boards from Wind River include at least 8 MB of memory. Space for a file system on hard disk, ramdisk, flash memory, or floppy disk. An Ethernet cable or null crossover cable (needed for initial board setup). A RS-232 null modem cable (needed for initial board setup). A floppy disk drive or network installation card for installation of a file system. A keyboard (recommended for configuration if using network booting). A monitor (recommended for configuration if using network booting).
For a detailed list of supported hardware, including target boards, keyboards, monitors, and more, see your product release notes.
1.6 Summary of Contents

In general, this migration guide focuses on migrating your applications and BSPs to VxWorks 6.2. This means that this book does not provide much information about new features introduced in VxWorks 6.2 or in previous VxWorks 6.x releases; in fact, new features are discussed only when activating them is necessary to migrate your existing applications or to make them available in your BSPs. For additional information about new VxWorks 6.2 features, see the product release notes, the VxWorks Kernel Programmers Guide, and the VxWorks Application Programmers Guide. If you are transitioning from a version of VxWorks earlier than 5.5, you should migrate to 5.5 before migrating to VxWorks 6.2 and Workbench 2.4. For more information, see the Tornado Migration Guide, 2.2. The sections below give a synopsis of the chapters in this guide.
1.6.1 Changes in the VxWorks Environment

This chapter provides a high-level summary of the changes between VxWorks 5.5 and VxWorks 6.x. These changes include configuration and build, writing applications in C and C++, and changes in how you think about your application in relation to the kernel and to user mode.
1.6.2 Porting a BSP to VxWorks 6.2

This chapter provides a step-by-step process for porting a VxWorks 5.5 BSP to VxWorks 6.2. It also provides instructions for building and booting your BSP from both the command line and from Wind River Workbench.
1.6.3 Migrating VxWorks 5.5 Applications to the 6.2 Kernel

This chapter provides a checklist to assess whether your application uses only basic functions and needs only to be rebuilt to run in the VxWorks 6.2 kernel, or whether you have customized features that require some migration. Remaining sections address the various areas where you may need to make changes.
1 Overview 1.6 Summary of Contents
1.6.4 Migrating Applications to RTPs

This chapter primarily addresses the differences between the kernel execution environment and a real-time process (RTP). Because they are essentially different, you will almost certainly need to make some changes to your application to make it suitable to run in an RTP. In addition, in VxWorks 6.2 enhanced support for POSIX applications is provided. This required changes in POSIX APIs and header files that may affect your application.
1.6.5 Migrating Applications From VxWorks AE to VxWorks 6.2

This appendix provides a comparison of behavior under VxWorks AE with that under VxWorks 6.x. It also discusses the differences between the protection domain model of VxWorks AE and the RTP model of VxWorks 6.x.
1.6.6 Migrating To the New VxBus

In VxWorks 6.2, Wind River has provided a new bus architecture. This appendix explains how to migrate your BSP to the new bus.
1.6.7 Conversion to apigen

This appendix provides a summary of apigen markup that will assist you to generating reference entries for your BSP that are compatible with the VxWorks documentation standard.
2
Changes in the VxWorks Environment
2.1 Introduction 9 2.2 Configuring Your System 11 2.3 Building Your System and Applications 13 2.4 Writing Applications in C and C++ 19 2.5 Accommodating New Features Introduced in VxWorks 6.0 21 2.6 Changes Introduced in VxWorks 6.1 27 2.7 Changes Introduced in VxWorks 6.2 35 2.8 Determining If a BSP Requires Migration 38 2.9 Architecture-Specific Issues 40
2.1 Introduction
As described in 1. Overview, VxWorks 6.x both maintains backward compatibility with VxWorks 5.5 and provides extensive new features. This chapter provides an overview of the changes, highlighting new concepts and key areas where migration may be a concern. In general, the focus is on differences between VxWorks 5.5 to VxWorks 6.x as a whole, as the concepts have not changed over the various 6.x releases. However, there are sections for users who have already
migrated to either 6.0 or 6.1, showing the incremental changes that may affect them. Your VxWorks 5.5 BSP or application should work with VxWorks 6.2 unless:
You plan to use new VxWorks 6.x capabilities. You have made modifications to your BSP. Your application is written in C++. You use certain APIs which have changed to support new functionality or to fix existing bugs. You use certain file system drivers that are not fully compatible with the new Extended Block Device facility (XBD). You use the dosFs 1.0 API or Wind Rivers proprietary VxWorks long name support for dosFs. You use POSIX routines that have been modified for greater compliance with the POSIX standard.
WARNING: As with previous VxWorks 6.x releases, VxWorks 6.2 is source
compatible only with VxWorks 5.5. Your VxWorks 5.5 BSP, drivers, and applications must be recompiled against VxWorks 6.2. This chapter discusses the changes between VxWorks 5.5 and VxWorks 6.2 as well as between previous versions of VxWorks 6.x and VxWorks 6.2 that could require you to migrate your BSP or that affect your application. If you have not already migrated your code to VxWorks 5.5, you must do this before migrating to VxWorks 6.2. See the Tornado Migration Guide, 2.2. This chapter covers issues that affect one or more of the following groups:

System developers who are configuring VxWorks. BSP developers who are migrating BSPs. Application developers who are migrating applications.
Most of the information in this chapter is relevant to more than one group. It supplements the more specific information provided in other chapters.
10
2 Changes in the VxWorks Environment 2.2 Configuring Your System
2.2 Configuring Your System

This section discusses issues relevant to the system engineer who configures VxWorks and its components.
2
2.2.1 Default Features

Aside from new features, the VxWorks default configuration has experienced minimal changes; the following components are no longer included by default:
INCLUDE_VXEVENTS INCLUDE_ISR_OBJECTS INCLUDE_OBJ_OWNERSHIP
If you wish to use these features, you must explicitly add them to your VxWorks image project. In addition, a dependency change causes POSIX clocks to be included if you include POSIX timers.
INCLUDE_POSIX_CLOCKS
If you use the clockLib API functions, you may need to explicitly add this component. The POSIX clocks component is automatically added when INCLUDE_POSIX_TIMERS is configured, but if you do not use the timers component, you must add INCLUDE_POSIX_CLOCKS manually. By default, the VxWorks 6.x configuration enables only features that are compatible with VxWorks 5.5. Therefore, Wind River BSPs for VxWorks 6.x disable the following features by default:

INCLUDE_RTP INCLUDE_SHARED_DATA INCLUDE_SHL INCLUDE_EDR_XXX
NOTE: The exceptions to this rule are the BSPs for the simulators. These enable a broader range of new capabilities by default, in order to support experimentation with the new features.
11
2.2.2 Configuration Process

In the past, VxWorks 5.5 could be configured either by using the Tornado project facility or by modifying config.h. For VxWorks 6.2, use of config.h is deprecated. You can migrate your config.h changes to VxWorks 6.2 by creating a VxWorks image project based on your BSP.
2.2.3 Obsolete C++ Components Removed

The following obsolete components have been removed from VxWorks 6.2:

INCLUDE_CPLUS_STL INCLUDE_CPLUS_STRING INCLUDE_CPLUS_STRING_IO INCLUDE_CPLUS_COMPLEX INCLUDE_CPLUS_COMPLEX_IO INCLUDE_IOSTREAMS_FULL
2.2.4 Changed Scheduler Configuration Parameters

The configuration parameter INCLUDE_CONSTANT_RDY_Q has been renamed to VX_NATIVE_SCHED_CONSTANT_RDY_Q. This configuration parameter is part of the new INCLUDE_VX_NATIVE_SCHEDULER component. For projects prior to VxWorks 6.2, a clean build is required in the project to pull in the new component and the replaced configuration parameter.
2.2.5 Wind River PPP Replaced

Previous releases of VxWorks 5.x bundled a simple PPP implementation with a simple API that was well-suited to downloading a boot image. This older API is no longer supported. However, the current PPP implementation does support a simplified interface. You can use this API to download boot images. You can also use it at run-time if your PPP needs are limited. You must include the INCLUDE_VXWORKS_5_X_EQUIV_PPP component through the configuration facility (either using Workbench or vxprj on the command line) to include this interface. Then rebuild your image. For more information, see the Wind River PPP Programmers Guide and your product getting started.
12
2 Changes in the VxWorks Environment 2.3 Building Your System and Applications
2.3 Building Your System and Applications

The build infrastructure has changed. If you use the default build method, these changes are transparent. If you have a customized build system, some changes to your build mechanism may be necessary; see 2.3.5 Migrating Custom BSP Makefiles, p.18. For more generalized build issues, see the Wind River Workbench Users Guide and the VxWorks Command-Line Tools User's Guide.
2
2.3.1 Header Trees

There are two sets of header files provided with VxWorks 6.2. One is for building the kernel, BSPs, and applications which are linked with the kernel. The other is for building VxWorks executables that run with memory protection in user mode. These header files should not be mixed. Each tree exposes the supported set of functionality in the two different operating modes. If functionality that you require is not present in user mode, it may be necessary to leave your application in the kernel. The compilers and the Workbench tools know the difference between the two environments, and use the appropriate header file tree. If the wrong set of header files is being used, check to be sure you are using the appropriate type of project. The kernel-mode development header files can be found in: installDir/vxworks-6.x/target/h The user-mode application development header files can be found in: installDir/vxworks-6.x/target/usr/h
2.3.2 Directory Changes

You may have already noticed that the target and host directory trees are stored one sub-directory deeper in the install tree under the vxworks-6.x directory than in VxWorks 5.5-based applications. You should also notice that the Wind River Compiler (formerly known as Diab) and the GNU compiler have moved out of the installDirTornado/host directory tree and into their own separate subdirectory trees in VxWorks 6.x. Finally, in VxWorks 6.x, the header files for the network stack have been more finely divided.
13
This impacts your makefiles in several ways. First, your binary executable path must include one of the following paths:
WIND_DIAB_PATH=$WIND_HOME/diab/5.3.1.0 WIND_GNU_PATH=$WIND_HOME/gnu/3.3.2-vxworks-6.2
It is important to note that common build utility binaries, some of them from the GNU distribution, are still located in: $WIND_BASE/host/$WIND_HOST_TYPE/bin However, the location pointed to by the above string has changed because the value of WIND_BASE has changed as follows: WIND_BASE=$WIND_HOME/vxworks-6.x
2.3.3 Compiler and Build Changes

All VxWorks 5.5 user libraries are functionally compatible with VxWorks 6.x. However, your code, including your BSP, must be recompiled with either the Wind River Compiler or the Wind River GNU Compiler. In most cases, VxWorks 6.0 and VxWorks 6.1 user library binaries are fully compatible with VxWorks 6.2.
Default Compiler Change
For VxWorks 6.x, the kernel libraries are built with the Wind River Compiler. However, Wind River continues to support both the Wind River Compiler and the Wind River GNU Compiler for building VxWorks applications. For migration information, see your product getting started. For more general build information, see the Wind River Workbench Users Guide and the VxWorks Command-Line Tools User's Guide. For information on compiling C++ code with the Wind River Compiler and the Dinkum standard template library, see 2.4 Writing Applications in C and C++, p.19 or your Wind River Compiler Users Guide.
14
Extra Compiler Command-line Flags
When compiling from the command line in VxWorks 6.x, it is necessary to define several macro values as command-line switches, for example: Wind River Compiler: -DCPU=PPC604 -DTOOL_FAMILY=diab -DTOOL=diab -D${BSPNAME} Wind River GNU Compiler: -DCPU=PPC604 -DTOOL_FAMILY=gnu -DTOOL=gnu -D${BSPNAME} While some Wind River header files may not produce compilation errors without these definitions, the resulting binary is suspect. For more information about command-line compilation, see the VxWorks Command-Line Tools User's Guide.
Setting Additional Build Flags
If you wish to set additional build flags, use the following macros: On the command line use: In Workbench use:
ADDED_CFLAGS, ADDED_C++FLAGS CC_ARCH_SPEC
C++ and STL
The C++ standard template library (STL) supplied with VxWorks 6.x is the Dinkum library, not the SGI library. Wind River provides no support for using the SGI STL with VxWorks 6.x. For information about the SGI standard template library, see http://www.sgi.com/tech/stl/. There are certain differences which must be taken into account when you compile your C++ code with the Dinkum STL. For more information, see 2.4 Writing Applications in C and C++, p.19.
SH C++ Libraries
VxWorks SH C++ libraries compiled with the Wind River Compiler are not backward compatible with the VxWorks 6.1 version and require a recompilation. (SH was first introduced in VxWorks 6.1.)
15
Compiler Warning and Error Levels
The Wind River-supplied makefiles for VxWorks 6.x implement stricter error checking and issue more warnings and errors than in the past. For more information on this subject, see your product getting started or the appropriate release notes.
GNU Compiler Changes
The GNU compilers in VxWorks 6.x are all based on the same FSF version 3.3.2, but they are not identical. The VxWorks 6.2 compiler has new features as well as bug fixes. If you are currently compiling your VxWorks 5.5 applications with GNU, and you plan to continue using GNU with VxWorks 6.2, there are several important changes you must take into account. In addition, if you are currently using VxWorks 6.0 or 6.1, you will find that new features and bug fixes have been introduced.
GNU Compiler Switches
One of the GNU complier switches has changed: -fvec has become -maltivec For more information on this and other switches, see the GNU compiler documentation. When compiling the kernel with the Wind River GNU Compiler, the -nostdlib option should still be used when linking; however, be aware that many of the other compiler options used as workarounds are no longer necessary. Most notably, the GNU 3.3 compiler is capable of producing valid C++ code with automatic template instantiation without any special directives. However, C++ code that is manually instantiated should continue to be compiled with -fno-implicit-templates. The GNU 3.3 C++ compiler does not support -fvolatile, though this capability is still available for plain C code. The Wind River Compiler supports the equivalent capability for C++ code and may be used instead. !
WARNING: You may not mix C++ object files compiled by different Wind River
compilers. If you need to use -fvolatile in C++ code builds, you must use the Wind River compiler to build all your C++ code.
16
objCopy Replaces Utilities
As of Workbench 2.2, GNU objcopy is used to convert files to binary and Motorola hex format rather than the legacy Wind River utilities. (These utilities may still be included, but they have known bugs, and they have not been updated in several major releases. Their use is deprecated.)
Unsupported Optimization Levels
Optimizing at the -O3 level is not supported in VxWorks 6.x, and was not supported in VxWorks 5.x. Of course, in specific cases it may be possible to compile with -O3 optimization and produce a valid object module. !
CAUTION: The fact that your application compiled successfully with -O3
optimization in the past is no guarantee that it will do so with the new compiler. Optimizing at the -O3 level is not supported in VxWorks 6.x.
torVars Replaced
The torVars script that was used to set up the working environment for VxWorks 5.x has changed for VxWorks 6.x to the wrenv script. For users of Workbench, this change is transparent; as with Tornado 2.2, Workbench automatically sets the environment appropriately. Command-line users should run the wrenv script at the root of their installation to set up the command-line environment and start the VxWorks command shell (Figure 2-1). For additional information on wrenv, see the VxWorks Command-Line Tools User's Guide: Creating a Development Shell with wrenv.
Figure 2-1 VxWorks Development Shell
17
Windows
To start a command shell from Windows, use the new VxWorks 6.x command shell, available from the Start menu: Start > Programs > Wind River > VxWorks 6.x and General Purpose Technologies > VxWorks Development Shell. The command shell is also available from the command prompt by entering:
C:\> installDir\wrenv.exe -p vxworks-6.x
Solaris/Linux
To start a command shell from Solaris or Linux, the new VxWorks 6.x command shell starts automatically when you type wrenv.sh on the command line.
% installDir/wrenv.sh -p vxworks-6.x
2.3.4 Building Real-Time Process (RTP) Applications

In some situations, it may be appropriate to port your VxWorks 5.5 application to a VxWorks 6.x RTP instead of to a VxWorks 6.x kernel application. This is usually the case when the application requires memory protection or if it makes use of the VxVMI library routines which are no longer supported. It may also be desirable when the product contains multiple disparate applications which are largely independent of each other, or if the application relies on POSIX behaviors and interfaces that may not be provided in the kernel space. It should be noted that processes are built differently from kernel application legacy code. When examining the build support for VxWorks 6.x, you must not confuse the new support included for building processes (RTPs) and shared libraries with that provided for building the kernel and dynamically linked objects. For more information see the VxWorks Application Programmers Guide.
2.3.5 Migrating Custom BSP Makefiles

For VxWorks 6.x, the target makefile infrastructure has moved to gmake 3.80. For additional information about the makefile conversion from a system perspective, see your product getting started. No makefile changes are required to port any Wind River-supported VxWorks 5.5 BSPs to VxWorks 6.x. However, if custom modifications to the makefile have been made or if there are differences between the third-party makefile and the standard Wind River makefile, some effort may be required to get a working VxWorks 6.x BSP makefile.
18
2 Changes in the VxWorks Environment 2.4 Writing Applications in C and C++
If conversion is required, the recommended method of performing this conversion is to start with a standard VxWorks 6.x makefile and get the BSP to build correctly. When that is done, non-standard additions and modifications from the VxWorks 5.5 version of the makefile can be applied to the working makefile, one at a time. Be sure to test using both command-line builds and project builds when making the modifications.
2.4 Writing Applications in C and C++

2.4.1 New C/C++ Libraries
New Dinkum C and C++ libraries are provided for most environments. As Table 2-1 shows, they are used in all cases except for C language applications in a kernel project, where the VxWorks native C libraries are used.
Table 2-1 Standard Libraries and Where They Are Used
Type of Application
C Language
C++ Language
User-mode application
Dinkum C Libraries
Dinkum C++ and Embedded C++ Libraries Dinkum C++ and Embedded C++ Libraries
Kernel-mode application VxWorks Native Libraries
The Dinkum C Libraries do not include any of the complex data types or compiler-dependent functions provided by C99. They do, however, conform to the POSIX standard. The VxWorks Native C Libraries provide functions outside the ANSI specification and provide no support for wide or multibyte characters and no support for locales. For more information, see the various reference entries. Because the Dinkum C++ libraries are different from the VxWorks 5.5 libraries, applications written in C++ require some migration.
19
2.4.2 Access to the TCB

In VxWorks 6.2, direct access to the task control block (WIND_TCB) structure is still permitted, but it deprecated. For information on alternative methods, see Accessing the TCB, p.74.
2.4.3 No activeQhead
The activeQhead no longer exists and cannot be used to determine if tasking has started. Example 2-1 shows the previous method:
Example 2-1 Old Method of Determining if Tasking Has Started if (Q_FIRST (&activeQHead) == NULL) /* pre kernel */ reboot (BOOT_WARM_AUTOBOOT); /* better reboot */
Since activeQHead no longer exists, instances where this was used in the past can be replaced with the method shown in Example 2-2:
Example 2-2 New Method of Determining if Tasking Has Started if ( taskIdCurrent == NULL) reboot (BOOT_WARM_AUTOBOOT); /* pre kernel */ /* better reboot */
2.4.4 Standard Template Library

The Dinkum Standard Template Library is more compliant with the ANSI standard than the SGI library it replaces. As a result, it provides fewer backward-compatible headers (for example, "template.h" versus <template>). Also, it does not include some STL extensions provided by the SGI library.
Example 2-3 Namespace Information
The standard used in the past:

#include <map.h> map<const int, int*, int*>::iterator pPtrIt;
becomes:
#include <map> std::map<int, int*, int *>::iterator pPtrIt;
For more information, see your platform getting started.
20
2 Changes in the VxWorks Environment 2.5 Accommodating New Features Introduced in VxWorks 6.0
The instructions for using the Dinkum STL with the Wind River Compiler are in the Wind River Compiler Users Guide. To use the Dinkum embedded STL with the GNU compiler:
Add -fno-exceptions -fno-rtti to your compiler line to disable exceptions. Modify installDir/gnu/3.3.2-vxworks62/x86-win32/include/c++/3.3.2/yvals.h. Change the macro to #define __CONFIGURE_EXCEPTIONS 0.
There is no strict standard for the embedded STL, so there is no guarantee that what was included in the SGI embedded STL (no exceptions version) is the same as the Dinkum Embedded STL. For more information, see the Dinkumware documentation.
2.4.5 Stricter Syntax

Both the Wind River Compiler and the GNU compiler are stricter about syntax. For more information. see Compiler Warning and Error Levels, p.16 and your product getting started.
Because both compilers are stricter about C++ syntax in particular, you must add "struct" in front of C++ "enum" where the compiler asks for it. Multiline _asm("") macros now require a backslash '\' continuation character at the end of the continued line. String literals " " spanning two lines are not allowed; use separate pairs of quotes on each line. The Dinkum STL has no assumed size for an enum type in a C++ class; unfortunately GNU 3.3 does not auto-convert enum types to the presumed width, so a cast is necessary in order to compile.
2.5 Accommodating New Features Introduced in VxWorks 6.0

The new features discussed here affect using VxWorks 6.x with applications.
21
2.5.1 Including New Features

Some new features require only selecting the feature in the Workbench kernel configurator or using vxprj, for example:
INCLUDE_RTP INCLUDE_EDR_XXX
However, some new features require modifications to the BSP before they can be provided to applications. For more information, see 3. Porting a BSP to VxWorks 6.2.
2.5.2 Changed Memory Mapping

Without RTP support, the kernel heap is assigned the RAM located between the end of the kernel code and sysMemTop( ), as was the case with VxWorks 5.5. However, when compiling with support for error detection and reporting, additional RAM is reserved for the persistent error log. This RAM comes from the region of memory located between sysMemTop( ) and sysPhysMemTop( ). This means that less memory is assigned to the kernel heap when the persistent error log is included in the configuration. (For more details, see Error Detection and Reporting Requires Reserved Memory, p.23.) When RTP support is included, not all of the RAM located between the end of the kernel code and sysMemTop( ) is assigned to the kernel heap and mapped initially. Instead, the kernel heap is given a configurable amount of memory. Its size is specified using the configuration parameter KERNEL_HEAP_SIZE. The RAM located between the end of the kernel heap and sysMemTop( ) is left unmapped initially, and is mapped on demand for RTPs, shared libraries, or shared data regions. By default, KERNEL_HEAP_SIZE is set to two-thirds of the memory located between the end of the kernel code and sysMemTop( ). The value of this parameter must be modified to partition the RAM between the kernel heap and user space, according to the needs of the system. For more information about memory maps with or without RTP support and for detailed information about memory management, see the VxWorks Kernel Programmers Guide: Memory Management.
22
Driver Access to User-mode Memory
If a driver is called as a result of a system call, it has access to the calling RTP memory space for the duration of the system call. Once the call completes, the driver loses access to the RTP memory space.
Protected Real-time Process Requires MMU
While real-time processes (RTPs) are designed to take advantage of processor MMUs, you can configure and run applications in RTPs without an MMU if your processor supports it. However, to take advantage of memory protection, an MMU is required. For more information on processes without MMU support, see the VxWorks Kernel Programmers Guide: Memory Management.
Error Detection and Reporting Requires Reserved Memory
The error detection and reporting features of VxWorks 6.x provide infrastructure for detecting and managing errors. The old system of allowing users to insert custom exception handlers has not been deprecated; however, error detection and reporting can save you from having to write your own infrastructure. To make use of error detection and reporting, add the following components or include BUNDLE_EDR using the project facility (either in Workbench or from the command line):
INCLUDE_EDR_ERRLOG INCLUDE_EDR_PM INCLUDE_EDR_SHOW INCLUDE_EDR_SYSDBG_FLAG INCLUDE_EDR_SHELL_COMMAND
/* if the shell is included */ /* allows control of how RTPs fail */ /* not included in bundle */
To increase the size of the error log, set the PM_RESERVED_MEM parameter to a larger value. (PM_RESERVED_MEM must be a multiple of the page size.) The default is six pages of memory. Modify the sysMemTop( ) routine of sysLib.c as shown:
char * sysMemTop (void) { static char * memTop = NULL; if (memTop == NULL) { memTop = sysPhysMemTop () - USER_RESERVED_MEM;
23
#ifdef INCLUDE_EDR_PM /* account for ED&R persistent memory */ memTop = memTop - PM_RESERVED_MEM; #endif ... } return (memTop); }
For more information about the relationship between PM_RESERVED_MEM, USER_RESERVED_MEM, and the heap, see the VxWorks Kernel Programmers Guide: Memory Management. The component INCLUDE_EDR_SYSDBG_FLAG should be included if you wish to control whether failing RTPs are deleted or suspended. A flag value of 0x400 in the boot line causes failing RTPs to be suspended. The default flag value is 0x000, which means that failing RTPs are deleted.
2.5.3 Boot Loaders

Boot loaders created with VxWorks 5.5 and with VxWorks AE (any release) are compatible with VxWorks 6.x in kernel mode. This means:
You can use your VxWorks 5.5 or AE boot loaders with kernel-mode applications that use only 5.5-compatible facilities. Your boot loader must have a 160-byte image path to be fully compatible. You can use your custom boot loader that worked with VxWorks 5.5 and AE. Images supporting error detection and reporting can be loaded using an old boot loader, with some limits in functionality. In particular, preservation of the error log across a reboot requires a new boot loader. We recommend that you use a VxWorks 6.x boot loader to support RTPs and other new functionality. Check your architecture supplement for any further architecture-specific restrictions.
24
2.5.4 RTP Startup Facility

Starting an RTP requires the RTP startup facility, which consists of a set of components that automatically launch one or more RTPs after the VxWorks kernel boots up. The list of RTPs to launch and the method of launching them are selected by specifying the appropriate components. The list of RTPs to be launched is not compiled into the VxWorks image, but is specified outside the build system. RTPs are launched after all other kernel facilities have finished initializing themselves, and after any user-defined kernel applications are launched (in other words, after USER_APPL_INIT). Thus launching RTPs is the final activity performed by tRootTask before it terminates. The following components are available to specify launching methods:
INCLUDE_RTP_APPL_USER 2
includes an empty function called usrRtpAppInit( ). You can add your own code to this function. Applications must be spawned by calling rtpSpawn( ).
INCLUDE_RTP_APPL_INIT_STRING
takes a string argument, where the string encodes a list of RTPs to launch. You must set the parameter RTP_APPL_INIT_STRING to the string containing all RTPs to launch.
INCLUDE_RTP_APPL_INIT_BOOTLINE
takes the list of RTPs from the startup-script field of the boot line. This field of the bootline is a string encoded in a similar format to the one used by INCLUDE_RTP_APPL_INIT_STRING.
INCLUDE_RTP_APPL_INIT_CMD_SHELL_SCRIPT
takes the name of a command shell script file as an argument, and executes it. This script may do anything the shell is capable of doing, including launching RTPs. The parameter RTP_APPL_INIT_STRING must be set to the name and path of the shell script to execute. For more information on the RTP startup facility, see the VxWorks Application Programmers Guide.
2.5.5 Wind River System Viewer

New VxWorks 6.x features have resulted in some new System Viewer events. Table 2-2 shows the libraries and functions affected.
25
Table 2-2
New System Viewer Events
Library
Feature
rtpLib system call interface edrLib isrLib sdLib USB stack IPv6 dual network stack
instrumentation of RTP creation and deletion instrumentation of system calls, selectable per RTP, with decoding of parameters instrumentation of writes to the error log ISR object creation and deletion, also ISR handler invocation instrumentation of creation and deletion of shared data regions instrumentation of host and peripheral USB stack updated instrumentation of the network stack
2.5.6 Power Management

Power management allows the processor to conserve power by entering a low-power mode. While in this mode, processor register values and memory contents are retained. Power management requires special hardware support, which not all core chips provide.
To find out if a specific core has power management support, see the Interface Variations section of the appropriate architecture supplement. To see if special timer support to extend the system timer interrupt for multiple ticks is required, see the VxWorks driver API reference entries.
2.5.7 RTPs Replace VxVMI

In VxWorks 5.x, VxVMI provided a form of MMU protection. In VxWorks 6.x, this protection is provided by real-time processes (RTPs). For information on migrating from VxVMI to VxWorks 6.2, see 4.11.2 Migrating From VxVMI To RTPs, p.99.
26
2 Changes in the VxWorks Environment 2.6 Changes Introduced in VxWorks 6.1
2.5.8 Message Channels Replace VxFusion

VxFusion is not included in this release. Wind River advises customers who have relied on these facilities to migrate their applications to message channels, which provides superior functionality. For information about message channels, see the VxWorks Application Programmers Guide: Multitasking or the VxWorks Kernel Programmers Guide: Multitasking.
2
2.5.9 Networking Changes

There are a number of changes in the network stack. This document does not cover these changes in detail. The changes include:
The network stack became an IPv4/IPv6 dual stack in VxWorks 6.x. Some component names have changed from what they were in the previous version of the stack. Network header files have changed.
For more information, see 4.6 Networking Changes, p.81, the Wind River Network Stack for VxWorks 6 Programmers Guide or your product getting started.
2.6 Changes Introduced in VxWorks 6.1

This section highlights specific changes between VxWorks 6.0 and VxWorks 6.1. The changes only affect users who have migrated to VxWorks 6.0 already as they were primarily designed to increase backward compatibility and simplify migration.
2.6.1 Loader Changes

Certain changes introduced in VxWorks 6.0 reverted to their VxWorks 5.5 values in VxWorks 6.1, in order to provide as much backward compatibility with VxWorks 5.5 as possible.
27
The following section-oriented APIs were added in VxWorks 6.0 but were removed for VxWorks 6.1. They are not useful because, from a user point of view, the loader is still segment-oriented and not section-oriented.
Table 2-3
Loader Routines Present in VxWorks 6.0 and Not In VxWorks 6.1 or 6.2
Routine Name
Routine Description
moduleSectionDescGet( ) get the first section from a module moduleSectionDescFree( ) free a section descriptor moduleFirstSectionGet( ) find the first section in a module
moduleNextSectionGet( ) find the next section in a module
In addition, the new errno, S_moduleLib_INVALID_MODULE_ID, is now correctly set when a module ID is invalid, instead of the VxWorks 6.0 value, S_moduleLib_INVALID_CODE_MODULE_ID. All but one of the loader-related errnos that were changed in VxWorks 6.0 have reverted to the same values they had in VxWorks 5.5. While some of the VxWorks 6.0 values provided more information than the VxWorks 5.5 versions, consistency and simplicity of migration were more important. S_loadLib_UNSUPPORTED_RELOCATION_TYPE becomes S_loadElfLib_UNSUPPORTED S_loadLib_UNKNOWN_RELOCATION_TYPE becomes S_loadElfLib_UNRECOGNIZED_RELOCENTRY S_loadLib_INVALID_RELOCATION_VALUE becomes S_loadElfLib_RELOC S_loadLib_WRONG_OBJ_MODULE_ARCH becomes S_loadElfLib_HDR_READ S_loadLib_UNSUPPORTED_RELOC_ENTRY_FMT becomes S_loadElfLib_RELA_SECTION S_loadLib_UNSUPPORTED_RELOC_ENTRY_FMT becomes S_loadElfLib_RELOC
The one errno that has retained its VxWorks 6.0 value is set when there is a relocation overflow: S_loadElfLib_RELOCATION_OFFSET_TOO_LARGE. The VxWorks 5.5 errno, S_loadElfLib_RELOC, is still set for other relocation error cases as before.
28
Finally, the VxWorks 5.5 errno S_loadElfLib_READ_SECTIONS, is correctly set when there is a problem reading a relocation, and the VxWorks 5.5 errno S_loadElfLib_SHDR_READ is correctly set when there is a problem reading a section header. Neither of these was set in VxWorks 6.0.
2.6.2 Task Stack Overrun and Underrun

Guard zones are inserted at the start and end of each task execution stack, when VxWorks is configured with the INCLUDE_PROTECT_TASK_STACK component (new in VxWorks 6.0). The size of the guard zones was defined in VxWorks 6.0 by the following configuration parameters:

TASK_STACK_OVERFLOW_SIZE TASK_STACK_UNDERFLOW_SIZE
These parameters applied to task stacks in the kernel and in RTPs, as well as to exception stacks. In VxWorks 6.1, these two parameters were replaced by the following five parameters:
TASK_USER_EXEC_STACK_OVERFLOW_SIZE
user task execution stack overflow size

TASK_USER_EXEC_STACK_UNDERFLOW_SIZE
user task execution stack underflow size

TASK_USER_EXC_STACK_OVERFLOW_SIZE
user task exception stack overflow size

TASK_KERNEL_EXEC_STACK_OVERFLOW_SIZE
kernel task execution stack overflow size

TASK_KERNEL_EXEC_STACK_UNDERFLOW_SIZE
kernel task execution stack underflow size If you used the default values for VxWorks 6.0, those values work unchanged for VxWorks 6.1. If you changed the defaults, you must make the same changes for VxWorks 6.1. !
CAUTION: The TCB has always been private; if you are accessing it, your code may
no longer work correctly. You should always access the stack through public APIs.
29
For general information about kernel task stacks, see the VxWorks Kernel Programmers Guide: Multitasking, and for information on process task stacks, see the VxWorks Application Programmers Guide: Multitasking.
2.6.3 File Descriptors Inheritance

In VxWorks 6.0 an RTP created by a kernel task, such as the kernel shell, inherited the file descriptors available to this task. Since all kernel tasks share the file descriptor table for the kernel, this resulted in a breach in the isolation between user space and kernel space. This introduced the risk of corrupting data streams used by kernel tasks in the case where code in the RTP inadvertently made use of one of the open kernel file descriptors. This error was very difficult to debug. In VxWorks 6.1, an RTP created by a kernel task inherits only the task's stdin, stdout, and stderr file descriptors (0, 1 and 2). No change has been made for the situation where a RTP creates another RTP. In this case the child RTP still inherits all the file descriptors of its parent RTP.
2.6.4 RTP Initial Task Names

In VxWorks 6.0 the name of the initial task for an RTP was tInitTask. For VxWorks 6.1, the name of an RTPs initial task is based on the name of the executable file: the letter i is prefixed, the first letter of the filename capitalized, and the file-name extension removed. For example, when foobar.vxe is run, the name of the initial task is iFoobar.
2.6.5 Multiple Sessions of the Kernel Shell

It is possible to have several kernel shell sessions running at the same time on different terminals (such as the console, VIO, telnet, rlogin, and so on). Each session has a different environment (user ID, current path, prompt) and does not affect the global standard I/O. The initial shell script is launched on a different shell session from the initial kernel shell session on the console. A side effect is that when shellPromptSet( ) is called in the shell script, the scope is limited to the script shell session and does not affect the prompt of other sessions. The default prompt can be changed with shellPromptFmtDftSet( ).
30
To restore VxWorks 5.5 behavior, set the shell component parameter SHELL_COMPATIBLE to TRUE when creating the project.
2
2.6.6 unld( ) and reld( ) Available In Shell Only

The unld( ) and reld( ) routines have been moved from the file unldLib.c to usrLib.c. To include these routines in your image, use the component INCLUDE_SHELL. These routines were deprecated in VxWorks 5.5 and can no longer be called directly from programs; they are now for use from the shell only. For unloading from within a program, use either unldByModuleId( ) or unldByNameAndPath( ). For reloading from within a program, you must first unload the module (using unldByModuleId( ) or unldByNameAndPath( )) and then load it again using one of the load routines: loadModule( ) or loadModuleAt( ).
2.6.7 ISR Objects

Interrupt service routines (ISRs) are now objects rather than data structures (ISRs were represented in VxWorks 5.5 as data structures). This means that resource reclamation is possible, as well as instrumenting objects and similar object manipulation.
2.6.8 Object Ownership Tracking

Object ownership tracking is a component of the object management feature. This component was configured in the default VxWorks 6.1 image, and is required in a system configured with RTP support. However, in VxWorks 6.2 it was removed from the default kernel configuration by removing INCLUDE_OBJ_OWNERSHIP, creating a system whose object ownership and resource reclamation overhead is similar to VxWorks 5.5. For more information, see the Multitasking chapter of either the application or kernel programmers guide.
2.6.9 Resource Reclamation

The introduction of resource reclamation should have minimal impact on drivers and BSPs. Objects in the kernel such as semaphores, message queues, and tasks are
31
owned by the RTP that created the object. Typically if a driver or a BSP creates objects, it is during the kernel initialization phase, which occurs in the context of the kernel. Thus, there should be no concern that an object can be unexpectedly deleted, since the kernel is never deleted. Resource reclamation could be an issue for any kernel routine that is executed as a result of a user task performing a system call. Any objects that are created are owned by the calling RTP, and are deleted when the RTP terminates. If any subsystem creates objects that must survive after the creating RTP terminates, then the objOwnerSet( ) routine should be used to assign the object to the kernel, or to some other RTP that persists after the creating RTP terminates. Resource reclamation is also an issue for kernel task create hooks. For most scenarios, a task create hook routine need not worry about the ownership of objects. The only case that presents a problem is when an RTP (for example, applA running in RTP A) performs an rtpSpawn( ). The rtpSpawn( ) system call creates an initial task (iApplA) in the newly created RTP. However, the taskSpawn( ) of the iApplA occurs in the context of RTP A; thus the task create hooks also execute in the context of RTP A. Any objects created in a task create hook for the iApplA are owned by RTP A. Thus if RTP A terminates, the objects are unexpectedly deleted. The reference entry for the kernel version of taskCreateHookAdd( ) recommends using objOwnerSet( ) to set ownership of newly created objects to the new RTP. The same issue exists for RTP post-create hooks. The reference entry for rtpPostCreateHook( ) also recommends using objOwnerSet( ) to set ownership of newly created objects to the new RTP.
2.6.10 Driver Changes

!
WARNING: The main change regarding drivers introduced in VxWorks 6.1 is the
discontinuation of BSD-style drivers. Otherwise, drivers are source compatible. Also, in the reference entries, drivers have now been moved to their own directory.
Drivers Source Compatible Only
VxWorks 5.5 drivers are not binary compatible with VxWorks 6.x drivers. You must install your driver source and recompile the drivers.
32
No BSD-Style Drivers
BSD-style drivers are no longer supported. Any BSD-style driver that was used with VxWorks 5.5 must be upgraded to an END-style driver to work with VxWorks 6.x.
Modified smEnd
In VxWorks 6.1 the shared memory networking driver smEnd has been upgraded from the BSD-style driver (if_sm.c in VxWorks 5.5) to an END-style driver (smEnd.c in VxWorks 6.x). For more information on the new driver, see the reference entry and Modified smEnd, p.83.
2.6.11 Task Self-destruction

Task self-destruction occurs when the entry point function specified to taskSpawn( ) returns or when a task performs one of the following functions:
taskDelete (0); taskDelete (taskIdSelf ()); exit();
In VxWorks 5.5, a task self-destruct was handled by the exception task (tExcTask) if it existed. In other words, if the INCLUDE_EXC_TASK component was configured into the VxWorks image, the taskDelete( ) function referred the self destruction to the tExcTask. If the tExcTask task did not exist, taskDelete( ) performed the self destruction in the context of the task itself. In order to support the task in destroying itself without a helper task, certain non-standard memory management techniques were introduced. In VxWorks 6.1 a memory partition and heap instrumentation library was introduced (INCLUDE_MEM_EDR) to help detect common programming errors such as double-freeing an allocated block, freeing or reallocating an invalid pointer, writing into freed buffers, memory leaks, and so forth. In this new context, task self-destruction as practiced in VxWorks 5.5 results in false alarms from the memory partition and heap instrumentation library. For these reasons, in VxWorks 6.1, task self-destruction without a helper task is no longer supported. In addition, tExcTask no longer supports task self-destruction. Instead, a new task named tJobTask is used; it executes at the priority of the task performing one of the self-destruct functions. To include support for task
33
self-destruction, the INCLUDE_JOB_TASK component must be configured into the kernel; it is included by default. If the INCLUDE_JOB_TASK component is not included in the kernel, any task that attempts to self-destruct will be left in a suspended state. The task can then be deleted by another task using taskDelete( ). An important consequence of this change is that the root task (tRootTask) self-destructs once it has completed initializing the kernel and applications. Thus, without the INCLUDE_JOB_TASK component included, the tRootTask remains in a suspended state. An application task that is spawned by USR_APPL_INIT (BSPs) or usrAppInit( ) (projects) is required to explicitly delete the root task:
rootTid = taskNameToId ("tRootTask"); if (rootTid != ERROR) taskDelete (rootTid);
2.6.12 Stricter Error Checking on Semaphores

The semaphore create routines for all types of semaphores, for example semBCreate( ), have been updated to perform stricter error checking on the options passed to the routine. In VxWorks 5.x, reserved bits were not checked. For VxWorks 6.x, all options passed are checked against allowed options. Thus code that worked in the past may have passed disallowed options; now, such code generates the errno S_semLib_INVALID_OPTION.
2.6.13 Message Channel API

Several changes occurred to the SAL/SNS interface.
sockOpt Structure Changed
The salCreate( ) command used the sockopt structure for one of its parameters; this has been changed to salSockopt as follows:
struct salSockopt { int so_level; int so_name; void * so_value; int so_length; }; /* socket option structure */ /* /* /* /* option option ptr to option level */ name */ option value */ length */
34
The change is necessary due to a name clash for the sockopt structure between networking code and SAL code. Since the SAL code is used by both kernel-based and RTP-based applications, while the networking structure is only visible in kernel applications, using the same version was not possible. The new structure is located in installDir/vxworks-6.x/target/h/dsi/salCommon.h.
backlog Parameter Added
The backlog parameter for the SNS server listen sockets was previously hardcoded to 5. With a heavy volume of registration, this can fill up quickly if the tasks doing the requests are of high priority; this would cause further requests to be rejected. The parameter is now a configurable item. The parameter appears under the selections for the Socket Name Service found in the Kernel Configurator selections below:

Network Components Distributed Systems Infrastructure Socket Application Library Components Socket Name Service server (Kernel or RTP) Socket Name Service in RTP Socket Name Service in Kernel Distributed Socket Name Service in RTP Distributed Socket Name Service in Kernel
The parameter name is SNS_LISTEN_BACKLOG. The option to configure the backlog did not exist in VxWorks 6.0.
2.7 Changes Introduced in VxWorks 6.2

2.7.1 File System Changes
Three new file system features are implemented in VxWorks 6.2: true removability support, support for multiple file systems, and the Highly Reliable File System (HRFS). These new features have had a significant impact on the design and
35
implementation of file systems in general, and have changed the principles by which VxWorks file systems operate. Prior to VxWorks 6.2, file system stacks were created at initialization time, and persisted throughout a particular instance of VxWorks. This operation was based on two assumptions:
Only one type of file system is supported for a particular device. The total number of file systems is known at initialization time.
The introduction of dynamic insertion and removability support and support for multiple file system types violate these two assumptions, requiring a change in this basic operating principle. Highlights of the changes are given below. For specific information on migration requirements, see 4.9 File System Changes, p.86.
Extended Block Device (XBD)
In previous systems, a stack consisting of some number of CBIO modules with a file system component on top of it was created at initialization time. This stack monitored insertion and removal of disks such as floppies or CD-ROMs, mounting and unmounting the file system as disks were inserted and removed. The CBIO stack has been replaced by the extended block device (XBD) which serves many of the purposes of CBIO, but which also provides for insertion and removal as well as safe dynamic creation and deletion.
File System Monitor
When a device insertion is detected, a new component, the file system monitor, automatically detects the file system type of the inserted device and creates a file system stack with the appropriate file system at the top. There is no longer the requirement to explicitly create file systems by invoking a creation function; this is handled by the file system monitor.
Highly Reliable File System
A new, highly reliable file system (HRFS) is available with VxWorks 6.2. For information on migrating from existing file systems, see 4.9 File System Changes, p.86.
36
Discontinued Features dosFs 1.0 Support 2
dosFs 1.0 is no longer supported in this release. For information on migrating from dosFs 1.0 to dosFs 2.0, see 4.9.3 dosFS, p.92.
dosFs Long File Name Support
Wind Rivers proprietary long name support for dosFs is not fully supported in this release. Wind River advises customers to migrate to the Microsoft standard of long names.
tapeFs
The tapeFs file system is no longer supported in this release.
Deprecated Features RAM Disk
The BLK_DEV-based RAM disk is deprecated. The XBD-based RAM disk should be used instead. For more information, see 4.9.1 Extended Block Device (XBD) Support, p.87.
VxWorks CBIO Interface
The VxWorks CBIO interface is replaced by the XBD facility. For information on migrating to XBD, see 4.9.1 Extended Block Device (XBD) Support, p.87.
2.7.2 Expanded POSIX Support

POSIX support for processes (RTPs) has been enhanced to further improve POSIX compliance, in terms of the number of APIs and their behavior, and in terms of header files and their content (types and macros). New routines have been added and existing routines have been modified to be more compliant with the PSE52 profile described by the IEEE 1003.13-2003 standard (also known as POSIX.13). New POSIX header files have been created and some of the existing POSIX header files have been moved to more appropriate locations. Some of these changes are also available in the kernel environment, particularly the new I/O routines and some of the kernel's POSIX thread APIs. The latter have
37
have been slightly modified to be more in line with the changes in the user space API and the POSIX standards. For information on changes to POSIX support in the kernel, see 4.10 Changes in POSIX Support, p.93. For information on changes to POSIX support in RTPs, see 5.4 Enhanced Support for POSIX Applications in VxWorks 6.2, p.121.
2.7.3 Changes To Memory Partition Options

Changes to memory partition options have occurred in both kernel and application space. The changes include new options, deprecated options, and changed defaults. For more information about changes in kernel space, see 4.5.3 Memory Partition Options, p.76. For more information about changes in application space, see 5.5 Changed Memory Partition Options in VxWorks 6.2, p.137.
2.7.4 Scalability
In VxWorks 6.2, scalability profiles allow you to build a preconfigured VxWorks system from source with scaled down functionality and reduced memory footprint from the default system. For more information on this new feature, see the VxWorks Kernel Programmers Guide: Kernel. For information on modifying a BSP to utilize scalability profiles, see your release notes.
2.7.5 VxBus
VxWorks 6.2 introduces a new bus and device model. For information about porting your BSP to VxBus, see B. Migrating to the New VxBus.
2.8 Determining If a BSP Requires Migration

The Wind River BSPs included in VxWorks 6.2 have been appropriately modified to support VxWorks 6.2. You may study those BSPs to see what changes may be necessary to yours. A few changes (such as the need to recompile) affect you even if you choose not to use new VxWorks 6.2 capabilities. Other changes need only concern you when you incorporate the new functionality.
38
2 Changes in the VxWorks Environment 2.8 Determining If a BSP Requires Migration
This checklist highlights the areas that you may have customized in your BSP; the steps you must take if you have done so are detailed in 3. Porting a BSP to VxWorks 6.2. That chapter also provides a migration example. 1. Is your architecture supported? See your product release notes for a complete list of supported architectures. 2. Is your host supported, and is your preferred compiler supported on that host? See your product release notes for a complete list of supported hosts and compilers. 3. Does your architecture have MMU support for RTPs? VxWorks 6.x can run effectively on CPUs with or without an MMU, and you can use the RTP functionality both with and without the MMU. But RTP memory protection is available only when an MMU is available; without the MMU, processes can be set up but their memory boundaries are not enforceable. In addition, not all CPUs support processes in configurations without an MMU. For more information, see the appropriate VxWorks architecture supplement. 4. Does the BSP use any VxVMI (vmLib) functions? The functionality provided in VxWorks 6.x by RTPs (with an MMU present) supersedes that of VxVMI. Therefore, VxVMI is obsolete in VxWorks 6.x. Migrate the functionality to the RTP model. This may involve redesign; see 2.5.7 RTPs Replace VxVMI, p.26. 5. ! Is your BSP based on VxWorks 5.5?
WARNING: If your BSP is based on a release older than VxWorks 5.5, you must first migrate your BSP to VxWorks 5.5. For instructions on migrating a BSP to VxWorks 5.5, see the Tornado Migration Guide, 2.2.
6.
Do you have existing VxWorks 5.5-based code that must be migrated? For example, if you use bundled PPP, this product is replaced by Wind River PPP in VxWorks 6.2. See the PPP chapter in your product getting started.
7.
Does your BSP include or link with any 3rd party binary libraries or objects? Any binary objects provided by customers or 3rd parties must be recompiled to be compatible with VxWorks 6.2 data structures and headers.
8.
Does the BSP contain modified versions of any standard files from the installDirTornado/target/config/all directory? If you have modified any of the
39
standard BSP files, then you must migrate those changes to the latest versions of those files. 9. Does the BSP contain modified versions of any standard configlette files from the installDirTornado/target/src/config or installDirTornado/target/config/comps/src directories? If you have modified any of the standard configlette files, then you must migrate those changes to the latest versions of those files. Does the BSP try to patch any architecture code through means other than a published hook or call-out function? Does the BSP have customized make targets or rules?
10. 11.
For more information on how to migrate your BSP, see 3. Porting a BSP to VxWorks 6.2.
2.9 Architecture-Specific Issues

Architecture-specific migration issues, as well as all other architecture-specific issues, are covered in the individual architecture supplements. Architecture-specific concerns include: PowerPC:
PHYS_ADDR is now an unsigned long long type.
PPC603 now uses a two-level translation table instead of a hash table. (The PPC604 family still uses both a hash table and translation tables.) Pentium Cacheability and type of cacheability are now treated as one entity; thus VM_STATE_WBACK and VM_STATE_WBACK_NOT cannot be combined with VM_STATE_CACHEABLE or VM_STATE_CACHEABLE_NOT. MIPS
PHYS_ADDR is now an unsigned long long type.
ARM Boot offsets must move in order to support kernel hardening. By default, BSPs are built with T2_BOOTROM_COMPATIBILITY. To enable kernel hardening, define INCLUDE_KERNEL_HARDENING and undefine
40
2 Changes in the VxWorks Environment 2.9 Architecture-Specific Issues
T2_BOOTROM_COMPATIBILITY. For additional information, see the
architecture supplement. XScale Boot offsets must move in order to support kernel hardening. By default, BSPs are built with T2_BOOTROM_COMPATIBILITY. To enable kernel hardening, define INCLUDE_KERNEL_HARDENING and undefine T2_BOOTROM_COMPATIBILITY. For additional information, see the architecture supplement.
2
41
42
3
Porting a BSP to VxWorks 6.2
3.1 Introduction 43 3.2 Features Supported 44 3.3 Porting a BSP to VxWorks 6.2 44 3.4 Booting a VxWorks 5.5 BSP 55
3.1 Introduction
The goal of this chapter is to provide an example to follow when converting a VxWorks 5.5 BSP to VxWorks 6.2. The Wind River BSPs shipped with VxWorks 6.2 have been migrated and are available for reference, as are the template BSPs. The example discusses incorporating support for error detection and recording and for real time processes (RTPs). For information on modifying a BSP to utilize scalability profiles, see your release notes. VxWorks 6.0 and 6.1 BSPs are compatible with VxWorks 6.2. For a complete discussion of BSPs, see the VxWorks BSP Developers Guide.
43
3.2 Features Supported

The major new VxWorks 6.x features that need to be supported by each BSP are:

memory protection error detection and reporting (which requires persistent memory)
For more information, see 2.5.2 Changed Memory Mapping, p.22.
3.3 Porting a BSP to VxWorks 6.2

These steps explain how to port a BSP to be compatible with VxWorks 6.2.
NOTE: These steps are cumulative. If you follow them in order, each step will work
properly when you attempt it.

Step 1: Back up Your BSP.
Copy your BSP to the new directory structure.

Step 2: Establish Your Environment
If you are using Workbench, this is automatic. From the command line, start wrenv as described in torVars Replaced, p.17.
Step 3: Modify Local Copies of Files From target/config/all
If your BSP contains modified versions of any standard files from the installDir/vxworks-6.2/target/config/all directory, then the corresponding files provided for VxWorks 6.2 must be patched with your changes. Make a local copy in your BSP directory of the common file before patching it. Use the filename build macro in Makefile under your BSP. !
WARNING: This procedure may not work, depending on what you have
modified and how you have modified it. Many of the standard files have been extensively modified for VxWorks 6.x, so it may not be obvious how to reapply the changes. You should expect the effort to modify the files again to be equivalent to the effort required to make the modifications to the previous version of the standard file.
44
3 Porting a BSP to VxWorks 6.2 3.3 Porting a BSP to VxWorks 6.2
Step 4:
Modify Configlettes
If your BSP contains modified versions of any standard configlette files from the target/src/config or target/config/comps/src directories, the modifications must be re-applied to the VxWorks 6.2 versions of the configlette files and put in the BSP. Do not expect to copy the working VxWorks 5.5 or 5.5.1 files, since Wind River has made extensive changes in many configlettes. Follow this procedure:
Copy the files from target/src/config to your BSP directory and link them using MACH_EXTRA, for example:
MACH_EXTRA = usrNetwork.o
Copy the modified file from target/comps/src to your BSP directory. Rename the file. Make modifications to bsp.cdf in your BSP directory to include your file for a component name. Decide on a component name for your changed file. Merge changes in the modified VxWorks 5.5 or 5.5.1 configlettes with the Wind River changes that were applied to VxWorks 6.x. If the merge method chosen requires a common ancestor, the as-shipped files from 5.5 or 5.5.1 (as applicable) can be used for this purpose.
NOTE: Depending on the nature of your changes, some amount of redesign may be needed. It may be easier to reapply your changes to the VxWorks 6.2 files. Step 5: Copy and Link Custom Files
If your BSP tries to patch any architecture code through means other than a published hook or call-out function, copy the architecture custom file to the BSP and link it using MACH_EXTRA.
Step 6: Add Memory Protection
Update your BSP to include MMU support:
In installDir/vxworks-6.2/target/config/all/configAll.h, be sure the default page size (VM_PAGE_SIZE) is appropriate for your architecture. Be sure the function sysPhysMemTop( ) exists in the BSP to return the address of the top of physical memory. sysPhysMemTop( ) is required in order for memory protection to be supported. Most BSPs already contain this function in sysLib.c. Verify that the virtual memory blocks described by the entries in the sysPhysMemDesc[ ] do not overlap.
45
Verify that the memory mappings described by sysPhysMemDesc[ ] and by any architecture-specific mapping mechanism (for example, sysBatDesc[ ] for the PowerPC) leave enough free, unmapped virtual memory space to be used for allocating virtual memory for RTPs. There are no guidelines how much space is needed because that depends on the size and memory heap usage of the RTPs running in the system and on the number of shared data regions being created. If you create no RTPs or shared data regions, this step is optional. Certain architectures, such as SuperH and MIPS, have restrictions about where user-space mappings can be made. Such restrictions must be taken into account when this step is performed. Use adrSpaceShow( ) to verify the size of the free virtual memory that remains after booting.
(Optional) Replace the VM_STATE_xxx macros in sysPhysMemDesc[ ] (located in sysLib.c) with MMU_ATTR_xxx macros as shown in Table 3-1. While the VM_STATE_xxx macros have been mapped to the appropriate MMU_ATTR_xxx macros, it is possible they may be deprecated in future VxWorks releases. For definitions of VM_STATE_xxx and MMU_ATTR_xxx, see the vmLib.h and vmLibCommon.h header files.
Table 3-1
Old and New Memory Protection Macros
VxWorks 5.5 Macros
VxWorks 6.2 Macros
VM_STATE_MASK_VALID VM_STATE_MASK_WRITABLE VM_STATE_MASK_CACHEABLE
MMU_ATTR_VALID_MSK MMU_ATTR_PROT_MSK MMU_ATTR_CACHE_MSK
VM_STATE_MASK_MEM_COHERENCY MMU_ATTR_CACHE_MSK VM_STATE_MASK_GUARDED VM_STATE_VALID VM_STATE_VALID_NOT VM_STATE_WRITABLE VM_STATE_WRITABLE_NOT MMU_ATTR_CACHE_MSK MMU_ATTR_VALID MMU_ATTR_VALID_NOT MMU_ATTR_SUP_RWX (MMU_ATTR_PROT_SUP_READ | MMU_ATTR_PROT_SUP_EXE) MMU_ATTR_CACHE_DEFAULT
VM_STATE_CACHEABLE
46
Table 3-1
Old and New Memory Protection Macros (contd)
VxWorks 5.5 Macros
VxWorks 6.2 Macros
VM_STATE_CACHEABLE_NOT VM_STATE_MEM_COHERENCY VM_STATE_MEM_COHERENCY_NOT VM_STATE_GUARDED VM_STATE_GUARDED_NOT
MMU_ATTR_CACHE_OFF MMU_ATTR_CACHE_COHERENCY
0 (set this macro to 0 for VxWorks 6.2)

MMU_ATTR_CACHE_GUARDED
0 (set this macro to 0 for VxWorks 6.2)
For those architectures where PHYS_ADDR is defined as a 64-bit type, such as PowerPC and MIPS, physical addresses in sysPhysMemDesc[ ] should be changed from 32-bit values to 64-bit values in sysLib.c. This prevents type mismatch warnings when compiling. You may need to change explicit castings in your BSP if they conflict with the new definitions of PHYS_ADDR or VIRT_ADDR. Pentium BSPs Only: In VxWorks 5.5, Pentium MMU support was implemented slightly differently than other architectures with regard to cache states. This is no longer the case in VxWorks 6.x, so Pentium BSPs must change the cache state definitions as follows:
Table 3-2
New Cache State Definitions for Pentium BSPs
VxWorks 5.5 Definition
Required VxWorks 6.x Definition
VM_STATE_MASK_CACHEABLE | VM_STATE_MASK_WBACK VM_STATE_CACHEABLE_NOT | VM_STATE_WBACK_NOT VM_STATE_CACHEABLE | VM_STATE_WBACK
VM_STATE_MASK_CACHEABLE or MMU_ATTR_CACHE_MSK VM_STATE_CACHEABLE_NOT or MMU_ATTR_CACHE_OFF VM_STATE_WBACK or MMU_ATTR_CACHE_COPYBACK
Failure to make these changes results in an error similar to:

invalid combination of MMU attributes for sysPhysMemDesc[] entry
47
Example 3-1
Replacing Cache States in Pentium BSPs
This example shows replacing the cache states in Pentium BSPs while supporting backward compatibility. In config.h:
#ifdef MMU_ATTR_SUP_RO /* VxWorks 6.x settings */ # define VM_STATE_MASK_FOR_ALL \ VM_STATE_MASK_VALID | VM_STATE_MASK_WRITABLE | \ VM_STATE_MASK_CACHEABLE | VM_STATE_MASK_GLOBAL # define VM_STATE_FOR_IO \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_CACHEABLE_NOT | VM_STATE_GLOBAL_NOT # define VM_STATE_FOR_MEM_OS \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_WBACK | VM_STATE_GLOBAL_NOT # define VM_STATE_FOR_MEM_APPLICATION \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_WBACK | VM_STATE_GLOBAL_NOT # define VM_STATE_FOR_PCI \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_CACHEABLE_NOT | VM_STATE_GLOBAL_NOT #else /* VxWorks 5.x settings */ # define VM_STATE_MASK_FOR_ALL \ VM_STATE_MASK_VALID | VM_STATE_MASK_WRITABLE | \ VM_STATE_MASK_CACHEABLE | VM_STATE_MASK_WBACK | \ VM_STATE_MASK_GLOBAL # define VM_STATE_FOR_IO \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_CACHEABLE_NOT | VM_STATE_WBACK_NOT | \ VM_STATE_GLOBAL_NOT # define VM_STATE_FOR_MEM_OS \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_CACHEABLE | VM_STATE_WBACK | VM_STATE_GLOBAL_NOT # define VM_STATE_FOR_MEM_APPLICATION \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_CACHEABLE | VM_STATE_WBACK | VM_STATE_GLOBAL_NOT # define VM_STATE_FOR_PCI \ VM_STATE_VALID | VM_STATE_WRITABLE | \ VM_STATE_CACHEABLE_NOT | VM_STATE_WBACK_NOT | \ VM_STATE_GLOBAL_NOT #endif /* MMU_ATTR_SUP_RO */
Step 7:
Update Your Cache Library APIs
Update your BSP to use the architecture-independent cache library API; replace functions named cacheArch* or cachePpc* with their associated architecture-independent cache functions.
48
Table 3-3
Sample Function Replacements
Architecture-dependent functions
Architecture-independent functions
cacheArchFlush( )
cacheFlush( )
cacheArchInvalidate( ) cacheInvalidate( ) cachePpcEnable( ) cachePpcDisable( )

Step 8:
cacheEnable( ) cacheDisable( )
Add Error Detection and Reporting Support
Make the changes required to support the startType argument that specifies the system boot type (cold, warm). In sysALib.s, integer startType is passed in by boot code as an argument to _sysInit and passed through as an argument to usrInit( ). The normal procedure is to save the startType value in a register during execution of sysInit( ), and then pass it to usrInit( ) using the normal subroutine passing conventions for the architecture. The following sample code saves startType in r7. You should verify that the register is not used for anything else in your BSP between saving startType and calling usrInit( ). The following example is for PowerPC.
FUNC_BEGIN(_sysInit) ..... /* save startType */ mr r7,r3 ..... /* jump to usrInit with arg indicating type of boot (startType) */ mr r3, r7 b usrInit /* never returns - starts up kernel */ FUNC_END(_sysInit)
Pre-VxWorks 6.0 boot loader images do not fully support VxWorks 6.x images that include error detection and reporting since they do not pass startType to _sysInit. By default, pre-VxWorks 6.0 images always set the startType value to warm boot.
RAM-based VxWorks images downloaded through an emulator and executed directly from RAM require that startType be set manually using the debug tools, since it is not passed in from boot code.
49
Make the changes required to support persistent memory Persistent memory begins after USER_RESERVED_MEM at (sysPhysMemTop( ) - PM_RESERVED_MEM). The size is determined by PM_RESERVED_MEM, which has a default value in configAll.h of 12 KB (0x3000). Change the sysMemTop( ) function in sysLib.c to account for the persistent memory area; for example:
char * sysMemTop ( void ) { static char * memTop = NULL; if (memTop == NULL) { memTop = sysPhysMemTop () - USER_RESERVED_MEM; #ifdef INCLUDE_EDR_PM /* account for ED&R persistent memory */ memTop = memTop - PM_RESERVED_MEM; #endif } return memTop ; }
Step 9:
Update Custom Make Rules
Make sure the custom rules are in Makefile under the BSP, and that they are documented in the target.ref file. These cases require case-by-case evaluation. For more information, see 2.3.5 Migrating Custom BSP Makefiles, p.18.
Step 10: Build and Address Compiler Warnings
Wind River has increased the level of compiler warning and error checking in Wind Rivers BSP makefiles. This results in higher quality BSPs; some BSPs which compiled silently under the VxWorks 5.5 and 5.5.1 makefiles no longer compile without errors or warnings in VxWorks 6.x until the code is modified. You may wish to increase the level of checking in your BSP makefiles and consider rewriting your code if necessary (recommended) or you may choose to reduce the level of checking. For information on how to do this, see the documentation for your compiler.
50
Compiler Error and Warning Levels
With VxWorks 6.x, there are three new warning levels, in addition to the obsolete (but still present) CC_WARNINGS_NONE and CC_WARNINGS_ALL. The new warning level settings are:

CC_WARNINGS_LOW CC_WARNINGS_MED CC_WARNINGS_HIGH
The default for library builds is now CC_WARNINGS_LOW. The default for BSP and application builds is now CC_WARNINGS_MED. The CC_WARNINGS_HIGH level is provided for the purpose of detailed code inspections. The warning level setting can be changed from the command-line make by following this example (Bash shell on Solaris:
% make CPU=PPC32 TOOL=diab CC_WARNINGS=$(CC_WARNINGS_HIGH)
Example Problems and Solutions
Signed/Unsigned Value Mismatch A signed constant or variable may be assigned to an unsigned variable. Re-defining the variables value (for example, -1 to 0xFFFFFFFF) or using a more suitable typedef may fix this problem.
Condition Always True/False The use of a constant as the expression in a condition such as while (TRUE) may be replaced with for (;;).
Step 11:
Version Number Change
In config.h, update the BSP version to match the operating system version and increment the BSP revision.
Example:
#define BSP_VERSION #define BSP_REV "2.0" "/4" <- increased by 1
In the README, add release notes for the VxWorks 6.2 version.
Example:
RELEASE 2.0/4 Released by Wind River for VxWorks 6.2.
51
Step 12:
Ethernet MAC Address "N" to "M" Boot Loader Command Migration
In providing boot loader support that works easily, it helps if a BSP is modified to use the M interface to Mac addresses. There were a number of problems with the N command. These related to multiple interfaces and to lack of definition of the byte order of the data. The original N command did not provide a mechanism for the user to set the MAC address of any interface except the one designated at BSP creation time. Although some workarounds exist in some BSPs, they are neither consistently applied, well documented, nor obvious to use. In addition, the design of the N command did not define the order of bytes within the MAC address for various functions. This means that on some architectures and configurations, the MAC address would be reversed from the intended order, or other odd behavior would result. The design of the M command defines the byte order for the MAC address at every level in order to eliminate confusion of the MAC address at BSP development time. It also requires the use of a mechanism to allow multiple interfaces to be handled without special consideration. Wind River recommends that you keep code supporting the N command for backward compatibility, unless code size or other considerations forbid it. However, where problems occur, the new M command is available in addition. To provide the option of the M command for a BSP, do the following:
From the console, identify whether or not the BSP supports the N command. Check to see whether ETHERNET_ADR_SET is defined in config.h in the BSP directory. If so, support for M command needs to be added. Keep code supporting the N command for backward compatibility.
This list provides a synopsis of the procedure for adding M support: Replace ETHERNET_ADR_SET with ETHERNET_MAC_HANDLER in config.h. Replace sysEnetAddrGet( ) with sysNetMacNVRamAddrGet( ) in sys{IF}End.c. Modify sysNet.c or sysLib.c to add the routines sysNetMacNVRamAddrGet( ), sysNetMacAddrGet( ), and sysNetMacAddrSet( ) to sysNet.c or sysLib.c, depending on which file currently contains sysEnetAddrGet( ).
52
For examples of these changes, see the appropriate files in the wrSbc8260Atm and wrSbcPowerQuiccII BSPs.
Step 13: BSP Documentation Conversion 3
Many providers of BSPs want to provide documentation similar to that provided by Wind River BSPs. For this reason, the tools that Wind River uses internally to generate BSP documentation are provided. For VxWorks 6.x, the tool that generates reference documentation is a Perl script, apigen. apigen uses a simpler syntax than the previous nroff-based markup (found particularly in target.nr files). apigen and other documentation tools are located in installDir/vxworks-6.2/host/resource/doctools.
Convert target.nr
Start by editing the target-specific documentation file to generate clean output using apigen.
If you have a target.nr file, convert it to a target.ref using the mg2ref tool.
% mg2ref target.nr
If you already have a target.ref, proceed to the next step.
Edit target.ref to correct any markup errors. This effort can be minimal to major depending on the compliance of the original file to the Wind River Coding Conventions. Your goal is to eliminate warning and error messages generated by apigen. Change the name in the first line to target.ref. Align all table columns and diagrammatic representations if they were not already aligned. Any blank characters at the beginning of a line cause the line to be unformatted or document generation to fail. Eliminate all remaining nroff formatting; for a table of correspondences, see C. Conversion to apigen. In particular, remove any remaining nroff formatting at the beginning of tables; it is no longer required or allowed. Check words with underscore. apigen automatically bolds every word with an underscore. It may or may not be appropriate. Correct grammar and spelling. Edit content for completeness.
53
Run apigen manually to create the bsp.html. Edit the target.ref until the bsp.html is releasable.
% apigen target.ref
Convert Other BSP Documentation
Convert other BSP API documentation, such as sysLib.c.
Follow the same procedure on your remaining files as you did for target.nr. Test your conversion by running apigen manually.
% apigen -missingok sysLib.c
The -missingok flag allows your document to be converted without generating warnings for failures to comply with the Wind River coding conventions. For example, failure to include an ERRNO section in an unpublished routine no longer generates a warning in you use -missingok.
BSP Documentation Build
Test the BSP documentation build.
Execute make man for your BSP.

% make man
Check the output in the $DOCS_ROOT/com.windriver.ide.doc.bsp/bspName directory. To correct markup and formatting errors that generate error messages in the build logs, be sure the files conform to the Wind River Coding Conventions, available from Online Support. If the sysLib.html has unknown( ) routines listed, it is possible that files with third-party copyright information have not been tagged correctly. To fix this problem:
/******** Third-party copyright and license blurb... \NOMANUAL *********/ <-ADD THIS
Update Infrastructure Files
The bspinstall script dynamically updates the online help table of contents with new BSPs. The script is located in installDir/setup. In Wind River products, this
54
3 Porting a BSP to VxWorks 6.2 3.4 Booting a VxWorks 5.5 BSP
runs as a post-installation step. In order for your BSP to appear in the Workbench table of contents, you need to run it manually or package it into your own installer.
Step 14: Compile 3
Build both VxWorks and your BSP documentation. See 2.3.3 Compiler and Build Changes, p.14 and your product Getting Started.
3.4 Booting a VxWorks 5.5 BSP

This section shows the exact procedure, with a step-by-step explanation, of how to bring up a VxWorks 5.5 BSP in the VxWorks 6.x environment, how to compile it, and how to run it in kernel mode. The section demonstrates these procedures using both the command line and Workbench.
3.4.1 Command-Line Build and Boot

Migrating a VxWorks 5.5 BSP to VxWorks 6.x requires a recompilation. This section of the tutorial uses the command-line VxWorks project facility, vxprj, to recompile the BSP.
Build Environment
VxWorks 6.x introduces a development shell consisting of a shell or DOS command window in which the proper environment has been set up by the executable wrenv.exe. The BSP recompilation is performed using this development shell. To open the shell in Windows, execute Start > Programs > Wind River > VxWorks 6.2 and General Purpose Technologies > VxWorks Development Shell. For Solaris and Linux, as well as from the Windows command line, execute wrenv.sh or wrenv.exe as described in torVars Replaced, p.17.
55
Customizing VxWorks
The technique of manually modifying the config.h file in the BSP directory is no longer recommended. If you prefer to use a command-line method rather than a graphical user interface (GUI) such as that provided by Workbench, then it is recommended that you use the command-line VxWorks project utility vxprj to modify a project. For detailed usage of vxprj, run vxprj help. Base your project on an existing BSP. If you are migrating a BSP, copy it from its original location (for example, installDirTornado/target/config/myBSP) to an appropriate VxWorks 6.2 directory (installDir/vxworks-6.2/target/config/myBSP). If you want to experiment without changing your BSP, you can create a VxWorks project based on any existing BSP using vxprj create. In this example, 55mv5100 is an unmodified VxWorks 5.5 BSP copied to the installDir/vxworks-6.2/target/config/ directory. The project name is CLIproj.
% vxprj create 55mv5100 diab /path/CLIproj
Once the project is successfully created, change directories to the project that was just created and add bundles and components using vxprj bundle add or vxprj component add as shown below:
% cd /path/CLIproj % vxprj bundle add BUNDLE_STANDALONE_SHELL
To start a user application in kernel mode immediately after boot up, edit the file usrAppInit.c as shown, replacing the taskSpawn( ) call with your application-specific code.
#include stdio.h #include taskLib.h ) /**************************************************************************** * * usrAppInit - initialize the users application */ void usrAppInit (void) { #ifdef USER_APPL_INIT USER_APPL_INIT; #endif
/* for backwards compatibility */
/* add application specific code here */ taskSpawn (tHello, 200, 0, 2000, printf, \ (int) Can start a user application here...\n, 2,3,4,5,6,7,8,9,0); }
56
Building VxWorks
To compile a new VxWorks image, use the command vxprj build [default] in the project directory:
% cd /path/CLIproj % vxprj build default
Other vxprj build commands that you may consider using include: vxprj build default_rom This command builds the ROM (uncompressed) image, vxWorks_rom, in the subdirectory default_rom. vxprj build default_romCompress This command builds a compressed image, vxWorks_romCompressed, in the subdirectory default_romCompress. vxprj build default_romResident This command builds a ROM-resident image, vxWorks_romResident, in the subdirectory default_romResident. vxprj build list This command lists all the build specifications for the project. vxprj help This command provides help on the vxprj command.
Starting VxWorks
In many cases, a VxWorks 5.x boot loader can be used to load a VxWorks 6.x image, so you may be able to use the same boot parameters as before. The following section provides more details on VxWorks 5.x boot loaders.
VxWorks 5.x Boot Loaders
A VxWorks 5.x boot loader may successfully load a VxWorks 6.x image under certain conditions. The recommendation is to try using your VxWorks 5.x boot loader, and if it does not work, then rebuild the boot loader for VxWorks 6.2. There are two conditions that necessitate updating the boot loader for VxWorks 6.2:
If the error log feature of error detection and reporting is enabled, your VxWorks 5.x boot loader must be updated. Enabling the error log requires setting the boot loader to recognize a reserved memory area and not to clear it
57
upon a warm reboot. For more information, see Error Detection and Reporting Requires Reserved Memory, p.23.
If you are using a MIPS target and you want to take advantage of memory protection for real-time processes (RTPs), you must update your boot loader.
If neither of the above conditions applies to your BSP, then your VxWorks 5.5 boot loader should be compatible with VxWorks 6.2. Many, but not all, VxWorks 5.4 boot loaders are compatible with VxWorks 5.5, and are therefore compatible with VxWorks 6.x, subject to the two conditions described above. Some, but not all, VxWorks 5.3 boot loaders are VxWorks 5.4- and 5.5-compatible. If the OMF is the same and the default load addresses are the same, then the boot loader should be VxWorks 5.5-compatible, and therefore VxWorks 6.x-compatible.
Booting VxWorks 6.2
Once you boot your board, the basic BSP migration is complete! Your output will be similar to that shown below. For more information on booting, see the Wind River Workbench Users Guide: Setting Up Your Hardware.
Sample Boot Output
VxWorks System Boot Copyright 1984-2004 Wind River Systems, Inc.
CPU: Motorola MVME5110-2163 - MPC 7410 Version: VxWorks 6.2 BSP version: 2.0/3 Creation date: Apr 9 2004, 17:27:24 Press any key to stop auto-boot... 7 [VxWorks Boot]: [VxWorks Boot]: @ : fei unit number : 0 processor number : 0 host name : host file name : c:\WindRiver\vxworks-6.2\target\proj\CLIproj\default\v xworks inet on ethernet (e) : 192.168.184.183:fffffe00 gateway inet (g) : 192.168.185.254 user (u) : demo ftp password (pw) : demo flags (f) : 0x0 target name (tn) : mv5100-3
58
Attaching interface lo0... done Attached IPv4 interface to fei unit 0 Loading... 1200268 + 244064 Starting at 0x100000...
3
Attaching interface lo0... done Attached IPv4 interface to fei unit 0 Adding 4883 symbols for standalone.
VxWorks Copyright 1984-2005 Wind River Systems, Inc. CPU: Motorola MVME5110-2163 - MPC 7410 Runtime Name: VxWorks Runtime Version: 6.2 - Reference Design Release BSP version: 1.2/2 Created: May 20 2005, 11:36:14 ED&R Policy Mode: Deployed WDB Comm Type: WDB_COMM_END WDB: Ready. -> Can start a user application here...
-> i NAME ---------tJobTask tExcTask tNbioLog tShell0 tWdbTask tNetTask
ENTRY TID PRI STATUS PC SP ERRNO DELAY ---------- -------- --- -------- ------- -------- ------ ----jobTask 22f8920 0 PEND 2042f0 22f87f0 0 0 excTask 22fbeb0 0 PEND 201bf4 22fbd50 0 0 ... 1a8b04 23028a0 0 PEND 2042f0 2302790 0 0 shellTask 244cc90 1 READY 20ba1c 244c990 0 0 wdbTask 2438480 3 PEND 2042f0 2438380 0 0 netTask 23074e0 50 PEND 2042f0 2307420 0 0
value = 0 = 0x0 ->
3.4.2 Wind River Workbench Build and Boot

Build Environment
To build a VxWorks 6.x image from the Wind River Workbench environment in Windows, execute Start > Programs > Wind River > Wind River Workbench 2.4 > Wind River Workbench 2.4. This opens a new Workbench window.
59
In Solaris and Linux, start Workbench as follows:

% cd installDir % startWorkbench.sh
Customizing VxWorks
Base your project on an existing BSP. Copy the BSP from its original location (for example, installDirTornado/target/config/mv5100) to an appropriate VxWorks 6.2 directory (installDir/vxworks-6.2/target/config/55mv5100). To create and configure a project based on the BSP, follow the steps below: Click File > New > Project. In the New Project window, select VxWorks Image Project under the Project folder, and click Next. Supply a name for the project, then click Next. In the VxWorks Image Project window, make sure the A board support package radio button is selected, and navigate to your BSP (55mv5100) using the Browse button. After selecting the appropriate Tool, either Wind River Compiler (diab) or GNU compiler (gnu), click Finish. Find your project in the Project Navigator window, then expand the project by clicking + next to the project name. To start a user application in kernel mode immediately after boot up, edit the file usrAppInit.c as shown, replacing the taskSpawn( ) call with your application-specific code. Double-click the file usrAppInit.c to open it in the Editor window.
#include stdio.h #include taskLib.h /**************************************************************************** * * usrAppInit - initialize the users application */
void usrAppInit (void) { #ifdef USER_APPL_INIT USER_APPL_INIT; #endif
/* for backwards compatibility */
60
/* add application specific code here */ taskSpawn (tHello, 200, 0, 2000, printf, \ (int) Can start a user application here...\n, 2,3,4,5,6,7,8,9,0); }
3 Building VxWorks
To build the VxWorks image, right-click on the VxWorks image project and select Build Project. You will probably receive many compiler warnings; for more information, see Compiler Warning and Error Levels, p.16.
Starting VxWorks
In many cases, a VxWorks 5.x boot loader can be used to load a VxWorks 6.x image, so you may be able to use the same boot parameters as before. The following section provides more details on VxWorks 5.x boot loaders.
VxWorks 5.x Boot Loaders
A VxWorks 5.x boot loader may successfully load a VxWorks 6.x image under certain conditions. The recommendation is to try using your VxWorks 5.x boot loader, and if it does not work, then rebuild the boot loader for VxWorks 6.2. There are two conditions that necessitate updating the boot loader for VxWorks 6.2:
If the error log feature of error detection and reporting is enabled, your VxWorks 5.x boot loader must be updated. Enabling the error log requires setting the boot loader to recognize a reserved memory area and not to clear it upon a warm reboot. For more information, see Error Detection and Reporting Requires Reserved Memory, p.23. If you are using a MIPS target and you want to take advantage of memory protection for real-time processes (RTPs), you must update your boot loader.
If neither of the above conditions applies to your BSP, then your VxWorks 5.5 boot loader should be compatible with VxWorks 6.2. Many, but not all, VxWorks 5.4 boot loaders are compatible with VxWorks 5.5, and are therefore compatible with VxWorks 6.2, subject to the two conditions described above. Some, but not all, VxWorks 5.3 boot loaders are VxWorks 5.4- and 5.5-compatible. If the OMF is the same and the default load addresses are the same, then the boot
61
loader should be VxWorks 5.5-compatible, and therefore compatible with VxWorks 6.x as well.
Booting VxWorks 6.2
Once you boot your board, your BSP migration is complete! Your output will be similar to that shown below. For more information on booting, see the Wind River Workbench Users Guide: Setting Up Your Hardware.
Sample Boot Output
VxWorks System Boot Copyright 1984-2004 Wind River Systems, Inc.
CPU: Motorola MVME5110-2163 - MPC 7410 Version: VxWorks 6.2 BSP version: 2.0/3 Creation date: Apr 9 2004, 17:27:24 Press any key to stop auto-boot... 7 [VxWorks Boot]: [VxWorks Boot]: @ : fei unit number : 0 processor number : 0 host name : host file name : c:\WindRiver\Workspace\WBproj\default\vxworks inet on ethernet (e) : 192.168.184.183:fffffe00 gateway inet (g) : 192.168.185.254 user (u) : demo ftp password (pw) : demo flags (f) : 0x0 target name (tn) : mv5100-3 Attaching interface lo0... done Attached IPv4 interface to fei unit 0 Loading... 1200268 + 244064 Starting at 0x100000...
Attaching interface lo0... done Attached IPv4 interface to fei unit 0 Adding 4883 symbols for standalone.
VxWorks Copyright 1984-2005 Wind River Systems, Inc. CPU: Motorola MVME5110-2163 - MPC 7410 Runtime Name: VxWorks Runtime Version: 6.2 - Reference Design Release BSP version: 1.2/2 Created: May 20 2005, 11:36:14
62
ED&R Policy Mode: Deployed WDB Comm Type: WDB_COMM_END WDB: Ready. -> Can start a user application here...
-> i NAME ---------tJobTask tExcTask tNbioLog tShell0 tWdbTask tNetTask
ENTRY TID PRI STATUS PC SP ERRNO DELAY ---------- -------- --- -------- ------- -------- ------ ----jobTask 22f8920 0 PEND 2042f0 22f87f0 0 0 excTask 22fbeb0 0 PEND 201bf4 22fbd50 0 0 ... 1a8b04 23028a0 0 PEND 2042f0 2302790 0 0 shellTask 244cc90 1 READY 20ba1c 244c990 0 0 wdbTask 2438480 3 PEND 2042f0 2438380 0 0 netTask 23074e0 50 PEND 2042f0 2307420 0 0
value = 0 = 0x0 ->
Starting the Target Server
Once the target board boots successfully, you must create a target server to launch the host tools in Workbench.
In the Target Manager window, right-click on default(localhost) and select New > Connection. In the Connection Type window, select Wind River Target Server Connection for VxWorks and click Next. In the Target Server Connection window, select the appropriate Back End, type in Name / IP Address and other fields as appropriate, then click Next. There is nothing to change in the Object Path Mapping window or the next window; click Next and Finish. Right-click on the connection you just created and select Connect.
63
64
4
Migrating VxWorks 5.5 Applications To the 6.2 Kernel
4.1 Introduction 65 4.2 Migration Checklist 67 4.3 Build Changes 68 4.4 Internal Changes 70 4.5 System Changes 73 4.6 Networking Changes 81 4.7 Driver Changes 82 4.8 I/O System Changes 85 4.9 File System Changes 86 4.10 Changes in POSIX Support 93 4.11 Changes To VxWorks Components 99
4.1 Introduction
VxWorks 6.2 provides a high degree of backward compatibility with VxWorks 5.5 and with previous versions of VxWorks 6.x.
Draft: 18 Nov 05
65
VxWorks 5.5 application software can be migrated to the VxWorks 6.x kernel without modification, provided it uses standard features of the 5.5 release and does not include components that are obsolete. (For more information, see your product Release Notes.) However, to run a 5.5 application in a 6.x real-time process, the software startup code must be changed, and the application must be built with different libraries. Furthermore, certain kernel-only APIs are not available as system calls, which may prevent certain types of software from being migrated out of the kernel. In particular, software that must execute with supervisor privilege (ISRs, drivers, and so on) or software that cannot communicate by using standard APIs (interprocess communication, file descriptors, or sockets) cannot be migrated out of the kernel without more substantial changes. VxWorks 6.x is fully backward compatible with VxWorks 5.5, meaning that compliant VxWorks 5.5 BSPs, drivers, and projects work with VxWorks 6.x. For example, VxWorks 6.x can be built and run with a standard VxWorks 5.5 BSP. However, all the new operating system features that are dependent on supporting functionality in the BSP would not be available. VxWorks 6.x BSPs do not work with VxWorks 5.5, meaning you cannot build and run a VxWorks 6.x BSP in a VxWorks 5.5 environment. For more information, see your product release notes. There are several levels of effort possible in migrating your applications to VxWorks 6.x: 1. 2. 3. You can stay with a level of functionality comparable to VxWorks 5.5 and make any small changes required for your application. You can migrate to a kernel-mode application and take advantage of the new functionality available in VxWorks 6.x. You can migrate your application to an RTP and take advantage of memory protection.
This chapter covers the first two topics. For more information on migrating to RTPs, see 5. Migrating Applications to RTPs.
66
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.2 Migration Checklist
4.2 Migration Checklist

The checklist below provides guidance for assessing what aspects of existing applications might require additional effort to migrate to kernel projects. If the answer is no to all questions, there should not be any migration issues. !
WARNING: If the applications are based on VxWorks 5.4, you should first migrate to VxWorks 5.5, using the documentation provided with that release, before proceeding to VxWorks 6.x. The checklist below assumes a Tornado 2.2 and VxWorks 5.5 baseline.
Kernel applications from VxWorks 5.5 should run in the VxWorks 6.x kernel with only re-compilation necessary, unless non-standard libraries or compiler options have been used, or unless the application uses the WDB API. 1. Do your applications utilize Wind River private APIs (libraries that are not documented as part of the VxWorks kernel)? Examples are aioSysDrv, avlLib, avlUintLib, cbioLib, classLib, dcacheCbio, dpartCbio, hashLib, inflateLib, objLib, passFsLib, poolLib, and ramDiskCbio. Note that not all libraries defined in installDirTornado/target/h in earlier releases were public APIs. Private APIs continue to be undocumented. They may also change without announcement as they are under the covers. If you have used Wind River private APIs in the past, you should now migrate to public APIs, which are documented in the VxWorks reference entries. 2. Do you utilize any special Wind River Compiler options, pragmas, or in-line assembly code? Use standard Wind River macros for portability. For more information, see the Wind River Compiler Users Guide. 3. Do you utilize any special GCC options, pragmas, or in-line assembly code? Use standard Wind River macros for portability. For more information, see the GNU compiler documentation. 4. Does your product use any WTX tool interface APIs such as wtxtcl or the Tornado C API? Changes have occurred in these areas. For more information, see the Wind River Workbench Migration Guide.
Draft: 18 Nov 05
67
5.
Does your application include any make rule changes? Changes to make rules must be migrated manually.
6.
Does your application use the following POSIX thread APIs: pthread_setschedparam( ), pthread_create( ), or pthread_attr_setscope( )?
4.3 Build Changes

Most build changes are transparent if you use the Workbench GUI. This section highlights some exceptions. For additional build information, see 2. Changes in the VxWorks Environment.
4.3.1 Recompiling Source Code

If you need to recompile the VxWorks kernel libraries from the supplied source code, or if you wish to create additional kernel libraries from your own source code, use the wrconfig utility to set up a build environment. wrconfig generates a makefile and subdirectory structure to support the build; the resulting archive (.a) files can later be linked into VxWorks image projects. For more information, see the VxWorks Command-Line Tools Users Guide.
NOTE: The VxWorks 5.5 kernel library build model is still supported, so backward compatibility is maintained.
4.3.2 Header File Changes

Type Changes
The pathLib.h header file now uses const char *.
68
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.3 Build Changes
IPv6 Stack Headers Directory Change
Some network header files have changed. These changes are transparent if you use the default make rules. However, customized rules must be modified to account for the new file locations. For kernel applications, the header files are still stored in the installDir/vxworks-6.x/target/h directory. However, the header files have been divided in finer detail than in VxWorks 5.5. If you have custom makefiles, you may need to add new entries to the include search paths to account for this. For example, the network header files are now in:
-I{WIND_BASE}/target/h/wrn/coreip
When compiling VxWorks 5.5 code for use in a VxWorks 6.x kernel application, the use of any path that references {WIND_BASE}/target/usr is incorrect. The new headers in {WIND_BASE}/target/usr are specific to RTP applications. For more information, see your product getting started.
isascii( ), toascii( ) Relocated
These routines have been moved. They are no longer defined in vxWorks.h; instead they now reside in ctypes.h to parallel the user-mode library API. Should you rebuild an application and see undefined references to these routines, you should include ctypes.h.
objLib Macro Moved
The OBJ_VERIFY( ) macro has moved into h/private/objLibP.h.
4.3.3 Compiling for Both VxWorks 6.x and VxWorks 5.5

Because VxWorks 6.x is highly backward compatible, there is no reason not to compile the same code for both VxWorks 6.x and VxWorks 5.5. Provided you are aware of the differences, it should be straight-forward to design code that can be moved between the two environments. In the short run, the following macros set in version.h can assist you in compiling for multiple versions. However, you should be aware that these macros are intended for internal Wind River use. Their definition will change with each
Draft: 18 Nov 05
69
release, according to the release level, making any code that uses them potentially obsolete. For code intended to run in RTPs, it is more appropriate to use the uname( ) API, which is provided for this purpose.
Table 4-1 Macros For Specifying the VxWorks Version
Macro Name
Value
_WRS_VXWORKS_MAJOR _WRS_VXWORKS_MINOR _WRS_VXWORKS_MAINT _WRS_VXWORKS_5_X a. Updated in VxWorks 6.2.
6 2a 0 N/A
4.4 Internal Changes

Several types of internal changes have occurred:
A new kernel initialization process automatically calls initialization routines. Changes made in the kernel loader and its supporting libraries have changed the values used to represent symbol types.
4.4.1 Initialization Routines

xxxLibInit
Some library initialization routines have been published previously in the API Reference Manuals. They are now called automatically by the kernel initialization process and user code is not required to call them. They have been marked private and removed from the published documentation.
70
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.4 Internal Changes
4.4.2 Loader Changes

This section summarizes the differences between the VxWorks 6.x loader and the VxWorks 5.5.
4 Backward Compatibility
The kernel loader and its supporting libraries (including loadLib, unldLib, symLib, and moduleLib) have undergone an internal overhaul for VxWorks 6.x. For the most part, all changes should be transparent to users:
APIs have the same signatures and the same options (or additional ones). The same errno is returned for most error conditions as for VxWorks 5.5; all API behavior remains the same (except for SPR fixes; for more information see the online support Web page at http://www.windriver.com/support). The one errno that has changed its VxWorks 5.5 value is set when there is a relocation overflow: S_loadElfLib_RELOCATION_OFFSET_TOO_LARGE. The VxWorks 5.5 errno, S_loadElfLib_RELOC, is still set for other relocation error cases as before. In certain cases S_loadElfLib_SCN_READ, S_loadElfLib_SHDR_READ, and S_loadElfLib_READ_SECTIONS were set when there was an error reading the header of the module to download; we now keep the errno that is set by underlying routines while executing the module to provide more information about the cause of the error.
In other words, the loader, unloader, module, and symbol libraries are completely backward compatible. Re-compilation with new headers is required, of course.
Changed Symbol Type Values
The single notable exception to full backward compatibility of these libraries is that the values used to represent symbol types have changed. In general, changes to values associated with macros do not violate backward compatibility, since VxWorks is not binary backward compatible. Code that uses only the symbol names of the macros should not encounter any compatibility problems. However, the previous set of values used for representing symbol types were almost, but not quite, usable as a bit map. The result was that sometimes code could be forced to look at the actual numeric values contained in a symbol type variable to try to deduce the real meaning of the variable.
Draft: 18 Nov 05
71
Any code that used the numeric values of these macros must be modified to use only the symbolic names. The new set of values makes it possible to always work only with the symbolic names, so this problem no longer occurs. These were the previous (VxWorks 5.5) values:
#define #define #define #define #define #define #define #define #define SYM_UNDF SYM_LOCAL SYM_GLOBAL SYM_ABS SYM_TEXT SYM_DATA SYM_BSS SYM_COMM SYM_SDA 0x0 0x0 0x1 0x2 0x4 0x6 0x8 0x12 0x40 0x80 /* /* /* /* /* /* /* /* /* /* /* /* undefined local global (external) (ORed) absolute text data bss common symbol symbols related to a PowerPC SDA section symbols related to a PowerPC SDA2 section */ */ */ */ */ */ */ */ */ */ */ */ */
#define SYM_SDA2
#define SYM_THUMB
0x40
/* Thumb function
These are the new (VxWorks 6.x) values:

#define #define #define #define #define #define #define SYM_UNDF SYM_GLOBAL SYM_ABS SYM_TEXT SYM_DATA SYM_BSS SYM_COMM 0x0 0x1 0x2 0x4 0x8 0x10 0x20 0x40 0x80 /* /* /* /* /* /* /* undefined (lowest 8 bits only) */ global (external) */ absolute */ text */ data */ bss */ common symbol */ */ */
#define SYM_LOCAL #define SYM_THUMB
/* local /* Thumb function
With the previous set of values, some bits could be meaningfully ORd together (for instance, the global symbol type could be meaningfully ORd with any other symbol type). But if some symbol types were ORd together, the original meaning could be lost. For example, with the old values:
SYM_ABS | SYM_TEXT = 0x6 = SYM_DATA.
The new values work as a true bit field. Each bit carries one and only one possible meaning. The symbol masks should be used to avoid these bit-field and compatibility problems. You should test for symbol types with the following macros, defined in symbol.h:

#define SYM_IS_UNDF(symType) #define SYM_IS_GLOBAL(symType) #define SYM_IS_LOCAL(symType) #define SYM_IS_TEXT(symType) #define SYM_IS_DATA(symType) #define SYM_IS_BSS(symType)
72
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.5 System Changes
#define SYM_IS_ABS(symType) #define SYM_IS_COMMON(symType)
WARNING: Code that only uses the symbolic names of these macros should not encounter any problems. But any code that used the numeric values of these macros must be modified to use only the symbolic names.
Resolving Common Symbols
Resolving COMMON symbols changed between VxWorks 5.5 and VxWorks 6.x. In the past if you used the LOAD_COMMON_MATCH_USER or LOAD_COMMON_MATCH_ALL loader options and there were several matches, BSS symbols would be picked first, then DATA symbols. For VxWorks 6.x, the matching order is DATA symbols, then BSS symbols.
Symbol Tables and Modules Not Objects
Symbol tables and modules are no longer objects. This change occurred in VxWorks 6.0 and remains in VxWorks 6.x.
The objShow( ) and show( ) APIs no longer work with a module ID or a symbol table ID. For modules, use moduleShow( ). For symbol tables, use lkup( ) with no arguments; it prints the contents of the symbol table. The new routine symShow( ) can be used to display general information about a symbol table. If an invalid ID is provided to symbol table or module APIs, the errno is no longer set to S_objLib_OBJ_ID_ERROR. Instead, it is now set to S_symLib_INVALID_SYMTAB_ID or S_moduleLib_INVALID_MODULE_ID.
4.5 System Changes

Some changes affect such system activities as hashing, tasks, semaphores, and signals.
Draft: 18 Nov 05
73
4.5.1 Tasks and the TCB

Accessing the TCB
Currently, direct access to the task control block (WIND_TCB) structure is permitted, but it is deprecated. This release provides the taskUtilLib library to provide controlled access to fields in the WIND_TCB structure. Wind River advises replacing any code that directly accesses the TCB with routines provided by this library and routines in the taskLib and taskInfo libraries. The task name is now stored as part of the generic object structure, and can no longer be referenced directly from the TCB. For complete portability use taskName( ) instead. The taskUtilLib library has been added to VxWorks and the following APIs are published. This library provides utility routines to access fields in the task control block (WIND_TCB) structure. Wind River advises using these routines when accessing fields in the WIND_TCB structure, because direct access to the structure will not be allowed in a future release. The new routines are the following:

taskSpareNumAllot( ) taskSpareFieldGet( ) taskSpareFieldSet( )
Changed Components and Macros
The following macros have been introduced for taskLib routines:

TASK_SCHED_INFO_GET TASK_SCHED_INFO_SET
taskSwitchHookAdd( ) Behavior Modified
The general behavior of this function does not change, but a subtle change in the VxWorks 6.x scheduler may affect customer task switch hooks. In the VxWorks kernel, there exists a global variable called taskIdCurrent that typically contains the task ID of the currently executing task (or in an ISR context, the task ID of the task that was interrupted). In the VxWorks 5.5 scheduler, the value of taskIdCurrent was updated to contain the task ID of the task to be scheduled in before invoking the task switch (and swap) hooks.
74
Draft: 18 Nov 05
In the VxWorks 6.x scheduler, the value of taskIdCurrent is updated to contain the task ID of the task to be scheduled in after invoking the task switch (and swap) hooks.
taskCreat( ) Deprecated
The unpublished VxWorks 5.5 routine taskCreat( ), defined in installDir/vxworks-6.x/target/h/private/taskLibP.h, is deprecated. The new taskCreate( ) routine has the same behavior and API as taskCreat( ) and should be used in its place.
4.5.2 _func_excBaseHook Daisy Chaining

The _func_excBaseHook function pointer was private in VxWorks 5.5 and remains so in VxWorks 6.x. If you continue to use this function pointer, you must follow the daisy chaining policy described here. The _func_excBaseHook is provided to allow Wind River components to use the exception mechanism and handle exceptions in their own way. Currently the only user of this feature is objVerify( ). The object management system installs a hook during system initialization; the hook is always present to trap accesses to non-existing or protected memory when an application supplies a bad object identifier. The functions hooked into _func_excBaseHook must return a non-zero value to indicate that the exception has been handled, which allows excExcHandle( ) to return without taking any action. A zero return value indicates that normal exception handling should continue. If an additional Wind River subsystem wishes to hook into the exception handling path, the _func_excBaseHook can be daisy-chained. When the subsystem initialization function executes, the existing FUNCPTR value of _func_excBaseHook should be cached. Then, during exception handling, the cached FUNCPTR should be called if the exception is not to be handled by the current hook.
NOTE: The simulators temporarily overwrite the _func_excBaseHook hook (and do not perform daisy chaining) in vxMemProbeArch( ). However, the entire sequence of operations in vxMemProbeArch( ) where the _func_excBaseHook hook has been used in a non-standard manner is protected with intLock( )/intUnlock( ).
Draft: 18 Nov 05
75
4.5.3 Memory Partition Options

This section provides a summary of the new and changed memory partition options introduced in VxWorks 6.2. For more information about the memory partition error handling options see the reference entry for the memLib kernel library and the memPartLib application library, as well as the kernel and application versions of memPartOptionsSet( ) and memOptionsSet( ). For more information about the error detection and reporting facility and policy handlers see the VxWorks Kernel Programmer's Guide: Error Detection and Reporting.
New Options
In VxWorks 6.2 the following new memory partition options have been added to memPartLib.c and memLib.c:
MEM_ALLOC_ERROR_EDR_FATAL_FLAG
Inject a fatal event when there is an error in allocating memory.

MEM_ALLOC_ERROR_EDR_WARN_FLAG
Inject an warning when there is an error in allocating memory.

MEM_BLOCK_ERROR_EDR_FATAL_FLAG
Inject a fatal event when there is an error in freeing or reallocating memory.

MEM_BLOCK_ERROR_EDR_WARN_FLAG
Inject a non-fatal event when there is an error in freeing or reallocating memory. Enabling the error detection and reporting-specific options does not require the infrastructure to be enabled. However, when error detection and reporting is enabled, these flags provide additional debug capability, such as call stack trace information.
Deprecated Options
The following options are deprecated:

MEM_ALLOC_ERROR_SUSPEND_FLAG
Suspend the task when there is an error in allocating memory unless the task was spawned with the VX_UNBREAKABLE option.
76
Draft: 18 Nov 05
MEM_BLOCK_ERROR_SUSPEND_FLAG
Suspend the task when there is an error in freeing or reallocating memory, unless the task was spawned with the VX_UNBREAKABLE option.
Changed Default Options
In the kernel, the default memory partition options have been changed as follows:
Figure 4-1 Changes to Kernel Memory Partition Options
VxWorks 6.2
Prior Versions
MEM_ALLOC_ERROR_LOG_FLAG
MEM_ALLOC_ERROR_EDR_WARN_FLAG MEM_BLOCK_CHECK MEM_BLOCK_ERROR_LOG_FLAG MEM_BLOCK_CHECK MEM_BLOCK_ERROR_LOG_FLAG
MEM_BLOCK_ERROR_SUSPEND_FLAG MEM_BLOCK_ERROR_SUSPEND_FLAG MEM_BLOCK_ERROR_EDR_WARN_FLAG -
NOTE: The default partition options are applied to all new partitions created, including the heap memory partition. In the kernel, these default options apply when the INCLUDE_MEM_MGR_FULL component is included.
The addition of the error detection and reporting warning flags in kernel space does not have backward compatibility consequences. In future releases the MEM_BLOCK_ERROR_SUSPEND_FLAG flag will be removed from the default options.
Restoring Prior Options
If you prefer to deploy the default memory partition options of previous releases, memOptionsSet( ) can be used for the heap memory partition. For example: memOptionsSet (MEM_ALLOC_ERROR_LOG_FLAG | MEM_BLOCK_CHECK | MEM_BLOCK_ERROR_LOG_FLAG | MEM_BLOCK_ERROR_SUSPEND_FLAG);
Draft: 18 Nov 05
77
4.5.4 Caching
cacheLib Routines Replaced
In previous versions of VxWorks, two non-published routines, cacheArchFlush( ) and cacheArchInvalidate( ), have occasionally been used to manipulate the PowerPC caches. These routines were part of the PowerPC cache library implementation. Occasionally, BSPs and device drivers made direct use of these routines instead of calling the standard library entry points for these operations. In VxWorks 6.x, these routines have been removed from the VxWorks libraries. Any source file which uses either of these two function calls can instead use the following architecture-independent cache library routines:
Table 4-2 Cache Replacement Routines
Obsolete Routines
Replacement Routines
cacheArchFlush( ) cacheArchInvalidate( )
cacheFlush( ) cacheInvalidate( )
The cacheFlush( ) and cacheInvalidate( ) routines accept the same parameters as the cacheArchFlush( ) and cacheArchInvalidate( ) routines that they replace.
4.5.5 Scalability Changes

The following APIs and macros have been introduced for static instantiation of kernel objects, to be used with the small kernel scalability profiles:

semBInitialize( ) semCInitialize( ) semMInitialize( ) msgQInitialize( ) wdInitialize( )

VX_TASK VX_TASK_INSTANTIATE VX_TASK_INITIALIZE VX_BINARY_SEMAPHORE VX_COUNTING_SEMAPHORE VX_MUTEX_SEMAPHORE VX_MSG_Q VX_WD
In addition, some routines have moved from vmBaseLib.c to vmGlobalMap.c.
78
Draft: 18 Nov 05
4.5.6 Other System API Changes

Newly Public Libraries and APIs
The following APIs are now public:

taskStackAllot( ) excJobAdd( )
objLib and its routines are now public. For a list of newly public routines in objLib, see your product Release Notes.
Newly Private Structures and Routines hashLib
The definition of the HASH_TBL structure has been moved into the private header file h/private/hashLibP.h.
excTask( )
The excLib library documentation has changed. The excTask( ) routine, which was not intended to be public, is no longer published. The excJobAdd( ) routine is now provided.
New APIs and Libraries vmGlobalMap.c
This new file includes some routines moved from vmBaseLib.c.
Parameter Change vmBaseLib Parameter Change
The VxWorks 6.x version of the vmBaseLibInit( ) routine takes the parameter cacheDefault. The VxWorks 5.5 version of the routine took the parameter pageSize. In general, library initialization routines should not be called by user code; they should only be called by the operating system.
Draft: 18 Nov 05
79
The vmBaseStateSet( ) and vmStateSet( ) routines are not fully backward compatible with the VxWorks 5.5 versions. For more information, see 4.11.2 Migrating From VxVMI To RTPs, p.99.
Deprecated Library and APIs semOLib
semOLib is deprecated. The semOLib routines are semCreate( ), semInit( ), and semClear( ). Note that the semOLib library has been superseded in functionality by semBLib.
Deprecated APIs
With the introduction of the new power management facility, the vxPowerModeSet( ) and vxPowerModeGet( ) routines are deprecated. The routines still exist but have no effect on power management. Applications making use of these routines should migrate to API provided by the light CPU power manager.
Removed APIs
The following unpublished routines are not available in this release:

semBCoreInit( ) semCCoreInit( ) semMCoreInit( ) semQInit( )
If you have used these unpublished APIs with a past release, you should modify your code to use semBInitialize( ), semCInitialize( ), and semMInitialize( ) routines (or their associated macros) instead.
80
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.6 Networking Changes
4.6 Networking Changes

The following sections are not intended to be a complete listing of networking changes. For complete information, see the Wind River Network Stack for VxWorks 6 Programmer's Guide.
Deprecated Header Files
The header files osdep.h, machdep.h, and clarinet.h are now deprecated. If you have any code that includes these files, it should be modified to use vxWorks.h. These header files are available for VxWorks 6.x but they should not be used as they will be removed in a future release.
Unneeded Header Files Removed
Most of the header files available in VxWorks 6.0 have been removed from installDir/vxworks-6.x/target/usr/h/wrn/coreip. If your code includes some header that is no longer available, the include should be removed. These headers are not appropriate for use in user mode.
No _KERNEL Flag
The _KERNEL flag that was available in VxWorks 6.0 is no longer used. If you have any code which made use of this flag, it should be changed to use the _WRS_KERNEL flag instead.
IPv4 FTP Server Replaced
The IPv4 FTP server (ftpdLib, INCLUDE_FTP_SERVER) is no longer available. The dual FTP server (ftpd6Lib, INCLUDE_FTP6_SERVER) has been modified to work in IPv4-only mode in addition to dual mode. If you were using ftpdLib before, ftpd6Lib replaces it. This library supports the ftpdLib APIs for backward compatibility but these are deprecated.
Draft: 18 Nov 05
81
etherAddrResolve( ) Removed
This routine is not available in VxWorks 6.x. It is replaced by arpResolve( ).
IP Forwarding
In VxWorks 6.x, IP forwarding is turned off by default. For more information, see the Wind River Network Stack for VxWorks 6 Programmers Guide.
4.7 Driver Changes

END-Style Drivers Replace BSD Drivers
Table 4-3 shows which BSD drivers have a current END driver to replace them. The remaining BSD drivers support hardware which is no longer available. For information on migrating to END drivers, see the Wind River Network Stack for VxWorks 6 Programmers Guide: Integrating a New Network Interface Driver.
Table 4-3 END-style Drivers Replacing BSD-Style Drivers
BSD-Style Driver END-Style Driver
if_cpm if_cs if_dc if_eex if_ei if_eidve if_eihk if_elc
motcpmEnd obsolete dec21x40End obsolete obsolete obsolete obsolete obsolete
82
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.7 Driver Changes
Table 4-3
END-style Drivers Replacing BSD-Style Drivers (contd)
BSD-Style Driver END-Style Driver
if_elt if_ene if_esmc if_fei if_fn if_ln if_lnPci if_loop if_mbc if_nicEvb if_sl if_sm if_sn if_ultra
elt3c509End ne2000End obsolete fei82557End obsolete obsolete ln97xEnd loopEnd obsolete nicEvbEnd obsolete smEnd obsolete obsolete
4
Modified smEnd
In VxWorks 6.x the shared memory networking driver smEnd has been upgraded from the BSD-style driver (if_sm.c in VxWorks 5.5) to an END-style driver (smEnd.c in VxWorks 6.x). For more information on the new driver, see the reference entry. In addition, as when porting any new END driver, the BSP supporting shared memory networking in VxWorks 5.5 must also be modified to use smEnd.c. The MV5100 BSP provides an example. The following summary shows how to modify a BSP to support the shared memory END driver: 1. Change config.h. Include INCLUDE_SMEND conditionally if INCLUDE_SM_NET was originally defined; remove INCLUDE_BSD if it was defined.
Draft: 18 Nov 05
83
2.
Change configNet.h. Add the shared memory entry in the endDevTbl[ ] before the last NULL entry. Example:
#ifdef INCLUDE_SMEND # define SMEND_LOAD_STRING "" # define SMEND_LOAD_FUNC sysSmEndLoad IMPORT END_OBJ* SMEND_LOAD_FUNC (char*, void*); #endif /* INCLUDE_SMEND */ #ifdef INCLUDE_SMEND { 0, SMEND_LOAD_FUNC, SMEND_LOAD_STRING, 0, NULL, FALSE}, #endif
3.
Create a new function, sysSmEndLoad( ). Although this function can be placed in any appropriate file such as sysNet.c, in some BSPs there is a new file that serves as a placeholder for sysSmEndLoad( ). (This is the case, for example, with mv5100/sysSmEnd.c.) The routine sysSmEndLoad( ) converts all shared memory configuration parameters to a load string. The load string format is as follows: "unit:pAnchor:smAddr:memSize:tasType:maxCpus:masterCpu:localCpu: maxPktBytes:maxInputPkts:intType:intArg1:intArg2:intArg3:mbNum: cbNum:configFlg:pBootParams"
4.
If a new file is created in the previous step, modify sysLib.c or Makefile to include this file. In sysLib.c:
#ifdef INCLUDE_SMEND # include "./sysSmEnd.c" #endif /* INCLUDE_SMEND */
or in Makefile:
MACH_EXTRA = sysSmEnd.o
NOTE: usrNetwork.c and bootConfig.c have been modified to support the shared
memory END driver.
84
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.8 I/O System Changes
4.8 I/O System Changes

I/O Error Code Value Changes
In order for Wind Rivers I/O system to be more in line with POSIX I/O system error codes, the numeric values for all of the old VxWorks I/O related errors have been changed. The macro names have not been changed; only the numeric values that represent them have changed. Because VxWorks had a richer set of error codes than POSIX, some of the VxWorks error codes are no longer numerically unique. This could cause application code that tries to decode the numeric values to fail with compiler errors. For example, a switch statement that tries to decode S_iosLib_NO_DEVICE_FOUND and S_ioLib_NO_DEVICE_NAME_IN_PATH as different cases now generates a compiler error because the two are not unique. Table 4-4 provides a mapping of VxWorks error codes to their POSIX equivalents. This table contains those error codes that are no longer numerically unique.
Table 4-4 VxWorks I/O Errors With Non-Unique Numeric Error Codes
VxWorks Name
POSIX Name
S_iosLib_NO_DEVICE_FOUND S_ioLib_NO_DEVICE_NAME_IN_PATH S_iosLib_CONTROLLER_NOT_PRESENT S_ioLib_DISK_NOT_PRESENT S_ioLib_NO_DRIVER S_iosLib_DUPLICATE_DEVICE_NAME S_iosLib_INVALID_ETHERNET_ADDRESS S_ioLib_NO_FILENAME S_ioLib_DEVICE_ERROR S_ioLib_DEVICE_TIMEOUT S_ioLib_UNFORMATTED
ENODEV ENODEV ENXIO ENXIO ENXIO EINVAL EINVAL EINVAL EIO EIO EIO
Draft: 18 Nov 05
85
Table 4-5 provides a list of error codes that do have numerically unique numbers.
Table 4-5 VxWorks I/O Errors With Unique Numeric Error Codes
VxWorks Name
POSIX Name
S_iosLib_DRIVER_GLUT S_iosLib_INVALID_FILE_DESCRIPTOR S_iosLib_TOO_MANY_OPEN_FILES S_ioLib_UNKNOWN_REQUEST S_ioLib_WRITE_PROTECTED S_ioLib_CANCELLED S_ioLib_NAME_TOO_LONG S_ioLib_CANT_OVERWRITE_DIR
ENOMEM EBADF EMFILE ENOSYS EACCES ECANCELED ENAMETOOLONG EISDIR
I/O Device Control APIs
The following APIs are added to the I/O system for device control:

iosDevSuspend( ) iosDevResume( ) iosDevReplace( ) iosDevDelCallback( )
For more information about these changes, see New I/O System Device Control APIs, p.98.
4.9 File System Changes

VxWorks 6.2 introduces extensive changes to file system support. This section contains information about migrating your kernel applications. For an overview of XBD support, the new highly reliable file system (HRFS), and other changes, see 2.7.1 File System Changes, p.35. For additional details, see the VxWorks Kernel Programmers Guide: I/O System.
86
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.9 File System Changes
4.9.1 Extended Block Device (XBD) Support

Under the new XBD facility, only file system code should directly access XBDs. If it is necessary to access the underlying device, rawFs is available.
4 XBD Replaces CBIO
The XBD facility resides between the file system and the driver, replacing CBIO. In most cases, migration is straightforward.
The Wind River device drivers for USB block storage, ATA, and RAM disk devices have been updated to be compliant with the XBD driver interface. The only migration steps are: Include the INCLUDE_XBD component in your VxWorks project. Remove any code that directly initializes a file system. For example, a call to dosFsDevCreate( ) must be removed.
The BLK_DEV-based device drivers for floppy drives, SCSI, and TrueFFS (the disk-access emulator for flash) have not been updated to be compliant with the XBD driver interface. THey require the XBD wrapper component in order to work with the XBD facility. In addition to INCLUDE_XBD, you need the INCLUDE_XBD_BLK_DEV component in your VxWorks project. Remove any code that directly initializes a file system.
Custom drivers that were compliant with the BLK_DEV interface can be used with XBD by using INCLUDE_XBD_BLK_DEV. Custom drivers that were not BLK_DEV-compliant must be migrated to be either BLK_DEV-compliant or XBD-compliant. XBD is the preferred route.
Table 4-6
XBD Support for Wind River Drivers
XBD-Compliant Drivers
Drivers Requiring XBD Wrapper Component
USB block storage ATA RAM disk
Floppy devices SCSI TrueFFS
Draft: 18 Nov 05
87
xbdBlkDev.c
XBDs replace CBIO and block device drivers. These are soft or logical extended block devices. The xbdBlkDev.c library provides the XBD block wrapper for BLK_DEV drivers. xbdBlkDevLibInit( ) Initialize the XBD block wrapper library. xbdBlkDevCreate( ) Create an XBD block device wrapper on top of a BLK_DEV device. xbdBlkDevDelete( ) Destroy a previously created XBD block device wrapper.
cdromFsLib.c
cdromFsDevCreate( ) This routine now takes a device_t instead of a BLK_DEV *. Also, it is not necessary to call this function in VxWorks 6.x as the new file system framework calls it automatically when the CD-ROM device is detected. cdromFsVersionDisplay( ) cdromFsVersionNumGet( ) These routines are deprecated.
usrFdiskPartLib.c
While still supported, this component and all CBIO-based components are deprecated.
partLib.c
partLib.c is the XBD version of the usrFdisk component. xbdCreatePartition( ) This routine creates an FDIDK-like partition table on a disk
xbdRamDisk.c
The following routines are provided by xbdRamDisk.c, the XBD version of the BLK_DEV and CBIO RAM disk components. xbdRamDiskDevCreate( ) This routine creates an XBD RAM disk. It replaces ramDiskDevCreate( ). xbdRamDiskDevDelete( ) This routine deletes a previously created XBD RAM disk.
88
Draft: 18 Nov 05
Disk Partitioning
The usrFdiskPartCreate( ) routine is no longer used for disk partitioning. It is replaced by the xbdCreatePartition( ) routine.
STATUS xbdCreatePartition ( char * pathName, int nPart, int size1, int size2, int size3
This routine creates a partition table using pathName to specify the appropriate XBD. The nPart parameter indicates the number of partitions to create (up to 4). The size1, size2, and size3 parameters indicate the percentage of the disk to use for the first, second and third partitions respectively. This routine performs the following steps:
removes all of the file systems and intermediate XBDs from the XBD stacks based on a single XBD. removes the partition manager. places a partition table on the XBD which actually accesses the media. recreates the XBD stacks by creating a new partition manager based on the newly created table.
Fallback to rawFs
In situations in which a file system cannot be detected on an XBD, or where unformatted access to the media is required (as when formatting a file system or partitioning a disk) rawFs is used as a file system on the XBD. The top of every XBD stack is accessible in core I/O as a pathname; if no other file system exists, then that XBD stack is accessed by rawFs.
ATA Driver Changes
The ATA driver for VxWorks 6.2 has been substantially modified. It now supports ATA/ATAPI-5 and has support for DMA. It is also compliant with the new XBD (Extended Block Device) interface that the VxWorks 6.2 file systems use.
Draft: 18 Nov 05
89
However, no migration is required. Configuring INCLUDE_ATA in the project and setting the ATA parameters as in VxWorks 6.1 instantiates the ATA driver and the appropriate file systems.
Disk Formatting
Disk formatting routines, such as dosFsVolFormat( ) and hrfsFormat( ), take a pathname argument that specifies what to format. That pathname must refer to an entry in the core I/O device table (accessible by the devs command). Once formatting is complete, the path refers to the newly formatted file system.
Changes to ioctl( ) Commands ioctl( ) Commands Removed
Several ioctl( ) commands are no longer supported by file systems.

FIODISKCHANGE
no longer supported. XBD-based devices determine their status either automatically or by calling the XBD_TEST ioctl( ) command. XBD_TEST causes the devices to test for status and insert or remove a new file system as appropriate.
FIOFORMAT
no longer supported. There are now multiple, general purpose file systems, which cannot be specified by the FIOFORMAT ioctl( ) command.
File System Monitor ioctl( ) Commands
The ioctl( ) commands XBD_SOFT_EJECT and XBD_HARD_EJECT are provided to provide access to the file system monitor auto detection sequence.
XBD_SOFT_EJECT
This command causes the file system (and potentially some part of the XBD stack) to be removed, and replaced with rawFS.
XBD_HARD_EJECT
This command causes the file system (and potentially part of the XBD stack) to be removed and replaced using the auto detection sequence. The parameter to these ioctl( ) commands is an enumeration constant of the type XBD_LEVEL which specifies what level of the XBD stack to remove:
XBD_TOP, which means no XBD is removed, only the file system on top of it.
90
Draft: 18 Nov 05
XBD_PART, which means that all XBDs above the partition manager are removed (partitions are preserved) XBD_BASE, which means that all XBDs above the bottommost (base) XBD are removed. (This parameter removes all partitions and all file systems associated with those partitions).
4.9.2 HRFS
hrFsLib.c
This is the new highly reliable file system. It is composed of many files but only one function, contained in hrfsFormatLib.c, is relevant. hrfsFormat( ) This routine formats the disk for HRFS. It is similar to dosFsVolFormat( ) but for the HRFS file system, rather than DOS.
usrFsLib.c
There have been some changes to usrFsLib.c. Most functions have stayed the same, but the following APIs have changed: diskInit( ) is deprecated and prints an error when used. diskFormat( ) is deprecated and it prints a warning, but proceeds with formatting the device for dosFs. dosfsDiskFormat( ) is new in VxWorks 6.2; it replaces diskInit( ) and diskFormat( ). hrfsDiskFormat( ) invokes the HRFS file system formatter. It is the HRFS equivalent to dosfsDiskFormat( ).
4.9.3 dosFS
Migrating From dosFs 1.0 to 2.0
dosFs 1.0 is not supported in VxWorks 6.x. If you have not already migrated, you must address the following concerns:
Draft: 18 Nov 05
91
OPT_LOWERCASE
This option stored and displayed file names in all lowercase instead of all uppercase per the Microsoft standard. When migrating to dosFS 2, given a lower case filename, the ls directory listing command showed a file, for example foobar.txt, which is in the directory entry as foobar txt instead of FOOBAR TXT. When opening the file, the correct file name encoding of FOOBAR TXT did not match what was physically stored on the disk (foobar txt), and the file could not be opened or deleted.
Long File Name Support
Wind Rivers proprietary VxWorks long name support (VxLong) for dosFs is not fully supported in this release. In this release, VxWorks is able to read volumes with VxLong name files, but is not able to create them or write to them. Wind River advises customers to migrate to the Microsoft standard of long names. Thus DOS_OPT_VXLONGNAMES is no longer supported.
dosFs 2.0 Migration APIs
This VxWorks release does not provide backward compatibility with the dosFs 1.0 API. The following migration routines have been replaced with empty stub routines:

dosFsInit( ) dosFsDevInit( ) dosFsDevInitOptionsSet( ) dosFsMkOptionsSet( ) dosFsConfigInit( ) dosFsConfigGet( ) dosFsConfigShow( ) dosFsModeChange( ) dosFsReadyChange( ) dosFsVolOptionsGet( ) dosFsVolOptionsSet( ) dosFsDateTimeInstall( )
92
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.10 Changes in POSIX Support
Changed APIs dosFsLib.c
dosFsDevCreate( ) now takes a device_t instead of a CBIO_DEVI_ID. Also, it is not necessary to call this function in VxWorks 6.2 as the new file system framework calls it automatically when the CD-ROM device is detected.
dosFsFmtLib.c
dosFsVolFormat( ) now exclusively takes the name of the device to format:

void *device -> char *device.
4.9.4 File System-Related APIs and Libraries Removed

scsiSeqLib.c
This component is no longer available.

tapeFsLib.c
This library is no longer available.

rt11fsLib
All routines in rt11fsLib are no longer available.
4.10 Changes in POSIX Support

Each release of VxWorks 6.x has introduced new areas of increased compliance with the POSIX standard. This section shows these changes grouped by release.
Draft: 18 Nov 05
93
4.10.1 Changes in POSIX Facilities in VxWorks 6.0

The changes introduced in VxWorks 6.0 addressed message queues, semaphores, and threads. The changes in the kernel were primarily required to provide kernel support to RTPs.
POSIX Message Queues
Several changes to the mq_des structure were introduced in VxWorks 6.0. In both VxWorks 5.5 and VxWorks 6.x, the POSIX message queue (mqPxLib) structure type mqd_t is defined as follows in mqueue.h:
struct mq_des; typedef struct mq_des * mqd_t;
The internals of the mq_des structure have changed between VxWorks 5.5 and VxWorks 6.x. Since this structure is defined in a private header (installDir/vxworks-6.x/target/h/private/mqPxLib.h), the possibility of applications accessing mqd_t internals is much less likely than in the POSIX semaphore situation described below. However, the impact of the change to the mq_des structure is that an mqd_t value is no longer a VxWorks kernel object ID. In concrete terms, performing the following no longer works:
mqd_t mq_id = mq_open ("test", 0x202, 0, 0); show (mq_id);
Instead, the mqPxShow( ) command should be substituted for show( ):

mqd_t mq_id = mq_open ("test", 0x202, 0, 0); mqPxSshow (mq_id);
POSIX Thread Support
Several changes in pthreadLib were introduced in VxWorks 6.0. The pthread_attr_setstacksize( ) routine now returns the EINVAL status if the stack size is smaller than PTHREAD_STACK_MIN. Previously (in VxWorks 5.5 and VxWorks AE) stack size was not checked, even though this check is required by the POSIX standard. The pthread_create( ) routine now returns the EINVAL status if the a user-supplied stack area is provided but its size is not valid. Previously (in VxWorks 5.5 and VxWorks AE) the stack size, if invalid, was forced to the default stack size. Then, since no stack area of this default size was actually provided by user code, thread
94
Draft: 18 Nov 05
creation would (at best) fail with an EAGAIN status. According to the POSIX standard, EINVAL is the status that should be returned when the thread attributes are invalid. The EAGAIN error status should be returned when the system does not have the necessary resources to create a new thread, which is not the case in this situation.
4 POSIX Semaphores
Several changes in semPxLib were introduced in VxWorks 6.0. The sem_t type was defined as follows in VxWorks 5.5 semaphore.h:
typedef struct sem_des { OBJ_CORE objCore; SEM_ID semId; int refCnt; char * sem_name; } sem_t; /* sem_t */ /* /* /* /* semaphore object core semaphore identifier number of attachments name of semaphore */ */ */ */
In VxWorks 6.x, the definition of the structure has been made private (private/semPxLibP.h) and the definition of sem_t appears as follows in semaphore.h:
typedef void * sem_t;
It is non-standard for POSIX applications to access the internals of the sem_t structure. Any application that accesses the internals of the sem_t structure must be modified to execute in VxWorks 6.x, preferably by eliminating such references.
4.10.2 Changes in POSIX APIs in VxWorks 6.2

While most work on POSIX compliance applies to applications in RTPs, some changes have occurred that affect kernel applications.
New POSIX APIs
The following I/O routines are available in the kernel in VxWorks 6.2: access( ) fcntl( ) fsync( ) aio_fsync( ) fdatasync( ) link( ) chmod( ) fpathconf( ) pathconf( )
Draft: 18 Nov 05
95
The I/O routines can be guaranteed to perform fully only if the underlying file system device driver supports the operations they command. In VxWorks 6.2 only the HRFS file system is guaranteed to do so. For more information, see the VxWorks Kernel Programmers Guide: Local File Systems. In VxWorks 6.2, fcntl( ) supports only a limited set of operations: F_DUPFD, F_SETFL, and F_GETFL. As for the other I/O functions, these operations can actually be executed only if the underlying file system device driver supports them.
Changes in Existing POSIX APIs
The following pthread routines have been modified: pthread_attr_init( ) This routine now sets the default scheduling policy to be SCHED_OTHER, the active VxWorks native scheduling policy, instead of SCHED_RR. pthread_attr_setschedpolicy( ) pthread_attr_getschedpolicy( ) SCHED_OTHER is now described as the equivalent of the active native VxWorks scheduling policy. pthread_setschedparam( ) This routine now returns the EPERM error code, instead of EINVAL, when the scheduling policy is not the same as the active native VxWorks scheduling policy. pthread_getschedparam( ) The reference entry for this routine has been updated. pthread_create( ) This routine now returns the EPERM error code instead of ENOTTY when the requested scheduling policy is not the system's current one. It no longer fails when the requested scheduling policy is SCHED_OTHER since this now defaults to using the active native scheduling policy. pthread_attr_setscope( ) This routine now returns the error code ENOTSUP, instead of indicating success, for the specific case when the requested contention scope is PTHREAD_SCOPE_PROCESS. pthread_attr_setopt( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid.
96
Draft: 18 Nov 05
pthread_attr_getopt( ) This routine now returns the EINVAL error code if either the pAttr parameter or the pOptions parameter is not valid. pthread_attr_setname( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_getname( ) This routine now returns the EINVAL error code if either the pAttr parameter or the name parameter is not valid. pthread_attr_setstacksize( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_getstacksize( ) This routine now returns the EINVAL error code if either the pAttr parameter or the pStackSize parameter is not valid. pthread_attr_setstackaddr( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_getstackaddr( ) This routine now returns the EINVAL error code if either the pAttr parameter or the ppStackAddr parameter is not valid. pthread_attr_setdetachstate( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_getdetachstate( ) This routine now returns the EINVAL error code if either the pAttr parameter or the pDetachState parameter is not valid.
Modified Signal APIs
sigtimedwait( ) The API for this routine has changed from:

int sigtimedwait (const sigset_t, struct siginfo, const struct timespec);
to:
int sigtimedwait (const sigset_t, siginfo_t, const struct timespec);
Draft: 18 Nov 05
97
This change is to conform with POSIX but should be transparent to existing application code. sigwaitinfo( ) The API for this routine has changed from:
int sigwaitinfo (const sigset_t, struct siginfo);
to:
int sigwaitinfo (const sigset_t, siginfo_t);
This change is to conform with POSIX but should be transparent to existing application code. This routine may set errno to ESRCH. For more information, see the reference entry.
Modified I/O system Device Control APIs
iosDevDelete( ) iosDrvRemove( ) The iosDevDelete( ) and iosDrvRemove( ) APIs now support the device delete callback feature. This is transparent to existing applications. For more information on these routines, see the reference entries and the VxWorks Kernel Programmer's Guide: I/O System.
New I/O System Device Control APIs
There are a few new I/O system device control APIs: int iosDevSuspend (DEV_HDR *); This routine suspends a device from the I/O system device list, making it unavailable to subsequent I/O accesses. int iosDevResume (DEV_HDR *); This routine resumes a suspended device in the I/O system device list, making it available to subsequent I/O accesses again. STATUS iosDevReplace (DEV_HDR *, const char *, int); This routine replaces a device of the same name in the I/O system device list, making the device available for subsequent I/O access. STATUS iosDevDelCallback (DEV_HDR *, FUNCPTR); This routine enables the device delete callback support feature.
98
Draft: 18 Nov 05
4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel 4.11 Changes To VxWorks Components
For more information on these routines, see the reference entries and the VxWorks Kernel Programmer's Guide: I/O System.
Modified Macros and Parameters 4 DELAYTIMER_MAX
The macro DELAYTIMER_MAX has been added to the kernel header file, limits.h. This is defined to take the value _POSIX_DELAYTIMER_MAX.
timer_getoverrun( )
The routine timer_getoverrun( ) has been updated to use the DELAYTIMER_MAX macro instead of _POSIX_DELAYTIMER_MAX. This change occurs both in the kernel and in application mode as the routine is shared by kernel and user.
4.11 Changes To VxWorks Components

VxVMI, dosFS, Wind River PPP, Wind River IPv6, and Wind River System Viewer have changed between VxWorks 5.5 and VxWorks 6.x.
4.11.1 VxFusion No Longer Available

Wind River advises customers who have relied on these facilities to migrate their applications to message channels, which provides superior functionality.
4.11.2 Migrating From VxVMI To RTPs

VxVMI is no longer supported in VxWorks 6.x. It is replaced by RTP support. Table 4-7 compares VxVMI features to those provided in VxWorks 6.x.
Draft: 18 Nov 05
99
Table 4-7
Memory Management Features in VxVMI and VxWorks 6.x
Feature
Supported in VxWorks 6.x
Text write protection Kernel vector table write protection API to map physical to virtual memory API to modify and examine state of virtual memory API to generate report on state of virtual memory Creation of virtual memory contexts
Yes Yes Yes Yes Yes No
In VxWorks 6.x, all of the features shown in Table 4-7 except creation of virtual memory contexts are available as part of the basic virtual memory library, INCLUDE_MMU_BASIC. Creation of virtual memory contexts as implemented for VxVMI is no longer available. This functionality is replaced by creation of processes. Processes in VxWorks 6.x execute in private virtual memory contexts. The behavior of vmBaseStateSet( ) and vmStateSet( ) has changed. Cache attributes: When changing cache attributes, the user must always specify the cacheability and, if supported by the architecture, the guarded and coherency bits together. These are changed using a single mask, MMU_ATTR_CACHE_MSK. The cacheability must be specified with one and only one of the following: MMU_ATTR_CACHE_OFF, MMU_ATTR_CACHE_COPYBACK, or MMU_ATTR_CACHE_WRITETHRU. Protection attributes: In previous releases the protection setting of VM_STATE_WRITABLE changed both supervisor- and user-mode protection. In VxWorks 6.x, supervisor and user protection attributes are set with distinct macros, that is, MMU_ATTR_SUP_RWX and MMU_ATTR_USR_RWX. Validity attribute: No change in behavior.
100
Draft: 18 Nov 05
In VxWorks 6.x, therefore, these states must be changed by first calling vmStateGet( ) to get the current state for the page and then calling vmStateSet( ) or vmBaseStateSet( ) to set the new state. Table 4-8 illustrates the VxVMI APIs and their VxWorks 6.x replacements, when replacements are available.
Table 4-8 VxVMI APIs Mapped to VxWorks 6.x Routines
VxVMI
VxWorks 6.x
vmMap( ) vmTextProtect( ) vmStateSet( ) vmStateGet( ) vmTranslate( ) vmPageSizeGet( ) vmContextShow( ) vmShowInit( ) vmContextCreate( ) vmContextDelete( ) vmCurrentGet( ) vmCurrentSet( ) vmGlobalInfoGet( ) vmGlobalMap( )
vmMap( ) vmTextProtect( )a vmStateSet( ) vmStateGet( ) vmTranslate( ) vmPageSizeGet( ) vmContextShow( ) not available not available not available not available not available not available not available
vmPageBlockSizeGet( ) not available

a. vmTextProtect( ) now takes an argument (BOOL setState)
The type of the parameter specifying the virtual address defined for the routines vmMap( ), vmStateSet( ), vmBaseStateSet( ), vmStateGet( ), and vmTranslate( ) has changed from void * in VxWorks 5.5 to VIRT_ADDR in VxWorks 6.x. VIRT_ADDR is declared as an unsigned integer (UINT32). Depending on the level
Draft: 18 Nov 05
101
of compiler warnings and error checking selected, as well as the toolchain used (the Wind River Compiler or the Wind River GNU Compiler), this change may generate compiler warnings or errors. You must either change the type of variables used in your application to represent virtual addresses or cast them to VIRT_ADDR where required. The type of the parameter specifying the physical address defined for the routines vmMap( ) and vmTranslate( ) has been changed respectively from void * and void ** in VxWorks 5.5 to PHYS_ADDR, and PHYS_ADDR * in VxWorks 6.x. On some architectures (PowerPC and MIPS) PHYS_ADDR is defined as a unsigned long long (64 bit unsigned integer, UINT64), while on the other architectures it is defined as a unsigned integer (32 bit unsigned integer, UINT32). Again, depending on the level of compiler warnings and error checking selected, as well as the toolchain used (the Wind River Compiler or the Wind River GNU Compiler), this change may generate compiler warnings, or errors. You must either change the type of variables used in your application to represent physical addresses, or cast them to PHYS_ADDR where required. For additional information about memory management migration issues, see 2.5.2 Changed Memory Mapping, p.22.
4.11.3 PPP
For more information on migrating from the version of PPP bundled with VxWorks 5.5 to the version included with VxWorks 6.x, see your product getting started.
4.11.4 Wind River System Viewer

wvLib in VxWorks 6.x has been updated to simplify creation of System Viewer logs. It is no longer necessary to create and manage the log header, taskname buffer, and ring buffer as separate entities. Instead, a ring buffer is created and added to a System Viewer log; the log is managed as a single item. Examples are provided in the wvLib documentation, and also in the supplied wvOn( ) and wvOff( ) functions.
102
Draft: 18 Nov 05
APIs Changed
wvUploadStart( ) This function, used to upload System Viewer log data to a host, now takes a pointer to a WV_LOG structure instead of a pointer to a ring buffer.
4 APIs Removed
wvEvtLogInit( ) This is now done when the System Viewer log is created, as part of wvLogCreate( ). wvLogHeaderCreate( ) This is now done when the System Viewer log is created, as part of wvLogCreate( ). wvLogHeaderUpload( ) This whole log is now uploaded as a single entity, rather than in individual pieces, and so this is done as part of wvUploadStart( ). wvTaskNamesPreserve( ) This is now done as part of the System Viewer log creation, in wvLogCreate( ). wvTaskNamesUpload( ) This is now done as part of the System Viewer log upload, by wvUploadStart( ).
Draft: 18 Nov 05
103
104
Draft: 18 Nov 05
5
Migrating Applications to RTPs
5.1 Introduction 105 5.2 Issues In Moving Applications to RTPs 106 5.3 Changes to User APIs For RTPs in VxWorks 6.0 119 5.4 Enhanced Support for POSIX Applications in VxWorks 6.2 121 5.5 Changed Memory Partition Options in VxWorks 6.2 137 5.6 File System-Related Changes in VxWorks 6.2 139 5.7 Component Changes 139
5.1 Introduction
This chapter assumes that you have decided to migrate your application out of the kernel and into a real-time process (RTP). For a discussion of the kernel/RTP decision, see 4.1 Introduction, p.65. This chapter identifies migration steps for key areas. A common definition of a process is a program in execution. VxWorks processes are called real-time processes because they are designed to support the determinism required of real-time systems. For a complete discussion of RTPs, see the VxWorks Application Programmers Guide: Applications and Processes.
105
The following new features are available in RTPs:
memory protected processes new Dinkum (full libc) libraries for RTP space resource reclamation of objects in RTP space shared libraries shared data
5.2 Issues In Moving Applications to RTPs

When migrating an application from the kernel to a real-time process, issues not relevant to a kernel-based application must be considered. The RTP environment offers protection and is thus innately different from the kernel environment where the application originated. This section highlights issues that are not present in kernel mode, or that are different in user mode.
5.2.1 Compiling Code for Both User and Kernel Mode

Much of the VxWorks API is shared between user and kernel modes; however, as this section shows, there are areas where the APIs, or general system capabilities, are different. This is a natural aspect of memory protection and the process model. Provided you are aware of the differences, it should be fairly straightforward to design code that can be moved between the two environments. You may need to compile sections of code slightly differently; this can be accomplished by using the _WRS_KERNEL macro. This macro is set when building kernel code, and is not set when building user-mode code.
void exampleTaskCode (void) { /* ... */ /* now it is time to kill this thread; */ /* the others will keep on running */ #ifdef _WRS_KERNEL exit();
/* This API kills a task in kernel mode */
106
5 Migrating Applications to RTPs 5.2 Issues In Moving Applications to RTPs
#else taskExit(); /* exit() kills the whole process in user mode; use taskExit() instead */ #endif /* _WRS_KERNEL */ }
An alternative is to make use of the __RTP__ macro, which is set when building an RTP.
5
5.2.2 Reducing Library Size

For production RTPs, it may be desirable to create stripped images of included libraries. Shared libraries and dynamic executables can be stripped with the command:
striparch --strip-unneeded
5.2.3 RTP Scope

One of the key aspects of running an application within an RTP is that code running within the RTP can only access memory owned by the RTP. It is not possible for an RTP to access memory directly within another RTPs memory context, or to access memory owned by the kernel. When migrating applications, it is important to bear these restrictions in mind. The following approaches can be helpful.
Communicating Between Applications
Although RTPs are designed to isolate and protect applications, many alternatives exist for communication between RTPs or between RTPs and kernel applications. If large amounts of data need to be shared, either between applications or between an application and the kernel, consider using a shared-memory or shared-data region. The applications that map a given shared-data region into their memory context can specify different access permissions; for instance, the application that creates and initializes the shared data can open it with read and write permissions, while all the consumer applications may open the shared data region with read-only permissions. This provides some level of protection to the shared data. For more information, see the reference entry for sdLib. If your data needs to be more strictly protected and separated from other applications or from the kernel, use inter-process communication mechanisms to
107
pass data between RTPs or between an RTP and the kernel. Common options are public versions of:

semaphores message queues message channels sockets (especially the AF_LOCAL domain sockets) pipes
For more information, see the VxWorks Application Programmers Guide: Multitasking.
Communicating Between an Application and the Operating System
While some applications which are closely coupled with the kernel are not suitable to run in an RTP, this is not necessarily always the case. Consider the whole range of solutions for communicating between applications before reaching a conclusion. In addition to standard inter-process communication methods, the following options are available.
In some cases, the best solution is to architect code that must remain in the kernel as a VxWorks driver. Then open the driver from user mode and use the read/write/ioctl( ) model to communicate with it. Another alternative is to implement a sysctl( ) method. In rare cases, you may decide to add an additional system call. This is the riskiest option as the possibility exists of breaking the protection of either the kernel or of your RTP. For more information, see the VxWorks Application Programmers Guide: Multitasking.
5.2.4 Initialization and Finalization Code in C++

The default method for handling program startup and termination in VxWorks 6.2 remains the same in kernel code, but it has changed for RTP code. For details, see the Wind River Compiler Users Guide: Use in an Embedded Environment. The key points are:
.init$nn and .fini$nn code sections are replaced by .ctors and .dtors sections. .ctors and .dtors sections contain pointers to initialization and finalization functions.
108
Functions to be referenced in .ctors and .dtors can exist in any program module and are identified with __attribute__((constructor)) and __attribute__((destructor)), respectively, instead of the old _STI__nn_ and _STD__nn_ prefixes. The priority of initialization and finalization functions can be specified through optional arguments to the constructor and destructor attributes. Example:
__attribute__((constructor(75))) void hardware_init() { ... // hardware initialization code }
It is recommended that initialization and finalization functions be specified with an explicit priority. If no priority is specified, functions are assigned the lowest (last) priority by default; this default can be changed with -Xinit-section-default-pri. Unless the default is changed, C++ global class object constructors are also assigned the lowest (last) priority.
Linker command (.dld) files for legacy projects must be modified to define .ctors and .dtors sections. For an example, see bubble.dld and the Wind River Compiler Users Guide: Linker Command Language. Old-style .init$nn and .fini$nn sections are still supported, as are _STI__nn_ and _STD__nn_ function prefixes, through the -Xinit-section=2 option.
5.2.5 Eliminating Hardware Access

RTP code executes in user mode. Any supervisor-level access attempt is illegal, and is trapped. Access to hardware devices usually falls into this category. The following are prohibited:
Calling intLock( ) and intUnlock( ) are forbidden. RTP tasks must not lock out interrupts. RTP tasks can lock out preemption using taskRtpLock( ) and taskRtpUnlock( ), but only for tasks within the same RTP. In any case, an RTP cannot preempt another running RTP. Access to devices may be possible depending on the memory map and the mappings for the address area for the device. However, it is a bad idea to access devices directly from user mode even if the device is accessible. Use the standard I/O library APIs: open( ), close( ), read( ), and so forth. Applications can directly access a memory-mapped device in user mode by creating a shared-data region that maps the physical location of the device into the RTP memory space. A private shared-data region can be created if only a
109
single RTP should be accessing the device. For more information, see the VxWorks Application Programmers Guide: Shared Data.
It is also a bad idea to use processor-specific features and instructions in application code. This hampers portability.
5.2.6 No Interrupt Context In RTPs

A real-time process cannot contain an interrupt context. This separation protects the kernel from actions taken within an RTP. It also means that when you migrate an application that used to run in the kernel to an RTP, you must look for routines that require an interrupt context. Modify the code that contains them so that an interrupt is not required.
POSIX Signals
Signal handling in RTPs follows POSIX semantics, not VxWorks kernel semantics. If your existing application used VxWorks signals, you must confirm that the new behavior is what the application requires. For more information, see 5.2.10 POSIX Signal Differences, p.115.
No Watchdogs
The wdLib functions cannot be used in user mode. Replace them with POSIX timers from timerLib as shown in Table 5-1.
Table 5-1 Corresponding wdLib and timerLib Routines
wdCreate( ) Routines
timer_create( ) Routines
wdCreate( ) wdStart( ) wdCancel( ) wdDelete( )
timer_create( ) timer_connect( ) + timer_settime( ) timer_cancel( ) timer_delete( )
There are slight differences in the behavior of the two timers, as shown in Table 5-2.
110
Table 5-2
Differences Between Watchdogs and POSIX Timers
VxWorks wdLib
POSIX timerLib
A function executes in an interrupt context when the watchdog timer expires. The handler executes when the timer expires, right in the context of the system clock tick handler.
A signal handler executes as a response to the timer expiring.

5
A signal handler executes in the context of a task; the handler cannot run until the scheduler switches in the task (which is, of course, based on the task priority). Thus there may be a delay, even though the timeout has expired.
No Drivers
Hardware interface services are provided by the kernel in response to API kernel calls. From an RTP you should access drivers through ioctl( ), system calls, message queues, or shared data. For more information, see 5.2.5 Eliminating Hardware Access, p.109.
5.2.7 I/O Redirection

I/O redirection is possible for the whole RTP, but not for individual tasks in the RTP. The functions ioTaskStdGet( ) and ioTaskStdSet( ) are not available in user mode. You can use dup( ) and dup2( ) instead, but they change the file descriptors for the whole RTP. The POSIX dup( ) and dup2( ) routines have been introduced to VxWorks for manipulation of file descriptor numbers. They are used for redirecting standard I/O to a different file and then restoring it to its previous value when the operations are completed.
Example 5-1 VxWorks 5.5 Method of I/O Redirection /* temporary data values */ int oldFd0; int oldFd1; int oldFd2; int newFd;
111
/* Get oldFd0 oldFd1 oldFd2
the standard file descriptor numbers */ = ioGlobalStdGet(0); = ioGlobalStdGet(1); = ioGlobalStdGet(2);
/* open new file to be stdin/out/err */ newFd = open ("newstandardoutputfile",O_RDWR,0); /* redirect standard IO to new file */ ioGlobalStdSet (0, newFd); ioGlobalStdSet (1, newFd); ioGlobalStdSet (2, newFd); /* Do operations using new standard file for input/output/error */ /* When complete, restore the standard IO to normal */ ioGlobalStdSet (0, oldFd0); ioGlobalStdSet (1, oldFd1); ioGlobalStdSet (2, oldFd2);
This process is easily emulated using dup( ) and dup2( ). Use the dup( ) command to duplicate and save the standard file descriptors upon entry. The dup2( ) command is used to change the standard I/O files and then later used to restore the standard files that were saved. The biggest difference is the need to close the duplicates that were created at the start.
Example 5-2 VxWorks 6.x Method of I/O Redirection /* temporary data values */ int oldFd0; int oldFd1; int oldFd2; int newFd; /* Get oldFd0 oldFd1 oldFd2 the standard file descriptor numbers */ = dup(0); = dup(1); = dup(2);
/* open new file to be stdin/out/err */ newFd = open ("newstandardoutputfile",O_RDWR,0); /* redirect standard IO to new file */ dup2 (newFd, 0); dup2 (newFd, 1); dup2 (newFd, 2); /* Do operations using new standard file for input/output/error */
112
/* When complete, restore the standard IO to normal */ dup2 (oldFd0, 0); dup2 (oldFd1, 1); dup2 (oldFd2, 2); /* close the dupes */ close (oldFd0); close (oldFd1); close (oldFd2);
5.2.8 Process and Task API Differences

This section highlights API changes that affect applications in RTPs.
Task Naming Changed
RTP tasks are named differently from kernel tasks. For VxWorks 6.x, the name of an RTPs initial task is based on the name of the executable file: the letter i is prefixed, the first letter of the filename is capitalized, and the file-name extension is removed. For example, when foobar.vxe is run, the name of the initial task is iFoobar.
Changes in Scope Between Kernel and User Modes
Applications running in an RTP are running in a process. Some APIs have a changed scope within user mode from that they display in kernel mode, typically to match POSIX semantics.
exit( ) in user mode terminates the current process. In kernel mode, exit( ) terminates only the current task. The user-mode behavior of exit( ) causes it to match the POSIX standard. The API taskExit( ) can be used in an RTP instead of exit( ) if you want to kill only the current task. kill( ) in user mode sends a signal to a process. In kernel mode, kill( ) sends a signal only to a specific task. The user-mode behavior of kill( ) causes it to match the POSIX standard. The API taskKill( ) can be used in an RTP instead of kill( ) if you want to send a signal only to a particular task within the RTP. raise( ) in user mode sends a signal to the calling process. In kernel mode, raise( ) sends a signal only to the calling task. The user-mode behavior of raise( ) causes it to match the POSIX standard. The API taskRaise( ) can be used in an RTP instead of raise( ) if you wish to send a signal to the calling task.
113
In addition, if you wish to send a signal to the calling process, the API rtpRaise( ) can be used in an RTP instead of raise( ).
sigqueue( ) in user mode sends a queued signal to a process. In kernel mode, sigqueue( ) sends a queued signal only to a specific task. The user-mode behavior of sigqueue( ) causes it to match the POSIX standard. The API taskSigqueue( ) can be used in an RTP instead of sigqueue( ) if you wish to send a queued signal to a particular task within the RTP. The API rtpSigqueue( ) can be used in an RTP instead of sigqueue( ) if you wish to send a queued signal to a particular RTP.
Task Locking and Unlocking
Task locking is available but is restricted to the tasks of the RTP where the locking or unlocking calls are made. In other words, you cannot provoke a system-wide task lock from within an application. This also means that, while the RTP task that disables the task context switching is ensured not to be preempted by other tasks in this same RTP, it probably will be preempted by other tasks from the kernel or from other applications. The API available for task locking and unlocking in user mode is different from the one available in the kernel. In an application, task locking can be obtained by calling the taskRtpLock( ) API. Task unlocking can be done by calling the taskRtpUnlock( ) API.
Private and Public Objects
The traditional means for inter-task communication used in VxWorks 5.5, such as semaphores and message queues, have been extended such that they can be defined as private or public, as well as named. Private objects are visible only to tasks within a process, whereas public objectswhich must be namedare visible to tasks throughout the system. Public objects can therefore be used for inter-process communication. For more information about public and private objects and about naming, see the VxWorks Application Programmers Guide.
5.2.9 Semaphore Differences

In a real-time process, semaphores are available using the traditional VxWorks API (semTake( ), semGive( ), and so forth). They are known as user-mode semaphores because they are optimized so as to generate a system call only when
114
necessary. The scope of a semaphore object created by a VxWorks application is, however, restricted to the RTP it was created in. In other words, two different applications cannot be synchronized using user-level semaphores. If mutual exclusion or synchronization is required between application, then a public semaphore must be used. A public semaphore can be created using semOpen( ) by assigning a name starting with / (forward slash). There are restrictions on the type of information regarding semaphores available in user-mode. In particular, the semaphore owner and list of tasks pending on a semaphore is not provided by the semInfoGet( ) API. If this information is required, its management must be implemented within the user-mode library itself.
5
5.2.10 POSIX Signal Differences

There are significant differences between signal handling in a kernel environment (in other words, in the equivalent of a VxWorks 5.5 environment) and in the RTP environment. The VxWorks 5.5 kernel signal behavior still holds true for kernel tasks, but in the RTP environment the behavior is both new for VxWorks 6.x, and different from signal behavior in the kernel environment in some respects. The signal model in user mode is designed to follow the POSIX process model. (For more information, see the POSIX 1003.1-2004 specification at http://www.opengroup.org.)
Signal Generation
A kernel task or an ISR can send signals to any task in the system, including both kernel and RTP tasks. An RTP task can send signals to itself, to any task within its RTP, to its RTP, to another RTP, and to any public tasks in another RTP. RTP tasks cannot send signals to kernel tasks. For more information, see Private and Public Objects, p.114.
Signal Delivery
The process of delivering a signal involves setting up the signal context so that the action associated with the signal is executed, and setting up the return path so that when the signal handler returns, the target task gets back to its original execution context.
115
Kernel signal generation and delivery code runs in the context of the task or ISR that generates the signal. RTP signal generation is performed by the sender task, but the signal delivery actions take place in the context of the receiving task.
Scope Of Signal Handlers
The kernel is an entity with a single address space. Tasks within the kernel share that address space, but are really different applications that coexist in that one address space. Hence, each kernel task can individually install a different handler for any given signal. The signal model in user mode follows the POSIX process model. An RTP is a process that executes an application. Tasks that belong to the RTP are equivalent to threads within a process. Therefore, RTP tasks are not allowed to register signal handlers individually. A signal handler is effective for all tasks in a given RTP.
Default Handling Of Signals
By default, signals sent to kernel tasks are ignored (in other words, SIG_DFL in kernel mode means ignore the signals or SIG_IGN). However, by default, signals sent to RTP tasks result in RTP termination (in other words, SIG_DFL for RTP tasks means terminate the RTP).
Default Signal Mask For New Tasks
Kernel tasks, when created, have all signals unmasked. RTP tasks inherit the signal mask of the task that created them. Thus, if a kernel task created an RTP, the initial task of the RTP has all signals unblocked.
Signals Sent To Blocked Tasks
Kernel tasks that receive signals while blocked are immediately unblocked and run the signal handler. After the handler returns, the task goes back to blocking on the original object.
116
Signals sent to a blocked RTP task are delivered only if the task is blocked on an interruptible object. In this case, the blocking system call returns ERROR with errno set to EINTR. After the signal handler returns, it is the responsibility of the task to re-issue the interrupted call if it wishes. Signals sent to RTP tasks blocked on non-interruptible objects are queued. The signal is delivered whenever the task unblocks.
5 Signal API Behavior
Table 5-3 shows APIs that behave differently in the kernel than they do in an RTP.
Table 5-3 Differences in Signal API Behavior
API
Kernel Behavior
RTP Behavior
kill( ) raise( ) sigqueue( )
sends a signal to a task sends a signal to the current task
sends a signal to an RTP sends a signal to the current tasks RTP
sends a queued signal to a task sends a queued signal to an RTP
For more information, see the VxWorks Application Programmers Guide: POSIX Standard Interfaces.
5.2.11 Networking Issues

In the process of porting network applications to RTPs, Wind River has exposed both standard socket APIs and the routing socket APIs at the RTP level. If you have an application that limits (or can be made to limit) its interaction with the network stack to standard or routing socket API calls, that application is a good candidate for porting to run in an RTP. For additional network migration information, see your product getting started. routeAdd( ) is not supported in user mode. In order to make or monitor changes to the routing table from user mode, routeAdd( ) must be replaced by a routing socket. For more information, see Wind River Network Stack Programmers Guide: Routing Sockets for Route Table Events.
117
5.2.12 Header File Differences

RTPs Compared to VxWorks 5.5
The most likely issue to arise when you try to move existing code into user mode is that a header file you used previously is unavailable or no longer contains something you need, and hence your code fails to compile. This may occur commonly when transitioning code and suggests that the feature you are trying to use is not available in user mode. It may be tempting to find the missing header file on the kernel side of the VxWorks tree and use that, but this is unlikely to help. Wind River supplies specific header files for user-mode development in a distinct user-mode part of the directory tree. These header files only supply features that have been designed and tested to work under user-mode protections. If a header file does not exist or exposes less functionality than is available in kernel mode, this is because those features are not available from user mode. Usually these features cannot be implemented in user mode due to the nature of the protection model. For example, layer 2 networking facilities typically access hardware I/O drivers directly; however, this is not allowed within the protected user-mode environment. There is a newly created system for alerting customers to some of the differences between kernel and user modes. The _WRS_DEPRECATED macro is used to tag an API as being deprecated. The Wind River Compiler allows for a message to be applied as well. If the compiler encounters an API tagged as deprecated it issues an immediate warning with the optional message. Many routines, like ioGlobalStdSet( ), that are not available in user mode, generates the following message when using the Wind River Compiler:
fileline ioGlobalStdSet is deprecated not available in RTP.
New or Changed Header Files for VxWorks 6.2
For information on the new header files introduced by POSIX, see New POSIX Header Files, p.133.
118
5 Migrating Applications to RTPs 5.3 Changes to User APIs For RTPs in VxWorks 6.0
5.3 Changes to User APIs For RTPs in VxWorks 6.0

In order to support RTPs, a set of user APIs was introduced in VxWorks 6.0. These routines are based on the VxWorks 5.x routines, but they have specific changes required to support real time processes.
The APIs that make system calls (marked system, system call, or syscall) cannot complete their work without assistance from facilities provided only by the kernel. In RTPs, the routines use POSIX semantics rather than VxWorks semantics.
While additional changes to APIs have occurred since VxWorks 6.0 as the product has developed, it is helpful to compare the earliest differences to highlight the distinction between running an application in the kernel as opposed to an RTP.
5.3.1 APIs Not Present In User Mode

Some APIs are not present in user mode because their action is not compatible with a protected environment.
taskInit( )
The taskInit( ) routine is not available in user mode. Instead, use taskCreate( ).
taskSwitchHookAdd( ), taskSwitchHookDelete( )
Support for adding and deleting task switch hooks in user mode is not supported. Thus the routines taskSwitchHookAdd( ) and taskSwitchHookDelete( ) do not exist in user mode. However, task delete and create hooks are supported in user mode, so the routines taskCreateHookAdd( ), taskCreateHookDelete( ), taskDeleteHookAdd( ), and taskDeleteHookDelete( ) do exist in user mode. For more information, see 5.3.3 APIs That Work Differently In RTPs, p.120.
intLock( ), intUnlock( ), taskLock( ), taskUnlock( )
It is not possible to lock and unlock interrupts from user mode, so intLock( ) and intUnlock( ) are not present in user mode. Similarly, from an RTP it is not possible to globally lock and unlock the scheduler as in done in the kernel by taskLock( ) and taskUnlock( ). You can disable context switching within an RTP using taskRtpLock( ) and taskRtpUnlock( ); the calling task becomes the only task in the RTP that is allowed to execute, unless the task explicitly gives up the CPU by making itself no longer ready. However, tasks in other RTPs may preempt a task
119
locked with taskRtpLock( ). If exclusion between tasks in different RTPs is required, use a public semaphore in place of taskLock( ).
taskOptionsSet( )
There are no user-changeable task options available in user mode, so taskOptionsSet( ) is not present. Also, not all task options are available; in particular, VX_UNBREAKABLE and VX_SUPERVISOR are unavailable in user mode.
Object IDs As Pointers To Memory
In user mode, object IDs such as SEM_ID are no longer pointers to memory. Instead, they are handles typically comprised of a small integer reference number and a generation ID. It is not possible to access the internal structures of objects in user mode.
System Call Validation
All user-mode APIs that are system calls have all arguments and memory addresses validated before the call is allowed to complete.
NOTE: There is no hardware, BSP, or driver access from user-mode. For a list of all
APIs that are present in user-mode, see the reference entries.
5.3.2 APIs Added For RTPs Only

Some new user-mode APIs are available in RTPs only. The largest group of these is the Dinkumware C and C++ libraries. For more information, see the reference entries.
5.3.3 APIs That Work Differently In RTPs

taskCreateHookAdd( ), taskDeleteHookAdd( )
The kernel versions of these routines are unchanged from VxWorks 5.5. However, the user-mode versions are slightly different:
They pass an integer task ID as an argument. They return STATUS instead of void.
120
5 Migrating Applications to RTPs 5.4 Enhanced Support for POSIX Applications in VxWorks 6.2
For more information, see the reference entries for the user versions of taskCreateHookAdd( ) and taskDeleteHookAdd( ). See also 5.3.4 ANSI vs. POSIX API Differences, p.121 and following.
5.3.4 ANSI vs. POSIX API Differences

A few libc functions previously had API definitions that did not match POSIX. These APIs have been updated to use the POSIX definitions. A macro, _VXWORKS_COMPATIBILITY_MODE, has been defined to support the VxWorks 5.5 definitions of these functions. This macro should be set before including string.h or timer.h. The following functions are affected: strerror( ), asctime_r( ), ctime_r( ), gmtime_r( ), localtime_r( ).
5
5.3.5 Kernel Calls Require Kernel Facilities

It is possible to call a user-mode API, even if the kernel component that implements that service has not been compiled into the system. In this case, an error is returned, with errno set to ENOSYS. The solution is to add the appropriate component to the kernel and rebuild VxWorks.
5.3.6 Other API Issues
There is no way to get the task list for all tasks in an RTP. Show routines are not available from user mode.
5.4 Enhanced Support for POSIX Applications in VxWorks 6.2

VxWorks 6.2 incorporates a variety of changes to improve POSIX compliance. This section discusses changes in thread scheduling, in PIs and libraries, in header files, and in components in parameters.
121
5.4.1 POSIX Thread Scheduling

POSIX threads (also known as pthreads) in RTPs are now scheduled according to the POSIX thread scheduling model. This means that pthreads and VxWorks threads behave like each other in some circumstances and differently in others. In order to maintain the real-time behavior of VxWorks, all tasks must be handled by the same scheduler. However, their behavior is affected not only by the scheduler itself but by the scheduling policy they declared at creation.
Table 5-4 Task and Thread Behavior in the Kernel and RTPs
Execution Environment
VxWorks Native Schedulera
POSIX Schedulerb
Kernel RTP
Tasks and pthreads both behave like VxWorks tasks. Only tasks are permitted; pthreads are not supported.
Tasks and pthreads both behave like VxWorks tasks. Tasks behave like VxWorks tasks; pthreads behave as normal POSIX threads.
a. INCLUDE_VX_NATIVE_SCHEDULER b. INCLUDE_POSIX_PTHREAD_SCHEDULER
POSIX threads in RTPs can therefore be scheduled according to the POSIX scheduling schemes: SCHED_RR, SCHED_FIFO, and SCHED_OTHER policies can now be concurrently used in user space. The SCHED_RR and SCHED_FIFO are comparable to VxWorks round-robin and priority scheduling policies but differ in some details. The SCHED_OTHER policy is now supported and is the equivalent of the native VxWorks scheduling policy. Practically speaking, SCHED_OTHER means that a thread is handled strictly as a VxWorks task by the scheduler. The VxWorks native round-robin policy does not affect POSIX threads using the SCHED_RR or SCHED_FIFO policies but does affect POSIX threads created with the SCHED_OTHER policy. For more information on pthread scheduling, see New Components and Parameters, p.136 and the VxWorks Application Programmers Guide: POSIX Standard Interface. The backward compatibility impacts of the different schedulers and policies can be summarized in Table 5-5 and Table 5-6. The first table addresses the case where the pre-6.2 application using POSIX threads is recompiled and now uses the VxWorks 6.2 pthread library in an RTP.
122
Table 5-5
Pre-VxWorks 6.2 POSIX Application Recompiled for VxWorks 6.2 RTP
Previously Used Scheduling Policy
SCHED_OTHER
SCHED_FIFO
SCHED_RR
VxWorks native
SCHED_FIFO SCHED_RR
No impact a N/A N/A
N/A Impact b N/A
N/A N/A Impact b

5
a. No impact: the customer was already using the current native scheduling policy. b. Minimal behavioral impact due to the usage of the POSIX thread scheduler or ENOSYS/EINVAL error if the POSIX scheduler is not configured.
The second table addresses the case where the pre-6.2 application using POSIX threads is used as-is in binary form on a VxWorks 6.2 system. !
CAUTION: There is no guarantee in VxWorks 6.2 that previous 6.x application binaries will be fully functional; rebuilding is recommended.
Previous 6.x POSIX Binary Executed in a VxWorks 6.2 RTP
Table 5-6
Previously Used Scheduling Pure Policy Priority
VxWorks Scheduler Round Robin
POSIX Thread Scheduler SCHED_FIFO SCHED_RR
VxWorks native
SCHED_FIFO SCHED_RR
No impact a No impact c N/A d
No impact a N/A d No impact f
No impact b Impact e N/A
No impact b N/A Impact e
a. No impact: applications were already using the current native scheduling policy. b. No impact: threads are handled like VxWorks tasks. c. No impact: SCHED_FIFO was handled via VxWorks's pure priority scheduling policy already. d. This creates an immediate failure in VxWorks 6.x, so applications cannot use this combination. e. Minimal behavioral impact due to the usage of the POSIX scheduler. f. No impact: SCHED_RR was already handled using VxWorks's round robin scheduling policy.
123
5.4.2 POSIX-Related Changes in Libraries and APIs

New POSIX APIs
New POSIX APIs are now supported in RTPs:

System Configuration
uname( ), sysconf( ) The uname( ) function depends on information provided in part by the processor abstraction layer (PAL) and the BSP. It is not guaranteed that all processor architecture support code or all BSPs provide the required information. This does not prevent uname( ) from functioning but some information (machine name, processor endianness, CPU family) may be reported as unknown. The uname.vxe sample program shipped in this product makes it possible for custom BSP providers to easily check whether the required information is correctly set.
Input/Output
access( ), aio_fsync( ), chmod( ), fcntl( ), fdatasync( ), fpathconf( ), fsync( ), link( ), pathconf( ). The I/O functions can be guaranteed to perform fully only if the underlying file system device driver supports the operations they command. In VxWorks 6.2 only the HRFS file system is guaranteed to do so. (For more information on HRFS, see 4.9.2 HRFS, p.91 and the VxWorks Application Programmers Guide: Local File Systems.) In this implementation fcntl( ) supports only a limited set of operations: F_DUPFD, F_SETFL, and F_GETFL. As is the case for the other I/O functions, these operations can be executed only if the underlying file system device driver supports them.
POSIX threads
pthread_atfork( ), pthread_setschedprio( ) Note that pthread_atfork( ) is only provided for conformity with the PSE52 profile described by IEEE Std 1003.13-2003. However because the PSE52 profile does not support fork( ) or the exec( ) family of functions, pthread_atfork( ) always returns -1 in this implementation.
124
Changes in Existing POSIX APIs
A set of POSIX routines has been modified to better comply with the POSIX standard. These changes include simple stylistic changes in the prototype declarations and changes in the routine documentation, as well as in-depth behavior changes that might affect backward compatibility. These changed APIs are listed here.
POSIX Threads APIs
pthread_attr_init( ) The default scheduling policy is now SCHED_OTHER (which is equivalent to the current VxWorks native scheduling policy) instead of SCHED_RR. For more information, see the reference entry. pthread_attr_getdetachstate( ) This routine now returns the EINVAL error code if either the pAttr parameter or the pDetachState parameter is not valid. pthread_attr_getname( ) This routine now returns the EINVAL error code if either the pAttr parameter or the name parameter is not valid. pthread_attr_getopt( ) This routine now returns the EINVAL error code if either the pAttr parameter or the pOptions parameter is not valid. pthread_attr_getschedpolicy( ) For more information, see 5.4.1 POSIX Thread Scheduling, p.122 and the reference entry. pthread_attr_setscope( ) This routine now returns the ENOTSUP error code, instead of EINVAL, for the PTHREAD_SCOPE_PROCESS contention scope. For more information, see the reference entry. pthread_attr_getstackaddr( ) This routine now returns the EINVAL error code if either the pAttr parameter or the ppStackAddr parameter is not valid. pthread_attr_getstacksize( ) This routine now returns the EINVAL error code if either the pAttr parameter or the pStackSize parameter is not valid.
125
pthread_attr_setdetachstate( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_setname( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_setopt( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_setstacksize( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_setstackaddr( ) This routine now returns the EINVAL error code if the pAttr parameter is not valid. pthread_attr_setschedpolicy( ) For more information, see 5.4.1 POSIX Thread Scheduling, p.122 and the reference entry. pthread_cond_timedwait( ) This routine now returns the EPERM error code, instead of EINVAL, when the caller is not the owner of the mutex associated with the condition variable. For more information, see the reference entry. pthread_cond_wait( ) This routine now returns the EPERM error code, instead of EINVAL, when the caller is not the owner of the mutex associated to the condition variable. For more information, see the reference entry. pthread_create( ) This routine now honors the creation of pthreads scheduled by one of the POSIX policies (SCHED_RR, SCHED_FIFO, or SCHED_OTHER) regardless of the current VxWorks native scheduling policy. It no longer returns the ENOTTY error code but it does return the ESRCH and ENOSYS error codes. For more information, see the reference entry. pthread_getschedparam( ) This routine may now return the ENOSYS error code. For more information, see the reference entry.
126
pthread_setschedparam( ) It is now possible to change the scheduling policy of a running pthread to one of the POSIX policies (SCHED_RR, SCHED_FIFO, or SCHED_OTHER) regardless of the current VxWorks native scheduling policy. This routine may now return the ENOSYS error code. For more information, see the reference entry.
POSIX Semaphore APIs 5
sem_init( ) The API has been changed from:

int sem_init (sem_t *, int, unsigned int);
to:
int sem_init (sem_t *, int, unsigned);
This is to conform with POSIX. There is no functional change. For more information, see the API reference entry. sem_open( ) This routine now systematically checks for too-long semaphore names and sets errno to the ENAMETOOLONG error code. For more information, see the reference entry. sem_unlink( ) This routine now systematically checks for too-long semaphore names and sets errno to the ENAMETOOLONG error code. For more information, see the reference entry.
POSIX Message Queue APIs
mq_open( ) This routine now systematically checks for too-long message queue names and sets errno to the ENAMETOOLONG error code. For more information, see the reference entry. mq_receive( ) The API has been changed from:
ssize_t mq_receive (mqd_t, void *, size_t, int);
to:
ssize_t mq_receive (mqd_t, void *, size_t, unsigned);
This is to conform with POSIX. There is no functional change. For more information, see the reference entry.
127
mq_send( ) The API has been changed from:

int mq_send (mqd_t, const void *, size_t, int);
to:
int mq_send (mqd_t, const char *, size_t, unsigned);
This is to conform with POSIX. There is no functional change. For more information, see the reference entry. mq_unlink( ) This routine now systematically checks for too-long message queue names and sets errno to the ENAMETOOLONG error code. For more information, see the reference entry.
POSIX Signal APIs
kill( ) The API has been changed from:

int kill (RTP_ID, int);
to:
int kill (pid_t, int);
This is to conform with POSIX. There is no functional change. This routine sets errno to ESRCH. The reference entry has been updated. signal( ) This routine can no longer set errno to EFAULT. For more information, see the reference entry. sigqueue( ) The API has been changed from:
int sigqueue (int, int, const union sigval);
to:
int sigqueue (pid_t, int, const union sigval);
This change is to conform with POSIX. There is no functional change. sigtimedwait( ) The API has been changed from:
int sigtimedwait (const sigset_t, struct siginfo, const struct timespec);
128
to:
int sigtimedwait (const sigset_t, siginfo_t, const struct timespec);
This change is to conform with POSIX but is transparent to existing application code. sigwaitinfo( ) The API has been changed from
int sigwaitinfo (const sigset_t, struct siginfo);
to:
int sigwaitinfo (const sigset_t, siginfo_t);
This change is to conform with POSIX but is transparent to existing application code. This routine may set errno to ESRCH. For more information, see the reference entry.
POSIX Timer APIs
alarm( ) The API has been changed from:

unsigned int alarm (unsigned int);
to:
unsigned int alarm (unsigned);
This change is to conform with POSIX. There is no functional change. pause( ) The API has been changed from:
STATUS pause (void);
to:
int paus (void);
sleep( ) The API has been changed from:

unsigned int sleep (unsigned int);
to:
unsigned int sleep (unsigned);
This change is to conform with POSIX. There is no functional change.
129
POSIX I/O APIs
isatty( ) The API has been changed from:

BOOL isatty (int);
to:
int isatty (int);
This change is to conform with POSIX but is transparent to applications because the VxWorks BOOL type is an integer. ioctl( ) ioctl( ) is now a library call instead of a system call. The API has been changed from:
int ioctl (int, int, int);
to:
int ioctl (int, int, ...);
This change is to conform with POSIX. Although it is now possible to call ioctl( ) with a variable number of arguments, only three argument are supported in this implementation. This routine may now set errno to the new error code ENXIO. For more information, see the reference entry. open( ) open( ) is now a library call instead of a system call. The API has been changed from:
int open (const char *, int, int);
to:
int open (const char *, int, ...);
This change is to conform with POSIX and is transparent to applications. This routine now supports the O_DSYNC and O_RSYNC flags. For more information, see the reference entry. read( ) The API has been changed from:
int read (int, char *, size_t);
to:
ssize_t read (int, void *, size_t);
This change is to conform with POSIX but is transparent to existing application code. Any pointer can convert to a void pointer without an explicit type cast.
130
This system call may now set errno to ENXIO. For more information, see the reference entry. rename( ) This routine is now part of fsPxLib instead of ioLib. The reference entry has been updated. unlink( ) This routine is now part of fsPxLib instead of ioLib. write( ) The API has been changed from:
int write (int, char *, size_t);
to:
ssize_t write (int, const void *, size_t);
This change is to conform with POSIX. This system call sets errno to ENXIO. For more information, see the reference entry.
POSIX File System APIs
mkdir( ) The API has been changed from:

STATUS mkdir (const char *);
to:
int mkdir (const char *, mode_t);
This change is to conform with POSIX. For more information, see the reference entry.
libc API
clock( ) This routine is not supported on VxWorks. It now always returns -1.
ISO C APIs
malloc( ) and calloc( ) The definition of the S_memLib_NOT_ENOUGH_MEMORY error status code has been changed to match the value of the standard ENOMEM definition. This ensures that the memory allocation routines such as the standard malloc( ) and calloc( ) routines set errno to the standard error status code when an out-of-memory condition is detected. At the same time, backward compatibility is maintained for applications that check errno against the
131
VxWorks-specific S_memLib_NOT_ENOUGH_MEMORY definition as S_memLib_NOT_ENOUGH_MEMORY and ENOMEM are fully interchangeable. _exit( ) The API has been changed from:
int _exit (int);
to:
void _exit (int);
This change is to conform with POSIX and may cause compiler errors in applications that declare a prototype for _exit( ).
POSIX Scheduling APIs
sched_getpriority_max( ) and sched_getpriority_min( ) These routines now accept the SCHED_OTHER policy instead of returning an error. For this reason, these routines no longer set errno to EINVAL. sched_rr_get_interval( ) This routine now works even if the scheduler is not set in round-robin mode. It is possible to get an interval of 0 second and 0 nanosecond, which indicates that the native VxWorks scheduler is in place and that it is not set in round-robin mode.
Changes to Existing Non-POSIX APIs
getOptServ( ) This routine now returns an int instead of a STATUS but there is no functional change. memPartAlloc( ) This routine now sets errno to ENOMEM instead of S_memLib_NOT_ENOUGH_MEMORY. At the same time, backward compatibility is maintained for applications that check errno against the VxWorks-specific S_memLib_NOT_ENOUGH_MEMORY definitions S_memLib_NOT_ENOUGH_MEMORY and ENOMEM are fully interchangeable.
132
5.4.3 POSIX-Related Header File Changes

New POSIX Header Files
The directory installDir/vxworks-6.2/target/usr/h/sys now includes the following new header files.
usr/h/sys/time.h
This header file declares the type struct timeval which was originally declared in usr/h/time.h. Because POSIX does not allow usr/h/time.h to make the symbols from usr/h/sys/time.h visible, applications using the struct timeval type must now also include usr/h/sys/time.h.
usr/h/sys/select.h
The header file usr/h/sys/select.h declares the prototype of the select( ) API which was originally declared in the VxWorks-specific usr/h/selectLib.h header file. Applications using the select( ) function must now also include usr/h/sys/select.h.
usr/h/sys/wait.h
The header file usr/h/sys/wait.h replaces the header file header file usr/h/wait.h. For backward compatibility, the header file usr/h/wait.h still exists; its only function is to include usr/h/sys/wait.h. The usr/h/wait.h version is deprecated.
usr/sys/utsname.h
The header file usr/sys/utsname.h is used in conjunction with the uname( ) routine.
New Version Header File usr/h/version.h
The header file installDir/vxworks-6.2/usr/h/version.h has been added. It provides the macros _WRS_VXWORKS_MAJOR, _WRS_VXWORKS_MINOR, and _WRS_VXWORKS_MAINT, which respectively define the major number, minor number, and maintenance number of the OS release. These macros should only be used in preprocessor' conditional compilation statements when the code being compiled might be different based on the release of VxWorks. However the
133
uname( ) routine should be used for runtime determination of the VxWorks release and all situations in which the application code cannot be recompiled.
Changes In Existing POSIX Header Files
A set of POSIX header files has been modified to better comply with POSIX. The changes listed here affect backward compatibility.
usr/h/limits.h
This header file has undergone a complete overhaul. Now the minimum values macros are POSIX-compliant; however, the runtime invariant values macros reflect what is supported on VxWorks. The macro DELAYTIMER_MAX is now defined and used by timer_getoverrun( ). For more information, see the sysconf( ) reference entry.
usr/h/math.h
This header file now defines a set of math constants: M_E, M_LOGE, M_LOG10E, M_LN2, M_LN10, M_PI, M_PI_2, M_PI_4, M_1_PI, M_2_PI, M_2_SQRTPI, M_SQRT2, M_SQRT1_2, MAXFLOAT.
usr/h/pthread.h
This header file no longer includes vxWorks.h, signal.h, or timers.h. However, it does now include unistd.h, limits.h, and time.h. The prototypes of pthread_kill( ) and pthread_sigmask( ) have been moved to signal.h. Applications using pthread_kill( ) or pthread_sigmask( ) must now include signal.h. Applications that previously obtained VxWorks native types and macro definitions from pthread.h must now include vxWorks.h and timers.h. The macro _POSIX_THREAD_PROCESS_SHARED is now defined in unistd.h and has the value -1, meaning it is an unsupported feature. The following macros are now defined in unistd.h and have the value 200112L, meaning they are supported features:
_POSIX_THREAD_PRIORITY_SCHEDULING _POSIX_THREAD_PRIO_INHERIT _POSIX_THREAD_PRIO_PROTECT _POSIX_THREAD_ATTR_STACKSIZE _POSIX_THREAD_ATTR_STACKADDR
134
usr/h/sched.h
This header file no longer includes timers.h; however, it now includes time.h. Applications that previously obtained VxWorks native types and macro definitions from sched.h must now include timers.h.
usr/h/signal.h
This header file now defines the SI_USER macro. Function prototypes have been moved here from pthread.h. For more information, see usr/h/pthread.h, p.134.
usr/h/stdio.h
This header file now defines the constants L_ctermid and P_tmpdir. It also declares the prototypes for ctermid( ), flockfile( ), fseeko( ), ftello( ), ftrylockfile( ), funlockfile( ), getc_unlocked( ), getchar_unlocked( ), pclose( ), popen( ), putc_unlocked( ), putchar_unlocked( ), tempnam( ). While these routines are now defined, they are not supported in this release.
usr/h/strings.h
This header file no longer includes string.h. Applications that use functions such as bcopy( ) and strcmp( ) must now include string.h in addition to strings.h.
usr/h/time.h
This header file no longer includes vxWorks.h. Applications that previously obtained VxWorks native types and macro definitions from time.h must now include vxWorks.h.
usr/h/unistd.h
This header file no longer includes vxWorks.h. Applications that previously obtained VxWorks native types and macro definitions by including unistd.h must also include vxWorks.h. This header file has undergone a complete overhaul. It now defines the set of POSIX options and option groups that are supported, or not, on VxWorks. In addition, macro definitions have been moved here from pthread.h. For more information, see usr/h/pthread.h, p.134 and the reference entries for sysconf( ), pathconf( ), and fpathconf( ).
135
5.4.4 POSIX Configuration Components and Parameters

New Components and Parameters INCLUDE_POSIX_PTHREAD_SCHEDULER
The pthread scheduling in RTPs now requires the usage of the INCLUDE_POSIX_PTHREAD_SCHEDULER component in the OS image. For more information, see the VxWorks Application Programmers Guide: POSIX Standard Interface.
POSIX_PTHREAD_RR_TIMESLICE
The timeslice value for the SCHED_RR policy applied to pthread scheduling in RTPs can be changed using the POSIX_PTHREAD_RR_TIMESLICE parameter. For more information, see the VxWorks Application Programmers Guide: POSIX Standard Interface.
Changed Configuration Parameters RTP_SIGNAL_QUEUE_SIZE
This configuration parameter defines the number of queued signals supported in an RTP. The default value for this configuration parameter has changed from 16 to 32 to support POSIX PSE52 and SCA. For a system that supports POSIX-conforming RTP applications, this configuration parameter should be set to 32 or above. Any value less than 32 makes the signal queuing non-conforming to POSIX.
RTSIG_MAX
The RTSIG_MAX value is defined to be 7 in VxWorks 6.2, which does not conform to the POSIX PSE52 expected value of 16. The POSIX standard also expects the SIGRTMIN and SIGRTMAX range to correspond to RTSIG_MAX; currently, the range is set to 23-29, corresponding to the maximum RTSIG_MAX value of 7 rather than to the expected value of 16.
SIGQUEUE_MAX
The routine sysconf( ) that returned the SIGQUEUE_MAX value now returns a value of _POSIX_SIGQUEUE_MAX (defined to be 32) for VxWorks 6.2.
136
5 Migrating Applications to RTPs 5.5 Changed Memory Partition Options in VxWorks 6.2
Addition of sysctl Identifiers KERN_VERSION
The KERN_VERSION sysctl identifier now reports the kernel version string instead of the OS version string. The OS version information is now obtained via the KERN_OSTYPE, KERN_OSRELEASE, KERN_OSREV and KERN_OSBUILDDATE identifiers as documented in sysctlLib.
5.5 Changed Memory Partition Options in VxWorks 6.2

This section provides a summary of the memory of new and changed memory partition options for VxWorks 6.2. For more information about the memory partition error handling options see the reference entry for the memPartLib application library, as well as the kernel and application versions of memPartOptionsSet( ) and memOptionsSet( ). For more information about the error detection and reporting facility and policy handlers see the VxWorks Kernel Programmer's Guide: Error Detection and Reporting.
5.5.1 New Options

In VxWorks 6.2, the following new memory partition options have been added to memPartLib.c and memLib.c:
MEM_ALLOC_ERROR_EDR_FATAL_FLAG
Inject a fatal event when there is an error in allocating memory.

MEM_ALLOC_ERROR_EDR_WARN_FLAG
Inject an warning when there is an error in allocating memory.

MEM_BLOCK_ERROR_EDR_FATAL_FLAG
Inject a fatal event when there is an error in freeing or reallocating memory.

MEM_BLOCK_ERROR_EDR_WARN_FLAG
Inject a non-fatal event when there is an error in freeing or reallocating memory. Enabling the error detection and reporting-specific options does not require the infrastructure to be enabled. However, when error detection and reporting is
137
enabled, these flags provide additional debug capability, such as call stack trace information.
5.5.2 Deprecated Options

The following options are deprecated.
MEM_ALLOC_ERROR_SUSPEND_FLAG
Suspend the task when there is an error in allocating memory, unless the task was spawned with the VX_UNBREAKABLE option.
MEM_BLOCK_ERROR_SUSPEND_FLAG
Suspend the task when there is an error in freeing or reallocating memory, unless the task was spawned with the VX_UNBREAKABLE option.
5.5.3 Changed Default Options

In application space (that is, in RTPs), the default memory partition options have been changed as follows:
Table 5-7 Default Memory Partition Options Compared to Prior Versions
VxWorks 6.2
Prior Versions
MEM_ALLOC_ERROR_LOG_FLAG MEM_ALLOC_ERROR_EDR_WARN_FLAG MEM_BLOCK_CHECK MEM_BLOCK_ERROR_LOG_FLAG MEM_BLOCK_ERROR_EDR_FATAL_FLAG
MEM_BLOCK_CHECK MEM_BLOCK_ERROR_LOG_FLAG MEM_BLOCK_ERROR_SUSPEND_FLAG
The change from MEM_BLOCK_ERROR_SUSPEND_FLAG to MEM_BLOCK_ERROR_EDR_FATAL_FLAG has the following consequences:
When the error detection and reporting infrastructure is not enabled, the process is deleted. When the error detection and reporting infrastructure is enabled in deployed mode, the process is deleted.
138
5 Migrating Applications to RTPs 5.6 File System-Related Changes in VxWorks 6.2
When the error detection and reporting infrastructure is enabled in lab mode, the process is stopped.
5.5.4 Restoring Prior Options

If you prefer to use the default memory partition options of previous releases, memOptionsSet( ) can be used for the heap memory partition. For example: memOptionsSet (MEM_ALLOC_ERROR_LOG_FLAG | MEM_BLOCK_CHECK | MEM_BLOCK_ERROR_LOG_FLAG | MEM_BLOCK_ERROR_SUSPEND_FLAG);
5
5.6 File System-Related Changes in VxWorks 6.2

The extensive changes to file systems for VxWorks 6.2 have changed the kernel interface to the file systems. However, access to file systems from RTPs is essentially unchanged from VxWorks 6.1. When moving applications to an RTP, you must make sure that the moved code does not attempt to format. Any code that does should stay in the kernel. diskInit( ) is deprecated and prints an error when used. diskFormat( ) is deprecated. For this release, it prints a warning but proceeds with formatting the device for dosFs. dosfsDiskFormat( ) is new to VxWorks 6.2; it replaces diskInit( ) and diskFormat( ). However, it cannot be used from an RTP and generates an error.
5.7 Component Changes

5.7.1 RTPs Replace VxVMI
The process model used in VxWorks 6.x automates much of the virtual context management previously provided by VxVMI.
139
In VxWorks 6.x each process (RTP) runs in its own private virtual memory context. The context is automatically created when the process is started, and automatically deleted when the process is deleted. The virtual memory context is also automatically switched when tasks of different processes are swapped. None of the vmBaseLib routines are available to user-mode applications; they are restricted to kernel applications. If your application uses vmStateSet( ) or vmBaseStateSet( ) to modify the access or cache attributes of existing mapping, your application must be modified to use mprotect( ) directly when migrated to an RTP.
5.7.2 PPP
PPP cannot be included in an RTP; it must be part of the kernel. For more information, see your product getting started.
5.7.3 Network Clients and Servers

Network clients and servers are RTP-capable. For more information, see your product getting started.
5.7.4 System Viewer

The only System Viewer function available in an RTP is wvEvent( ). System Viewer logs must be created and managed in the kernel.
140
A
Migrating Applications From VxWorks AE to VxWorks 6.x
A.1 Introduction 141 A.2 Changes 141 A.3 Compiler 147 A.4 User and Kernel APIs 147
A.1 Introduction
This document provides information on differences and migration issues between VxWorks AE and VxWorks 6.x. The focus of this document is on the VxWorks runtime. Host migration information is not discussed here.
A.2 Changes
This section highlights the areas of change between VxWorks AE and VxWorks 6.x.
141
A.2.1 Application Model

VxWorks 6.x provides a different application model from VxWorks AE. The protection domain model of VxWorks AE is replaced by the real-time process (RTP) model of VxWorks 6.x. The VxWorks AE protection domain model provided users with the ability to load or unload modules from within the domain and to spawn or terminate tasks from remote domains. VxWorks AE application files are different from VxWorks 6.x application executables. In AE, a protection domain may be created empty (as a container) and the user may choose to load code modules into the domain. Once all code is loaded into the domain, the user specifies the initialization routine to run for the application domain and the application starts executing. For deployed systems, VxWorks AE applications are built and their symbols resolved against VxWorks at build time. When the system boots, the application symbols are fully resolved and no undefined references exist. In VxWorks 6.x, the RTP model combines all the load and run steps of the VxWorks AE protection domain model. An application in 6.0 is a fully linked executable that is loaded and run in one step. Dynamically loading modules into an application space is no longer allowed in VxWorks 6.x. Once the application is loaded, execution immediately begins at the entry point. The entry point to the application is defined as the main( ) routine of the application. An application stays active until the last task in the RTP terminates. With the introduction of the RTP model in VxWorks 6.x, all protection domain APIs are obsolete.
A.2.2 Memory Model

The memory model in VxWorks AE is different from VxWorks 6.x. The key difference is in the overlapped versus non-overlapped memory map. In VxWorks AE, application memory is overlapped in virtual space. All applications have the same start and end virtual addresses for their spaces. Thus, memory addresses used by one application may be the same for another application, but the memory context for each of these application is different. In other words, the same virtual page of memory in application A maps to a different physical address than in application B. This model enables the application to allocate as much memory as available in the physical space and up to the size of the overlapped virtual space.
142
A Migrating Applications From VxWorks AE to VxWorks 6.x A.2 Changes
In VxWorks 6.x, applications are not overlapped. Each application has its own unique address in the virtual space. An address in application A is never the same as an address in application B, unless the address is in a shared memory region or in a shared library.
A.2.3 Entry Points

The VxWorks AE concept of entry points and the linkage table has been removed from VxWorks 6.x. Instead, the concept of system calls is used to export kernel APIs to RTPs. VxWorks AE allowed users to restrict or export kernel routines to protection domains by setting or unsetting these routines as entry points in the CDF files. The majority of the kernel routines were exported, but certain routines, such as hardware access routines, were restricted from being exported. For ease of portability to protection domains, the APIs for these exported routines are the same for both the kernel and the application. VxWorks 6.x exports only a restricted set of kernel routines as system calls. For more information on exported kernel routines, see the reference entries for user-mode APIs. It is not possible to migrate the entry point information in the CDF components to VxWorks 6.x. You must take the list of kernel-exported routines that were defined as entry points and validate whether these routines are defined as system calls. If you require a kernel routine in your RTP that does not have a system call, you may be able to use another technique for communication with the kernel. See 5.2.3 RTP Scope, p.107. It may be necessary to create the system call handlers for the routine as shown in the VxWorks Kernel Programmers Guide: Kernel. For any entry points that were newly created for your VxWorks AE application, it may also be necessary to follow this procedure.
A
A.2.4 Memory Management

The memory management layers in VxWorks AE and VxWorks 6.x are similar. VxWorks 6.x has adopted some of the memory management libraries from VxWorks AE, but there are differences.
143
Similarities
The VxWorks 6.x heap allocator is based on the VxWorks AE code base. Both use a best-fit algorithm to provide better and more deterministic memory allocations. Many of the VxWorks AE virtual memory routines are also available with VxWorks 6.x, as the code base is very similar. The kernel memory context is included in the application memory context. This makes for faster accesses when performing system calls into the kernel, as no switching of mappings is required; only a change from user to supervisor mode is needed.
Differences
In VxWorks AE, the virtual address space is categorized into four parts: shared library, shared data, kernel, and the application. Certain areas are reserved in the address space for application and kernel memory. All remaining virtual memory can be used for shared-data regions and shared-libraries. Thus memory for applications is contiguous in virtual space. In VxWorks 6.x, the kernel address space is derived from the entries defined in sysPhysMemDesc[ ]. The rest of the address space is available for user-mode allocations: user-mode application text and data, user-mode application heap and task stack, shared libraries, and shared data regions. An applications memory may not be contiguous and its memory may span the whole of the virtual address space; in other words, the text segment may be in one range and the stacks for user tasks may be in another.
Each shared data region and shared library in VxWorks AE has its own memory context. In VxWorks 6.x, these entities are not standalone; they do not have a memory context associated with them. In order for a shared data region or a shared library to exist, an application must be attached to it. Otherwise, the shared-data region or shared library is removed from the system. VxWorks AE had a system page mapped and aliased into each application that allowed the kernel to store read-only kernel data in this page, enabling faster read of the kernel data without incurring a trap into the kernel. taskIdCurrent( ) is an example. In VxWorks 6.x, there is no such system page. Access to taskIdCurrent( ) in user mode is through a local copy of the ID stored in the application heap.
144
A Migrating Applications From VxWorks AE to VxWorks 6.x A.2 Changes
The region information file within the BSP, region.sdf, is no longer used in VxWorks 6.x to describe the memory maps for a specific BSP, or how virtual or physical memory is to be used and assigned. You must use the sysPhysMemDesc[ ] structure in sysLib.c of the BSP to describe the kernel mappings. Virtual space available to user-mode applications, shared libraries, and shared-data regions is derived from this data structure and corresponds to the virtual space remaining. Some architectures may restrict even further the amount of virtual space available to applications (MIPS, SH, and simulators, for example) or where this virtual space is located. As a consequence, VxWorks 6.x does not provide the rgnLib APIs. VxWorks AE provided the functionality whereby physical memory could be specifically reserved for use by certain applications. This was made possible by creating and assigning physical page pools to specific applications, in conjunction with the definition of the corresponding memory regions in region.sdf. In VxWorks 6.x, the system is simplified, and assigning physical page pools to specific applications is no longer allowed. VxWorks 6.x only provides one physical page pool that describes the RAM; all allocations of RAM pages come from this one physical page pool. RAM is divided into only two parts, one for kernel and one for user-mode use.
In VxWorks AE, the region.sdf file describes how the RAM is being divided between the kernel and the user-mode applications, shared libraries, and shared-data regions. VxWorks 6.x uses a single configuration parameter, KERNEL_HEAP_SIZE, to split the RAM between kernel use and user-mode use: the RAM located between the end of the kernel heap (derived from KERNEL_HEAP_SIZE) and sysMemTop( ) is assigned to user-mode use, including RTPs, shared libraries, and shared-data regions. With VxWorks AE, the initial size of the protection domain heap, as well as whether it can grow, corresponds to parameters passed to the routine rtpSpawn( ) or to some of the protection domain attributes that can be set through the project facility. VxWorks 6.x uses environment variables to specify the initial size of the RTP heap as well as whether or not it can grow. (For more information, see VxWorks Application Programmers Guide: Memory Management.) VxWorks AE provides published APIs for the page pool (pgPoolLib), the page pool list (pgPoolLstLib), typed memory partitions (memAttrLib), and page manager objects (pgMgrLib). These APIs are available for kernel applications and protection domain applications.
145
VxWorks 6.x also uses page pools and page managers internally. However, none of these APIs is published and therefore should not be used with kernel applications in VxWorks 6.x. In addition, VxWorks 6.x has no concept of page pool lists or typed memory partitions: pgPoolLstLib and memAttrLib APIs are not available.
VxWorks AE provides for the pgMgrLib routines to manage the application space on a page basis. VxWorks 6.x provides the mmap( ), munmap( ), and mprotect( ) routines instead. VxWorks AE memory partitions can be created with the options MEM_GROW_ENABLE or MEM_RECLAIM_ENABLE. These options are not available with VxWorks 6.x. The MMU attribute MMU_ATTR_IO exists only in VxWorks AE. It is not available in VxWorks 6.x.
A.2.5 Module Management

Certain module management features in the loader that were available in VxWorks AE are not available in VxWorks 6.x. The following is a list of these features.
Out-of-order loading, where code modules for an application may be loaded in any order and the loader tracks the symbol references between code modules. The load-and-run feature, where modules are loaded and then executed after loading. Loading modules into an application (a protection domain), either by the kernel or by another application. malLib support, a module access layer that is the abstraction layer between the loader and the I/O system, is no longer provided. VxWorks AE had private sections that described the application modules. VxWorks 6.x does not have these private sections. VxWorks AE application .o modules cannot be run on a VxWorks 6.x kernel.
A.2.6 CDF Components

VxWorks AE has a component model where all .o modules are described in CDF components. There is no linking to library archives and the build mechanism relies
146
A Migrating Applications From VxWorks AE to VxWorks 6.x A.3 Compiler
on the CDF analysis tool to generate and drag in dependent components and modules. VxWorks 6.x continues to use the VxWorks 5.5 model, where .o modules still reside in archives and the CDF components only describe the high level dependencies between feature components. Certain dependencies are still managed at the make level by symbolic references. VxWorks AE created many new CDF components to describe the features and .o modules available in AE. Some of these components do not exist in VxWorks 6.x and some CDF component names have changed.
A
A.3 Compiler
VxWorks AE made use of the GNU 2.72 compiler. There may be incompatibilities in the binaries generated by the Wind River GNU Compiler 3.3 and the Wind River Compiler 5.3.1 provided in VxWorks 6.x. All sources must be recompiled with the new compilers provided in VxWorks 6.x.
A.4 User and Kernel APIs

VxWorks AE exported the majority of the VxWorks 5.x kernel APIs to protection domains, with the exception of certain low-level APIs, primarily driver APIs. The availability of the APIs in user mode allowed for ease of migration for 5.x customers to AE. In VxWorks 6.x, because of the move to provide more POSIX APIs in user mode, the user APIs available in RTPs differ from those available in the kernel. Signal APIs differ between VxWorks AE and VxWorks 6.x. In VxWorks AE, the same signal APIs and behavior are provided in user and kernel modes. In VxWorks 6.x, the signal behavior in user mode is modeled after POSIX signals while signal behavior in the kernel remains the same as VxWorks 5.5. For more information on POSIX signals in RTP space, see 5.2.10 POSIX Signal Differences, p.115 and the VxWorks Application Programmers Guide: POSIX Standard Interfaces.
147
A.4.1 Kernel API Differences

objNameToId( ) is now replaced by the xxxOpen( ) family of calls, including taskOpen( ) and semOpen( ). The following examples show how to access an existing semaphore:
VxWorks AE
semId = (SEM_ID) objNameToId (windSemClass, "someSemaphoreName")
VxWorks 6.x
semId = semOpen ("someSemaphoreName", 0, 0, 0, 0, NULL);
Also, the concept of private and public objects is introduced in VxWorks 6.x. Thus, if the semaphore named someSemaphoreName needs to be accessed by a different RTP than the RTP that created the semaphore, the semaphore must be made public. This is accomplished by prefixing the / character (forward slash) to the name when the object is initially created.
A.4.2 Task State

The task state BREAK for VxWorks AE is replaced by the STOP state in VxWorks 6.x. The meaning and behavior is similar. The APIs for controlling this state are still available but they apply to the STOP state and they are no longer published APIs.
taskStop( ) taskCont( )
A.4.3 Host and Kernel Shell

The shell for VxWorks 6.x has changed significantly from VxWorks AE.
The way to switch to the application space is different. VxWorks AE: Uses : (colon) to switch between applications and the kernel.
[vxWorks] -> : usrApp [usrApp] -> : [vxWorks] ->
148
A Migrating Applications From VxWorks AE to VxWorks 6.x A.4 User and Kernel APIs
VxWorks 6.x: Uses the command interpreter to switch.

-> cmd [vxWorks *]# %1 [usrApp *]# C ->
<-- where 1 is the process attachment number for the application
All protection domain shell commands are obsolete in VxWorks 6.x. Debugging of applications is now done in the command interpreter shell. It is not recommended to debug applications with the C interpreter shell. Certain operations are no longer allowed in the new VxWorks 6.x shell. Spawning tasks in an application or loading modules into an application are not allowed. The VxWorks 6.x shells do not use or change VxWorks global I/O. Any change to VxWorks global I/O does not impact the shell. For information, see 5.2.7 I/O Redirection, p.111. Multiple sessions of the shell can be spawned, each one using different I/O (for example, different serial lines, rlogin, telnet, VIO). Sessions are independent, with different configurations, user IDs, default working paths, and so forth. A shell component parameter, SHELL_COMPATIBLE, can be set to TRUE in order to remain compatible with the VxWorks 5.5 shell, which allows only one session shared between connections with global I/O redirected. For more information, see 2.6.5 Multiple Sessions of the Kernel Shell, p.30.
A
For more information on the new shells, see the Wind River Workbench Command-Line Users Guide.
Shared Libraries
Shared libraries in VxWorks AE are represented differently from VxWorks 6.x shared libraries. Shared libraries in VxWorks AE are created as containers with code modules loaded into them, as are protection domains. These shared libraries may be created at boot time by the kernel or dynamically by the kernel or a protection domain. A shared library may exist in the system without any application referencing it. VxWorks 6.x adopts the more conventional shared library or .so approach. A shared library is an object file and is loaded by the application that references it. A
149
shared library does not have its own memory context as in VxWorks AE. An shared library may only exist if there is at least one application referencing it. VxWorks AE shared libraries used the link path to enable the loader to resolve undefined shared library references in applications. VxWorks 6.x uses the LD_LIBRARY_PATH environment variable set in the application to resolve shared library references. To migrate a VxWorks AE shared library to VxWorks 6.x, the shared library source files need to be compiled as a .so file. It is not possible to port shared library project components to VxWorks 6.x since shared libraries are built from source code rather than from projects or components. The system shared library in VxWorks AE is no longer available in VxWorks 6.x. Applications that make use of the system shared library and have added user modules to it should instead create a shared library for the user modules. The application can then make use of the shared library. For more information, see the VxWorks Application Programmers Guide: Applications and Processes.
Shared Data Regions
Shared data regions are similar between VxWorks AE and VxWorks 6.x. The usage of these regions is similar but the APIs to create and use them have changed.
Table A-1 Shared Data APIs
VxWorks AE
VxWorks 6.x
Usage
sdCreate( ) sdMap( ) sdUnMap( ) sdDelete( ) sdOpen( ) sdAttach( ) sdDetach( ) sdShow( )
sdCreate( ) sdMap( ) sdUnMap( ) sdDelete( ) sdOpen( )
API changed. In 6.x, this creates and maps the shared data region to the calling RTP or kernel. API changed. API changed. API changed.
Not available in 6.0 Not available in 6.0 sdShow( )
150
A Migrating Applications From VxWorks AE to VxWorks 6.x A.4 User and Kernel APIs
Shared data regions in VxWorks 6.x do not have a virtual memory context associated with them as was the case in VxWorks AE. Thus, by default, a shared data region may not exist on its own and the last client (RTP) to reference it deletes the shared data region unless the SD_LINGER flag is set.
A.4.4 Other Differences
Dependencies and symbols for applications are resolved at build time in VxWorks AE. Thus, by the time the VxWorks image is booted, all symbol references are resolved. In VxWorks 6.x, application builds do not link against the kernel and symbols are not referenced across the system-call boundary. One consequence is that if the required feature is not present in the system, the system call returns errno, with a value of ENOSYS. Object IDs in VxWorks AE are global and may be passed across applications. IDs in VxWorks 6.x may not be passed across applications since each application has its own ID identifier for an object. To provide sharing of an object between applications, an object must be created and named as a public object.
151
152
B
Migrating to the New VxBus
B.1 Introduction 153 B.2 Device Driver Interface 160 B.3 Bus Type Requirements and Interface 168 B.4 BSP Modifications 169 B.5 Driver Modifications 171 B.6 Initialization Sequence 173 B.7 Hardware Configuration File 176 B.8 Optimization Issues 178
B.1 Introduction
A new bus and device model has been introduced in VxWorks 6.2. The goal of VxBus is threefold. First is to simplify BSPs. Second, is to provide a standard API for OS/middleware functionality including power management and networking. Finally, to create BSP and architecture agnostic driver support. This appendix describes:
the bus and device model how to configure it into a working BSP
153
how to write or modify device drivers to make use of VxBus facilities how to modify BSPs to make use of VxBus additional aspects of using the VxBus system
These preliminary migration instructions contain information about VxBus which will eventually migrate to the driver guide or the BSP developers guide. The current bus structure and bus code remain as the default for the VxWorks 6.2 release. However, in future releases this will be deprecated and ultimately removed in favor of VxBus.
B.1.1 Glossary
bus a hardware mechanism for communication between the processor and a device, or between different devices. In this document, the term bus refers to a specific piece of communication hardware, with its associated instance of controller and driver. See also device, driver, instance. bus discovery See probe. child a device which is attached to the current bus. device a hardware module which performs some specific action, usually visible in some way outside the processor or to the external world. See also bus, driver, instance. downstream refers to a point further from the CPU on the bus hierarchy from the perspective of a device. See also child. driver a compiled software module, usually consisting of a text segment containing the executable driver code, plus a small, static data segment containing information required to recognize whether the driver can manage a particular device. Software to configure bus controllers, such as the Raven PCI host controller, is considered to be a driver. See also bus, device, instance.
154
B Migrating to the New VxBus B.1 Introduction
driver method a specific functionality, which may be provided by a driver. Examples of methods include functionality such as suspending a device or reducing power usage. See also method ID. instance a driver and device which have been associated with each other. This is the minimal unit which is accessible to higher levels of the operating system. See also bus, device, driver. method ID the identification of a specific functionality which is provided by a driver. It must be unique for each method on the system. The method ID is a unique number, currently implemented as an address. See also driver method. orphan device a device with no driver associated with it. parent the bus to which a device is attached. per-device data data used by the device driver and associated with an instance, not with a driver or device. probe discovery of devices present on a bus. For some bus types such as PCI, the bus contains information about devices which are present. For those bus types, dynamic discovery is performed during the probe phase. For bus types such as VME, which do not have such functionality, tables are maintained in the BSP describing the devices which may be present on the system. See also probe routine. probe routine an entry point into drivers. After the system has tentatively identified a device as being associated with a driver, VxBus provides the driver an opportunity to verify that the driver is suitable to control the device. The driver registers the probe routine to perform this last-minute validation. The probe routine is optional. If specified, it would normally be safe and acceptable for the routine to simply indicate acceptance. upstream refers to a point closer to the CPU on the bus hierarchy from the perspective of a device. See also parent.
B
155
B.1.2 Overview of VxBus

The VxBus model is based on registration of drivers and devices. During system initialization, or anytime during system operation, drivers register with VxBus. Devices are dynamically discovered if possible, and associated with drivers which have registered. If dynamic discovery is not possible, a table-driven method is used. For more information, see B.7 Hardware Configuration File, p.176. The code to manipulate a given bus controller, which used to reside in the BSP in whatever format the BSP developer desired, is now consolidated into a single file and is considered to be a driver like other device control modules. Devices and buses are configured early during system bring up following a multi-stage configuration process. Early stages of instance initialization are limited as to what operating system facilities are available for use by the instance. Instances created after system initialization are initialized using the same multi-stage process. Though the limits on operating system facilities are not present at that time, drivers must follow the same restrictions, so that they can be included with a statically configured system as well as a dynamically configured one. Drivers can also provide methods for middleware to use to gain access to instance facilities. For a description of the modifications required to BSPs and drivers to participate with VxBus, see B.4 BSP Modifications, p.169, B.5 Driver Modifications, p.171, and subsequent sections.
Participants
This section describes the hardware and software elements that participate in the VxBus model.
BSP
As in earlier releases of VxWorks, the BSP continues to contain the board-specific code which allows the operating system and device drivers to communicate with each other, and which allows device drivers to communicate with the hardware. However, most device-related, architecture-specific code and most board-independent, device-specific code has been moved out of the BSP.
156
VxBus
The VxBus software consists of a framework, used by all bus types, of device drivers and code to manage individual bus types including PCI, RapidIO, and USB. Bus controllers and bridges are typically considered to be a special kind of device and usually have a VxBus device driver.
Bus Type
Each type of bus puts specific constraints on communication transactions. These constraints are uniform among all bus controllers of the specific bus type. In general, some code can be shared among all bus controllers for a given bus type. For an example of this, see the PCI configuration modules.
Bus Controller (Hawk, Universe)
In modern hardware, in order for a CPU to cause transactions on a specific bus, the CPU configures a bus controller to format the transaction and insure that the constraints specific to the bus type are maintained. Each processor has access to a bus local to the processor, which is referred to in this document as the processor local bus (PLB). Typically, the PLB contains RAM, cache, and a small number of devices such as controllers for other bus types. The PLB is always at the root of each bus hierarchy. In some cases, the PLB may be accessible by more than one processor core.
Device Drivers
Device drivers are the executable code modules which manage particular types of hardware devices. In previous versions of VxWorks, an attempt was made to abstract the hardware away from device drivers. The core parts of device drivers, for the most part, were unaware of what bus their devices resided on, and were agnostic to the bus type. However, this abstraction was not completely successful. Device drivers did need to be aware of what bus their devices resided on in order to manage access widths, register interleave size, write posting, and other bus-specific features. VxBus provides a set of uniform access methods for the driver to manipulate device registers and memory. In the past, this functionality was always provided by the BSP. In VxBus, default access methods are provided by VxBus itself, and optimized versions can be provided by the BSP in the form of a specific set of standard preprocessor macros for each device type.
157
In addition, the current design recognizes that the driver may need to be aware of what bus the device resides on, but it also attempts to provide a common interface to handle bus-specific requirements, so that the driver no longer needs to be concerned about them in most cases. VxBus provides an interface so that the driver can explicitly check what buses are present between the processor and the device, modifying its behavior if necessary.
Architecture Modules
Some of the code which previously resided in the BSP has been moved to architecture-specific modules. This is typically related to processor instruction pipe issues.
Configuration
Configuration of buses in the new system is more tightly integrated into the project facility than it was in previous releases. Configuration is performed by inclusion or exclusion of driver modules, bus-type modules, and a few hardware interface (HWIF) utility modules. The VxBus core (INCLUDE_VXBUS) requires support for the processor local bus (PLB) bus type (INCLUDE_PLB_BUS). Other drivers and bus types are included separately from the VxBus core, as are show routines. In general when using Workbench to configure a VxWorks system with VxBus, prerequisite modules are listed in the configuration files. This means that when you include a bus controller device driver, the system includes the bus-type code for the bus downstream from the bus controller device. However, this is not a symmetric relationship. When you select a bus type, no bus controller is selected automatically. Standard (non-bus controller) device drivers may optionally list a required bus type, as well. A list of the bus types and bus controllers available on the system is provided to Workbench, allowing Workbench to display them for selection in the project. The list, and therefore Workbench, does not reflect the bus topology as it is not known until the system is booted. For information on a visual representation of the bus topology available at runtime, see the reference entry for vxBusShow( ). From the project, select which bus types and bus controllers are present on the system. In general, there are no configuration options at the level of VxBus. The configuration options are made at the level of a specific bus type, at the level of the bus controller, at the level of the driver, or at the level of a HWIF utility module.
158
BSP Requirements
With VxBus, most driver information has been moved out of the BSP and consolidated in the driver, in a HWIF utility module, or in a core VxBus module. In certain cases, however, information must continue to come from a set of tables in the BSP. For more information about the tables, see B.7 Hardware Configuration File, p.176. The first exception is that the BSP continues to require information about devices, including bus controller devices, which reside directly on the PLB. The information must be known statically at compile time. The primary information consists of the base address of the device registers and the name of the device driver. Additional device-specific information may be required, such as the input clock rate for a UART device. Similarly, devices for any bus type which cannot be probed under software control, such as VME, require additional device entries in the tables. The second exception is that the BSP requires information about interrupt lines, both for devices present on the system and for bus slots for plug-in devices. For example, in most cases the previous PCI configuration libraries required a table which mapped specific slots to interrupts. This information is still required. As with the older PCI configuration libraries, interrupt information is still kept in a table. For other bus types, the interrupt information may be available from the bus type (for example, MSI interrupts on PCI-X), from a device table entry for the device, or from some other mechanism.
Source files
The core parts of VxBus are provided by Wind River. The primary source code files for both VxBus core source modules and VxBus-compliant device driver source modules reside in installDir/vxworks-6.x/target/src/hwif and its subdirectories. Header files have been separated into a number of locations, according to a new Wind River convention for header file locations. Some header files may reside in the same source directory as the source file they belong with. These header files are never referenced by any source file outside that directory. Several header files with functionality restricted to the interface between device drivers and VxBus and among different device drivers are found in installDir/vxworks-6.x/target/src/hwif/h and subdirectories. Header files for reference outside of the VxBus environment, such as the interface between drivers and middleware modules, may reside in installDir/vxworks-6.x/target/h/hwif/ and
159
subdirectories. Finally, there is a basic VxBus header file located at installDir/vxworks-6.x/target/h/vxBusLib.h. In addition to source and header files, all VxBus-compliant drivers have project configuration files associated with them. By convention, these files reside in installDir/vxworks-6.x/target/config/comps/vxWorks and begin with the digits 40.
B.2 Device Driver Interface

This section discusses the interface between VxBus and device drivers.
B.2.1 Driver Registration and Initialization Mechanism

Drivers register with VxBus by calling the routine vxbDevRegister( ). The argument to vxbDevRegister( ) is a pointer to a DRIVER_REGISTRATION structure, which can be found in installDir/vxworks-6.x/target/h/hwif/vxbus/vxBus.h. This structure contains device recognition information, which VxBus needs to know about the driver and about the device to which the driver might be attached. For more information about how VxBus makes use of this information, see B.2.6 Instance Creation, p.166. In addition to the global device recognition information kept in the
DRIVER_REGISTRATION structure, each bus type can require additional
information. To handle this, each bus type defines a bus-type-specific structure to contain the additional information. The first field of each bus-type-specific structure is the DEVICE_REGISTRATION structure. (This is not a pointer, but the structure itself.) See the appropriate bus-specific header file in installDir/vxworks-6.x/target/h/hwif/vxbus for more information about bus-type-specific information. It is possible for a single driver to register device recognition information for more than one bus type. To do this, create several bus-type-specific device recognition structures, each with a DRIVER_REGISTRATION structure as the first element. For each bus-type-specific device recognition structure, make a call to vxbDevRegister( ) with a pointer to the structure.
160
B Migrating to the New VxBus B.2 Device Driver Interface
CAUTION: It is possible for the driver to link the structures together and make a single call to vxbDevRegister( ), but this is not recommended.
Here are some sample device recognition structures, along with function prototypes and other required structures:
LOCAL LOCAL LOCAL LOCAL BOOL void void void templateDriverProbe(VXB_DEVICE_ID pDev); templateDriverInstInit(VXB_DEVICE_ID pDev); templateDriverInstInit2(VXB_DEVICE_ID pDev); templateDriverInstConnect(VXB_DEVICE_ID pDev);
LOCAL struct drvBusFuncs templateDriverFuncs = { templateDriverInstInit, /* devInstanceInit */ templateDriverInstInit2, /* devInstanceInit2 */ templateDriverInstConnect /* devConnect */ };
If this driver is for a device resident on a PCI bus, then the pciDevIDList[ ] table must be created and maintained as shown. !
CAUTION: Follow the convention of explicitly listing the boards and devices which have been tested.
The following data is for the ns16550 and compatible serial devices, but with the devID and vendID fields set to illegal values. (Check the ns16550 driver, located in installDir/vxworks-6.x/target/src/hwif/sio, if you need those values for the ns16550 devices.)
LOCAL struct vxbPciID pciDevIDList[] = { /* { devID, vendID } */ /* Board: CompUSA * PCI High-Speed 2-Serial and 1-Parallel Port Adapter * UPC# 0-49696-10155-4 * SKU# 271773 * * CHIP: NetMos technology * Nm9825CV * FHFFT-000 * 0345 */ { 0xffff, 0xffff}, /* Board: IC0607KB - Axxon (softio) * PCI High-Speed 2-Serial and 1-Parallel Port Adapter * Multi-function device: Function 0 = UARTs * Function 1 = 8-bit local bus or parallel port *
161
* Controller: Oxford Semiconductor * Board controller has OXmPCI952 silkscreened but is OXmPCI954. * * Configuration Notes: * Has 4-UARTs; only 2 are pinned. * Ships with UARTs in Common IO Space */ { 0xffff, 0xffff}, { 0xffff, 0xffff}, /* add additional DevVend IDs here */ }; LOCAL struct vxbPciRegInfo templateDriverPciDevRegistration = { { /* basic information */ NULL, /* pNext */ VXB_DEVID_DEVICE, /* devID */ VXB_BUSID_PCI, /* busID = PCI */ BUS_VERSION_1, /* vxbVersion */ "templateDriver", /* drvName */ &templateDriverFuncs, /* pDrvBusFuncs */ NULL, /* pMethods */ templateDriverProbe /* devProbe */ }, NELEMENTS(pciDevIDList), &pciDevIDList[0], };
If the driver is for use on the PLB, the following table should be used No information other than the top-level information is required in order to match the device to the driver. Both devices and drivers are specified on PLB by name. For more information, see B.7.1 Structures, p.176.
LOCAL struct vxbPlbRegInfo templateDriverPLBDevRegistration = { { /* basic information */ NULL, /* pNext */ VXB_DEVID_DEVICE, /* devID */ VXB_BUSID_PLB, /* busID = PLB */ BUS_VERSION_1, /* vxbVersion */ "templateDriver", /* drvName */ &templateDriverFuncs, /* pDrvBusFuncs */ NULL, /* pMethods */ templateDriverProbe /* devProbe */ } };
NOTE: The name field is case sensitive, and must match the resource table record
in the BSP hwconf.c file exactly. For more information, see B.7.1 Structures, p.176.
162
B.2.2 Register Access Routines

With the introduction of VxBus, the BSP is no longer required to provide the driver with routines to access the device registers. This section describes the mechanisms available.
Standard Access Routines
VxBus provides a set of functions allowing drivers to access the devices they control. These functions do not require any BSP support, so VxBus-compliant device drivers should not require driver-specific support in the BSP. Pointers to the register access functions are kept in a structure and made available to the driver. Versions are available for reading and writing 8-, 16-, 32-, and 64-bit registers.
BSP-Specific Optimized Register Access Routines
Although drivers should function with no BSP support, in some cases it may be appropriate to provide optimized access to device registers for performance. This can be done for VxBus-compliant drivers by using preprocessor macros. For these to be effective, the driver must be compiled in the context of the BSP or bootable project. The macro names providing optimized register access conform to a strict format, which includes the driver name. These macros require parameters, and the format of the parameters is fixed: the parameter format is the same for all drivers. In the following macro list, {DEV} is the driver name in capital letters. {DEV}_REGISTER_READ8 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_READ16 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_READ32 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_READ64 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_WRITE8 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_WRITE16 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_WRITE32 (pDev, regSpace, offset, pDataBuf) {DEV}_REGISTER_WRITE64 (pDev, regSpace, offset, pDataBuf) For more information, see the VxWorks Device Driver Developers Guide.
163
B.2.3 Interrupt Handling

The facilities provided by VxBus include the ability for a single device to support multiple interrupt sources and to have a different interrupt handling routine for each interrupt source. A uniform API is presented to drivers, so they can manage interrupt sources the same way regardless of the type of bus they are on. The VxBus interrupt mechanism defines a set of zero or more interrupts for each device. The driver references the interrupts through an index number. The mapping of index to interrupt may depend on the device or the bus type. For devices with a single interrupt, the index is always zero unless the bus type requires something different. However, if the bus type requires a non-zero value, then the exact mapping depends on the bus type. For example, in PCI, the driver can read the INT_PIN configuration space register, which returns a value between one and four, inclusive. Subtract one from this value, and the result is the VxBus interrupt index. For devices with three interrupts, the convention is normally index=0 referring to transmit, index=1 referring to receive, and index=2 referring to an error condition. For devices with more than three interrupts, the mappings are device dependent. The API for interrupt handling includes the following routines: vxbIntConnect( ) vxbIntDisconnect( ) vxbIntEnable( ) vxbIntDisable( ) vxbIntAcknowledge( ) Each of these routines requires the same arguments: a device ID (VXB_DEVICE_ID), an interrupt index, a pointer to the ISR, and a pointer to the argument to be passed to the ISR. Different bus types provide different requirements for interrupt handling. For example, PCI allows a device to use any one of four interrupt lines. Typically, the choice of interrupt line is hardwired into the device, though it may be possible for a configuration transaction to modify the choice of interrupt line on some devices. The driver discovers which of the four interrupt lines to use by querying PCI configuration space and reading the intPin field. Subtracting one from the intPin field results in the index to use with the VxBus interrupt routines. The processor local bus (PLB) provides another good example. For devices on the PLB, any number of interrupts can be used, and the number of interrupts depends only on the device itself. Devices such as PCI-X controllers may have more than ten or fifteen interrupt sources, each with a specific function. Devices such as
164
high-speed network devices typically have three or more. Each driver may wish to connect different ISRs to the multiple interrupt vectors, and the driver determines the order of interrupts. for a sample PLB naming scheme, see B.7 Hardware Configuration File, p.176. With this mechanism, drivers do not need to know anything more about the interrupt than what index to use. The use of IRQs, vectors, or other interrupt abstractions is hidden from the driver.
B.2.4 Driver Methods

A driver can register any number of specific method APIs and make them available to the system for all instances. It does this by putting a pointer to a NULL-terminated list of methods in the pMethods field of the VXB_DEVICE_ID structure after instance initialization. The driver can change the set of advertised methods at any time. For example, if one method is used to connect a mass storage device to a file system, then the driver can remove that method from the list once it has been called. The replacement of methods must be protected by locking interrupts. The normal way to replace methods is to provide a second array, rather than removing one entry from the existing array. The replacement of driver methods does not guarantee that the method can no longer be called, since it is possible some other task has already loaded the method but not yet called it. The driver must be able to handle this situation, for example by use of a lightweight interlock mechanism.
B.2.5 Compilation Context

A VxBus device driver gains access to device registers either through VxBus access functions or through BSP-supplied macros. The purpose of the VxBus-supplied access functions is to increase driver portability. The purpose of the BSP-supplied macros is to increase performance. For more information, see B.2.2 Register Access Routines, p.163.
165
Generic Drivers
With VxBus, drivers are expected to be available in source form and compiled in the context of the BSP or the bootable image project. However, this is not a strict requirement. Generic forms of VxBus device drivers can be made available in object module format. These object modules must follow normal requirements for distribution of VxWorks object modules: they must be available in a library for the build system to pick them up, and a separate object module must be available for every supported processor.
BSP-Specific Optimized Access
When the BSP supplies device register access macros for a particular driver, that driver must be compiled in the context of the BSP or bootable project, in order for the macros to be available. For these optimizations to be available, the driver must be available in source form.
B.2.6 Instance Creation

In VxWorks 6.1 and earlier systems, devices on most bus types were matched with drivers by manually configuring the sys{Dev}.c file to associate them. With VxBus, a simple mechanism is available to match devices and drivers. Once a match has been made, devices that provide a probe routine can perform a final validation.
Automatic Procedures
The VxBus matching mechanism is able to test different information, depending on what is available. The actual test used depends on the bus type. The following types of data can be tested in order to create a match. If no probe routine is registered, a successful match produced by this process becomes an instance. bus type Each device is associated with a bus type based on the type of the bus on which the device is directly connected. The driver registers itself for use with specific bus types. If the driver's registered bus type matches the device's bus type, then the driver and the device are a potential match. Failure to match rejects the pairing.
166
vendor ID and device ID This information is available on PCI, RapidIO, and other bus types. If the driver registers device ID and vendor ID information, and if that information matches the information read from the device, then the driver and the device are a potential match. Failure to match rejects the pairing. device name For simple, non-enumerable bus types such as PLB, a table of available devices is kept in the BSP. The table includes the device name, which is matched against the names of registered drivers. If the device name from the table matches the driver name, then the driver and device are a potential match. If the device name from the table does not match the driver's name, then VxBus rejects the pairing. other bus-type-specific information If the bus-type-specific information that the driver registered matches what it reads from the device, then it is a potential match. Otherwise, VxBus rejects the pairing.
Driver-Provided Probe
At this point, more checks have been done than occurred in VxWorks 6.1 and earlier versions. However, VxBus allows for an additional check to verify that the driver and device match. If all other conditions indicate a match, VxBus checks to see if the probe routine is present. If no routine is registered, then VxBus accepts the other indicators and pairs the driver and device. However, if the probe routine is registered, VxBus calls it. If the probe routine returns TRUE, it indicates that the driver and device can be paired. If the probe routine returns FALSE, it is not a match and VxBus rejects the pairing. If the driver and device do not match, having used the probe routine raises a number of issues. These are minimized by the checks which are done before the probe routine is called; however, they cannot be eliminated entirely. The driver may modify device registers in order to determine whether the device is a good match. The risk is, once the registers have been modified and the device is not a good match, then the device may be set to an unknown state, and may end up in a state where it does not respond to normal requests. For example, a keyhole register address may be set, and the device may not respond to any other register modifications until the address behind the keyhole is either read or written. Or the
167
device may be set into some other unusual state, such as flash devices being ready to program but not available to be read. A good use of the probe routine is for devices such as the 3Com EtherLink II and III cards. Some of these devices are 3C589C devices. Others are 3C589D devices. There are significant differences between the behavior of the two revisions. Unfortunately, 3Com did not update the device ID and revision number for some of the early 3C589D devices. Because of this, the two different devices are indistinguishable from PCI configuration space alone. If there are two drivers, one for 3C589C devices and one for 3C589D devices, they would both register the same PCI configuration information, and register a probe routine. During execution of the probe routine, they would distinguish between the two device types, and reject the device if appropriate.
B.3 Bus Type Requirements and Interface

In order to provide support for buses, VxBus requires two things. First, every bus has a piece of hardware that manages the bus, and a VxBus device driver is required for that hardware. Second, VxBus requires a bus-type-specific library, or set of libraries, to support the requirements of the bus type that are independent of the specific bus controller.
B.3.1 PLB Bus Type

Processor vendors have a variety of ways to refer to the bus to which the processor is directly connected. VxBus standardizes on the name processor local bus (PLB), and provides VxBus support for PLB devices. The distinguishing characteristics of PLB are that devices are hardwired, typically at specific fixed addresses, and that there is no uniform method to determine what device exists at a given address, or even whether a device is present at the given address. The PLB device driver is a special-case device driver, which does not expect physical hardware to be present and performs no hardware initialization. Also, for most purposes, PLB bus support is included in the driver.
168
B Migrating to the New VxBus B.4 BSP Modifications
PLB device configuration is table-based. All supported PLB devices must be listed in the hcfDeviceList[ ] array in the BSP. For more information, see B.7.1 Structures, p.176.
B.3.2 PCI Bus Type

VxBus includes support for the peripheral component interconnect (PCI) bus. PCI supports probing for the presence of PCI devices on the bus, as well as dynamic configuration of the PCI bus and PCI devices. In VxBus, PCI bus configuration is performed automatically, using pciAutoConfigLib, as was done in prior VxWorks releases.
B.4 BSP Modifications

This section describes the BSP modifications required for VxBus to work with that BSP. In particular, it describes the steps for adapting an existing BSP to use VxBus.
Step 1: Add the hardWareInterFaceInit( ) call.
Modify sysHwInit( ) in sysLib.c by adding a call to the routine hardWareInterFaceInit( ). This should be done at a point after the processor and memory are initialized, but before any devices are initialized.
Step 2: Add the vxbDevInit( ) call.
Modify sysHwInit2( ) in sysLib.c to add a call to the routine vxbDevInit( ). This should be the first thing that sysHwInit2( ) does.
Step 3: Add the vxbDevConnect( ) call and an empty device table.
Put the vxbDevConnect( ) call at the end of sysHwInit2( ), as the last action performed. Create an empty hcfDeviceList[ ] table in the hwconf.c source file. (For more information, see B.7.1 Structures, p.176.) Test your work to this point. Create a VxWorks image configuration which includes VxBus and the VxBus show routines. Build and boot that configuration, and run vxBusShow( ). The system should boot without complication. At this time, no devices should be listed in the vxBusShow( ) output.
169
Be sure to include bus controllers, which have not traditionally been listed as drivers or devices in documentation such as target.nr and target.ref. At this time, you can ignore devices not resident on the PLB. Find which of the listed devices have existing VxBus drivers. Create a VxWorks image configuration which includes VxBus and those drivers for standard devices which already support VxBus. At this time, ignore bus controllers, since it is more convenient to configure those later. Build and boot that configuration, and run vxBusShow( ). The system should boot without complication. At this time, no devices should be listed in the vxBusShow( ) output.
Step 4: Add device descriptions for devices attached to the PLB.
The hcfDeviceList[ ] table you created in Step 3 is where the PLB bus-type code discovers what devices are available. Get a list of devices on the PLB, and create an hcfDeviceList[ ] entry for each device. Be sure to include bus controllers, which have not traditionally been listed as drivers or devices in documentation such as target.nr and target.ref; it may require some additional work to discover what bus controllers are present. At this time, you can ignore devices not resident on the PLB. Determine which of the listed devices have existing VxBus drivers. Create a VxWorks image configuration which includes VxBus. Also include any existing VxBus device drivers for devices present on the system and described in the new hcfDeviceList[ ] table entries. At this time, you can ignore bus controller device drivers, since it is more convenient to configure those later. Build and boot the new configuration including the new hcfDeviceList[ ] tables entries and device drivers, and run vxBusShow( ) again. This time, the devices listed in your table should appear, and the existing VxBus drivers should be attached to their devices and appear as instances. Devices with no VxBus drivers should appear as orphans.
Step 5: Perform registration-only driver modifications for non-VxBus drivers.
Non-VxBus drivers can still use the earlier mechanism for accessing device registers. Be sure to verify that the addresses of the devices do not change due to bus controller modifications. Build and boot the image, and verify that the modified drivers now show up as instances and not as orphans.
Step 6: Write bus controllers if required.
If you are working with a board which uses a bus controller that is already supported, remove the existing BSP code that performs initialization of the bus controller and include the standard bus controller in the configuration. If there is
170
B Migrating to the New VxBus B.5 Driver Modifications
not an existing VxBus driver for that bus controller, you must write one. As with normal devices, start with registration routines. Then add the existing initialization code from the BSP. Bus controllers should not normally need to have optimized access methods, and in most circumstances it would be wasteful to create them.
Step 7: Clean up the modified drivers.
They should use the VxBus register access methods instead of the ad-hoc methods they previously used. This should include removal of the sys{Dev}.c file from the BSP, if it was previously required. These drivers can now be considered VxBus drivers.
Step 8: Create optimized register access methods.
For high-speed devices such as high-speed network devices and disk devices, create any required optimized register access methods. It is possible these optimized methods were used in the BSP, and it may be possible to modify the existing methods so that they work with VxBus. Some modification is to be expected. For more information, see B.8 Optimization Issues, p.178.
B.5 Driver Modifications

In general, drivers can participate with VxBus at one of two levels: registration only, and full participation.
B.5.1 Registration Only

To participate with VxBus registration only, the driver needs to register with VxBus. This involves creating four routines to handle registration and initialization. The first routine is the registration routine that calls the registration API provided by VxBus, vxbDevRegister( ). (For more information, see B.2.6 Instance Creation, p.166.) The other initialization routines can be stubs at the registration-only stage; they are required for full participation.
171
B.5.2 Full Participation

After getting the registration interface working, the next step is to modify the driver to use the VxBus register access routines. The routines can be accessed directly through the access list pointer, or they can be accessed through BSP-supplied macros. (See B.2.2 Register Access Routines, p.163.) In general, it is a good idea to have two sets of macros within the driver, and use the appropriate set. The first set uses the access list pointer routines. The second set can be overridden by the BSP. The BSP developer may choose to have the macros use inline code. The size of the image may increase significantly if the driver uses only the BSP supplied macros. Because of this, the standard access methods using the access list pointer routines should be used whenever performance is less critical than code size. After the driver has been modified to make use of the access methods, the next step is to modify the interrupt handling mechanism to use the VxBus API. This should normally involve some driver simplification, since the driver simply defines the number of interrupts required (usually one) and what order each interrupt is listed. If three interrupts are used, the standard order is 0: transmit, 1: receive, and 2: error. For other numbers of interrupts, the order is determined exclusively by the driver. Once the interrupt indexing scheme is defined, replace all interrupt handling code with calls to the VxBus interrupt routines: vxbIntConnect( ) vxbIntDisconnect( ) vxbIntEnable( ) vxbIntDisable( ) vxbIntAcknowledge( )
NOTE: For portability, it is usually best to include calls to vxbIntEnable( ), vxbIntDisable( ), and vxbIntAcknowledge( ) at the appropriate places regardless of whether they are required on the board for which development is taking place. However, this is not required; if they are not included initially, the driver can be modified when it is used on a board requiring the calls.
172
B Migrating to the New VxBus B.6 Initialization Sequence
B.6 Initialization Sequence

The purpose of driver registration is to be able to link devices with the drivers that can manage them. The information provided by the driver is sufficient to allow this. After devices and drivers are paired to create instances, there is a three-part initialization sequence that is followed for all devices. Although all devices may make use of any stage in the process, the stages are intended for specific purposes.
Registration
When a driver is loaded into the system, the driver must register with VxBus. This registration is performed by calling vxbDevRegister( ). For information on specifying the argument, see B.2.1 Driver Registration and Initialization Mechanism, p.160. In general, drivers can be loaded onto the system and registered at any time, but statically linked drivers should be registered during system bring-up. Drivers under development may benefit by delaying the call to vxbDevRegister( ) until after the system has booted and the developer is ready to debug the driver. By convention, each driver provides a single driver registration routine which makes the call to vxbDevRegister( ). The BSP project configuration mechanism creates a routine which calls the driver registration routine early in system bring-up. During the registration phase, no operating system facilities are available to drivers. Drivers are expected to do nothing except register with VxBus.
First Stage: vxbDevInit( )
The first initialization stage is intended for initializing bus controller drivers. Bus controllers are responsible for two things during the first stage of initialization: notifying VxBus that the bus type exists, and enumerating devices on the bus and notifying VxBus that each device exists.
Bus controller drivers notify VxBus that the bus type exists by calling vxbBusAnnounce( ). Bus controller drivers notify VxBus of new devices by calling vxbDeviceAnnounce( ) for each device, with information about that device. The bus controller driver is responsible for creating a VXB_DEVICE_ID structure for each device and loading information about the device into the structure.
173
When a new device is discovered and VxBus is notified by vxbDeviceAnnounce( ), VxBus checks to see if the device can be associated with a driver. If so, VxBus makes that association and creates an instance. It then calls the driver vxbDevInit( ) routine for the new instance. Drivers for normal devices are expected to return at this point, though there is no requirement that they do so. Drivers for bus controller devices are expected to perform bus initialization at the time their vxbDevInit( ) routine is called. During the bus initialization phase, no operating system facilities are available to drivers. Configuration of addresses and other resources may not be available. Drivers for normal devices are expected to do nothing. Drivers for bus controller devices are required to initialize resources used by devices on the bus.
Second Stage: vxbDevInit2( )
The second stage is for standard device initialization. During the device initialization phase, most basic operating system facilities are available, but no network is available. Memory allocation can be performed at this time, semaphores can be created, but other services are probably not available. For example, the console may be configured during this phase rather than during stage one, so it may not be available.
Third Stage: vxbDevConnect( )
During the third stage, standard devices make themselves available outside VxBus for middleware to use their services. The primary file system is initialized. Customer-supplied custom devices are initialized, such as XY plotters, DSP drivers, audio device drivers, and AD/DA converters.
Other Initialization
Some device types may require additional initialization which cannot be done easily during the three-phase initialization process. If this is the case, then the driver may accomplish the initialization by use of a driver method. Some external agent must define a method for use by the driver, and the driver makes the method available to the external agent. At an appropriate time, the external agent must make a call to all instances which support the method. In this way, initialization can be done as required by external modules. Here are two good examples of additional initialization.
174
B Migrating to the New VxBus B.6 Initialization Sequence
Network Initialization
Network initialization is performed all at once, with a call from the BSP to sysNetHwInit( ). This includes initialization of the MUX. The required initialization sequence with regard to network drivers is as follows:
The MUX must be initialized, along with assorted buffer manipulation libraries. The instances must attach themselves to the MUX. The network code queries the bootline information in order to set the IP address of the boot interface.
B
Due to this sequence, the network device initialization cannot occur before the call to sysNetHwInit( ) because the devices cannot register with the MUX. In addition, the devices cannot perform their initialization after the call to sysNetHwInit( ) completes, or they do not have access to the IP address configured from bootline information. The solution in this case is for the network stack to define a driver method, called muxDevConnect( ). Early in the routine usrNetEndLibInit( ), the network stack makes a call to vxbDevMethodRun( ) which calls the muxDevConnect( ) method for each instance which supports it.
Serial Port Initialization
Before the introduction of VxBus, the BSP supplied the sysSerialChanGet( ) function. Under VxBus, sysSerialChanGet( ) moves without change to VxBus (installDir/vxworks-6.x/target/src/hwif/util/sioChanUtil.c) where it can be called by applications as it was previously. BSPs now provide a routine called bspSerialChanGet( ) with the same arguments as sysSerialChanGet( ). The BSP-version provides the SIO_CHAN structure for serial devices which have legacy drivers instead of VxBus drivers. From the application view, nothing has changed. From the BSP point of view, the name of the BSP sysSerialChanGet( ) routine must be changed to bspSerialChanGet( ).
175
B.7 Hardware Configuration File

Hardware configuration for static information is kept in a file in the BSP, called hwconf.c. This file contains tables which describe the hardware register addresses, interrupt vectors, and other hardware-specific information for static hardware. This file is a candidate for automatic generation. However, for this release, the file must be created and maintained manually.
B.7.1 Structures
Two structures are used in the hwconf.c file. They are struct hcfResource[ ] and struct hcfDevice[ ]. Information about each statically configured device on the system is kept in a separate array of hcfResource[ ] records for that device. The number of entries in each hcfResource[ ] table is defined as a macro value for use later in the file. At the end of hwconf.c is a table of hcfDevice structures called hcfDeviceList[ ]. This table contains a single entry for each device on the PLB and additional entries as required for devices or connectors on other bus types. Each entry in hcfDeviceList[ ] contains, among other things, a pointer to a resource table (a table of hcfResource structures) specific to that device, and a count of the number of entries in the resource table. For more information about these structures, refer to installDir/vxworks-6.x/target/h/hwif/vxbus/hwConf.h.
hcfResource[ ] Parameters
Each resource is referred to by name, and the names are represented as ASCII string values. They are case sensitive.
hcfResource[ ] Values
Each resource must be associated with a single value. The value can take one of several types: integer, string, or pointer. The use of pointer values is not recommended, but is available for those very rare cases where it is required. Both the type and the name are used in selection of the value, so the type field must match the type the driver expects.
176
B Migrating to the New VxBus B.7 Hardware Configuration File
hcfResource[ ] Structure
Each hcfResource[ ] structure contains three fields: a string representing the resource name, a type field representing the type of the value associated with the resource, and the value itself. In the hwconf.c file, all values are cast to void * in order to reduce compile-time warning messages.
Standard Parameters
There are several standard parameters that are expected to be associated with each statically-configured device. In some cases, these values are required.
Table B-1 Standard Parameters
Resource Name
Type
regBase interrupts
type RES_INT type RES_INT (see B.7.2 Interrupt Information, p.177)
B.7.2 Interrupt Information

In the PLB, any number of interrupt vectors can be associated with a single device. VxBus defines a standard naming scheme, with several commonly-used options for the vector names. The following table provides the names for each interrupt vector number. The names are case sensitive.
Table B-2 Interrupt Vector Naming Scheme
Number
Options
0 1 2 3 4 ... 64
intr0, intr, irq, txInt intr1, rxInt intr2, errInt intr3 intr4 ... intr64
177
B.8 Optimization Issues

VxBus provides several mechanisms for optimization of accesses to device registers. This section discusses some issues related to the optimization, and why optimization cannot be performed in some cases. There are three levels of optimization for the routines drivers use to get access to device registers. The levels of optimization are: basic optimization mimics the hardware, with at least one function call for every bus between the processor and the device. It is inevitably very slow. internal optimization provides a single routine for each register size that allows a driver to access the device registers. There is the overhead of exactly one subroutine call for each register access. In many cases, this equals the current performance, since a subroutine is sometimes used for things such as processor pipeline flush, and previous versions of VxWorks sometimes use a subroutine even when it is not required. Remember that the interface between the driver and the sysDev.c file uses subroutine calls, as well. In any case, where VxWorks 6.2 is already efficient, internal optimization will be slower. BSP-provided optimization provides a mechanism for the BSP developer to provide inline code for those cases where there is a critical need to have the fastest possible code.
B.8.1 Internal Optimization

Only a select set of operations can be optimized. This includes:

byte-sized-order transformations on the data (swap even/odd bytes) short-order transformations on the data (swap even/odd 16-bit values) processor pipeline flush perform operation in I/O space read-after-write bit-order transformations on the data (probably never needed) long-order transformations on the data (probably never needed)
This example illustrates the X-order operations listed. The before-transformation value for reference in each case is 0x12.34.56.78.9a.bc.de.f0. Of course, the size of the operation determines how much of the data is actually transformed.
178
B Migrating to the New VxBus B.8 Optimization Issues
The after-transformation values are: byte-order word-order long-order 0x34.12.78.56.bc.9a.f0.de 0x56.78.12.34.de.f0.9a.bc 0x9a.bc.de.f0.12.34.56.78
Byte-order and word-order transformations usually occur together, yielding 0x78.56.34.12.f0.de.bc.9a The bit-order transformations should normally be handled by the hardware. However, in case it is ever needed, it can be made available. The 1-byte operation is: 0x12 -> 0x48 (0b00010010 -> 0b01001000). Internal optimizations cannot be made at the bus level for other operations. The accesses should continue to work, but they will not be high-performance. Some of the operations which cannot be optimized include:
virtual address mapping reading/writing registers not visible to the CPU non-contiguous register address interleave
B.8.2 BSP-supplied Optimization

Drivers need to be aware of both the BSP-provided access methods and the standard access methods. From the perspective of the driver, the basic methods and the internally optimized methods are equivalent. In most cases, the BSP would only provide BSP-optimized versions for very high speed devices such as gigabit ethernet, some high-performance disk controllers, and some bus controllers (for example, a USB host controller) where high throughput demands inline-speed register access. This is not a strict requirement, but is instead an assumption about the results of the design trade-off between increased performance and increased effort. There are situations where the BSP-supplied optimization methods may be required, and where there are difficulties in creating them. In general, BSP-provided optimizations are more difficult when different instances may control hardware on different bus types or on incompatible interfaces. For example, in the case of serial controllers, there may be a situation where a high-speed serial network connection (for example, SLIP) is based on a serial port on a big-endian PLB bus, running at high speed and requiring high-performance access methods. At the same time, a different port of the same type, but on a
179
little-endian PCI bus, is used for console output. In such a case, the BSP-supplied optimization methods would be required for the SLIP port, but not for the console port. For this case, there are several possible solutions:
BSP-supplied Optimization Strategy #1
In most cases, a driver written to support devices on multiple bus types can have optimized access methods which work only on one bus. If the device is only found on that bus type, then support for other bus types may be superfluous, and the presence of optimized methods which preclude the unsupported bus types will not be a problem.
In some cases, it may be most convenient to provide complex BSP-supplied optimization methods which branch depending on the value of pDev->pRegBase[i] and run the appropriate code. This code is slower than if no such test were required, but may still be as fast as existing BSP code for pre-VxBus drivers. In the base case, there are several conditions for this. If the processor byte-order is the same as PCI, if the registers for both devices are visible from the processor, and if the registers are in the same address space (for example, I/O space or memory space), then it is possible to use BSP-supplied inline register access. The BSP-supplied access method reads the values from the pRegBase[ ] entry, masks them appropriately, and makes the appropriate read or write transaction. In the worst case, the optimization code still reads the pRegBase[ ] entry and masks it appropriately, but it then performs different byte-order and other manipulations depending on the value in pRegBase[ ].
In the most extreme cases, it may be better to split the driver into bus-specific variants, using preprocessor token merging so that the source code is not actually duplicated.
180
C
Conversion to apigen
Summary of apigen Markup
Table C-1 is a summary of apigen markup. It also shows the corresponding mangen markup for those more familiar with that style. For details, see the reference entry for apigen and the conversion steps provided in Step 13 on page 53.
Table C-1 apigen Markup
Column
apigen Markup
Mangen Equivalent
Description
any any any any any 1
'text ...' or 'text ...' <text> \\ or \/ \< \> \ \ \| \ss

...
same same \e N/A N/A .tS ... .tE .CS ... .CE
boldface words italicized words (text variables, emphasis) the character \ the characters < > the character | within a table preformatted text (syntax)
\se 1 \cs
...
literal text (code)
\ce
181
Table C-1
apigen Markup (contd)
Column
apigen Markup
Mangen Equivalent
Description
\bs
...
\be 1 \is \i item \ie \ml \m mark \me \ts

...
.bS ... .bE .iP or .IP
literal text, smaller (board layout)
itemized list (terms list)
.iP or .IP
marker list (numbered or dashed)
\te 1 1 \sh text \tb reference
.TS ... .TE .SS text
table
subheading
.I, .pG, .tG cross-reference to a publication
NOTE: In Table C-1, any denotes inline markup (it can appear anywhere in text); 1 denotes a tag that must start in effective column 1.
182
Index
Symbols
.ctors sections 108 .dtors sections 108 _exit( ), changed 132 _func_excBaseHook, use of private function pointer 75 _KERNEL flag removed 81 _VXWORKS_COMPATIBILITY_MODE macro 121 _WRS_DEPRECATED macro 118
A
access( ), changed 95, 124 accessing objects, changed from VxWorks AE 148 activeQhead, removed 20 aio_fsync( ) added, application 124 changed, kernel 95 alarm( ) changed 129 apigen BSP conversion 54 markup summary 181 APIs added application aio_fsync( ) 124 chmod( ) 124
fcntl( ) 124 fdatasync( ) 124 fpathconf( ) 124 fsync( ) 124 link( ) 124 pathconf( ) 124 pthread_atfork( ) 124 pthread_setschedprio( ) 124 sysconf( ) 124 uname( ) 124 kernel cacheFlush( ) 78 cacheInvalidate( ) 78 cdromFsDevCreate( ) 88 cdromFsVersionDisplay( ) 88 cdromFsVersionNumGet( ) 88 hrfsFormat( ) 91 iosDevCallback( ) 98 iosDevReplace( ) 98 iosDevResume( ) 98 iosDevSuspend( ) 98 msgQInitialize( ) 78 partLib.c 88 semBInitialize( ) 78 semCInitialize( ) 78 semMInitialize( ) 78 wdInitialize( ) 78 xbdBlkDevLibCreate( ) 88 xbdBlkDevLibDelete( ) 88 xbdBlkDevLibInit( ) 88
183
xbdCreatePartition( ) 88 xbdRamDiskDevCreate( ) 88 xbdRamDiskDevDelete( ) 89 APIs changed application _exit( ) 132 alarm( ) 129 calloc( ) 131 clock( ) 131 getOptServ( ) 132 ioctl( ) 130 isatty( ) 130 kill( ) 128 malloc( ) 131 memPartAlloc( ) 132 mkdir( ) 131 mq_open( ) 127 mq_receive( ) 127 mq_send( ) 128 mq_unlink( ) 128 open( ) 130 pause( ) 129 pthread_attr_cond_wait( ) 126 pthread_attr_getdetachstate( ) 125 pthread_attr_getname( ) 125 pthread_attr_getopt( ) 125 pthread_attr_getschedpolicy( ) 125 pthread_attr_getstackaddr( ) 125 pthread_attr_getstacksize( ) 125, 126 pthread_attr_init( ) 125 pthread_attr_setdetachstate( ) 126 pthread_attr_setname( ) 126 pthread_attr_setopt( ) 126 pthread_attr_setschedpolicy( ) 126 pthread_attr_setscope( ) 125 pthread_attr_setstackaddr( ) 126 pthread_cond_timedwaitt( ) 126 pthread_create( ) 126 pthread_getschedparam( ) 126 pthread_setschedparam( ) 127 queue( ) 128 read( ) 130 rename( ) 131 sched_getpriority_max( ) 132 sched_getpriority_min( ) 132
sched_rr_get_interval( ) 132 sem_init( ) 127 sem_open( ) 127 sem_unlink( ) 127 signal( ) 128 sigtimedwait( ) 128 sigwaitinfo( ) 129 sleep( ) 129 unlink( ) 131 vmBaseLib 140 write( ) 131 kernel access( ) 95, 124 aio_fsync( ) 95 chmod( ) 95 dosFsDevCreate( ) 93 dosFsVolFormat( ) 93 fcntl( ) 95 fdatasync( ) 95 fpathconf( ) 95 ioctl( ) 90 iosDevDelete( ) 98 iosDevRemove( ) 98 pthread_attr_getdetachstate( ) 97 pthread_attr_getname( ) 97 pthread_attr_getopt( ) 97 pthread_attr_getschedpolicy( ) 96 pthread_attr_getstackaddr( ) 97 pthread_attr_getstacksize( ) 97 pthread_attr_init( ) 96 pthread_attr_setdetachstate( ) 97 pthread_attr_setname( ) 97 pthread_attr_setopt( ) 96 pthread_attr_setschedpolicy( ) 96 pthread_attr_setscope( ) 96 pthread_attr_setstackaddr( ) 97 pthread_create( ) 94, 96 pthread_getschedparam( ) 96 pthread_setschedparam( ) 96 sigtimedwait( ) 97 sigwaitinfo( ) 98 timer_getoverrun( ) 99 usrFsLib.c 91
184
Index
APIs deprecated application diskFormat( ) 139 diskInit( ) 139 kernel semOLib 80 taskCreat( ) 75 APIs moved kernel isascii( ) 69 toascii( ) 69 APIs not present in RTPs taskSwitchHookAdd( ) 119 taskSwitchHookDelete( ) 119 APIs removed kernel cacheArchFlush( ) 78 cacheArchInvalidate( ) 78 ftpdLib 81 rt11fsLib 93 scsiSeqLib.c 93 semBCoreInit( ) 80 semCCoreInit( ) 80 semMCoreInit( ) 80 semQCoreInit( ) 80 tapeFsLib.c 93 usrFdiskPartCreate( ) 89 APIs with changed scope in RTPs asctime_r( ) 121 ctime_r( ) 121 gmtime_r( ) 121 localtime_r( ) 121 strerror( ) 121 APIs, system viewer changed wvUploadStart( ) 103 removed wvEvtLogInit( ) 103 wvLogHeaderCreate( ) 103 wvLogHeaderUpload( ) 103 wvTaskNamesPreserve( ) 103 wvTaskNamesUpload( ) 103 application model, changed from VxWorks AE 142 architecture models, participants, VxBus 158 architecture-specific migration issues 40
asctime_r( ), scope changes in RTP 121 attributes constructor 109 destructor 109
B
backlog, parameter 35 backward compatibility 5.5 bootloaders 24 kernel mode 66 vmBaseLib not 79 boot loaders, 5.5 compatible 24 BSD-style drivers not supported 33 BSPs apigen 53 building, compiler warnings 50 compatibility checklist 39 compatibility with VxWorks 6.1 10 default features enabled 11 drivers replaced 82 modifications, VxBus 169 participant, VxBus 156 porting 43 porting, ETHERNET_ADR_SET 52 porting, ETHERNET_MAC_HANDLER requirements, VxBus 159 source compatible only 10 build flags, setting 15 build infrastructure, changes 13 build specification, glossary definition 4 build utility, wrconfig 68 building kernel from Workbench 61 user applications 18 VxWorks from command line 57 bundled PPP 102 bus discovery, glossary definition 154 bus type, participant, VxBus 157 bus, glossary definition 154
Index
52
185
C
C++ components removed, obsolete 12 cache attributes MMU_ATTR_CACHE_MSK 100 MMU_ATTR_CACHE_OFF 100 MMU_ATTR_CACHE_WRITETHRU 100 MMU_ATTR_SUP_RWX 100 MMU_ATTR_USR_RWX 100 MMU_ATTR_xxx 46 cache library APIs, updating 48 cache state definitions, Pentium BSPs, new 47 cacheArchFlush( ), removed 78 cacheArchInvalidate( ), removed 78 cacheFlush( ), added 78 cacheInvalidate( ), added 78 cacheLib, private headers 78 calloc( ) changed 131 cdromFsDevCreate( ), added 88 cdromFsVersionDisplay( ), added 88 cdromFsVersionNumGet( ), added 88 changed directory structure 13 loader 71 memory mapping 22 changes VxWorks 6.0 to VxWorks 6.1 27 VxWorks components 99 changing version number, config.h 51 child, glossary definition 154 chmod( ) added, application 124 changed, kernel 95 clock( ) changed 131 command line building VxWorks 57 customizing VxWorks with vxprj 56 sample boot output 58 validating a ported BSP 55 VxWorks 5.x boot loaders 57 compilation context, VxBus drivers 165 compiler extra command-line flags 15 new warning and error levels 16 options, GNU 16
specifying path 14 stricter syntax 21 VxWorks AE, changed from 147 warnings, building BSPs 50 compiling user and kernel modes 106 VxWorks 6.1 vs 5.5 environments 69 component model, changed from VxWorks AE 146 components glossary definition 4 INCLUDE_BSD 83 INCLUDE_CONSTANT_RDY_Q 12 INCLUDE_EDR_SYSDBG_FLAG 24 INCLUDE_EDR_XXX 11 INCLUDE_EXC_TASK 33 INCLUDE_ISR_OBJECT 11 INCLUDE_JOB_TASK 34 INCLUDE_MEM_EDR 33 INCLUDE_MMU_BASIC 100 INCLUDE_POSIX_CLOCKS 11 INCLUDE_POSIX_PTHREAD_ SCHEDULER 136 INCLUDE_PROTECT_STACK 29 INCLUDE_RTP 11 INCLUDE_RTP_APPL_INIT_BOOTLINE 25 INCLUDE_RTP_APPL_INIT_CMD_SHELL_ SCRIPT 25 INCLUDE_RTP_APPL_INIT_STRING 25 INCLUDE_RTP_APPL_USER 25 INCLUDE_SHARED_DATA 11 INCLUDE_SHARED_LIBRARIES 11 INCLUDE_SM_NET 83 INCLUDE_SMEND 83 INCLUDE_VXEVENTS 11 INCLUDE_VXWORKS_5_X_EQUIV_PPP 12 POSIX_PTHREAD_RR_TIMESLICE 136 config.h replaced 12 configuration, VxBus 158 constructor attribute 109 ctime_r( ), scope changes in RTP 121 custom BSPs, migrating makefiles 18 customizing VxWorks with vxprj from command line 56 with Workbench 60
186
Index
D
default compiler change 14 definitions build specification 4 component 4 deprecated 5 downloadable kernel module project 4 error detection and reporting 4 graphical user interface 5 project 4 real-time process project 4 RTP 3 shared-library project 4 toolchain 4 VxWorks image project 4 workspace 4 DELAYTIMER_MAX macro 99 deprecated, glossary definition 5 design issues, RTPs communicating between RTPs 107 communicating with kernel 108 destructor attribute 109 device drivers, VxBus participants 157 device, glossary definition 154 Dinkum Standard Template Library 20 discontinued dosFs 1.0 37 dosFs long file name support 37 tapeFs 37 diskFormat( ), deprecated 139 diskInit( ), deprecated 139 dosFs 1.0 discontinued 37 dosFs long file name support discontinued 37 dosFsDevCreate( ), changed 93 dosFsVolFormat( ), changed 93 downloadable kernel module project, glossary definition 4 downstream, glossary definition 154 driver method glossary definition 155 VxBus 165 driver modifications VxBus full participation 172 VxBus registration only 171
driver, glossary definition 154 drivers registration, VxBus 160 source-compatible only 32 dup( ), I/O redirection 111 dup2( ), I/O redirection 111
E
ED&R, see error detection and reporting errno changes, loader 27 error detection and reporting adding to BSP 49 glossary definition 4 reserved memory required 23 error-checking, semaphores 34 escJobAdd( ),newly public 79 etherAddrResolve( ) removed 82 Ethernet MAC address, boot loaders 52 ETHERNET_ADR_SET, include macro 52 ETHERNET_MAC_HANDLER, include macro 52 example, VxWorks 5.5 BSP to VxWorks 6. 1 43 excJobAdd( ), replaces excTask( ) 79 excTask( ), newly private 79 exit( ), scope changes in RTP 113 exported entry points (VxWorks AE) 143 extended block device, summary 36
Index
F
fcntl( ) added, application 124 changed, kernel 95 fdatasync( ) added, application 124 changed, kernel 95 file descriptor inheritance, changed in RTP file system changes, summary 35 removability support 36 finalization code 108 FIODISKCHANGE, removed 90
30
187
FIOFORMAT, removed 90 flags _KERNEL, removed 81 build, setting 15 GNU -fno-exception 21 -fno-rtti 21 GNU compiler 16 fpathconf( ) added, application 124 changed, kernel 95 fsync( ), added 124 ftpdLib removed 81
stdio.h 135 strings.h 135 time.h 135 unistd.h 135 changes to 13 kernel mode 13 user mode 13 host and target shells (VxWorks AE) hrfsFormat( ), added 91
148
I
I/O errnos duplicate 85 unique 86 I/O redirection VxWorks 5.5 111 VxWorks 6.x 112 I/O system, POSIX compliance 85 INCLUDE_CONSTANT_RDY_Q replaced 12 INCLUDE_EDR_XXX, disabled by default 11 INCLUDE_ISR_OBJECT, no longer included by default 11 INCLUDE_PLB_BUS, macro added, VxBus 158 INCLUDE_POSIX_CLOCKS, automatic with POSIX timers 11 INCLUDE_RTP, default changed 11 INCLUDE_SHARED_DATA, disabled by default 11 INCLUDE_SHARED_LIBRARIES, disabled by default 11 INCLUDE_VX_NATIVE_SCHEDULER, configuring 12 INCLUDE_VXBUS, macro added, VxBus 158 INCLUDE_VXEVENTS, no longer included by default 11 initialization code 108 installed location, online documentation 2 instance creation VxBus automatic 166 VxBus driver-provided probe 167 instance, glossary definition 155 intended audience, this guide 2
G
getOptServ( ) changed 132 gmtime_r( ), scope changes in RTP 121 graphical user interface, glossary definition GUI, see graphical user interface 5
H
hardWareInterFaceInit( ) 169 hashLib, private headers 79 hcfDeviceList[ ] VxBus BSP modifications 169 VxBus hardware configuration file 176 hcfResource[ ], VxBus parameters 176 header files added sys/select.h 133 sys/time.h 133 sys/utsname.h 133 sys/wait.h 133 version.h 133 changed limits.h 134 math.h 134 pthread.h 134 sched.h 135 signal.h 135
188
Index
interrupt service routine 31 interrupts, VxBus handling 164 information 177 intLock( ), no user mode 119 intUnlock( ), no user mode 119 ioctl( ) changed, application 130 commands changed, kernel 90 iosDevCallback( ), added 98 iosDevDelete( ), changed 98 iosDevRemove( ), changed 98 iosDevReplace( ), added 98 iosDevResume( ), added 98 iosDevSuspend( ), added 98 IP forwarding default 82 IPv4/IPv6 dual network stack 69 isascii( ) moved 69 isatty( ), changed, application 130 ISR, see interrupt service routine
loadModuleAt( ), reloading from a program 31 localtime_r( ), scope changes in RTP 121
M
MACH_EXTRA linking configlettes 45 linking custom architecture code 45 main( ) routine, entry point 142 makefiles, migrating custom BSPs 18 malLib, module access layer support 146 malloc( ) changed 131 MEM_GROW_ENABLE parameter 146 MEM_RECLAIM_ENABLE parameter 146 memAttrLib, VxWorks AE library 145 memory management, changed, from VxWorks AE 143 memory model, changed, from VxWorks AE 142 memory partition options applications 137 kernel 76 memory protection macros 46 memPartAlloc( ) changed 132 method ID, glossary definition 155 migration architecture-specific issues 40 BSPs sysEnetAddrGet( ) 52 sysMemTop( ) 50 sysNetMacNVRamAddrGet( ) 52 sysPhysMemTop( ) 50 checklist, kernel applications 67 custom BSP makefiles 18 dosFs1 to dosFs2 92 options 66 options, kernel mode 66 versions older than VxWorks 5.5, from 6 mkdir( ) changed 131 MMU, protected RTP requires 23 MMU_ATTR_CACHE_MSK, cache attribute 100 MMU_ATTR_CACHE_OFF, cache attribute 100 MMU_ATTR_CACHE_WRITETHRU, cache attribute 100 MMU_ATTR_IO, VxWorks AE cache attribute 146
Index
K
kernel applications building from command line 57 building from Workbench 61 kernel shell, multiple sessions 30 KERNEL_HEAP_SIZE, parameter 145 kill( ) changed, application 128 scope changes in RTP 113
L
libraries, Dinkum C and C++ 19 link( ), added 124 loader changed 71 errno changes 27 routines removed in VxWorks 6.1 28 loader macros, use symbolic names 72 loadModule( ), reloading from a program 31
189
MMU_ATTR_SUP_RWX, cache attribute 100 MMU_ATTR_USR_RWX, cache attribute 100 MMU_ATTR_xxx, cache attribute 46 module management, changed (VxWorks AE) 146 mprotect( ), replaces vmStateSet( ) and vmBaseStateSet( ) in user mode 140 mq_des changed (POSIX message queues) 94 mq_open( ) changed 127 mq_receive( ) changed 127 mq_send( ) changed 128 mq_unlink( ) changed 128 msgQInitialize( ), added, kernel 78
optimization, VxBus BSP-supplied 179 internal 178 orphan device, glossary definition 155 overview, VxBus model 156
P
parameter type change physical address, virtual memory routines 102 virtual address, virtual memory routines 101 parameters added, KERN_VERSION 137 backlog 35 changed RTP_SIGNAL_QUEUE_SIZE 136 RTSIG_MAX 136 SIGQUEUE_MAX 136 vmBaseLibInit( ) 79 KERNEL_HEAP_SIZE 145 MEM_GROW_ENABLE 146 MEM_RECLAIM_ENABLE 146 parent, glossary definition 155 partLib.c, added 88 pathconf( ), added 124 pathLib.h, type changes 68 pause( ) changed 129 PCI bus type, VxBus requirements 169 Pentium BSPs, new cache state definitions 47 per-device data, glossary definition 155 pgMgrLib, VxWorks AE 145 pgPoolLib, VxWorks AE 145 pgPoolLstLib, VxWorks AE 145 PHYS_ADDR parameter 47 type changed 102 PLB bus type, VxBus requirements 168 PM_RESERVED_MEM example 23 required for error detection and reporting 50 porting a BSP introduction 43 to VxWorks 6.1, steps 44
N
network header files changed 69 deprecated 81 removed 81 networking changes, summary 27 new configuration process 12 features, including 22 parameter exception overflow 29 kernel stack overflow 29 kernel stack underflow 29 user stack overflow 29 user stack underflow 29
O
OBJ_VERIFY( ) relocated 69 object ownership, tracking 31 objLib now public 79 private headers 69 open( ) changed 130 OPT_LOWERCASE option with dosFs optimization, -O3 not supported 17
92
190
Index
POSIX file system, application mkdir( ) 131 I/O, application fsync( ) 124 open( ) 130 read( ) 130 rename( ) 131 unlink( ) 131 write( ) 131 I/O, kernel access( ) 95 chmod( ) 95 fcntl( ) 95 fdatasync( ) 95 fpathconf( ) 95 fsync( ) 95 iosDevCallback( ) 98 iosDevDelete( ) 98 iosDevRemove( ) 98 iosDevReplace( ) 98 iosDevResume( ) 98 iosDevSuspend( ) 98 ISO C, application _exit( ) 132 calloc( ) 131 malloc( ) 131 libc, application clock( ) 131 message queues, application mq_open( ) 127 mq_receive( ) 127 mq_send( ) 128 mq_unlink( ) 128 scheduling, application sched_getpriority_max( ) 132 sched_getpriority_minn( ) 132 sched_rr_get_interval( ) 132 semaphores, application sem_init( ) 127 sem_open( ) 127 sem_unlink( ) 127 signals, application kill( ) 128 queue( ) 128
signal( ) 128 sigtimedwait( ) 128 sigwaitinfo( ) 129 signals, kernel sigtimedwait( ) 97 sigwaitinfo( ) 98 thread scheduler, behavior 122 threads, application pthread_atfork( ) 124 pthread_attr_cond_wait( ) 126 pthread_attr_getdetachstate( ) 125 pthread_attr_getname( ) 125 pthread_attr_getopt( ) 125 pthread_attr_getschedpolicy( ) 125 pthread_attr_getstackaddr( ) 125 pthread_attr_getstacksize( ) 125 pthread_attr_init( ) 125 pthread_attr_setdetachstate( ) 126 pthread_attr_setname( ) 126 pthread_attr_setopt( ) 126 pthread_attr_setschedpolicy( ) 126 pthread_attr_setscope( ) 125 pthread_attr_setstackaddr( ) 126 pthread_attr_setstacksize( ) 126 pthread_cond_timedwait( ) 126 pthread_create( ) 126 pthread_getschedparam( ) 126 pthread_setschedparam( ) 127 pthread_setschedprio( ) 124 threads, kernel pthread_attr_getdetachstate( ) 97 pthread_attr_getname( ) 97 pthread_attr_getopt( ) 97 pthread_attr_getschedpolicy( ) 96 pthread_attr_getstackaddr( ) 97 pthread_attr_getstacksize( ) 97 pthread_attr_init( ) 96 pthread_attr_setdetachstate( ) 97 pthread_attr_setname( ) 97 pthread_attr_setopt( ) 96 pthread_attr_setschedpolicy( ) 96 pthread_attr_setscope( ) 96 pthread_attr_setstackaddr( ) 97 pthread_attr_setstacksize( ) 97 pthread_create( ) 94, 96
Index
191
pthread_getschedparam( ) 96 pthread_setschedparam( ) 96 timers, application pause( ) 129 sleep( ) 129 POSIX message queues, mq_des changed 94 POSIX semaphores, sem_t moved 95 POSIX signals in RTPs 115 POSIX support, summary 37 POSIX timers, difference from watchdogs 111 power management, summary 26 PPP new implementation 12 not available in RTP 140 private headers cacheLib 78 hashLib 79 objLib 69 probe routine, glossary definition 155 probe, glossary definition 155 project, glossary definition 4 protected RTP requires MMU 23 pthread_atfork( ), added, application 124 pthread_attr_cond_wait( ) changed, application 126 pthread_attr_getdetachstate( ) changed, application 125 changed, kernel 97 pthread_attr_getname( ) changed, application 125 changed, kernel 97 pthread_attr_getopt( ) changed, application 125 changed, kernel 97 pthread_attr_getschedpolicy( ) changed, application 125 changed, kernel 96 pthread_attr_getstackaddr( ) changed, application 125 changed, kernel 97 pthread_attr_getstacksize( ) changed, application 125 changed, kernel 97
pthread_attr_init( ) changed, application 125 changed, kernel 96 pthread_attr_setdetachstate( ) changed, application 126 changed, kernel 97 pthread_attr_setname( ) changed, application 126 changed, kernel 97 pthread_attr_setopt( ) changed, application 126 changed, kernel 96 pthread_attr_setschedpolicy( ) changed, application 126 changed, kernel 96 pthread_attr_setscope( ) changed, application 125 changed, kernel 96 pthread_attr_setstackaddr( ) changed, application 126 changed, kernel 97 pthread_attr_setstacksize( ) changed, application 126 changed, kernel 97 pthread_cond_timedwait( ) changed, application 126 pthread_create( ) changed, application 126 changed, kernel 94, 96 pthread_getschedparam( ) changed, application 126 changed, kernel 96 pthread_setschedparam( ) changed, application 127 changed, kernel 96 pthread_setschedprio( ), added
124
R
raise( ), scope changes in RTP 113 RAM disk, BLK_DEV-based, deprecated 37 read( ) changed 130 real-time process project, glossary definition 4 real-time process, see RTP
192
Index
region.sdf, no longer maps memory 145 register access routines, VxBus BSP-specific 163 standard 163 reld( ) callable from shell only 31 moved to usrLib.c 31 reloading from a program loadModulAt( ) 31 loadModule( ) 31 rename( ) changed 131 resource reclamation kernel 31 kernel task create hooks 32 RTP post-create hooks 32 user task calls kernel routine 32 routeAdd( ), not supported, user mode 117 routines not present in user mode intLock( ) 119 intUnlock( ) 119 routeAdd( ) 117 rt11fsLib, removed 93 RTP initial task name, changed 30 rtpRaise( ), alternative to raise( ) in RTP 114 RTPs default signal handling 116 glossary definition 3 header files 118 I/O redirection 111 introduction 105 networking issues 117 no drivers 111 no hardware access 109 no interrupt context 110 no watchdogs 110 process vs task APIs 113 routines differing from kernel 120 scope of signal handlers 116 semaphores in 114 signals behavior 117 delivery 115 generation 115 mask 116 sent to blocked tasks 116
startup facility 25 task locking/unlocking 114 user-mode-only APIs 120 rtpSigqueue( ), alternative to sigqueue( ) in RTP 114 rtpSpawn( ), in RTP 145
S
salCreate( ), sockopt structure changed 34 salSockopt replaces sockopt 34 sample boot output command line 58 Workbench 62 scalability 38 sched_getpriority_max( ) changed 132 sched_getpriority_min( ) changed 132 sched_rr_get_interval( ) changed 132 scope changes in RTPs exit( ) 113 kill( ) 113 raise( ) 113 sigqueue( ) 114 scope of signal handlers, RTPs 116 scsiSeqLib.c, removed 93 sdAttach( ), shared data 150 sdCreate( ), shared data 150 sdDelete( ), shared data 150 sdDetach( ), shared data 150 sdMap( ), shared data 150 sdOpen( ), shared data 150 sdShow( ), shared data 150 sdUnMap( ), shared data 150 sections .ctors 108 .dtors 108 sem_init( ) changed 127 sem_open( ) changed 127 sem_t moved (POSIX semaphores) 95 sem_unlink( ) changed 127 semaphore changes in RTPs semGive( ) 114 semInfoGet( ) 115
Index
193
semOpen( ) 115 semTake( ) 114 semaphores in RTPs 114 stricter error-checking 34 semBCoreInit( ) removed 80 semBInitialize( ), added, kernel 78 semCCoreInit( ) removed 80 semCInitialize( ), added, kernel 78 semGive( ), semaphore 114 semInfoGet( ), semaphore 115 semMCoreInit( ) removed 80 semMInitialize( ), added, kernel 78 semOLib deprecated 80 semOpen( ), semaphore 115 semQCoreInit( ) removed 80 semTake( ), semaphore 114 SGI standard template library, no longer supported 15 SH C++ libraries 15 shared data regions, changed from VxWorks AE 150 sdAttach( ) 150 sdCreate( ) 150 sdDelete( ) 150 sdDetach( ) 150 sdMap( ) 150 sdOpen( ) 150 sdShow( ) 150 sdUnMap( ) 150 shared libraries, changed from VxWorks AE 149 shared memory END driver, BSP support 83 shared-library project, glossary definition 4 SHELL_COMPATIBLE, parameter 31 shellPromptFmtDftSet( ), shell prompt default 30 shellPromptSet( ), shell prompt 30 signal behavior, RTPs 117 signal( ) changed 128 sigqueue( ) changed, application 128 scope changes in RTP 114 sigtimedwait( ) changed, application 128 changed, kernel 97
sigwaitinfo( ) changed, applications 129 changed, kernel 98 sleep( ) changed 129 smEnd, upgraded shared memory driver 33, 83 sockopt changed 34 source files, VxBus 159 source-compatible only, drivers 32 specifying, compiler path 14 standard template library 20 Dinkumware 20 SGI 15 STL, see standard template library strerror( ), scope changes in RTP 121 stricter syntax, compilers 21 string.h, VxWorks compatibility mode 121 symbol references, changed from VxWorks AE 151 symbol types, changed 71 symbolic names, loader, eliminate numeric values 72 sysconf( ), added 124 sysEnetAddrGet( ), migrating BSP 52 sysHwInit2( ) 169 sysMemTop( ) changed from VxWorks AE 145 migrating BSPs 50 sysNetHwInit( ), VxBus initialization, network 175 sysNetMacNVRamAddrGet( ), migrating BSP 52 sysPhysMemTop( ), migrating BSP 50 sysSerialChanGet( ), VxBus initialization, serial 175 sysSmEndLoad( ), created during shared memory migration 84 System Viewer events, new 25
T
tapeFs discontinued 37 tapeFsLib.c, removed 93 target requirements 5 target server, starting from Workbench 63 target.nr 53 target.ref 53
194
Index
task options not available in RTPs VX_SUPERVISOR 120 VX_UNBREAKABLE 120 task self-destruction, changed behavior 33 task state, BREAK vs STOP in VxWorks AE 148 TASK_KERNEL_EXEC_STACK_OVERFLOW_ SIZE, new parameter 29 TASK_KERNEL_EXEC_STACK_UNDERFLOW_ SIZE, new parameter 29 TASK_STACK_OVERFLOW_SIZE, removed in VxWorks 6.1 29 TASK_STACK_UNDERFLOW_SIZE, removed in VxWorks 6.1 29 TASK_USER_EXC_STACK_OVERFLOW_SIZE, new parameter 29 TASK_USER_EXEC_STACK_OVERFLOW_SIZE, new parameter 29 TASK_USER_EXEC_STACK_UNDERFLOW_SIZE, new parameter 29 taskCreat( ) deprecated 75 taskCreate( ), replaces taskInit( ) in user mode 119 taskDelete( ), task self-destruction 33 taskExit( ), replaces taskExit( ) in user mode 113 taskInit( ), not present in user mode, use taskCreate( ) 119 taskKill( ), replaces taskKill( ) in user mode 113 taskName( ), replacing direct access to TCB 74 taskRaise( ), replaces raise( ) in user mode 113 taskRtpLock( ) eliminating hardware access from RTP 109 locking in an RTP 114 replaces taskLock( ) in user mode 119 taskRtpUnlock( ) eliminating hardware access from RTP 109 replaces taskLock( ) in user mode 119 unlocking in an RTP 114 taskSigqueue( ), replaces taskSigqueue( ) in user mode 114 taskSpawn( ), may replace when customizing VxWorks 60 taskStackAllot( ), newly public 79 taskSwitchHookAdd( ) replaced in RTPs 119 scheduling change 74 taskSwitchHookDelete( ), replaced 119
timer.h, VxWorks compatibility mode 121 timer_cancel( ), replaces wdCancel( ) in RTPs 110 timer_connect( ), use in applications 110 timer_create( ), replaces wdCreate( ) in user mode 110 timer_delete( ), replaces wdDelete( ) in RTPs 110 timer_getoverrun( ), changed 99 timer_settime( ), use in applications 110 toascii( ) moved 69 toolchain, glossary definition 4 torVars replaced 17 type changes, loader 71 Index
U
uname( ), added 124 unld( ) callable from shell only 31 moved to usrLib.c 31 unldByModuleId( ), unloading from a program 31 unldByNameAndPath( ), unloading from a program 31 unlimited passing of object IDs in VxWorks AE 151 unlink( ) changed 131 unloading from a program unldByModuleId( ) 31 unldByNameAndPath( ) 31 unsupported optimization, -O3 17 upstream, glossary definition 155 user applications, building 18 user mode differences from previous releases 3 memory, driver access to 23 USER_APPL_INIT, RTP startup 25 USER_RESERVED_MEM, persistent memory in BSPs 50 usrFdiskPartCreate( ), removed 89 usrFsLib.c, changed 91
195
V
validating a ported BSP command line 55 Workbench 59 versions older than VxWorks 5.5, migrating from 6 VIRT_ADDR BSP macro 47 parameter type change 101 VM_PAGE_SIZE, BSP macro 45 VM_STATE_xxx, BSP macro 46 vmBaseLib not backward compatible 79 RTPs 140 vmBaseLibInit( ), changed 79 vmBaseStateSet( ), replaced in RTPs 140 vmContextCreate( ), removed 101 vmContextDelete( ), removed 101 vmContextShow( ), still present in kernel 101 vmCurrentGet( ), obsolete 101 vmCurrentSet( ), obsolete 101 vmGlobalInfoGet( ), obsolete 101 vmGlobalMap( ), obsolete 101 vmMap( ), still present in kernel 101 vmPageBlockSizeGet( ), obsolete 101 vmPageSizeGet( ), still present in kernel 101 vmShowInit( ), obsolete 101 vmStateGet( ), still present in kernel 101 vmStateSet( ) replaced by mprotect( ) user mode 140 still present in kernel 101 vmTextProtect( ), still present in kernel 101 vmTranslate( ), still present in kernel 101 VX_BINARY_SEMAPHORE, added 78 VX_COUNTING_SEMAPHORE, added 78 VX_MSG_Q, added 78 VX_MUTEX_SEMAPHORE, added 78 VX_SUPERVISOR not available in RTPs 120 VX_TASK, added 78 VX_TASK_INITIALIZE, added 78 VX_TASK_INSTANTIATE, added 78 VX_UNBREAKABLE not available in RTPs 120 VX_WD, added 78
vxbDevConnect( ) VxBus BSP modifications 169 VxBus initialization 174 vxbDevInit( ) VxBus BSP modifications 169 VxBus initialization 173 vxbDevInit2( ), VxBus initialization 174 vxbDevRegister( ) driver registration 160 initialization 173 vxbIntAcknowledge( ) 164 vxbIntConnect( ) 164 vxbIntDisable( ) 164 vxbIntDisconnect( ) 164 vxbIntEnable( ) 164 VxBus BSP modifications 169 BSP requirements 159 compilation context, drivers 165 configuration 158 driver methods 165 driver modifications full participation 172 registration only 171 driver registration 160 hardWareInterFaceInit( ) 169 hcfDeviceList[ ], hardware configuration file 176 hcfResource[ ], parameters 176 interrupt handling 164 interrupt information 177 optimization issues 178 overview, model 156 register access routines 163 requirements PCI bus type 169 PLB bus type 168 source files 159 sysHwInit2( ) 169 sysNetHwInit( ) initialization, network 175 sysSerialChanGet( ) initialization, serial 175
196
Index
vxbDevConnect( ) BSP modifications 169 initialization 174 vxbDevInit( ) BSP modifications 169 initialization 173 vxbDevInit2( ), initialization 174 vxbDevRegister( ) driver registration 160 initialization 173 vxbIntAcknowledge( ) 164 vxbIntConnect( ) 164 vxbIntDisable( ) 164 vxbIntDisconnect( ) 164 vxbIntEnable( ) 164 vxBusShow( ) 158 VxBus participants architecture models 158 BSP 156 bus type 157 device drivers 157 VxBus 157 VxBus, instance creation automatic 166 driver-provided probe 167 VxBus, optimization BSP-supplied 179 internal 178 vxBusShow( ) 158 VxFusion, replaced by message channels 27 vxMemProbeArch( ), use in simulator 75 VxVMI removed 99 replaced by RTPs 26, 139 routines, obsolete vmCurrentGet( ) 101 vmCurrentSet( ) 101 vmGlobalInfoGet( ) 101 vmGlobalMap( ) 101 vmPageBlockSizeGet( ) 101 vmShowInit( ) 101 routines, removed vmContextCreate( ) 101 vmContextDelete( ) 101
routines, still present in kernel vmContextShow( ) 101 vmMap( ) 101 vmPageSizeGet( ) 101 vmStateGet( ) 101 vmStateSet( ) 101 vmTextProtect( ) 101 vmTranslate( ) 101 VxWorks building from command line 57 building from Workbench 61 VxWorks 5.5 BSP to VxWorks 6.1, example 43 VxWorks 5.5, I/O redirection 111 VxWorks 5.x boot loaders command line 57 Workbench 61 VxWorks 6.x BSPs, features required 44 VxWorks 6.x, I/O redirection 112 VxWorks AE, changed from accessing objects 148 application model 142 compiler 147 component model 146 exported entry points 143 host and target shells 148 memory management 143 memory model 142 module management 146 shared data regions 150 shared libraries 149 symbol references 151 sysMemTop( ) 145 task state, BREAK vs STOP 148 unlimited passing of object IDs 151 VxWorks image project, glossary definition 4 VxWorks, 5.x compatibility 2
Index
W
watchdogs, difference from POSIX timers 111 wdCancel( ), unavailable in user mode 110 wdCreate( ), unavailable in user mode 110 wdDelete( ), unavailable in user mode 110 wdInitialize( ), added, kernel 78
197
wdStart( ), unavailable in user mode 110 Wind River Compiler (formerly Diab), now default 14 Wind River GNU compiler 14 Workbench building the kernel 61 customizing VxWorks 60 sample boot output 62 target server, starting 63 validating a ported BSP 59 VxWorks 5.x boot loaders 61 workspace, glossary definition 4 wrconfig build utility 68 wrenv command shell 55 environment setup 17 write( ) changed 131 wvEvent( ), available in RTPs 140 wvEvtLogInit( ), system viewer, removed 103 wvLib, system viewer 102 wvLogHeaderCreate( ), removed 103 wvLogHeaderUpload( ), removed 103 wvTaskNamesPreserve( ), removed 103 wvTaskNamesUpload( ), removed 103 wvUploadStart( ), changed 103
X
xbdBlkDevLibCreate( ), added 88 xbdBlkDevLibDelete( ), added 88 xbdBlkDevLibInit( ), added 88 xbdCreatePartition( ), added 88 xbdRamDiskDevCreate( ), added 88 xbdRamDiskDevDelete( ), added 89
198

Vxworks Migration Guide 6.2

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Vxworks Migration Guide 6.2

Transféré par

Droits d'auteur :

Formats disponibles

VxWorks Migration Guide

VxWorks Migration Guide, 6.2 18 Nov 05 Part #: DOC-15598-ZD-00

VxWorks Migration Guide, 6.2

Changes in the VxWorks Environment .............................................

VxWorks Migration Guide, 6.2

Determining If a BSP Requires Migration ........................................................ Architecture-Specific Issues .................................................................................

Porting a BSP to VxWorks 6.2 ............................................................. 43

Migrating VxWorks 5.5 Applications To the 6.2 Kernel .....................

VxWorks Migration Guide, 6.2

4.5.4 4.5.5 4.5.6

Migrating Applications to RTPs .......................................................... 105

VxWorks Migration Guide, 6.2

5.2.4 5.2.5 5.2.6

5.3.3 5.3.4 5.3.5 5.3.6 5.4

VxWorks Migration Guide, 6.2

Migrating Applications From VxWorks AE to VxWorks 6.x .............. 141

Migrating to the New VxBus ................................................................ 153

VxWorks Migration Guide, 6.2

Conversion to apigen ........................................................................... 181

Index .............................................................................................................. 183

VxWorks Migration Guide, 6.2

The VxWorks Migration Guide is intended for several groups of developers:

1 Overview 1.3 Key Concepts

1.3 Key Concepts

VxWorks Migration Guide, 6.2

1 Overview 1.5 Target Requirements

Graphical User Interface (GUI):

1.5 Target Requirements

VxWorks Migration Guide, 6.2

1.6 Summary of Contents

1.6.1 Changes in the VxWorks Environment

1.6.2 Porting a BSP to VxWorks 6.2

1.6.3 Migrating VxWorks 5.5 Applications to the 6.2 Kernel

1 Overview 1.6 Summary of Contents

1.6.4 Migrating Applications to RTPs

1.6.5 Migrating Applications From VxWorks AE to VxWorks 6.2

1.6.6 Migrating To the New VxBus

1.6.7 Conversion to apigen

VxWorks Migration Guide, 6.2

VxWorks Migration Guide, 6.2

WARNING: As with previous VxWorks 6.x releases, VxWorks 6.2 is source

2 Changes in the VxWorks Environment 2.2 Configuring Your System

2.2 Configuring Your System

2.2.1 Default Features

INCLUDE_RTP INCLUDE_SHARED_DATA INCLUDE_SHL INCLUDE_EDR_XXX

VxWorks Migration Guide, 6.2

2.2.2 Configuration Process

2.2.3 Obsolete C++ Components Removed

INCLUDE_CPLUS_STL INCLUDE_CPLUS_STRING INCLUDE_CPLUS_STRING_IO INCLUDE_CPLUS_COMPLEX INCLUDE_CPLUS_COMPLEX_IO INCLUDE_IOSTREAMS_FULL

2.2.4 Changed Scheduler Configuration Parameters

2.2.5 Wind River PPP Replaced

2.3 Building Your System and Applications

2.3.1 Header Trees

2.3.2 Directory Changes

VxWorks Migration Guide, 6.2

2.3.3 Compiler and Build Changes

Default Compiler Change

Extra Compiler Command-line Flags

Setting Additional Build Flags

C++ and STL

VxWorks Migration Guide, 6.2

Compiler Warning and Error Levels

GNU Compiler Changes