JThe VAXELN IPU Utility J KEIPU *ÝIO Page Utility Reference Manualᜃ Contents  IO_Page Utility EĊKG 3 Building IPU into Your Application EĊKG 4 Entering Commands EĊKG 5 Abbreviating Command Names EĊKG 6 Entering Parameters EĊKG 7 Range Specifications EĊKG 7 File Specifications EĊKG 8 Data Specifications EĊKG 10 Comments EĊKG 10 IPU Dictionary EĊKG 11 @ (Execute Procedure) EĊKG 12 DEFINE EĊKG 13 EXIT EĊKG 14 HELP EĊKG 15 MONITOR EĊKG 16 READ EĊKG 17 SET EĊKG 18 SHOW EĊKG 21 WRITE EĊKG 22 ᬩ> Conventions The following conventions are used in this manual:J []In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one, or all of the choices.J {}In format descriptions, braces surround a required choice of options; you choose one of the options listed.J ̝boldface textBoldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason.J numbersUnless otherwise noted, all numbers in the text are assumed to be decimal. Nondecimal radixesbinary, octal, or hexadecimalare explicitly indicated.J& IO_Page Utility蜕 The IO_Page Utility (IPU) provides a set of commands you can issue at a target system terminal to communicate with the Qbus IO Page. The IPU commands allow you to perform tasks such as the following: Analysis of hardware registers.J Trouble shooting and debugging of IO devices.J ̜Manipulation and monitoring of Qbus memory locations.J Set up the environment to manipulated Qbus memory locations with different formats.J The IPU utility can help you manipulate, debug, finetune, and trouble shoot your VAXELN applications. This document explains how to use IPU, how to build IPU into the VAXELN system, and how to issue IPU commands. The document also describes the format for an IPU command and for specifying such elements as parameters and memory range specifications. Finally, the document provides a technical description of each IPU command. 2 Building IPU into Your Application蜕 To build the IPU utility into your application, you must specify certain information to the System Builder. The following two lines must be added to the ELN BUILD file for your particular application to include IPU with the application: program IPU /warm_debug /kernel_stack=40 /mode=kernel device IO_PAGE /register=%O760000 /vector=%O304/priority=4 /noautoload This will load the IPU program and set up a device to allow access to the Qbus IO page. Sometimes it is helpful to create a RAM disk to store command files and logging files. Refer to the VAXELN Development Utilities Guide for help in building a RAM disk. Entering Commands蜕 IPU command line syntax follows the general format shown below. IPU> command [parameter] [expression] IPU> IPU> is the IPU prompt, indicating that the IPU utility is ready to accept a command.J Command Specifies the name of the command.J Parameter Specifies what the command acts upon. Examples of parameters are range specifications, symbol names, and expressions.J Observe the following rules when entering IPU commands: You can use any combination of uppercase and lowercase letters. The IPU command interpreter translates lowercase letters to uppercase.J At least one blank space must separate the command name from the first parameter, and at least one blank must separate each additional parameter from the previous parameter. Multiple spaces and tabs are permitted in all cases where a single blank is required. The command interpreter compresses multiple blank spaces or tabs to a single blank space.J The following is an example of an IPU command: IPU> DEFINE DIGITAL_IO_REGISTERS %xfe00:+20 where: IPU> is the IPU promptJ DEFINE is a commandJ DIGITAL_IO_REGISTERS is a parameter (in this case a symbol for a named range)J %xfe00:+20 is a parameter (in this case specifying a range)J X Abbreviating Command Names蜕 You can abbreviate any IPU command down to the fewest number of characters that uniquely represent the command. For example, because IPU has a SET command, the SHOW command can be abbreviated to SH or SHO, but not S. You can also abbreviate keywords to the fewest number of characters that provide a unique abbreviation within a set of possible keywords. Entering Parameters蜕 There are three types of parameters available to the IPU commands, they are range specifications, file specifications, and data specifications. Range Specifications蜕 Most IPU commands accept a range of memory address locations as an input parameter. The format for a range of memory address locations is as follows: [%{d|o|x}]START[:[%{d|o|x}][{+|}]END] The fields are as follows: Field Meaning START Starting memory location.J % Indicates a radix specifier follows.J {d|o|x} Decimal, octal, or hexadecimal radix respectively.J : Colon functions as a separator between the starting and ending memory locations.J {+|} Indicates an offset from the starting memory location.J END Ending memory location or offset from starting location.J You can specify an absolute memory location or an offset from a starting memory location. Follow these rules: If a sign is used for the ending memory location the ending memory location is calculated as an offset from the starting memory location. If no sign is used then the range is considered an absolute range.J If the END field is omitted, END is set equal to START.J If the radix field is omitted, the radix setting for the current terminal session is used.J If a named_range is used then and END specification is ignored.Jb File Specifications蜕 This section provides the rules for using file specifications and device names with IPU commands. It contains information about the following: Specifying the parts of a file specification : the node, device, directory, file name, and file type.J A file specification provides the system with all of the information it needs to identify a file. A file specification has the following format: node::device:[directory]filename.type;version The fields are as follows: node The node number of a remote network node. A node identification is needed to access a VAXELN FILE Service volume by its volume name. Furthermore, you do not have to specify this if the volume being accessed is on the current node. A node specification has the following format:J ̝node["accesscontrolstring"]::J The accesscontrolstring is an optional 0 to 42character string containing login information to be sent to the remote node. the information is used to log you into the remote node; the remainder of the file specification is passed to the remote node and interpreted there.J device The name of the device on which the file is stored or is to be written; this field can be a volume label (such as DISK$VOLUME), an explicit physical device name (such as DUA1), or null. If null, the default device for the destination node is applied; for a local device, the current session default, established either in the System Builder, by the first MOUNT_VOLUME procedure call, or by the SET DEFAULT command is applied.J directory The name of the directory under which the file is cataloged. As in VMS, the directory can be suffixed with subdirectory names, separated by periods. If you do not specify this field, the current directory default , established at login or by the SET DEFAULT command, is applied.J b file name The name of the file. It can have up to 39 characters, including alphanumeric characters, underscore(_), and dollar sign ($). No defaults apply to an input file name; but input file names are applied as defaults for output file names.J type Identification of the structure or the type of data in the file. It can have up to 39 characters, including alphanumeric characters, underscore (_), and dollar sign ($).J version The version number of the file. Versions are identified by a decimal number, which is incremented by 1 each time a new version of the file is created. The version number cannot exceed 65,535. For input files, the highest version is assumed by default; for output files, the default version is the next highest version number or, if no file exists with the specified name and type, a version number of 1.J The following are some examples of file specification: Filespec Refers to:J [TEST]FILE1.DAT The highest version of the file FILE1.DAT in the directory [TEST] on the default volume for the current nodeJ 25.276:::FILE1.DAT The highest version of the file FILE1.DAT in the current default directory on the default disk directory on the default volume for node 25.276J DISK$TEST:[DATA] The file FILE1.DAT, version 23, in directoryJ FILE1.DAT;23 [DATA] on the volume DISK$TEST, wherever it residesJ DUA0:FILE1.DAT The highest version of the file FILE1.DAT in the current default directory on the local volume DUA0:J Observe the following rules when entering a file specification: The maximum size of a file specification, including all delimiters, is 255 characters.J Punctuation marks and brackets are required to separate the fields of the file specification.J f܌ The directory field applies only to files on disks (as opposed to files on tape)J The node field is used only if your system is part of a network and is not needed to access a VAXELN File Service volume by its volume name or to access a local volume.J The fields for file name, type, and version apply only to files on mass storage devices (such as disks and tapes).J Data Specifications蜕 A data specification is a way to define a single element of data for the IPU interpreter. This section provides the rules for entering data specifications with IPU commands. The format for a data specification is as follows: [%{a|b|d|o|x}]DATAELEMENT The fields are as follows: Field Meaning % Indicates a format specifier follows.J {a|b|d|o|x} ASCII, BINARY, DECIMAL, OCTAL, or HEXADECIMAL format specification respectively.J DATAELEMENT Data element to be written.J If the format specifier is omitted, the format setting for the current session is used.J Comments蜕 You can include comments in command lines by preceding the comment text with an exclamation point (!). For example: IPU> READ %o17760000 ! This is a comment R IPU Dictionary蜕 This section provides reference information and a technical description of the VAXELN IO_Page Utility (IPU) commands.  @ (Execute Procedure)蜕 Requests the command interpreter to read subsequent command input from a specific file.J A command procedure can also contain the @ command to execute another command procedure. The maximum command level you can achieve by nesting command procedures is 16, including the toplevel command procedure.J FORMAT @ filespec PARAMETERS ̝filespecJ Specifies the file specification or the command procedure to be executed as follows:J node::device:[directory]filename.type;versionJ For a complete description on defining file specifications, refer to the File Specifications section under the Entering Parameters section of the IO Page Utilities Reference Manual.J The default file type is COM.J EXAMPLE ̝IPU> @MYFILEJ The @ command executes the commands in MYFILE.COM.J> DEFINE蜕 Associates a symbolic name with a named range. If you specify an existing logical name, the new symbolic name replaces the existing symbolic name. A symbolic name can be used anywhere a named range is used.J FORMAT DEFINE symbolicname [namedrange] PARAMETERS ̝symbolicnameJ Specifies the symbolic name string, which is a character string containing from 1 to 31 characters (including the dollar sign [$] and the underscore [_]).J ̝namedrangeJ Specifies a range of memory address locations as follows:J [%{d|o|x}]START[:[%{d|o|x}][{+|}]END]J For a complete description on defining range specifications, refer to the Range Specifications section under the Entering Parameters section of the IO_Page Utilities Reference Manual.J EXAMPLES 1. IPU> DEFINE area1 235:984J In this example, the DEFINE command defines area1 as equivalent to the specified range of 235:984.J 2. IPU> DEFINE area2 area1J In this example, the DEFINE command defines area2 as equivalent to area1.J 3. IPU> DEFINE area1J In this example, the DEFINE command deletes the definition for area1.JV EXIT蜕 Exits the IPU session.J FORMAT EXIT HELP蜕 Displays all the IPU commands.J FORMAT HELP PARAMETERS ̝noneJ EXAMPLE 1. IPU> HELPJ The following is a list of IPU commands:J .J .#(List of IPU topics)#J .J ̝IPU> J$ MONITOR蜕 The monitor command allows you to observe a named range and display the activity to a screen or a file.J FORMAT MONITOR namedrange [time] PARAMETERS ̝namedrangeJ Specifies a range of memory address locations as follows:J [%{d|o|x}]START[:[%{d|o|x}][{+|}]END]J For a complete description on defining range specifications, refer to the Range Specifications section under the Entering Parameters section of the IO_Page Utilities Reference Manual.J A symbolic name can also be used in place of a named range. For a complete description on specifying symbolic names refer to the DEFINE command in the IO_Page Utilities Reference Manual.J ̝timeJ Specifies a standard DCL type time specification as either an absolute or a delta time. If a single integer value is specified it is interpreted as seconds.J EXAMPLE J This example monitors the input channel of a DLV11J asynchronous serial line unit for 20 seconds.J ̝IPU> set format ASCIIJ IPU> mon 16502 20J Monitor will continue for the specified time period. J The time period being used is <0 ::20>.J %O17776502 %AIJ %O17776502 %AOJ %O17776502 %APJ %O17776502 %AAJ %O17776502 %AGJ %O17776502 %AEJ Monitor session is exiting. Time period has elapsed.J ̝IPU>Jd READ蜕 Reads a specified range of memory address locations and displays the contents. The data is interpreted according to the size and format settings for the current session.J FORMAT READ [namedrange] PARAMETERS ̝namedrangeJ Specifies a range of memory address locations as follows:J [%{d|o|x}]START[:[%{d|o|x}][{+|}]END]J For a complete description on defining range specifications, refer to the Range Specifications section under the Entering Parameters section of the IO_Page Utilities Reference Manual.J A symbolic name can also be used in place of a named range. For a complete description on specifying symbolic names refer to the DEFINE command in the IO_Page Utilities Reference Manual.J If the namedrange parameter is omitted, the next memory location is displayed.J EXAMPLE 1. This example uses a DLV11J asynchronous serial line unit and the transmit line (16506) is strapped to the read line (16502) to demonstrate how a character is written and then verified by the read.J ̝IPU> set format asciiJ IPU> write 16506 H J IPU> read 16502J %O17776502 %AHJ ̝IPU> write 16506 iJ IPU> read 16502J %O17776502 %AiJV SET蜕 Defines or changes, for the current terminal session, characteristics associated with data format specifications, address radix specifications, and session logging.J FORMAT SET keyword option J PARAMETER J ̝SET keywordsJ ̝baseJ Defines a base address for all subsequent memory range specifications. Base is added to all subsequent entries making base appear as the bottom of the IO_Page region in memory. To show what the default IO_Page region is, use the SHOW IO_Page command.J ̝formatJ Sets the format for displaying the results of all subsequent READ and SHOW commands. The following formats are available:J ̝ASCIIJ BINARYJ DECIMALJ HEXADECIMALJ OCTALJ The default format is OCTAL.J ̝logJ Opens a specified file and starts logging the session. The format for defining a file specification is as follows:J node::device:[directory]filename.type;versionJ For a complete description on defining file specifications, refer to the File Specifications section under the Entering Parameters section of the IO Page Utilities Reference Manual.J The file is closed when you enter a SET LOG command without a file specification.J The default file type is COM.J f Commands and responses are logged. Responses are preceded with an explanation point (!) making them comment lines. You can later submit the log file as an IPU command file.J ̝radixJ Specifies the radix to be used for all subsequent commands. The available options are:J ̝DECIMALJ HEXADECIMALJ OCTALJ The default radix is octal.J ̝sizeJ Specifies the size to used by all subsequent commands. The following sizes are available:J ̝BYTEJ WORDJ The default size is BYTE.J EXAMPLES 1. IPU> SHOW IO_PAGEJ IO_PAGE mapping:J  Base:##((-%o17760000-J  Bottom Address: %o17760000J  Top Address: %o17777776J ̝IPU> SET BASE %o17760008J IPU> SHOW IO_PAGEJ IO_PAGE mapping:J  Base:##((-%o17760008-J  Bottom Address: %o17760000J  Top Address: %o17777776J This example uses the SHOW io_page command to display the current IO_Page mapping when the IPU utility is first started. Then the SET base command is used to change the base address. The subsequent SHOW io_page shows the new base address. Note that the Bottom and Top addresses are static and never change.JZ 2. IPU> SHOW FORMATJ The current format is: OCTALJ ̝IPU> READ BASEJ %o17760000: %o234J ̝IPU> SET FORMAT DECIMALJ The current format is: DECIMALJ ̝IPU> READ BASEJ %o17760000: %d156J This example uses the SHOW FORMAT and READ command to display the current format and the contents of the base address. Next the SET FORMAT command is used to change the current format from octal to decimal. The subsequent READ command shows the changes made by the SET FORMAT command.J 3. IPU> SHOW RADIXJ The current radix is: OCTALJ ̝IPU> READ %o17760000J %o17760000: %o234J ̝IPU> SET RADIX HEXADECIMALJ The current radix is: HEXADECIMALJ ̝IPU> READ %x3fe000J %x3fe000: %o234J This example uses the SHOW RADIX and READ commands do show the initial state of location %o17760000. Next the SET RADIX command is used to change the current radix from octal to hexadecimal. The subsequent read command shows the changes made by the SET RADIX command.J< SHOW蜕 Displays information about the current status of data format and address radix specifications.J FORMAT SHOW keyword [symbolicname]J PARAMETER ̜SHOW keywordsJ ̜̝allJ Displays all available data format, address radix, and symbol definition information for the current terminal session.J ̝baseJ Displays the current base address.J ̝formatJ Displays the current format setting.J ̝io_pageJ Displays the bottom and top address of the IO page and the base address for the current session.J ̝logJ Displays the current log file name if logging is enabled.J ̝radixJ Displays the current radix setting.J ̝sizeJ Displays the current size setting.J ̝symbolJ Displays the specified symbolic name and the range specification associated with the symbol. If no symbolic name is specified all symbols defined for the current session are displayed.J EXAMPLES Refer to the SET command examples.J V WRITE蜕 Writes a specified data element to a memory address location. The data is interpreted according to the size and format specifications for the current terminal session. The format can be explicitly specified using the percent sign (%) operator.J FORMAT WRITE namedrange dataspecification PARAMETERS ̝namedrangeJ Specifies a range of memory address locations as follows:J [%{d|o|x}]START[:[%{d|o|x}][{+|}]END]J For a complete description on defining range specifications, to the Range Specifications section under the Entering Parameters section of the IO_Page Utilities Reference Manual.J A symbolic name can also be used in place of a named range. For a complete description on specifying symbolic names to the DEFINE command in the IO_Page Utilities Reference Manual.J If the named range includes more than one memory location, only the first memory location is written to. The rest of the named range is unaffected.J ̝dataspecificationJ Specifies a single data element to be written into the named range as follows:J [%{a|b|d|o|x}]DATAELEMENTJ For a complete description on defining data specifications, to the Data Specifications section under the Entering Parameters section of the IO Page Utilities Reference Manual.J EXAMPLE Refer to the READ command example.