VxWorks Migration Guide, 6 - pudn.comread.pudn.com/.../vxworks_migration_guide_6.2.pdf · 1.6.3...

VxWorks

MIGRAT ION GUIDE

®

6.2

VxWorks Migration Guide

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 HeadquartersWind River Systems, Inc.500 Wind River WayAlameda, CA 94501-1153U.S.A.

toll free (U.S.): (800) 545-WINDtelephone: (510) 748-4100facsimile: (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

http://www.windriver.com/company/terms/trademark.html

http://www.windriver.com

http://www.windriver.com/support

iii

Contents

1 Overview ............................................................................................... 1

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.6.1 Changes in the VxWorks Environment ................................................. 6

1.6.2 Porting a BSP to VxWorks 6.2 ................................................................. 6

1.6.3 Migrating VxWorks 5.5 Applications to the 6.2 Kernel ...................... 6

1.6.4 Migrating Applications to RTPs ............................................................. 7

1.6.5 Migrating Applications From VxWorks AE to VxWorks 6.2 ............. 7

1.6.6 Migrating To the New VxBus ................................................................. 7

1.6.7 Conversion to apigen ............................................................................... 7

VxWorksMigration Guide, 6.2

iv

2 Changes in the VxWorks Environment ............................................. 9

2.1 Introduction ............................................................................................................. 9

2.2 Configuring Your System ..................................................................................... 11

2.2.1 Default Features ........................................................................................ 11

2.2.2 Configuration Process .............................................................................. 12

2.2.3 Obsolete C++ Components Removed ................................................... 12

2.2.4 Changed Scheduler Configuration Parameters ................................... 12

2.2.5 Wind River PPP Replaced ....................................................................... 12

2.3 Building Your System and Applications ........................................................... 13

2.3.1 Header Trees ............................................................................................. 13

2.3.2 Directory Changes .................................................................................... 13

2.3.3 Compiler and Build Changes ................................................................. 14

Default Compiler Change ....................................................................... 14Extra Compiler Command-line Flags .................................................... 15Setting Additional Build Flags ............................................................... 15C++ and STL ............................................................................................. 15SH C++ Libraries ...................................................................................... 15Compiler Warning and Error Levels ..................................................... 16GNU Compiler Changes ......................................................................... 16torVars Replaced ....................................................................................... 17

2.3.4 Building Real-Time Process (RTP) Applications .................................. 18

2.3.5 Migrating Custom BSP Makefiles .......................................................... 18

2.4 Writing Applications in C and C++ .................................................................... 19

2.4.1 New C/C++ Libraries .............................................................................. 19

2.4.2 Access to the TCB ..................................................................................... 20

2.4.3 No activeQhead ........................................................................................ 20

2.4.4 Standard Template Library ..................................................................... 20

2.4.5 Stricter Syntax ........................................................................................... 21

Contents

v

2.5 Accommodating New Features Introduced in VxWorks 6.0 .......................... 21

2.5.1 Including New Features .......................................................................... 22

2.5.2 Changed Memory Mapping ................................................................... 22

Driver Access to User-mode Memory ................................................... 23Protected Real-time Process Requires MMU ........................................ 23Error Detection and Reporting Requires Reserved Memory ............. 23

2.5.3 Boot Loaders ............................................................................................. 24

2.5.4 RTP Startup Facility ................................................................................. 25

2.5.5 Wind River System Viewer ..................................................................... 25

2.5.6 Power Management ................................................................................. 26

2.5.7 RTPs Replace VxVMI ............................................................................... 26

2.5.8 Message Channels Replace VxFusion ................................................... 27

2.5.9 Networking Changes ............................................................................... 27

2.6 Changes Introduced in VxWorks 6.1 .................................................................. 27

2.6.1 Loader Changes ........................................................................................ 27

2.6.2 Task Stack Overrun and Underrun ........................................................ 29

2.6.3 File Descriptors Inheritance .................................................................... 30

2.6.4 RTP Initial Task Names ........................................................................... 30

2.6.5 Multiple Sessions of the Kernel Shell .................................................... 30

2.6.6 unld( ) and reld( ) Available In Shell Only ........................................... 31

2.6.7 ISR Objects ................................................................................................. 31

2.6.8 Object Ownership Tracking .................................................................... 31

2.6.9 Resource Reclamation .............................................................................. 31

2.6.10 Driver Changes ......................................................................................... 32

Drivers Source Compatible Only ........................................................... 32No BSD-Style Drivers .............................................................................. 33Modified smEnd ....................................................................................... 33

2.6.11 Task Self-destruction ................................................................................ 33

2.6.12 Stricter Error Checking on Semaphores ................................................ 34


vi

2.6.13 Message Channel API .............................................................................. 34

sockOpt Structure Changed .................................................................... 34backlog Parameter Added ...................................................................... 35

2.7 Changes Introduced in VxWorks 6.2 .................................................................. 35

2.7.1 File System Changes ................................................................................ 35

Extended Block Device (XBD) ................................................................ 36File System Monitor ................................................................................. 36Highly Reliable File System .................................................................... 36Discontinued Features ............................................................................. 37Deprecated Features ................................................................................. 37

2.7.2 Expanded POSIX Support ....................................................................... 37

2.7.3 Changes To Memory Partition Options ................................................ 38

2.7.4 Scalability ................................................................................................... 38

2.7.5 VxBus ......................................................................................................... 38

2.8 Determining If a BSP Requires Migration ........................................................ 38

2.9 Architecture-Specific Issues ................................................................................. 40

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

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.4.1 Command-Line Build and Boot ............................................................. 55

Build Environment ................................................................................... 55Customizing VxWorks ............................................................................. 56Building VxWorks .................................................................................... 57Starting VxWorks ...................................................................................... 57

3.4.2 Wind River Workbench Build and Boot ................................................ 59

Build Environment ................................................................................... 59Customizing VxWorks ............................................................................. 60

Contents

vii

Building VxWorks .................................................................................... 61Starting VxWorks ..................................................................................... 61Starting the Target Server ........................................................................ 63

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

4.1 Introduction ............................................................................................................. 65

4.2 Migration Checklist ............................................................................................... 67

4.3 Build Changes ......................................................................................................... 68

4.3.1 Recompiling Source Code ....................................................................... 68

4.3.2 Header File Changes ................................................................................ 68

Type Changes ............................................................................................ 68IPv6 Stack Headers Directory Change .................................................. 69isascii( ), toascii( ) Relocated ................................................................... 69objLib Macro Moved ................................................................................ 69

4.3.3 Compiling for Both VxWorks 6.x and VxWorks 5.5 ............................ 69

4.4 Internal Changes .................................................................................................... 70

4.4.1 Initialization Routines ............................................................................. 70

4.4.2 Loader Changes ........................................................................................ 71

Backward Compatibility ......................................................................... 71Changed Symbol Type Values ................................................................ 71Resolving Common Symbols ................................................................. 73Symbol Tables and Modules Not Objects ............................................. 73

4.5 System Changes ...................................................................................................... 73

4.5.1 Tasks and the TCB .................................................................................... 74

Accessing the TCB .................................................................................... 74Changed Components and Macros ....................................................... 74taskSwitchHookAdd( ) Behavior Modified .......................................... 74taskCreat( ) Deprecated ........................................................................... 75

4.5.2 _func_excBaseHook Daisy Chaining ..................................................... 75


viii

4.5.3 Memory Partition Options ...................................................................... 76

New Options ............................................................................................. 76Deprecated Options ................................................................................. 76Changed Default Options ....................................................................... 77Restoring Prior Options ........................................................................... 77

4.5.4 Caching ...................................................................................................... 78

4.5.5 Scalability Changes .................................................................................. 78

4.5.6 Other System API Changes ..................................................................... 79

Newly Public Libraries and APIs ........................................................... 79Newly Private Structures and Routines ................................................ 79New APIs and Libraries .......................................................................... 79Parameter Change .................................................................................... 79Deprecated Library and APIs ................................................................. 80Deprecated APIs ....................................................................................... 80Removed APIs .......................................................................................... 80

4.6 Networking Changes ............................................................................................. 81

Deprecated Header Files ......................................................................... 81Unneeded Header Files Removed ......................................................... 81No _KERNEL Flag ................................................................................... 81IPv4 FTP Server Replaced ....................................................................... 81etherAddrResolve( ) Removed ............................................................... 82IP Forwarding ........................................................................................... 82

4.7 Driver Changes ....................................................................................................... 82

END-Style Drivers Replace BSD Drivers .............................................. 82Modified smEnd ....................................................................................... 83

4.8 I/O System Changes ............................................................................................... 85

I/O Error Code Value Changes .............................................................. 85I/O Device Control APIs ......................................................................... 86

4.9 File System Changes .............................................................................................. 86

4.9.1 Extended Block Device (XBD) Support ................................................. 87

XBD Replaces CBIO ................................................................................. 87Fallback to rawFs ...................................................................................... 89ATA Driver Changes ................................................................................ 90

Contents

ix

Disk Formatting ........................................................................................ 90Changes to ioctl( ) Commands ............................................................... 90

4.9.2 HRFS .......................................................................................................... 91

4.9.3 dosFS .......................................................................................................... 92

Migrating From dosFs 1.0 to 2.0 ............................................................. 92Changed APIs ........................................................................................... 93

4.9.4 File System-Related APIs and Libraries Removed .............................. 93

4.10 Changes in POSIX Support .................................................................................. 93

4.10.1 Changes in POSIX Facilities in VxWorks 6.0 ........................................ 94

POSIX Message Queues .......................................................................... 94POSIX Thread Support ............................................................................ 94POSIX Semaphores .................................................................................. 95

4.10.2 Changes in POSIX APIs in VxWorks 6.2 ............................................... 95

New POSIX APIs ...................................................................................... 95Changes in Existing POSIX APIs ........................................................... 96Modified Signal APIs ............................................................................... 97Modified I/O system Device Control APIs .......................................... 98New I/O System Device Control APIs ................................................. 98Modified Macros and Parameters .......................................................... 99

4.11 Changes To VxWorks Components .................................................................... 99

4.11.1 VxFusion No Longer Available .............................................................. 99

4.11.2 Migrating From VxVMI To RTPs ........................................................... 99

4.11.3 PPP ............................................................................................................. 102

4.11.4 Wind River System Viewer ..................................................................... 102

APIs Changed ........................................................................................... 103APIs Removed .......................................................................................... 103

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

5.1 Introduction ............................................................................................................. 105

5.2 Issues In Moving Applications to RTPs ............................................................ 106

5.2.1 Compiling Code for Both User and Kernel Mode ............................... 106


x

5.2.2 Reducing Library Size ............................................................................. 107

5.2.3 RTP Scope .................................................................................................. 107

Communicating Between Applications ................................................ 107Communicating Between an Application and the Operating

System ......................................................................................... 108

5.2.4 Initialization and Finalization Code in C++ ......................................... 108

5.2.5 Eliminating Hardware Access ................................................................ 109

5.2.6 No Interrupt Context In RTPs ................................................................ 110

POSIX Signals ........................................................................................... 110No Watchdogs ........................................................................................... 110No Drivers ................................................................................................. 111

5.2.7 I/O Redirection ........................................................................................ 111

5.2.8 Process and Task API Differences .......................................................... 113

Task Naming Changed ............................................................................ 113Changes in Scope Between Kernel and User Modes ........................... 113Task Locking and Unlocking .................................................................. 114Private and Public Objects ...................................................................... 114

5.2.9 Semaphore Differences ............................................................................ 114

5.2.10 POSIX Signal Differences ........................................................................ 115

Signal Generation ..................................................................................... 115Signal Delivery ......................................................................................... 115Scope Of Signal Handlers ....................................................................... 116Default Handling Of Signals .................................................................. 116Default Signal Mask For New Tasks ...................................................... 116Signals Sent To Blocked Tasks ................................................................ 116Signal API Behavior ................................................................................. 117

5.2.11 Networking Issues ................................................................................... 117

5.2.12 Header File Differences ........................................................................... 118

RTPs Compared to VxWorks 5.5 ............................................................ 118New 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 APIs Not Present In User Mode ............................................................. 119

5.3.2 APIs Added For RTPs Only .................................................................... 120

Contents

xi

5.3.3 APIs That Work Differently In RTPs ..................................................... 120

5.3.4 ANSI vs. POSIX API Differences ........................................................... 121

5.3.5 Kernel Calls Require Kernel Facilities ................................................... 121

5.3.6 Other API Issues ....................................................................................... 121

5.4 Enhanced Support for POSIX Applications in VxWorks 6.2 ......................... 121

5.4.1 POSIX Thread Scheduling ...................................................................... 122

5.4.2 POSIX-Related Changes in Libraries and APIs ................................... 124

New POSIX APIs ...................................................................................... 124Changes in Existing POSIX APIs ........................................................... 125

5.4.3 POSIX-Related Header File Changes .................................................... 133

New POSIX Header Files ........................................................................ 133New Version Header File ........................................................................ 133Changes In Existing POSIX Header Files ............................................. 134

5.4.4 POSIX Configuration Components and Parameters ........................... 136

New Components and Parameters ........................................................ 136Changed Configuration Parameters ...................................................... 136Addition of sysctl Identifiers .................................................................. 137

5.5 Changed Memory Partition Options in VxWorks 6.2 ..................................... 137

5.5.1 New Options ............................................................................................. 137

5.5.2 Deprecated Options ................................................................................. 138

5.5.3 Changed Default Options ....................................................................... 138

5.5.4 Restoring Prior Options .......................................................................... 139

5.6 File System-Related Changes in VxWorks 6.2 .................................................. 139

5.7 Component Changes .............................................................................................. 139

5.7.1 RTPs Replace VxVMI ............................................................................... 139

5.7.2 PPP ............................................................................................................. 140

5.7.3 Network Clients and Servers .................................................................. 140

5.7.4 System Viewer .......................................................................................... 140


xii

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

A.1 Introduction ............................................................................................................. 141

A.2 Changes .................................................................................................................... 141

A.2.1 Application Model ................................................................................... 142

A.2.2 Memory Model ......................................................................................... 142

A.2.3 Entry Points ............................................................................................... 143

A.2.4 Memory Management ............................................................................. 143

Similarities ................................................................................................. 144Differences ................................................................................................. 144

A.2.5 Module Management ............................................................................... 146

A.2.6 CDF Components ..................................................................................... 146

A.3 Compiler ................................................................................................................... 147

A.4 User and Kernel APIs ............................................................................................ 147

A.4.1 Kernel API Differences ............................................................................ 148

A.4.2 Task State ................................................................................................... 148

A.4.3 Host and Kernel Shell .............................................................................. 148

Shared Libraries ........................................................................................ 149Shared Data Regions ................................................................................ 150

A.4.4 Other Differences ...................................................................................... 151

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

B.1 Introduction ............................................................................................................. 153

B.1.1 Glossary ..................................................................................................... 154

B.1.2 Overview of VxBus .................................................................................. 156

Participants ................................................................................................ 156Configuration ............................................................................................ 158BSP Requirements .................................................................................... 159Source files ................................................................................................. 159

Contents

xiii

B.2 Device Driver Interface ......................................................................................... 160

B.2.1 Driver Registration and Initialization Mechanism .............................. 160

B.2.2 Register Access Routines ......................................................................... 163

Standard Access Routines ....................................................................... 163BSP-Specific Optimized Register Access Routines .............................. 163

B.2.3 Interrupt Handling ................................................................................... 164

B.2.4 Driver Methods ........................................................................................ 165

B.2.5 Compilation Context ............................................................................... 165

Generic Drivers ......................................................................................... 166BSP-Specific Optimized Access .............................................................. 166

B.2.6 Instance Creation ...................................................................................... 166

Automatic Procedures ............................................................................. 166Driver-Provided Probe ............................................................................ 167

B.3 Bus Type Requirements and Interface ............................................................... 168

B.3.1 PLB Bus Type ............................................................................................ 168

B.3.2 PCI Bus Type ............................................................................................. 169

B.4 BSP Modifications .................................................................................................. 169

B.5 Driver Modifications ............................................................................................. 171

B.5.1 Registration Only ..................................................................................... 171

B.5.2 Full Participation ...................................................................................... 172

B.6 Initialization Sequence ......................................................................................... 173

B.7 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 Internal Optimization .............................................................................. 178

B.8.2 BSP-supplied Optimization .................................................................... 179


xiv

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

Summary of apigen Markup .................................................................. 181

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

1

1Overview

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.


2

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 Overview1.3 Key Concepts

3

11.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 RTP’s 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 program’s data, execution and exception stacks


4

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 Overview1.5 Target Requirements

5

1Graphical 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 User’s Guide. For more information on the command line, see the VxWorks Command-Line Tools User’s 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.


6

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 Programmer’s Guide, and the VxWorks Application Programmer’s 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 Overview1.6 Summary of Contents

7

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


8

9

2Changes 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


10

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 River’s proprietary VxWorks long name support for dosFs.

■ You use POSIX routines that have been modified for greater compliance with the POSIX standard.

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.

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

2 Changes in the VxWorks Environment2.2 Configuring Your System

11

2

2.2 Configuring Your System

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

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.


12

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 Programmer’s Guide and your product getting started.

2 Changes in the VxWorks Environment2.3 Building Your System and Applications

13

2

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 User’s Guide and the VxWorks Command-Line Tools User's Guide.

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.


14

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 User’s 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 User’s Guide.


15

2

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:

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

On the command line use: ADDED_CFLAGS, ADDED_C++FLAGS

In Workbench use: CC_ARCH_SPEC


16

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.


17

2

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.

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.

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

Figure 2-1 VxWorks Development Shell


18

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 Programmer’s 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.

2 Changes in the VxWorks Environment2.4 Writing Applications in C and C++

19

2

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.

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.

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

Kernel-mode application VxWorks Native Libraries

Dinkum C++ and Embedded C++ Libraries


20

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) /* pre kernel */ reboot (BOOT_WARM_AUTOBOOT); /* 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.

2 Changes in the VxWorks Environment2.5 Accommodating New Features Introduced in VxWorks 6.0

21

2

The instructions for using the Dinkum STL with the Wind River Compiler are in the Wind River Compiler User’s 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.


22

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 Programmer’s Guide: Memory Management.


23

2

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 Programmer’s 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_ERRLOGINCLUDE_EDR_PMINCLUDE_EDR_SHOW /* if the shell is included */INCLUDE_EDR_SYSDBG_FLAG /* allows control of how RTPs fail */INCLUDE_EDR_SHELL_COMMAND /* 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;


24

#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 Programmer’s 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.


25

2

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 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 Programmer’s 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.


26

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.

Table 2-2 New System Viewer Events

Library Feature

rtpLib instrumentation of RTP creation and deletion

system call interface

instrumentation of system calls, selectable per RTP, with decoding of parameters

edrLib instrumentation of writes to the error log

isrLib ISR object creation and deletion, also ISR handler invocation

sdLib instrumentation of creation and deletion of shared data regions

USB stack instrumentation of host and peripheral USB stack

IPv6 dual network stack

updated instrumentation of the network stack

2 Changes in the VxWorks Environment2.6 Changes Introduced in VxWorks 6.1

27

2

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 Programmer’s Guide: Multitasking or the VxWorks Kernel Programmer’s Guide: Multitasking.

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 Programmer’s 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.


28

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

:

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

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


29

2

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


30

For general information about kernel task stacks, see the VxWorks Kernel Programmer’s Guide: Multitasking, and for information on process task stacks, see the VxWorks Application Programmer’s 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 RTP’s 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( ).


31

2

To restore VxWorks 5.5 behavior, set the shell component parameter SHELL_COMPATIBLE to TRUE when creating the project.

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 programmer’s 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


32

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

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.

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


33

2

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


34

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 /* socket option structure */ { int so_level; /* option level */ int so_name; /* option name */ void * so_value; /* ptr to option value */ int so_length; /* option length */ };


35

2

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


36

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.


37

2

Discontinued Features

dosFs 1.0 Support

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 River’s 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


38

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 Programmer’s 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.

2 Changes in the VxWorks Environment2.8 Determining If a BSP Requires Migration

39

2

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?

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

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


40

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.

10. Does the BSP try to patch any architecture code through means other than a published hook or call-out function?

11. Does the BSP have customized make targets or rules?

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

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

MIPSPHYS_ADDR is now an unsigned long long type.

ARMBoot 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

2 Changes in the VxWorks Environment2.9 Architecture-Specific Issues

41

2

T2_BOOTROM_COMPATIBILITY. For additional information, see the architecture supplement.

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


42

43

3Porting 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 Developer’s Guide.


44

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.

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.

NOTE: These steps are cumulative. If you follow them in order, each step will work properly when you attempt it.

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

3 Porting a BSP to VxWorks 6.23.3 Porting a BSP to VxWorks 6.2

45

3

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.

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.

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.


46

■ 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 MMU_ATTR_VALID_MSK

VM_STATE_MASK_WRITABLE MMU_ATTR_PROT_MSK

VM_STATE_MASK_CACHEABLE MMU_ATTR_CACHE_MSK

VM_STATE_MASK_MEM_COHERENCY MMU_ATTR_CACHE_MSK

VM_STATE_MASK_GUARDED MMU_ATTR_CACHE_MSK

VM_STATE_VALID MMU_ATTR_VALID

VM_STATE_VALID_NOT MMU_ATTR_VALID_NOT

VM_STATE_WRITABLE MMU_ATTR_SUP_RWX

VM_STATE_WRITABLE_NOT (MMU_ATTR_PROT_SUP_READ | MMU_ATTR_PROT_SUP_EXE)

VM_STATE_CACHEABLE MMU_ATTR_CACHE_DEFAULT


47

3

■ 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:

Failure to make these changes results in an error similar to:

invalid combination of MMU attributes for sysPhysMemDesc[] entry

VM_STATE_CACHEABLE_NOT MMU_ATTR_CACHE_OFF

VM_STATE_MEM_COHERENCY MMU_ATTR_CACHE_COHERENCY

VM_STATE_MEM_COHERENCY_NOT 0 (set this macro to 0 for VxWorks 6.2)

VM_STATE_GUARDED MMU_ATTR_CACHE_GUARDED

VM_STATE_GUARDED_NOT 0 (set this macro to 0 for VxWorks 6.2)

Table 3-1 Old and New Memory Protection Macros (cont’d)

VxWorks 5.5 Macros VxWorks 6.2 Macros

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_MASK_CACHEABLE or MMU_ATTR_CACHE_MSK

VM_STATE_CACHEABLE_NOT | VM_STATE_WBACK_NOT

VM_STATE_CACHEABLE_NOT or MMU_ATTR_CACHE_OFF

VM_STATE_CACHEABLE | VM_STATE_WBACK

VM_STATE_WBACK or MMU_ATTR_CACHE_COPYBACK


48

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.


49

3

Step 8: 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, r7b 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.

Table 3-3 Sample Function Replacements

Architecture-dependent functions

Architecture-independent functions

cacheArchFlush( ) cacheFlush( )

cacheArchInvalidate( ) cacheInvalidate( )

cachePpcEnable( ) cacheEnable( )

cachePpcDisable( ) cacheDisable( )


50

■ 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 River’s 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.


51

3

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 variable’s 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 "2.0"#define BSP_REV "/4" <- increased by 1

In the README, add release notes for the VxWorks 6.2 version.

Example:

RELEASE 2.0/4Released by Wind River for VxWorks 6.2.


52

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


53

3

For examples of these changes, see the appropriate files in the wrSbc8260Atm and wrSbcPowerQuiccII BSPs.

Step 13: BSP Documentation Conversion

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.


54

■ 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

3 Porting a BSP to VxWorks 6.23.4 Booting a VxWorks 5.5 BSP

55

3

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

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.


56

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; /* for backwards compatibility */#endif

/* 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);}


57

3

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


58

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 User’s Guide: Setting Up Your Hardware.

Sample Boot Output

VxWorks System BootCopyright 1984-2004 Wind River Systems, Inc.

CPU: Motorola MVME5110-2163 - MPC 7410Version: VxWorks 6.2BSP version: 2.0/3Creation date: Apr 9 2004, 17:27:24

Press any key to stop auto-boot...7

[VxWorks Boot]: [VxWorks Boot]: @ : feiunit number : 0 processor number : 0 host name : hostfile name : c:\WindRiver\vxworks-6.2\target\proj\CLIproj\default\v xworksinet on ethernet (e) : 192.168.184.183:fffffe00 gateway inet (g) : 192.168.185.254user (u) : demoftp password (pw) : demoflags (f) : 0x0 target name (tn) : mv5100-3


59

3

Attaching interface lo0... doneAttached IPv4 interface to fei unit 0Loading... 1200268 + 244064Starting at 0x100000...

Attaching interface lo0... doneAttached IPv4 interface to fei unit 0Adding 4883 symbols for standalone.

VxWorksCopyright 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:14ED&R Policy Mode: Deployed WDB Comm Type: WDB_COMM_END WDB: Ready.

-> Can start a user application here...

-> iNAME ENTRY TID PRI STATUS PC SP ERRNO DELAY

---------- ---------- -------- --- -------- ------- -------- ------ -----tJobTask jobTask 22f8920 0 PEND 2042f0 22f87f0 0 0tExcTask excTask 22fbeb0 0 PEND 201bf4 22fbd50 0 0 ...tNbioLog 1a8b04 23028a0 0 PEND 2042f0 2302790 0 0tShell0 shellTask 244cc90 1 READY 20ba1c 244c990 0 0tWdbTask wdbTask 2438480 3 PEND 2042f0 2438380 0 0tNetTask 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.


60

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; /* for backwards compatibility */#endif


61

3

/* 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);}

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


62

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 User’s Guide: Setting Up Your Hardware.

Sample Boot Output

VxWorks System BootCopyright 1984-2004 Wind River Systems, Inc.

CPU: Motorola MVME5110-2163 - MPC 7410Version: VxWorks 6.2BSP version: 2.0/3Creation date: Apr 9 2004, 17:27:24

Press any key to stop auto-boot... 7

[VxWorks Boot]: [VxWorks Boot]: @ : feiunit number : 0 processor number : 0 host name : hostfile name : c:\WindRiver\Workspace\WBproj\default\vxworksinet on ethernet (e) : 192.168.184.183:fffffe00 gateway inet (g) : 192.168.185.254user (u) : demoftp password (pw) : demoflags (f) : 0x0 target name (tn) : mv5100-3

Attaching interface lo0... doneAttached IPv4 interface to fei unit 0Loading... 1200268 + 244064Starting at 0x100000...

Attaching interface lo0... doneAttached IPv4 interface to fei unit 0Adding 4883 symbols for standalone.

VxWorksCopyright 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


63

3

ED&R Policy Mode: Deployed WDB Comm Type: WDB_COMM_END WDB: Ready.

-> Can start a user application here...

-> iNAME ENTRY TID PRI STATUS PC SP ERRNO DELAY

---------- ---------- -------- --- -------- ------- -------- ------ -----tJobTask jobTask 22f8920 0 PEND 2042f0 22f87f0 0 0tExcTask excTask 22fbeb0 0 PEND 201bf4 22fbd50 0 0 ...tNbioLog 1a8b04 23028a0 0 PEND 2042f0 2302790 0 0tShell0 shellTask 244cc90 1 READY 20ba1c 244c990 0 0tWdbTask wdbTask 2438480 3 PEND 2042f0 2438380 0 0tNetTask 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.


64

Draft: 18 Nov 05 65

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


66 Draft: 18 Nov 05

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. You can stay with a level of functionality comparable to VxWorks 5.5 and make any small changes required for your application.

2. You can migrate to a kernel-mode application and take advantage of the new functionality available in VxWorks 6.x.

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

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.2 Migration Checklist

Draft: 18 Nov 05 67

4

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.

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 User’s 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.

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


68 Draft: 18 Nov 05

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 User’s Guide.

4.3.2 Header File Changes

Type Changes

The pathLib.h header file now uses const char *.

NOTE: The VxWorks 5.5 kernel library build model is still supported, so backward compatibility is maintained.

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.3 Build Changes

Draft: 18 Nov 05 69

4

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


70 Draft: 18 Nov 05

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.

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.

Table 4-1 Macros For Specifying the VxWorks Version

Macro Name Value

_WRS_VXWORKS_MAJOR 6

_WRS_VXWORKS_MINOR 2a

_WRS_VXWORKS_MAINT 0

_WRS_VXWORKS_5_X N/A

a. Updated in VxWorks 6.2.

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.4 Internal Changes

Draft: 18 Nov 05 71

4

4.4.2 Loader Changes

This section summarizes the differences between the VxWorks 6.x loader and the VxWorks 5.5.

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.

http://www.windriver.com/windsurf/beta/vdt3_0


72 Draft: 18 Nov 05

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 SYM_UNDF 0x0 /* undefined */#define SYM_LOCAL 0x0 /* local */#define SYM_GLOBAL 0x1 /* global (external) (ORed) */#define SYM_ABS 0x2 /* absolute */#define SYM_TEXT 0x4 /* text */#define SYM_DATA 0x6 /* data */#define SYM_BSS 0x8 /* bss */#define SYM_COMM 0x12 /* common symbol */#define SYM_SDA 0x40 /* symbols related to a */

/* PowerPC SDA section */#define SYM_SDA2 0x80 /* symbols related to a */

/* PowerPC SDA2 section */

#define SYM_THUMB 0x40 /* Thumb function */

These are the new (VxWorks 6.x) values:

#define SYM_UNDF 0x0 /* undefined (lowest 8 bits only) */#define SYM_GLOBAL 0x1 /* global (external) */#define SYM_ABS 0x2 /* absolute */#define SYM_TEXT 0x4 /* text */#define SYM_DATA 0x8 /* data */#define SYM_BSS 0x10 /* bss */#define SYM_COMM 0x20 /* common symbol */

#define SYM_LOCAL 0x40 /* local */#define SYM_THUMB 0x80 /* Thumb function */

With the previous set of values, some bits could be meaningfully OR’d together (for instance, the global symbol type could be meaningfully OR’d with any other symbol type). But if some symbol types were OR’d 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)

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.5 System Changes

Draft: 18 Nov 05 73

4

■ #define SYM_IS_ABS(symType) ■ #define SYM_IS_COMMON(symType)

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.

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


74 Draft: 18 Nov 05

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.


Draft: 18 Nov 05 75

4

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


76 Draft: 18 Nov 05

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.


Draft: 18 Nov 05 77

4

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:

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);

Figure 4-1 Changes to Kernel Memory Partition Options

VxWorks 6.2 Prior Versions

MEM_ALLOC_ERROR_LOG_FLAG MEM_ALLOC_ERROR_LOG_FLAG

MEM_ALLOC_ERROR_EDR_WARN_FLAG -

MEM_BLOCK_CHECK MEM_BLOCK_CHECK

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


78 Draft: 18 Nov 05

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:

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.

Table 4-2 Cache Replacement Routines

Obsolete Routines Replacement Routines

cacheArchFlush( ) cacheFlush( )

cacheArchInvalidate( ) cacheInvalidate( )


Draft: 18 Nov 05 79

4

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.


80 Draft: 18 Nov 05

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.

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.6 Networking Changes

Draft: 18 Nov 05 81

4

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.


82 Draft: 18 Nov 05

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 Programmer’s 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 Programmer’s 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 motcpmEnd

if_cs obsolete

if_dc dec21x40End

if_eex obsolete

if_ei obsolete

if_eidve obsolete

if_eihk obsolete

if_elc obsolete

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.7 Driver Changes

Draft: 18 Nov 05 83

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.

if_elt elt3c509End

if_ene ne2000End

if_esmc obsolete

if_fei fei82557End

if_fn obsolete

if_ln obsolete

if_lnPci ln97xEnd

if_loop loopEnd

if_mbc obsolete

if_nicEvb nicEvbEnd

if_sl obsolete

if_sm smEnd

if_sn obsolete

if_ultra obsolete

Table 4-3 END-style Drivers Replacing BSD-Style Drivers (cont’d)

BSD-Style Driver END-Style Driver


84 Draft: 18 Nov 05

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

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.8 I/O System Changes

Draft: 18 Nov 05 85

4

4.8 I/O System Changes

I/O Error Code Value Changes

In order for Wind River’s 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 ENODEV

S_ioLib_NO_DEVICE_NAME_IN_PATH ENODEV

S_iosLib_CONTROLLER_NOT_PRESENT ENXIO

S_ioLib_DISK_NOT_PRESENT ENXIO

S_ioLib_NO_DRIVER ENXIO

S_iosLib_DUPLICATE_DEVICE_NAME EINVAL

S_iosLib_INVALID_ETHERNET_ADDRESS EINVAL

S_ioLib_NO_FILENAME EINVAL

S_ioLib_DEVICE_ERROR EIO

S_ioLib_DEVICE_TIMEOUT EIO

S_ioLib_UNFORMATTED EIO


86 Draft: 18 Nov 05

Table 4-5 provides a list of error codes that do have numerically unique numbers.

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 Programmer’s Guide: I/O System.

Table 4-5 VxWorks I/O Errors With Unique Numeric Error Codes

VxWorks Name POSIX Name

S_iosLib_DRIVER_GLUT ENOMEM

S_iosLib_INVALID_FILE_DESCRIPTOR EBADF

S_iosLib_TOO_MANY_OPEN_FILES EMFILE

S_ioLib_UNKNOWN_REQUEST ENOSYS

S_ioLib_WRITE_PROTECTED EACCES

S_ioLib_CANCELLED ECANCELED

S_ioLib_NAME_TOO_LONG ENAMETOOLONG

S_ioLib_CANT_OVERWRITE_DIR EISDIR

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.9 File System Changes

Draft: 18 Nov 05 87

4

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.

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 Floppy devices

ATA SCSI

RAM disk TrueFFS


88 Draft: 18 Nov 05

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.


Draft: 18 Nov 05 89

4

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.


90 Draft: 18 Nov 05

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.


Draft: 18 Nov 05 91

4

■ 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:


92 Draft: 18 Nov 05

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 River’s 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( )

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.10 Changes in POSIX Support

Draft: 18 Nov 05 93

4

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.


94 Draft: 18 Nov 05

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


Draft: 18 Nov 05 95

4

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.

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 /* sem_t */{OBJ_CORE objCore; /* semaphore object core */SEM_ID semId; /* semaphore identifier */int refCnt; /* number of attachments */char * sem_name; /* name of semaphore */} sem_t;

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( ) aio_fsync( ) chmod( ) fcntl( ) fdatasync( ) fpathconf( ) fsync( ) link( ) pathconf( )


96 Draft: 18 Nov 05

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 Programmer’s 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.


Draft: 18 Nov 05 97

4

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);


98 Draft: 18 Nov 05

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.

4 Migrating VxWorks 5.5 Applications To the 6.2 Kernel4.11 Changes To VxWorks Components

Draft: 18 Nov 05 99

4

For more information on these routines, see the reference entries and the VxWorks Kernel Programmer's Guide: I/O System.

Modified Macros and Parameters

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.


100 Draft: 18 Nov 05

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.

Table 4-7 Memory Management Features in VxVMI and VxWorks 6.x

Feature Supported in VxWorks 6.x

Text write protection Yes

Kernel vector table write protection Yes

API to map physical to virtual memory Yes

API to modify and examine state of virtual memory Yes

API to generate report on state of virtual memory Yes

Creation of virtual memory contexts No


Draft: 18 Nov 05 101

4

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.

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

Table 4-8 VxVMI APIs Mapped to VxWorks 6.x Routines

VxVMI VxWorks 6.x

vmMap( ) vmMap( )

vmTextProtect( ) vmTextProtect( )a

vmStateSet( ) vmStateSet( )

vmStateGet( ) vmStateGet( )

vmTranslate( ) vmTranslate( )

vmPageSizeGet( ) vmPageSizeGet( )

vmContextShow( ) vmContextShow( )

vmShowInit( ) not available

vmContextCreate( ) not available

vmContextDelete( ) not available

vmCurrentGet( ) not available

vmCurrentSet( ) not available

vmGlobalInfoGet( ) not available

vmGlobalMap( ) not available

vmPageBlockSizeGet( ) not available

a. vmTextProtect( ) now takes an argument (BOOL setState)



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.


Draft: 18 Nov 05 103

4

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.

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



105

5Migrating 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 Programmer’s Guide: Applications and Processes.


106

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 */

5 Migrating Applications to RTPs5.2 Issues In Moving Applications to RTPs

107

5

#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.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 RTP’s 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


108

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 Programmer’s 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 Programmer’s 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 User’s 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.


109

5

■ 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 User’s 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


110

single RTP should be accessing the device. For more information, see the VxWorks Application Programmer’s 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.

There are slight differences in the behavior of the two timers, as shown in Table 5-2.

Table 5-1 Corresponding wdLib and timerLib Routines

wdCreate( )Routines

timer_create( ) Routines

wdCreate( ) timer_create( )

wdStart( ) timer_connect( ) + timer_settime( )

wdCancel( ) timer_cancel( )

wdDelete( ) timer_delete( )


111

5

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;

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.

A signal handler executes as a response to the timer expiring.

The handler executes when the timer expires, right in the context of the system clock tick handler.

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.


112

/* Get the standard file descriptor numbers */oldFd0 = ioGlobalStdGet(0);oldFd1 = ioGlobalStdGet(1);oldFd2 = 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 the standard file descriptor numbers */oldFd0 = dup(0);oldFd1 = dup(1);oldFd2 = 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 */


113

5

/* 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 RTP’s 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.


114

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 objects—which must be named—are 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 Programmer’s 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


115

5

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


116

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.


117

5

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.

Signal API Behavior

Table 5-3 shows APIs that behave differently in the kernel than they do in an RTP.

For more information, see the VxWorks Application Programmer’s 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 Programmer’s Guide: Routing Sockets for Route Table Events.

Table 5-3 Differences in Signal API Behavior

API Kernel Behavior RTP Behavior

kill( ) sends a signal to a task sends a signal to an RTP

raise( ) sends a signal to the current task

sends a signal to the current task’s RTP

sigqueue( ) sends a queued signal to a task sends a queued signal to an RTP


118

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.

5 Migrating Applications to RTPs5.3 Changes to User APIs For RTPs in VxWorks 6.0

119

5

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


120

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.

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.

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 Migrating Applications to RTPs5.4 Enhanced Support for POSIX Applications in VxWorks 6.2

121

5

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


122

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.

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 Programmer’s 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.

Table 5-4 Task and Thread Behavior in the Kernel and RTPs

Execution Environment VxWorks Native Schedulera POSIX Schedulerb

Kernel Tasks and pthreads both behave like VxWorks tasks.

Tasks and pthreads both behave like VxWorks tasks.

RTP Only tasks are permitted; pthreads are not supported.

Tasks behave like VxWorks tasks; pthreads behave as normal POSIX threads.

a. INCLUDE_VX_NATIVE_SCHEDULER b. INCLUDE_POSIX_PTHREAD_SCHEDULER


123

5

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.

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 No impact a N/A N/A

SCHED_FIFO N/A Impact b N/A

SCHED_RR N/A N/A Impact b

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.

! CAUTION: There is no guarantee in VxWorks 6.2 that previous 6.x application binaries will be fully functional; rebuilding is recommended.

Table 5-6 Previous 6.x POSIX Binary Executed in a VxWorks 6.2 RTP

Previously Used Scheduling Policy

VxWorks Scheduler POSIX Thread Scheduler

Pure Priority

Round Robin SCHED_FIFO SCHED_RR

VxWorks native

No impact a No impact a No impact b No impact b

SCHED_FIFO No impact c N/A d Impact e N/A

SCHED_RR N/A d No impact f 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.


124

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 Programmer’s 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.


125

5

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.


126

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.


127

5

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

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.


128

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);


129

5

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);


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);



130

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.


131

5

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


132

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.


133

5

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


134

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


135

5

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


136

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 Programmer’s 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 Programmer’s 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.

5 Migrating Applications to RTPs5.5 Changed Memory Partition Options in VxWorks 6.2

137

5

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


138

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:

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.

Table 5-7 Default Memory Partition Options Compared to Prior Versions

VxWorks 6.2 Prior Versions

MEM_ALLOC_ERROR_LOG_FLAG MEM_ALLOC_ERROR_LOG_FLAG

MEM_ALLOC_ERROR_EDR_WARN_FLAG -

MEM_BLOCK_CHECK MEM_BLOCK_CHECK

MEM_BLOCK_ERROR_LOG_FLAG MEM_BLOCK_ERROR_LOG_FLAG

MEM_BLOCK_ERROR_EDR_FATAL_FLAG MEM_BLOCK_ERROR_SUSPEND_FLAG

5 Migrating Applications to RTPs5.6 File System-Related Changes in VxWorks 6.2

139

5

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


140

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.

141

AMigrating Applications FromVxWorks 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.


142

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.

A Migrating Applications From VxWorks AE to VxWorks 6.xA.2 Changes

143

A

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 Programmer’s 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.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.


144

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 application’s 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.

A Migrating Applications From VxWorks AE to VxWorks 6.xA.2 Changes

145

A

■ 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 Programmer’s 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.


146

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

A Migrating Applications From VxWorks AE to VxWorks 6.xA.3 Compiler

147

A

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.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 Programmer’s Guide: POSIX Standard Interfaces.


148

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

A Migrating Applications From VxWorks AE to VxWorks 6.xA.4 User and Kernel APIs

149

A

VxWorks 6.x: Uses the command interpreter to switch.

-> cmd[vxWorks *]# %1 <-- where 1 is the process attachment

number for the application[usrApp *]# C->

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

For more information on the new shells, see the Wind River Workbench Command-Line User’s 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


150

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 Programmer’s 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( ) sdCreate( ) API changed. In 6.x, this creates and maps the shared data region to the calling RTP or kernel.

sdMap( ) sdMap( ) API changed.

sdUnMap( ) sdUnMap( ) API changed.

sdDelete( ) sdDelete( ) API changed.

sdOpen( ) sdOpen( )

sdAttach( ) Not available in 6.0

sdDetach( ) Not available in 6.0

sdShow( ) sdShow( )

A Migrating Applications From VxWorks AE to VxWorks 6.xA.4 User and Kernel APIs

151

A

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.


152

153

BMigrating 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


154

■ 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 developer’s 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.

B Migrating to the New VxBusB.1 Introduction

155

B

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.


156

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.


157

B

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.


158

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.


159

B

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


160

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.

B Migrating to the New VxBusB.2 Device Driver Interface

161

B

Here are some sample device recognition structures, along with function prototypes and other required structures:

LOCAL BOOL templateDriverProbe(VXB_DEVICE_ID pDev);LOCAL void templateDriverInstInit(VXB_DEVICE_ID pDev);LOCAL void templateDriverInstInit2(VXB_DEVICE_ID pDev);LOCAL void 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.

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*

! CAUTION: It is possible for the driver to link the structures together and make a single call to vxbDevRegister( ), but this is not recommended.

! CAUTION: Follow the convention of explicitly listing the boards and devices which have been tested.


162

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


163

B

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.

For more information, see the VxWorks Device Driver Developer’s Guide.

{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)


164

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:

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

vxbIntConnect( ) vxbIntDisconnect( ) vxbIntEnable( ) vxbIntDisable( ) vxbIntAcknowledge( )


165

B

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.


166

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.


167

B

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


168

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.

B Migrating to the New VxBusB.4 BSP Modifications

169

B

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.


170

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

B Migrating to the New VxBusB.5 Driver Modifications

171

B

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.


172

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.

B Migrating to the New VxBusB.6 Initialization Sequence

173

B

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.


174

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.

B Migrating to the New VxBusB.6 Initialization Sequence

175

B

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.

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


176

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.

B Migrating to the New VxBusB.7 Hardware Configuration File

177

B

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.

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-1 Standard Parameters

Resource Name Type

regBase type RES_INT

interrupts type RES_INT (see B.7.2 Interrupt Information, p.177)

Table B-2 Interrupt Vector Naming Scheme

Number Options

0 intr0, intr, irq, txInt

1 intr1, rxInt

2 intr2, errInt

3 intr3

4 intr4

... ...

64 intr64


178

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 optimizationmimics the hardware, with at least one function call for every bus between the processor and the device. It is inevitably very slow.

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

B Migrating to the New VxBusB.8 Optimization Issues

179

B

The after-transformation values are:

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

byte-order 0x34.12.78.56.bc.9a.f0.deword-order 0x56.78.12.34.de.f0.9a.bclong-order 0x9a.bc.de.f0.12.34.56.78


180

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.

181

CConversion 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

Columnapigen Markup

MangenEquivalent Description

any 'text ...' or 'text ...' same boldface words

any <text> same italicized words (text variables, emphasis)

any \\ or \/ \e the character \

any \< \> \‘ \’ N/A the characters < > ‘ ’

any \| N/A the character | within a table

1 \ss...\se

.tS

...

.tE

preformatted text (syntax)

1 \cs...\ce

.CS

...

.CE

literal text (code)


182

1 \bs...\be

.bS

...

.bE

literal text, smaller (board layout)

1 \is\i item\ie

.iP or .IP itemized list (terms list)

1 \ml\m mark\me

.iP or .IP marker list (numbered or dashed)

1 \ts...\te

.TS

...

.TE

table

1 \sh text .SS text subheading

1 \tb reference .I, .pG, .tG cross-reference to a publication

Table C-1 apigen Markup (cont’d)

Columnapigen Markup

MangenEquivalent Description

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.

183

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

Aaccess( ), changed 95, 124accessing objects, changed from VxWorks AE 148activeQhead, removed 20aio_fsync( )

added, application 124changed, kernel 95

alarm( ) changed 129apigen

BSP conversion 54markup summary 181

APIs addedapplication

aio_fsync( ) 124chmod( ) 124

fcntl( ) 124fdatasync( ) 124fpathconf( ) 124fsync( ) 124link( ) 124pathconf( ) 124pthread_atfork( ) 124pthread_setschedprio( ) 124sysconf( ) 124uname( ) 124

kernelcacheFlush( ) 78cacheInvalidate( ) 78cdromFsDevCreate( ) 88cdromFsVersionDisplay( ) 88cdromFsVersionNumGet( ) 88hrfsFormat( ) 91iosDevCallback( ) 98iosDevReplace( ) 98iosDevResume( ) 98iosDevSuspend( ) 98msgQInitialize( ) 78partLib.c 88semBInitialize( ) 78semCInitialize( ) 78semMInitialize( ) 78wdInitialize( ) 78xbdBlkDevLibCreate( ) 88xbdBlkDevLibDelete( ) 88xbdBlkDevLibInit( ) 88

VxWorks Migration Guide, 6.2

184

xbdCreatePartition( ) 88xbdRamDiskDevCreate( ) 88xbdRamDiskDevDelete( ) 89

APIs changedapplication

_exit( ) 132alarm( ) 129calloc( ) 131clock( ) 131getOptServ( ) 132ioctl( ) 130isatty( ) 130kill( ) 128malloc( ) 131memPartAlloc( ) 132mkdir( ) 131mq_open( ) 127mq_receive( ) 127mq_send( ) 128mq_unlink( ) 128open( ) 130pause( ) 129pthread_attr_cond_wait( ) 126pthread_attr_getdetachstate( ) 125pthread_attr_getname( ) 125pthread_attr_getopt( ) 125pthread_attr_getschedpolicy( ) 125pthread_attr_getstackaddr( ) 125pthread_attr_getstacksize( ) 125, 126pthread_attr_init( ) 125pthread_attr_setdetachstate( ) 126pthread_attr_setname( ) 126pthread_attr_setopt( ) 126pthread_attr_setschedpolicy( ) 126pthread_attr_setscope( ) 125pthread_attr_setstackaddr( ) 126pthread_cond_timedwaitt( ) 126pthread_create( ) 126pthread_getschedparam( ) 126pthread_setschedparam( ) 127queue( ) 128read( ) 130rename( ) 131sched_getpriority_max( ) 132sched_getpriority_min( ) 132

sched_rr_get_interval( ) 132sem_init( ) 127sem_open( ) 127sem_unlink( ) 127signal( ) 128sigtimedwait( ) 128sigwaitinfo( ) 129sleep( ) 129unlink( ) 131vmBaseLib 140write( ) 131

kernelaccess( ) 95, 124aio_fsync( ) 95chmod( ) 95dosFsDevCreate( ) 93dosFsVolFormat( ) 93fcntl( ) 95fdatasync( ) 95fpathconf( ) 95ioctl( ) 90iosDevDelete( ) 98iosDevRemove( ) 98pthread_attr_getdetachstate( ) 97pthread_attr_getname( ) 97pthread_attr_getopt( ) 97pthread_attr_getschedpolicy( ) 96pthread_attr_getstackaddr( ) 97pthread_attr_getstacksize( ) 97pthread_attr_init( ) 96pthread_attr_setdetachstate( ) 97pthread_attr_setname( ) 97pthread_attr_setopt( ) 96pthread_attr_setschedpolicy( ) 96pthread_attr_setscope( ) 96pthread_attr_setstackaddr( ) 97pthread_create( ) 94, 96pthread_getschedparam( ) 96pthread_setschedparam( ) 96sigtimedwait( ) 97sigwaitinfo( ) 98timer_getoverrun( ) 99usrFsLib.c 91

Index

185

Index

APIs deprecatedapplication

diskFormat( ) 139diskInit( ) 139

kernelsemOLib 80taskCreat( ) 75

APIs movedkernel

isascii( ) 69toascii( ) 69

APIs not present in RTPstaskSwitchHookAdd( ) 119taskSwitchHookDelete( ) 119

APIs removedkernel

cacheArchFlush( ) 78cacheArchInvalidate( ) 78ftpdLib 81rt11fsLib 93scsiSeqLib.c 93semBCoreInit( ) 80semCCoreInit( ) 80semMCoreInit( ) 80semQCoreInit( ) 80tapeFsLib.c 93usrFdiskPartCreate( ) 89

APIs with changed scope in RTPsasctime_r( ) 121ctime_r( ) 121gmtime_r( ) 121localtime_r( ) 121strerror( ) 121

APIs, system viewerchanged

wvUploadStart( ) 103removed

wvEvtLogInit( ) 103wvLogHeaderCreate( ) 103wvLogHeaderUpload( ) 103wvTaskNamesPreserve( ) 103wvTaskNamesUpload( ) 103

application model, changed from VxWorks AE 142architecture models, participants, VxBus 158architecture-specific migration issues 40

asctime_r( ), scope changes in RTP 121attributes

constructor 109destructor 109

Bbacklog, parameter 35backward compatibility

5.5 bootloaders 24kernel mode 66vmBaseLib not 79

boot loaders, 5.5 compatible 24BSD-style drivers not supported 33BSPs

apigen 53building, compiler warnings 50compatibility checklist 39compatibility with VxWorks 6.1 10default features enabled 11drivers replaced 82modifications, VxBus 169participant, VxBus 156porting 43porting, ETHERNET_ADR_SET 52porting, ETHERNET_MAC_HANDLER 52requirements, VxBus 159source compatible only 10

build flags, setting 15build infrastructure, changes 13build specification, glossary definition 4build utility, wrconfig 68building

kernel from Workbench 61user applications 18VxWorks from command line 57

bundled PPP 102bus discovery, glossary definition 154bus type, participant, VxBus 157bus, glossary definition 154


186

CC++ components removed, obsolete 12cache attributes

MMU_ATTR_CACHE_MSK 100MMU_ATTR_CACHE_OFF 100MMU_ATTR_CACHE_WRITETHRU 100MMU_ATTR_SUP_RWX 100MMU_ATTR_USR_RWX 100MMU_ATTR_xxx 46

cache library APIs, updating 48cache state definitions, Pentium BSPs, new 47cacheArchFlush( ), removed 78cacheArchInvalidate( ), removed 78cacheFlush( ), added 78cacheInvalidate( ), added 78cacheLib, private headers 78calloc( ) changed 131cdromFsDevCreate( ), added 88cdromFsVersionDisplay( ), added 88cdromFsVersionNumGet( ), added 88changed

directory structure 13loader 71memory mapping 22

changesVxWorks 6.0 to VxWorks 6.1 27VxWorks components 99

changing version number, config.h 51child, glossary definition 154chmod( )


clock( ) changed 131command line

building VxWorks 57customizing VxWorks with vxprj 56sample boot output 58validating a ported BSP 55VxWorks 5.x boot loaders 57

compilation context, VxBus drivers 165compiler

extra command-line flags 15new warning and error levels 16options, GNU 16

specifying path 14stricter syntax 21VxWorks AE, changed from 147warnings, building BSPs 50

compilinguser and kernel modes 106VxWorks 6.1 vs 5.5 environments 69

component model, changed from VxWorks AE 146components

glossary definition 4INCLUDE_BSD 83INCLUDE_CONSTANT_RDY_Q 12INCLUDE_EDR_SYSDBG_FLAG 24INCLUDE_EDR_XXX 11INCLUDE_EXC_TASK 33INCLUDE_ISR_OBJECT 11INCLUDE_JOB_TASK 34INCLUDE_MEM_EDR 33INCLUDE_MMU_BASIC 100INCLUDE_POSIX_CLOCKS 11INCLUDE_POSIX_PTHREAD_

SCHEDULER 136INCLUDE_PROTECT_STACK 29INCLUDE_RTP 11INCLUDE_RTP_APPL_INIT_BOOTLINE 25INCLUDE_RTP_APPL_INIT_CMD_SHELL_

SCRIPT 25INCLUDE_RTP_APPL_INIT_STRING 25INCLUDE_RTP_APPL_USER 25INCLUDE_SHARED_DATA 11INCLUDE_SHARED_LIBRARIES 11INCLUDE_SM_NET 83INCLUDE_SMEND 83INCLUDE_VXEVENTS 11INCLUDE_VXWORKS_5_X_EQUIV_PPP 12POSIX_PTHREAD_RR_TIMESLICE 136

config.h replaced 12configuration, VxBus 158constructor attribute 109ctime_r( ), scope changes in RTP 121custom BSPs, migrating makefiles 18customizing VxWorks

with vxprj from command line 56with Workbench 60

Index

187

Index

Ddefault compiler change 14definitions

build specification 4component 4deprecated 5downloadable kernel module project 4error detection and reporting 4graphical user interface 5project 4real-time process project 4RTP 3shared-library project 4toolchain 4VxWorks image project 4workspace 4

DELAYTIMER_MAX macro 99deprecated, glossary definition 5design issues, RTPs

communicating between RTPs 107communicating with kernel 108

destructor attribute 109device drivers, VxBus participants 157device, glossary definition 154Dinkum Standard Template Library 20discontinued

dosFs 1.0 37dosFs long file name support 37tapeFs 37

diskFormat( ), deprecated 139diskInit( ), deprecated 139dosFs 1.0 discontinued 37dosFs long file name support discontinued 37dosFsDevCreate( ), changed 93dosFsVolFormat( ), changed 93downloadable kernel module project, glossary

definition 4downstream, glossary definition 154driver method

glossary definition 155VxBus 165

driver modificationsVxBus full participation 172VxBus registration only 171

driver, glossary definition 154drivers

registration, VxBus 160source-compatible only 32

dup( ), I/O redirection 111dup2( ), I/O redirection 111

EED&R, see error detection and reportingerrno changes, loader 27error detection and reporting

adding to BSP 49glossary definition 4reserved memory required 23

error-checking, semaphores 34escJobAdd( ),newly public 79etherAddrResolve( ) removed 82Ethernet MAC address, boot loaders 52ETHERNET_ADR_SET, include macro 52ETHERNET_MAC_HANDLER, include macro 52example, VxWorks 5.5 BSP to VxWorks 6. 1 43excJobAdd( ), replaces excTask( ) 79excTask( ), newly private 79exit( ), scope changes in RTP 113exported entry points (VxWorks AE) 143extended block device, summary 36

Ffcntl( )


fdatasync( )added, application 124changed, kernel 95

file descriptor inheritance, changed in RTP 30file system

changes, summary 35removability support 36

finalization code 108FIODISKCHANGE, removed 90


188

FIOFORMAT, removed 90flags

_KERNEL, removed 81build, setting 15GNU

-fno-exception 21-fno-rtti 21

GNU compiler 16fpathconf( )


fsync( ), added 124ftpdLib removed 81

GgetOptServ( ) changed 132gmtime_r( ), scope changes in RTP 121graphical user interface, glossary definition 5GUI, see graphical user interface

HhardWareInterFaceInit( ) 169hashLib, private headers 79hcfDeviceList[ ]

VxBus BSP modifications 169VxBus hardware configuration file 176

hcfResource[ ], VxBus parameters 176header files

addedsys/select.h 133sys/time.h 133sys/utsname.h 133sys/wait.h 133version.h 133

changedlimits.h 134math.h 134pthread.h 134sched.h 135signal.h 135

stdio.h 135strings.h 135time.h 135unistd.h 135

changes to 13kernel mode 13user mode 13

host and target shells (VxWorks AE) 148hrfsFormat( ), added 91

II/O errnos

duplicate 85unique 86

I/O redirectionVxWorks 5.5 111VxWorks 6.x 112

I/O system, POSIX compliance 85INCLUDE_CONSTANT_RDY_Q replaced 12INCLUDE_EDR_XXX, disabled by default 11INCLUDE_ISR_OBJECT, no longer included by

default 11INCLUDE_PLB_BUS, macro added, VxBus 158INCLUDE_POSIX_CLOCKS, automatic with POSIX

timers 11INCLUDE_RTP, default changed 11INCLUDE_SHARED_DATA, disabled by default

11INCLUDE_SHARED_LIBRARIES, disabled by

default 11INCLUDE_VX_NATIVE_SCHEDULER,

configuring 12INCLUDE_VXBUS, macro added, VxBus 158INCLUDE_VXEVENTS, no longer included by

default 11initialization code 108installed location, online documentation 2instance creation

VxBus automatic 166VxBus driver-provided probe 167

instance, glossary definition 155intended audience, this guide 2

Index

189

Index

interrupt service routine 31interrupts, VxBus

handling 164information 177

intLock( ), no user mode 119intUnlock( ), no user mode 119ioctl( )

changed, application 130commands changed, kernel 90

iosDevCallback( ), added 98iosDevDelete( ), changed 98iosDevRemove( ), changed 98iosDevReplace( ), added 98iosDevResume( ), added 98iosDevSuspend( ), added 98IP forwarding default 82IPv4/IPv6 dual network stack 69isascii( ) moved 69isatty( ), changed, application 130ISR, see interrupt service routine

Kkernel applications

building from command line 57building from Workbench 61

kernel shell, multiple sessions 30KERNEL_HEAP_SIZE, parameter 145kill( )

changed, application 128scope changes in RTP 113

Llibraries, Dinkum C and C++ 19link( ), added 124loader

changed 71errno changes 27routines removed in VxWorks 6.1 28

loader macros, use symbolic names 72loadModule( ), reloading from a program 31

loadModuleAt( ), reloading from a program 31localtime_r( ), scope changes in RTP 121

MMACH_EXTRA

linking configlettes 45linking custom architecture code 45

main( ) routine, entry point 142makefiles, migrating custom BSPs 18malLib, module access layer support 146malloc( ) changed 131MEM_GROW_ENABLE parameter 146MEM_RECLAIM_ENABLE parameter 146memAttrLib, VxWorks AE library 145memory management, changed, from VxWorks

AE 143memory model, changed, from VxWorks AE 142memory partition options

applications 137kernel 76

memory protection macros 46memPartAlloc( ) changed 132method ID, glossary definition 155migration

architecture-specific issues 40BSPs

sysEnetAddrGet( ) 52sysMemTop( ) 50sysNetMacNVRamAddrGet( ) 52sysPhysMemTop( ) 50

checklist, kernel applications 67custom BSP makefiles 18dosFs1 to dosFs2 92options 66options, kernel mode 66versions older than VxWorks 5.5, from 6

mkdir( ) changed 131MMU, protected RTP requires 23MMU_ATTR_CACHE_MSK, cache attribute 100MMU_ATTR_CACHE_OFF, cache attribute 100MMU_ATTR_CACHE_WRITETHRU, cache

attribute 100MMU_ATTR_IO, VxWorks AE cache attribute 146


190

MMU_ATTR_SUP_RWX, cache attribute 100MMU_ATTR_USR_RWX, cache attribute 100MMU_ATTR_xxx, cache attribute 46module management, changed (VxWorks AE) 146mprotect( ), replaces vmStateSet( ) and

vmBaseStateSet( ) in user mode 140mq_des changed (POSIX message queues) 94mq_open( ) changed 127mq_receive( ) changed 127mq_send( ) changed 128mq_unlink( ) changed 128msgQInitialize( ), added, kernel 78

Nnetwork header files

changed 69deprecated 81removed 81

networking changes, summary 27new

configuration process 12features, including 22parameter

exception overflow 29kernel stack overflow 29kernel stack underflow 29user stack overflow 29user stack underflow 29

OOBJ_VERIFY( ) relocated 69object ownership, tracking 31objLib

now public 79private headers 69

open( ) changed 130OPT_LOWERCASE option with dosFs 92optimization, -O3 not supported 17

optimization, VxBusBSP-supplied 179internal 178

orphan device, glossary definition 155overview, VxBus model 156

Pparameter type change

physical address, virtual memory routines 102virtual address, virtual memory routines 101

parametersadded, KERN_VERSION 137backlog 35changed

RTP_SIGNAL_QUEUE_SIZE 136RTSIG_MAX 136SIGQUEUE_MAX 136vmBaseLibInit( ) 79

KERNEL_HEAP_SIZE 145MEM_GROW_ENABLE 146MEM_RECLAIM_ENABLE 146

parent, glossary definition 155partLib.c, added 88pathconf( ), added 124pathLib.h, type changes 68pause( ) changed 129PCI bus type, VxBus requirements 169Pentium BSPs, new cache state definitions 47per-device data, glossary definition 155pgMgrLib, VxWorks AE 145pgPoolLib, VxWorks AE 145pgPoolLstLib, VxWorks AE 145PHYS_ADDR

parameter 47type changed 102

PLB bus type, VxBus requirements 168PM_RESERVED_MEM

example 23required for error detection and reporting 50

porting a BSPintroduction 43to VxWorks 6.1, steps 44

Index

191

Index

POSIXfile system, application

mkdir( ) 131I/O, application

fsync( ) 124open( ) 130read( ) 130rename( ) 131unlink( ) 131write( ) 131

I/O, kernelaccess( ) 95chmod( ) 95fcntl( ) 95fdatasync( ) 95fpathconf( ) 95fsync( ) 95iosDevCallback( ) 98iosDevDelete( ) 98iosDevRemove( ) 98iosDevReplace( ) 98iosDevResume( ) 98iosDevSuspend( ) 98

ISO C, application_exit( ) 132calloc( ) 131malloc( ) 131

libc, applicationclock( ) 131

message queues, applicationmq_open( ) 127mq_receive( ) 127mq_send( ) 128mq_unlink( ) 128

scheduling, applicationsched_getpriority_max( ) 132sched_getpriority_minn( ) 132sched_rr_get_interval( ) 132

semaphores, applicationsem_init( ) 127sem_open( ) 127sem_unlink( ) 127

signals, applicationkill( ) 128queue( ) 128

signal( ) 128sigtimedwait( ) 128sigwaitinfo( ) 129

signals, kernelsigtimedwait( ) 97sigwaitinfo( ) 98

thread scheduler, behavior 122threads, application

pthread_atfork( ) 124pthread_attr_cond_wait( ) 126pthread_attr_getdetachstate( ) 125pthread_attr_getname( ) 125pthread_attr_getopt( ) 125pthread_attr_getschedpolicy( ) 125pthread_attr_getstackaddr( ) 125pthread_attr_getstacksize( ) 125pthread_attr_init( ) 125pthread_attr_setdetachstate( ) 126pthread_attr_setname( ) 126pthread_attr_setopt( ) 126pthread_attr_setschedpolicy( ) 126pthread_attr_setscope( ) 125pthread_attr_setstackaddr( ) 126pthread_attr_setstacksize( ) 126pthread_cond_timedwait( ) 126pthread_create( ) 126pthread_getschedparam( ) 126pthread_setschedparam( ) 127pthread_setschedprio( ) 124

threads, kernelpthread_attr_getdetachstate( ) 97pthread_attr_getname( ) 97pthread_attr_getopt( ) 97pthread_attr_getschedpolicy( ) 96pthread_attr_getstackaddr( ) 97pthread_attr_getstacksize( ) 97pthread_attr_init( ) 96pthread_attr_setdetachstate( ) 97pthread_attr_setname( ) 97pthread_attr_setopt( ) 96pthread_attr_setschedpolicy( ) 96pthread_attr_setscope( ) 96pthread_attr_setstackaddr( ) 97pthread_attr_setstacksize( ) 97pthread_create( ) 94, 96


192

pthread_getschedparam( ) 96pthread_setschedparam( ) 96

timers, applicationpause( ) 129sleep( ) 129

POSIX message queues, mq_des changed 94POSIX semaphores, sem_t moved 95POSIX signals in RTPs 115POSIX support, summary 37POSIX timers, difference from watchdogs 111power management, summary 26PPP

new implementation 12not available in RTP 140

private headerscacheLib 78hashLib 79objLib 69

probe routine, glossary definition 155probe, glossary definition 155project, glossary definition 4protected RTP requires MMU 23pthread_atfork( ), added, application 124pthread_attr_cond_wait( ) changed,

application 126pthread_attr_getdetachstate( )

changed, application 125changed, kernel 97

pthread_attr_getname( )changed, application 125changed, kernel 97

pthread_attr_getopt( )changed, application 125changed, kernel 97

pthread_attr_getschedpolicy( )changed, application 125changed, kernel 96

pthread_attr_getstackaddr( )changed, application 125changed, kernel 97

pthread_attr_getstacksize( )changed, application 125changed, kernel 97

pthread_attr_init( )changed, application 125changed, kernel 96

pthread_attr_setdetachstate( )changed, application 126changed, kernel 97

pthread_attr_setname( )changed, application 126changed, kernel 97

pthread_attr_setopt( )changed, application 126changed, kernel 96

pthread_attr_setschedpolicy( )changed, application 126changed, kernel 96

pthread_attr_setscope( )changed, application 125changed, kernel 96

pthread_attr_setstackaddr( )changed, application 126changed, kernel 97

pthread_attr_setstacksize( )changed, application 126changed, kernel 97

pthread_cond_timedwait( )changed, application 126

pthread_create( )changed, application 126changed, kernel 94, 96

pthread_getschedparam( )changed, application 126changed, kernel 96

pthread_setschedparam( )changed, application 127changed, kernel 96

pthread_setschedprio( ), added 124

Rraise( ), scope changes in RTP 113RAM disk, BLK_DEV-based, deprecated 37read( ) changed 130real-time process project, glossary definition 4real-time process, see RTP

Index

193

Index

region.sdf, no longer maps memory 145register access routines, VxBus

BSP-specific 163standard 163

reld( )callable from shell only 31moved to usrLib.c 31

reloading from a programloadModulAt( ) 31loadModule( ) 31

rename( ) changed 131resource reclamation

kernel 31kernel task create hooks 32RTP post-create hooks 32user task calls kernel routine 32

routeAdd( ), not supported, user mode 117routines not present in user mode

intLock( ) 119intUnlock( ) 119routeAdd( ) 117

rt11fsLib, removed 93RTP initial task name, changed 30rtpRaise( ), alternative to raise( ) in RTP 114RTPs

default signal handling 116glossary definition 3header files 118I/O redirection 111introduction 105networking issues 117no drivers 111no hardware access 109no interrupt context 110no watchdogs 110process vs task APIs 113routines differing from kernel 120scope of signal handlers 116semaphores in 114signals

behavior 117delivery 115generation 115mask 116sent to blocked tasks 116

startup facility 25task locking/unlocking 114user-mode-only APIs 120

rtpSigqueue( ), alternative to sigqueue( ) in RTP 114

rtpSpawn( ), in RTP 145

SsalCreate( ), sockopt structure changed 34salSockopt

replaces sockopt 34sample boot output

command line 58Workbench 62

scalability 38sched_getpriority_max( ) changed 132sched_getpriority_min( ) changed 132sched_rr_get_interval( ) changed 132scope changes in RTPs

exit( ) 113kill( ) 113raise( ) 113sigqueue( ) 114

scope of signal handlers, RTPs 116scsiSeqLib.c, removed 93sdAttach( ), shared data 150sdCreate( ), shared data 150sdDelete( ), shared data 150sdDetach( ), shared data 150sdMap( ), shared data 150sdOpen( ), shared data 150sdShow( ), shared data 150sdUnMap( ), shared data 150sections

.ctors 108

.dtors 108sem_init( ) changed 127sem_open( ) changed 127sem_t moved (POSIX semaphores) 95sem_unlink( ) changed 127semaphore changes in RTPs

semGive( ) 114semInfoGet( ) 115


194

semOpen( ) 115semTake( ) 114

semaphoresin RTPs 114stricter error-checking 34

semBCoreInit( ) removed 80semBInitialize( ), added, kernel 78semCCoreInit( ) removed 80semCInitialize( ), added, kernel 78semGive( ), semaphore 114semInfoGet( ), semaphore 115semMCoreInit( ) removed 80semMInitialize( ), added, kernel 78semOLib deprecated 80semOpen( ), semaphore 115semQCoreInit( ) removed 80semTake( ), semaphore 114SGI standard template library, no longer

supported 15SH C++ libraries 15shared data

regions, changed from VxWorks AE 150sdAttach( ) 150sdCreate( ) 150sdDelete( ) 150sdDetach( ) 150sdMap( ) 150sdOpen( ) 150sdShow( ) 150sdUnMap( ) 150

shared libraries, changed from VxWorks AE 149shared memory END driver, BSP support 83shared-library project, glossary definition 4SHELL_COMPATIBLE, parameter 31shellPromptFmtDftSet( ), shell prompt default 30shellPromptSet( ), shell prompt 30signal behavior, RTPs 117signal( ) changed 128sigqueue( )

changed, application 128scope changes in RTP 114

sigtimedwait( )changed, application 128changed, kernel 97

sigwaitinfo( )changed, applications 129changed, kernel 98

sleep( ) changed 129smEnd, upgraded shared memory driver 33, 83sockopt changed 34source files, VxBus 159source-compatible only, drivers 32specifying, compiler path 14standard template library 20

Dinkumware 20SGI 15

STL, see standard template librarystrerror( ), scope changes in RTP 121stricter syntax, compilers 21string.h, VxWorks compatibility mode 121symbol references, changed from VxWorks AE 151symbol types, changed 71symbolic names, loader, eliminate numeric

values 72sysconf( ), added 124sysEnetAddrGet( ), migrating BSP 52sysHwInit2( ) 169sysMemTop( )

changed from VxWorks AE 145migrating BSPs 50

sysNetHwInit( ), VxBus initialization, network 175sysNetMacNVRamAddrGet( ), migrating BSP 52sysPhysMemTop( ), migrating BSP 50sysSerialChanGet( ), VxBus initialization,

serial 175sysSmEndLoad( ), created during shared memory

migration 84System Viewer events, new 25

TtapeFs discontinued 37tapeFsLib.c, removed 93target requirements 5target server, starting from Workbench 63target.nr 53target.ref 53

Index

195

Index

task options not available in RTPsVX_SUPERVISOR 120VX_UNBREAKABLE 120

task self-destruction, changed behavior 33task state, BREAK vs STOP in VxWorks AE 148TASK_KERNEL_EXEC_STACK_OVERFLOW_

SIZE, new parameter 29TASK_KERNEL_EXEC_STACK_UNDERFLOW_

SIZE, new parameter 29TASK_STACK_OVERFLOW_SIZE, removed in

VxWorks 6.1 29TASK_STACK_UNDERFLOW_SIZE, removed in

VxWorks 6.1 29TASK_USER_EXC_STACK_OVERFLOW_SIZE,

new parameter 29TASK_USER_EXEC_STACK_OVERFLOW_SIZE,

new parameter 29TASK_USER_EXEC_STACK_UNDERFLOW_SIZE,

new parameter 29taskCreat( ) deprecated 75taskCreate( ), replaces taskInit( ) in user mode 119taskDelete( ), task self-destruction 33taskExit( ), replaces taskExit( ) in user mode 113taskInit( ), not present in user mode, use

taskCreate( ) 119taskKill( ), replaces taskKill( ) in user mode 113taskName( ), replacing direct access to TCB 74taskRaise( ), replaces raise( ) in user mode 113taskRtpLock( )

eliminating hardware access from RTP 109locking in an RTP 114replaces taskLock( ) in user mode 119

taskRtpUnlock( )eliminating hardware access from RTP 109replaces taskLock( ) in user mode 119unlocking in an RTP 114

taskSigqueue( ), replaces taskSigqueue( ) in user mode 114

taskSpawn( ), may replace when customizing VxWorks 60

taskStackAllot( ), newly public 79taskSwitchHookAdd( )

replaced in RTPs 119scheduling change 74

taskSwitchHookDelete( ), replaced 119

timer.h, VxWorks compatibility mode 121timer_cancel( ), replaces wdCancel( ) in RTPs 110timer_connect( ), use in applications 110timer_create( ), replaces wdCreate( ) in user

mode 110timer_delete( ), replaces wdDelete( ) in RTPs 110timer_getoverrun( ), changed 99timer_settime( ), use in applications 110toascii( ) moved 69toolchain, glossary definition 4torVars replaced 17type changes, loader 71

Uuname( ), added 124unld( )

callable from shell only 31moved to usrLib.c 31

unldByModuleId( ), unloading from a program 31unldByNameAndPath( ), unloading from a

program 31unlimited passing of object IDs in VxWorks AE 151unlink( ) changed 131unloading from a program

unldByModuleId( ) 31unldByNameAndPath( ) 31

unsupported optimization, -O3 17upstream, glossary definition 155user applications, building 18user mode

differences from previous releases 3memory, driver access to 23

USER_APPL_INIT, RTP startup 25USER_RESERVED_MEM, persistent memory in

BSPs 50usrFdiskPartCreate( ), removed 89usrFsLib.c, changed 91


196

Vvalidating a ported BSP


versions older than VxWorks 5.5, migrating from 6VIRT_ADDR

BSP macro 47parameter type change 101

VM_PAGE_SIZE, BSP macro 45VM_STATE_xxx, BSP macro 46vmBaseLib

not backward compatible 79RTPs 140

vmBaseLibInit( ), changed 79vmBaseStateSet( ), replaced in RTPs 140vmContextCreate( ), removed 101vmContextDelete( ), removed 101vmContextShow( ), still present in kernel 101vmCurrentGet( ), obsolete 101vmCurrentSet( ), obsolete 101vmGlobalInfoGet( ), obsolete 101vmGlobalMap( ), obsolete 101vmMap( ), still present in kernel 101vmPageBlockSizeGet( ), obsolete 101vmPageSizeGet( ), still present in kernel 101vmShowInit( ), obsolete 101vmStateGet( ), still present in kernel 101vmStateSet( )

replaced by mprotect( ) user mode 140still present in kernel 101

vmTextProtect( ), still present in kernel 101vmTranslate( ), still present in kernel 101VX_BINARY_SEMAPHORE, added 78VX_COUNTING_SEMAPHORE, added 78VX_MSG_Q, added 78VX_MUTEX_SEMAPHORE, added 78VX_SUPERVISOR not available in RTPs 120VX_TASK, added 78VX_TASK_INITIALIZE, added 78VX_TASK_INSTANTIATE, added 78VX_UNBREAKABLE not available in RTPs 120VX_WD, added 78

vxbDevConnect( )VxBus BSP modifications 169VxBus initialization 174

vxbDevInit( )VxBus BSP modifications 169VxBus initialization 173

vxbDevInit2( ), VxBus initialization 174vxbDevRegister( )

driver registration 160initialization 173

vxbIntAcknowledge( ) 164vxbIntConnect( ) 164vxbIntDisable( ) 164vxbIntDisconnect( ) 164vxbIntEnable( ) 164VxBus

BSP modifications 169BSP requirements 159compilation context, drivers 165configuration 158driver methods 165driver modifications

full participation 172registration only 171

driver registration 160hardWareInterFaceInit( ) 169hcfDeviceList[ ], hardware configuration

file 176hcfResource[ ], parameters 176interrupt handling 164interrupt information 177optimization issues 178overview, model 156register access routines 163requirements

PCI bus type 169PLB bus type 168

source files 159sysHwInit2( ) 169sysNetHwInit( )

initialization, network 175sysSerialChanGet( )

initialization, serial 175

Index

197

Index

vxbDevConnect( )BSP modifications 169initialization 174

vxbDevInit( )BSP modifications 169initialization 173

vxbDevInit2( ), initialization 174vxbDevRegister( )

driver registration 160initialization 173

vxbIntAcknowledge( ) 164vxbIntConnect( ) 164vxbIntDisable( ) 164vxbIntDisconnect( ) 164vxbIntEnable( ) 164vxBusShow( ) 158

VxBus participantsarchitecture models 158BSP 156bus type 157device drivers 157VxBus 157

VxBus, instance creationautomatic 166driver-provided probe 167

VxBus, optimizationBSP-supplied 179internal 178

vxBusShow( ) 158VxFusion, replaced by message channels 27vxMemProbeArch( ), use in simulator 75VxVMI

removed 99replaced by RTPs 26, 139routines, obsolete

vmCurrentGet( ) 101vmCurrentSet( ) 101vmGlobalInfoGet( ) 101vmGlobalMap( ) 101vmPageBlockSizeGet( ) 101vmShowInit( ) 101

routines, removedvmContextCreate( ) 101vmContextDelete( ) 101

routines, still present in kernelvmContextShow( ) 101vmMap( ) 101vmPageSizeGet( ) 101vmStateGet( ) 101vmStateSet( ) 101vmTextProtect( ) 101vmTranslate( ) 101

VxWorksbuilding from command line 57building from Workbench 61

VxWorks 5.5 BSP to VxWorks 6.1, example 43VxWorks 5.5, I/O redirection 111VxWorks 5.x boot loaders


VxWorks 6.x BSPs, features required 44VxWorks 6.x, I/O redirection 112VxWorks AE, changed from

accessing objects 148application model 142compiler 147component model 146exported entry points 143host and target shells 148memory management 143memory model 142module management 146shared data regions 150shared libraries 149symbol references 151sysMemTop( ) 145task state, BREAK vs STOP 148unlimited passing of object IDs 151

VxWorks image project, glossary definition 4VxWorks, 5.x compatibility 2

Wwatchdogs, difference from POSIX timers 111wdCancel( ), unavailable in user mode 110wdCreate( ), unavailable in user mode 110wdDelete( ), unavailable in user mode 110wdInitialize( ), added, kernel 78


198

wdStart( ), unavailable in user mode 110Wind River Compiler (formerly Diab), now

default 14Wind River GNU compiler 14Workbench

building the kernel 61customizing VxWorks 60sample boot output 62target server, starting 63validating a ported BSP 59VxWorks 5.x boot loaders 61

workspace, glossary definition 4wrconfig build utility 68wrenv

command shell 55environment setup 17

write( ) changed 131wvEvent( ), available in RTPs 140wvEvtLogInit( ), system viewer, removed 103wvLib, system viewer 102wvLogHeaderCreate( ), removed 103wvLogHeaderUpload( ), removed 103wvTaskNamesPreserve( ), removed 103wvTaskNamesUpload( ), removed 103wvUploadStart( ), changed 103

XxbdBlkDevLibCreate( ), added 88xbdBlkDevLibDelete( ), added 88xbdBlkDevLibInit( ), added 88xbdCreatePartition( ), added 88xbdRamDiskDevCreate( ), added 88xbdRamDiskDevDelete( ), added 89

Date post:	23-Aug-2018
Category:	Documents
Upload:	vohanh
View:	354 times
Download:	28 times

VxWorks Migration Guide, 6 - pudn.comread.pudn.com/.../vxworks_migration_guide_6.2.pdf · 1.6.3...

Documents