VxWorks[R]__________________________________________ Release Notes Read these release notes first. They describe VxWorks for Alpha Version 3.2A installation considerations, enhancements, corrections, and restrictions. Revision/Update Information: These release notes supersede the VxWorks Version 3.2 Release Notes AA-QA99C-TE Operating System and Version: Digital UNIX, Version 3.0 or higher Software Version: VxWorks for Alpha, Version 3.2A Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First Printing, March 1992 Revised, December 1992, July 1996 Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © Digital Equipment Corporation 1996. All Rights Reserved. Printed in U.S.A. The postpaid Reader's Comments form at the end of this document requests your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: Bookreader, DEC, DECchip, Digital UNIX, DECwindows, RT-11, ThinWire, VAX, VMS, and the DIGITAL logo. The following are third-party trademarks: BSD is a trademark of the University of California, Berkeley. Intel is a trademark of Intel Corporation. Motorola and 68000 are registered trademarks of Motorola, Inc. MS-DOS is a registered trademark of Microsoft Corporation. NFS and Sun are registered trademarks of Sun Microsystems, Inc. Motif, OSF, OSF/1, and OSF/Motif are registered trademarks of the Open Software Foundation, Inc. POSIX is a registered trademark of IEEE. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. VxWorks is a registered trademark and VxGDB is a trademark of Wind River Systems, Inc. X Window System, Version 11 and its derivations (X, X11, X Version) are trademarks of the Massachusetts Institute of Technology. All other trademarks and registered trademarks are the property of their respective holders. S3306 _________________________________________________________________ Contents Preface................................................... vii 1 Installing the VxWorks Software 1.1 Installing the VxWorks Software.................. 1-1 1.2 License Registration............................. 1-1 2 Enhancements 2.1 In This Chapter.................................. 2-1 2.2 Merge with Wind River Systems Code Base Continues........................................ 2-1 2.3 AXPvme 230, 166, 100 Support..................... 2-1 2.4 AXPpci 33 BSP Support for SCSI Boot.............. 2-2 2.5 New Firmware for AXPvme Systems.................. 2-2 2.6 EB64 16 Mbyte Memory Restriction................. 2-2 2.7 Twisted-Pair Support for AXPpci, EB64+, and EB66 Systems.......................................... 2-4 2.8 POSIX 1003.1b Support............................ 2-4 2.9 Example Device Drivers........................... 2-4 2.10 PCI Bus Support for AXPvme and AXPpci Modules.... 2-5 2.11 Host and Target Name Length...................... 2-5 3 Corrections 3.1 In This Chapter.................................. 3-1 3.2 VB Driver Timeout................................ 3-1 3.3 SCSI Asynchronous Clock Conversion Factor........ 3-1 3.4 Stack Size Error................................. 3-1 3.5 bootrom_alpha Error.............................. 3-1 3.6 SCSI Clock Frequency for AXPvme Systems.......... 3-2 3.7 Floating Point Context Saved Correctly........... 3-2 3.8 VMEbus IACK Processing........................... 3-2 iii 3.9 Function Prototypes Added for adp* Routines...... 3-2 4 Restrictions 4.1 In This Chapter.................................. 4-1 4.2 Netload and IP Subnets........................... 4-1 4.3 ls Command at Shell Prompt....................... 4-1 4.4 Register Corruption from VxGDB................... 4-2 4.5 ISA Bus Floppy Disk Directories.................. 4-2 4.6 D64 VMEbus Transactions on AXPvme Target Systems.......................................... 4-2 4.7 GNU C Compiler (cc68k) Unresolved Reference...... 4-2 4.8 nm68k Utility Failure (68K Targets).............. 4-2 4.9 IVP and System Build Warning Messages for 68K Systems.......................................... 4-3 4.10 Boot Menu Output Lost When Terminal is Set to Smooth Scroll on 68K Targets..................... 4-3 5 Documentation Notes 5.1 In This Chapter.................................. 5-1 5.2 Digital UNIX 3.0 or Later Required............... 5-1 5.3 Data Typing in the Shell......................... 5-1 5.4 sysDate()........................................ 5-1 5.5 clock() Routine Not Implemented.................. 5-2 5.6 PATH Setting for VxGDB........................... 5-2 5.7 Minimum Kernel Documentation..................... 5-2 5.8 configAll.h and Base Level (BL) tests............ 5-2 5.9 Renamed INCLUDE Definitions in configAll.h....... 5-3 5.10 Moved INCLUDE Definitions in configAll.h......... 5-3 5.11 Moving the INCLUDE_ANSI_ALL Symbol............... 5-4 5.12 Clock Rate for AXPvme Real-Time Clocks........... 5-4 5.13 Making Compressed Images for AXPvme boot ROMs.... 5-4 5.14 Change to Clock Connect Routine Arguments........ 5-5 5.15 Interpreting References to the VxWorks Directory Tree............................................. 5-5 5.16 LOCAL_MEM_LOCAL_ADRS on EBxx Platforms........... 5-6 5.17 O3 Optimization Available........................ 5-6 5.18 Limit on the Number of Global Symbols............ 5-7 5.19 getpid() Routine Not Supported................... 5-9 5.20 System-wide List of Error Codes.................. 5-9 5.21 Notes on Manpages................................ 5-9 5.21.1 New Manpages Available ........................ 5-9 iv 5.22 Notes on VxGDB................................... 5-10 5.22.1 Diagnosing VxGDB Windows Interface Errors ..... 5-10 5.22.2 VxGDB's "net connect: RPC: Program Not Registered" Message............................ 5-10 5.22.3 VxGDB run Command Accepts Up to 9 Arguments ... 5-10 5.22.4 VxGDB Default Directory for Redirected Task I/O............................................ 5-11 5.22.5 Setting Options for Tasks Spawned Under VxGDB.......................................... 5-11 5.23 Notes on Software for the Digital Alpha AXPvme Module........................................... 5-11 5.23.1 adpCreateMapPath Modifications ................ 5-11 5.24 Notes on X Windows Use........................... 5-11 5.24.1 Exiting an X Window Application ............... 5-12 5.24.2 X Window Applications May Need More Stack ..... 5-12 5.24.3 Motif Example Provided ........................ 5-12 5.24.4 Use MrmOpenHierarchyPerDisplay() Instead of MrmOpenHierarchy() ............................ 5-12 5.25 Configuring the VAXELN API....................... 5-13 5.26 EB6x PAL Code and SYSGEN Utility Support......... 5-13 5.27 Tracing a Task in the Prolog on an Alpha Target System........................................... 5-13 5.28 Username Length Restricted for rsh Boot.......... 5-14 5.29 netDrv Devices Cannot Use rm(), rename(), remove() ........................................ 5-14 A Changes Since the Release of VxWorks V3.2 A.1 Changes Since VxWorks for Alpha V3.2............. A-1 A.1.1 VxWorks Linking Loader Modified for Digital UNIX V4.0...................................... A-1 A.1.2 V3.2A Can Be Installed on Digital UNIX V4.0 ... A-1 A.1.3 V3.2A Network Loaders Incompatible with V3.2 .. A-1 A.1.4 netTask Software .............................. A-2 A.1.5 bcopy Routine Optimization .................... A-2 A.1.6 Digital UNIX C Compiler ....................... A-2 A.1.7 68K tools on Digital UNIX V4.0 ................ A-3 A.1.8 POSIX Documentation Out of Date ............... A-4 A.1.9 fcntl() Not POSIX Compliant ................... A-4 v B POSIX Interface in VxWorks V3.2A B.1 POSIX.1 Functions................................ B-1 B.2 POSIX.1b Functions............................... B-4 B.3 VxWorks POSIX Thread Control Functions........... B-6 C Support for Optional PCI Bus Devices adpFindDevice().................................. C-1 D AXPpci 33 BSP Support for SCSI Disk Boot alphaDiskBootFile().............................. D-1 Tables 5-1 Maximum Userflash Image Sizes for AXPvme Modules........................................ 5-4 vi _________________________________________________________________ Preface VxWorks[[R]] for Alpha is a Digital UNIX layered software product for developing dedicated, realtime applications that run on the following set of Digital Alpha and Motorola 68K target systems: o Digital AXPvme 64, 100, 160, 166, and 230 single-board computers o Digital AXPpci 33 single-board computer o DECchip 21064 Evaluation Board (EB64)[1] o DECchip 21064 PCI Evaluation Board (EB64+)[1] o DECchip 21066/21068 Evaluation Board (EB66)[1] o Motorola MVME147-S, MVME147-SA, and MVME167 single-board computers Document Objectives These release notes describe installation considerations, enhancements, restrictions, and documentation notes for Version 3.2A of VxWorks for Alpha. Intended Audience These release notes are for application programmers and systems engineers who use the VxWorks for Alpha software. ____________________ [1] Supplied in the VxWorks Board Porting Kit for Alpha vii Document Structure This document is organized as follows: o Chapter 1, Installing the VxWorks Software, contains notes about installing Version 3.2A of the VxWorks software. o Chapter 2, Enhancements, describes features new with Version 3.2A of the VxWorks software. o Chapter 3, Corrections, describes recent corrections to the VxWorks Version 3.2A software. o Chapter 4, Restrictions, identifies restrictions for the VxWorks Version 3.2A software. o Chapter 5, Documentation Notes, contains additions and corrections to the VxWorks documentation. o Appendix A, Changes Since the Release of VxWorks V3.2, describes additions and changes made to VxWorks V3.2 to produce V3.2A. o Appendix B, POSIX Interface in VxWorks V3.2A, lists the POSIX functions available in VxWorks. o Appendix C, Support for Optional PCI Bus Devices, provides information on support for optional PCI bus devices. o Appendix D, AXPpci 33 BSP Support for SCSI Disk Boot, provides information for booting an AXPpci 33 system from an attached SCSI disk drive. Conventions The following conventions are used in this document: ___________________________________________________________ Convention_____Meaning_____________________________________ % The default user prompt is the user's system name followed by a right angle bracket. In this document, a percent sign (%) represents this prompt. viii ___________________________________________________________ Convention_____Meaning_____________________________________ # A number sign is the default superuser prompt. -> This is the VxWorks shell prompt for interactive input. UPPERCASE The system differentiates between lowercase lowercase and uppercase characters. Literal strings that appear in text, examples, syntax descriptions, and function definitions must be typed exactly as shown. cat(1) Cross-references to Digital UNIX online reference pages include the appropriate section number in parentheses. For example, a reference to cat(1) indicates that you can find the material on the Digital UNIX command cat in Section 1 of the Digital UNIX online reference pages. Ctrl/x Ctrl/x indicates a control key sequence. Press the key labeled Ctrl while you simultaneously press another key. For example: Ctrl/C. yourCloneTree This is shorthand for the location to which you have copied or cloned the installed directory structure. For example, if you have cloned the VxWorks directory tree to /usr/users/fred/work, a documentation reference to yourCloneTree/config/mv167/system.st would refer to /usr/users/fred/work/config/mv167/system.st. VXWnnn In this notation nnn refers to a VxWorks version number. For example, VXW320 refers to VxWorks Version 3.2. VXW32A refers to _______________VxWorks_Version_3.2A._______________________ ix Associated Documents You will need to refer to other manuals as you prepare your VxWorks programs. The choice of manuals to consult depends on your familiarity with the VxWorks for Alpha software and the nature of your VxWorks application. VxWorks for Alpha o VxWorks Installation Guide o Introduction to VxWorks o VxWorks Programmer's Guide o VxWorks Reference Manual o VxWorks Alpha Hardware Supplement o VxWorks Motorola MVME147S-1 and MVME147SA-1 Hardware Supplement o VxWorks Motorola MVME167 Hardware Supplement o VxWorks Guide to GNU Software for 68K Systems o VxWorks Guide to VxGDB o VxWorks Guide to DECwindows Other Useful References o The C Programming Language, by Brian W. Kernighan and Dennis M. Ritchie, Prentice-Hall, 1988 (2nd ed.). Online Documentation The VxWorks software distribution includes the nroff sources for reference material, including the VxWorks Reference Manual and its hardware supplements. Formatted entries can be accessed online from the Digital UNIX host using the man command. For more information, see the Digital UNIX manpages vxworks(4) and man(1). See also the VxWorks Programmer's Guide. In addition, all VxWorks manuals are available on CDROM for online access with Bookreader. x 1 _________________________________________________________________ Installing the VxWorks Software 1.1 Installing the VxWorks Software For installation information, please read the VxWorks Installation Guide. The on-line Release Notes in /usr/opt /VXW320/READMEFIRST supersede the printed Release Notes you received with this letter. Please read them after the product is installed. If you are currently running VxWorks for Alpha V3.2, this release is a mandatory update. Please install the software normally as described in the VxWorks Installation Guide. Pay special attention to the information in the Installation Guide that describes how to remove an existing version of VxWorks from your system before installing a new version. After installation, please read Appendix A in these Release Notes for information on changes in V3.2A. 1.2 License Registration VxWorks for Alpha software includes support for the License Management Facility (LMF). License Product Authorization Keys (License PAKs) must be registered in the License Database before VxWorks can be installed. For details about the PAKs required for your installation and the procedure for registering licenses, see the VxWorks Installation Guide. Installing the VxWorks Software 1-1 2 _________________________________________________________________ Enhancements 2.1 In This Chapter This chapter identifies enhancements provided in the VxWorks Version 3.2 software. ________________________ Note ________________________ The following enhancements have been added since the release of VxWorks V3.1A. ______________________________________________________ 2.2 Merge with Wind River Systems Code Base Continues This release of VxWorks for Alpha implements another step in the source code merge with VxWorks from Wind River Systems. Many of the source modules in the VxWorks operating system have been updated to reflect Digital's continued efforts in this area. User applications should not be affected. 2.3 AXPvme 230, 166, 100 Support VxWorks Version 3.2 adds support for the following VMEbus single-board computers: o AXPvme 230 o AXPvme 166 o AXPvme 100 The yourCloneTree/config/AXPvme directory of the VxWorks Board Support Package for Alpha has been modified to support these systems in addition to the AXPvme 160 and AXPvme 64. Enhancements 2-1 2.4 AXPpci 33 BSP Support for SCSI Boot VxWorks V3.2 software supports booting directly from an attached SCSI disk drive. The AXPpci 33 BSP provides the alphaDiskBootFile() routine to update the bootblock on the SCSI disk drive for use by the Alpha SRM Console. See Appendix D for information on this routine. 2.5 New Firmware for AXPvme Systems The new additions to the AXPvme family (AXPvme 100, 166 and 230) are shipped with V14.0 of the console firmware. This firmware version will also work correctly on the existing members of the AXPvme family (AXPvme 64 and 160). Any AXPvme system that is running V14.0 of the console firmware must also be running V3.2 of the VxWorks software. VxWorks V3.2 will continue to support the existing members of the AXPvme family (64 and 160) that are running previous versions of the console firmware. However, older versions of VxWorks software (V3.1 and V3.1A) will not support any of the AXPvme systems that are running V14.0 of the console firmware. In addition, V14.0 of the console firmware does not support handling an interrupt from the HALT switch and does not allow the system to continue operating after the HALT switch has been pressed. With firmware V14.0, pressing the HALT switch will always halt the processor and transfer control to the console. If your application requires the ability to handle the interrupt from the HALT switch, you should continue to use previous versions of the console firmware on AXPvme 64 and 160 systems. The AXPvme 100, 166, and 230 must be running V14.0 of the console firmware and therefore do not support handling an interrupt from the HALT switch. 2.6 EB64 16 Mbyte Memory Restriction The 16 Mbyte maximum memory restriction for EB64 systems has been removed. The Lance buffers (128 Kbytes in size) have been located in between the PAL code and the VxWorks image in memory. If you require the network in your image, you must build in 128 Kbytes of free space between the PAL code and the system image. If you use the default values provided, no modification is required. 2-2 Enhancements If you are building a system image, as opposed to a boot ROM image, then you have to add 128 Kbytes (20000 hexadecimal) to the current value of RAM_LOW_ADRS in both yourCloneTree/config/eb64/MakeSkel and yourCloneTree/config /eb64/config.h. For example, the current value of RAM_LOW_ADRS in MakeSkel and config.h is FFFFFC0000400000. #define RAM_LOW_ADRS 0xFFFFFC0000400000 /* RAM address application image */ The new value in both config.h and MakeSkel would be FFFFFC0000420000. #define RAM_LOW_ADRS 0xFFFFFC0000420000 /* RAM address application image */ The documentation example currently shows the sysgen command as follows: $EB_TOOLBOX/sysgen -e300000 -v $pal_64 -e400000 -c systemT.st -o systemT.img The new command would add the 128 Kbytes to the second address parameter: $EB_TOOLBOX/sysgen -e300000 -v $pal_64 -e420000 -c systemT.st -o systemT.img If you are building a boot ROM image, you have to add 128 Kbytes (20000 hexadecimal) to the current value of RAM_ HIGH_ADRS in both MakeSkel and config.h. For example, the current value of RAM_HIGH_ADRS in MakeSkel and config.h is FFFFFC0000A00000. #define RAM_HIGH_ADRS 0xFFFFFC0000A00000 /* RAM address bootrom image */ The new value in both config.h and MakeSkel would be FFFFFC0000420000. #define RAM_HIGH_ADRS 0xFFFFFC0000A20000 /* RAM address bootrom image */ The documentation example currently shows the sysgen command as follows: $EB_TOOLBOX/sysgen -e900000 -v $pal_64 -eA00000 -c bootrom_ebxx -o bootrom_ebxx.img The new command would add the 128 Kbytes to the second address parameter: $EB_TOOLBOX/sysgen -e900000 -v $pal_64 -eA20000 -c bootrom_ebxx -o bootrom_ebxx.img Enhancements 2-3 2.7 Twisted-Pair Support for AXPpci, EB64+, and EB66 Systems Previous VxWorks releases supported only AUI (Thickwire and Thinwire) Ethernet connections to AXPpci, EB64+ and EB66 systems. This release adds twisted pair support. The Ethernet device driver will automatically detect the type of connection. In each case, the driver initializes the device appropriately. 2.8 POSIX 1003.1b Support VxWorks Version 3.2 has been updated to conform to the POSIX 1003.1b standard (formerly known as POSIX 1003.4) for the following sections: o Synchronous input and output o Semaphores o Clocks and timers o Shared memory o Interprocess communication Please see the updated POSIX documents supplied with this kit for more information. 2.9 Example Device Drivers Two example drivers have been added to the yourCloneTree /src/demo directory. The yourCloneTree/src/demo/fdc directory contains a driver for the PC87311/PC87312 diskette controller manufactured by National Semiconductor Corporation. This driver is intended to be an example of an ISA device driver. It runs on EB64+, EB66, and AXPpci 33 systems. The yourCloneTree/src/demo/XYCOM directory contains a driver for the XYCOM 203 clock module. This driver is also intended as an example driver and runs on both AXPvme and 68K systems. 2-4 Enhancements 2.10 PCI Bus Support for AXPvme and AXPpci Modules Additional capabilities have been added to the adapter I/O library and to the AXPvme and AXPpci BSPs to support optional PCI devices. A new routine, adpFindDevice() has been added to the adapter I/O library. This routine can be used at startup to find information about user specified devices, such as the vector and CSR addresses, that are needed to initialize a user written device driver. In addition, the PCI bus support portion of the BSP has been enhanced to scan all configured PCI buses, and create adapter/node data structures that describe the configuration of the target system PCI buses. These structures are then used by the adpFindDevice() routine to locate PCI devices for user-written and system-supplied PCI device drivers. However, the DECchip 21050 PCI-to-PCI bridge is not supported. See Appendix C for information explaining the adpFindDevice() routine. 2.11 Host and Target Name Length In previous VxWorks releases, host and target name lengths were restricted to 19 characters. This release supports host and target names that are 63 characters long or less. Enhancements 2-5 3 _________________________________________________________________ Corrections 3.1 In This Chapter This chapter identifies recent corrections for the VxWorks Version 3.2 software. 3.2 VB Driver Timeout In previous VxWorks releases a timeout error would could occur when one AXPvme system (the slave) made a request of another AXPvme system (the master) to downline load software from the local disk on the master using the VB driver. This error has been corrected. 3.3 SCSI Asynchronous Clock Conversion Factor In previous VxWorks releases an incorrect SCSI asynchronous clock conversion factor could be applied. This error has been corrected. The new clock conversion factor for AXPvme 64 and 160 systems is 21.33 MHz, not 32 MHz. 3.4 Stack Size Error In VxWorks V3.2 software the stack size of the RPC port map daemon has been increased to 7000 bytes from 5000 bytes. The new stack size allows software that uses the RPC services (including the remote debugger), to execute without risk of running out of stack space. 3.5 bootrom_alpha Error In previous VxWorks releases compile-time errors occurred when a bootrom_alpha build included the SM driver. This error has been corrected. Corrections 3-1 3.6 SCSI Clock Frequency for AXPvme Systems In previous releases, the clock conversion factor used for setting the SCSI clock frequency on AXPvme systems was incorrect. This error has been corrected. AXPvme SCSI operations will complete more rapidly. 3.7 Floating Point Context Saved Correctly In previous releases of VxWorks software, the floating point context of a task could be saved incorrectly in some cases. On AXPvme and AXPpci systems this condition resulted in a reference to a virtual address of 8 and an access violation. On 68K targets this condition corrupted low memory locations. This error has been corrected. 3.8 VMEbus IACK Processing In previous releases, if two VME interrupts were acknowledged at the same time, and the VME IACK functionality was enabled for both, there was a risk that one of the IACKs (the one with the higher VME IRQ) would not be propagated to the user. This error has been corrected. 3.9 Function Prototypes Added for adp* Routines In previous releases, function prototypes for the adp* routines were accidentally omitted. Applications that call these routines and are compiled with the -std1 switch may need to be modified to conform to the new prototypes. 3-2 Corrections 4 _________________________________________________________________ Restrictions 4.1 In This Chapter This chapter identifies restrictions for VxWorks Version 3.2 software. 4.2 Netload and IP Subnets The secondary network loaders, netload.AXPvme and netload.AXPpci33, do not support use of the IP Gateway parameter in the VxWorks bootline. To load a target system using the netload utility, ensure that toth the host and target systems are in the same IP subnet. 4.3 ls Command at Shell Prompt The ls command issued at the target's shell prompt may fail for both Alpha and 68K targets. When you boot from flash ROM and leave the password field blank, the rsh protocol supports the ls shell command. The ls command will fail if you use rsh. If you supply a password in the boot menu, the ftp protocol is used. The ls command succeeds when ftp is used. To avoid the error, choose either of the following options: o Specify a password in the boot menu, invoking the ftp protocol and avoiding the error. o Or, if you prefer not to supply a password, substitute the lsOld command for the l command at the shell prompt. Restrictions 4-1 4.4 Register Corruption from VxGDB Setting registers with the VxGDB debugger corrupts other registers. When a user issues a set or print command from VxGDB to modify registers of a task under control of the debugger, the registers get set properly. However, garbage appears in other registers, noticeably the PS (processor status) register. In some cases the task will crash when VxWorks attempts to dispatch and use the PS register. 4.5 ISA Bus Floppy Disk Directories The ISA floppy disk driver does not support subdirectories. All files must be written to the root directory. A problem with subdirectory files causes a block of null values to overwrite the first block of a file. This does not occur when the file is written to the root directory. 4.6 D64 VMEbus Transactions on AXPvme Target Systems Please read the documentation shipped with your AXPvme system for restrictions on D64 VMEbus transactions. 4.7 GNU C Compiler (cc68k) Unresolved Reference When the gcc compiler encounters a main() routine in your code, it creates a reference to a function called __main(). This reference remains unresolved when the compiled code is linked with VxWorks software. Workaround: You can either rename main() or put a dummy routine in your code to satisfy the reference. For example: void __main (void) { } 4.8 nm68k Utility Failure (68K Targets) The + options for the nm68k utility do not work correctly. Workaround: Use the alternatives. For example: nm68k +numeric-sort prog.o ! Fails. nm68k -n prog.o ! Works. 4-2 Restrictions 4.9 IVP and System Build Warning Messages for 68K Systems The VxWorks Installation Verification Procedure (IVP) issues some warnings that you can safely ignore on 68K target systems. For example, when the IVP rebuilds a target system image on a 68K target, the compiler: o Warns about missing function prototypes o Warns about functions that do not return data types that they are defined as returning These same warnings are issued whenever a customer rebuilds system files (system, system.st, and so on). For example, you will get these warnings when you rebuild the system file for use with the VxGDB debugger. 4.10 Boot Menu Output Lost When Terminal is Set to Smooth Scroll on 68K Targets Output from the boot menu can be lost when the terminal is set to smooth scroll. To avoid losing the output, set the terminal to jump scroll. Restrictions 4-3 5 _________________________________________________________________ Documentation Notes 5.1 In This Chapter This chapter lists changes, omissions, and errors in the documentation provided for VxWorks Version 3.2. 5.2 Digital UNIX 3.0 or Later Required Digital UNIX Version 3.0 or later is required to run the VxWorks for Alpha Version 3.2A software. 5.3 Data Typing in the Shell The VxWorks Programmer's Guide contains an error Section 9.3.1. The heading on page 9-7 should say, "Representation of Data Types Other Than long for Alpha Systems." Section 10.4.2 of the VxWorks Programmer's Guide should refer to Section 9.3.1 for information on data typing in the shell. 5.4 sysDate() In previous releases, the documentation for the sysDate() routine showed that the routine accepts no arguments. This is incorrect. To obtain the current date, call sysDate() with a null (0) parameter. For example: sysDate(0); Calling the routine without an argument can cause unpredictable behavior. Documentation Notes 5-1 5.5 clock() Routine Not Implemented The clock() routine described in the VxWorks Reference Manual Volume A is not implemented. This routine always returns the value -1. The ANSI routine clock() is provided in VxWorks only for the sake of conforming completely to the ANSI C specification. The processor time information that clock() would otherwise provide is available using other features of VxWorks that are not compatible with clock(). As the ANSI specification allows, this routine always returns the error, indicating that the processor time used is not available in this manner. 5.6 PATH Setting for VxGDB Step #4 on page 5-10 of the Introduction to VxWorks incorrectly lists the PATH setting for VxGDB. The correct command is: % setenv PATH /usr/opt/VXWnnn/bin/osf:$PATH As noted elsewhere, the VXWnnn represents the current kit. For example, V3.2 is VXW320, V5.2 is VXW520, and so on. 5.7 Minimum Kernel Documentation The documentation for building a minimally configured kernel in the VxWorks Programmer's Guide is slightly out of date. The recent merge between VxWorks for Alpha from Digital and VxWorks from Wind River Systems has affected some of this information. The documentation will be corrected in a future release of VxWorks for Alpha. 5.8 configAll.h and Base Level (BL) tests Starting with the VxWorks Version 3.2, the yourCloneTree /config/all/configAll.h file differs from that of previous Digital VxWorks releases. Digital is returning this configuration file to its original Wind River Systems format. As such, the default settings in this file are no longer sufficient for running the Base Level (BL) tests in the yourCloneTree/config/all/test directory. 5-2 Documentation Notes To run the BL tests, you must edit yourCloneTree/config/all /configAll.h and move the following definitions into the "true" section: #define INCLUDE_POSIX_IPC /* POSIX.4 IPC */ #define INCLUDE_POSIX_SEMAPHORES/* POSIX.4/D11 Binary Semaphores */ #define INCLUDE_POSIX_THREADS /* POSIX.4a/D4 Threads */ #define INCLUDE_POSIX_SHARED_MEMORY_OBJECTS /* POSIX.4/D13 * Memory Management */ #define INCLUDE_POSIX_TIMERS /* POSIX timers */ #define INCLUDE_RPC /* rpc package */ #define INCLUDE_DOSFS /* dosFs file system */ #define INCLUDE_RT11FS /* rt11Fs file system */ With these definitions, the systemT and systemT.st images will build and run successfully. 5.9 Renamed INCLUDE Definitions in configAll.h As a result of our continuing efforts to merge VxWorks code with Wind River Systems, two INCLUDE definitions in yourCloneTree/config/all/configAll.h have been renamed in the V3.2 and V3.2A releases. o INCLUDE_PROXY_ARP is now called INCLUDE_PROXY_SERVER o INCLUDE_SM_NETAUTO is now called INCLUDE_SM_SEQ_ADDR 5.10 Moved INCLUDE Definitions in configAll.h Several INCLUDE definitions specific to AXPvme systems have been moved from yourCloneTree/config/all/configAll.h to yourCloneTree/AXPvme/config.h. This change is related to our efforts to merge software with Wind River Systems. The moved definitions are: o PRCAUX_CLOCK_HERTZ o INCLUDE_PRCAUX_REALTIME o INCLUDE_SHOW_PRCAUX_REALTIME o INCLUDE_TIMEDIST_MASTER o INCLUDE_TIMEDIST_SLAVE o INCLUDE_VB Documentation Notes 5-3 Look for these definitions in yourCloneTree/AXPvme /config.h, even if the documentation refers you to configAll.h. 5.11 Moving the INCLUDE_ANSI_ALL Symbol If you move the symbol INCLUDE_ANSI_ALL out of the #if FALSE section of yourCloneTree/AXPvme/configAll.h, be sure to move it above the line where it is referenced by the line #ifdef INCLUDE_ANSI_ALL. Otherwise the additional definitions will not be included. 5.12 Clock Rate for AXPvme Real-Time Clocks The clock rate for the realtime clocks on AXPvme systems is set in yourCloneTree/config/AXPvme/config.h. Although the default rate is 4096, the rate can be set much higher. The maximum acceptable value varies, depending on factors such as the processor speed, the bus speed, the relative complexity of the clock interrupt service routine, and the rate at which other interrupts occur. When that maximum value is exceeded, the clock interrupts occur faster than the system is physically able to service them. As more and more of the available CPU time is spent servicing clock interrupts, less and less is available for everything else, and the system appears to hang. You need to select the clock rate judiciously in order to allow other normal system functions to operate correctly. 5.13 Making Compressed Images for AXPvme boot ROMs The new additions to the AXPvme family feature a user programmable flash ROM that is much larger than that on the existing members of the family. Table 5-1 shows the "userflash" ROM sizes for all AXPvme systems. Table_5-1_Maximum_Userflash_Image_Sizes_for_AXPvme_Modules_ AXPvme_Module____Maximum_Image_Size_(Compressed)___________ AXPvme 160, 64 512 Kbytes (continued on next page) 5-4 Documentation Notes Table 5-1 (Cont.) Maximum Userflash Image Sizes for AXPvme __________________Modules__________________________________ AXPvme_Module____Maximum_Image_Size_(Compressed)___________ AXPvme 230, 3.5 Mbytes 166,_100___________________________________________________ The dialogue shown on the console when you make a compressed boot ROM image indicates the size of the actual flash ROM image. You need to check that the size reported for the compressed image is not larger than the size of your boot ROM. See Part I of the VxWorks Alpha Hardware Supplement for details. 5.14 Change to Clock Connect Routine Arguments The data type on the second argument to the clock connect routines has been changed from int to long to allow passing an address to the clock handler on 64 bit machines. The procedures are now defined as follows: STATUS sysClkConnect (FUNCPTR routine, long arg); STATUS sysAuxClkConnect (FUNCPTR routine, long arg); STATUS sysPRCAuxClkConnect (FUNCPTR routine, long arg); 5.15 Interpreting References to the VxWorks Directory Tree Throughout the VxWorks documentation, the installed directory tree is referred to as /usr/opt/VXWnnn. In this notation, nnn denotes the VxWorks version; for example, VXW320 denotes Version 3.2, or VXW31A denotes VxWorks 3.1A. The current VxWorks version is V3.2; therefore the installed directory tree is located at /usr/opt/VXW320. ________________________ Note ________________________ In some VxWorks documents references to the installed directory tree have not yet been updated to use the generic notation. If you encounter a stale reference, Documentation Notes 5-5 such as /usr/opt/VXW310, you should interpret it to mean the current tree location, /usr/opt/VXW320. ______________________________________________________ 5.16 LOCAL_MEM_LOCAL_ADRS on EBxx Platforms On EBxx target systems, the value LOCAL_MEM_LOCAL_ADRS is used as the starting address of a memory area that is saved on a restart, or warm reboot. This area will contain initialization data such as the default boot line. Following a catastrophic error it will contain some information describing the cause of failure. On a cold boot, VxWorks will store the initialization data in memory starting at the address value specified by LOCAL_ MEM_LOCAL_ADRS. If you do not have the correct value for LOCAL_MEM_LOCAL_ADRS, the system might overwrite some part of itself. On EBxx platforms this value, by default, is defined as 0x2F0000, just below 300000. This value should change if you change the default palcode and image addresses. If you boot from ROM, the lowest value for this constant is zero, with the palcode loaded at address 0x4000 and the image loaded at the address defined by (size of palcode + 0x4000) rounded to a 0x4000 (16 Kbyte) boundary. If you boot with the debug monitor, the lowest value for LOCAL_MEM_LOCAL_ADRS is 0x200000, with the palcode starting at 0x204000 (2 Mbytes +16 Kbytes), and the image starting at 0x200000 + size-of-palcode + 0x4000 (2 Mbytes + size-of- palcode + 16 Kbytes), rounded to a 16 Kbyte boundary. 5.17 O3 Optimization Available If you are running Digital UNIX V3.2 or later you can use the -O3 compiler switch to compile your application source code and to recompile various pieces of the VxWorks operating system itself. To support older versions of Digital UNIX use -O2, the default switch. 5-6 Documentation Notes The -O3 switch performs all optimizations including global register allocation and procedure inlining. In some cases, much more efficient code will be produced. Those pieces of the VxWorks operating system which you can recompile to take advantage of -O3 optimization include src/usr, src/drv and all the BSPs in config. To change to the -O3 compiler switch, edit the file h /make/make.21064osf and change all occurrences of O2 to O3. Then change to the directory you want to recompile (config/AXPvme, for example), delete Makefile.21064osf, and re-make the directory. For example: # cd yourCloneTree/h/make # vi make.21064osf # cd yourCloneTree/config/AXPvme # rm Makefile.21064osf # make system 5.18 Limit on the Number of Global Symbols There is a limit on the number of global symbols that can be referenced by the initially booted VxWorks image (such as system, system.st, or one of their derivatives). An entry in the Global Offset Table is generated for each global subroutine that is referenced. For example, the following code generates two entries in the Global Offset Table: static subroutine1(int arg) { printf("%d\n",arg); } subroutine2(int arg) { printf("%d\n",arg); } main() { int five = 5; Documentation Notes 5-7 subroutine1(five); subroutine2(five); printf("%d\n",five); } One entry is made for referencing subroutine2 because it is a globally accessible subroutine. Another entry is for referencing printf. An entry is not made for referencing subroutine1 because it is declared as static and is not globally accessible. Each entry in the Global Offset Table occupies 16 bytes. You can see the current size of the Global Offset Table by using the Digital UNIX odump utility. The size of the .lita section is the size of the global symbol table. For example: # odump -h test.o ***SECTION HEADER*** Name Paddr Vaddr Size Scnptr Relptr Lnnoptr Nreloc Nlnno Flags blah.o: .text 0x0000000000000000 0x0000000000000000 0x0000000000000120 0x00000000000001a8 0x0000000000000348 0x0000000000000000 42 0 0x00000020 .xdata 0x0000000000000120 0x0000000000000120 0x0000000000000020 0x00000000000002c8 0x00000000000005e8 0x0000000000000000 0 0 0x02400000 .pdata 0x0000000000000140 0x0000000000000140 0x0000000000000020 0x00000000000002e8 0x00000000000005e8 0x0000000000000004 16 0 0x02800000 .lita 0x0000000000000160 0x0000000000000160 0x0000000000000020 0x0000000000000308 0x00000000000006e8 0x0000000000000000 3 0 0x04000000 .sdata 0x0000000000000180 0x0000000000000180 0x0000000000000020 0x0000000000000328 0x0000000000000718 0x0000000000000718 0 4 0x00000200 In this case, the size of the .lita section is 0x20 bytes, representing 2 global symbols referenced. To see the size of your .lita section use the odump utility on the system or system.st image you will be booting. The limit on the size of the .lita section is 0x00010000 (or 64K). The 5-8 Documentation Notes VxWorks operating system, in its default configuration, uses approximately 37 Kbytes, leaving 27 Kbytes available. If you link an application with many different global references in with the VxWorks kernel and exceed the 64K .lita limit, the system will crash shortly after booting. You must decrease the size of the .lita section either by decreasing the number of referenced global symbols in your application or by dynamically loading your application, using the VxWorks dynamic module loader instead of linking it in with the kernel. There is no limit on images loaded dynamically. The .lita limit affects only the image that contains the VxWorks kernel and is initially booted. 5.19 getpid() Routine Not Supported The POSIX routine getpid() is not supported. A POSIX pid (like the one supplied to the kill() routine) should be obtained from one of the VxWorks routines that returns a task ID. For example, taskIdSelf() and taskSpawn() both return task IDs. 5.20 System-wide List of Error Codes A system-wide list of error codes, generated by makeStatTbl, is provided in yourCloneTree/src/usr, not in yourCloneTree/config/all, as claimed in the makeStatTbl manpage and the VxWorks Reference Manual. 5.21 Notes on Manpages 5.21.1 New Manpages Available Manpages for the makefile preprocessor tools mpp and mdepend are missing from the VxWorks Reference Manual and will be added in a future update. The manpages are available in the VxWorks manpage tree for online viewing. The mdepend tool adds dependencies to a VxWorks makefile. The mpp tool is the VxWorks makefile preprocessor. This tool looks at all MakeSkel files in a directory and generates a makefile from them on standard output. Documentation Notes 5-9 5.22 Notes on VxGDB 5.22.1 Diagnosing VxGDB Windows Interface Errors The VxGDB windows interface does not always handle errors in the most user-friendly manner. Often the window disappears immediately after displaying the error message from an unexpected situation. From the user's perspective, it is as if the windows interface simply disappears when the unanticipated error is encountered. You can make the error message visible by using the line mode debugger. Invoke the debugger with the -l switch, vxgdb -l, and reissue the commands which led up to the crash. The error message will be displayed on your screen, and it will remain there, giving you ample time to read it. 5.22.2 VxGDB's "net connect: RPC: Program Not Registered" Message When you issue a target vxworks my-target-machine command immediately after the target machine boots, you will see this message: (vxgdb) target vxworks snow Connecting to target system across net... net_connect: RPC: Program not registered Couldn't connect to remote target. This error message means that the VxGDB connect request was issued before the target was completely booted. The solution is to reissue the connect request a few seconds later. If you continue to see this message for more than a few seconds, it could indicate that you have failed to include the remote debugger support in your yourCloneTree/config /all/configAll.h file. See the VxWorks Guide to VxGDB, Section 1.4, Configuring VxWorks Software for Remote Debugging, for more information. 5.22.3 VxGDB run Command Accepts Up to 9 Arguments The VxWorks Guide to VxGDB incorrectly states that the run command accepts up to 10 arguments after the entryPoint. The run command accepts 9 arguments after the entryPoint. 5-10 Documentation Notes 5.22.4 VxGDB Default Directory for Redirected Task I/O The VxGDB default directory for redirected task I/O is your home directory. (See Section 1.10.10 Task I/O in the VxWorks Guide to VxGDB.) If you want to use another directory, specify it as such. For example: (vxgdb) run taskId > /usr/users/smith/test/taskOutput 5.22.5 Setting Options for Tasks Spawned Under VxGDB Numerical values for the rdbRunTaskOptions task variable (discussed in Section 1.10.12.2 of the VxWorks Guide to VxGDB) are found in the /usr/opt/VXW320/h/taskLib.h file. For example, the command for setting this variable to supervisor mode is: (vxgdb) set rdbRunTaskOptions=0x0001 5.23 Notes on Software for the Digital Alpha AXPvme Module 5.23.1 adpCreateMapPath Modifications The adpLib documentation in the VxWorks Reference Manual omits mention of the following new fields in the adpMapObj data structure. Figure 1-8 in the VxWorks Reference Manual shows the fields in the map objects structure, but it omits these new fields. o reqSize A u_long value indicating the size of the adp map object originally requested by the user. This field follows the size field shown in Figure 1-8 in the VxWorks Reference Manual. o dstAddress A u_long value indicating the destination address originally requested by the user. This field follows the address field shown in Figure 1-8 in the VxWorks Reference Manual. 5.24 Notes on X Windows Use Documentation Notes 5-11 5.24.1 Exiting an X Window Application You should flush your display (for example, by calling the XFlush() or XSync() routine) before the task running the X application exits. Simply closing the display does not flush it back to the X display server. You have to flush it explicitly. In addition, if you are using the Xt Toolkit, you should not destroy your application context (by calling the XtDestroyApplicationContext() routine) until all your displays in all your tasks have been closed for the last time. To exit a particular X application which might then be restarted, clean up the widgets, close and flush the display, and exit the application. For example: XtUnmapWidget(toplevel); XtDestroyWidget(toplevel); XtCloseDisplay(display); XFlush(display); exit(1); 5.24.2 X Window Applications May Need More Stack It may be necessary to increase the default task stack size when you use the X Window libraries. Use the checkStack() routine to determine if your application has overrun its stack or is close to overrunning it. 5.24.3 Motif Example Provided An example Motif program is available in the yourCloneTree /src/demo/X directory. The files periodic.c and periodic.uil show how a Motif application might be ported to run under VxWorks for Alpha software. The application displays many different kinds of Motif widgets. 5.24.4 Use MrmOpenHierarchyPerDisplay() Instead of MrmOpenHierarchy() The MrmOpenHierarchy() routine in the Mrm library is obsolete. Use the MrmOpenHierarchyPerDisplay() routine instead. 5-12 Documentation Notes 5.25 Configuring the VAXELN API In addition to the INCLUDE_ELNAPI symbol, you must also move the INCLUDE_ANSI_ALL and INCLUDE_POSIX_TIMERS symbols out of an #if FALSE section in the yourCloneTree/config/all /configAll.h file. You must also add the LIB_ELN library to the list of libraries in your yourCloneTree/config/target /Makefile.21064osf file. Always add LIB_ELN before lib21064osfvx.a. If you are in doubt, just make it the first library referenced. For example, change this: LIBS = $(VX_BSP_BASE)/lib/lib$(CPU)$(TOOL)drv.a \ $(VX_VW_BASE)/lib/lib$(CPU)$(TOOL)vx.a $(LIB_EXTRA) to this: LIBS = $(LIB_ELN) \ $(VX_BSP_BASE)/lib/lib$(CPU)$(TOOL)drv.a \ $(VX_VW_BASE)/lib/lib$(CPU)$(TOOL)vx.a $(LIB_EXTRA) 5.26 EB6x PAL Code and SYSGEN Utility Support The current EB6x VxWorks Board Support Package requires the latest release of the Alpha Evaluation Board Software Developers Kit, EBSDK V1.3A or later. You should create a new SROM and a new EPROM from the EBSDK kit. 5.27 Tracing a Task in the Prolog on an Alpha Target System The following message is issued if the task you are tracing is currently in the prolog. This can occur when you are using the local symbolic debugger from the shell, issue a break, and do a tt() on a task that is at a breakpoint: -> tt "t1" trcLib: PC is in prolog, retry operation after PC > = 0xfffffc0000376140 value = 0 = 0x0 -> To work around this problem, choose one of these procedures: o Step past the prolog (as denoted by the PC value in the error message) Documentation Notes 5-13 o Set a breakpoint at a later point in the procedure The following example shows shell output when a user issues the same tt() call after stepping past the prolog: -> tt "t1" fffffc00003d0cc4 kerTaskEntry +18 : temptest (0) fffffc00003762b0 temptest +40 : temptest2 (2, 99) fffffc000037624c temptest2 +4c : temptest3 (3, 999, 888) fffffc00003761dc temptest3 +5c : temptest4 (4, 9999, 888, 777) value = 0 = 0x0 -> 5.28 Username Length Restricted for rsh Boot A username longer than eight characters causes the rsh boot to fail. 5.29 netDrv Devices Cannot Use rm(), rename(), remove() A netDrv device that accesses other VxWorks targets cannot use the rm(), remove(), or rename() functions. 5-14 Documentation Notes A _________________________________________________________________ Changes Since the Release of VxWorks V3.2 The notes in this appendix refer to changes in the software and documentation between VxWorks for Alpha V3.2 and V3.2A. A.1 Changes Since VxWorks for Alpha V3.2 A.1.1 VxWorks Linking Loader Modified for Digital UNIX V4.0 The VxWorks linking loader has been modified to work with the Digital UNIX V4.0 link editor (ld). The modified loader will work with partially linked images (ld -r) generated by Digital UNIX V3.2, V3.2C, or V4.0 systems. A.1.2 V3.2A Can Be Installed on Digital UNIX V4.0 VxWorks V3.2 could not be installed on Digital UNIX V4.0. This condition has been fixed in VxWorks V3.2A. ________________________ Note ________________________ VxWorks V3.2A does not support any Digital UNIX T4.0 field test version. ______________________________________________________ A.1.3 V3.2A Network Loaders Incompatible with V3.2 After installing VxWorks V3.2A, you may need to update the locations of the VxWorks network loaders in /etc/bootptab. You cannot use the V3.2 versions of these loaders to load images built with V3.2A. Likewise, you cannot use V3.2A network loaders to load images built with V3.2. V3.2 and V3.2A both contain the following network loaders: o bin/osf/netload.AXPvme o bin/osf/netload.AXPpci33 Changes Since the Release of VxWorks V3.2 A-1 A.1.4 netTask Software In previous releases, the software that implements the TCP/IP communications stack could produce a memory access violation in the netTask task. The error was caused by use of an invalid address while processing the TCP input packet stream. This problem caused the network task to fail, and then the target system would no longer be reachable over the network. This error has been corrected. A.1.5 bcopy Routine Optimization In previous releases, optimization for the bcopy() routine corrupted data in some cases. When the source and destination buffers for the bcopy() operation overlap, bcopy() copies the source buffer to the destination buffer, starting from the end of each buffer, and continuing to the beginning of each buffer. If the buffers have the same byte alignment, the copy operation is optimized to copy in long units instead of byte units. The optimization in previous releases incorrectly copied an additional long data element that would include bytes preceding the beginnings of the buffers. This error would in some cases corrupt data immediately preceding the destination buffer. This error has been corrected. A.1.6 Digital UNIX C Compiler In all versions of Digital UNIX up to V4.0, the default compiler accessed by the cc command is the Digital UNIX C compiler (also known as acc). The VxWorks operating system is built with this compiler and all the VxWorks make files use it, by default. The DEC C compiler is also available on recent versions of Digital UNIX, as an option. In Digital UNIX V4.0, the DEC C compiler is the default cc compiler. The acc compiler will continue to be available using the -oldc switch to the cc command. A-2 Changes Since the Release of VxWorks V3.2 Use of the DEC C compiler with VxWorks V3.2A is unsupported. If you use Digital UNIX V4.0 or a later version, you must add the -oldc option to all your compiler commands to access the acc compiler instead of the DEC C compiler. You need to make the change by hand to the file yourCloneTree/h/make/make.21064osf. Add the -oldc switch to the CC definition. For example, the existing defintion of CC looks like this: CC=cc On Digital UNIX V4.0, change the definition to look like this: CC=cc -oldc After making this change, you should ensure that make files are regenerated by first deleting them in the directory you want to rebuild. For example, the following lines show how to regenerate make files in the AXPvme Board Support Package directory and then rebuild the VxWorks image: # cd yourCloneTree/config/AXPvme # rm Makefile* # mpp > Makefile # make vxWorks Be sure your VX environment variables are set properly before you call mpp. Do not delete MakeSkel, because it is not a generated file. No change is necessary to the definition of CC if you use any version of Digital UNIX earlier than V4.0. DEC C will be supported in a future release of VxWorks for Alpha. A.1.7 68K tools on Digital UNIX V4.0 To use the 68K tools in yourCloneTree/bin/gnu/lib on Digital UNIX V4.0 you must replace the existing version of bin/gnu/lib/cc1 with bin/gnu/lib/du40_cc1. For example: # cd /yourCloneTree/bin/gnu/lib # mv cc1 cc1_old # cp du40_cc1 cc1 # chmod 755 cc1 If you are using a version of Digital UNIX V3.0 or V3.2, no action is necessary. Changes Since the Release of VxWorks V3.2 A-3 A.1.8 POSIX Documentation Out of Date The VxWorks POSIX Manual is out of date and will not be revised. Since the publication of that book, Digital has incorporated the POSIX code provided by Wind River Systems. See Appendix B for lists and descriptions of the available POSIX functions. In addition, Chapter 3 in the Introduction to VxWorks contains material on programming with POSIX which may be out of date. The information in this chapter was last updated before POSIX 1003.1b became a standard. In some cases, the material is relevant to draft versions of the standard. In all cases, the final arbiter of all VxWorks POSIX 1003.1b issues is the POSIX 1003.1b standard, itself. For a copy of the standard, contact the IEEE: IEEE Computer Society 1730 Massachusetts Ave. NW Washington, DC 20036-1903 (202) 728-9614 A.1.9 fcntl() Not POSIX Compliant The fcntl() function in VxWorks is not POSIX compliant. The VxWorks version of fcntl() is the same as the VxWorks ioctl() function. It is not compatible with the POSIX fcntl() function. See the manpage for ioctl() for more information. A-4 Changes Since the Release of VxWorks V3.2 B _________________________________________________________________ POSIX Interface in VxWorks V3.2A This appendix lists functions that make up the POSIX interface for VxWorks V3.2A. o Section B.1 lists the VxWorks functions defined in the IEEE POSIX.1 specification. o Section B.2 lists the VxWorks real-time functions defined in the IEEE POSIX.1b specification. o Section B.3 lists the VxWorks pthreads functions defined in the IEEE POSIX.4a specification. B.1 POSIX.1 Functions The following POSIX functions form part of the standard POSIX operating system interface. For descriptions of these functions, refer to Information Technology - Portable Operating System Interface - Part 1: System Application Program Interface (API) [C Language]; IEEE Std 1003.1-1990, Institute of Electrical and Electronics Engineers, Inc, New York, NY, 1990. _________________________________________________________________ Function_____________________Purpose_____________________________ asctime_r() Converts broken-down time into a string close() Closes an open file closedir() Closes a directory stream ctime_r() Converts time in seconds into a string POSIX Interface in VxWorks V3.2A B-1 _________________________________________________________________ Function_____________________Purpose_____________________________ fdatasync() Forces completion of all queued I/O operations associated with the specified file to the synchronized I/O completion state with data integrity fdopen() Opens a file specified by a file descriptor fileno() Returns the file descriptor for a stream fstat() Gets file status information ftruncate() Truncates a file or shared memory object to a specified length fstat() Obtains information about an open file ioctl() Performs an I/O control function. The following functions are supported for shared memory objects: FIOSEEK (position the file offset to arg), FIOWHERE (return the current file offset), FIONREAD (return the number of bytes between the offset and eof), and FIOSETEOF (set eof to the current object length if arg is less than or equal to zero, or set eof to the offset specified by arg). The FIOSEEK function can also be accessed using the lseek() function. For more information, see the VxWorks Reference Manual. Reviewers: this function is defined in the VxWorks Reference Manual getcwd() Gets the current default path gmtime_r() Converts calendar time into broken- down time kill() Sends a signal to a process or a group of processes B-2 POSIX Interface in VxWorks V3.2A _________________________________________________________________ Function_____________________Purpose_____________________________ localtime_r() Converts calendar time into broken- down time lseek() Sets a file or shared memory object read/write pointer. For more information, see the VxWorks Reference Manual. Reviewers: this function is defined in the VxWorks Reference Manual open() Opens a file opendir() Opens a directory for searching pause() Suspends the task until delivery of a signal read() Reads the specified number of bytes from a file readdir() Reads one entry from a directory rewinddir() Resets the position of a directory stream sigaction() Examines or specifies the action of a specific signal sigaddset() Adds a signal to a list of signals sigdelset() Deletes a signal from an existing set of signals sigemptyset() Initializes a set of signals by excluding all signal definitions sigfillset() Initializes a set of signals by including all signal definitions sigismember() Tests whether a signal is a member of an existing set of signals sigpending() Stores a set of pending signals in a specified space sigprocmask() Examines or changes the signal mask of the calling process sigsuspend() Replaces the signal mask of the calling process and then suspends the process POSIX Interface in VxWorks V3.2A B-3 _________________________________________________________________ Function_____________________Purpose_____________________________ stat() Obtains information about an open file strtok_r() Breaks down a string into tokens (reentrant) uname() Returns information about the current operating system write() Writes the specified number of bytes _____________________________to_a_file___________________________ B.2 POSIX.1b Functions The following POSIX functions form part of the real-time POSIX operating system interface. For descriptions of these functions, refer to IEEE Standard for Information Technology - Portable Operating System Interface [POSIX] - Part 1: System Application Program Interface [API] - Amendment 1: Realtime Extension [C Language], The Institute of Electrical and Electronics Engineers, Inc, New York, NY, 1994. _________________________________________________________________ Function_____________________Purpose_____________________________ clock_getres() Gets the clock resolution clock_gettime() Gets the current time of the clock clock_settime() Sets the clock to a specified time ftruncate() Truncates a file mlock() Locks specified pages into memory mlockall() Locks all pages used by a process into memory mq_close() Closes a message queue mq_getattr() Gets message queue attributes mq_notify() Notifies a task that a message is available on a queue mq_open() Opens a message queue B-4 POSIX Interface in VxWorks V3.2A _________________________________________________________________ Function_____________________Purpose_____________________________ mq_receive() Receives a message from a message queue mq_send() Sends a message to a message queue mq_setattr() Sets message queue attributes mq_unlink() Removes a message queue munlock() Unlocks specified pages munlockall() Unlocks all pages used by a process nanosleep() Suspends the current task until the time interval elapses sched_get_priority_max() Gets the maximum priority sched_get_priority_min() Gets the minimum priority sched_getparam() Gets the scheduling parameters for a specified task sched_getscheduler() Gets the current scheduling policy sched_rr_get_interval() Gets the current time slice sched_setparam() Sets a task's priority sched_setscheduler() Sets scheduling policy and scheduling parameters sched_yield() Relinquishes the CPU sem_close() Closes a named semaphore sem_destroy() Destroys an unnamed semaphore sem_getvalue() Gets the value of a semaphore sem_init() Initializes an unnamed semaphore sem_open() Initializes or opens a named semaphore sem_post() Unlocks (gives) a semaphore sem_trywait() Locks (takes) a semaphore, returning error if unavailable sem_unlink() Removes a named semaphore sem_wait() Locks (takes) a semaphore, blocking if not available statfs() Gets file status information using a pathname POSIX Interface in VxWorks V3.2A B-5 _________________________________________________________________ Function_____________________Purpose_____________________________ strerror_r() Maps an error number to an error string timer_create() Allocates a timer using the specified clock for a timing base timer_delete() Removes a previously created timer timer_getoverrun() Returns the timer expiration overrun timer_gettime() Gets the remaining time before expiration and the reload value timer_settime() Sets the time until the next _____________________________expiration_and_arm_timer____________ B.3 VxWorks POSIX Thread Control Functions The following POSIX functions form part of the threads extension for the POSIX interface. For descriptions of these functions, refer to Threads Extension for Portable Operating Systems, P1003.4a Draft 4, The Institute of Electrical and Electronics Engineers, Inc, New York, NY, August 10, 1990. _________________________________________________________________ Function_____________________Purpose_____________________________ pthread_attr_create() Creates a thread attributes object to be used when threads are created pthread_attr_delete() Deletes a thread attributes object pthread_attr_ Returns the inherit scheduling getinheritsched() attribute of a thread pthread_attr_getprio() Returns the value of the scheduling priority of threads created using an attributes object pthread_attr_getsched() Returns the scheduling policy of threads created using an attributes object pthread_attr_ Returns the minimum size of the getstacksize() stack for a thread created using an attributes object B-6 POSIX Interface in VxWorks V3.2A _________________________________________________________________ Function_____________________Purpose_____________________________ pthread_attr_ Changes the inherit scheduling setinheritsched() attribute of thread creation pthread_attr_setprio() Changes the scheduling priority of threads that are created using an attributes object pthread_attr_setsched() Sets the scheduling policy of a thread that is subsequently created using an attributes object pthread_attr_ Sets the minimum size of the setstacksize() stack needed for a thread using an attributes object pthread_cancel() Sends a cancel request to terminate execution of a thread pthread_cleanup_pop() Removes and executes the routine at the top of the calling thread's cleanup stack pthread_cleanup_push() Establishes a cleanup handler for the calling thread pthread_condattr_create() Creates a condition variable attributes object pthread_condattr_delete() Deletes a condition variable attributes object pthread_cond_broadcast() Wakes all threads that are waiting on a condition variable pthread_cond_destroy() Deletes a condition variable pthread_cond_init() Initializes a condition variable pthread_cond_signal() Wakes one thread that is waiting on a condition variable pthread_cond_timedwait() Causes a thread to wait on a condition variable or for an absolute time pthread_cond_wait() Causes a thread to wait for a condition variable pthread_create() Creates a thread object and a thread pthread_delay_np() Delays execution of a thread POSIX Interface in VxWorks V3.2A B-7 _________________________________________________________________ Function_____________________Purpose_____________________________ pthread_detach() Marks a thread for deletion pthread_exit() Terminates the calling thread pthread_get_expiration_ Obtains a value representing a np() desired (absolute) expiration time pthread_getprio() Returns the priority of a thread pthread_getscheduler() Returns the scheduling policy of a thread pthread_getspecific() Obtains the per-thread context associated with a key for the calling thread pthread_join() Causes the calling thread to wait for the termination of another thread pthread_keycreate() Generates a unique per-thread context key value pthread_lock_global_np() Locks a global mutex if it is unlocked pthread_mutexattr_create() Creates a mutex attributes object that specifies the attributes of mutexes when they are created pthread_mutexattr_delete() Deletes a mutex attributes object pthread_mutex_destroy() Deletes a mutex pthread_mutex_init() Initiates a mutex pthread_mutex_lock() Locks an unlocked mutex pthread_mutex_trylock() Locks an unlocked mutex; if the mutex is already locked, this function does not wait pthread_mutex_unlock() Unlocks a mutex pthread_once() Calls an initialization routine that can be executed by only one thread, a single time pthread_self() Returns the identifier of the calling thread B-8 POSIX Interface in VxWorks V3.2A _________________________________________________________________ Function_____________________Purpose_____________________________ pthread_setasynccancel() Enables or disables the responsiveness of the calling thread to asynchronous cancellation pthread_setcancel() Enables or disables the responsiveness of the calling thread to general cancellation pthread_setprio() Changes the priority of a thread pthread_setscheduler() Changes the scheduling policy and priority of a thread pthread_setspecific() Sets the per-thread context associated with a key for the calling thread pthread_testcancel() Requests delivery of a pending cancel (if there is one) to cancel the calling thread pthread_unlock_global_np() Unlocks a global mutex pthread_yield() Notifies the scheduler that the calling thread is willing to yield to other threads of the same _____________________________priority____________________________ POSIX Interface in VxWorks V3.2A B-9 C _________________________________________________________________ Support for Optional PCI Bus Devices _________________________________________________________________ adpFindDevice() Searches for a specific device adpNode structure. C Syntax #include struct adpNode *adpFindDevice (u_int adpType, u_int incarnationNumber, struct adpDeviceId *deviceId); Arguments adpType Specifies the ID of bus type where the device resides. Current supported bus types are: o PCI incarnationNumber Specifies which device to return from among a list of similar devices. deviceId Contains bus specific fields to identify a particular device during a search. A mask is used to create a set of matching parameters. For PCI bus devices, select any of the following masks: o PCI_DEVICE_ID_SEARCH o PCI_VENDOR_ID_SEARCH o PCI_BASE_CLASS_SEARCH Support for Optional PCI Bus Devices C-1 adpFindDevice() o PCI_SUB_CLASS_SEARCH Description Given a set of search parameters, this routine returns an adpNode structure for a specific device. Devices are grouped by the type of bus on which they reside. Search parameters can be enabled or disabled for matching, by using a mask. If more than one device matches the search parameters, the incarnationNumber argument is used to pick the desired (first, second, third (and so on) incarnation of the same device). ________________________ Note ________________________ This routine replaces the sysPciFindDevice() routine that was formerly a part of the board support package for AXPpci systems. ______________________________________________________ Return Values This routine returns a pointer to the appropriate adpNode structure, NULL if the structure is not found, or error. C-2 Support for Optional PCI Bus Devices D _________________________________________________________________ AXPpci 33 BSP Support for SCSI Disk Boot _________________________________________________________________ alphaDiskBootFile() Updates the boot block on a SCSI disk drive to use the specified file as the boot image when the system is booted from the Alpha SRM console. C Syntax #extern alphaDiskBootFile (char *filename) STATUS alphaDiskBootFile (char *filename); Arguments filename Specifies a pointer to the name of the DOS file that will be booted by the Alpha SRM console. Description This routine modifies an existing DOS boot block to be compatible with the Alpha SRM console boot block format, allowing the Alpha SRM console to directly boot a suitable VxWorks image from a SCSI disk drive. The routine accepts as input a single parameter. It is the full pathname of the boot image file. The routine then determines the starting LBN (logical block number) and the size (in logical blocks) of the boot image file. The routine then modifies the DOS boot block with this information in a manner compatible with the Alpha SRM. ___________________ Considerations ___________________ AXPpci 33 BSP Support for SCSI Disk Boot D-1 alphaDiskBootFile() o The DOS disk structure (BLK_DEV) must include the first block on the physical device. The Alpha SRM console requires this, and the VxWorks bootrom code assumes this. o The boot image file must be contiguous, as the Alpha SRM console requires. The VxWorks DOS file system attempts to make all files contiguous, but does not require contiguity. If the boot image file is not marked contiguous, the routine fails and returns an error. You must determine the best method of making the file contiguous. o The routine assumes that it can access the DOS device. That is, you should have previously created and initialized the DOS device. o The routine modifies the DOS file system boot block. This modification is required for the Alpha SRM console to directly boot from the disk device. However, this modification may or may not be compatible with existing or future MS-DOS systems. The modification does not have any effect on the DOS file system used within VxWorks. ______________________________________________________ Return Values OK if the boot block has been successfully updated. ERROR if an error occurred while the boot block was being updated. Error messages are written to the system console. Procedures for VxWorks Disk Boot on the AXPpci 33 Target System Disk booting is a two-step process, requiring up to three VxWorks images. The first of the three images is an ordinary VxWorks image, such as system.st, containing support for the network device, SCSI disk, shell, DOS and RAW file systems, and alphaDiskBoot procedures. This image is loaded by way of the network, and is used to initialize a DOS device (file system) on the SCSI drive. In addition, this image is used to copy the other VxWorks system images to the DOS device and to modify the DOS boot block to be D-2 AXPpci 33 BSP Support for SCSI Disk Boot alphaDiskBootFile() compatible with the boot block required by the Alpha SRM console. The second VxWorks system image needed is the bootrom_alpha image. This image is copied to the DOS device and is the image that is to be booted by the Alpha SRM console. This is a secondary loader and it loads the third and final VxWorks image. The third VxWorks image is your VxWorks application image, it contains the user application code. Steps in the Boot Process 1. The Alpha SRM console loads an image from the disk. This image is the VxWorks bootrom image (bootrom_alpha), the VxWorks loader. Its purpose is to load the final VxWorks user application image. 2. The VxWorks loader uses a VxWorks bootline stored in the target's NVRAM to determine where the loader is to find the final VxWorks application image. The loader reads the bootline information and proceeds to load the user's VxWorks application image, either from the same SCSI disk drive or over the network. Steps You Must Take to Successfully Boot an AXPpci33 Target from a SCSI Disk 1. Modify yourCloneTree/config/all/configAll.h to include the DOS and RAW file systems. You can accomplish this by moving the line shown in the following example to a place where it will be defined during the compilation phase. #define INCLUDE_DOSFS #define INCLUDE_RAWFS 2. Modify yourCloneTree/config/AXPpci33/config.h to define INCLUDE_ALPHA_DISK_BOOT. This involves changing the line in the example in Step 1 in the yourCloneTree/config /AXPpci33/config.h source code to read #if TRUE. 3. Modify yourCloneTree/src/config/usrScsi.c to reflect your SCSI disk configuration. See Chapter 8 of the VxWorks Programmer's Guide for information on this topic. AXPpci 33 BSP Support for SCSI Disk Boot D-3 alphaDiskBootFile() You may want to exclude SCSI autoconfiguration (in yourCloneTree/config/AXPpci33/config.h in favor of building your SCSI configuration information directly into the yourCloneTree/src/config/usrScsi.c module. On the disk that you want to make bootable, there must be a DOS file system that is the first file system partition on the physical device. The VxWorks Programmer's Guide provides information on how to create and initialize DOS file systems on SCSI devices. 4. Build the make target system.st. This image will contain, SCSI support, network support, Alpha Disk Boot support, and the command shell. 5. In the clone BSP directory, build the make target bootrom_alpha. This image will be the first image loaded when booting from the SCSI disk. 6. In a clone directory build the your application VxWorks image. 7. Boot the first image (system.st) over the network into the AXPpci 33 target system. 8. If all has gone well, you should be able to access your SCSI disk or disks, such as /sd0/. 9. Copy the bootrom_alpha image and the your VxWorks application image from your clone tree to the local SCSI disk on your target system. You may need to rename these images during the copy process. For example: % copy "yourCloneTree/config/AXPpci33/bootrom_alpha", "/sd0/bootrom" 10.Copy your application image to the SCSI disk on your target system. 11.At the shell prompt on the target enter: alphaDiskBootFile "/sd0/bootrom" In this example, /sd0/bootrom is the full file specification of the copy of bootrom_alpha image that you have copied to the target system in Step 9. This updates the boot block to indicate that the Alpha SRM Console should boot the /sd0/bootrom file. D-4 AXPpci 33 BSP Support for SCSI Disk Boot alphaDiskBootFile() 12.Define a new bootline in the AXPpci 33 NVRAM by entering the command bootChange at the shell prompt. Be certain to change the device specification to indicate the disk you want to boot from: scsi=, Change the filename to the file that you want to load, such as /sd0/system.st. 13.Return to the Alpha SRM Console prompt by typing Ctrl/X. 14.At the Alpha SRM Console prompt, boot the system from the SCSI disk. For example, enter the comand B DKA100. The console will then load the VxWorks bootrom image. When the VxWorks bootrom image executes, it waits for several seconds for input from the console terminal to stop the autoboot process. If there is no input from the console terminal, the boot process proceeds to load the file specified in the bootline stored in the NVRAM. If you do enter information on the console, the autoboot process halts. This allows you to make changes to the bootline and then proceed to load the final VxWorks application image. AXPpci 33 BSP Support for SCSI Disk Boot D-5