VxWorks[[R]]__________________________________ Installation Guide Order Number: AA-Q3YQC-TE This guide contains instructions for installing VxWorks software on Alpha processors that are running the Digital UNIX operating system. It also explains how to access the online release notes before or after installing the product. Revision/Update Information: This guide super- sedes the VxWorks Installation Guide AA-Q3YQB-TE. Operating System and Version: Digital UNIX, Version 3.0 or higher Software Version: VxWorks for Alpha, Version 3.2 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ First Printing, March 1992 Revised, November 1994, July 1995 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 1995. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: Bookreader, DEC, DECchip, DECwindows, RT-11, ThinWire, VAXELN, 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/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. S2914 ________________________________________________________________ Contents Preface.................................................. v 1 Preparing for VxWorks Software Installation 1.1 Release Notes................................... 1-1 1.2 Installation Checklist.......................... 1-2 1.3 License Registration............................ 1-2 1.4 Checking the Software Distribution Kit.......... 1-3 1.5 Installation Procedure Requirements............. 1-4 1.5.1 Checking Login Privileges .................... 1-4 1.5.2 Hardware Requirements ........................ 1-4 1.5.3 Software Requirements ........................ 1-5 1.5.4 Determining Disk Space Requirements .......... 1-5 1.6 Backing Up Your System Disk..................... 1-7 1.7 Stopping the Installation....................... 1-7 1.8 Installing from Media or Using ris.............. 1-7 2 Installing VxWorks Software 2.1 Installing VxWorks from the Digital CD-ROM Software Library................................ 2-2 2.2 Installing VxWorks from the VxWorks Standalone CD-ROM.......................................... 2-2 2.3 Installing VxWorks Using the Remote Installation Services Utility (ris).......................... 2-3 2.4 Continuing the Installation..................... 2-3 2.5 Monitoring Displays During the Subset Loading Process......................................... 2-5 iii 3 Completing the Installation 3.1 Running the Installation Verification Procedure....................................... 3-1 3.2 Using the VxWorks Tools......................... 3-2 3.2.1 Accessing the VxWorks Tools Directory ........ 3-2 3.2.2 Defining GCC_EXEC_PREFIX for 68K Cross-Compilation............................. 3-3 3.2.3 Using the shadow Utility ..................... 3-3 3.2.4 Defining Environment Variables for System Builds........................................ 3-4 3.2.5 Updating and Reading Important Files ......... 3-5 3.2.6 Accessing Online Help ........................ 3-6 3.2.7 Differentiating Digital UNIX and VxWorks Commands...................................... 3-9 3.3 Cross-Development Commands - for 68K Target Systems......................................... 3-9 3.4 Deleting VxWorks from Your System............... 3-10 A Sample Listings for VxWorks Installation and IVP B Directory Tree C Recovering from Installation Errors C.1 Failures During Product Installation ........... C-1 C.2 Failures During Product Use..................... C-2 Index Figures 1-1 Installation Checklist ....................... 1-3 B-1 VxWorks Directory Tree ....................... B-1 iv Tables 1-1 VxWorks Subset Sizes ......................... 1-6 3-1 GNU Toolkit Cross-Development Commands for 68K Target Systems................................ 3-10 v ________________________________________________________________ Preface The VxWorks[[R]] software installation procedure creates directory structures subordinate to the /usr/opt/VXWnnn + and /var/opt/VXWnnn directories and loads VxWorks subsets into them. After you run the installation procedure, you will need to perform additional tasks, such as copying or linking to installed files and setting environment variables. Purpose of This Guide This guide explains how to install VxWorks[[R]] for Alpha on Alpha systems that run the Digital UNIX operating system. Intended Audience The audience for this guide is: o VxWorks users o System managers who manage VxWorks host and target systems o Remote Installation Services (RIS) managers who manage RIS server areas ___________________ + Throughout the VxWorks documentation, the notation nnn denotes the VxWorks version. For example, VXW320 denotes VxWorks Version 3.2; VXW310 denotes VxWorks Version 3.1 v Structure of This Document This guide consists of three chapters and three ap- pendixes: o Chapter 1, Preparing for VxWorks Software Installation, describes the operating system and hardware require- ments for VxWorks software installation and explains related procedures that you complete before the installation. This chapter provides information you need to make your installation run smoothly. o Chapter 2, Installing VxWorks Software, describes the installation procedures for local, server, and client installations. Installing VxWorks software involves using one installation kit which includes the following VxWorks software subsets: - VxWorks Base Support - VxWorks Release Notes - VxWorks X Client Support - VxWorks BSP for Alpha - VxWorks BSP for 68K - VxWorks BPK for Alpha - VxWorks VAXELN API o Chapter 3, Completing the Installation, describes the Installation Verification Procedure (IVP) and postinstallation procedures that you must complete in order to use the VxWorks software. o Appendix A, Sample Listings for VxWorks Installation and IVP, contains a listing of a sample VxWorks installation with the Installation Verification Procedure. o Appendix B, Directory Tree, includes a figure that shows the hierarchy of VxWorks kit directories. o Appendix C, Recovering from Installation Errors, provides information to help you deal with failures and errors that might occur during installation or product use. vi Conventions The following conventions are used in this guide: __________________________________________________________ Convention_______Meaning__________________________________ UPPERCASE and The Digital UNIX system differentiates lowercase between lowercase and uppercase characters. Literal strings that appear in text, examples, syntax descriptions, and function descriptions must be entered exactly as shown. system output This typeface indicates system output or the exact name of a command, option, partition, pathname, directory, or file. % The percent sign (%) is the default user prompt. # A number sign is the default superuser prompt. -> This is the VxWorks shell prompt for interactive input. red type In hardcopy documentation, red ink is used in interactive examples to indicate typed user input. For example: # mount -dr /dev/ra1c /cdrom bold type The following items appear in bold type: o In Bookreader documentation, a bold typeface is used in interactive examples to indicate typed user input. For example: # setld -l /cdrom o Case-sensitive name of a library, driver, command, or command option, when it appears in text or in syntax displays. For example: Enter a setld command that requests the load function and . . . vii __________________________________________________________ Convention_______Meaning__________________________________ keyword In text, this typeface indicates the case-sensitive name of a routine, function, pathname, directory, or file. For example: The clone is made up of symbolic links to files in the /usr/opt/VXWnnn directory. This typeface is also used in interactive examples and other screen displays. italic type This typeface indicates variable information, such as user-supplied information in commands, syntax, or example text. For example: The default value for the new-path parameter is the current directory. . . . Horizontal ellipsis points indicate that the preceding item can be repeated one or more times. It is used in syntax descriptions and function definitions. Vertical ellipsis points indicate that . a portion of an example or figure is . omitted. . setld(8) Cross-references to the online reference pages include the appropriate section number in parentheses. For example, a reference to setld(8) indicates that you can find the material on the command setld in Section 8 of the Digital UNIX online reference pages. In tables, key names are designated by a box. For example: . viii __________________________________________________________ Convention_______Meaning__________________________________ Ctrl/x Ctrl/x indicates a control key sequence. Press the key labeled Ctrl while you simultaneously press another key. For example: Ctrl/C. [y] In a prompt, square brackets indicate that the enclosed item is the default response. For example, [y] means that the default response is Yes. 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. Associated Documents o VxWorks Programmer's Guide o VxWorks Reference Manual o VxWorks Release Notes o Introduction to VxWorks o VxWorks Guide to VxGDB o VxWorks Guide to GNU Software for 68K Systems o VxWorks POSIX Manual o VxWorks Guide to DECwindows o VxWorks Alpha Hardware Supplement o VxWorks Motorola MVME147S-1 and MVME147SA-1 Hardware Supplement o VxWorks Motorola MVME167 Hardware Supplement ix VxWorks Board Porting Kit for Alpha For creating board support packages for additional Alpha target boards of your choosing, refer to this document, which is available separately: o VxWorks Board Porting Guide x 1 ________________________________________________________________ Preparing for VxWorks Software Installation Before you start the installation procedures in Chapter 2, complete the preparation requirements outlined in this chapter. This chapter provides the information you need to make your installation run smoothly. This chapter contains the following sections: o Section 1.1, Release Notes o Section 1.2, Installation Checklist o Section 1.3, License Registration o Section 1.4, Checking the Software Distribution Kit o Section 1.5, Installation Procedure Requirements o Section 1.6, Backing Up Your System Disk o Section 1.7, Stopping the Installation o Section 1.8, Installing from Media or Using ris 1.1 Release Notes VxWorks provides release notes for all installations. Digital strongly recommends that you read the VxWorks Release Notes before you use the product. The release notes contain information about restrictions and changes to the software. Online release notes in text format are supplied as an optional installation subset and are placed in /usr/opt/VXWnnn/READMEFIRST. For information about installing the release notes before you install VxWorks software, see Section 2.4. Preparing for VxWorks Software Installation 1-1 Your documentation will include a cover letter which may provide information that is important for you to know before installing VxWorks software. That information may not be included either in installation guides or primary release notes documents. Please check the cover letter to see if it contains information about VxWorks software. 1.2 Installation Checklist Figure 1-1 is a checklist to which you can refer while you install the software. It shows the steps you must follow in preparing for the installation, installing the software, and verifying the installation. 1.3 License Registration VxWorks software includes support for the Digital UNIX License Management Facility (LMF). A License Product Authorization Key (License PAK) must be registered in the License Database (LDB) before you can use VxWorks software on a node. The License PAK may be shipped with the kit if you have ordered the license and media together. Otherwise, it may be shipped separately. If you are installing VxWorks software as an update on a node already licensed for this software, you may have already completed the License PAK registration requirements. If you are installing prerequisite or optional software along with VxWorks software, install the PAKs for any prerequisite or optional software before you install VxWorks software. Installation of any of the VxWorks subsets requires prior installation of a corresponding LMF PAK. You need the VXWORKS-TOOLS PAK for any VxWorks installation. The following PAKs are optional: o VXWORKS-AXP o VXWORKS-68K o VXWORKS-X-CLIENT o VXWORKS-BPK-AXP 1-2 Preparing for VxWorks Software Installation o VXWORKS-VAXELN-API For complete information about using the License Management Facility, see the Guide to Software License Management and the lmf(8) reference page. 1.4 Checking the Software Distribution Kit Use the Bill of Materials to check that you have the correct software distribution kits. Each distribution includes the full VxWorks kit. The VxWorks kit includes: o Documentation in bookreader format o Installation media containing subsets for installing the following: - VxWorks online release notes - VxWorks base support (prerequisite for other software subsets) - A board support package (BSP) for Alpha applications - A board support package for Motorola 68K applica- tions - Support for X Client software - VxWorks Board Porting kit for Alpha - VAXELN API for VxWorks Be sure to read the online release notes and the cover letters for information about this release of VxWorks. Some information you need to know before you install the product may be included there and not in the printed release notes or in this manual. If your software distribution kit is damaged or incom- plete, contact your Digital representative. Preparing for VxWorks Software Installation 1-3 1.5 Installation Procedure Requirements The VxWorks base kit must be installed before you install any optional subset (BSP or other software). When you list the base kit along with other subsets in response to prompts from the installation procedure (see Appendix A), the installation procedure installs them in the right order, with the base kit first. If you install subsets individually and you do not start with the base kit, the installation procedure displays a warning message to remind you that the VxWorks Base Support subset must be installed first. For example, you cannot successfully install VxWorks software by starting with the VxWorks X Client Support subset. A local installation or ris server installation takes approximately 30 minutes, depending on your choice of target support and your system configuration. A client installation may take longer because it is dependent on network activity at the time you do the installation. If the network is not active, you should expect an installation time roughly equal to a local installation. Running the Installation Verification Procedure (IVP) on your local system may take an additional 5 to 10 minutes. 1.5.1 Checking Login Privileges You must be able to log in as root on the system where you are installing VxWorks software to have sufficient privileges to perform the installation. 1.5.2 Hardware Requirements To perform the installation, you need the following hardware: o Software distribution device You need a CD-ROM drive if you are installing from CD-ROM media. o Terminal You can use either a hardcopy terminal or a video terminal to respond to prompts from the installation procedure. 1-4 Preparing for VxWorks Software Installation See the VxWorks Software Product Description (SPD) for additional hardware requirements. 1.5.3 Software Requirements This version of VxWorks requires that the Digital UNIX operating system Version 3.0 or higher be installed on your system. Future releases may require higher versions of the operating system. 1.5.4 Determining Disk Space Requirements Table 1-1 lists the disk space requirements for loading VxWorks software subsets on Alpha processors running the Digital UNIX operating system. The /usr/opt/VXWnnn directory contains all the files from the installed subsets. All sizes are in kilobytes. Preparing for VxWorks Software Installation 1-5 Table_1-1_VxWorks_Subset_Sizes__________________________________ Size in Subset Kilobytes During Size in Kilobytes Title_______Subset_Name__Installation_______After_Installation__ VxWorks VXWBASEnnn 31300 31200 Base Support VxWorks VXWRELnnn 100 100 Release Notes VxWorks VXW68KBSPnnn /usr/opt /usr/opt/VXWnnn: 23400 BSP for /VXWnnn: 23400 /var/opt/VXWnnn: 0 68K /var/opt /VXWnnn: 1700 VxWorks VXWAXPBSPnnn /usr/opt /usr/opt/VXWnnn: 20600 BSP for /VXWnnn: 20600 /var/opt/VXWnnn: 0 Alpha /var/opt /VXWnnn: 3800 VxWorks VXWAXPBPKnnn /usr/opt /usr/opt/VXWnnn: 29500 BPK for /VXWnnn: 29500 /var/opt/VXWnnn: 0 Alpha /var/opt /VXWnnn: 5200 VxWorks VXWELNAPInnn 900 900 ELN API VxWorks X VXWXCLIENTnnn 16400 16400 Client TOTAL:___________________________________________________________ Using this table, find the total of the values for the subsets that you plan to load. Use the df command (see man pages for details) to compare the space required for subsets with the free space currently on the disks where VxWorks files will reside. 1-6 Preparing for VxWorks Software Installation 1.6 Backing Up Your System Disk Digital recommends that you back up your system disk before you install any software. For details on performing a system disk backup, see your Digital UNIX documentation. 1.7 Stopping the Installation You can stop the installation procedure at any time by typing Ctrl/C. However, files created up to this point are not deleted automatically. You must interactively delete files from the following directories: o /usr/opt/VXWnnn o /var/opt/VXWnnn 1.8 Installing from Media or Using ris Someone from your site must perform at least one VxWorks installation from the distribution medium. Your site system manager can then decide whether to make a VxWorks distribution kit available online so that subsequent installations of VxWorks can use the Remote Installation Service (ris). For information about extracting VxWorks subsets to a ris distribution area, see the Guide to Sharing Software on a Local Area Network. If you expect to use VxWorks subsets from the ris area of a remote system for installation on your local system, first check with your site system manager to ensure that: o A VxWorks network kit is available for use. o Your system is registered as a ris client. o A VxWorks kit is installed in the server area and is available for use. If VxWorks subsets are available to you on a server system, you will need the name of that system to start the installation procedure described in this guide. Preparing for VxWorks Software Installation 1-7 2 ________________________________________________________________ Installing VxWorks Software This chapter describes the procedures for installing VxWorks software. Before you start, read Chapter 1, which describes general options and requirements for installing the product. This chapters contains the following sections: o Section 2.1, Installing VxWorks from the Digital CD-ROM Software Library o Section 2.2, Installing VxWorks from the VxWorks Standalone CD-ROM o Section 2.3, Installing VxWorks Using the Remote Installation Services Utility (ris) o Section 2.4, Continuing the Installation o Section 2.5, Monitoring Displays During the Subset Loading Process You can install VxWorks software locally from media or from a server area. If you encounter any failures during installation, see Appendix C. The installation procedure installs VxWorks software under the /usr/opt/VXWnnn directory. The Installation Verification Procedure (IVP) uses the /var/opt/VXWnnn directory. Appendix B describes the tree for the /usr/opt /VXWnnn directory. VxWorks software provides development software for Alpha target systems and Motorola 68K target systems. The installation procedure lets you selectively install the board support package and other optional software for a particular target system. You can select from the range of available installation subsets by responding to prompts from the setld utility, as explained in Section 2.4. Installing VxWorks Software 2-1 2.1 Installing VxWorks from the Digital CD-ROM Software Library You can install VxWorks software from the Digital CD-ROM Software Library for Digital UNIX Layered Products disk. Instructions for accessing the software are provided with the disk. The VxWorks software is located in the /VXWnnn /kit directory on the CD-ROM. Once you have mounted the disk at a convenient mount point (for example, /osfcd), proceed with Section 2.4. 2.2 Installing VxWorks from the VxWorks Standalone CD-ROM Perform these steps to install VxWorks software from a CD-ROM disk that contains only the VxWorks product: 1. Insert the disk into the CD drive. Make sure you know the name of the drive on your system. If you do not know the name, use the file command to find it. As superuser, type the following command: # file /dev/rrz*c The entry for the CD-ROM will include the words "RRD42 disk." Notice that the file command will give you this information only if you access the drives in character mode (using the rrz*c name). 2. Mount the CD-ROM at a convenient mount point as a block device. Use the option -dr. For example, if you found the name of the CD-ROM in Step 1 to be /dev/rrz4c, you can mount the drive at /osfcd with the following command: # mount -dr /dev/rz4c /osfcd Notice that you must mount the drive in block mode (using the /dev/rz*c name.) 3. The VxWorks software binaries are located in the /VXWnnn/kit directory on the CD-ROM. The bookreader documentation is located in the /VXWnnn/decw_book directory. After you have located the software and documentation, proceed with Section 2.4. 2-2 Installing VxWorks Software 2.3 Installing VxWorks Using the Remote Installation Services Utility (ris) You can install VxWorks software using the ris utility. The ris utility performs remote installation services to install software from a disk area on the server for a client machine through the TCP/IP local network. See Sharing Software on a Local Area Network Installation Guide, provided in the Digital UNIX documentation set, for more information about setting up a ris area. After your ris area is configured, proceed with Section 2.4. 2.4 Continuing the Installation Make sure you are at the root (/) directory by entering the following command as superuser: # cd / Check for previously installed VxWorks subsets. The setld utility does not allow you to install subsets that are already installed. You need to delete those subsets for which you want to install updated copies. Proceed as follows: 1. List current VxWorks subsets that are already installed on your system. # setld -i | grep VXW 2. Delete those current subsets listed as "installed." For example, to delete the VXWBASEnnn subset, issue the following command: # setld -d VXWBASEnnn Use the -l option for the setld command and specify the location of the software subsets that corresponds to the type of installation you are performing. For example, if you are installing subsets from the Digital CD-ROM Software Library or from the VxWorks standalone CD-ROM, enter a command similar to the following: # setld -l /osfcd/VXWnnn/kit Installing VxWorks Software 2-3 If you are performing a ris installation (from node ris_ server, for example), enter a command similar to the following: # setld -l ris_server: The installation procedure displays the following text: The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1) VxWorks Base Toolkit Support 2) VxWorks Board Porting Kit for Alpha (EB64,EB66,EB64+) 3) VxWorks Board Support Package for 68K 4) VxWorks Board Support Package for Alpha (AXPvme,AXPpci) 5) VxWorks Release Notes 6) VxWorks VAXELN API 7) VxWorks X Client Support --- MORE TO FOLLOW --- Enter your choices or press RETURN to display the next screen. Choices (for example, 1 2 4-6): 1 4 Or you may choose one of the following options: 8) ALL of the above 9) CANCEL selections and redisplay menus 10) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6): 1 4 You are installing the following optional subsets: VxWorks Base Toolkit Support VxWorks Board Support Package for Alpha (AXPvme,AXPpci) Is this correct? (y/n): y 2-4 Installing VxWorks Software 2.5 Monitoring Displays During the Subset Loading Process The procedure displays a message indicating that the installation is starting: Checking file system space required to install selected subsets: File system space checked OK. VxWorks for Alpha Copyright 1992, 1995 by Digital Equipment Corporation, Maynard, Massachusetts All Rights Reserved. VxWorks Vn.n - Base Toolkit Support Installation... If, during the installation, you encounter errors from the setld utility, see the Diagnostics section of the setld(8) reference page for an explanation of the error and the appropriate action to take. When you see the "Verifying" message during the subset installation, the installation procedure is checking to see that the files are copied correctly; it is not part of the IVP. If the verification process fails, you can look in the file /usr/var/adm/fverify to find information that can help you diagnose the problem. Chapter 3 describes the postinstallation requirements specified in the final informational messages from the procedure. Chapter 3 also explains how to run the IVP after installation and how to delete VxWorks subsets. Installing VxWorks Software 2-5 3 ________________________________________________________________ Completing the Installation This chapter explains what to do following the instal- lation to make VxWorks software ready for use. It also explains how to access the VxWorks documentation. This chapter contains the following sections: o Section 3.1, Running the Installation Verification Procedure o Section 3.2, Using the VxWorks Tools o Section 3.3, Cross-Development Commands - for 68K Target Systems o Section 3.4, Deleting VxWorks from Your System 3.1 Running the Installation Verification Procedure You can run the VxWorks Installation Verification Procedure (IVP), as a part of the installation procedure, to verify that the software is available on your system. You might also want to run the IVP independently after a power failure to be sure that users can access the VxWorks development system. The IVP verifies the installation as follows: o The procedure creates a duplicate of /usr/opt/VXWnnn in /var/opt/VXWnnn/tmp. o The procedure attempts to build a new kernel and symbol table in the various target-specific configuration directories. To run the appropriate IVP after an installation, enter one of the following commands: # setld -v VXW68KBSPnnn Completing the Installation 3-1 or # setld -v VXWAXPBSPnnn or # setld -v VXWAXPBPKnnn For a sample listing that shows the VxWorks IVP display, see Appendix A. 3.2 Using the VxWorks Tools To set up easy invocation of VxWorks development tools from the Digital UNIX host, include the tools directory in your Digital UNIX shell search path. In addition, for Motorola 68K cross-compilation, you must define the GCC_EXEC_PREFIX environment variable. 3.2.1 Accessing the VxWorks Tools Directory The VxWorks host tools are found in a bin directory, the path for which is determined by your target architecture: Alpha targets /usr/opt/VXWnnn/bin/osf Motorola 68K targets /usr/opt/VXWnnn/bin/gnu To conveniently run the VxWorks tools, you may want to put the appropriate bin directory in your Digital UNIX shell search path by executing one of the following path- definition commands. Alternatively, you can put the path definition in the appropriate shell startup file, such as .cshrc or .profile. In csh, for Alpha target development: % setenv PATH /usr/opt/VXWnnn/bin/osf:$PATH or % set path=(/usr/opt/VXWnnn/bin/osf $path) In csh, for Motorola 68K target development: % setenv PATH /usr/opt/VXWnnn/bin/gnu:$PATH or % set path=(/usr/opt/VXWnnn/bin/gnu $path) In sh or ksh, for Alpha target development: % PATH=/usr/opt/VXWnnn/bin/osf:$PATH % export PATH 3-2 Completing the Installation In sh or ksh, for Motorola 68K target development: % PATH=/usr/opt/VXWnnn/bin/gnu:$PATH % export PATH 3.2.2 Defining GCC_EXEC_PREFIX for 68K Cross-Compilation In order to use the GNU C compiler to cross-compile for Motorola 68K targets, you must first define the GCC_EXEC_ PREFIX environment variable as follows: setenv GCC_EXEC_PREFIX /usr/opt/VXWnnn/bin/gnu/lib/ 3.2.3 Using the shadow Utility You use the VxWorks shadow utility to create clone direc- tory trees. This utility is located in the appropriate bin directory for your target architecture. Here is the command format for running the shadow utility: ________________________Note ________________________ This command assumes that your Digital UNIX shell search path includes the VxWorks tools directory. See the previous section, "Using the VxWorks Tools", for information on setting your Digital UNIX shell search path. _____________________________________________________ % shadow [ -x directory ] old-path [ new-path ] where the flag and parameters have the following meanings: -x This flag excludes unwanted directories. old-path The source directory tree to be cloned. new-path The destination for the clone directory tree. The default value for this parameter is the current directory. The following command sequence shows how to clone the VxWorks directory tree to the private directory /usr/users/fred/work: % mkdir /usr/users/fred/work 1 % cd /usr/users/fred/work 2 % shadow -x unsupported /usr/opt/VXWnnn 3 1 Create the subdirectory /usr/users/fred/work. Completing the Installation 3-3 2 Change the current directory to the subdirectory you just created. 3 Create a clone tree of /usr/opt/VXWnnn into the current directory /usr/users/fred/work, excluding the unsupported directory. ________________________Note ________________________ Before cloning a directory tree, you should check for and delete any previous clones of that tree. _____________________________________________________ 3.2.4 Defining Environment Variables for System Builds The following environment variables must be defined in order to build a VxWorks system file: VX_VW_BASE Specifies the location to which you copied or cloned the directory tree. For example, VX_VW_BASE=/usr/users/fred/work. VX_HSP_BASE Specifies the location to which you copied or cloned the directory tree. VX_HOST_TYPE Specifies the host system type: o VX_HOST_TYPE=gnu for Motorola 68K target development o VX_HOST_TYPE=osf for Alpha target development VX_MAKE Specifies the relative location of the make utility within the directory tree: VX_MAKE=h/make. VX_BSP_BASE Specifies the location to which you copied or cloned the directory tree. For example, in csh, for a Motorola 68K system build, the following could be defined: 3-4 Completing the Installation setenv VX_VW_BASE /usr/users/fred/work setenv VX_HSP_BASE /usr/users/fred/work setenv VX_HOST_TYPE gnu setenv VX_MAKE h/make setenv VX_BSP_BASE /usr/users/fred/work Other key environment variables are PATH and GCC_EXEC_PREFIX, discussed in "Using the VxWorks Tools", and MANPATH, discussed in "Accessing Online Help". 3.2.5 Updating and Reading Important Files /etc/bootptab When setting up a bootp/tftp downline load to an Alpha target system, this file must be updated with appropriate target boot parameters. For more information, see the VxWorks Programmer's Guide. /etc/vxbootlines When setting up a bootp/tftp downline load to an Alpha target system, this file must be updated with an appropriate standard VxWorks boot line. For more information, see the VxWorks Programmer's Guide. .rhosts This file, located in the user's home directory, must contain the names of target systems the user can downline load. /usr/opt/VXWnnn/READMEFIRSTline release notes are supplied as an optional installation subset. Completing the Installation 3-5 3.2.6 Accessing Online Help Three sources of online help are available: one from the VxWorks shell running on your VxWorks target system and the other two from the Digital UNIX host system. From the VxWorks shell, you can invoke the following online help commands, provided the corresponding subsystem has been included in your VxWorks system configuration: help() dbgHelp() timexHelp() spyHelp() netHelp() nfsHelp() These help commands display brief summaries of various VxWorks subsystems. From the Digital UNIX host, two forms of online help are available: o The VxWorks manual set on CD-ROM o VxWorks reference material, in the form of manpages All VxWorks manuals are available on CD-ROM for online access with Bookreader. The VxWorks software distribution includes the nroff sources for reference material, including the VxWorks Reference Manual, its hardware supplements, and reference portions of the VxWorks POSIX Manual. Formatted entries can be accessed online from the Digital UNIX host using the man command. The VxWorks manpage directory, which resides in the VxWorks directory tree at relative location yourCloneTree/man, is organized into the following sections: o Section 1 contains overviews of VxWorks libraries, drivers, and target systems. o Section 2 contains descriptions of individual routines from the libraries and drivers in Section 1, including BSP routines. 3-6 Completing the Installation o Section 3 contains descriptions of VxWorks utilities (commands) that run on the Digital UNIX host. Using an Alias to Access Manpages VxWorks manpages can be accessed by aliasing man -M or setting the MANPATH environment variable. Using an alias allows you to create a command that searches only the VxWorks man directory. This method uses man -M with the pathname of the directory that man will search. For example: % alias vxman 'man -M /usr/opt/VXWnnn/man' Then, to display the VxWorks manpage for ls(), enter: % vxman ls This ensures that you see the VxWorks version of ls(), not the Digital UNIX version. Setting the MANPATH Environment Variable To view VxWorks manual pages with the man command, add the pathname of the VxWorks manpage directory to the MANPATH environment variable. If you have not already set this variable, also be sure to include /usr/share/man so that you can continue to view the Digital UNIX manual pages. ________________________Note ________________________ The VxWorks manpage directory contains entries for routines also found in the Digital UNIX C library. Place the VxWorks manual directory before or after /usr/share/man in your MANPATH definition, depending on which entries you prefer to see by default. _____________________________________________________ For example, if you cloned the VxWorks directory tree to /usr/users/fred/work and you want to view VxWorks manual pages by default, you can add the following to your .cshrc file: setenv MANPATH /usr/users/fred/work/man:/usr/share/man Completing the Installation 3-7 If you did not clone the manpage portion of the VxWorks directory tree and you want to view VxWorks manual pages by default, you can add the following to your .cshrc file: setenv MANPATH /usr/opt/VXWnnn/man:/usr/share/man To look up commands that are available in both the Digital UNIX and VxWorks operating system environments, you can take advantage of numbering differences between Digital UNIX and VxWorks manpages and specify the appropriate entry by number: o Specify 2 to select a VxWorks routine over the Digital UNIX equivalent o Specify 3 to select a VxWorks host utility (command) over the Digital UNIX equivalent For example, to display the manual entry for the VxWorks routine ls(), use: % man 2 ls An alternate way to override the default manpage display is by explicitly specifying the manpage directory path on the command line. See the Digital UNIX manpage man(1) for instructions on temporarily altering the precedence of manpage directories. Accessing BSP Manpages Manual entries for BSPs have the board name prefixed to the entry name. For example, to see the sysLib library overview manpage for the Motorola MVME167 target, type: % man mv167_sysLib Target system overview manpages are given the name of their respective target prefix. For example, to see the target description for the MVME167, type: % man mv167 3-8 Completing the Installation 3.2.7 Differentiating Digital UNIX and VxWorks Commands To look up commands that are available in both the Digital UNIX and VxWorks operating system environments, you can take advantage of numbering differences between Digital UNIX and VxWorks manpages and specify the appropriate entry by number: o Specify 2 to select a VxWorks routine over the Digital UNIX equivalent o Specify 3 to select a VxWorks host utility (command) over the Digital UNIX equivalent For example, to display the manual entry for the VxWorks routine ls(), use: % man 2 ls An alternate way to override the default manpage display is by explicitly specifying the manpage directory path on the command line. See the Digital UNIX manpage man(1) for instructions on temporarily altering the precedence of manpage directories. Manual entries for BSPs have the board name prefixed to the entry name. For example, to see the sysLib library overview manpage for the Motorola MVME167 target, type: % man mv167_sysLib Target system overview manpages are given the name of their respective target prefix. For example, to see the target description for the MVME167, type: % man mv167 3.3 Cross-Development Commands - for 68K Target Systems The GNU toolkit cross-development tools have been renamed to avoid confusion with the corresponding host native tools. A suffix identifying the target architecture is appended to each tool name. For example, the cross- compiler for the 68K processor family is named cc68k. Once you have set up the PATH variable to include the gnu directory, you can invoke the cross-development tools with the names shown in Table 3-1. Completing the Installation 3-9 Table 3-1 GNU Toolkit Cross-Development Commands for 68K __________Target_Systems__________________________________ GNU Toolkit Command_____________UNIX_Version__________________________ ar68k ar as68k as cc68k cc cpp68k cpp ld68k ld nm68k nm objdump68k objdump ranlib68k ranlib size68k size strip68k____________strip_________________________________ 3.4 Deleting VxWorks from Your System If you must remove a version of VxWorks from your system, delete each subset that you have previously installed. To delete subsets: 1. Log in as root. 2. Make sure you are at the root directory (/) by entering this command: # cd / 3. Look for the word "installed" in the listing produced by: # setld -i | grep VXW Then delete the installed subsets. For example, to delete the VXWBASEnnn subset, enter this command: # setld -d VXWBASEnnn 3-10 Completing the Installation A ________________________________________________________________ Sample Listings for VxWorks Installation and IVP This appendix provides a sample listing for an instal- lation of VxWorks software on a Digital UNIX system. Following the installation listing, this appendix shows output from the Installation Verification Procedures for: o The VxWorks Board Support Package for Alpha o The VxWorks Board Support Package for 68K o The VxWorks Board Porting Kit for Alpha # setld -l /cdrom/VXWnnn/kit The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1) VxWorks Base Toolkit Support 2) VxWorks Board Porting Kit for Alpha (EB64,EB66,EB64+) 3) VxWorks Board Support Package for 68K 4) VxWorks Board Support Package for Alpha (AXPvme,AXPpci) 5) VxWorks Release Notes 6) VxWorks VAXELN API 7) VxWorks X Client Support --- MORE TO FOLLOW --- Enter your choices or press RETURN to display the next screen. Choices (for example, 1 2 4-6): 1 4 Or you may choose one of the following options: 8) ALL of the above 9) CANCEL selections and redisplay menus 10) EXIT without installing any subsets Sample Listings for VxWorks Installation and IVP A-1 Add to your choices, choose an overriding action or press RETURN to confirm previous selections. Choices (for example, 1 2 4-6): 1 4 You are installing the following optional subsets: VxWorks Base Toolkit Support VxWorks Board Support Package for Alpha (AXPvme,AXPpci) Is this correct? (y/n): y Checking file system space required to install selected subsets: File system space checked OK. VxWorks for Alpha Copyright 1992, 1995 by Digital Equipment Corporation, Maynard, Massachusetts All Rights Reserved. VxWorks Vn.n - Base Toolkit Support Installation... Installation of this Base Toolkit subset takes about 5 minutes. Allow 25 minutes to install all optional subsets. VxWorks Base Toolkit Support Copying from /cdrom/VXWnnn/kit Working....Tue Jun 20 15:00:22 EDT 1995 Verifying Working....Tue Jun 20 15:01:14 EDT 1995 VxWorks for Alpha Copyright 1992, 1995 by Digital Equipment Corporation, Maynard, Massachusetts All Rights Reserved. VxWorks Vn.n - Board Support Package for Alpha (AXPvme,AXPpci) Installation... VxWorks Board Support Package for Alpha (AXPvme,AXPpci) Copying from /cdrom/VXWnnn/kit Working....Tue Jun 20 15:01:37 EDT 1995 Verifying Installing VxGDB components A-2 Sample Listings for VxWorks Installation and IVP Installing rdb.a into /usr/opt/VXWnnn/lib/lib21064osfvx.a. Existing file /usr/opt/VXWnnn/lib/lib21064osfvx.a saved. s - creating symbol hash table. Wait... Installing command driver for the osf host into /usr/opt/VXWnnn/bin/osf Installing executables for the osf host into /usr/opt/VXWnnn/bin/osf Installing the VxWorks and vxworks man pages into /usr/share/man/man4. VxWorks Vn.n - Base Toolkit Support Installation completed successfully. Configuring "VxWorks Base Toolkit Support" (VXWBASEnnn) VxWorks Vn.n - Board Support Package for Alpha (AXPvme,AXPpci) Installation completed successfully. Configuring "VxWorks Board Support Package for Alpha (AXPvme,AXPpci)" (VXWAXPBSPnnn) Would you like to run the Board Support Package for Alpha IVP (y/n) [y]: VxWorks for Alpha Copyright 1992, 1995 by Digital Equipment Corporation, Maynard, Massachusetts All Rights Reserved. Sample Listings for VxWorks Installation and IVP A-3 Running IVP for VxWorks for Alpha Building clone tree of /usr/opt/VXWnnn in /var/opt/VXWnnn This step takes about 5 minutes. Clone tree successfully created in /usr/opt/VXWnnn Test the AXPvme board support package Building the VxWorks kernel make -f Makefile.21064osf CPU=21064 TOOL=osf system cc -c -O3 -I/h -I. -I/usr/opt/VXWnnn/config/all/ -I/usr/opt/VXWnnn/h -I/usr/op t/VXWnnn/h/ -I/usr/opt/VXWnnn/src/config/ -I/usr/opt/VXWnnn/src/drv/ -Wf,-XNd1 0000 -Dconst= -DCPU=21064 -std1 -D_ANSI_C_SOURCE /usr/opt/VXWnnn/config/all/u srConfig.c cc -c -O3 -I/h -I. -I/usr/opt/VXWnnn/config/all/ -I/usr/opt/VXWnnn/h -I/usr/op t/VXWnnn/h/ -I/usr/opt/VXWnnn/src/config/ -I/usr/opt/VXWnnn/src/drv/ -Wf,-XNd1 0000 -Dconst= -DCPU=21064 -std1 -D_ANSI_C_SOURCE sysLib.c VX_CPU_FAMILY=ALPHA /usr/opt/VXWnnn/bin/osf/makeVersion > version.c cc -c -O3 -I/h -I. -I/usr/opt/VXWnnn/config/all/ -I/usr/opt/VXWnnn/h -I/usr/op t/VXWnnn/h/ -I/usr/opt/VXWnnn/src/config/ -I/usr/opt/VXWnnn/src/drv/ -Wf,-XNd1 0000 -Dconst= -DCPU=21064 -std1 -D_ANSI_C_SOURCE version.c ld -N -EL -e sysInit -Ttext fffffc0000252400 -o system dataSegPad.o sysALib. o sysLib.o tyCoDrv.o sysAdpLib.o usrConfig.o version.o /usr/opt/VXWnnn/lib/lib 21064osfdrv.a /usr/opt/VXWnnn/lib/lib21064osfvx.a /usr/opt/VXWnnn/lib/lib21064o sfmath.a /usr/opt/VXWnnn/bin/osf/ecoffXsyms < system > system.sym VxWorks kernel successfully built AXPvme board support package ran successfully -------------------------------------------- A-4 Sample Listings for VxWorks Installation and IVP Test the AXPpci33 board support package Building the VxWorks kernel make -f Makefile.21064osf CPU=21064 TOOL=osf system cc -c -O3 -I/h -I. -I/usr/opt/VXWnnn/config/all/ -I/usr/opt/VXWnnn/h -I/usr/op t/VXWnnn/h/ -I/usr/opt/VXWnnn/src/config/ -I/usr/opt/VXWnnn/src/drv/ -Wf,-XNd1 0000 -Dconst= -DCPU=21064 -std1 -D_ANSI_C_SOURCE /usr/opt/VXWnnn/config/all/u srConfig.c cc -c -O3 -I/h -I. -I/usr/opt/VXWnnn/config/all/ -I/usr/opt/VXWnnn/h -I/usr/op t/VXWnnn/h/ -I/usr/opt/VXWnnn/src/config/ -I/usr/opt/VXWnnn/src/drv/ -Wf,-XNd1 0000 -Dconst= -DCPU=21064 -std1 -D_ANSI_C_SOURCE sysLib.c VX_CPU_FAMILY=ALPHA /usr/opt/VXWnnn/bin/osf/makeVersion > version.c cc -c -O3 -I/h -I. -I/usr/opt/VXWnnn/config/all/ -I/usr/opt/VXWnnn/h -I/usr/op t/VXWnnn/h/ -I/usr/opt/VXWnnn/src/config/ -I/usr/opt/VXWnnn/src/drv/ -Wf,-XNd1 0000 -Dconst= -DCPU=21064 -std1 -D_ANSI_C_SOURCE version.c ld -N -EL -e sysInit -Ttext fffffc0000182400 -o system dataSegPad.o sysALib. o sysLib.o tyCoDrv.o sysIo.o sysAdpLib.o usrConfig.o version.o /usr/opt/VXWnnn /lib/lib21064osfdrv.a /usr/opt/VXWnnn/lib/lib21064osfvx.a /usr/opt/VXWnnn/lib/l ib21064osfmath.a /usr/opt/VXWnnn/bin/osf/ecoffXsyms < system > system.sym VxWorks kernel successfully built AXPpci33 board support package ran successfully -------------------------------------------- Cleaning up files created during the IVP VxWorks Vn.n - Board Support Package for Alpha (AXPvme,AXPpci) IVP successful. # Sample Listings for VxWorks Installation and IVP A-5 B ________________________________________________________________ Directory Tree Figure B-1 shows the structure of the VxWorks directory tree. Directory Tree B-1 C ________________________________________________________________ Recovering from Installation Errors This appendix provides information to help you deal with failures or errors that might occur during product installation or product use. If you find an error in the documentation, fill out and submit the Reader's Comments form at the back of this document. Include the section and page number where the error occurred. C.1 Failures During Product Installation If errors occur during installation, the system displays failure messages. For example, if installation fails due to insufficient disk space, this message appears: There is not enough space for subset VXWBASEnnn VXWBASEnnn will not be loaded. Errors can occur during installation if any of those conditions exists: o The prerequisite operating system software version is incorrect. o There is insufficient disk space. o The user is not logged in as root. o VXWBASEnnn is not installed before other VxWorks subsets. See Section 1.5 in Chapter 1 for details. o Required LMF PAKs are not installed. For descriptions of error messages generated by these conditions, see the Digital UNIX documentation on system messages, recovery procedures, and Digital UNIX software installation. Recovering from Installation Errors C-1 C.2 Failures During Product Use If an error occurs while VxWorks software is in use and you believe the error is caused by a problem with the product, take one of the following actions: o If you have a Software Product Services Support Agreement, contact your Customer Support Center (CSC) by telephone or by using the electronic means provided with your support agreement (such as DSNlink). The CSC provides telephone support for high-level advisory and remedial assistance. When you initially contact the CSC, indicate the following: - The name and version number of the operating system you are using - The version number of VxWorks software you are using - The hardware system you are using (such as a model number) - A brief description of the problem (one sentence if possible) - How critical the problem is o If you have a Self-Maintenance Software Agreement, you can submit a Software Performance Report (SPR). o If you do not have any type of software services support agreement and you have purchased VxWorks software within the past year, you can submit an SPR if you think the problem is caused by a software error. When you submit an SPR, complete these steps: 1. Describe as accurately as possible the circumstances and state of the system when the problem occurred. Include the version number of the VxWorks software being used. Demonstrate the problem with specific examples. 2. Reduce the problem to as small a size as possible. 3. Include listings of any command files, INCLUDE files, or relevant data files, and so forth. For information about submitting media, see the tar(1) reference page. C-2 Recovering from Installation Errors 4. Report only one problem per SPR. This facilitates a faster response. 5. Mail the SPR package to Digital Equipment Corporation. If the problem is related to VxWorks software documenta- tion, you can do one of the following: o Report the problem to the CSC (if you have a Software Product Services Support Agreement and the problem is severe). Recovering from Installation Errors C-3 ________________________________________________________________ Index A CD-ROM ___________________________ installation from, 2-2 Aborting the installation, Checking 1-7 login privileges, 1-4 ar cross-development the distribution kit, 1-3 command, 3-10 Checklist, 1-3 ar68k cross-development Clone directory tree, command, 3-10 creating with the shadow as cross-development utility, 3-3 command, 3-10 Commands as68k cross-development cross-development, 3-9 command, 3-10 Digital UNIX and VxWorks, 3-9 B__________________________ cpp cross-development Backing up your system command, 3-10 disk, 1-7 cpp68k cross-development Board Porting kit for Alpha command, 3-10 , 1-3 Cross-development commands, Board support package GNU toolkit, 3-9 for Alpha applications, D 1-3 ___________________________ for Motorola 68K dbgHelp() routine, 3-6 applications, 1-3 Deleting VxWorks, 3-10 Development environment C accessing online help, ___________________________ 3-6 cc cross-development creating command, 3-10 with the shadow cc68k cross-development utility, 3-3 command, 3-10 differentiating Digital UNIX and VxWorks commands, 3-8 Index-1 Development environment (cont'd) H__________________________ environment variables Hardware requirements, 1-4 GCC_EXEC_PREFIX, 3-2 Help commands, 3-6 MANPATH, 3-7 Digital UNIX host-based PATH, 3-2 man, 3-6 VX_BSP_BASE, 3-4 VxWorks shell-based VX_HOST_TYPE, 3-4 dbgHelp(), 3-6 VX_HSP_BASE, 3-4 help(), 3-6 VX_MAKE, 3-4 netHelp(), 3-6 VX_VW_BASE, 3-4 nfsHelp(), 3-6 reading the READMEFIRST spyHelp(), 3-6 file, 3-5 timexHelp(), 3-6 updating the .rhosts help() routine, 3-6 file, 3-5 using the VxWorks tools, I__________________________ 3-2 Installation GNU C compiler, 3-2 checklist, 1-3 Differentiating Digital from media, 1-7 UNIX and VxWorks of VxWorks commands, 3-9 sample listing, A-1 Digital UNIX commands, 3-9 prompts, 2-4 Directory tree, VxWorks, requirements, 1-4 B-1 using ris, 1-7 Disk space Installation Guide, 1-3 requirements, 1-5 Installation media, 1-3 Displays for subset loading Installation subsets, 1-5 , 2-5 Installation Verification Distribution kit, 1-3 Procedure See IVP G__________________________ IVP, 3-1 GCC_EXEC_PREFIX environment running, 3-1 variable, 3-2 GNU L__________________________ toolkit cross-development ld cross-development commands, 3-9 command, 3-10 GNU C compiler (Digital ld68k cross-development UNIX, for 68K targets), command, 3-10 3-2 License PAK, 1-2 License registration, 1-2 Loading subsets, 2-5 Index-2 Login privileges, 1-4 Release notes, 1-1, 1-3 Requirements, 1-4 M__________________________ hardware, 1-4 man command software, 1-5 accessing from the host, ris, 1-7 3-6 Running the installation MANPATH environment verification procedure, variable, 3-7 3-1 Monitoring displays, during S the subset loading, 2-5 ___________________________ Sample listing N__________________________ for VxWorks installation, netHelp() routine, 3-6 A-1 nfsHelp() routine, 3-6 for VxWorks IVPs, A-1 nm cross-development Selecting subsets, 2-4 command, 3-10 shadow utility, use nm68k cross-development for creating a clone command, 3-10 directory tree, 3-3 size cross-development O command, 3-10 ___________________________ size68k cross-development objdump cross-development command, 3-10 command, 3-10 Software objdump68k cross- requirements, 1-5 development command, subsets required, 1-5 3-10 spyHelp() routine, 3-6 Online release notes, 1-3 Stopping the installation, 1-7 P__________________________ strip cross-development PAK command, 3-10 License, 1-2 strip68k cross-development PATH environment variable, command, 3-10 3-2 Subsets Prompts, 2-4 for installation, 1-5 loading displays, 2-5 R selecting, 2-4 ___________________________ System disk ranlib cross-development backup, 1-7 command, 3-10 ranlib68k cross-development command, 3-10 Index-3 VX_HOST_TYPE environment T__________________________ variable, 3-4 timexHelp() routine, 3-6 VX_HSP_BASE environment variable, 3-4 V__________________________ VX_MAKE environment VxWorks variable, 3-4 base support, 1-3 VX_VW_BASE environment commands, 3-9 variable, 3-4 directory tree, B-1 X VxWorks ELN API, 1-3 ___________________________ VX_BSP_BASE environment X Client software support, variable, 3-4 1-3 Index-4