VAXELN-KMV1A-TOOLKIT User's Guide Order Number: AA-KT40B-TE October 1989 This manual describes the VAXELN-KMV1A-TOOLKIT and the installation of the driver in the VAXELN operating system. Digital Equipment Corporation Maynard, Massachusetts ________________________ October 1989 __________ The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. __________ © Digital Equipment Corporation October 1989. All Rights Reserved. Printed in U.S.A. __________ The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DEC DIBOL UNIBUS DEC/CMS EduSystem VAX DEC/MMS IAS VAXcluster DECnet MASSBUS VMS DECsystem-10 PDP VT DECSYSTEM-20 PDT DECUS RSTS DECwriter RSX DIGITAL This document was prepared using VAX DOCUMENT, Version 2.0. __________________________________________________________ Contents _____________________________________________________ PREFACE ix __________________________________________________________ CHAPTER 1 VAXELN-KMV1A-TOOLKIT 1-1 _____________________________________________________ 1.1 KMV1A 1-1 _____________________________________________________ 1.2 KMV1A CONTROL PROGRAMS 1-1 _____________________________________________________ 1.3 VAXELN KMV1A TOOLS 1-1 __________________________________________________________ CHAPTER 2 VAXELN KMVTOOL MICROCODE APPLICATION GENERATION PROCEDURE 2-1 _____________________________________________________ 2.1 INTRODUCTION 2-1 _____________________________________________________ 2.2 RUNNING VAXELN_KMVGEN 2-2 _____________________________________________________ 2.3 VAXELN_KMVGEN QUESTIONS AND EXPLANATIONS 2-5 _____________________________________________________ 2.4 VAXELN_KMVGEN SAMPLES 2-18 2.4.1Sample VAXELN_KMVGEN Run ___________ 2-18 2.4.2Sample Data Tables Module __________ 2-23 2.4.3Sample VAX-11 RSX Task Builder Command Files ______________________ 2-25 2.4.4Sample Response File _______________ 2-25 iii Contents __________________________________________________________ CHAPTER 3 VAXELN KMV1A LOAD PROGRAM 3-1 _____________________________________________________ 3.1 LOADING A KMV1A USING KMV_FILE_LOAD 3-2 _____________________________________________________ 3.2 SPECIFYING THE KMV1A TO LOAD 3-2 _____________________________________________________ 3.3 MASTER CLEARING THE KMV1A 3-3 _____________________________________________________ 3.4 SPECIFYING THE KMV1A CONTROL PROGRAM FILE 3-4 _____________________________________________________ 3.5 LOADING THE KMV1A 3-5 _____________________________________________________ 3.6 STARTING THE KMV1A 3-5 _____________________________________________________ 3.7 LOADING ANOTHER KMV1A 3-6 _____________________________________________________ 3.8 LOADING THE DEBUGGER SERVICE MODULE (ODTDSM) 3-6 _____________________________________________________ 3.9 BUILDING KMV_FILE_LOAD INTO VAXELN 3-7 __________________________________________________________ CHAPTER 4 VAXELN KMV1A DUMP PROGRAM 4-1 _____________________________________________________ 4.1 VAXELN DUMP PROGRAM OVERVIEW 4-2 _____________________________________________________ 4.2 DUMP PROCEDURE 4-3 _____________________________________________________ 4.3 BUILDING A VAXELN SYSTEM USING THE DUMP PROGRAM 4-4 _____________________________________________________ 4.4 TRIGGERING A DUMP 4-6 iv Contents _____________________________________________________ 4.5 USING THE DUMP 4-8 __________________________________________________________ CHAPTER 5 KMV1A DEBUGGER 5-1 _____________________________________________________ 5.1 DEBUGGER SERVICE MODULE COMMANDS 5-3 _____________________________________________________ 5.2 SUMMARY OF COMMANDS 5-3 _____________________________________________________ 5.3 ODTDSM COMMAND DESCRIPTIONS 5-5 _____________________________________________________ 5.4 REFERRING TO ADDRESSES 5-5 _____________________________________________________ 5.5 REFERRING TO ODTDSM REGISTERS 5-5 _____________________________________________________ 5.6 RELOCATION REGISTERS 5-6 _____________________________________________________ 5.7 BREAKPOINTS AND WATCHPOINTS 5-7 _____________________________________________________ 5.8 OPEN A MEMORY LOCATION 5-8 _____________________________________________________ 5.9 CLOSE LOCATION 5-8 _____________________________________________________ 5.10 STARTING AND RESUMING EXECUTION 5-10 _____________________________________________________ 5.11 SETTING AND CLEARING BREAKPOINTS AND WATCHPOINTS 5-11 _____________________________________________________ 5.12 SETTING AND CLEARING RELOCATION REGISTERS 5-12 _____________________________________________________ 5.13 ERRORS 5-12 _____________________________________________________ 5.14 ODTDSM INITIALIZATION 5-13 v Contents _____________________________________________________ 5.15 PROGRAM LOADING WITH KMV_FILE_LOAD 5-13 _____________________________________________________ 5.16 LOADING ODTDSM 5-13 _____________________________________________________ 5.17 LOADING THE APPLICATION TO BE DEBUGGED 5-15 _____________________________________________________ 5.18 REMOTEOI FOR ODTDSM 5-15 _____________________________________________________ 5.19 BUILDING ODTDSM INTO THE KMV1A IMAGE 5-17 _____________________________________________________ 5.20 BUILDING KMV1A_ODTDSM_SERVER INTO VAXELN SYSTEMS 5-18 __________________________________________________________ CHAPTER 6 VAXELN-KMV1A-TOOLKIT SOFTWARE INSTALLATION 6-1 _____________________________________________________ 6.1 PREPARING TO INSTALL VAXELN-KMV1A-TOOLKIT 6-1 6.1.1Required Operating System Components _________________________ 6-1 6.1.2Prerequisite Hardware ______________ 6-2 6.1.3License Registration _______________ 6-2 6.1.4Installation Procedure Requirements _ 6-3 6.1.4.1 Time o 6-3 6.1.4.2 Privileges o 6-4 6.1.4.3 Disk Space o 6-4 6.1.4.4 System Parameters o 6-5 6.1.4.5 Process Account Quotas o 6-6 6.1.4.6 VMSINSTAL Requirements o 6-8 6.1.4.7 Backing Up Your System Disk o 6-8 vi Contents _____________________________________________________ 6.2 INSTALLING VAXELN-KMV1A-TOOLKIT 6-10 6.2.1General Information ________________ 6-10 6.2.1.1 Determining the Files Added to the System o 6-10 6.2.1.2 Running the Installation Verification Procedure (IVP) o 6-10 6.2.1.3 Aborting the Installation o 6-11 6.2.2Installation Procedure _____________ 6-12 6.2.2.1 Invoking VMSINSTAL o 6-12 6.2.2.2 Installation Questions o 6-13 6.2.2.3 Informational Messages o 6-21 6.2.2.4 Running the Installation Verification Procedure o 6-23 6.2.2.5 Completing the Installation Procedure o 6-23 6.2.3Error Recovery _____________________ 6-23 _____________________________________________________ 6.3 AFTER INSTALLING VAXELN-KMV1A-TOOLKIT 6-25 6.3.1Editing the System Files ___________ 6-25 6.3.2User Account Requirements __________ 6-25 6.3.2.1 Privileges o 6-25 6.3.2.2 User Account Quotas o 6-25 6.3.3Determining and Reporting Problems _ 6-27 _____________________________________________________ 6.4 INSTALLATION VERIFICATION PROCEDURE 6-29 _____________________________________________________ 6.5 SAMPLE INSTALLATION 6-29 6.5.1Full Development Kit _______________ 6-29 _____________________________________________________ 6.6 INSTALLATION EXAMPLE 6-29 _____________________________________________________ 6.7 FILES AND LOGICAL NAMES INSTALLED ON YOUR SYSTEM 6-36 6.7.1File Names _________________________ 6-36 6.7.2File Names _________________________ 6-36 vii Contents __________________________________________________________ FIGURES 3-1 KMV1A Program Load Configuration ________ 3-1 4-1 KMV1A Program Dump Configuration ________ 4-1 5-1 KMV1A Program Debug Configuration _______ 5-2 __________________________________________________________ TABLES 1-1 KMV1A Control Program Assemble and Link/Task Build Tools (Host Development) _ 1-3 1-2 VAXELN MicroVAX System Image Components _ 1-3 1-3 KMV1A Debugger Support __________________ 1-4 5-1 System Resource Limits to Be Increased __ 5-19 6-1 Disk Space Requirements _________________ 6-4 6-2 Process Account Quotas for the Installing Account _________________________________ 6-6 6-3 User Account Quotas for Using VAXELN-KMV1A-TOOLKIT ____________________ 6-26 viii __________________________________________________________ Preface This document describes the VAXELN-KMV1A-TOOLKIT for VAXELN. __________________________________________________________ Audience This manual is intended for the installer, system level programmer, and user who operates the VAXELN-KMV1A-TOOLKIT. __________________________________________________________ Related Documentation For a more complete description of the KMV1A device, refer to the following documents. KMV1A Programmable Communications Controller Technical Manual KMV1A Programmable Communications Controller User's Guide ix __________________________________________________ 1 VAXELN-KMV1A-TOOLKIT __________________________________________________________ 1.1 KMV1A The KMV1A Programmable Communication Controller is a DCT-11 microprocessor controlled peripheral device designed to operate as part of a Q-bus type computer system such as a PDP-11 or a MicroVAX. To operate a KMV1A, the computer system in which the KMV1A is installed must load a control program into the KMV1A and command its execution. __________________________________________________________ 1.2 KMV1A Control Programs Software for the KMV1A is developed on a host VAX/VMS based computer system containing an installed VAXELN Toolkit product and an installed VMS RSX emulation product. KMV1A control programs are generally written in MACRO-11, assembled, and linked into an RSX11M task image (.EXE file) on the host computer system. This task image is the form in which a KMV1A control program is loaded into a KMV1A. Testing a KMV1A program requires a debugging facility that can monitor and/or control the operation of a program operating in a KMV1A. __________________________________________________________ 1.3 VAXELN KMV1A Tools This manual describes the software that is included in the VAXELN-KMV1A-TOOLKIT. The package includes VAX/VMS DCL command files used to assemble and to link a DCT-11 executable image in MCR compatibility mode on a VAX/VMS host development system for later download and execution in a KMV1A device. In addition several of the toolkit modules support a development mode of execution by inclusion in the task images 1-1 VAXELN-KMV1A-TOOLKIT a remote debugging capability and/or a KMV1A memory updump command capability. A typical hardware configuration would include a VAX host development system with an Ethernet connection to a MicroVAX containing one or more KMV1A devices. Seven of the fourteen toolkit modules will be used on the host development system. Five of the modules will execute in a VAXELN system image on the MicroVAX. The ODTDSM debugger modules will execute in the KMV1A device. 1-2 VAXELN-KMV1A-TOOLKIT The contents of the VAXELN-KMV1A-TOOLKIT are: __________________________________________________________ Table 1-1 KMV1A Control Program Assemble and Link/Task Build Tools (Host Development) __________________________________________________ __________________________________________________ KMV_ELNTOOL$VAXELN_KMVGEN.COM KMV1A Protocol Image Command File KMV_ELNTOOL$KVTOOLMAC.COM MACRO 11 assembly control KMV_ELNTOOL$KVTOOLTKB.COM MACRO 11 task build control KMV_ELNTOOL$KVTOOLDCX.STB KMV1A DCX Symbol Definitions KMV_ELNTOOL$KVTOOLKML.MLB KMV1A DCX Macro Library KMV_ELNTOOL$KVTOOLEND.OBJ KMV1A Assembly Image End Marking __________________________________________________________ __________________________________________________________ Table 1-2 VAXELN MicroVAX System Image Components __________________________________________________ __________________________________________________ KMV_ELNTOOL$KMV_FILE_LOAD.EXE VAXELN KMV1A Stand Alone Loader KMV_ELNTOOL$KMV1A_DUMP.EXE VAXELN KMV1A Dump Program KMV_ELNTOOL$KMV1A_DUMP_PIDD.OBJ VAXELN Dump Descriptor Definitions KMV_ELNTOOL$KMV1A_DUMP_PROC.OBJ VAXELN Application Program Interface for triggering KMV1A dump. __________________________________________________________ 1-3 VAXELN-KMV1A-TOOLKIT __________________________________________________________ Table 1-3 KMV1A Debugger Support __________________________________________________ __________________________________________________ KMV_ELNTOOL$ODTDSM.OBJ KMV1A ODT Debugger Service Module - Linkable Version KMV_ELNTOOL$ODTDSM.EXE KMV1A ODT Debugger Service Module - Load Standalone Version KMV_ELNTOOL$REMOTEOI.EXE VAX/VMS Debugger Remote Interface KMV_ELNTOOL$KMV1A_ODTDSM_SERVER.EXE VAXELN Debugger Communications Server __________________________________________________________ Note The names of the toolkit files have been revised to reflect current naming conventions for this product release. A prefix of "KMV_ELNTOOL$" has been added to the older names. Earlier implementations of user application software will refer to the older names. After installation of this product the user may rename these files back to the earlier names in order to avoid modifications to existing code. For brevity the older file names will be used in the remainder of this manual. 1-4 __________________________________________________ 2 VAXELN KMVTOOL Microcode Application Generation Procedure __________________________________________________________ 2.1 Introduction The VAXELN KMVTOOL Microcode Application Generation Procedure is the DCL command file VAXELN_KMVGEN.COM. The result is a DCT-11 Executable image that runs in a KMV1A device as the selected communications protocol. In detail the DCL command procedure configures the KMV1A application data base, assembles the application code modules, and builds the VAXELN downline loadable microcode image. It runs as a dialogue of queries and user responses at a terminal. Some of the responses are used to build the user- specific data base and to set the KMV1A interrupt vectors. Others responses control parameters that are used to build MCR Indirect Command Files. The MVR files will be executed in RSX Compatibility Mode to assemble and task build the KMV1A communications protocol. RSX is a VAX/VMS layered product which must be present in order to build a KMV1A protocol image. VAXELN_KMVGEN.COM will reference five other toolkit files. These files have the string 'KVTOOL' as part of their name in the form "KVTOOLxxx.xxx". Normally the user will not directly reference these five files as part of his toolkit usage. 2-1 VAXELN KMVTOOL Microcode Application Generation Procedure __________________________________________________________ 2.2 Running VAXELN_KMVGEN To start VAXELN_KMVGEN, the user should type the following command at the $ prompt: $ @SYS$DEVICE:[ELN.KMV$]VAXELN_KMVGEN VAXELN_KMVGEN will begin with the first of its seven parts. 1 Introduction Instructions, notes and cautions about running VAXELN_KMVGEN.COM are presented. The user is asked if the responses should be saved in a response file may be as the response input file at a future session. A chance is provided to name an existing response input file for use during this session. A response file consists of the user reply for each VAXELN_KMVGEN.COM question. Naming an existing response file avoids lengthy keyboard input during repeat executions of VAXELN_KMVGEN.COM. Response files can be edited to make simple changes to the key parameters of the communications protocol image to be built. An example response file is provided later. 2-2 VAXELN KMVTOOL Microcode Application Generation Procedure 2 Process Definition A file KVTOOLTBL.MAC is created and opened. User responses provided during the next several parts of VAXELN_KMVGEN are processed to form parameters of MACRO-11 macro calls which are written to KVTOOLTBL.MAC. This file then becomes part of the communications protocol assembly/task build for a KMV1A executable. Other information is requested for use to build the process descriptor vectors. Processes are identified by name, type, priority, and timer support requirement. For LLC processes, each channel is identified by its corresponding system line number and optional station number. 3 System Line Definition The DDM process and DLC process defining each system line are identified. 4 Channel Definition Tables mapping system lines to logical channels are built from the query information entered in the preceding two sections. 5 System Resource Definition System buffers are defined as Communication Control Blocks (CCB), Receive Data Buffers (RDB), and Large Data Buffers (LDB). See the 'Guide to Writing Comm/Exec Process Manual' for buffer management details. A query requests the count, length, and failure threshold of CCB's, RDB's, and LDB's to be built into the respective buffer pools. Parameters defining the short and long clock ticks for timer control are also requested. 6 Interrupt Vector Definition The address of routines in the KMV1A image that handle interrupts from the host, the Multi-Port Serial Controller (MPSC) and the real-time clock are requested. This completes the information needed for KMTOOLTBL.MAC and the file is closed. 2-3 VAXELN KMVTOOL Microcode Application Generation Procedure 7 Command File Generation Two command procedures are built: KVTOOLMAC.CMD and KVTOOLTKB.CMD Note the distinction from the two corresponding toolkit files with '.COM' extensions. The two '.CMD' files that are built run under RSX Compatibility Mode. KVTOOLMAC.CMD will invoke the VAX-11 RSX Macro Assembler to perform the assemblies. The user is asked to provide the names of all the source modules to be assembled. These module names are referenced in KVTOOLMAC.CMD. 2-4 VAXELN KMVTOOL Microcode Application Generation Procedure KVTOOLTKB.CMD will invoke the VAX-11 RSX Task Builder to build the downline loadable image. A request is made to provide the names of all the object modules to be included in the task build. The next request asks if the ODT Debugger server module (ODTDSM) should be included in the task image. Finally, the user is asked if the assembly command file and the task build command file should be run at this time. If the user chooses not to do this, the assembly and task build command files can be run at later time, by typing: DEFINE KMVTOOL SYS$SYSDEVICE[ELN.KMV$] @KVTOOLMAC and @KVTOOLTKB The above command files are the toolkit VAX/VMS '.COM' versions. The resulting microcode image will be identifiable by the user assigned filename and the default filetype of '.EXE' for KMV1A executable microcode. __________________________________________________________ 2.3 VAXELN_KMVGEN Questions and Explanations At the start of the VAXELN_KMVGEN procedure, the user is asked whether or not the long explanations should be displayed with each VAXELN_KMVGEN query. If the reply is yes, long explanations are always provided. If no, entering the " ? " key after any query will display the long explanation for that query. The use of long explanations are recommended initially to become familiar with the VAXELN_KMVGEN.COM procedure. 2-5 VAXELN KMVTOOL Microcode Application Generation Procedure The following is a list of each query and its explanation: VAXELN KMV1A MICROCODE APPLICATION GENERATION PROCEDURE Welcome to VAXELN_KMVGEN! You will be asked many questions... - Press the return key to give the default answer for a question. For YES/NO questions the default is always "NO". - Press the ^ key (shift 6) to see a more complete explanation and have the question repeated. - Press at any time to close all open files and exit. 2-6 VAXELN KMVTOOL Microcode Application Generation Procedure Welcome to VAXELN_KMVGEN! 1-1. Do you wish to see the long explanation for each question? The Notes/Cautions describe the prerequisite conditions for starting the VAXELN_KMVGEN procedure. 1-2. Do you wish to see the VAXELN_KMVGEN Notes/Cautions? " VAXELN_KMVGEN Notes and Cautions -------------------------------- Your current default is the source and output area. It is recommended that you make a copy of this area before continuing. Command files and data files will be written to the default area during the VAXELN_KMVGEN procedure. To execute the command files produced by the VAXELN_KMVGEN procedure, the VAX-11 RSX Compatibility Mode product must be installed on this system. Also, the following files must reside in the SYS$SYSDEVICE:[ELN.KMV$] directory: - KVTOOLKML.MLB, a macro library - KVTOOLDCX.STB, the DCX Communications Executive symbol table - ODTDSM.OBJ, the Debug Microcode object file. - KVTOOLEND.OBJ, the symbol marking the end of user code area You can create a Response File to save your answers to the VAXELN_KMVGEN questions. This Response File can be run during a subsequent VAXELN_KMVGEN session to automatically answer each question. If you wish to save your responses, enter a filename. 1-3. Name of optional Response File to save user responses: 2-7 VAXELN KMVTOOL Microcode Application Generation Procedure If you wish to use a response file containing the answers you saved from a previous VAXELN_KMVGEN session, enter the filename. The remainder of this session will proceed automatically. 1-4. Name of optional Response File to provide responses: PART 2 - PROCESS DEFINITION Specify the number of processes you have in your application microcode. Include the AUX process in the count if you intend to use it. 2-8 VAXELN KMVTOOL Microcode Application Generation Procedure 2-1. How many processes does your application contain? [1-64.]: Answer "YES" if you want to include the AUX process in your application. 2-2. Do you want to include the AUX process as process 0? Specify the process name. It must be a three-character alphanumeric string. 2-3. Name of process number [3 characters]: Specify the scheduling priority of the process. If this process is a DDM or a DDM combination, you have to take into account the hardware priority of the device handled by this process. 2-4. process scheduling priority [0-7]: Answer "YES" if the corresponding process requires timer support. For LLC processes, this will set a timer flag in the process' PDV, and the process will be scheduled at its timeout entry point at the end of every long timer interval. For DLC or DDM processes, this will set a timer flag in the system line table of each system line controlled by that process. The process will be scheduled at its timeout entry point at the expiration of the timer located in the process line table. Refer to the 'KMV1A Programmable Communications Controller User's Guide' for more information. 2-5. Does the process require timer support? Specify the process type: DDM, DLC, LLC, DDM/DLC, or DDM/DLC/LLC. 2-9 VAXELN KMVTOOL Microcode Application Generation Procedure 2-6. process type [DDM, DLC, LLC, DDM/DLC, DDM/DLC/LLC]: Specify the number of logical channels handle by this LLC process. Do not count LLC-to-LLC pathways as logical channels. 2-7. How many logical channels does process handle? [0-255.]: For each channel, please define the corresponding system line number. 2-10 VAXELN KMVTOOL Microcode Application Generation Procedure 2-8. System line number for channel [0-5]: Answer "YES" if the system line is a multipoint line. 2-9. Is the system line a multipoint line? Multipoint - specify the number of stations on the system line that are controlled by this LLC. 2-10. Specify the number of stations on system line [0 - 127.]:" PART 3 - SYSTEM LINES DEFINITION Specify the total number of system lines handled by the application. A KMV application may have from 1 to 6 system lines: - one or two for host Q-BUS interface via the CSR registers (not needed if Controlling process is DDM/DLC/LLC) - one or two for host Q-BUS interface via the DMA registers (not needed if controlling process is DDM/DLC/LLC) - one or two for communications line interface via the MPSC PUSART Use two system lines per DDM process if you wish to differentiate between incoming and outgoing traffic. Use one if you don't need this distinction. 3-1. Number of system lines [1-6]: Specify the name of the DDM process that handles the system line. 3-2. Name of DDM process handling line [3 characters]: 2-11 VAXELN KMVTOOL Microcode Application Generation Procedure Specify the name of the DLC process that handles this system line. It can be the same as the DDM for a DDM/DLC combination. 3-3. Name of DLC process handling line [3 characters]: PART 4 - CHANNEL DEFINITION The data table to map system lines and stations to processes and channels is being built from information supplied above. 2-12 VAXELN KMVTOOL Microcode Application Generation Procedure PART 5 - SYSTEM RESOURCE DEFINITION Specify the number of CCBs to be reserved in the pool area, excluding the CCBs associated with each RDB. 5-1. Number of CCBs [default = 25]: Specify the CCB size in bytes. The minimum required is 28. bytes; the default is 40. bytes. 5-2. CCB size in bytes [minimum = 28., default = 40.]: Specify the number of RDBs/LDBs to be reserved in the pool area. 5-3. Number of RDBs/LDBs [default = 10.]: Specify the RDB size in bytes. This does not include the CCB header portion. 5-4. RDB/LDB size in bytes [default = 132.]: Specify the LDB allocation failure threshold. Requests for LDB allocation will fail when this number or less buffers remain in the RDB/LDB pool. 5-5. LDB allocation failure threshold [default = 2.]: Answer "YES" if you want to use the on-board Real Time Clock. 5-6. Do you want to use the Real Time Clock? Specify the real time clock divider you have calculated in order to enter the clock interrupt routine at the desired frequency. This value determines the short timer tick. 5-7. Real Time Clock divider value [1 - 32768., default = 2700.]: 2-13 VAXELN KMVTOOL Microcode Application Generation Procedure Specify the long timer counter value, defined as follows: In the DCX clock interrupt routine, this value multiplied by the short timer tick gives the long timer value. In a user-written clock interrupt routine, the definition is left to the user. 5-8. Long Timer Counter value [1 - 255., default = 20.]: 2-14 VAXELN KMVTOOL Microcode Application Generation Procedure PART 6 - INTERRUPT VECTOR INITIALIZATION Specify the interrupt routine entry point corresponding to the BSEL0 interrupt. Any host write access to BSEL0 will generate an interrupt to the KMV1A microprocessor if you have enabled this capability. 6-1. Routine to handle BSEL0 interrupts: Specify the interrupt routine entry point corresponding to the BSEL2 interrupt. Any host write access to BSEL2 will generate an interrupt to the KMV1A microprocessor if you have enabled this capability. 6-2. Routine to handle BSEL2 interrupts: Specify the interrupt routine entry point corresponding to the Receive Data Available interrupt for the MPSC line A. 6-3. Routine to handle Line A Receive interrupts: Specify the interrupt routine entry point corresponding to the Transmit Buffer Empty interrupt for the MPSC line A. 6-4. Routine to handle Line A Transmit interrupts: Specify the interrupt routine entry point corresponding to the MPSC Special Conditions interrupt. 6-5. Routine to handle MPSC Special Conditions interrupts: Answer "YES" if you want to use the DCX firmware clock routine. Answer "NO" if you are providing your own microcode clock routine. 6-6. Are you using the DCX firmware clock routine? " 2-15 VAXELN KMVTOOL Microcode Application Generation Procedure Specify the Real Time Clock interrupt routine entry point. 6-7. Routine to handle Real Time Clock interrupts: " PART 7 - COMMAND FILE GENERATION Command file to assemble the modules: KVTOOLMAC.COM Using the data file: KVTOOLMAC.CMD Answer "YES" if you want a cross-reference listing with each assembly. 2-16 VAXELN KMVTOOL Microcode Application Generation Procedure 7-1. Do you want a cross-reference listing Specify the filename, but not the filetype, for each .MAC file to be assembled. Hitting a carriage return after entering one or more filenames will cause a single assembly to be set up for those files. Question 7-2 will then be repeated, allowing you to enter the names of the next file or files to be assembled. Hitting a carriage return without entering any filenames will let you proceed to the next question. 7-2. Name of .MAC file to assemble: Command file to task build the modules: KVTOOLTKB.COM Using the data file KVTOOLTKB.CMD You may enter the name of the microcode task image to be built. A default filetype of .TSK is provided. 7-3. Name of .TSK file to be built: Answer "YES" if you want a global cross-reference listing with the task build. 7-4. Do you want a global cross-reference? Specify the filename, but not the filetype, for each OBJECT file to be included in the task build. The default file extension must be .OBJ. The System Tables module KVTOOLTBL.OBJ is already included. Use only VAX-11 RSX notation. 7-5. Name of .OBJ file to include: ODTDSM is the VAXELN KMV1A on-line debug module. 7-6. Do you want to include KDT in your system? Use the command file KVTOOLMAC.COM to assemble the modules for the KMV1A microcode. 2-17 VAXELN KMVTOOL Microcode Application Generation Procedure 7-7. Do you want to assemble your files at this time? $ MCR MAC @KVTOOLMAC.CMD $ SET NOVERIFY When all modules are assembled, use the command file KVTOOLTKB.COM to task build the KMV1A microcode. The output of the task build procedure is the downline- loadable microcode task image. 7-8. Do you want to task build the microcode at this time? " $ MCR TKB @KVTOOLTKB.CMD $ SET NOVERIFY End of VAXELN_KMVGEN __________________________________________________________ 2.4 VAXELN_KMVGEN Samples _____________________________ 2.4.1 Sample VAXELN_KMVGEN Run The Demonstration Microcode consists of five microcode processes plus KMV1A MicroVMS Tools User's the AUX process, as described in the KMV1A MicroVMS Tools User's Guide. Here is the VAXELN_ KMVGEN run that generates the Demonstration Microcode: VAXELN KMV1A MICROCODE APPLICATION GENERATION PROCEDURE Welcome to VAXELN_KMVGEN! You will be asked many questions... - Press the return key to give the default answer for a question. For YES/NO questions the default is always "NO". 2-18 VAXELN KMVTOOL Microcode Application Generation Procedure - Press the ^ key (shift 6) to see a more complete explanation and have the question repeated. - Press at any time to close all open files and exit. VAXELN KMV1A MICROCODE APPLICATION GENERATION PROCEDURE Welcome to VAXELN_KMVGEN! 1-1. Do you wish to see the long explanation for each question? N 1-2. Do you wish to see the VAXELN_KMVGEN Notes/Cautions? N 1-3. Name of optional Response File to save user responses: TESTY 1-4. Name of optional Response File to provide responses: 2-19 VAXELN KMVTOOL Microcode Application Generation Procedure PART 2 - PROCESS DEFINITION 2-1. How many processes does your application contain? [1-64.]: 3 2-2. Do you want to include the AUX process as process 0? Y 2-3. Name of process number 1 [3 characters]: CSR 2-4. CSR process scheduling priority [0-7]: 4 2-5. Does the CSR process require timer support? N 2-6. CSR process type [DDM, DLC, LLC, DDM/DLC, DDM/DLC/LLC]: DDM/DLC/LLC 2-7. How many logical channels does CSR process handle? [0-255.]: 0 2-3. Name of process number 2 [3 characters]: DMA 2-4. DMA process scheduling priority [0-7]: 4 2-5. Does the DMA process require timer support? N 2-6. DMA process type [DDM, DLC, LLC, DDM/DLC, DDM/DLC/LLC]: DDM/DLC/LLC 2-7. How many logical channels does DMA process handle? [0-255.]: 0 2-3. Name of process number 3 [3 characters]: CHK 2-4. CHK process scheduling priority [0-7]: 0 2-5. Does the CHK process require timer support? N 2-6. CHK process type [DDM, DLC, LLC, DDM/DLC, DDM/DLC/LLC]: LLC 2-7. How many logical channels does CHK process handle? [0-255.]: 1 2-8. System line number for channel 0 [0-5]: 0 2-20 VAXELN KMVTOOL Microcode Application Generation Procedure 2-9. Is the system line 0 a multipoint line? N PART 3 - SYSTEM LINES DEFINITION 3-1. Number of system lines [1-6]: 1 3-2. Name of DDM process handling line 0 [3 characters]: LIN 3-3. Name of DLC process handling line 0 [3 characters]: MOD 2-21 VAXELN KMVTOOL Microcode Application Generation Procedure PART 4 - CHANNEL DEFINITION The data table to map system lines and stations to processes and channels is being built from information supplied above. PART 5 - SYSTEM RESOURCE DEFINITION 5-1. Number of CCBs [default = 25.]: 25 5-2. CCB size in bytes [minimum = 28., default = 40.]: 40 5-3. Number of RDBs/LDBs [default = 10.]: 12 5-4. RDB/LDB size in bytes [default = 132.]: 128 5-5. LDB allocation failure threshold [default = 2.]: 2 5-6. Do you want to use the Real Time Clock? Y 5-7. Real Time Clock divider value [1 - 32768., default = 2700.]: 2700 5-8. Long Timer Counter value [1 - 255., default = 20.]: 20 PART 6 - INTERRUPT VECTOR INITIALIZATION 6-1. Routine to handle BSEL0 interrupts: $CSRQI 6-2. Routine to handle BSEL2 interrupts: $CSRDY 6-3. Routine to handle Line A Receive interrupts: $LNRXA 6-4. Routine to handle Line A Transmit interrupts: $LNTXA 6-5. Routine to handle MPSC Special Conditions interrupts: $LNSPC 6-6. Are you using the DCX firmware clock routine? Y 6-7. Routine to handle Real Time Clock interrupts: $CKINT 2-22 VAXELN KMVTOOL Microcode Application Generation Procedure PART 7 - KMV1A COMMAND FILE GENERATION 7-1. Do you want a cross-reference listing? Y 7-2. Name of .MAC file to assemble: RM9CSR 7-2. Name of .MAC file to assemble: RM9DMA 7-2. Name of .MAC file to assemble: RM9CHK 7-2. Name of .MAC file to assemble: 7-3. Name of .EXE file to be built [default = KMV]: KVTOOLEXM 7-4. Do you want a global cross- reference listing? Y 7-5. Name of .OBJ file to include: RM9CSR 7-5. Name of .OBJ file to include: RM9DMA 7-5. Name of .OBJ file to include: RM9CHK 7-5. Name of .OBJ file to include: 7-6. Do you want to include ODTDSM in your system? Y 7-7. Do you want to assemble your files at this time? N 7-8. Do you want to task build the microcode at this time? N End of VAXELN_KMVGEN _____________________________ 2.4.2 Sample Data Tables Module The following is the MACRO-11 source module created by the sample run of VAXELN_KMVGEN above. When KVTOOLMAC.COM is run, the macro calls are assembled against the KVTOOLKML macro library and the hardware and software definitions files. 2-23 VAXELN KMVTOOL Microcode Application Generation Procedure .TITLE KVTTBL.MAC ; DCX Data Tables .LIST ME .MCALL SYSDF$, STDRD$ SYSDF$ SYDRD$ .NLIST ME .LIST MEB .BLKB 340 ; Reserve low memory .PAGE .SBTTL Process Descriptor Vectors ; PDVGN$ AUX,0,0,ZF.LLC PDVGN$ CSR,4,0,ZF.DDM!ZF.DLC!ZF.LLC!ZF.TIM PDVGN$ DMA,4,0,ZF.DDM!ZF.DLC!ZF.LLC PDVGN$ CHK,0,1,ZF.LLC LLCLT$ 0,0 .PAGE .SBTTL PDV Address Table ; $PDVTB:: AUXIDX==.-$PDVTB ; PDV index .WORD AUXPDV ; Addr table entry CSRIDX==.-$PDVTB ; PDV index .WORD CSRPDV ; Addr table entry DMAIDX==.-$PDVTB ; PDV index .WORD DMAPDV ; Addr table entry CHKIDX==.-$PDVTB ; PDV index .WORD CHKPDV ; Addr table entry .PAGE .SBTTL System Line Address Table ; $SLTMB: .WORD SLT0 .WORD SLT1 SLTGN$ 0,2,2,$HDITB,$HDITB,LF.ACT!LF.RDY SLTGN$ 1,10,8,$LINTB,$DMATB,LF.ACT!LF.RDY!LF.TIM 2-24 VAXELN KMVTOOL Microcode Application Generation Procedure .PAGE .SBTTL Reverse Mapping Table ; $LLCTB: RVSBY$ 0,4 RVSBY$ 1,6 DCXTP$ 6,2,20,46,14,302,2,2700,100 VCTGN$ 200,RQI.IN,$RDY.IO,$LNRXA,,$LNTXA,,$LNSPC,$CKINT .END _____________________________ 2.4.3 Sample VAX-11 RSX Task Builder Command Files The task build command procedure created by VAXELN_KMVGEN is named KVTOOLTKB.COM. When it is executed, it will pass the user's object files to the VAX-11 RSX task builder. It also includes the data tables module, KLTOOLTBL.OBJ and other toolkit modules resident in: SYS$SYSDEVICE:[ELN.KMV$] _____________________________ 2.4.4 Sample Response File In the sample VAXELN_KMVGEN run, the user replied that a response file named TESTY was to be created to capture all responses to Parts 2 - 7 of VAXELN_KMVGEN. Below is the resulting file, TESTY.DAT. On a subsequent run of VAXELN_KMVGEN, the user can specify that VAXELN_KMVGEN read responses from the file TESTY. VAXELN_KMVGEN will open the file and as each VAXELN_KMVGEN question is encountered, a line will be read from the file. The reply will be extracted from the file and used in place of a response from the terminal. 2-25 VAXELN KMVTOOL Microcode Application Generation Procedure 2-1 !3 2-2 !Y 2-3 !CSR 2-4 !4 2-5 !N 2-6 !DDM/DLC/LLC 2-7 !0 2-3 !DMA 2-4 !4 2-5 !N 2-6 !DDM/DLC/LLC 2-7 !0 2-3 !CHK 2-4 !0 2-5 !N 2-6 !LLC 2-7 !1 2-8 !0 2-9 !N 3-1 !1 3-2 !LIN 3-3 !MOD 5-1 !25 5-2 !40 5-3 !12 5-4 !128 5-5 !2 5-6 !Y 5-7 !2700 5-8 !20 6-1 !$CSRQI 6-2 !$CSRDY 6-3 !$LNRXA 6-4 !$LNTXA 6-5 !$LNSPC 6-6 !N 6-7 !$CKINT 7-1 !Y 7-2 !RM9CSR 7-2 !RM9DMA 7-2 !RM9CHK 7-2 ! 7-3 !KVTOOLEXM 2-26 VAXELN KMVTOOL Microcode Application Generation Procedure 7-4 !Y 7-5 !RM9CSR 7-5 !RM9DMA 7-5 !RM9CHK 7-5 ! 7-6 !Y 7-7 !N 7-8 !N 2-27 __________________________________________________ 3 VAXELN KMV1A Load Program The KMV_FILE_LOAD program loads ODTDSM and micro- code to be debugged into the KMV1A. This would allow testing of the KMV1A code when the VAXELN MicroVAX software that is intended to work in conjunction with KMV1A code is not sufficiently developed to communicate across the QBUS. In a MicroVAX VAXELN environment, a KMV1A program is normally loaded into the KMV1A and controlled by the MicroVAX VAXELN application program. However, when testing a newly created KMV1A protocol it may be desirable to test/debug part of the KMV1A code as a separate effort before attempting communication across the QBUS. The VAXELN KMV1A Load Program provides an alternative means of loading a program image (.EXE file) into a KMV1A. Figure 3-1 shows the KMV1A program load configuration. __________________________________________________________ Figure 3-1 KMV1A Program Load Configuration __________________________________________________________ +-------------------+ +------------------------------------------+ | | | MicroVAX | | KMV1A | | VAX/VMS | | -------- |Q| ----- | | or | DECNet | |B| ODTDSM | | MicroVAX/ |-----------| VAXELN System |U| | | MicroVMS | Ethernet | |S| Control | | | | KMV_LOAD_FILE | | Test Image | ________+-------------------+___________+------------------------------------------+ 3-1 VAXELN KMV1A Load Program __________________________________________________________ 3.1 Loading a KMV1A Using KMV_FILE_LOAD KMV_FILE_LOAD can read a KMV1A program image from a either a host computer system through DECNet /Ethernet or a local VAXELN mass storage device. Once the file is open, it loads the task image into the KMV1A. __________________________________________________________ 3.2 Specifying the KMV1A to Load When the program begins to execute, it will prompt for the name of a KMV1A to load. This name must be the same as that specified during the EBUILD for the VAXELN system. Suggested naming for KMV1As are "KVxy" where: o "KV" - is the device type identifier for a KMV1A o x - is a letter indicating the controller number (A for zero, B for one,... H for seven) o y - is the number zero For example KVA0, KVB0 and so on. The prompt is as follows: Enter KMV1A device to load: When the device name has been entered, the program will try to access the KMV1A. If it cannot access it (through a VAXELNCREATEDEVICE), it will respond with the following error message: Error on device KVxy "vaxeln error message" Where: "vaxeln error message" is the error message text for a VAXELN error or the error code number in hex if the program could not access the error message file. If this message is displayed, the program will reprompt for device name. If a is typed in response to this prompt, the program will exit. 3-2 VAXELN KMV1A Load Program __________________________________________________________ 3.3 Master Clearing the KMV1A The next prompt will ask whether or not the KMV1A should be master cleared. A master clear stops any program currently running in the KMV1A or recovers from a run away program. In any case when you wish to load the first program into the KMV1A, you should request a master clear. The prompt is: Do you want to master clear KVxy ? [Y/N]: Where: "KVxy" is the name of the KMV1A as entered in the previous step. You should answer Y (yes) or N (no). If you are loading a KMV1A program and you have not already loaded a debugger (ODTDSM), you should answer Y. This will stop what ever is running in the KMV1A and prepare it to receive your program. If you are loading the standalone debugger ODTDSM, you should also answer Y. This will allow control to be passed to the debugger after it is loaded. The debugger has code which allows it to emulate the ROM loader on the KMV1A after it is loaded. This allows ODTDSM to load programs to be debugged under its control. If you are loading your KMV1A program and the debugger has just been loaded, you should answer N. This will allow the debugger to retain control and load you program under its control while it cooperates with the KMV1AFILELOAD program in the MicroVAX. 3-3 VAXELN KMV1A Load Program __________________________________________________________ 3.4 Specifying the KMV1A Control Program File Next KMV_FILE_LOAD prompts for the name of the file which you wish to load into the KMV1A. This must be a fully qualified name including node address (areanumber.nodenumber), device name, directory, file name, and file type. There are no defaults for any of these. The prompt is: Enter file name: input should be of the form: node_number::device_name:[directory]filename.type The program will try to access the file and copy it from its source to the MicroVAX memory. The file must have WORLD-READ, -WRITE, and -EXECUTE access, otherwise you will get access errors and not be able to load it. If it cannot access the file, an error message will be displayed, and the program will reprompt for a valid name. Open error on "filename" "vaxeln error message" Where: - "filename" is the name of the file as entered in the previous step. - "vaxeln error message" is an error message from the VAXELN system error message file or the hex code for the error message if the message file cannot be accessed. 3-4 VAXELN KMV1A Load Program __________________________________________________________ 3.5 Loading the KMV1A Once the file is opened, the load program will read the KMV1A control program record-by-record, load it into the KMV1A, read it back from the KMV1A and verify what was written is in the KMV1A memory. If an error occurs during the file transfer or verify, the following error messages may be displayed: "Hardware timeout loading KVxy" The KMV1A has a hardware problem and timed out. The timeout is really a program loop which lasts about 20 milliseconds-per-word to be loaded into the KMV1A. "Compare error loading micro-code in KVxy" The data written to the KMV1A is not the same as was read back during the compare phase. __________________________________________________________ 3.6 Starting the KMV1A If the KMV1A program is loaded correctly, the next message and prompt will appear: KVxy loaded successfully Do you want to start KVxy ? [Y/N]: Where: "KVxy" is the name of the KMV1A as entered above. You may turn control of the KMV1A over to the program you just loaded by answering Y to the prompt. This passes control from the KMV1A ROM loader (or ODTDSM) to the program just loaded into the KMV1A. When the KMV1A is started the following message will appear: KVxy started successfully 3-5 VAXELN KMV1A Load Program __________________________________________________________ 3.7 Loading Another KMV1A The load program will recycle and prompt for another KMV1A to load. This process will continue until you press in response to the device name prompt. __________________________________________________________ 3.8 Loading the Debugger Service Module (ODTDSM) If you are loading the stand-alone version of a Debugger Service Module (ODTDSM), you should load it into the KMV1A before the program you wish to debug. The debugger service module takes over from the ROM loader and can load the program to be debugged just like the ROM loader. However, you must make sure that you answer "N" to the question: Do you want to master clear KVxy ? [Y/N]: when you load the program to be debugged. Otherwise, the debugger service module will be aborted and control will be passed back to the ROM loader. 3-6 VAXELN KMV1A Load Program __________________________________________________________ 3.9 Building KMV_FILE_LOAD into VAXELN In order to use KMV_FILE_LOAD in a VAXELN system ,you must run the EBUILD utility and specify that you want the program included. Below are the parameters you should specify to EBUILD: Program KMV_FILE_LOAD Debug No Run Yes Init Required No Mode Kernel Kernel Stack 16 Job Priority 8 The actual value you enter for Job Priority depends on the priorities of other programs in your system. The main point to consider is that KMV_FILE_LOAD is given a high enough priority to be able to start running and load the KMV1A. After it has finished loading all the requested KMV1A programs, it will exit and will no longer be competing for resources. You will have to increase some system resource limits when including KMV_FILE_LOAD in you system. These resources are cumulative, and you will have to calculate all the resources for all your applications and the KMV tool programs in your VAXELN system. Listed below are the suggested increases: Ports +1 Page Table Slots +4 Pool +4 3-7 __________________________________________________ 4 VAXELN KMV1A Dump Program The VAXELN-KMV1A-TOOLKIT provides the software that enables a program call in a user application routine to halt the operation of a KMV1A and up- dump the 32K RAM memory to a designated file in the Host Development system. The DUMP program must first be included through EBUILD into the VAXELN application system. The calling sequence would be included within the application routine. The VAXELN-KMV1A-TOOLKIT includes three files used to support this service: KMV1A_DUMP.EXE Main Dump processing KMV1A_DUMP_PROC.OBJ Interface to trigger Dump KMV1A_DUMP_PIDD.OBJ Interface Descriptor Definitions Figure 4-1 shows the KMV1A program dump configuration. __________________________________________________________ Figure 4-1 KMV1A Program Dump Configuration __________________________________________________________ +-------------------+ +------------------------------------------+ | | | MicroVAX - VAXELN | | KMV1A | | VAX/VMS | | ----------------- |Q| ----- | | or | DECNet | KMV1A_DUMP.EXE |B| | | MicroVAX/ |-----------| KMV1A_DUMP_PROC.OBJ |U|Communications| | MicroVMS | Ethernet | KMV1A_DUMP_PIDD.OBJ |S| Protocol | | | | | | Image | +-------------------+ +------------------------------------------+ __________________________________________________________ 4-1 VAXELN KMV1A Dump Program __________________________________________________________ 4.1 VAXELN Dump Program Overview The VAXELN Dump Program operates as part of a VAXELN system in a MicroVAX. The dump program will receive a service request from an application program in the VAXELN system. At such time the dump program master clears the KMV1A specified in the service request, reads the contents of KMV1A read/write memory, first into the MicroVAX memory, and then into a file located on the host VAX/VMS system. When the dump operation is completed, the file will contain an exact binary copy of 32K of KMV1A memory. This file may be examined using the standard VAX/VMS Dump utility, however the RSX compatibility mode DMP utility is recommended. 4-2 VAXELN KMV1A Dump Program __________________________________________________________ 4.2 Dump Procedure To provide an easy-to-use interface between VAXELN application programs and the Dump Program, the VAXELN-KMV1A-TOOLKIT includes a procedure KMV1A_DUMP_PROC.OBJ. When invoked by a VAXELN application program and supplied with a device name string, a file name string, and two status variables, this program send a Dump service request to the Dump Program. The procedure returns two status values indicating the status of the dump and the updumped file. This procedure is called DUMPKMV1A and its Pascal declaration heading is: PROCEDURE DUMP_KMV1A (KMV1A_NAME : VARYING_STRING(30) ; filename : VARYING_STRING(64) ; status : INTEGER ; eln_status : INTEGER ); The status values returned by the Dump Program are listed below. CONST KMV$_Dump_Successful = %XC001 ; KMV$_Dump_Dev_access_Error = %XC002 ; KMV$_Dump_Bad_Srv_Req_Fmt = %XC004 ; KMV$_Dump_Unrec_Srv_Req_Op = %XC006 ; KMV$_Dump_No_VAXELN_Resources = %XC008 ; KMV$_Dump_VAXELN_Problem = %XC00A ; KMV$_Dump_Incomplete = %XC00C ; KMV$_Dump_Dev_Problem = %XC00E ; KMV$_Dump_No_Dump_Seerver = %XC010 ; KMV$_Dump_Dump_Server_Busy = %XC012 ; KMV$_Dump_Server_Problem = %XC014 ; KMV$_Dump_File_Open_Error = %XC016 ; KMV$_Dump_File_Protect_Error = %XC018 ; The elnstatus values are VAXELN status codes and are valid only if the status value is not "success." 4-3 VAXELN KMV1A Dump Program __________________________________________________________ 4.3 Building a VAXELN System Using the Dump Program In the example command file shown below, APPLICATION.PAS is compiled, linked, and Ebuilt into an ELNDUMP.SYS. Other documentation is available to explain these VAXELN procedures, however for completeness an example APPLICATION.COM is shown. Particularly note the use of KMV1A_DUMP_PIDD.OBJ, KMV1A_DUMP_PROC.OBJ, and KMV1ADUMP.EXE file references in the compile and link procedures to support a user application call to up-dump KMV1A memory at execution time. The Ebuild procedure will create an ELNDUMP.SYS for download into a MicroVAX hosting a KMV1A device. Example: APPLICATION.COM $ ! $ ! Compile, Link, & Ebuild APPLICATION.PAS (VAXELN) $ ! Include KMV1A_DUMP and create ELNDUMP.SYS $ ! $ SET VERIFY $ ! $ VTP := NAME.KMV_LIB $ ! $ EPAS/DEB=(IMPORT_TOO)/LIST/INC=($KMV_UTILITY,$KMV_DMADATA,- APPLICATION+SYS$SYSDEVICE:[ELN.KMV$]KMV1A_DUMP_PIDD/MOD+ - KMV1A_DUMP_PROC/MOD+ - ['VTP']CSSKMVRTL/LIB+ELN$:RTLOBJECT/LIB+ELN$:RTL/LIB $ ! $ LINK/DEBUG/MAP/FULL APPLICATION.OBJ+['VTP']CSSKMVRTL/LIB+ - SYS$SYSDEVICE:[ELN.KMV$]KMV1A_DUMP_PIDD+KMV1A_DUMP_PROC+ - ELN$:RTLSHARE/LIB+ELN$:RTL/LIB/inc=(eln$msgdef_text) $ ! $ ! $ EBUILD/NOEDIT ELNDUMP.DAT $ SET PROT=(W:RWE) ELNDUMP.SYS $ ! $ ! $ EXIT Here is an example ELNDUMP.DAT: 4-4 VAXELN KMV1A Dump Program characteristic /connect_time=100 /objects=1024 /jobs=128 /subprocesses=128 - /ports=257 /p0_virtual_size=4992 /p1_virtual_size=512 /interrupt_stack=32 program APPLICATION /DEBUG /kernel_stack=32 /user_stack=8 program KMV1ADRIVER /initialize /kernel_stack=34 /mode=kernel /job_priority=4 program SYS$SYSDEVICE:[ELN.KMV$]KMV1A_DUMP.EXE /kernel_stack=16 - /initialize /mode=kernel /job_priority=8 device KVA0 /register=%O760420 /vector=%O310 /priority=4 /noautoload device KVB0 /register=%O760440 /vector=%O320 /priority=4 /noautoload device KVC0 /register=%O760460 /vector=%O330 /priority=4 /noautoload device KVD0 /register=%O760500 /vector=%O340 /priority=4 /noautoload device KVE0 /register=%O760520 /vector=%O350 /priority=4 /noautoload device KVF0 /register=%O760540 /vector=%O360 /priority=4 /noautoload device KVG0 /register=%O760560 /vector=%O370 /priority=4 /noautoload device KVH0 /register=%O760600 /vector=%O400 /priority=4 /noautoload terminal CONSOLE /nohardcopy 4-5 VAXELN KMV1A Dump Program The Dump Program if built under Edit Mode in VAXELN should be specified to EBuild as follows: Program KMV1A_DUMP Debug No Run Yes Init Required Yes Mode Kernel Kernel Stack 16 Job Priority 4 When editing the System Characteristics, some system resource limits must be increased. The increases are listed below. Ports +1 Page Table Slots +2 Pool +9 __________________________________________________________ 4.4 Triggering a Dump The dump must be triggered by the VAXELN application program. Code must be inserted in the application program to call the KMV1A_DUMP_ PROC procedure. The timing of the call is at user discretion. It would be anticipated that such a call would be made from an error branch in the application code. The EPASCAL declaration to set up the call is as the following example: 4-6 VAXELN KMV1A Dump Program VAR kmv1a_name : varying_string(30); { Such as "KVA0" } dump_file : varying-string(64) := '3.698"NAME PASSWORD"::USER2:[NAME.KMV]KMVDMP.DAT'; dump_stat : INTEGER; eln_dump_stat : INTEGER; { valid if dump_stat is unsuccessful } kmv1a_name := 'KVA0'; DUMP_KMV1A (kmv1a_name, dump_file, dump_stat, eln_dump_stat); 4-7 VAXELN KMV1A Dump Program __________________________________________________________ 4.5 Using the Dump The dump file in previous section was created on the host system as KMVDMP.DAT. There is an additional step to be taken to make the dump file an ASCII readable. This is done after completion of the test run. At the DCL prompt type: $ MCR DMP Then at the DMP utility prompt enter: DMP> DMPKMV.DAT=KMVDMP.DAT DMPKMV.DAT is a readable file with part of a block provided as a sample below. In the sample a wrap around buffer in the KMV1A is displayed. It shows about five messages received raw with the protocol idle characters spaced between them. The data is in octal, 16 bit word format. Usually of interest is the binary representation of the data for analysis. This final step must be done with pad and pencil. Sample Dump Segment: 4-8 VAXELN KMV1A Dump Program Dump of $$4:[NAME.KMV]DMPKMV.DAT;1 - File ID 7543,6,0 Virtual block 0,000100 - Size 512. bytes 000000 001001 004004 020020 177500 052652 053253 055255 065265 000020 125325 125525 126526 132532 152552 052652 053253 055255 000040 065265 125325 125525 126526 132532 152552 052652 053253 000060 055255 025265 001200 001001 004004 020020 100100 000400 000100 002002 010010 077540 125325 125525 126526 132532 152552 000120 052652 053253 055255 065265 125325 125525 126526 132532 000140 152552 052652 053253 055255 065265 125325 125525 126526 000160 160012 100100 000400 002002 010010 040040 000200 001001 000200 144004 132537 152552 052652 053253 055255 065265 125325 000220 125525 126526 132532 152552 052652 053253 055255 065265 000240 125325 125525 126526 132532 152552 052652 001253 010110 000260 040040 000200 001001 004004 020020 100100 000400 053756 000300 055255 065265 125325 125525 126526 132532 152552 052652 000320 053253 055255 125665 126526 132532 152552 052652 053253 000340 055255 065265 125325 125525 126526 132532 152552 052652 000360 053253 055255 065265 125325 125525 126526 012532 100100 000400 000400 002002 010010 040040 000200 001001 004004 137760 000420 152552 052652 053253 055255 065265 125325 125525 126526 000440 132532 152552 052652 053253 055255 065265 125325 125525 000460 126526 132532 052552 001400 002002 010010 040040 000200 000500 165166 000340 165166 000340 000153 000020 165166 000000 *** EOF *** 4-9 __________________________________________________ 5 KMV1A Debugger ODTDSM is the On-line Debugging Tool Server Module. It executes in the KMV1A and is used to debug KMV1A micro-code. ODTDSM is available in the toolkit in two forms: An object module that can be linked into the KMV1A code during the VAXELN_KMVGEN.COM execution, and as an executable image that can be downloaded into the KMV1A under control of KMV_FILE_LOAD. The VAXELN KMV1A ODT Debugger Service module (ODTDSM) is designed to allow a programmer to use a subset of RSX-11 ODT commands to monitor and control the operation of a program in a KMV1A. The ODT Debugger Service Module communicates with KMV1A_ODTDSM_SERVER, a program installed in a MicroVAX executing VAXELN. This program in turn communicates with REMOTEOI, the remote operator interface program that runs in the host VAX/VMS system and provides the operator interface to the debugger. The ODTDSM debugging tool requires a system configuration of: o KMV1A installed in a MicroVAX o VAXELN software system in the MicroVAX o Ethernet link to a VAX/VMS or MicroVAX/MicroVMS system The hardware configuration required and the software that executes in each part of the configuration is illustrated in Figure 5-1. 5-1 KMV1A Debugger __________________________________________________________ Figure 5-1 KMV1A Program Debug Configuration __________________________________________________________ +-------------------+ +------------------------------------------+ | VAX/VMS | | MicroVAX | | KMV1A | | or | | -------- |Q| ----- | | MicroVAX/ | DECNet | |B| ODTDSM | | MicroVMS |-----------| VAXELN System |U| | | | Ethernet | |S| Protocol | | REMOTEOI | | KMV1A_ODTDSM_SERVER | | Executable | +-------------------+ +------------------------------------------+ __________________________________________________________ 5-2 KMV1A Debugger __________________________________________________________ 5.1 Debugger Service Module Commands ODTDSM is a simplified version of the standard PDP-11/LSI-11 ODT program. It provides commands to control execution and examine memory while a program is running in the KMV1A. ODTDSM provides the following commands: Where: nnnnnn is an up to 6 digit octal number k is a single digit value 0 to 7 c is an octal number interpreted as a count a is an address specifier which may be in either of two forms: nnnnnn or k,nnnnnn where k is a relocation register __________________________________________________________ 5.2 Summary of Commands A summary of the commands available with ODTDSM is listed below: o a/ open location a o $kr/ open an internal register where r is: - null machine register k is register number (0 - 7) - B breakpoint register k - W watch point register k - R relocation register k o S/ open user status register k o nnnnnn close current location, store nnnnnn in it o close current location, leave it the same 5-3 KMV1A Debugger o nnnnnn close current location, store nnnnnn there, open next word o close the current location, open next word o aG begin execution of the program at address a o G begin execution at the program transfer address o P proceed from a break point or watch point o cP proceed from the current break or watch point until the c-th occurrance of that break /watch point o a;kB set break point k at address a o a;B set next break point at address a o ;kB clear break point k o ;B clear all break points o a;kW set watch point k at address a o a;W set next watch point at address a o ;kW clear watch point o ;W clear all watch points o a;kR set relocation register k to address a o a;R set next free relocation register to address a o ;kR clear relocation register k o ;R clear all relocation registers o S step program by one instruction o cS step program by c instructions 5-4 KMV1A Debugger __________________________________________________________ 5.3 ODTDSM Command Descriptions The following sections describe the commands used by ODTDSM. ODTDSM indicates its readiness to accept a command by displaying the "@" as its prompt character. You may enter a command whenever the prompt is displayed. If the VAX/VMS terminal supports type-ahead, you may enter any number of ODTDSM commands before receiving the prompt back from ODTDSM. __________________________________________________________ 5.4 Referring to Addresses Addresses in ODTDSM may be represented as a six- digit octal number which is an absolute address; or a relocation register and a six-digit octal number. Valid addresses are as follows: Assume relocation register $2R has 2000 in it, then: 2064 - absolute address 2064 002064 - absolute address 2064 2,64 - relative address 64, relocated by register 2 (absolute address 2064) 2,000064 - relative address 64, relocated by register 2 (absolute address 2064) __________________________________________________________ 5.5 Referring to ODTDSM Registers ODTDSM maintains the locations of watchpoints, breakpoints, relocation registers, and the contents of user program machine registers in memory. The contents of these registers may be examined explicitly by using the register reference syntax. The user program machine registers are saved automatically by ODTDSM every time it gains control. When the user program is started after a breakpoint, watchpoint, single step, or error, they are restored before the Return From Interrupt (RFI) is executed. 5-5 KMV1A Debugger Registers are reference by the prefix "$" followed by a register number and register specifier. The register specifiers are: $kB - break point register $kW - watch point register $kR - relocation register $k - machine register $S - machine status register The breakpoint and watchpoint registers contain the addresses of the associated breakpoints and watchpoints. The relocation registers contain the values that are added to a specified address reference. There is one other register specifier ($S) which specifies the program status word. Examples of register specifiers: $2B - breakpoint register 2 $7 - machine register 7 (PC) $1R - relocation register 1 $4W - watchpoint register 4 $S - machine PS register __________________________________________________________ 5.6 Relocation Registers When debugging programs, it is often necessary to refer to addresses in memory. Rather than specifying absolute addresses, it is more convenient to refer to addresses relative to the beginning of an assembly module since the listing of a program almost always is relative to zero. The binding of the module's relative addresses to absolute addresses is handled by the Task Builder. From a task builder map, it is possible to determine the base addresses of each module. By setting a relocation register to the base of 5-6 KMV1A Debugger a module, it is possible to refer to an address relative to the relocation register. ODTDSM will add the base of the relocation register to the relative address to compute an absolute address. ODTDSM has eight relocation registers numbered 0 - 7 and identified as $0R to $7R. When used in an address specification, only the register number and a comma seperating the relative address from the register are used. For example assume $4R (relocation register 4) has 2004 in it then 4,4/ will open location 2010 4,2000G will start execution at location 4004 4,16;3B will set break point 3 at location 2022 $4R/ will open relocation register 4 and display 2004 __________________________________________________________ 5.7 Breakpoints and Watchpoints ODTDSM has eight breakpoints and eight watchpoints. A breakpoint is set at an instruction at which you want the execution of the program being debugged to stop. ODTDSM will stop execution before the instruction is executed. You may continue the execution of the program with the 'Proceed' or 'Step' command. A watchpoint is a memory address which is monitored by ODTDSM for a data content change. The watchpoint uses the T-bit trap of the KMV1A DCT-11 microprocessor which intercepts every instruction executed by the DCT-11. If there is a change and the watchpoint count (specified at the proceed following a watch point trap) is one, execution will stop and ODTDSM will display the address of the watchpoint. If the watch point count is not one, it is decremented and execution continues. 5-7 KMV1A Debugger Because of the overhead involved in servicing the T-bit trap and determining if any watch point has changed, execution of an application will take much longer to run as it does without watchpoints. Therefore, applications which are driven by real time events may not operate correctly. __________________________________________________________ 5.8 Open a Memory Location To examine the contents of a KMV1A memory location or register, it must be opened. This is accomplished by specifying an address followed by a "/". ODTDSM will open the location and display its contents. The location is then considered open. New data may be deposited in the memory location. Only words (even addresses) may be opened. Odd byte addresses are illegal. Assume relocation register $2R has 2000 in it, then: 2064/ - opens location 2064 2,64/ - opens location 2064 $2R/ - open relocation register 2 $S/ - open program status word The actual display is: @2064/004563^ where "^" signifies the cursor location @2,64/004563^ @$2R/002000^ @$S/000340^ __________________________________________________________ 5.9 Close location If a location is open, it must be closed before executing any other ODTDSM command. When closing a location, a new value may be entered followed by a . Entering a only closes the location but retains the current contents. Entering a with or without a preceding 5-8 KMV1A Debugger new value closes the current location and opens the next sequential even addressed location. @2064/004563 close current location, open next 002066/101367^ no change at address 2064 @2064/004563 2467 close current location, open next 002066/101367^ contents of address 2064 = 2467 assume $2R contains 2000 @2,64/004563 close current location, open next 2,66/101367^ @$2R/002000 close current location, open next $3R/004000^ @2,64/004563 close current location - no change @^ @2,64/004563 1234 close current location @^ contents of address 2064 = 1234 The internal registers (breakpoints, watchpoints, relocation registers, user registers) are stored in sequence in memory and may be examined using a series of 'open next' commands (close with linefeeds). The sequence of register locations are as follows: $0R - $7R - relocation registers 0 through 7 $0B - $7B - breakpoint registers 0 through 7 $0W - $7W - watchpoint registers 0 through 7 $0 - $7 - user registers 0 through 7 $S - user status register (PS) 5-9 KMV1A Debugger __________________________________________________________ 5.10 Starting and Resuming Execution Execution of a test program under ODTDSM begins with the 'G' command. The 'G' command (Go) can only be used to start a program after it has been loaded or to restart the program at a particular address after a breakpoint or watchpoint. Resuming execution from a breakpoint or watchpoint is initiated with the 'P' or 'S' commands. The 'P' command (Proceed) restarts execution from where halted. It is possible to specify the number of times to pass through the breakpoint before stopping again. The 'S' command (Step) allows execution of one or more instructions starting at the current or halted position. o Go command G - Start execution at the initial PC value specified specified in the task image of the KMV1A program aG - Start execution at address 'a' o Proceed command P - Proceed from current breakpoint and stop after one pass through this breakpoint cP - Proceed from current breakpoint and stop after 'c' passes through this breakpoint o Step command S - Execute next instruction and stop cS - Execute the next c instructions and stop 5-10 KMV1A Debugger Assuming a breakpoint halt at address 2064, here are some examples of the 'G', 'P', and 'S' ODTDSM commands: @G Start execution at the transfer address of the image @P Resume execution from address 2064. Halt at this breakpoint location if this instruction is executed again @5P Resume execution from address 2064. Halt at this breakpoint location on the fifth execution of this instruction @S Execute next instruction and halt @7S Execute next the next seven instructions and halt __________________________________________________________ 5.11 Setting and Clearing Breakpoints and Watchpoints Breakpoints and watchpoints are addresses at which user program execution is halted. Breakpoints halt execution when the program attempts to execute the instruction at the breakpoint location address. Watchpoints halt execution when the contents of the watchpoint location address are changed. There are eight breakpoint and watchpoint registers. It is possible to set a breakpoint or watchpoint by specific reference to the register number or allow ODTDSM to select the next free register. Breakpoints or watchpoints may be cleared individually by specific register reference or they all may be cleared with a single command. a;kB - set breakpoint at address 'a' - use register 'k' a;B - set breakpoint at address 'a' - ODTDSM selects register a;kW - set watchpoint at address 'a' - use register 'k' a;W - set watchpoint at address 'a' - ODTDSM selects register ;kB - clear breakpoint register 'k' ;B - clear all breakpoints 5-11 KMV1A Debugger ;kW - clear watchpoint register 'k' ;W - clear all watchpoints Examples where $2R (register #2) is set with the value 2000 @2,100;2B - set break point 2 at location 002100 @1000;3W - set watchpoint 3 at location 001000 @;3B - clear breakpoint 3 @;W - clear all watchpoints __________________________________________________________ 5.12 Setting and Clearing Relocation Registers There are eight relocation registers. It is possible to set a relocation register by specific reference to that register number or allow ODTDSM to select the next free register. Relocation registers may be cleared individually by specific register reference or they all may be cleared with a single command. a;kR - set relocation register 'k' to address 'a' ;kR - clear relocation register 'k' ;R - clear all relocation registers Examples where $2R contains 002000 @1000;1R - set relocation register 1 to address 001000 @2,100;2R - set relocation register 2 to address 002100 @;2R - clear relocation register 2 @;R - clear all relocation registers __________________________________________________________ 5.13 Errors ODTDSM will display its error indicator (?) whenever improper syntax is detected. Some causes of these errors are: Improper Commands 5-12 KMV1A Debugger Odd address references when word boundary reference are expected Reference to ODTDSM registers not properly initialed __________________________________________________________ 5.14 ODTDSM Initialization When ODTDSM is loaded into the KMV1A as part of the task image, execution will be delayed until communications are established with the debugger server in the VAXELN system and also with REMOTEOI in a host VAX/VMS system. Then the ODTDSM name will be displayed at the VAX/VMS terminal, along with the transfer address of the program to be debugged. At the ODTDSM prompt "@", commands may now be entered. __________________________________________________________ 5.15 Program Loading with KMV_FILE_LOAD Always specify that the KMV1A should be master cleared when ODTDSM is loaded, but not when your application program is loaded. This is because a master clear will take control of the KMV1A away from ODTDSM and return it to the ROM code. Respond affirmatively to the KMVLOADFILE query to start both ODTDSM and the application program. The first start causes ODTDSM to start running and emulate the KMV1A ROM code. The second start tells ODTDSM to start executing the application program when the remote console program makes contact with it. __________________________________________________________ 5.16 Loading ODTDSM A typical session to load and start the debugger and a program to be debugged is as follows: Assuming that the VAXELN Epascal system that contains KMVLOADFILE is named ELNSYS.SYS, the system may be booted over the network by typing at the MicroVAX console: 5-13 KMV1A Debugger >>>B XQA0 or alternatively by typing at the VAX/VMS terminal: $ EDEBUG/LOAD=ELNSYS.SYS where xxxxxx is the MicroVAX DECNET node name VAXELN will boot and display at the MicroVAX console the following message: VAXELN ver 3.02 KMV_FILE_LOAD will start to run and prompt for input. ODTDSM should first be loaded into the KMV1A followed by the program requiring debug. For ODTDSM the following interactive exchange occurs at the console: o Enter device to load: KVA0 o Do you want to master clear KVA0 ?[Y/N]: Y o Enter file name: 2.999::SYS$SYSDEVICE:[ELN.KMV$]ODTDSM.EXE o KVA0 Loaded successfully o Do you want to start KVA0 ? [Y/N]: Y o KVA0 start successfully 5-14 KMV1A Debugger __________________________________________________________ 5.17 Loading the Application to be Debugged Now load the program to be debugged: o Enter device to load: KVA0 o Do you want to master clear KVA0 ?[Y/N]: N o Enter file name: 2.999::SYS$SYSDEVICE:[YOURDIRECTORY]YOUR.EXE o KVA0 Loaded successfully o Do you want to start KVA0 ? [Y/N]: Y o KVA0 start successfully __________________________________________________________ 5.18 REMOTEOI for ODTDSM REMOTEOI is the Remote Operator interface for ODTDSM. It executes on the host VAX/VMS system and communicates over the Ethernet with the KMV1A_ODTDSM_SERVER in the MicroVAX VAXELN system. After a VAXELN system that includes KMV1A_ODTDSM_SERVER has been loaded and is executing in a MicroVAX, and the ODTDSM module has been loaded and is executing in a KMV1A installed in that MicroVAX; the REMOTEOI program may be run on either a VAX/VMS system or a MicroVAX/MicroVMS system. The display at the terminal will be: MicroVAX Remote Operator Interface Program V1.0 A Please Specify network node name and task port name for remote MicroVAX The response is made by entering the node name or number of the MicroVAX executing the VAXELN system, followed by a <::> delimiter, followed by "TASK=DBGdevnam". "devnam" should be the ASCII string name of the KMV1A in which the debug is to occur. A typical input example is: 5-15 KMV1A Debugger UVAX01::"TASK=DBG_KVA0" It is necessary that the object "TASK" be defined in the VAX/VMS system with object number '0'. The existence of object "TASK" can be determined with the following DCL command: $ MCR NCP SHOW KNOWN OBJECTS 5-16 KMV1A Debugger If the object "TASK" is not defined, it is done with the following DCL command: $ MCR NCP SET OBJECT TASK Answer the prompt for 'object number' with the value '0'. Answer all other prompts with the default . After entering the target system specification is pressed. REMOTEOI then establishes the communications link to the MicroVAX executing KMV1A_ODTDSM_SERVER. If the KMV1A device specified is executing ODTDSM, The prompt character for the debugger will be displayed at the remote terminal and ODTDSM commands may then be entered. The initiation of ODTDSM at the terminal is as follows: ODTDSM ssssss @ "ssssss" is the application program transfer address. The remote operator interface process REMOTEOI in you host VAX/VMS system is talking to the VAXELN program KMV1A_ODTDSM_SERVER in the MicroVAX and through it to ODTDSM in the KMV1A. __________________________________________________________ 5.19 Building ODTDSM into the KMV1A Image The ODTDSM.OBJ object module may be linked/task built into a KMV1A program using the VAXELN_ KMVGEN VAX/VMS DCL command procedure. This is done in response to a query by the command procedure. 5-17 KMV1A Debugger __________________________________________________________ 5.20 Building KMV1A_ODTDSM_SERVER into VAXELN Systems The KMV1A_ODTDSM_SERVER is included in a VAXELN system using the VAXELN EBuild program. This server relays messages to and from ODTDSM in the KMV1A and REMOTEOI in the VAX host. The KMV1A_ ODTDSM_SERVER program should be specified to EBuild as follows: Program KMV1A_ODTDSM_SERVER Debug No Run Yes Init Required Yes Mode Kernel Kernel Stack 16 Job Priority 4 Program Argument device-name Device-name should be the ASCII string name of the KMV1A that will contain the ODTDSM debug module. Note REMOTEOI expects a different debug server for each KMV1A that it in contact with. Each copy of the server must specify a different KMV1A name to EBUILD at the prompt for a program argument. When editing the System Characteristics, some system resource limits must be increased for each copy of KMV1A_ODTDSM_SERVER. They are listed below: 5-18 KMV1A Debugger __________________________________________________________ Table 5-1 System Resource Limits to Be Increased __________________________________________________ Instruction Emulation_____________String______________________ Ports +1 ________Pool__________________+16_________________________ Note the the above values are cumulative for all applications in the VAXELN system. When the VAXELN system that contains the KMV1A_ODTDSM_SERVER program is loaded into a MicroVAX and executed, the server program will be executed, set up to perform I/O with the KMV1A, and wait for data to process from the KMV1A over the QBUS or REMOTEOI over the DECNet/Ethernet. 5-19 __________________________________________________ 6 VAXELN-KMV1A-TOOLKIT Software Installation __________________________________________________________ 6.1 Preparing to Install VAXELN-KMV1A-TOOLKIT This section discusses the preparations and requirements necessary for installing VAXELN- KMV1A-TOOLKIT. This manual applies to Version 3.0 of VAXELN- KMV1A-TOOLKIT and all subsequent maintenance releases up to the next major product release. Your bill of materials (BOM) and indented bills report (BIL) specify the number and contents of your media. Be sure to verify the contents of your kit with this information. If your kit is damaged or if you find that parts of it are missing, contact your Digital representative. VAXELN-KMV1A-TOOLKIT provides online release notes. Digital strongly recommends that you read the release notes before proceeding with the installation. For information on accessing the online release notes, see (online_ relnotes) _____________________________ 6.1.1 Required Operating System Components The VMS operating system comes with a variety of support options, or classes. Classes include such features as networking and RMS journaling. To use VAXELN-KMV1A-TOOLKIT, your system should be running a version of VMS that includes the following classes: o VAX/VMS Version 5.0 or higher o VAXELN-KMV1A-TOOLKIT Version 3.1 or higher need not be installed. Ultimately however, execution depends on it. 6-1 VAXELN-KMV1A-TOOLKIT Software Installation For a complete list of the required classes, see the Software Support Addendum (SSA), which comes with the Software Product Description (SPD). _____________________________ 6.1.2 Prerequisite Hardware This section discusses the hardware you must have installed on your system before installing VAXELN-KMV1A-TOOLKIT. o Q-bus based MicroVAX for system download o Ethernet connection between the host VAX and the MicroVAX _____________________________ 6.1.3 License Registration You must register the VAXELN-KMV1A-TOOLKIT license through the VMS License Management Facility (LMF) in accordance with the license agreement signed by your site. The license registration information you need is contained in the Product Authorization Key (PAK) that is shipped with VAXELN-KMV1A-TOOLKIT. The PAK is a paper certificate that contains information about the license you have to run a particular piece of software. During the installation, the system asks whether you have registered the VAXELN-KMV1A-TOOLKIT license and loaded the appropriate authorization key. You must register and load your license for VAXELN-KMV1A-TOOLKIT before you start the installation in order to run the Installation Verification Procedure (IVP) and use the software. To register a license under VMS, first log in to the system manager's account, SYSTEM. You then have a choice of two ways to perform the registration: o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, respond 6-2 VAXELN-KMV1A-TOOLKIT Software Installation with data from your Product Authorization Key (PAK). o At the DCL prompt, issue the LICENSE REGISTER command with the appropriate qualifiers that correspond to PAK information. If you plan to use VAXELN-KMV1A-TOOLKIT on more than one node in a VAXcluster, you will need to perform a license load on the other nodes after you complete this installation. See (postcluster_consids). For complete information on using LMF, see the manual on the License Management Utility in the VMS documentation set. _____________________________ 6.1.4 Installation Procedure Requirements The following sections discuss various requirements for installing VAXELN-KMV1A-TOOLKIT. _____________________________ 6.1.4.1 Time The installation takes approximately 4 to 5 minutes, depending on your type of media and your system configuration. Installing VAXELN-KMV1A-TOOLKIT and running the IVP on a standalone VAX 8600 system takes 5 minutes. 6-3 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.1.4.2 Privileges To install VAXELN-KMV1A-TOOLKIT, you must be logged in to an account that has SETPRV or at least the following privileges: o CMKRNL o WORLD o SYSPRV o PHY_IO Note that VMSINSTAL turns off BYPASS privilege at the start of the installation. _____________________________ 6.1.4.3 Disk Space Installing VAXELN-KMV1A-TOOLKIT requires a certain amount of free disk storage space during the installation. Once VAXELN-KMV1A-TOOLKIT is installed, less storage space is required. Table 6-1 summarizes the storage requirements: __________________________________________________________ Table 6-1 Disk Space Requirements __________________________________________________ Blocks Blocks During After In- Kit______________Installation__________stallation_ VAXELN-KMV1A- 500 500 TOOLKIT Version ________3.1_______________________________________________ To determine the number of free disk blocks on the current system disk, enter the following command at the DCL prompt: $ SHOW DEVICE SYS$SYSDEVICE 6-4 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.1.4.4 System Parameters There are no special requirements for system parameters. 6-5 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.1.4.5 Process Account Quotas The account you use to install VAXELN-KMV1A- TOOLKIT must have sufficient quotas to enable you to perform the installation. Table 6-2 summarizes the process quotas required for the installation account. __________________________________________________________ Table 6-2 Process Account Quotas for the Installing Account __________________________________________________ Account_Quota____Value____________________________ ASTLM 24 BIOLM 18 BYTLM 18,000 DIOLM 18 ENQLM 30 ________FILLM____________20_______________________________ User account quotas are stored in the file SYSUAF.DAT. Use the VMS Authorize Utility to verify and change user account quotas. First set your directory to SYS$SYSTEM and then run AUTHORIZE: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> At the UAF> prompt, use the SHOW command with an account name to check a particular account. For example: UAF> SHOW SMITH To change a quota, use the MODIFY command. MODIFY has the following format: MODIFY account-name /quota-name=NNN 6-6 VAXELN-KMV1A-TOOLKIT Software Installation The following example changes the FILLM quota for the SMITH account and then exits from the utility: UAF> MODIFY SMITH /FILLM=50 UAF> EXIT After you exit from the utility, the system displays messages indicating whether or not changes were made. Once the changes have been made, you must log out and log in again for the new quotas to take effect. For more information on modifying account quotas, see the description of the Authorize Utility in the VMS System Management Subkit. 6-7 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.1.4.6 VMSINSTAL Requirements When you invoke VMSINSTAL, it checks the following: o Whether you have set your default device and directory to SYS$UPDATE o Whether you are logged in to a privileged account o Whether you have adequate quotas for installation o Whether DECnet is running o Whether any users are logged in to the system Note that the VMSINSTAL requires that the installation account have a minimum of the following quotas: ASTLM = 24 BIOLM = 18 BYTLM = 18,000 DIOLM = 18 ENQLM = 30 FILLM = 20 If VMSINSTAL detects any problems during the installation, it notifies you and asks if you want to continue the installation. In some instances, you can enter YES to continue. To stop the installation process and correct the situation, enter NO or press RETURN. Then correct the problem and restart the installation. _____________________________ 6.1.4.7 Backing Up Your System Disk At the beginning of the installation, VMSINSTAL asks if you have backed up your system disk. Digital recommends that you do a system disk backup before installing any software. 6-8 VAXELN-KMV1A-TOOLKIT Software Installation Use the backup procedures that are established at your site. For details on performing a system disk backup, see the section on the Backup Utility in the VMS System Management Subkit. 6-9 VAXELN-KMV1A-TOOLKIT Software Installation __________________________________________________________ 6.2 Installing VAXELN-KMV1A-TOOLKIT This section describes how to install VAXELN- KMV1A-TOOLKIT. Section 6.2.2 contains a step-by- step description of the installation procedure. The last section covers postinstallation considerations. _____________________________ 6.2.1 General Information This section includes information about the following topics: o Accessing release notes o Determining files added to your system o Running the Installation Verification Procedure (IVP), o Aborting the installation. _____________________________ 6.2.1.1 Determining the Files Added to the System During the installation, VAXELN-KMV1A-TOOLKIT creates some files on your system. _____________________________ 6.2.1.2 Running the Installation Verification Procedure (IVP) The Installation Verification Procedure (IVP) for VAXELN-KMV1A-TOOLKIT verifies the installation. During the installation, you are asked if you want to run the IVP as part of the installation. If you respond YES, VMSINSTAL runs the IVP. It is recommended that you run the IVP to make sure that VAXELN-KMV1A-TOOLKIT is installed correctly. After VAXELN-KMV1A-TOOLKIT is installed, you can run the IVP independently to verify that the software is available on your system. You might need to run the IVP after a system failure to make sure that users can access VAXELN-KMV1A- TOOLKIT. 6-10 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.2.1.3 Aborting the Installation To abort the installation procedure at any time, press CTRL/Y. When you press CTRL/Y, the installation procedure deletes all files it has created up to that point and exits. You can then start the installation again. 6-11 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.2.2 Installation Procedure The VAXELN-KMV1A-TOOLKIT installation procedure consists of a series of questions and informational messages. _____________________________ 6.2.2.1 Invoking VMSINSTAL To start the installation, invoke the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. VMSINSTAL is in the SYS$UPDATE directory. You use the following syntax to invoke VMSINSTAL: @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N saveset-name The installation name for the component. For VAXELN-KMV1A-TOOLKIT, use the following installation name: KMV_ELNTOOL011 device-name The name of the device on which you plan to mount the media. For example, MTA0: is the device name for a tape drive. It is not necessary to use the console drive for this installation. However, if you do use the console drive, you should replace any media you removed once the installation is complete. OPTIONS N An optional parameter that indicates you want to see the release notes question. If you do not include the OPTIONS N parameter, VMSINSTAL does not ask you about the release notes. You should review the release notes before proceeding with the installation in case they contain new information about the installation. Note that there are several other options you can select when you invoke VMSINSTAL. See the VMS documentation on software installation in the VMS System Management Subkit for information on these 6-12 VAXELN-KMV1A-TOOLKIT Software Installation options. If you specify more than one option, separate the options with commas (OPTIONS A,N). The following example invokes VMSINSTAL to install VAXELN-KMV1A-TOOLKIT from tape drive MTA0: and shows the system response. This example uses the OPTIONS N release note parameter. $ @SYS$UPDATE:VMSINSTAL KMV_ELNTOOL011 MTA0: OPTIONS N VAX/VMS Software Product Installation Procedure VN.N It is 22-AUG-1989 at 14:16. Enter a question mark (?) at any time for help. If you do not supply either the product name or the device name, VMSINSTAL prompts you for this information later in the installation procedure. VMSINSTAL does not prompt you for any options, so be sure to include OPTIONS N on the VMSINSTAL command line to access the release notes during the installation. _____________________________ 6.2.2.2 Installation Questions This section discusses the questions that appear during the installation. Appendix A contains a sample installation procedure showing how the questions can be answered. Each question in the installation is marked with an asterisk (*) at the beginning of the line. Some questions show the default response in brackets, for example [YES]. To use the default response, press the RETURN key. 1 DECnet status VMSINSTAL notifies you if DECnet is running and displays a list of all active processes. It then asks if you want to continue the installation. You should install VAXELN-KMV1A- TOOLKIT on a standalone system or cluster with 6-13 VAXELN-KMV1A-TOOLKIT Software Installation DECnet shut down. NO is the default response to the question. %VMSINSTAL-W-DECNET, Your DECnet network is up and running. . . . * Do you want to continue anyway [NO]? YES If you are installing on VMS Version 5.2 or higher, VMSINSTAL does not check the DECnet status. You can install VAXELN-KMV1A-TOOLKIT while DECnet is up and running. 2 System backup VMSINSTAL asks if you are satisfied with your system backup. You should always back up your system disk before performing an installation. If you are satisfied with the backup of your system disk, press RETURN. Otherwise, enter NO to discontinue the installation. After you back up your system disk, you can restart the installation. * Are you satisfied with the backup of your system disk [YES]? YES 3 Mounting the media You should now mount the first distribution volume on the device you specified when you invoked VMSINSTAL. The device name appears in the line preceding the question. VMSINSTAL then asks you if you are ready to continue with the installation. 6-14 VAXELN-KMV1A-TOOLKIT Software Installation If you respond YES to indicate that you are ready, VMSINSTAL displays a message that the media containing VAXELN-KMV1A-TOOLKIT has been mounted on the specified device and that the installation has begun. For example: Please mount the first volume of the set on MTA0:. * Are you ready? YES %MOUNT-I-MOUNTED, KMV_EL MOUNTED ON _$$MTA0: (NODE 1) The following products will be processed: KMV_ELNTOOL V1.1 Beginning installation of KMV_ELNTOOL V1.1 at 20:01 %VMSINSTAL-I-RESTORE, Restoring product saveset A... If you entered the wrong device name when you invoked VMSINSTAL and need to restart the installation, enter NO in response to the "Are you ready?" question. To abort the installation for other reasons, press CTRL/Y. 4 Release Notes For systems with VMS version 5.0 or 5.1, if you specified OPTIONS N when you invoked VMSINSTAL, you are now asked to choose one of the five options for reviewing the release notes. Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes * Select option [2]: 5 If you select option 1, VMSINSTAL displays the release notes immediately on the console terminal. You can terminate the display at any time by pressing CTRL/C. 6-15 VAXELN-KMV1A-TOOLKIT Software Installation If you select option 2, VMSINSTAL prompts you for the name of the print queue that you want to use: * Queue name [SYS$PRINT]: You can press RETURN to send the file to the default output print device or you can enter another queue name. If you select option 3, VMSINSTAL displays the release notes immediately on the console terminal and then prompts you for a queue name for the printed version. Option 4 causes the installation to copy the release notes to the help directory. Select option 5 if you have already reviewed the release notes and are restarting the installation. 6-16 VAXELN-KMV1A-TOOLKIT Software Installation If you specified OPTIONS N when you invoked VMSINSTAL, you are now asked to choose one of the four options for reviewing the release notes. Release notes included with this kit are always copied to SYS$HELP. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: If you select option 1, VMSINSTAL displays the release notes immediately on the console terminal. You can terminate the display at any time by pressing CTRL/C. If you select option 2, VMSINSTAL prompts you for the name of the print queue that you want to use: * Queue name [SYS$PRINT]: You can press RETURN to send the file to the default output print device or you can enter another queue name. If you select option 3, VMSINSTAL displays the release notes immediately on the console terminal and then prompts you for a queue name for the printed version. Select option 4 if you have already reviewed the release notes and are restarting the installation. If you specified OPTIONS N when you started the installation, VMSINSTAL asks a release notes question. You have five options for handling the release notes under VMS Versions 5.0 and 5.1. There are only four options under VMS Version 5.2 or higher. 6-17 VAXELN-KMV1A-TOOLKIT Software Installation For VMS Versions 5.0 and 5.1, you see the following display: Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes * Select option [2]: For VMS Version 5.2 or higher the display is as follows: Release notes included with this kit are always copied to SYS$HELP. Additional Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. None of the above * Select option [2]: 6-18 VAXELN-KMV1A-TOOLKIT Software Installation If you select option 1, VMSINSTAL displays the release notes immediately on the console terminal. You can terminate the display at any time by pressing CTRL/C. If you select option 2, VMSINSTAL prompts you for the name of the print queue that you want to use: * Queue name [SYS$PRINT]: You can press RETURN to send the file to the default output print device or you can enter another queue name. If you select option 3, VMSINSTAL displays the release notes immediately on the console terminal and then prompts you for a queue name for the printed version. Option 4 under VMS Versions 5.0 and 5.1 causes the installation to copy the release notes to the help directory. [Even if you do not select the VMS Version 5.0 or 5.1 option 4, the release notes for VAXELN-KMV1A-TOOLKIT are copied to the SYS$HELP directory. Under VMS V5.2 or higher, release notes are always copied to SYS$HELP. VMSINSTAL automatically copies the VAXELN- KMV1A-TOOLKIT release notes to the the system help directory. The file specification is: SYS$HELP:file-spec Select option 4 (VMS Version 5.2 or higher) or option 5 (VMS Version 5.0 or 5.1) if you have already reviewed the release notes and are restarting the installation. 5 Continuing the installation The installation procedure now asks if you want to continue the installation. To continue, enter YES. Otherwise, press RETURN. In either case, the release notes are copied to a file in the SYS$HELP directory. For example: 6-19 VAXELN-KMV1A-TOOLKIT Software Installation * Do you want to continue the installation [N]?: YES %VMSINSTAL-I-RELMOVED, The product's release notes have been successfully moved to SYS$HELP. The release notes are located in the following file: SYS$HELP:KMV_ELNTOOL011.RELEASE_NOTES Note The name of the release notes file installed by VMSINSTAL consists of the current product name and version number. Do not delete release notes for previous versions of VAXELN-KMV1A-TOOLKIT. 6 Choosing to purge files You have the option to purge files from previous versions of VAXELN-KMV1A-TOOLKIT that are superseded by this installation. Purging is recommended; however, if you need to keep files from the previous version, enter NO in response to the question. * Do you want to purge files replaced by this installation [YES]? 6-20 VAXELN-KMV1A-TOOLKIT Software Installation 7 Choosing to run the Installation Verification Procedure (IVP) The installation procedure now asks if you want to run the Installation Verification Procedure. The IVP for VAXELN-KMV1A-TOOLKIT checks to be sure that the installation is successful. It is recommended that you run the IVP. * Do you want to run the IVP after the installation [YES]? 8 License Registration The installation procedure displays license information about your product and then asks if you have registered and loaded your authorization key for VAXELN-KMV1A-TOOLKIT. For example: Product: VAXELN-KMV1A-TOOLKIT Producer: DEC Version: 1.1 Release Date: 01-SEP-1989 * Does this product have an authorization key registered and loaded? If you have not registered and loaded your authorization key, you must answer "NO" to this question. You have to register and load your product authorization key to successfully complete the installation. If you have not done so, you should stop the installation, register and load your product authorization key, and then restart the installation. _____________________________ 6.2.2.3 Informational Messages At this point, the installation procedure displays a number of informational messages that report on the progress of the installation. There are no further questions. If the installation procedure has been successful up to this point, VMSINSTAL moves the new or modified files to their target directories, updates help files, and updates DCL tables, if necessary. If you chose 6-21 VAXELN-KMV1A-TOOLKIT Software Installation to have files purged, that work is done now. The following messages are displayed: %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$SYSDEVICE:[ELN.KMV$]. %CREATE-I-EXISTS, SYS$SYSDEVICE[ELN.KMV$] already exists %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$SYSROOT:[SYSTEST.KMV_ELNTOOL]. %CREATE-I-EXISTS, SYS$SYSROOT:[SYSTEST.KMV_ELNTOOL] already exists KMV_ELNTOOL Toolkit installation procedure complete. %VMSINSTAL-I-MOVEFILES, files will now be moved to their target directories... %VMSINSTAL-I-MOVEFILES, files will now be moved to their target directories... 6-22 VAXELN-KMV1A-TOOLKIT Software Installation _____________________________ 6.2.2.4 Running the Installation Verification Procedure If you chose to run the IVP, VMSINSTAL runs it now. When the IVP runs successfully, you see the following display: _____________________________ 6.2.2.5 Completing the Installation Procedure The following messages indicate that the entire installation procedure is complete: Installation of KMV_ELNTOOL V1.1 completed at 14:20 VMSINSTAL procedure done at 14:20 You can now log out of the privileged account: $ LOGOUT SYSTEM logged out at 01-AUG-1989 14:20:23.31 Note that VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the system manager's account and you want to restore these symbols, you should log out and log in again. _____________________________ 6.2.3 Error Recovery If errors occur during the installation itself or when the IVP is running, VMSINSTAL displays failure messages. If the installation fails, you see the following message: %VMSINSTAL-E-INSFAIL, The installation of KMV_ELNTOOL V1.1 has failed. If the IVP fails, you see these messages: The VAXELN-KMV1A-TOOLKIT V1.1 Installation Verification Procedure failed. %VMSINSTAL-E-IVPFAIL, The IVP for KMV_ELNTOOL V1.1 has failed. Errors can occur during the installation if any of the following conditions exist: o The operating system version is incorrect. 6-23 VAXELN-KMV1A-TOOLKIT Software Installation o A prerequisite software version is incorrect. o The product license has not been registered and loaded. For descriptions of the error messages generated by these conditions, see the VMS documentation on system messages, recovery procedures, and VMS software installation. If you are notified that any of these conditions exist, you should take the appropriate action as described in the message. (You might need to change a system parameter or increase an authorized quota value.) For information on installation requirements, see Section 6.1. 6-24 VAXELN-KMV1A-TOOLKIT Software Installation __________________________________________________________ 6.3 After Installing VAXELN-KMV1A-TOOLKIT After installing VAXELN-KMV1A-TOOLKIT, you need to perform the following tasks: o Edit the system startup and shutdown files. o Set user account quotas. o Modify system parameter settings. This section also explains how to run the Installation Verification Procedure (IVP) independently after the software is installed. _____________________________ 6.3.1 Editing the System Files There is no required rebooting of the system after the VAXELN-KMV1A-TOOLKIT has been installed. _____________________________ 6.3.2 User Account Requirements To work with VAXELN-KMV1A-TOOLKIT, user accounts on your system must have certain privileges and quotas. The next two sections contain information on these requirements. _____________________________ 6.3.2.1 Privileges There are no additional privileges required for the VAXELN-KMV1A-TOOLKIT. _____________________________ 6.3.2.2 User Account Quotas You must make sure that the appropriate user accounts have sufficient quotas to be able to use VAXELN-KMV1A-TOOLKIT. Table 6-3 summarizes the required user account quotas. 6-25 VAXELN-KMV1A-TOOLKIT Software Installation __________________________________________________________ Table 6-3 User Account Quotas for Using VAXELN-KMV1A- TOOLKIT __________________________________________________ Account_Quota____Value____________________________ ASTLM 24 BIOLM 18 BYTLM 18,000 DIOLM 18 ENQLM 30 ________FILLM____________12_______________________________ 6-26 VAXELN-KMV1A-TOOLKIT Software Installation User account quotas are stored in the file SYSUAF.DAT. Use the VMS Authorize Utility to verify and change user account quotas. First set your directory to SYS$SYSTEM and then run AUTHORIZE: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> At the UAF> prompt, use the SHOW command with an account name to check a particular account. For example: UAF> SHOW SMITH To change a quota, use the MODIFY command at the UAF> prompt. MODIFY has the following format: MODIFY account-name /quota-name=NNN The following example changes the FILLM quota for the SMITH account and then exits from the utility: UAF> MODIFY SMITH /FILLM=50 UAF> EXIT After you exit from the utility, the system displays messages indicating whether or not changes were made. Once you have made the changes, the users must log out and log in again for the new quotas to take effect. For more information on modifying account quotas, see the description of the Authorize Utility in the VMS System Management Subkit. _____________________________ 6.3.3 Determining and Reporting Problems If you encounter a problem while using VAXELN- KMV1A-TOOLKIT, report it to Digital. Depending on the nature of the problem and the type of support you have, you can take one of the following actions: 6-27 VAXELN-KMV1A-TOOLKIT Software Installation o Call Digital if your software contract or warranty agreement entitles you to telephone support. o Submit a Software Performance Report (SPR). o Fill out and submit a Reader's Comments form if the problem has to do with the VAXELN-KMV1A- TOOLKIT documentation. There are Reader's Comments forms at the back of each manual. Use the form from the manual in which you found the error. Include the section and page number. Review the Software Product Description (SPD) and Warranty Addendum for an explanation of warranty. If you encounter a problem during the warranty period, report the problem as indicated above or follow alternate instructions provided by Digital for reporting SPD nonconformance problems. See the release notes for VAXELN-KMV1A-TOOLKIT for information on how to submit an SPR. 6-28 VAXELN-KMV1A-TOOLKIT Software Installation __________________________________________________________ 6.4 Installation Verification Procedure A sample Installation Verification Procedure is include as part of the sample installation. __________________________________________________________ 6.5 Sample Installation This section contains a sample installation of VAXELN-KMV1A-TOOLKIT. This sample was run on a system that had no previous version of VAXELN- KMV1A-TOOLKIT installed. [Depending on which layered products you have on your system, you might see additional messages and questions when you perform your installation. The sample installation assumes that DECnet has been shut down, that no users are logged on to your system, and that OPTIONS N is specified to print the release notes. The Installation Verification Procedure (IVP) runs at the end of the installation. _____________________________ 6.5.1 Full Development Kit This section contains a sample installation for the VAXELN-KMV1A-TOOLKIT full development kit. __________________________________________________________ 6.6 Installation Example This section contains a sample installation of KMV_ELNTOOL Product. This example was run on a system that had no previous version of KMV_ELNTOOL Product installed but required directories had been created. The sample installation assumes that DECnet is running and that a couple of users are logged on to your system, and that OPTIONS N is specified to print the Release Notes. The Installation Verification Procedure (IVP) runs at the end of the installation. 6-29 VAXELN-KMV1A-TOOLKIT Software Installation $ @SYS$UPDATE:VMSINSTAL VAX/VMS Software Product Installation Procedure V5.0 It is 22-NOV-1989 at 10:12. Enter a question mark (?) at any time for help. %VMSINSTAL-W-DECNET, Your DECnet network is up and running. %VMSINSTAL-W-ACTIVE, The following processes are still active: SMITH JONES * Do you want to continue anyway [NO]? YES * Are you satisfied with the backup of your system disk [YES]? YES * Where will the distribution volumes be mounted: TAPE1: 6-30 VAXELN-KMV1A-TOOLKIT Software Installation Enter the products to be processed from the first distribution volume set. * Products: KMV_ELNTOOL011 * Options: N Please mount the first volume of the set on TAPE1:. * Are you ready? YES %MOUNT-I-MOUNTED, KMV_EL mounted on TAPE1: The following products will be processed: KMV_ELNTOOL V1.1 Beginning installation of KMV_ELNTOOL V1.1 at 20:01 %VMSINSTAL-I-RESTORE, Restoring product saveset A... Release Notes Options: 1. Display Release Notes 2. Print Release Notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes * Select option _[2]: 1 VMI$ROOT:[SYSUPD.KMV_ELNTOOL011]KMV_ELNTOOL$011.RELEASE_NOTES;1 This is the 1989 release of the VAXELN-KMV1A-TOOLKIT software for inclusion in user developed communications software that drive the KMV1A Programmable Communications Controller device. Fourteen modules will be installed in the standard VAXELN sub-directory: SYS$SYSDEVICE:[ELN.KMV$] Six of these files support the Macro II assembly and Link/Task build of a communications protocol suitable for a download to a KMV1A device. These files are: KMV_ELNTOOL$VAXELN_KMVGEN.COM KMV1A task image generator KMV_ELNTOOL$KVTOOLMAC.COM Macro 11 assembly control KMV_ELNTOOL$KVTOOLTKB.COM Macro 11 task build control KMV_ELNTOOL$KVTOOLDCX.STB KMV1A DCX symbol definitions KMV_ELNTOOL$KVTOOLKML.MLB KMV1A DCX Macro Library KMV_ELNTOOL$KVTOOLEND.OBJ KMV1A assembly end marking The remaining eight files support special builds of the communication protocol for a choice of remote debugging, standalone download of a protocol and debugger to a KMV1A, and an updump of KMV1A memory on command. These files are: 6-31 VAXELN-KMV1A-TOOLKIT Software Installation KMV_ELNTOOL$KMV_FILE_LOAD.EXE VAXELN KMV1A standalone load KMV_ELNTOOL$KMV1A_DUMP.EXE VAXELN KMV1A Dump Program KMV_ELNTOOL$ODTDSM.OBJ KMV1A ODT Debugger - linkable KMV_ELNTOOL$ODTDSM.EXE KMV1A ODT Debugger - Loadable KMV_ELNTOOL$KMV1A_ODTDSM_SERVER.EXE Debugger Communications Server KMV_ELNTOOL$REMOTEOI.EXE Debugger Remote Operator Interface KMV_ELNTOOL$KMV1A_DUMP_PIDD.OBJ VAXELN Descriptor Definitions KMV_ELNTOOL$KMV1A_DUMP_PROC.OBJ VAXELN Application Procedure for triggering KMV1A dump These files will be used in a VAX host development effort in which they will be combined with one or more user designed application modules and with several VAXELN provided modules to create a downloadable system image built under the VAXELN Ebuild procedure. 6-32 VAXELN-KMV1A-TOOLKIT Software Installation IVP -- VAXELN is not necessary for the installation of this product. Although any practical execution of this product would require a VAXELN installation. Also required would be several hardware items such as a pair of MicroVAX IIs with KMV1A boards installed and interconnected across a serial line, an Ethernet connection between the host VAX and the MicroVAX IIs, and one or more protocols installed in the VAX for downloading into the KMV1A device. Also some additional software to simulate the user application would be needed. Therefore the validation procedure selected for this product will be limited to determining that the [ELN.KMV$] directory exists and that the fourteen files have been installed in the [ELN.KMV$] directory. * Do you want to continue the installation [N]?: YES %VMSINSTAL-I-RELMOVED, The products Release Notes have been successfully moved to SYS$HELP. Digital Equipment Corporation, 1989 All Rights Reserved Product: VAXELN-KMV1A-TOOLKIT Producer: DEC Version: 1.1 Release Date: 01-Sep-1989 * Does this product have an authorization key registered and loaded? YES * Do you want to purge files replaced by this installation [YES]? YES * Do you want to run the IVP after the installation [YES]? YES There will be no further questions. Starting a check for directory existence %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$SYSDEVICE:[ELN.KMV$]. %CREATE-I-EXISTS, SYS$SYSDEVICE[ELN.KMV$] already exists %VMSINSTAL-I-SYSDIR, This product creates system disk directory SYS$SYSROOT:[SYSTEST.KMV_ELNTOOL]. %CREATE-I-EXISTS, SYS$SYSROOT:[SYSTEST.KMV_ELNTOOL] already exists Directory check completed KMV_ELNTOOL Toolkit installation procedure complete. %VMSINSTAL-I-MOVEFILES, files will now be moved to the target directories... 6-33 VAXELN-KMV1A-TOOLKIT Software Installation Digital Equipment Corporation, 1989 All Rights Reserved Beginning installation verification procedure for VAXELN KMV1A Toolkit Success __ SYS$SYSDEVICE:[ELN.KMV$] directory exists Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KMV_FILE_LOAD.EXE Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KMV1A_DUMP.EXE 6-34 VAXELN-KMV1A-TOOLKIT Software Installation Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KMV1A_ODTDSM_SERVER.EXE Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$REMOTEOI.EXE Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KMV1A_DUMP_PIDD.OBJ Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KMV1A_DUMP_PROC.OBJ Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$ODTDSM.EXE Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$ODTDSM.OBJ Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KVTOOLMAC.COM Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KVTOOLTKB.COM Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KVTOOLDCX.STB Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KVTOOLKML.MLB Successful installation of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$KVTOOLEND.OBJ Successful install of SYS$SYSDEVICE:[ELN.KMV$]KMV_ELNTOOL$VAXELN_KMVGEN.COM VAXELN KMV1A Toolkit Software Package V1.1 IVP Successful Installation of KMV_ELNTOOL V1.1 completed at 14:20 Enter the products to be process from the next distribution volume set. * Products: (Ctrl-Z to Exit) VMSINSTAL procedure done at 14:20 6-35 VAXELN-KMV1A-TOOLKIT Software Installation __________________________________________________________ 6.7 Files and Logical Names Installed on Your System The VAXELN-KMV1A-TOOLKIT installation procedure installs a number of files on your system and defines some logical names. The next section lists the files installed. _____________________________ 6.7.1 File Names The following list contains the names of all files installed on your system when VAXELN- KMV1A-TOOLKIT is installed. The installation procedure installs a fourteen files on the system in the directory SYS$SYSDEVICE:[ELN.KMV$]. The IVP will be located in SYS$SYSROOT:[SYSTEST.KMV_ ELNTOOL] and the release notes will be located in SYS$SYSROOT:[SYSUPD.KMV_ELNTOOL011]. _____________________________ 6.7.2 File Names The following list contains the names of 14 files installed in [ELN.KMV$] when the VAXELN-KMV1A- TOOLKIT is installed. File Name Description _________ ___________ KMV_ELNTOOL$VAXELN_KMVGEN.COM KMV1A task image generator KMV_ELNTOOL$KVTOOLMAC.COM Macro 11 assembly control KMV_ELNTOOL$KVTOOLTKB.COM Macro 11 task build control KMV_ELNTOOL$KVTOOLDCX.STB KMV1A DCX symbol definitions KMV_ELNTOOL$KVTOOLKML.MLB KMV1A DCX Macro Library KMV_ELNTOOL$KVTOOLEND.OBJ KMV1A assembly end marking KMV_ELNTOOL$KMV_FILE_LOAD.EXE VAXELN KMV1A standalone load KMV_ELNTOOL$KMV1A_DUMP.EXE VAXELN KMV1A Dump Program KMV_ELNTOOL$ODTDSM.OBJ KMV1A ODT Debugger - linkable KMV_ELNTOOL$ODTDSM.EXE KMV1A ODT Debugger - Loadable KMV_ELNTOOL$KMV1A_ODTDSM_SERVER.EXE Debugger Communications Server KMV_ELNTOOL$REMOTEOI.EXE Debugger Remote Operator Interface KMV_ELNTOOL$KMV1A_DUMP_PIDD.OBJ VAXELN Descriptor Definitions KMV_ELNTOOL$KMV1A_DUMP_PROC.OBJ VAXELN Application Procedure for triggering KMV1A dump 6-36