IMD 1.18: 21/01/2023 18:12:07 PRQ-SFT-MBD-6 3RCC PERQ DOCUMENTATION DISTRIBUTION FLOPPY Copyright (C) Three Rivers Computer Corporation, 1982 single density, double sided D.6 Group name Command file DOCUMENTATION-1 1DOC.CMD  d types, as well as supporting separate compilation. Modules may be separately compiled, and intermodule type checking will d into a module. The declaration includes the name of the module to be imported and the file name of the source file fbe performed as part of the compilation process. Unless an identifier is exported from a module, it is local to that moduleor that module. When compiling an import declaration, the source file containing the module to be imported must and cannot be used by other modules. Likewise all identifiers referenced in a module must be either local to the mo be available to the compiler. Note: If the module is composed of several INCLUDE files, only those files from the fdule or imported from another module. Modules do not contain a main statement body. A program is a special instaile containing the program or module heading through the file which contains the word PRIVATE, must be available. (See "Cnce of a module and conforms to the definition of a ______ ____ ______ ___ ______ program given by tompiler Switches" in this manual.) The syntax for the IMPORTS declaration is: ::= IMPORTS <he PASCAL User Manual and Report [JW74]. Only a program may contain a main body, and every executable group of modules mumodule name> FROM ; - 19 - PERQ Pascal Extensions st contain exactly one instance of a program. Exporting allows a module to make constants, types, variables, procedu 04 Feb 82 13.2 EXPORTS Declaration Section If a program or module is to contain any exports,  functions, as described by the BSI/ISO Pascal Standard [BSI79]. You must put the full description of the procedure parameres and functions available to other modules. Importing allows a module to make use of the EXPORTS of other modules. Gter in the routine header (just as if it was defined by itself). For example: Procedure EnumerateAll (directory: Strlobal constants, types, variables, procedures and functions can be declared by a module to be private (available only to coding; Function for each one (filename: String): boolean; all:boolean); Note that if the procedure ise within the module) or exportable (available within the module as well as from any other module which imports them).  forward declared or in an export section, the routine header for this procedure cannot be repeated Modules which contain only type and constant declarations cause no run-time overhead; making them ideal for common declarati - 18 - PERQ Pascal Extensions 04 Feb ons. It should also be noted that such modules may not be compiled (as errors will be produced), however they may be succes82 13. Modules The module facility provides the ability to encapsulate procedures, functions, data ansfully imported. 131 IMPORTS Declaration The IMPORTS Declaration specifies the modules which are to be importe j[.J ~[BJ #S[;J % N[J I&Z[ J &@'J &8"[FJ h Rr[iJ sQQ"[#J  ;d[J dvn[&J j[J H wR[J `w [J oJ d ection. Only forward references are given. (See "Declaration Relaxation" in this manual.) (See Chapter 11.2 in  used for error conditions. There are three steps to using an exception: 1) The exception must be declared. the "PASCAL User Manual and Report" [JW74].) The inclusion of "FORWARD;" in the EXPORTS reference is omitted. The EX 2) A handler for the exception must be defined. 3) The exception must be raised. An exception is declaredPORTS Declaration section is terminated by the occurrence of the word PRIVATE. This signifies the beginning of the declarati by the word EXCEPTION followed by its name and optional list of parameters. For example: EXCEPTION Divisions which are local to the module. The PRIVATE Declaration section must contain the declarations and bodies for all proceonByZero(Numerator : integer); Exceptions can be declared anywhere in the declaration portion of a program or module. dures and functions defined in the EXPORTS Declaration section. If a program is to contain no EXPORTS Declaration sec The second step is to specify the code to be executed when the exception condition occurs. This is done by defining a tion, the inclusion of PRIVATE following the program heading is optional (PRIVATE is assumed). (Note: A module wi handler with the same name and parameter types as the declared exception, for example: HANDLER Divisith no EXPORTS would be useless, since its contents could never be referenced -- it only makes sense for a program not to honByZero(Top : integer); (See "Declaration Relaxation" in this document for a definition of ::= | .) Essentially, a handler looks like a procedure with the word HANDLER substituted for the word PROCEDURE. Handlers may am> ::= . ::= . ::= Pppear in the same places procedures are allowed, with one difference. Handlers cannot be global to a module (they may, howevROGRAM ( {, }); ::= MODULE ; ::= EXPORTS PRIVATE | PRIVATE | - 20 - PERQ Pascal Extensions ons are given as previously specified with one exception: procedure and function bodies are not given in the exports s 04 Feb 82 14.0 Exceptions PERQ Pascal provides an exception handling facility. Exceptions are typically o[J sQQ"[#J   aJ JJHJLH v=H,=H HHJHvJJKHv(v' ' rHJr HJv'v=H'w,w``I vw(w,w``v``v I wv(w,w```v xτ}vv'v=H'  hav,VvI'JvI'>vI'7tJ*tHH,uJ*uHH, \(]``c}mH`}( =H o)&  H `% c}ɺan' n'ώ {L'mL* \L` = o)B& *HJ  H ̶\wn' h #`Jm\>m``m``&m&m &m LHLLJL ception declaration but the names of the parameters may be different. Multiple handlers can exist for the same exception as  In this case the search continues down the run-time stack until a non-active handler is found. A handler cannotlong as there is only one per name scope. The exception must be declared before its handler(s). Raising an exception, therefore, invoke itself by raising the same exception it was meant to handle. If a recursive procedure contains a handler is analogous to a procedure call. The word RAISE appears before the name and parameters of the exception, for example: , each activation of the procedure has its own eligible handler. - 22 - PE RAISE DivisionByZero(N); causes the appropriate handler to execute. The appropriate handler is determinRQ Pascal Extensions 04 Feb 82 If an exception is raised for which no handler ed by the current subprogram calling sequence. The run-time stack is searched until a subprogram containing a handler ( is defined or eligible, the system catches the exception and invokes the debugger. A facility is provided to allow the uof the same name) is found. The search starts from the subprogram which issues the RAISE. ser to catch such exceptions before the system does. Handlers can be defined for the predefined exception ALL:  - 21 - PERQ Pascal Extensions 04 Feb 82 For example: program EXCEPTION ALL(ES,ER,PStart,PEnd : integer); where 1) ES is the system segment number of the exception, ExampleException; exception Ex; handler Ex; begin writeln('Global Handler for exception Ex' 2) ER the routine number of the exception, 3) PStart the stack offset of the first word of the exception's ); end; procedure Proc1; begin raise Ex; end; procedure Proc2; ha original parameters and, 4) PEnd the stack offset of the word following the original parametndler Ex; begin writeln('Local Handler for exception Ex') end; begin raise Exers. Any raised exception that does not have an eligible handler in the same or suceeding level (of the calling se; Proc1; end; begin raise Ex; Proc2; Proc1; end. produces the followinquence), in which an ALL handler is defined, is caught by that ALL handler. The four integer parameter values are calculateg output: Global Handler for exception Ex Local Handler for exception Ex Local Handler for exception Ex d by the system and supplied to the ALL handler. Extreme caution should be used when defining an ALL handler, as the handler Global Handler for exception Ex Handlers which are already active are not eligible for reactivation. will also catch system exceptions. All cannot be raised explicitly. The ability to define ALL handlers is intended for o have a general grasp of computers and computerized editors. Some experience or familiarity with a similar editorables you to read the HELP file while you are editing. Copy it to a scratch file so that you won't have to worry about  is helpful. Copyright (C) 1981 Three Rivers Computer Corporation 720 Gross Street Pittsaccidentally changing it. Do this with the system "Copy" command: Copy Editor.Help Scratch.File Now ask the Editor burgh, PA 15224 (412) 621-6250 Editor V1.9 Quick Guide 17 Jul 81 to edit this new scratch file: Edit Scratch.File The PERQ Text Editor is a "point, act" editor. This means that This document is not to be reproduced in any form or transmitted in whole or in part, without the pri to perform an editing action, you first "point" to a piece of text in the file and then perform some action on it. Pointinor written authorization of Three Rivers Computer Corporation. The information in this document is subject tg is done on the tablet using either a BitPad pen or a four-button puck. Your PERQ probably has a Summagraphics BitPad tao change without notice and should not be construed as a commitment by Three Rivers Computer Corporation. The Comblet. The BitPad pen contains a switch in the point of the pen. When you press the pen on the tablet, it closes the swipany assumes no responsibility for any errors that may appear in this document. Three Rivers Computer Corporation will make every effort to keep customers apprised of all documentation changes as quickly as possible. The Reader's Comments card is distrib- uted with this document to request users' critical evalu- ation to assist us in preparing future documentation. PERQ is a trademark of Three Rivers Computer Corporation.  Editor V1.9 Quick Guide John P. S - ii - Editor V1.9 Quick Guide trait This manual describes version 1.9 of the PERQ Text Editor. It includes a small amount of 17 Jul 81 ____________ Introduction It is a good idea to sit down at a PERQ and try out the E overview and philosophy behind the Editor and contains a list of the commands available. The reader is expected tditor as you are reading. A good file to edit when you are experimenting with the Editor is the Editor's HELP file. This en ERQ's memory architecture which require extensions to the standard allocation procedures. First, there are situations NEW cannot be performed, a NIL pointer is usually returned. However, if memory is exhausted, the FULLMEMORY exception ma which require particular alignment of memory buffers, such as IO operations. Second, PERQ supports multiple data segmy be raised. If the call to NEW fails and raises FULLMEMORY, the user program will abort unless it ents from which dynamic allocation may be performed. This facilitates grouping data together which are to be accessed - 24 - PERQ Pascal Extensions 04 Feb 82 includes a handler for  "systems hackers" only. The operating system provides several default handlers. Information on these handle together, which may improve PERQ's performance due to improved swapping. Data segments are multiples of 256 words in sizers can be found in the "Program System" and "Module Except" descriptions in the Operating System Manual. Since exceptio and are always aligned on 256 word boundaries. For further information of the memory architecture and availablens are generally used for serious errors, careful consideration should be given as to whether or not execution should be res functions see the documentation on the memory manager. 15.1 NEW If the standard form of the NEW procedure callumed after an exception is raised. When a handler terminates, execution resumes at the place following the RAISE stat is used: NEW(Ptr{,Tag1,...TagN}) memory for Ptr will be allocated with arbitrary alignment fromement. The handler can, of course, explicitly dictate otherwise. The EXIT and GOTO statements may prove useful here ( the default data segment. The extended form of the NEW procedure call is: NEW(Segment,Alignment,Ptr{See "Control Structures" in this manual.) - 23 - PERQ Pascal Ext,Tag1,...TagN}) Segment is the segment number from which the allocation is to be performed. This number is returneensions 04 Feb 82 15.0 Dynamic Space Allocation and Deallocation The PERQ d to the user when creating a new data segment. The value 0 is used to indicate the default data segment. Alig Pascal Compiler supports the dynamic allocation ______ ____ ______ prnment specifies the desired alignment; Any power of 2 to 256 (2**0 through 2**8) is permissable. Do not use zero to specifyocedures NEW and DISPOSE defined on page 105 of PASCAL User Manual ___ ______ and Report [JW74], along with several upwa the desired alignment. If the extended form of NEW is used, both a segment and alignment must be specified; there isrd compatible extensions which permit full utilization of the PERQ memory architecture. There are two features of P no form which permits selective inclusion of either characteristic. If the desired allocation from any call to w the puck. The pointer changes shape depending on where it is on the screen. It may be a up-and-left pointing arrow, aracter, word, or line with the tablet. After selecting text, you can perform some action on it. You can insert ban up-pointing arrow, a down-pointing arrow, or a circle. These different shapes indicate that different things will happefore or after the selected text, delete the selected text, search for a character string starting at the beginning of the seen when you press. Pointing at text (also called selecting text) is done by pressing on the tablet when the polection, or any of the other Editor actions. The top line of the screen shows the command prompt, error messages, and promptsinter is an up-and-left-pointing arrow. If you move the pointer to some character and then press the yellow button, the cha within commands. Most Editor commands require termination by either accepting or rejecting the action. Acceptance iracter is selected by underlining it. Press the white button, and a word is selected by an underline. If you press the s signalled by typing the INS key. Rejection is signalled by typing the DEL key. When typing text to the Editogreen button, the entire line is selected. You can also select a word by pressing twice in the same place with the yellow r, BACK SPACE deletes the most recently typed character, control-BACK SPACE deletes the most recently typed word, anbutton. If you press the yellow button three times, the entire line is selected. Another way to select an entire line is to d control-OOPS deletes the most recently typed line up to and including the carriage return. The RETURN key (carriage retu move the pointer until it points at the left margin line. One press here selects the entire line. Once you havern) is used to mark the end of each line in your file. The Editor does automatic indenting for you by supplying leading bl selected some text, you can extend the selection by moving the puck to another piece of text and then typing "E" or pressianks on the new line to match those on the previous line. You may BACK SPACE over them or type more. When the first litch. Throughout this document we describe the use of the puck which has cross-hairs and four buttons: yellow, whitng the blue button. The selection is extended to a character, word, or line boundary, depending on the type of your e, green and blue. This description also applies to the use of the pen with one qualification: the pen switch actslast selection. Commands that change the selection (other than Extend) set the type to character. You can make the selec like the yellow button of the puck. In this manual, the term "press" means to press one of the switches on the puck or prtion larger with Extend, but you cannot make it smaller. To make the selection - 1 ess the pen on the tablet. When you move the puck on the tablet, the pointer (cursor) moves on the screen to follo- Editor V1.9 Quick Guide 17 Jul 81 smaller, you must start over by selecting a ch  the procedure (hence there is no procedure call overhead associated with their use). The syntax for the logical functRQ Pascal Extensions 04 Feb 82 17. Input/Output Intrinsics ions are described in the following sections. 16.1 And Function LAND(Val1,Val2: integer): integer;  ______ ____ PERQ's Input/Output intrinsics vary slightly from PASCAL User ______ LAND returns the bitwise AND of Val1 and Val2. 16.2 Inclusive Or Function LOR(Val1,Val2: integer): integer___ ______ Manual and Report [JW74]. 17.1 REWRITE The REWRITE procedure has the following form: ; LOR returns the bitwise INCLUSIVE OR of Val1 and Val2. 16.3 Not Function LNOT(Val: integer): i REWRITE(F,Name) F is the file variable to be associated with the file to be written and Name is a string contanteger; LNOT returns the bitwise complement of Val. 16.4 Exclusive Or Function LXOR(Val1,Val2: inteining the name of the file to be created. EOF(F) becomes true and a new file may be written. The only ger): integer; LXOR returns the bitwise EXCLUSIVE OR of Val1 and Val2. 16.5 Shift Function SHIFT(Value ______ ____ ______ ___ ______ difference between the PERQ and PASCAL User Manual and Report[JW74] RFULLMEMORY. 15.2 DISPOSE ______ ____ DISPOSE is identica, Distance: integer): integer; SHIFT returns Value shifted Distance bits. If Distance is positive, a left shiftl to the definition given in PASCAL User ______ ___ ______ Manual and Report [JW74]. Note that the segment and ali occurs, otherwise, a right shift occurs. When performing a left shift, the Least Significant Bit is filled with a 0, and lignment are never given to DISPOSE, only the pointer and tag field values. kewise when performing a right shift, the Most Significant Bit is filled with a 0. - - 25 - PERQ Pascal Extensions  26 - PERQ Pascal Extensions 04 Feb 82 16.6 Rotate Function ROTAT 04 Feb 82 16. Single Precision Logical Operations The PERQ Pascal compiler supports a variety ofE(Value, Distance: integer): integer; ROTATE returns Value rotated Distance bits. If Distance is positive a righ single precision (INTEGER) logical operations. The operations supported include: and, inclusive or, not, exclusive or, t rotate occurs, otherwise a left rotate occurs. Note that the direction of the ROTATE is the opposite of SHIFT. shift and rotate. The syntax for their use resembles that of a function call; however the code is generated inline to - 27 - PE hen the last character of the file is showing on the screen, it is followed by a " "--this is the end-of-text marker.ly upper case text characters. If the target string is found, it becomes the selected text. Note that the target string You may select this character, but try as you may, you cannot delete it. ______ ________ Editor Commands  is shown at the top of the screen inside of F{ ... } . A Find command can be done in the revers A - Append text after the selection. Type text until you are done, then either accept or reject the insertion. Ie direction (toward the beginning of the file). See the section "Direction of Find and Replace" in this manual. Youf you accept immediately after typing "A", the most recently inserted or deleted text is inserted. If you acce can ask the Editor to search for a certain number of occurrences of the target string by preceding the command witpt, the text you have just typed is displayed at the top of the screen inside of I{ ... } . D - Deleh a number. See the section "Repeat Count for Find and Replace" in this manual. I - Insert text before the selectionte the selected text. If you delete text, it is displayed at the top of the screen inside of D{ ... } . Type text until you are done, then either accept or reject the insertion. If you accept immediately after ty. The character which immediately follows the deleted text is selected. ping "I", the most recently inserted or deleted text is inserted. If you accept, the text you have just typed is - 2 - Editor V1.9 Quick Guide 17 Jul 81 E - Extend the selection to the curr displayed at the top of the screen inside of I{ ... } . Q - Quit from the Editor. When you type "Q", thent position of the pointer. F - Find a character string starting at the beginning of the selected text. Whene screen is erased, and a list of options is presented. U to update W to write  you type "F", the top line shows the prompt Find: enter target string Type the string you want to search forto another file E to exit without updating R to return to the Editor : Type one of  and then accept or reject the string. Rejecting aborts the Find command. If you accept immediately after typing these letters followed by the RETURN key. You may change your mind and select another letter before typing RETURN. "F", the previous target string (shown in the 'F' line at the top of the screen) is used. Lower case letters in tIf you update or write to a file that already exists, the Editor saves the old version of the file by adding a "$" to the ene of text is showing on the screen, it is indicated by a " " in the left margin--this is the beginning-of-text marker. Whe target will match either upper or lower case letters in the text. Upper case target characters will match on s true and F^ is undefined. 17.3 READ/READLN PERQ Pascal supports extended versions of the READ and READLN es defined by PASCAL User Manual and Report [JW74]. Due to the scope of these extensions, the WRITE and WRITELN procedure ______ ____ ______ ___ ______ procedures defined by PASCAL User Manual and Report [JW74]. Along withs are completely redefined below: 1. write(p1,...,pn) stands for write(output,p1,...,pn) 2. write(f,p1,... the ability to read longs, integers (and subranges of integers), reals and characters, PERQ Pascal also supports reading ,pn) stands for BEGIN write(f,p1); ... write(f,pn) END 3. writeln(p1,...,pn) stands for writeln(output,p1,. booleans, packed arrays of characters, and strings. The strings TRUE and FALSE (or any unique abbreviations) are ..pn) 4. writeln(f,p1,...,pn) stands for BEGIN write(f,p1); ... write(f,pn); writeln(f) END  valid input for parameters of type boolean. Mixed upper and lower case are permissible. If the parameter to be re 5. Every parameter pi must be of one of the forms: e e : e1 e : e1 : e2 ad is a PACKED ARRAY[m..n] of CHAR, then the next n-m+1 characters from the input line will be used to fill the array. If t where e, e1 and e2 are expressions. 6. e is the VALUE to be written and may be of type CHAR, long, here are fewer than n-m+1 characters on the line, the array will be filled with the available characters, starting at the integer (or subrange of integer), real, boolean, packed array of char, or string. For parameters of type m'th position, and the remainder of the array will be filled with - 28 - PER boolean, one of the strings TRUE, FALSE or UNDEF will be written; UNDEF is written if the internal Q Pascal Extensions 04 Feb 82 blanks. If the parameter to be read is of type form of the expression is neither 0 nor 1. 7. e1, the minimum field width, is optional. In general, the EWRITE is the inclusion of the filename string. 17.2 RESET The RESET procedure has the following form: STRING, then the string variable will be filled with as many characters as possible until either the end of the input  RESET(F,Name) F is the file variable to be associated with the existing file to be read and Name is a sline is reached or the maximum length of the string is met. If there are not enough characters on the line to fill the enttring containing the name of the file to be read. The current file position is set to the beginning of file, i.e. RESET assiire string, the dynamic length of the string will be set to the number of characters read. 17.4 WRITE/WRITELN PEgns the value of the first element of the file to F^. EOF(F) becomes false if F is not empty; otherwise, EOF(F) becomeRQ Pascal provides many extensions to the WRITE and WRITELN ______ ____ ______ ___ ______ procedur If you accept, the prompt Replace: enter replacement string is shown at the top of the screen. Now you can t 17 Jul 81 After substituting, the character immediately following the deleted text is selecype in the new string which will replace occurrences of the target string. If you accept before typing any charated. Be careful with this command. It is easy to confuse Substitute with Replace. There is no way to "undo" a nd of its name. This allows you to get the old version back if you decide you made a mistake. You can safely edicters of the replacement string, the previous replacement string is used. This means that to replace with notht the backup file since it has a different name than the new version of the file. -ing, you must first type a character and then delete it with the BACK SPACE key. In the absence of a repeat count, 3 - Editor V1.9 Quick Guide 17 Jul 81 While it is never a good idea to type  all occurrences within the selection are replaced. If a repeat count is typed immediately before the "R", a scontrol-C while you're in the Editor, you should not type it while the Editor is writing the new copy of your fipecified number of occurrences are replaced, starting at the beginning of the selection. See the section "Repeat Counle. You will lose the new version of your file, and the old version will be in the backup file. If you type contt for Find and Replace" in this manual. The direction can be changed in the same way as for the Find command.rol-C before writing the new file or type "E" to exit without updating, your file will remain unchanged regard- les See the section "Direction of Find and Replace" in this manual. S - Substitute new text for the selected text. Ts of any changes you made with the Editor. R - Replace occurrences of a character string with another character stringhis command is similar to the sequence "Insert, Delete". Type the desired text, then either accept or reject t inside the selected text. Typing "R" causes the prompt Replace: enter target string at the top of the screhe insertion. If you accept immediately after typing "S", the most recently inserted or deleted text is inserteden. Type in a string and then accept or reject. Note that the target string is displayed inside of F{ .... If you accept, the text you have just typed is displayed at the top of the screen as the most recently inserted tex } just as though you were using the the Find command. Lower case letters in the target will match either uppet inside of I{ ... } and the text you have just deleted is displayed at the top of the screen insr or lower case letters in the text. Upper case target characters will match only upper case text characters. ide of D{ ... } . - 4 - Editor V1.9 Quick Guide  ller than the number of characters required to print the given value, more space is allocated; if e is es. PERQ Pascal supports a procedure, STARTIO, to facilitate generation of the correct QCode sequence for I/O programming. Ta packed array of char, then only the first e1 characters of the array will be printed. he procedure call has the following form: STARTIO(Unit) where Unit is the hardware unit num - 29 - PERQ Pascal Extensions 04 Feb 82 8. e2, which is opber of the device to be activated. 18.2 RasterOp RasterOp is a special QCode which is used to manipulate blocks of tional, is applicable only when e is of type long, integer (or subrange of integer) or real. If e is of  memory of arbitrary sizes. It is especially useful for creating and modifying displays on the screen. RasterOp modifietype long or integer (or subrange of integer) then e2 indicates the base in which the value of e is to be prins a rectangular area (called the "destination") of arbitrary size (to the bit). The picture drawn into this rectangle ited. The valid range for e2 is 2..36 and -36..-2. If e2 is positive, then the value of e is prs computed as a function of the previous contents of the destination and the contents of another rectangle of the saminted as a signed quantity (16-bit twos complement); otherwise, the value of e is printed as a full 16-e size called the "source". The functions performed to combine the two pictures are described below. To allow Rasbit unsigned quantity. If e2 is omitted, the signed value of e is printed in base 10. If e is of tyterOp to work on memory other than that used for the screen bitmap, RasterOp has parameters that specify the areas of mpe real, then e2 specifies the number of digits to follow the decimal point. The number is then printed in emory to be used for the source and destination: a pointer to the start of the memory block and the width of the block in w fixed-point notation. If e2 is omitted, then real numbers are printed in floating-point notation. ords. Within these regions, the positions of the source and destination rectangles are given as offsets from the pointer.  - 30 - PERQ Pasca Thus position (0,0) would be at the upper left corner of the region, and, for the screen, (767, 1023) would be tl Extensions 04 Feb 82 18. Miscellaneous Intrinsics 18.1 StartIO STARTIhe lower right. The operating system module Screen exports useful parameters.  value e is written with e1 characters (with preceding blanks). With one exception, if e1 is smaO is a special QCode (See the PERQ QCode Reference Manual) which is used to initiate input/output operations to raw devic or arrow (if you keep the puck away from the tablet). This double underline is difficult to see, but it's there. You m _________ __ ____ ___ _______ Direction of Find and Replace Typing a ">" sets the forward directionay now accept the replacement with INS, you may skip over this occurrence by typing the space-bar, or abort the r (toward the end of the file) for Find and Replace commands. "." and "+" are synonyms for this command. Note that wheneplace command with DEL. X - Redraw the screen. Use this command if you think the text shown on the screen is no you type one of these, a ">" is displayed in the upper, left-hand corner of the screen. This always shows the current dirt what is really in your file. If it comes up wrong again, you lose. * - Select the entire file from beginning to eection. Typing a "<" sets the reverse direction (toward the beginning of the file) for Find and Replace commands.nd. INS - Repeat the last command. Typing the INS key at command level repeats the last command. Only certain comma "," and "-" are synonyms for this command. Note that when you type one of these, a "<" is displayed in the upper, leftSubstitute command because you cannot re-insert the deleted text. Attempting to re-insert the most recently insert- nds may be repeated this way, since it is unnecessary to repeat some commands (e.g., "*", "E"). The "A", "D", "F", "I ed or deleted text will merely re-insert the text you just typed in. The deleted text is gone forever. This means th", "R", and "S" commands may be repeated this way. HELP - Get help. Typing the HELP key at command level enters that if you type "S" when you means to type "R", you may accidentally delete a large portion of your file and have no wae online help facility. - 5 - Editor V1.9 Quick Guide y of getting it back. V - Toggle Verify mode. When you type "V", Verify mode is turned on or off, depending on wh 17 Jul 81 ______ _____ ___ ____ ___ _______ Repeat Count for Find and Replace ether it was off or on before. When Verify mode is on, a "V" is displayed in the upper, right-hand corner of the  Typing a 1- to 4-digit number before a Find or Replace command specifies the number of occurrences of the target string tscreen. In Verify mode the Replace command gives you the option of replacing, not replacing, or aborting at each occhat you want to find or replace. This number is displayed in the top, right-hand corner of the screen after the letteurrence of the target string. The prompt Replace: INS replaces, doesn't, DEL aborts is displayed fr "R" (which stands for "repeat count"). The number of occurrences actually found or replaced is displayed in the same or each occurrence of the target string. The target string is indicated by a double underline and by the curscorner following the letter "C" (which stands for "count"). This number increments as the Find or Replace command executes. Or Dst gets Dst OR Src 5 ROrNot Dst gets Dst OR NOT Src 6 RXor  MUST be quad-word aligned, however. ( See "New" in this document for details on buffer alignment.)  Dst gets Dst XOR Src 7 RXNor Dst gets Dst XNOR Src The symbolic names are expor "Source-X-Position" is the bit offset of the left side of the source rectangle. The value is  - 31 - PERQ Pascal Extensions 04 Feb 82 The compiler sted by the file "Raster.Pas". "Width" specifies the size in the horizontal ("x") direction of the source anupports a RASTEROP intrinsic which may be used to invoke the RasterOp QCode. The form of this call is: RASTEROP(Fd destination rectangles (given in bits). "Height" specifies the size in the vertical ("y") direction of tunction, Width, Height, Destination-X-Position, Destinathe source and destination rectangles (given in scan lines). "Destination-X-Position" is the bit offset of the left sidion-Y-Position, Destination-Area-Line-Length, Destination-Memory-Pointer, e of the destination rectangle. The value is offset from Destination-Memory-Pointer (see below).Source-X-Position, Source-Y-Position, Source-Area-Line-Length, Source-Memo - 32 - PERQ Pascal Extensions 04 Feb 82 ry-Pointer) Note: the values for the destination precede those for the source. The arguments to RasterOp are defined  "Destination-Y-Position" is the scan-line offset of the top of the destination rectangle. The vabelow: "Function" defines how the source and the destination are to be combined to create the final lue is offset from Destination-Memory-Pointer (see below). "Destination-Area-Line-Length" is the numberpicture stored at the destination. The RasterOp functions are as follows: (Src represents the sourc of words which comprise a line in the destination region (hence defining the region's width). The e and Dst the destination): Function Name Action -------- ---- ------  appropriate value to use when operating on the screen is 48. The specified value must be a multiple 0 RRpl Dst gets Src 1 RNot Dst gets NOT Src 2  of four (4) and within the range 4 through 48. "Destination-Memory-Pointer" is the 32-bit virtual address of the  RAnd Dst gets Dst AND Src 3 RAndNot Dst gets Dst AND NOT Src 4 R top left corner of the destination region (it may be a pointer variable of any type). This pointer  if you put the pointer near the top of the screen, by pressing repeatedly, you can scroll slowly through the file. If ythe beginning of the file is shown, when you press the " " the end of the file is shown, and when you press the "S" the begou put the pointer near the bottom of the screen, you can move through the file in large jumps of pages. If you put the poiinning of the selection is shown. The thumb bar can also be used to extend the selection. When you type "E" or prnter near the middle of the screen, you can move through the file in half-page jumps. When using the puck in the scrolless the blue button while the pointer is on the thumb bar, the selection is extended to the position in the file which is bar, you need not worry about whether the arrow points up or down. The white button always scrolls up, and the green  represented by that particular portion of the thumb bar. This is only useful for extending to the beginning or end of thbutton always scrolls down. - 6 - Editor V1.9 Quick Guide e file. - 7 - Editor V1.9 Quick Guide  17 Jul 81 ___ _____ ___ The Thumb Bar The top-margin line is called the "thumb bar" 17 Jul 81 _______ __________ Special Characters ______ _________ . When you move the pointer to this line, it changes into a circle. Think of the thumb bar as a linear representation of _________ Action Character Alternate End-of-line RETURN control-M,cont your file. The left end of the bar represents the beginning of your file. Special characters are used to represent other rol-J -or- control-M,LF Erase character BACK SPACE control-H Erase -hand corner of the screen. This always shows the current direction. ___ ______ ___ The Scroll Bar interesting parts of your file. - Represents the end of the file. S - Represents the position of the beThe area to the left of the left-margin line is called the "scroll bar". If you move the pointer into this bar, it chginning of the selection. ( - Represents the position of the beginning of the displayed texanges into an up-pointing arrow at the left side and a down-pointing arrow at the right side. If you press the yellow button t. ) - Represents the position of the end of the displayed text. The thumb bar is used to rapidly mwhen the arrow is pointing up, the line that the pointer is next to is scrolled to the top of the screen. If you press when tove around in your file, but it is not very precise. When you put the pointer on the thumb bar and press down, the portionhe arrow is pointing down, the top line of the screen is scrolled down to the line that the pointer is next to. Thus,  of the file represented by that portion of the bar is displayed on the screen. When you press at the left end of the bar  ed for any item which has a size associated with it. This includes constants, types, variables and functions. The i or function. (See "Routine Calls and Returns" for a description of LVRD and CALLV in the QCode Reference Manual.) ntrinsic takes a single parameter, the item whose size is desired, and returns an integer. Note: WordSize generates compil The variable routine descriptor is left on the expression stack of the PERQ, and any further operations must be performede time constants, and hence may be used in constant expressions. - 33 - PERQ by the user. This procedure takes one parameter, the name of the function or procedure for which the variable routine des Pascal Extensions 04 Feb 82 18.4 MakePtr The MakePtr intrinsic permits thcriptor is to be loaded. The use of this intrinsic assumes that the programmer is familiar with QCode (primarily a "hacke user to create a pointer to a data type given a system segment number and offset. Its use is intended for those wer's" intrinsic). 18.6 InLineByte InLineByte permits the user to place explicit bytes directly into the code st offset from Source-Memory-Pointer (see below). "Source-Y-Position" is the scan-line offset of the top ho are familiar with the system and are sure of what they are doing. The function takes three parameters. The first two are of the source rectangle. The value is offset from Source-Memory-Pointer (see below).  the system segment number and offset within that segment to be used in creating the pointer, respectively, given as integers "Source-Area-Line-Length" is the number of words which comprise a line in the source region (hence defin. The last parameter is the type of the pointer to be created. MakePtr will return a pointer of the type named by the thirding the region's width). The appropriate value to use when operating on the screen is 48. The speci parameter. Note: The next seven intrinsics, MakeVRD, InLineByte, InLineWord, InLineAWord, LoadExpr, LoadAdr and fied value must be a multiple of four (4) and within the range 4 through 48. "Source-Memory-Pointer" is the 3StorExpr, require that the user have knowledge of how the compiler generates code (which will not be discussed here). Thes2-bit virtual address of the top left corner of the source region (it may be a pointer variable ofe intrinsics are intended for "system hacking", and are made available for those who know what they are doing. The program any type). This pointer MUST be quad-word aligned, however. (See "New" in this document for details mer who wishes to experiment with these may find the QCode disassembler, QDIS, is very useful to determine if the desired  on buffer alignment.) 18.3 WordSize The WordSize intrinsic returns the number of words of storage requirresults were produced. 18.5 MakeVRD MakeVRD is used to load a variable routine descriptor for a procedure   Since these special keys are pre-defined, in order to insert them into your file you must type control-" (the Edck Guide 17 Jul 81 To replay a transcript, type "Editor/Replay". The Editor itor quote character) followed by the special key. When you type control-", the insert cursor changes from "_" to " " to  replays the previous edit session and stops just before the first command. You can control the replay by typing one of theindicate you typed the quote character. _________________ Transcript/Replay The Editor writes a tr following keys: SPACE stop replaying after the next character or puck press. CR stop replaying after a anscript file during every edit session. The transcript is a file which contains a description of every keystroke and pcarriage return in I command or after next command if not in I command. LF stop replaying after next couck or pen press performed during an edit session. This transcript is written to the file ">Editor.Transcript". The trammand. INS begin replaying and stop when one of the above keys is typed. DEL exit replay modenscript may be replayed later. This feature is intended for use when the Editor or the PERQ crashes during an edit session or. If no DEL key is typed, the Editor automatically exits from replay mode when the end of the transcript is reach if you make some disasterous error with the Editor. The Editor saves keystrokes and presses and writes them to the ted. Once you have exited replay mode you can begin editing normally, but we suggest that you Quit-Update as soon as pranscript file whenever: 1) A carriage-return is typed in Insert mode. 2) A command which changes the text is succossible. - 9 essfully completed. 3) The transcript buffer is filled. If an old transcript file exists, it is destroyed the - Editor V1.9 Quick Guide 17 Jul 81 _____ __ ________ Table of Contents first time the buffer is flushed. This means that you can re-enter the Editor without destroying the old transcript file  1 Introduction 2 Editor Commands 2 A - Append Text After the Selection 2 D - Delete thas long as you do not do something that causes the buffer to be flushed. Keep in mind that presses count against the 256-wore Selected Text 3 E - Extend the Selection 3 F - Find a Character String 3 I - Insert Text Before word control-BACK SPACE control-W Erase line control-OOPS control-U Accept INS d buffer. If you do not want to destroy the old transcript file, do not type any commands, do not press more than a few  control-Y Reject DEL control-N Quote control-" -none- times, and exit the Editor by typing control-shift-C. - 8 - Editor V1.9 Qui  cal Extensions 04 Feb 82 will be inserted immediately as the next two bytes of the coation must not require any address computation; the destination must be a local, intermediate or global variable; it must node stream (no word alignment is performed). The type of this parameter must be either integer or subrange of integer. t be a VAR parameter; if it is a record, a field specification may be given. 18.12 Float The Float intrinsic co18.8 InLineAWord InLineAWord permits the user to place explicit words directly into the code stream generated by tnverts an integer into a floating point number. - 35 - PERQ Pascal Extensiohe compiler. This intrinsic is particulary useful for insertion of direct QCodes into a program. InLineAWord requirens 04 Feb 82 18.13 Stretch The Stretch intrinsic converts a single precisis one parameter, the word to be inserted. This word is placed on the next word boundary of the code stream. The type of on integer to a double precision integer. 18.15 Shrink The Shrink intrinsic converts a double precision integethis parameter must be either integer or subrange of integer. 18.9 LoadExpr The LoadExpr intrinsic takes an ar to a single precision integer. If the double precision integer is outside the range of -32768 to +32767, a runtime error orbitrary expression as its parameter and "loads" the value of the expression. The result of the "load" is wherever the pccurs. - 36 -articular expression type would normally be loaded (expression stack for scalars, memory stack for sets, etc.). 18.10 Load PERQ Pascal Extensions 04 Feb 82 19. Command Line and Compiler Switches ream generated by the compiler. This intrinsic is particulary useful for insertion of actual QCodes into a programAdr The LoadAdr intrinsic loads the address of an arbitrary data item onto the expression stack. The parameter to Load. InLineByte requires one parameter, the byte to be inserted. The type of this parameter must be either integer or subrange Adr, the item whose address is desired, may include array indexing, pointer dereferencing and field selections. The addresof integer. 18.7 InLineWord InLineWord permits the user to place explicit words directly into the code stream s which is left on the expression stack will be a virtual address if the parameter includes either the use of a VAR paragenerated by the compiler. This intrinsic is particulary useful for insertion of direct QCodes into a program. InLmeter or a pointer dereference; otherwise a 20-bit stack offset will be loaded. 18.11 StorExpr StorExpr storesineWord requires one parameter, the word to be inserted. This word - 34 - PERQ Pas the single word on top of the expression stack in the variable given as a parameter. The destination for the store oper  have been modified: - Find can ignore the case of the text. - Find and Replace can be interrupted with control_______ Introduction It is probably a good idea to sit down at a PERQ and try out the Editor as you are readingthe Selection 3 Q - Quit from the Editor 4 R - Replace Occurrences of One String with Another 4 S -C. - The reverse direction flag (<) is turned off by most commands. - The verify flag (V for Replace Comm- Substitute New Text for the Selected Text 5 V - Toggle Verify Mode 5 X - Redraw the Screen 5 * -and) is turned off by most commands. - The replot function is invoked by Q,R,Return (not X).  Select the Entire File 5 INS - Repeat the Last Command 5 HELP - Get Help 6 Repeat Count for Find  Copyright (C) 1981 Three Rivers Computer Corporation 720 Gross Street Pittsburgh, PA 15224 (412) 621-6250and Replace 6 Direction of Find and Replace 6 The Scroll Bar 7 The Thumb Bar 8 Special C Editor V2.0 User's Guide 02 Feb 82 This document is notharacters 8 Transcript/Replay  to be reproduced in any form or transmitted in whole or in part, without the prior written authorization of Th - iii - ree Rivers Computer Corporation. The information in this document is subject to change without notice and sho Editor V2.0 User's Guide John P. Strait uld not be construed as a commitment by Three Rivers Computer Corporation. The Company assumes no responsibility  W. J. Hansen This manual describes version V2.0 of the PERQ text editor. It includes a for any errors that may appear in this document. Three Rivers Computer Corporation will make every effort to small amount of overview and philosophy behind the Editor and contains a list of the commands available. The reader keep customers apprised of all documentation changes as quickly as possible. The Reader's Comments card is distrib is expected to have a general grasp of computers and computerized editors. Some experience or familiarity with a- uted with this document to request users' critical evalu- ation to assist us in preparing future documentation.  similar editor is helpful. _______ Changes The major feature introduced with this version o PERQ is a trademark of Three Rivers Computer Corporation: f the editor is a set of commands to control the selection from the keyboard. A few features of the editor  - ii - Editor V2.0 User's Guide 02 Feb 82 _____  tFile> is the name of the source file to be compiled. The compiler searches for . If it does not find , it appends the extension ".PAS" and searches again. If is still not found, the user will be prompted for an ollar sign character ($) as the first character of the comment followed by the switch (unique abbreviations are acceptaentire command line. If is not specified, the compiler uses for the last file name remembered by the sble) and possibly switch parameters. The second form is given after the input file specification in the commanystem. is the name of the file to contain the output of the compiler. The extension ".SEG" will be appendd line preceded by the slash (/) character. The actual switches provided by the PERQ Pascal compiler, although similar in ed to if it is not already present. Note that if is not specified, the compiler uses the file namsyntax, bear little resemblance to the switches described ______ ____ ______ ___ ______ in PASCAL User Manual and Report [e from . Then, if the ".PAS" extension is present, it is replaced with the ".SEG" extension, else if the ".PAS" JW74]. - 37 - PERQ Pascal Extensions 04 Feb 82 extension is not present, the ".SEG" extension is appended. If already exists, it will be rewritten.  The following sections describe the various switches currently supported by the PERQ Pascal Compiler. 19.2. is the name of a compiler switch. All compiler switches specified on the command line must begin wi1 File Inclusion The PERQ Pascal compiler may be directed to include the contents of secondary source files in the comth the "/" character. Any number of switches may be specified, and if a switch is specified multiple times, the last occupilation. The effect of using the file inclusion mechanism is identical to having the text of the secondary file(s) prrrence is used. Also, if the /HELP switch is specified, the other information on the command line is ignored. The avaiesent in the primary source file (the primary source file is that file which the compiler was told to compile). Tolable switches are defined in the following sections. 19.2 Compiler Switches PERQ Pascal compiler switches may be include a secondary file, the following syntax is used: {$INCLUDE FILENAME} The characters betwe 19.1 Command Line The PERQ Pascal compiler is invoked by typing a compile command line to the PERQ Operating System set either in a mode similar ______ ____ ______ ___ to the convention describe. The syntax for the compile command line is: COMPILE [] [~ ] {}. HelpDir>EditorHelp>Introduction.Help Scratch.File n typing "E". The selection is extended to a character, word, or line boundary, depending on the type of your last sel Now ask the Editor to edit this new scratch file: Edit Scratch.File The PERQ text Editor is a "point, act" Editection. Commands that change the selection (other than Extend, W, and L) set the type to character. Unfortunately, you can mor. This means that to perform an editing action, you first "point" to a piece of text in the file and then perform some acake the selection larger with Extend, but you cannot make it smaller. To do so, you can start over with a fresh selectiontion on it. Pointing is done with the tablet and puck or pen. When you move the puck on the tablet, the pointer on t or use the M command described below. After selecting text, you can perform some action on it. You can insert befohe screen moves to follow it. The pointer changes shape depending on where it is on the screen. It is usually an up-and-lere or after it, delete it, search for a character string that follows it, or any of the other Editor actions. The top linft pointing arrow, but changes in certain areas to an up-pointing arrow, a down-pointing arrow, or a circle. These e of the screen usually shows editor version, file name, and time. It also displays repeat counts and flags for More, different shapes indicate that different things will happen when you press the buttons on the puck (or press down with the pen)Verify, and direction. On occasion the line is used for error messages and prompts within commands.   ".LST" extension, else if the ".PAS" extension is not present, the ".LST" extension is appended. Like the file inclusio Default value: Display of procedure and function names enabled $QUIET+ or /VERBOSE enables display of procen the "$INCLUDE" and the "}" are taken as the name of the file to be included (leading spaces and tabs are ignored). The n mechanism, in the comment form of the switch, the filename is taken as all characters between the "$LIST" and thcomment must terminate at the end of the filename, hence no other options can follow the filename. If the file FILENAe "}" (ignoring leading spaces and tabs); hence no other options may be included in this comment. With each sourceME does not exist, ".PAS" will be concatenated onto the end of FILENAME, and a second attempt will be made to find the file line, the compiler prints the line number, segment number, and procedure number. 19.2.3 Range Checking This . The file inclusion mechanism may be used anywhere in a program or module, and the results will be as if the entire switch is used to enable or disable the generation of additional code to perform checking on array subscripts  contents of the include file were contained in the primary source file (the file containing the include directive).  and assignments to subrange types. Default value: Range checking enabled $RANGE+ or /RANGE enables range Note: There is no form of this switch for the command line, it may only be used in comment form within a program.  checking $RANGE- or /NORANGE disables range checking $RANGE= resumes the state of range che 19.2.2 List Switch The List Switch controls whether or not the compiler generates a program listing of the source cking which was in force before the previous $RANGE-or $RANtext. The default is to not generate a list file. The format for the List switch is: {$LIST } or /LIST [= ] where is the nameled with range checking disabled will run slightly faster, but invalid indices will go undetected. Until a program is fu of the file to be written. The extension ".LST" will be appended to if it is not already present. If is not specified, the compiler uses the source file name. If the ".PAS" extension is present, it is replaced with table or disable the Compiler from displaying the name of each procedure and function as it is compiled. he - 38 - PERQ Pascal Extensions 04 Feb 82  - 39 - PERQ Pascal Extensions 04 Feb 82   DEL before typing "Q".) When you type "Q", the screen is erased, and a list of options is presented: he text as it was before the command. Acceptance is signalled by typing the INS key. Rejection is signalled by typing the  U to update W to write to another file E to exit without updating DEL key. When inserting text with the Editor, BACK SPACE deletes the most recently typed character, control-BACK SP R to return to the Editor Type one of these letters followed by RETURN. You may wish to pause before the RETUACE deletes the most recently typed word, and control-OOPS deletes the most recently typed line up to and including theRN to be sure you have the right choice. If you update or write to a file that already exists, the Editor sa carriage return. The RETURN key (carriage return) is used to mark the end of each line in your file. The Editor does automaves the old version of the file by adding a "$" to the end of its name. This allows you to get the old version back tic indenting for you by supplying leading blanks on the new line to match those on the previous line. You may BACK SPACE if you decide you made a mistake. You can safely edit the backup file since it has a different name than the new over them or type more. The special keys have alternates as shown by this table: ______ _________  version of the file. While it is never a good idea to type control-C while you're in the Editor, you shoul _________ Action Character Alternate End-of-line RETURN control-cribe the commands available. Each command description begins with the letter on the key used to perform the commandd not type it while the Editor is writing the new copy of your file. You will lose the new version of your file. _____ ______ _____ First Things First HELP - Get explanations Type the HELP key to g, and the old version will be in the backup file. If you type control-C before writing the new file or type "E" to et explanations of the editor commands. (If you are "in" a command, you may need to type DEL before typing HEL exit without updating, your file will remain unchanged regard- less of any changes you made with the Editor. P.) The editor will display a list of commands and keywords. You may then type the name of an entry (the word or  - 2 - Editor V2.0 User's Guide 02 Feb 82 _____ letter before the dash) and the editor will display an explanation. To exit, just type the RETURN key. Q __ ____ Special Keys The Text Modification commands are terminated by "Accept" or "Reject". The first of the- Quit from the Editor To leave the editor, type the "Q" key. (If you are "in" a command, you may need to typese indicates that the change is desired, the editor makes the change. The second foregoes the change, the editor leaves t  emory, the default number of symbol table blocks is 24 and the maximum number of symbol table blocks is 32. Note that you -", then "-" is assumed. Note: currently two programs, the debugger and the disassembler, use the information stored can specify more than 32 symbol table blocks with a 256k byte system, but performance usually degrades considerably. For sysin the Name Table. 19.2.8 Version Switch The Version Switch permits the inclusion of a version string in the fitems with 512k or 1024k bytes of main memory, the default number of symbol table blocks is 200 and the maximum number of syrst block of the ".SEG" file. This string has a maximum length of 80 characters. Currently this string is not used by any otmbol table blocks is also 200. 19.2.6 Automatic RESET/REWRITE The PERQ Pascal compiler automatically generather PERQ software, however, it may be accessed by user programs to identify ".SEG" files. The format for this switch is: edure and function names $QUIET- or /QUIET disables display of procedure andes a RESET(INPUT) and REWRITE(OUTPUT). This may be disabled if desired with the use of the AUTO switch. The format for th function names $QUIET= resumes the state of the quiet switch is switch is: - 40 - PERQ Pascal Extensions  which was in force before the previous $QUIET- or $QUIET+ switch.  04 Feb 82 Default value: Automatic initialization enabled $AUTO+ or /AUTO enables automatic initial if "$QUIET" is not followed by a "+" or "-", then "+" is assumed. 19.2.5 Symbols Switch This switch is uization $AUTO- or /NOAUTO disables automatic initialization If "$AUTO" is not followed by a "+" or "-", thesed to set the number of symbol table swap blocks used by the Compiler. As the number of symbol table swap blocks incren "+" is assumed. If the comment form of this switch is used, it must precede the BEGIN of the main body of the prograses, compiler execution time becomes shorter; however physical memory requirements increase (and the Compiler may abortam. 19.2.7 Procedure/Function Names The PERQ Pascal compiler generates a table of the procedure and function n due to insufficient memory). The format for this switch is: /SYMBOLS = <# of Symbol Table Blocks> Note: There isames at the end of the ".SEG" file, if so directed. This table may be useful for debugging programs. The format for t no comment form of this switch, it may only be used on a command line. The default number of symbol table blocks and thhis switch is: Default value: Name Table is generated $NAMES+ or /NAMES enables generation of the Name Tae maximum number of symbol table blocks are both dependent on the size of memory. For systems with 256k bytes of main mble $NAMES- or /NONAMES disables generation of the Name Table If "$NAMES" is not followed by a "+" or "   control-" -none- Since these special keys have special meanings, they must be "quoted" to insert them , Word, Line, and Goto character. The flag is turned forward by all other commands except More, Extend, Verify, and Note.in your file; Type control-" (the Editor quote character) followed by the special key. When you type control-", t It is also turned forward by Find, but the old direction is remembered if the Find is repeated with INS. > - Forward Dirhe insert cursor changes from "_" to " " to indicate you typed the quote character. INS - Repeat the last command ection Typing a ">" sets the forward direction (toward the end of the file). "+" and "." (unshifted ">") are Typing the INS key at command level repeats the last command. Only certain commands may be repeated this way, sinc synonyms for this command. > - Reverse Direction Typing a "<" sets the reverse direction (toward the beginnie it does not make sense to repeat some commands like * and Extend. Commands that may be repeated are A, I, ng of the file). "-" and "," (unshifted "<") are synonyms for this command. ____ _________  R, S, D, and those which move the selection. - 3 - Editor V2.0 User's  View Selection The Scroll Bar The area to the left of the left-margin line is called the "scroll bar". IfGuide 02 Feb 82 ______ _____ Repeat Count Typing a 1- to 4-digit nu you move the pointer into this bar, it changes into an up-pointing arrow at the left side and a down-pointing arrow at the mber enters a repeat count; it is displayed in the prompt line after the letter "R". This number specifies how many right side. If you press the yellow button when the arrow is pointing up, the line that the pointer is next to is scrolled to times to execute the next command, but it only applies if the command is Find, Repeat, Goto character, LF(Scroll), Line, Worthe top of the screen. If you press when the arrow is pointing down, the top line of the screen is scrolled down to the d, or one of the Character Selection commands. The number of repetitions actually performed is displayed in the prompt lineline that the pointer is next to. Thus if you put the pointer near the top of the screen, by pressing repeatedly, you can sM,control-J -or- control-M,LF Erase character BACK SPACE contr after the letter "C". _______ _________ Reverse Direction Many commands move through the file. Tol-H Erase word control-BACK SPACE control-W Erase line control-OOPS control-U Achey can do this either forward toward the end of the file or in reverse toward the beginning of the file. The currecept INS control-Y Reject DEL control-N Quote nt direction is displayed by a "<" or ">" in the upper left corner of the screen. It effects the commands Find, Replace  n the first block of the ".SEG" file. This string has a maximum length of 80 characters. It is particularly useful fot to follow is included in the compilation. If the boolean expression evaluates to false, then the text which follows ir including copyright notices in ".SEG" files. The format for this switch is: $COMMENT or /COMMENT = to set the comment string. When utilizing the $COMMENT form of the switch, the comment text is termi 04 Feb 82 The region of conditional compilation is terminated by the $ENDC switch: nated by the end of the comment or the end of the line. If the comment exceeds a single line, the remainder of the comm {$ENDC} Upon encountering the $ENDC switch, the state of compilation returns to whatever state was present prior toent is ignored. 19.2.10 Message Switch The Message Switch causes the text of the switch to be printed on the u the most recent $IFC. The remaining switch is the $ELSEC switch, and it functions much in the same way as the else clser's screen when the switch is parsed by the compiler. It has no effect on the compilation process. The format for this swause in an IF statement. If the boolean expression of the $IFC switch is true, then the $ELSEC text is ignored, otheritch is: $MESSAGE to print on the console during compilation wise it is included. If a $ELSEC switch is used, no $ENDC preceeds the $ELSEC; the $ELSEC signals the end of the $VERSION or /VERSION = to set the Version string. When The message is terminated by the end of the comment or the end of the line. If the comment exceeds a single line, the r using the $VERSION form of the switch, the version string is terminated by the end of the comment or the end of the line. Ifemainder of the comment is ignored. Note: There is no command line form for this switch, it may only be used in its comm the comment exceeds a single line, the remainder of the comment is ignored. If the /VERSION form is used, theent form. 19.2.11 Conditional Compilation The PERQ Pascal conditional compilation facility is implemented throu version string is terminated by either the end of the command line or the occurrence of a '/' character (hence a '/' may gh the standard switch facility. There are three switches which are used for conditional compilations. The first is the $IFCnot appear in the version string). - 41 - PERQ Pascal Extensions  switch, which has the following form: {$IFC THEN} This switch indicates the  04 Feb 82 19.2.9 Comment Switch The Comment Switch permits the inclusion of arbitrary text ibeginning of a region of conditional compilation. If the boolean expression, evaluated at compile time, is true, the tex croll slowly through the file. If you put the pointer near the bottom of the screen, you can move through the file in largts the position of the beginning of the displayed text. ) - Represents the position of the end of thee jumps of pages. If you put the pointer near the middle of the screen, you can move through the file  displayed text. N - Represents the position of the Noted display. O - Represents the position of  - 4 - Editor V2.0 User's Guide 02 Feb 82 in half-page jumps.  the display at the last thumbing. The thumb bar is used to rapidly move around in your file, but it is no When the pointer is in the Scroll Bar area, the puck buttons have special meanings: the white button always scrolls tt very precise. When you put the pointer on the thumb bar and press down, the portion of the file represented by that portionhe text up and the green button always scrolls it down. LF, Control-LF - Scroll LF repositions the screen window so of the bar is displayed on the screen. When you press at "S", the beginning of the selection is shown. For "N", the noted it displays text starting with the 37th line of the previous display. Control-LF scrolls in the other direction  position is shown. And so on. Similar control can be achieved with the X - 5 - so the previous top of the screen is at the new bottom. T - Top The line containing the end of the current s Editor V2.0 User's Guide 02 Feb 82 command described below. The thumb bar canelection is moved to the screen. If on-screen, it is moved to the bottom. B - Bottom The line containing the  also be used to extend the selection. When you type "E" while in the thumb bar, the selection is extended to the positicurrent selection is moved to the bottom of the screen. (If off-screen, it is moved to the middle.) on in the file which is represented by that particular portion of the thumb bar. This is usually only useful for extending The Thumb Bar The top-margin line is called the "thumb bar". When you move the pointer to this line, it changes  to the beginning or end of the file. N - Note The current screen display is noted and an N is placed in the into a circle. Think of the thumb bar as a linear representation of your file. The left end of the bar represents the beg Thumb Bar. The thumb bar may be used to return to this current display by selecting the N. ____ _________inning of your file. Special characters are used to represent other interesting parts of your file: - Represents t Text Selection E - Extend the selection This command extends the current selection from where it is to he end of the file. S - Represents the position of the beginning of the selection. ( - Representhe text currently indicated by the pointer. See the M command for an alternative way to extend the selection. * - S  TYPE Base = record i,j,k:integer end; {$IFC WORDSIZE(Base) = 3 THEN} Cover = array[0..2] of inteitch allows compilations to be left unattended. 19.2.13 Help Switch The Help switch provides general information ager {$ELSEC} Cover = array[0..10] of integer {$ENDC}; 19.2.12 Errorfile Switch When nd overrides all other switches. The format is /HELP.  the compiler detects an error in a program, it displays error information (file, error number, and the last two lines w - 44 - PERQ Pascal Extensions 04 Feb 82 20.0 Quirkshere the error occurred) on the screen and then requests whether or not to continue. The /ERRORFILE switch overrides this  and Other Oddities The following are descriptions of known quirks and problems with the PERQ Pascal compiler. Future action. When you specify the switch and the compiler detects an error, the error information is written to a file a releases may correct these problems. 1. FOR loops with an upper bound of greater than 32,766 will nevnd there is no query of the user. However, the compiler does display the total number of errors encountered on theer terminate. 2. The last line of any PROGRAM or MODULE must end with a carriage return, or an "Unexpe screen. - 43 - PERQ Pascal Extensions 04 Fcted End of Input" error occurs. 3. Although unique abbreviations are accepted for switches,eb 82 The format for this switch is: /ERRORFILE [= ] where is the name of the file to be w the following abbreviations cause compilation errors: ______ ___ ________ritten. The extension ".ERR" will be appended to if it is not already present. If is not specified, ____ Switch Bad Abbreviation $ELSEC $ELSE the compiler uses the source file name. If the ".PAS" extension is present, it is replaced with the ".ERR" extension $ENDC $END $IFC $IF $INCLUDE $IN  $IFC region. A $ENDC is then used to terminate the $ELSEC clause. Conditional compilations may be nested. The, else if the ".PAS" extension is not present, the ".ERR" extension is appended. The error file exists after a following are two examples of the conditional compilation mechanism: Const CondSw = TRUE; PROCEDURE Te compilation if and only if you specify the /ERRORFILE switch and an error is encountered. If the file .ERR ast; begin {$IFC CondSw THEN} Writeln('CondSw is true'); {$ENDC} end { Test }; lready exists from a previous compilation, it will be rewritten, or deleted in the case of no compiliation errors. This sw  - 6 - Editor V2.0 User's Guide 02 Feb 82 A Find command immediately after typing "I", the most recently inserted or deleted text is inserted. If you Accept, the tex can be done in the reverse direction (toward the beginning of the file). See the section "Reverse Direction". Yot you have just typed is displayed at the top of the screen inside of I{ ... } . R - Replace u can ask the Editor to search for a certain number of occurrences of the target string by preceding the command w This command finds all occurrences of a given string within the currently selected text. As each is found, it is replaceelect the entire file The entire file is selected. This is useful for Find, which otherwise begins its search fith a number. See the section "Repeat Count". ____ ____________ Text Modification Text modirom the current selection. It is also useful for doing replacements throughout the text. F - Find a character stringfication is done with the commands Insert, Append, Substitute, Replace, and Delete. The first two of these operate bef (N. B.: The search starts at the beginning of the selected text.) When you type "F", the top line shows the pore and after the current selection, but the others operate on the current selection itself. After execution of one ofrompt Find: enter target string Type the string you want to search for and then Accept or Rejec these commands, it can be re-executed by pressing the INS key. This can be handy for inserting the same text in a number t. Rejection aborts the Find command; Acceptance starts the search. If you Accept immediately after typing "F", theof places. A - Append text after the selection. Type text until you are done, then either Accept or Reject the previous target string is used. Lower case letters in the target string will match both upper and lower cas insertion. If you Accept immediately after typing "A", the most recently inserted or deleted text is inserte letters in the text, but UPPER case target letters will match only upper case text letters. While searced. If you Accept, the text you have just typed is displayed at the top of the screen inside of I{ ... hing for the target, the top line displays the cue "Finding". At this time, the search can be interrupted by } . D - Delete the selected text. If you delete text, it is displayed at the top of the screen inside of typing control-c. The selection will be unchanged. If the target string is found, it becomes the selected text.  D{ ... } . The character which immediately follows the deleted text is selected. I - Insert t Note that the target string is shown at the top of the screen inside of F{ ... } . ext before the selection. Type text until you are done, then either Accept or Reject the insertion. If you Accept  4. Procedures and functions which are forward declared (this includes EXPORT declarations) and le by the compiler when in actuality they are not. 8. Reals and longs cannot be used together in an contain procedure parameters, may not have their parameter lists redeclared at the site of the proc expression. 9. The compiler will not detect an error in the definition or use of a set tedure body. 5. The compiler currently permits the use of an EXIT statement where the routine to be exited hat exceeds set size limitations. If such a set is used, incorrect code will be generated. 1 from is at the same lexical level as the routine containing the EXIT statement. For example: 0. Many functions that exist for integers (e.g. LAND) are not implemented for longs. 11. The RECAST in program Quirk; procedure ProcOne; begin trinsic does not work with two-word scalers (for example, LONG) and arrays.  end; procedure ProcTwo; begin exit(ProcOne)  - 46 - PERQ Pascal Extensions 04 Feb 82  end; begin ProcTwo end. If there is no  20. References ________ [BSI79] "BSI/ISO Pascal Standard," Computer, April 1979. invocation of the routine to be - 45 - PERQ Pascal Extensions  [FP80] "An Implementation Guide to a Proposed Standard for Floating ________ Point", Computer, January 04 Feb 82 exited on the run-time stack, the PERQ will hang and has to be re-booted 1980 ______ ____ ______ ___ ______ [JW74] K. Jensen and N. Wirth, PASCAL Us. 6. The filename specification given in IMPORTS Declarations must start with an alphabetic er Manual and Report, Springer Verlag, New York, 1974. [P*] J. Hennessy and F. Baskett, "Pascal*: A Pascal Based S character. 7. Record comparisons involving packed records (illegal comparisons) will not ystems Programming Language," Stanford University Computer Science Department, TRN 174, August 1979.  be caught unless the word PACKED appears explicitly in the record definition. For example, records w ___________ __ ____ ________ __ ______ [UCSD79] K. Bowles, Proceedings of UCSD Workshop on ith fields of user-defined type Foo, where Foo contains packed information, are considered comparab System ___________ __________ __ ___ ______ ________ Programming Extensions to the Pascal Language, Instit aracters of the replacement string, the previous replacement string is used. This means that to replace with no puck or pen away from the tablet). This double underline is difficult to see, but it's there. You may now thing, you must first type a character and then delete it with the BACK SPACE key. While the editor is "ReplacAccept the replacement with INS, you may skip over this occurrence by typing the space-bar, or abort the replace coming", you may interrupt by typing control-c. The Count field at the top of the screen will show how many replacememand with DEL. - 8 - Editor V2.0 User's Guide nts have been made. In the absence of a Repeat Count, all occurrences within the selection are replaced 02 Feb 82 S - Substitute New text is substituted for the selected text. This command is similar to the sequ. If a Repeat Count is typed immediately before the "R", the specified number of occurrences are replaced, ence "Delete, Insert". After typing "I", type text until you are done, then either Accept or Reject the insertistarting at the beginning of the selection. See the section "Repeat Count". The direction can be changed as on. If you Accept immediately after typing "S", the most recently inserted or deleted text is inserted. If you d by a second given string. Typing "R" causes the prompt Replace: enter target string at the top of described in the section "Reverse Direction". V - Toggle Verify mode When you type "V", Verify mode is turned on or the screen. Type in a string and then Accept or Reject. Note that the target string is displayed inside of  off, depending on whether it was off or on before. When Verify mode is on, a "V" is displayed in the prompt lin - 7 - Editor V2.0 User's Guide 02 Feb 82 F{ e. Most commands revert the verify flag to non-verify mode. Those that do not cause reversion are Word, Li ... } just as though you were using the the Find command. Lower case letters in the target string will match bne, *, Goto character, More, Extend, Note, and the Character Selection commands. In Verify mode the Replaceoth upper and lower case letters in the text, but UPPER case target letters will match only upper case text le command gives you the option of replacing, not replacing, or aborting at each occurrence of the target string. Thtters. If you Accept, the prompt Replace: enter replacement string is shown at the top of the screen. Nowe prompt Replace: INS replaces, doesn't, DEL aborts is displayed for each occurrence of the tar you can type in the new string to replace occurrences of the target string. If you Accept before typing any chget string. The target string is indicated by a double underline and by the pointer arrow (if you keep the  2 Declarations 2 DISPOSE  38 Inclusive Or 26 INLINEAWORD  25 Dynamic Space Allocation and Deallocation 24 ELSEC  35 INLINEBYTE 34 INLINEWORD  42 ENDC 42 Error notification file  34 Input/Output Intrinsics 28 INTEGER ute for Information Systems, University of California, San Diego, California, 1979.  43 Errorfile Switch 43 EXCEPTION  - 47 - PERQ Pascal Extensions  21 Exceptions 21 Exclusive Or  04 Feb 82 INDEX (Entries entirely in upper cas 26 EXIT Statement 9 EXPORTS Declaration e are reserved words or predeclared identifiers) ALL  20 FILE 16 File Inclusion  23 AND 26 Assignment Compatibility  38 Files 2 FLOAT  4 Automatic RESET/REWRITE 40 CASE Statement  35 Floating Point Numbers 3 Function Result Type  8 Command Line 37 Comment Switch  18 Functions 18 Generic Files  42 Compiler Switches 37 Conditional Compilation  16 Generic Pointers 15 HANDLER  42 Constant Expressions 5 Constants  21 Help switch 44 Identifiers  5 Control Structures 9 Declaration Relaxation  2 IFC 42 INCLUDE  mmand because you cannot re-insert the deleted text. Attempting to re-insert the most recently inserted or deletel-w and Control-W are synonymous with this command, but shift-control-W treats a word as any consecu- tive string ofd text will merely re-insert the text you just typed in. The deleted text is gone forever. This means that if y printable characters. RETURN - Move to first character of line following the previous selection. Control-U is ou type "S" when you meant to type "R", you may accidentally delete a large portion of your file and have no way osynonymous with this command. Control-RETURN - Go back to first preceding non-blank that follows a CRLF. Control-OOPf getting it back. (Should disaster strike, see the section below on "Transcript/Replay".) _________ __S is synonymous to this command. X - Thumb bar (X-Coordinate selection) An "X" is placed on the thumb bar at the _______ Character Selection The Character Selection commands move the selection as though it were a cursor fortop of the screen. The following keys are active: INS - Display the part of file corresponding to  insert. The new seelection is a single character close to the former selection. None of these commands is affected  current position of the "X". DEL - Aborts. Display and current selection are by the Reverse Direction flag, but all are performed as many times as specified by the Repeat Count. They reset the Revers unaffected. TAB - Move "X" five positions to the right. control-TAB - Move "X" five positions to e Direction flag unless the More flag is set. When the More flag is set, these commands still move in their usual directithe left. SPACE - Move "X" one position to the right. BACKSPACE - Move "X" one position to the left. on; thus they can be used to reduce the selection. SPACE - Move to the character following the previous selection. BA RETURN - Move "X" to end of file position. Control-RETURN - Move "X" to beginning of file  Accept, the text you have just typed is displayed at the top of the screen as the most recently inserted text inside CKSPACE - Go to the character preceding the previous selection. Control-H is synonymous with this command. of I{ ... } and the text you have just deleted is displayed at the top of the screen inside of  - 9 - Editor V2.0 User's Guide 02 Feb 82 TAB D{ ... } . After substituting, the character immediately following the deleted text is sele - Advance five characters from end of previous selection. Control-TAB - Go back five characters from beginning of prevcted. Be careful. It is easy to confuse Substitute and Replace. There is no way to "undo" a Substitute coious selection. Control BACKSPACE - Go to the beginning of the word preceding the current selection. Contro  34 MESSAGE 42 Miscellaneous Intrinsics  12 References 47 RESET  31 Mixed Mode Expressions 4 Modules  28 REWRITE 28 ROTATE  19 NEW 24 NOT  27 Sets 11 SHIFT  26 Numbers 3 OR  26 SHRINK 36 Single and Double Precision Constants  26 OTHERWISE 8 Parameter Lists  5 Single Precision Logical Operations 26 STARTIO  18 Parameters 18 POINTER  31 STOREXPR 35 STRETCH  3 - 48 - PERQ Pascal Extensions 04 Feb 82  15 PRIVATE 20 Procedure/Function Names  INTEGER Logical Operations 26 LAND  41 Procedures 18 QUIET  26 LENGTH 14 LIST  39 Quirks 45 RAISE  38 LNOT 26 LOADADR  21 RANGE 39 Range Checking  35 LOADEXPR 35 LONG  39 RASTEROP 31 READ  3 LOR 26 LXOR  28 READLN 28 REAL  26 MAKEPTR 34 MAKEVRD  3 RECAST 7 Record Comparisons  r indicates what text was displayed prior to the last thumb bar selection. N - Moveeginning of the selection is chosen. Unshift-w chooses words that are consecutive letters and digits; Shift-W  to the N marker on the line. This marker is set by the N command. The current selection is unchange defines a word as any sequence of printable characters. A Repeat Count of (say) n will cause the selection of the n'td by X. However, if a keyboard command (C, W, L, G, space, ...) is given when the selection is off screen,h subsequent word. If the Reverse Direction flag is set, the search will be toward the beginning of the file.  the operation is treated as though the first character of the screen had been previously selected. If the More flag is set, the selection is extended to the end of the word that would otherwise be selected by th - 10 - Editor V2.0 User's Guide 02 Feb 82 G - Go to is command. L - Select Line If a line is currently selected, this command selects the next; otherwise it extecharacter After typing "G", one more character is typed. The editor searches the rest of the screen for the chnds or contracts the current selection to be the line that included its start. A Repeat Count of (say) n will causaracter. If found, it becomes the current selection. If the Reverse Direction flag is set, G searches from te the selection of the n'th subsequent line. If the Reverse Direction flag is set, the search will be toward the current selection toward the top of the screen otherwise it searches only from the selection downward. INS wilhe beginning of the file. If the More flag is set, the selection is extended to the end of the line that would l repeat a G command if it was the last command exectued. A repeat count may also be given to select a characotherwise be selected by this command. M - More in selection Turns on the More flag, indicated by an M in the promptter a known number of instances away. If the More Flag is set, the selection is extended to the found character. w line. When this flag is on, selection commands extend the current selection rather than change it. The select, W - Select Word This command selects the word that follows, extends, or begins the current selection. If the curion grows only at the end indicated by the Reverse Direction flag. The Character Selection commands (SPACE, BACKSrent selection is a word or is outside a word, the following word is selected; if currently inside a worPACE, RETURN, etc.) can cause the selection to shrink at that end. In More mode, these commands do not sele position. Digits - Set repeat count for TAB's and SPACE's. O - Move to O marker on line. This marked, the entire word is selected. When the current selection overlaps more than one word, the one overlap- ping the b  3 Type Compatibility 7 VERSION he prior written authorization of Three Rivers Computer Corporation. The information in this document is sub 41 Whole Number Constants 5 Whole Numbers ject to change without notice and should not be construed as a commitment by Three Rivers Computer Corporation.  3 WORDSIZE 33 WRITE The Company assumes no responsibility for any errors that may appear in this document. Three Rivers Comput 29 WRITELN 29 er Corporation will make every effort to keep customers apprised of all documentation changes as quickly as p - 50 - ossible. The Reader's Comments card is distributed with this document to request users' critical evaluation to assist us in preparing future documentation. PERQ is a trademark of Three Rivers Computer Corporation.  - ii - PERQ <--> Z-80 Messages  17 Aug 81 __ ____________ 1. Introduction This document gives a brief description of PERQ <--> Z-80 Messages Bill Glass and Donal the messages that are interchanged between PERQ and the Z-80 on the I/O board. The descriptions give the synta 36 - 49 - PERQ Pascal Extensions 04 Feb 82 d A. Scelza This document briefly describes the message protocol used in the PERQ <--> Z80 commu STRING 13 Strings nication interface. Copyright (C) 1981 Three Rivers Computer Corporation 720 Gross Street  13 Switches 37 Symbols Switch  Pittsburgh, PA 15224 (412) 621-6250 PERQ <--> Z-80 Messages 17 Aug 81  40 Type Coercion 7 Type Coercion Intrinsics  This document is not to be reproduced in any form or transmitted in whole or in part, without t unt against the 256-word buffer. If you do not want to destroy the old transcript file, do not type any commands, do not pree Selection to Top of Screen 5 B - Move Selection to Bottom of Screen 5 The Thumb Bar 6 N - Note Css more than a few times, and exit the Editor by typing control-shift-C. To replay a transcript, type "Eurrent Position 6 Text Selection 6 E - Extend the selection 6 * - Select the Entire File 6 ct a single character, nor do they change the direction flag. More mode is extinguished by More again or by execuditor/Replay". The Editor replays the previous edit session and stops just before the first command. You can control thting *, Extend, Quit, or one of the Text Modification commands. - 11 - e replay by typing one of the following keys: SPACE stop replaying after the next character or puck press. CR  Editor V2.0 User's Guide 02 Feb 82 _________________ Transcript/Replay  stop replaying after a carriage return in I command or after next command if not in I command. LF  The Editor writes a transcript file during every edit session. The transcript is a file which contains a description ofstop replaying after next command. INS begin replaying and stop when one of the above keys is typed.  every keystroke and puck or pen press performed during an edit session. This transcript is written to the file ">Editor DEL exit replay mode. If no DEL key is typed, the Editor automatically exits from replay mode when the .Transcript". The transcript may be replayed later. This feature is intended for use when the Editor or the PERQ crashes dend of the transcript is reached. Once you have exited replay mode you can begin editing normally, but we suggest that uring an edit session or if you make some disasterous error with the Editor. The Editor saves keystrokes and presses ayou Quit-Update as soon as possible. - 12 - Editor V2.0 Usend writes them to the transcript file whenever: 1) A carriage-return is typed in Insert mode. 2) A command which r's Guide 02 Feb 82 _____ __ ________ Table of Contents 1 Introductchanges the text is successfully completed. 3) The transcript buffer is filled. If an old transcript file exists, ion 2 HELP - Get Explanations 2 Q - Quit from the Editor 3 Special Keys 3 INS - Repeat tit is destroyed the first time the buffer is flushed. This means that you can re-enter the Editor without destroying the Last Command 4 Repeat Count 4 Reverse Direction 4 > - Set Forward Direction 4 > - Sethe old transcript file as long as you do not do something that causes the buffer to be flushed. Keep in mind that presses co Reverse Direction 4 View Selection 4 The Scroll Bar 5 LF, Control-LF - Scroll 5 T - Mov byte which is not shown. In all the descriptions, is a byte count. An N of zero is interpreted as 256. The the only command that must contain valid data. This data will be written to the floppy in byte has the low order bit set if that device is to be enabled, and clear if it is to be disabled. The remaining 7 bits athe specified sector. All writes transfer 256 bytes of data to the floppy. If 256 bytes are device specific and should normally be zero. All numbers are octal unless they are terminated with a period. re not provided by PERQ, then the remainder of the sector will be written with whatever is left  Whenever PERQ sends a message that requires a data transfer, no further transfer messages, for that device in the buffer. For all of the commands, except Write, a byte count of 1 must be specified. , should be sent until the Z-80 says that it is willing to accept messages for that device. __ ____ __ ___ ________ This data byte will not be used. - 1 - PERQ <--> Z-80 Messages  2. PERQ -> Z80 Messages ________ ____ RS232Out Char <001>... Th 17 Aug 81 ____ _______ GPIB Command <003>... The is message places characters into the RS-232 output ring buffer. The byte count (N) must ballowable values of cmd are: 1 - write data. 2 - write data with EOI on last byte. e less than or equal to sixteen. The Z-80 will give a transmitter ready status whenever 3 - write registers. The first two commands cause a data transfer on the GPIB bus. N must be in  there are sixteen free bytes in the ring buffer. ______ _______ Floppy Command <002>... The , and bytes of a floppy che third command allows PERQ to directly write into the TI-9914 registers. In this command, each paiommand must be in the same format that is expected by the NEC floppy chip. The valid values forr of data bytes is treated as the first being a register number, and the second a data value.  the byte of a floppy command are: 1 - read a sector of data. 2 - write a s The register numbers are: 0 - Interrupt Mask 0 (The Z-80 will always enable Bx of the command, a brief description of its function, and any restrictions. Note that all commands begin with a 153 ector of data. 3 - format a sector. 4 - seek to a cylinder. The write command is  ring future documentation. PERQ is a trademark of Three Rivers Computer Corporation.  - ii - Programming Examples - Introduction  Programming Examples Brad A. Myers  08 Feb 82 1. Introduction. This manual describes how to use the PERQ operating system to perform some int This manual describes how to use Fonts, Cursors, RasterOp, Line, Windows, CmdParse, PopUp menuseresting operations. Examples are given of the ways we have found to be successful in performing these operations. Alth, and how to allocate large amounts of memory. The manual includes examples of sample applications. ough there are obviously many ways to perform these operations, the ones given here are successful.  F - Find a Character String 7 Text Modification 7 A - Append Text After the Selection 7 D - Del Copyright (C) 1981, 1982 Three Rivers Computer Corporation 720 Gross Street Pittsburgh, PA 15224 (41ete the Selected Text 7 I - Insert Text Before the Selection 7 R - Replace Occurrences of One String with An2) 621-6250 Programming Examples 08 Feb 82 This dother 8 V - Toggle Verify Mode 9 S - Substitute New Text for the Selected Text 9 Character Selectiocument is not to be reproduced in any form or transmitted in whole or in part, without the prior written aon 9 SPACE - Advance to Next Character 9 BACKSPACE - Go Back a Character 10 TAB - Advance Five Charuthorization of Three Rivers Computer Corporation. The information in this document is subject to change wiacters 10 Control-TAB - Go Back Five Characters 10 Control-RETURN - Back to Beginning of Line 10 RETUthout notice and should not be construed as a commitment by Three Rivers Computer Corporation. The Company assumes RN - Advance to Next Line 10 Control-RETURN - Back to Beginning of Line 10 X - Thumb bar 11 G - Go to no responsibility for any errors that may appear in this document. Three Rivers Computer Corporation will Character 11 w, W - Select Word 11 L - Select Current Line 11 M - More in Selection 12 Tran make every effort to keep customers apprised of all documentation changes as quickly as possible. The Reader'script/Replay - iii - s Comments card is distrib- uted with this document to request users' critical evalu- ation to assist us in prepa (same as rr). - 2 - PERQ <--> Z-80 Messages  ground +5 +12 +12/-12 Vref Networ17 Aug 81 __ ss is the number of stop bits (00 for synchronous, 01 fk CRT base unit +55 +24 The value of speciI and BO with your data.) 1 - Address Register 3 - Parallel Poll or 1, 10 for 1 1/2, and 11 for 2). __ pp is the parity setting (00 for no pari 4 - Interrupt Mask 1 5 - Serial Poll 6 - Auxiliary Command Again, N ty, 01 for odd, 11 for even). ______ ______ Tablet Status <006><1> must be in the range of 1 to 32. ______ _______ Speech Command <004>...  Turns the tablet on or off. No other status settings are possible. ________ ______  This command is similar to the RS-232 output command except that the output goes to the s Keyboard Status <007><1> Turns the keyboard on or off. No other status settipeech channel. The byte count (N) must be less than or equal to thirty-two. The Z-80 will give a speecngs are possible. ____ ____ Disk Seek <010> Performs a seek of cylindersh ready status whenever there are thirty-two free bytes in the ring buffer _____ ______ RS232 Status . The seek complete message is issued after the appropriate delay time based on the value of  <005><3> This command sets the current state of the RS-232 c . _______ ________ Voltage Settings <011> Enables hannel. represents the baud rate (1 is 9600, 2 is 4800, 4 is 2400,  or disables voltage/temperature checking and sets the minimum and maximum allowable values (th ________ etc.). is the bit pattern rrttsspp where: __ e range is inclusive). The values are specified as four bytes for each voltage/temperature. The fir rr is the number of bits per receive character (00 for 5, 01 for 7, 10 for st byte is the low order minimum, the second is the high order minimum, the third is the low order ma 6 and 11 for 8). __ tt is the number of bits per transmit character ximum, and the fourth is the high order maximum. The ordering of the voltages/temperatures is:  e other lookup functions) from FileSystem. A VAR parameter to this function is the number of blocks in the file. Talignment. For DISPOSE, only the pointer should be specified. NEW is implemented by a call to the procedure NewP inhis number can be passed to the memory manager to tell it how much storage to allocate. Memory on the PERQ is divided in Dynamic. The user can call this procedure directly if he wants to specify the size of storage to allocate. NewP is defineto "segments". Each segment can have up to 256 blocks. Each block is 256 words or 512 bytes. When a segment is created, itd as Procedure NewP(seg: integer; allignment: integer; var p: MMPointer;  is given an initial size, a maximum size, and an increment by which to increase the current size when that is not enough.  size: integer); The segment number of 0 is always defined to be the default segment for NewP and NEW. All other seA segment is created by using the procedure from memory: Procedure CreateSegment( var Seg: Integegment numbers should come from a prior CreateSegment. To calculate the size of a record or array, WordSize is a usefur; initialSize, {in blocks} sizeIncrement, {in blocks} l intrinsic. It returns the size of any PASCAL variable or type and can be used in constant or variable expres- sions.  maximumSize: integer); {in blocks} where seg is assigned the segment number that has been created. There are  The user must remember the size used with NewP since DisposeP takes the size as a parameter. two ways to use a segment once created. The first is simply to create it with a fixed size and use the entire segment at  - 2 - Programming Examples - Allocating Memory 08 Feb 82 Procedure DisposeP(var p: - 1 - Programmingonce. For example, when reading an entire file into memory. Use MakePtr(seg, offset, TypeOfPointer) to create a pointer Examples - Allocating Memory 08 Feb 82 2. Allocating Memory. This section describes how to  of type TypeOfPointer in that segment at word offset "offset". The second way to allocate out of a segment is to use theuse the Memory module to allocate blocks of memory needed for reading in Fonts and pictures from files, for creating  standard Pascal NEW. NEW has been extended to have two forms. The standard form, NEW(p), allocates the pointer out of the pictures off screen for RasterOp, and for handling large amounts of data. Fonts and pictures are generally stored in fil default segment. The extended form, NEW(seg, allignment, p), allocates the storage out of the specified segment. Soes on the disk. To use the fonts and pictures, they must first be read into memory. First, do a FSLookUp (or one of thme buffers need to be specially aligned. For example, RasterOp buffers need to be on a multiple of 4. Do not use 0 for the  py Status <014><003><# Heads> The Floppy Status command is used to set  quantity received. The bytes have the following error bits: 1 (bit 0) - parit the status of the floppy. is used to set the floppy to single or double density. y 2 (bit 1) - overrun 4 (bit 2) - framing. ______ Tablet <003>Here, a value of 0 indicates single density and a value of 100(octal) indicates double density. This message reports the X and Y values from the tablet. The tablet s <# Heads> indicates the number of heads that the floppy has. Valid values are 1 and 2. represents the number of clock ticks pt Enable> is used to set the interrupt status of the floppy. If interrupts are disabled then th (1/60 second) elapsed since the sending of the last tablet message. _____ Clock <fies the number of data bytes in the command. It may fall in the range of 1 to 51 (octal). e floppy will not be able to interrupt the Z80. A 1 indicates that interrupts are to be al - 3 - PERQ <--> Z-80 Messages 17 Aug 81 _____ ___lowed. A 0 will disable interrupts. ______ ____ Floppy Boot <15> The Floppy B___ Clock Status <012><1> Turns the clock on or off. No other status seoot message is used to request the Z80 to read a boot file from the floppy. The format of a boot ttings are possible. _______ ______ Request Status <013> Requests the Z-80 to r floppy is described elsewhere. - 4 - PERQ <--> Z-80 Messages eturn the status settings of any device. The byte is treated as a set of one bit flags  17 Aug 81 __ ____ __ ____ ________ 3. Z80 -> PERQ Messages ________ ____ indicating the devices for which status is being requested. The bit definitions are: 001 - Keyboard Char <001> is the eight bit value received from the keyboard.  RS-232 002 - Tablet 004 - Keyboard 010 - Voltage 020 - Clock  _______ ____ RS232In Char <002><2*N>... This message transfe 040 - Floppy 100 - GPIB 200 - send status change ______ ______ Floprs up to sixteen characters received on the RS-232 channel. represents the eight bit  NameDesc = RECORD numCommands: integer; recSize: integer; commands: array[ 08 Feb 82 3. Reading in Large Files. There are a number of ways to read in a font or a picture from the 1..1] of s25; {vbl length array} END; pNameDesc = ^NameDesc; To allocate a pNameDesc with NUM namedisk. The fastest and most straightforward way is to use MultiRead. This is a special procedure that uses the micro-code's s in the segment seg, the following would be done: var p: MMPointer; size: integer; names: pNameDesability to read multiple blocks at once. The read, therefore, occurs at the maximum possible speed (the actual speed depc; begin size := 2*WordSize(integer) + { for the 2 integers } NUM*WordSize(s25); { the variable paends on how contiguous the blocks are on the disk). To use multi-read on a file called FileName do the following: varrt } NewP(seg, 1, p.p, size); names := RECAST(p.p, pNameDesc); names^.recSize := size; names^.numCommand fid: FileID; {imported from FileSystem} blocks, bits: integer; seg: Integer; begin fid := FSLookUps := NUM; {$R-} {turn range checking off to assign names} for i := 1 to NUM do names^.commands[i] := ''; {$R=} {return range checking to the previous state} end; Since Dynamic uses special places in the segmen {allocate} MultiRead(fid, MakePtr(seg, 0, pDirBlk), 0, blocks); end; end; MultiRead takes a fileIDt to store the free list information used by NEW, it is bad practice to mix NEW and MakePtr on the same segment. Whe, a pointer to the start of the block of memory, the first block to read of the file to read, and the number of blocks. n a program requires a large amount of data, consider the swapping characteristics of the operating system. Since POThe above code reads in the entire file. If you do not wish to import MultiRead, you can read in each block of the file uS swaps an entire segment at once, a big segment will take much longer to read in and write out. Also, there may simply nsing FSBlkRead. Replace the MultiRead call above with the following for i := 0 to blocks - 1 do FSBlkRead(fid, i,ot be enough memory to hold the large segment and all other necessary data. Therefore, the user should divide the data  MakePtr(seg, i*256, pDirBlk)); The MakePtr creates a pointer to the i-th block (the i*256-th word) of the segment. WARN MMPointer; size: integer); The size MUST be the same size used with NewP. One way to insure this is to store the size ainto separate segments, each of which is about 10 blocks large. For example, this is what the editor does to hold the ps a field in a record. As an example of NewP, we make a variable length array of strings: Type s25 = String[25]; iece table. - 3 - Programming Examples - Reading in Large Files  t implemented) <006>... - 5 - PERQ <--> Z-80 Mehe same order as in the PERQ to Z-80 message with the low byte preceeding the high byte in each ssages 17 Aug 81 _____ ______ RS232 Status <007><3> Z-80 Messages tings> Reports the current RS-232 status. The interpretation of and is the 17 Aug 81 _______ ______ Voltage Status <015><75>  same as for the PERQ to Z-80 message. ______ ______ Tablet Status <010><1>  This message reports the status of voltage/temperature checking.  Reports the current status of the tablet. ________ ______ Keyboard Status <011><1>  reports the current values (as in the voltage error message), and give the lowe Reports the current status of the keyboard. ____ ________ Seek Complete <012> Ackr and upper bounds in the same format as the PERQ to Z-80 message. _____ ______ Clock Status nowledges completion of a disk seek. ______ ______ Status Change <013> This messa <016><1> Reports the status of the clock. ______ ______ Floppy Status <20>.. This message is used to return the status of the floppy. Up to seven registers 004> This message reports the number of clock ticks since the last clock message. ag> is interpreted as a set of one bit flags that indicate which devices are currently permitted: Note, this message is used only when the clock is enabled and the tablet is disabled. _____ 001 - Can Accept RS232 Output 002 - Can Accept Speech Output 004 - Can Accept Floppy Inp_ ____ Floppy Data <005>... This message is used to transmit ut/Output 010 - Can Accept GPIB command 020 - Can Accept Disk Seek 200 - Always data from a read operation to PERQ. The low order bit of the status byte indicates if the Read set _______ _____ Voltage Error <014><024> Reports that at least  operation completed without error. A 1 indicates that there was error. ____ GPIB (no one of the voltage/temperatures was out of the allowable bounds. The values are reported in t emember that the destination is specified first. To move a rectangle one bit down: RasterOp(RRpl, 100, 200, 300, 400, SS at position (10, 100). We use RasterOp(RRpl, 543, 632, 10, 100, SScreenW, SScreenP, 0, ING: The multi-block read exported by FileAccess does not work. creenW, SScreenP, 300, 399, SScreenW, SScreenP); The position (0,0) is in the upper left cor - 4 - Programming Examples - RasterOp and Line 08 Feb 82 4. RasterOp and Line. RasterOner; the lower right corner is (767, 1023). RasterOp does not validate the widths or positions so be careful. Be espep and Line are the chief graphics primitives of the PERQ. Each is fast. TThe primitives allow drawing of rectangles cially careful to avoid negative widths and heights since these are taken as large positive numbers. The available RasterOp fand lines, respectively. RasterOp is described in the PERQ Pascal Extensions manual and Line is exported by the Screen unctions are: RRpl {dest get src} RNot {dest get invert of src} RAnd {dest gets dest AND src} RNmodule. Use RasterOp to clear a rectangle (either white or black); transfer a picture from one place to another; or combiAnd {dest gets dest AND invert of src} ROr {dest gets dest OR src} RNor {dest gets dest OR invert of src} ne two pictures. Use Line to draw a single width line on the screen at any orientation. RasterOp is a general utility. It  RXor {dest gets dest XOR src} RXNor {dest gets dest XOR invert of src} RasterOp can also move a picture from orcan be used on buffers that are not on the screen. Therefore, it takes parameters that describe the dimensions of the buf to an off-screen buffer. Suppose a picture is 543 bits wide and 632 bits high. The buffers used by RasterOp must be a multfer. For the Screen, the two constants SScreenW and SScreenP are exported by the Screen module. As a first example, weiple of 4 words in width. Therefore, allocate a buffer that is 36 words (=576 bits) wide and 632 bits high. This is 22 will clear an area of the screen 100 bits wide, 200 bits tall, starting at position (300, 400): RasterOp(RXor, 100, 200, 752 words. Since segments can only be allocated on block boundaries, round up to 22784 words or 89 blocks and create a segme300, 400, SScreenW, SScreenP, 300, 400, SScreenW, SScreenP); We do this by Xoring the area withnt of this size and a RasterPtr to its start: - 5 - Programming Examples - RasterOp a itself. Similarly, to clear an area to black, use the function RXNor. The function names are exported by the module nd Line 08 Feb 82 CreateSegment(seg, 89, 1, 89); p := MakePtr(seg, 0, RasterPtr); Now weRaster. To move a rectange from one area of the screen to another, simply use a different source and destination position. R might read a file into this buffer as described in Section 3. Next, we want to transfer the picture onto the screen, say  at the requested floppy operation has finished. The low order bit of this message is used to  is the number of bytes in the message. NOTE: in a Floppy Boot Data message a byte count of zerprovide error status information. If the low order bit is set then there was an error during theo means NO data bytes. A message with a zero byte count will be sent after all of the boot blocks fro operation. The Floppy Status command can be used to get more detailed information about any em the floppy have been read. rrors that may have occurred. ____ ______ GPIB Status <017><6>< - 8 - PERQ <--> Z-80 Messages 17 Aug 81 _____ __ ________ reg6> This message reports the status of the GPIB read registers at the last interrupt. The order Table of Contents 1 1. Introduction 1 2. PERQ -> Z80 Messages  of the registers is: 1 - Interrupt Status 0 2 - Address Switch 3 -4 Clock Status 3 Disk Seek 4 Floppy Boot 1  Address Status 4 - Command Pass Through 5 - Interrupt Status 1 6 - Bus Status  Floppy Command 4 Floppy Status 2 GPIB Command 3  - 7 - PERQ <--> Z-80 Messages 17 Aug 81  Keyboard Status 4 Request Status 2 RS232 Status 2  ______ ____ _____ Floppy Boot Error <22> The floppy boot error message will be sent  Speech Command 3 Tablet Status 3 Voltage Settings  anytime that there is an error while the Z80 is reading a boot file from the floppy. The possib 5 3. Z80 -> PERQ Messages 5 Clock 7 Clock Status 8 le errors are: a) the floppy is not ready. b) the floppy is not a boot floppy.  Floppy Boot Data 8 Floppy Boot Error 5 Floppy Data 7 may be returned by this message. These are the status registers that are provided by the NEC chip.  c) any error reported by the floppy chip. ______ ____ ____ Floppy Boot Data <23>...  ______ ____ Floppy Done <21> The floppy done message is used to indicate th This message is used to send a block of boot file information from the Z80 to PERQ.  . POS currently supports multiple, overlapping windows. However, POS does not know when two windows overlap. Thus parameters of the current window. Unfortuneately, you must do transformations on the numbers returned to get the all windows are "transparent" in that anything written to a covered window will "show through" any windows that a inside and outside areas of windows: GetWindowParms(var windx: WinRange; orgX, orgY, width, height: integer; re on top. Even with this restriction, windows are useful for a number of applications. For example, if multiple thin var hasTitle: boolean); windx is the current window number and hasTitle tells whether there is a title line. Cgs are going on and the user wants to separate the input and output of each. The Screen package handles scrolling of alculate the outside of the window as follows: begin orgX := orgX - 2; width := width + 5; orgY := orgY - 0, 36, p); The destination (given first) is (10, 100) on the screen, but the source is now the buffer. The bit width t the text inside windows automatically. Therefore separate windows scroll separately (if they do not overlap). This io transfer is 543 (the second argument), but the word width of the buffer is 36. (SScreenW is 48, the number of words acrs useful, for example, in a graphics package where there are commands typed in a small window with the rest of the areaoss the screen). p is the pointer to the buffer. A picture can be transfered from the screen into a buffer, or between used for the graphics (an example is the CursDesign program from the User Library). The user must maintain the allocat buffers in a similar manner. If you want to allocate a buffer using NEW or NewP for RasterOping to or from, be sure to maion of windows; the user tells the screen package where each window is and is expected to remember the number for each windoke the allignment 4. Line is used for drawing straight, single width lines on the screen. It takes a source and destination w. Window zero is reserved for the system and its size should not be changed. Use CreateWindow to create a new window. x and y position, a style and a pointer to the buffer to draw in. Currently, it can only draw lines in buffers that have wThe parameters passed are for the outside of the window. There are two bits of border, then a hair line, then two more bitsidth 48 (e.g. the screen). Line is defined as: Line(style: LineStyle; x1, y1, x2, y2: integer; p: RasterPtr); w on each side. On the top there may be a title line which is a band of black with white letters in it. Once a window is here the style is DrawLine, XOrLine or EraseLine. Use SScreenP for p. created, it cannot be moved or re-signed. Creating a new window automatically changes output to go to the new window. Gi - 6 - Programming Examples - Windows 08 Feb 82 5. Windowsven a set of windows, you can change amonst them by using the ChangeWindow command. The procedure GetWindowParms returns  nsmitted, in whole or in part, without the prior written authorization of Three Rivers Computer Corporation. The i1.d Global One Word Loads and Stores 4.A.1.e Intermediate One Word Loads and Stores 4.A.1.f Indirect One Word Loads and Stores Floppy Done 7 Floppy Status 5 GPIB 7 GPIB Status nformation in this document is subject to change without notice and should not be construed as a commitment by 5 Keyboard Char 6 Keyboard Status 6 RS232 Status  Three Rivers Computer Corporation. The Company assumes no responsibility for any errors that may appear in this  5 RS232In Char 1 RS232Out Char 6 Seek Complete  document. Three Rivers Computer Corporation will make every effort to keep customers apprised of all documenta 6 Status Change 5 Tablet 6 Tablet Status 6 tion changes as quickly as possible. The Reader's Comments card is distributed with this document to requ Voltage Error 7 Voltage Status est users' critical evaluation to assist us in preparing future documentation. PERQ is a trademark of Th - iii - ree Rivers Computer Corporation. - ii -  Table of Contents 1. Q-Machine Architecture 1.A Definitions 1.B Memory Organization  1.B.1 Memory Organization at the Process Level 1.B.1.a Global Data 1.B.1.b Local Data 1.B.1.c Run-Time Stack Organization  PERQ QCode Reference Manual Miles A. Barel  1.B.2 Memory Organization at the System Level 1.B.2.a System Segment Address Table 1.B.2.b System Segment Information Table John P. Strait June 25, 1981  1.B.2.c Code Segment Organization 1.C Error Handling and Fault Conditions 2. Instruction Format 3. Poin Copyright (C) 1981, 1982 Three Rivers Computer Corporation 720 Gross Street Pittsburgh, PA 15224 ters 4. QCode Descriptions 4.A Variable Fetching, Indexing, Storing and Transferring 4.A.1 Loads and Stores of (412) 621-6250 This document is not to be reproduced in any form or tra One Word 4.A.1.a Constant One Word Loads 4.A.1.b Local One Word Loads and Stores 4.A.1.c Own One Word Loads and Stores 4.A.  - 8 - ontP; RasterOp(RRpl, width, FontP^.height, xPos, yPos-FontP^.Base, SScreenW, SScreenP, Programming Examples - Fonts 08 Feb 82 6. Fonts. The definition of fonts is give Offset, Line*FontP^.height, SScreenW, MakePtr(Trik.seg, Trik.Ofst+#404, FontPtr)); n in the Screen module. Fonts currently can be variable width, but there is no kerning. A font starts with some global end; end; The #404 is the size of the introductory part of a font. Trik is used to create a pointer to the ac information: the height of the font in bits and the offset of the baseLine. Next is an array, which for each character htual bit pattern part of a font. - 9 - Programming Examplas the position and width of that character in the font. A width of zero means the character is not defined. After this es - Cursors 08 Feb 82 7. Cursors. Unfortuneately, the term "Cursor" is used in two wayarray is the actual bit pictures for the characters which are defined. Fonts can be created by using the FontEd programs in PERQ-land. First, it is the position where the next character will be placed on the screen. This "cursor" is usually si from the User Library available from the Sales department. To use a font, it must first be loaded into memory. See the segnified by an underline "_". The second "cursor" is the arrow or other picture that usually follows the pen or puck on t2; height := height + 5; if hasTitle then begin orgY := orgY - 15; height := height + 15; ction on reading files above. The Screen package allows you to change the font to one you have defined. First, you should de end; end; Calculate the inside of the window as follows: - 7 - Programmfine a new window so that you don't change the font for the default system. Now simply call the function SetFont passiing Examples - Windows 08 Feb 82 begin orgX := orgX + 2; width := width - 4; ng it a pointer to the top of the segment into which you read the font. If you wish to RasterOp a character (ch) using font F if hasTitle then begin orgY := orgY + 2; height := height - 4; end; end; One thing to nontP onto the screen by hand (at position (xPos, yPos)), use the following form (copied from SPutChr in Screen): ote: the title line for a window is written in the font that was in effect before the window was created. This font wivar Trik: Record Case Boolean of true: (F: FontPtr); false: (seg, ofst: integer); ll also be remembered as the font to use the next time the window that was in use before the CreateWindow is used again.  end; begin with FontP^.Index[ord(ch)] do if width > 0 then begin Trik.f := F  in two types: code segments, which are byte-addressed, read-only, and fixed in size with a m - 1 - PERQ QCode Reference Manual 04 Feb 82 aximum size of 64K bytes (32K words); and data segments, which are word-addressed, read-write, and variable in size  ISN - Internal Segment Number (compiler-generated). SSN - System Segment Number (system-generated). Note, System  with a maximum size of 64K words. MSTACK - Memory Stack. A data segment which contains the user  Segment 0 is reserved and may never be used. LL - Lexical Level. Note: the Lexical Level of the main body run-time stack. ESTACK - Expression Stack. A 16 level expression evaluation stack (internal to the PERQ p of a process is always 0. RN - Routine Number (register). RN contains the ordinal number of the cu 4.A.2 Loads and Stores of Multiple Words 4.A.2.a Double Word Loads and Stores 4.A.2.b Multiple Word Loads and Stores 4.A.rocessor). MTOS - Top of MSTACK. MTOS refers to the virtual address of the top of the memory stack. (MTOS)3 Byte Arrays 4.A.4 Strings 4.A.5 Record and Array Indexing and Assignment 4.B Top of Stack Arithmetic and Compar denotes the item on the top of the MSTACK. ETOS - Top of ESTACK. (ETOS) denotes the item on the top of the isons 4.B.1 Logical 4.B.2 Integer 4.B.3 Reals 4.B.4 Sets 4.B.5 Strings 4.B.6 Byte Arrays 4.B.7 Array and Re ESTACK. Activation Record - Stack segment fragment for a single routine containing local variables,cord Comparisons 4.B.8 Long Operations 4.C Jumps 4.D Routine Calls and Returns  parameters, function result, temporaries (anonymous variables), other housekeeping values (Activat - iii - Table of Contents 4.E Systems Programs Support Procedures Inion Control Block - defined below), and a copy of the EStack at the time the activation record is credex ated. CB - Code Base (register). Physical adddress of the base of the current code segment. SB -  - iv - PERQ QCode Reference Manual 04 Feb 82 1. Q-Machine Architecture Stack Base (register). Physical address of the base of the current stack segment. PC - Program Counter  1.A Definitions Segment - A segment is the underlying structure of PERQ's virtual memory system. (register). Physical address of the current instruction. GDB - Global Data Block. A GDB contains the  It is the largest area of contiguous memory, and also the unit of swappability. Segments comeglobal variables for a particular module. GDBs always begin on a double-word boundary.  er Library can be used to create cursors. Once a picture has been created, it can be read into Memory from the file (se use cursor mode IndepCursor. To set the cursor position, use the function IOSetCursorPos(x,y); Note that if you sete above) and then copied into the Cursor. Each cursor is 56 bits wide and 64 bits tall which comes to 4 words wide and 6 the cursor position in Track mode, it will be overwritten almost immediately by the position of the tablet. You can st4 bits tall or exactly one block. Therefore a file with one cursor in it can be read in directly into the cursor buffer. Till read the tablet in IndepCur- sor mode if it has been turned on; the tablet position is simply not used to set the cursor phe definition of the cursor and all utility procedures for manipulating it are in IO_Others. var curs: CurPatPtr; bosition. - 10 - Programming Examples - Cursors 08 Feb 8egin New(0,4,curs); Fid := FSLookup(CursorFile, blks, bits); FSBlkRead(fid, 0, RECAST(curs, pDirBlk)); end; 2 To read the tablet position, use the function IOReadTablet. It returns the last x and y position read from the tab Note that the cursor buffer must be quad-word aligned (since a RasterOp is done from it by the system). To set a culet. If the pen or puck is away from the tablet, it may be an old point. It is not possible to tell if the tablet is sensirsor, use the function IOLoadCursor. It takes a CurPatPtr and two integers to tell it the x and y offsets in the cursorng the pen or puck. The buttons can be read using the variables TabSwitch, TabYellow, TabBlue, TabWhite, and TabG from where the cursor is positioned. Thus, for a "bull's eye" cursor where the center is the interesting point, the offsereen. TabSwitch tells if any button was pressed. For a puck, the other booleans tell which button it was. For a pen, the ts would be the offsets from the top left of the center. For a right pointing arrow, the offsets would describe the poin"colored" booleans will always be false. These booleans are true while the button is held down. The user is reqt of the arrow. The user then does not need to compensate when reading the cursor position. IO_Others exports the cursor uired to wait for a press-let up event: repeat until tabswitch; while tabswitch do; { read tablet position, or whahe tablet. This section discusses the latter form. The picture in the cursor can be set by the user. POS currently DefaultCursor which is the upper-left pointing arrow. The cursor can be used in a number of ways. If you want the cursor tuses a number of different pictures. The default arrow cursor, the "scroll" and "do-it" cursors for PopUp menus, the hand o follow the tablet and then read the tablet coordinates, use the cursor mode TrackCursor. IOCursorMode(TrackCursor); that moves down the side of the screen, and the Busy Bee are all examples of cursors. The program CursDesign from the Us Be sure to turn the tablet on using IOSetModeTablet(relCursor). If you want to explicitly set the position of the cursor, cord which are used for function result and parameters. LTS - Local + Temporary Size. LTS is the number of w segment's GDB, represented as an offset from SB. XST - eXternal Segment Table. For a given program module, the ords in an activation record which are used for locals and temporaries (anonymous variables).  XST translates ISNs to SSNs and XGPs. RS - Return Segment. RS is the CS of the caller. RA - Return  (Note: the LTS of a main program body is always forced to 0.) AP - Activation Pointer (register). AP cAddress. PC of the caller, represented as an offset from CB. RR - Return Routine. RN of the caller. ontains the physical address of the current activation record. DL - Dynamic Link. This is the AP of the cal RD - Routine Dictionary. Each code segment contains a routine dictionary which is indexed by RN. For each rler, represented as an offset from SB. SL - Static Link. This is the AP of the surrounding routine, outine, the routine dictionary gives the lexical level (LL), entry address, exit address, parameter represented as an offset from SB. TP - Top Pointer (register). TP contains the physical address of th size (PS), result + parameter size (RPS), and local + temporary size (LTS). ACB - Activation Control Blocke top of the run-time MStack. TL - Top Link. TP of the caller, represented as an offset from SB. . The ACB contains housekeeping values in the activation record. It contains the SL, LP, DL, GL, RS, rrent routine. Note: RN must lie in the range 0 to 255. CS - Code Segment (register). CS contains the sy - 2 - PERQ QCode Reference Manual 04 Feb 82 GP stem segment number (SSN) for the current code segment. This segment must be resident in physical me- Global Pointer (register). Physical address of the GDB for the current code segment. GL - Global Link.mory for a process to be runnable. SS - Stack Segment (register). SS contains the system segment  GP of the caller, represented as an offset from SB. LP - Local Pointer (register). Physical address of th number (SSN) for the current stack segment. This segment must be resident in physical memory for a process to be current activation record. When the LP is stored in an Activation Control Block (ACB), it is representee runnable. PS - Parameter Size. PS is the number of words in an activation record whicd as an offset from SB. Unlike other values in the ACB, the LP value is the current value of the Loch are used for parameters. RPS - Result + Parameter Size. This is the number of words in an activation real Pointer, not some previous value. XGP - eXternal Global Pointer. Pointer to another code  tever } The Cursor functions determine how the cursor interacts with the picture on the screen under the cursor. Thethen { c is a valid character } where IOEIOC is a constant defined in the module IOErrors and c is a character variable.  cursor function also determines the background color. The even functions have zeroes in memory represented as white and onIf IOCRead returns some value other than IOEIOC, then no character has been hit. "Transkey" tells IO that you want thes as black (this is the default: white background with black characters). Odd functions have zeroes represented as black e standard ASCII interpretation of the character. If you use "KeyBoard" instead, you will get the actual 8 bits returned by  and ones as white. The functions are as follows (inverted means screen interpretation as just described): CTWhite: the keyboard. This code allows you to distinguish the special keys (INS, DEL, HELP, etc.) from the other keys and allo Screen picture is not shown, only cursor. CTCursorOnly: Same as CTWhite only inverted. CTBlackHole: This ws you to distinguish CONTROL-SHIFT-key from CONTROL-key. You will have to experiment to get the code for the desired kefunction doesn't work. CTInvBlackHole: This function doesn't work either. CTNormal: Ones in the cursor are blacky. There is no way to tell when a key has been let up. IOCRead does not write out the character typed. If you want i, zeros allow screen to show through. CTInvert: Same as CTNormal only inverted. CTCursCot printed, you should use Write(c). If you want to print all the special symbols in the font file (there is a picture asmpl: Ones in the cursor are XORed with screen, zeros allow screen to show through. CTInvCursCompsociated with every control character), you can set the high bit of the character. This prevents the Screen package from intel: Same as CTCursCompl only inverted. - 11 - rpreting the character as its special meaning if any. Thus, you could print the picture for RETURN by using Write(c Programming Examples - Reading Characters 08 Feb 82 8. Reading Characters from the Keyboard. hr(LOr(RETURN, #200))); IOCRead also does not turn on the input marker ("_") which shows the user that he is supposed to ty The normal PASCAL character Read waits for an entire line to be typed before returning any characters. This allows edipe something. Do a SCurOn (from Screen) before requesting input and an SCurOff when done to make the underline prompt apting of the line (backspace, etc.) as described in the PERQ Introductory Manual. If you want to get the characters exactlypear. The HELP key and ^C are handled specially by the IO system. If the HELP key is hit, an exception is raised. If you when they are hit, you must call IOCRead in IO_Unit. The normal form for this call is If IOCRead(TransKey, c) = IOEIOC  do not handle this exception (called HelpKey, exported by System), "/HELP" will be put into the input stream as if  by associating an exception with a handler. A (possibly empty) list of EEBs is associated with each space. The segment is the unit of swappability, and comes in two types: 1) Code segments which are byte-addressed, read-o activation record in the stack. Enabling an Exception - Associating a certain exception handler with a certnly, and fixed in size with a maximum size of 64K bytes (32K words). 2) Data segments which are word-addressain exception. - 3 - PERQ QCode Reference Manual ed, read-write, and variable in size with a maximum size of 64K words. A PERQ process is a collection of up t 04 Feb 82 EP - Exception Pointer. The address (as an offset from SB) of a list of nodes that describo 64K code and data segments. One of the data segments is the stack segment. Every process must have a stack segmente which exceptions are enabled in a certain routine. ER - Exception Routine Number. The routine number  and at least one code segment. All segments are allocated in 256 word chunks and when in physical memory are al of an exception. ES - Exception Segment Number. The segment number of an exception. igned on 256 word boundaries. Note: A single segment must exist in contiguous memory. It may not be fragmented. 1.B.1  Exception - An error or unusual occurrence in the execution of a routine or program. Exception Handler - Memory Organization at the Process Level The memory organization is designed with the following attributes i A procedure to be executed when a certain exception is raised. HR - Handler Routine Number. The routinen mind: 1) to allow separately compiled code segments to be grouped into a single process, 2) to allow code segments to  number of an exception handler. NE - Next Exception. The address (as an offset from SB) of be shared among processes, 3) to allow each code segment to have its own global variables, and 4) to allow one code  the next in a list of nodes that describe which exceptions are enabled in a certain routine. Raising an Exsegment to reference routines and global variables in other code segments. To achieve this, the following high-levelRA, RR and EP. In the ACB, the DL, GL, RS, RA, and RR are the AP, GP, CS, PC, and RN of the caller, ception - Asserting a certain exception. respectively. The SL is the AP of the routine that surrounds the current one. The LP in the ACB is the - 4 - PERQ QCode Reference Manual 04 Feb 82 1.B Memory Organization  current local pointer. EEB - Exception Enable Block - Each EEB enables a single exception  The PERQ's virtual memory system features a segmented 32-bit virtual address space mapped into a 20-bit physical address   - 13 -  end; switches := switches^.next; end; if (outs^.name <> '') or (outs^.next <> NIL) then S Programming Examples - CmdParse and PopCmdParse 08 Feb 82 9. CmdParse and PopCmdParse. CmdParse and PoptdError(ErNoOutFile, '', true); if ins^.next <> NIL then StdError(ErOneInput, '', true); CmdParse export a number of procedures that help read and parse strings of commands and arguments. Procedures exist for h if ins^.name = '' then begin Write(': '); ReadLn(s); ok := ParseString typed. If you do handle this exception, you can put chr(7) into the input stream: the code for HELP. When ^C is typed,andling command files (which may be nested), for parsing a string containing inputs, outputs and switches into its compone the exception CtlC is raised (also defined in System). If not caught, nothing special is done until the second ^C is hit nts, and for getting a command index from a string or a PopUp menu. The modules CmdParse and PopCmdParse document how when CtlCAbort is raised. This causes the program to exit. Note that the ^C's are put into the input stream. ^SHIFT-C c each of the procedures work. This section provides an example of how to use the parsing procedures in CmdParse. var ins, auses a separate exception to be raised. If the user wants one ^C to do something special in a program (for example, abort outs: pArgRec; switches: pSwitchRec; switchAr: CmdArray; err: String; ok, leave: boolean; c: Char;  type-out and go to top level as in FLOPPY), put the following Handler at the top level: Handler CtlC; begin  s: CString; isSwitch: boolean; i: integer; begin c := NextString(s, is WriteLn('^c'); IOKeyClear; {remove the ^C from input stream} - Switch); {remove ""} if (c<>' ') and (c<>CCR) then StdError(ErIllCharAfter, '', true); ok := Par12 - Programming Examples - Reading Characters 08 Feb 82 CtrlCPending := false; {so next ^CseCmdLine(ins, outs, switches, err); repeat if not ok then StdError(ErAnyError, err, true); while switches <> NIL won't abort program} goto 1; {top of command loop} end; (IOKeyClear comes from IO_Others. do {handle all the switches} begin ConvUpper(switches^.switch); i := UniqueCmdIndex(switches^.switch) Another special character to know about is ^S. This character prevents any further output to the screen until a ^Q is , switchAr, NumSwitches); case i of 1 : 2 : otherwise: StdError(ErBadSwitch, switches^.switch, true);   characteristics are implemented: 1) All code is re-entrant. 2) Each code segment only refers to other code  +-----------------------+ | | .... | segments by internal (compiler-generated) segment numbers, which are not necessarily the same as the system-as | +-----------------------+ | | signed segment numbers. 3) Each code segment in a process has its own Global Data Block on the run-time stack. | XST i | | | +-----------------------+ GP ---- 4) Each code segment has an external segment table to permit referencing global variables and routines from >| | | GDB i | | | other code segments. - 5 - PERQ QCode Reference Manual  +-----------------------+ | | .... towar 04 Feb 82 1.B.1.a Global Data At the global level, there is a Global Data Block (GDB) and an eXtd the top of stack The XST for each segment is indexed by the internal segment numbers (ISNs). The entry is ernal Segment Table (XST) associated with each code segment in a process. For a particular program module, the GDB contai at GP - 2*ISN (Note: There is no entry for ISN 0; ISN 0 always refers to the current segment). Each entry contains the ons the global variables, and the XST translates internal (compiler- generated) segment numbers (ISNs) to actual systeffset from stack base (SB) of an external data block (XGP) and the actual system segment number (SSN) of the external sm segment numbers (SSNs) and eXternal Global Pointers (XGPs). To simplify the system, we devote a single pointer to referenegment. The XGP values are set by the linker, and the SSN values are set by the loader. ce both the current GDB and XST. This Global Pointer (GP) points to the lowest address in the GDB and is ALWAYS aligned - 6 - PERQ QCode Reference Manual 04 Feb 82 +-------------- on a double-word boundary. +-----------------------+ SB ---->| | -----------------+ | eXternal Global Pointer (XGP)| +-------------------------------+  | undetermined space | | | +-----------------------+  | System Segment Number (SSN) | +-------------------------------+ 1.B.1.b Local Data At  | XST 1 | +-----------------------+ | GDB 1 | the local level, there is an activation record, which consists of local variables, function result, parameter oard. 14 CmdParse and PopCmdParse. on changes as quickly as possible. The Reader's Comments card is distrib- uted with this document to request users - iii - ' critical evalu- ation to assist us in preparing future documentation. PERQ is a trademark of Three Rivers Computer Corporation. - ii - PERQ Fault Dictionary 08 Feb 82 _______ ___________ Display Description 000 Boot never got going, StackReset doesn't work or other major problem in the processor board (or clock). 001  PERQ Fault Dictionary The Key to the PERQ DiagnosticSimple Branches fail. 002 Main Data Path Failure. 003 Dual Address failure on Registers. 004 Y Ram FailuLine(s, ins, outs, switches, err); leave := false; end - 14 - Progr Display Copyright (C) 1981, 1982 Three Rivers Computer Coamming Examples - CmdParse and PopCmdParse 08 Feb 82 else begin leave := true; if notrporation 720 Gross Street Pittsburgh, PA 15224 (412) 621-6250 PERQ Fault Dictionary  RemoveQuotes(ins^.name) then StdError(ErBadQuote, '', true); FSRemoveDots(ins^.name); end; until leave; end; tted in whole or in part, without the prior written authorization of Three Rivers Computer Corporation. The inform - 15 - Table of Contents ation in this document is subject to change without notice and should not be construed as a commitment by Thr 08 Feb 82 1 Introduction. 2 Allocating Memory. 4 Reading in Large Files. 5 ee Rivers Computer Corporation. The Company assumes no responsibility for any errors that may appear in this doRasterOp and Line. 7 Windows. 9 Fonts. 10 Cursors. 12 Reading Characters from the Keybcument. Three Rivers Computer Corporation will make every effort to keep customers apprised of all documentati  - PERQ QCode Reference Manual 04 Feb 82 .... s, locals and temporaries are located by an offset from LP. - 8 -  | | +-----------------------+ LP ---->| |  PERQ QCode Reference Manual 04 Feb 82 Each ACB has the following form:  | Result m | | | +-----------------------+  +---------------------------------------+ | Static Link (SL) | s, temporaries (anonymous variables), the Activation Control Block (ACB), the previous EStack, exception enable blo | | | Parameters m | | | cks, and extra values that the routine may push and pop from the run-time stack. Three pointers are used to access  +-----------------------+ | | | Locals m | and keep track of this information: the top-of-stack pointer (TP), the current-activation pointer (AP), and the local-va | | +-----------------------+ | | riables pointer (LP). +-----------------------+ | Result m-1 | + | Temporaries m | | | +-----------------------+ -----------------------+ | Parameters m-1 | +-----------------------+  AP ---->| | | ACB m | | | | Locals m-1 | +-----------------------+ | Temporaries m-1 |  +-----------------------+ | | | EStack m-1 |  +-----------------------+ | ACB m-1 | +-----------------------+  | | +-----------------------+ | |  | EStack m-2 | +-----------------------+ | Exceptions m-1 |  | Exceptions m | | | +-----------------------+  +-----------------------+ | Extra m-1 | +-----------------------+  | | | Extra m | TP ---->| | | | .... - 7 +-----------------------+ toward the top of stack The function result, parameter Empty stack bit not working. 052 Could not load TOS. 053 Push did not work. 054 Stack Empty did not go oouldn't have. 088 GEQ didn't jump. 089 GEQ jumped when it shouldn't have. 090 LSS didn't jump when it ff. 055 Data error in push. 056 Empty or Full set when that is not the case. 057 Data error in bit 15 ofshould have. 091 LSS jumped when it shouldn't have. 092 LEQ didn't jump. 093 LEQ jumped when it shouldn' the stack. 058 Stack empty set when the stack is full. 059 Data error on stack. 060 Data error after t have. 094 GEQ didn't jump on equal. 095 LEQ didn't jump on equal. 096 Carry didn't jump when it shouldPOP. Bit 14. 061 Data error after POP. Bit 13. 062 Data error after POP. Bit 12. 063 Data error after have. 097 Carry jumped when it shouldn't have. 098 Overflow didn't jump when it should have. 099 Overfl POP. Bit 11. 064 Data error after POP. Bit 10. 065 Data error after POP. Bit 9. 066 Data error afterow jumped when it shouldn't have. 100 And-Not ALU function failed. 101 Or ALU function failed. 102 Or- POP. Bit 8. 067 Data error after POP. Bit 7. 068 Data error after POP. Bit 6. 069 Data error after PNot ALU function failed. 103 And ALU function failed. 104 Or-Not ALU function failed. 105 Not-A ALU funcOP. Bit 5. 070 Data error after POP. Bit 4. 071 Data error after POP. Bit 3. 072 Data error after Ption failed. 106 Not-B ALU function failed. 107 Xor ALU function failed. 108 Xnor ALU function failed. OP. Bit 2. 073 Empty wrong. 074 Data error after POP. Bit 1. 075 Data error after POP. Bit 0. 076 109 OldCarry-Add ALU function failed. 110 OldCarry-Sub ALU function failed. 111 OldCarry-Add /w No OldC Empty not set after all pops. 077 Call test falied. 078 Odd didn't jump on a 1. 079 Odd jumped on aarry failed. 112 Fetch error on Force Bad Parity. 113 Unexpected Parity error. 114 No parity errors on fre. 005 Const/Carry Propogate failure. 006 ALU failure. 007 Conditional Branch failure. 008 Loop 0. - 1 - PERQ Fault Dictionary 08 Feb 82 _ing failure. 009 Control Store (or Write Control Store) failure. 010 Hung in Disk Boot. 011 Memory Dat______ ___________ Display Description 080 Byte sign didn't jump on 200. 081 Byte sign jumped on 0. 082a Error. 012 Memory Address Error. 013 Disk never became ready. 014 Couldn't boot from either disks. 01 C19 didn't jump when it should have. 083 BCP[3] didn't jump when it should have. 084 C19 jumped when it 5 - 020 Bad Interrupts Reading Floppy Disk Data. 030 VFY Hung. 050 Bad Error Message from VFY. 051 shouldn't have. 085 BCP[3] jumped when it shouldn't have. 086 GTR didn't jump. 087 GTR jumped when it sh n Pointer (EP) | +---------------------------------------+ toward the .... | | +-----------------------+ | (ETOS-n)  top of stack The values in the ACB are the AP of the surrounding routine (SL), the current (not previous) LP, th | +-----------------------+ toward the top of stack e AP of the caller (DL), the GP of the caller (GL), the TP of the caller (TL), the SSN of the caller (RS), the program co - 10 - PERQ QCode Reference Manual unter (PC) of the caller (RA), the RN of the caller (RR) and a pointer to the current exception enable records (EP).  04 Feb 82 1.B.1.c Run-Time Stack Organization The following is an outline of the stack for a proceNote: When previous pointer values are saved in the ACB they are called links: SL, DL, GL, TL. Because the current (not press of n segments, executing the mth routine call, which is in the ith segment: +------------------vious) LP and EP are stored in the ACB, they are called pointers, not links. The static link is not used for main progr-----+ SB ---->| | | undetermined space | |  +---------------------------------------+ | Local Pointer (LP) (current) | +--------ams and top-level routines. It is zero for these routines and is therefore a means of detecting top-level routines. The d-------------------------------+ | Dynamic Link (DL) | +------------------ynamic link is zero for the first routine on the stack (the one at the base of the stack). This is used to detect th---------------------+ | Global Link (GL) | +----------------------------e end of the stack during stack searches. - 9 - PERQ QCode R-----------+ | Top Link (TL) | +--------------------------------------eference Manual 04 Feb 82 The EStack image immediately follows the ACB and looks -+ | Return Segment Number (RS) | +---------------------------------------+ like this: +-----------------------+ | Number of Words Saved | +---------- | Return Address within Segment (RA) | +---------------------------------------+ -------------+ | (ETOS) | +-----------------------+ | (ETOS-1)| Return Routine Number (RR) | +---------------------------------------+ | Exceptio | +-----------------------+ | |  . 118 Stack upper bits test failed. 119 Store/Fetch test failed. 120 Unexpected refill. 121 BPnters set. 204 StackSegment number set. 205 Reading the BootBlock. 206 System version number set. 207 C test failed. 122 Fetch4 test failed. 123 Fetch4R test failed. 124 Store4 test failed. 125 Fetc Head of free-segment-number list set. 208 First system segment number set. 209 System boot disk set. 21h2 test failed. 126 Store2 test failed. 127 NextOp test failed. 128 Fetch/Store overlap failed. 0 System boot character set. 211 Boot block read. 212 Default heap segment number set. 213 First  - 2 - PERQ Fault Dictionary 08 Feb 82 _______ __used segment number set. 214 Before setting freelists of data segments. 215 Before trying to allocate a segment _________ Display Description 129 Bad interrupt Loc 4. 130 Bad interrupt Loc 14. 131 Bad interrupnumber. 216 Temporary segment number allocated. 217 Ready to enter loop to find memory size. 218 Exited t Loc 20. 132 Bad interrupt Loc 30. 133 Data error on memory sweep. 134 Address error on memory sweep. from memory size loop. 219 Restored mangled word. 220 Released temporary segment number. 135 Field didn't work. 136 Dispatch did not jump. 137 Wrong Dispatch target. 138 Data error on in - 3 - PERQ Fault Dictionary 08 Feb 82 _______ ___________ Disverted memory sweep. 139 Address error on inverted memory sweep. 150 Sysb not loaded correctly or hung. 151 play Description 221 Located segment adjacent to the I/O segment. 222 Modified the location of I/O segment. Sysb did not complete. 152 Illegal Boot Key. 153 Hard Disk Restore Failure. 154 No such boot. 155 223 Adjusted free memory. 224 Freelists of data segments set. 225 Set screen segment. 226 Heade No interpreter for that key. 156 Interpreter file is empty. 157 Disk Error. 158 Floppy error. 1r buffer allocated for swapping. 227 Status buffer allocated for swapping. 228 SwappingAllowed set false. 229 59 Malformed Boot File. 160 CheckSum error in microcode. 161 CheckSum error in QCode. 162 - 168 Bad i All boot-loaded segments set UnSwappable (if booted from floppy), InitMemory complete, ready to return to Systnterrupts. 198 QCode interpreter microcode not entered correctly. 199 System not entered - calls or assignmentem. 230 Starting to increase number of segments allowed (because memory is larger than 1/4 megabyte). 231orce bad parity. 115 Wrong address on force bad parity. 116 Upper 4 bit test failed. 117 MDX test faileds don't work. 200 System entered, InitMemory to be called. 201 InitMemory entered. 203 SAT and SIT poi  +-----------------------+ GP ---->| | | GDB i  +-----------------------+ | Extra 1 | +-----------------------+ | | | +-----------------------+ | LP ---->| | | Result m | | |  | .... | | +-----------------------+  +-----------------------+ | | | Parameters m |  | XST n | +-----------------------+ | GDB n |  | | +-----------------------+ | |  +-----------------------+ | ACB 0 (main program) | +-----------------------+  | Locals m | | | +-----------------------+  | Exceptions 0 | +-----------------------+ | Extra 0 |  | | | Temporaries m | | |  +-----------------------+ | Result 1 | +-----------------------+  +-----------------------+ AP ---->| | | ACB m |  | Parameters 1 | +-----------------------+ | Locals 1 |  | | +-----------------------+ | |  +-----------------------+ | Temporaries 1 | +-----------------------+  | EStack m-1 | | | +-----------------------+  | +-----------------------+ | XST 1 | +---------------- | | - 11 - PERQ QCode Reference Manual -------+ | GDB 1 | +-----------------------+ |  04 Feb 82 .... | |  | .... | | +-----------------------+  +-----------------------+ | ACB 1 | +-----------------------+  | | | XST i | | | | EStack 0 | +-----------------------+ | Exceptions 1 |  en. - 4 - PERQ Fault Dictionary 08 Feb 82 _951 About to enable swapping (if booted from hard disk). 952 FSLocalLookup and EnableSwapping complete. 999 ______ ___________ Display Description 374 Disk heads at cylinder 0 (not broken). 375 Microcode instruct System fully initialized, system title line to be printed. - 5 -  Changed maximum of SITSeg. 232 Changed size of SITSeg. 233 Changed maximum of SATSeg. 234 Changeed to consider current position as cylinder 0. 376 Dummy read of cylinder 0, sector 0 complete, about to d size of SATSeg. 235 Created new unallocated segment numbers. 236 Finished InitMemory. 300 InitIO to  dispose buffers and exit LocateDskHeads. 380 LocateDskHeads complete, FindSize to be called. 381 Findbe called. 301 InitIO entered. 302 KeyEnable set false. 303 Buffers allocated. 310 InitInterruSize entered and buffers allocated. 382 Disk access attempt returned. 383 Size of disk determined, about to dispptVectors to be called. 320 InitInterruptVectors complete, InitDeviceTable to be called. 322 Startose buffers and exit FindSize. 390 FindSize complete. 400 Keyboard enabled. 410 InitGPing to initialize ETHERNET. 325 ETHERNET initialized. 330 InitDeviceTable complete, InitScreen to be called. IB to be called. 411 InitGPIB entered, buffers allocated. 412 First GPIB command built. 413 First GPIB c 340 InitScreen complete, InitTablet to be called. 350 InitTablet complete, InitCursor to be called. 360 ommand sent to Z80. 414 Second GPIB command built. 415 Second GPIB command sent to Z80, about to dispose buffers InitCursor complete. 361 Interrupts are now off; about to send device table to microcode. 363 G and exit InitGPIB. 420 InitGPIB complete. 499 Clock enabled, about to exit InitIO. 500 ot control block for Z80 speech. 364 Set up video registers. 365 Screen is now started. 366 Got control  InitIO complete, InitStream to be called. 600 InitStream complete, FSInit to be called. 700 FSInit completblocks for keyboard, RS232, and GPIB. 368 Microcode returned. 369 Interrupts are now turned on. 370 Mie. 800 Command file and Console opened, InitExceptions to be called. 810 InitExceptions completecrocode informed that the device table has been initialized, IO microcode initialization complete, Locat. 820 System version number set. 822 Current 60 Hz. clock value read. 824 60 Hz time reference set, TeDskHeads to be called. 371 LocateDskHeads entered, buffers allocated. 373 Disk heads at cylinder 0 or disk brokimeStamp time reference to be set. 900 FSSetUpSystem to be called. 950 FSSetUpSystem complete.   +-----------------------+ | | | Extra m |he base of the segment. If the segment is not resident in physical memory, this field is undefined. The lower 8 bits of  TP ---->| | +-----------------------+ toward the top of stathe Segment Base Address are always guaranteed to be zero (since all segments are aligned on 256-word boundaries). The ck - 12 - PERQ QCode Reference Manual 04 F Segment Size is one less than the size of the segment in 256-word blocks (i.e., Segment Size 0 = 256 words). The Flaeb 82 1.B.2 Memory Organization at the System Level The system makes use of two tables to control memory usage, tgs have the following meanings and uses: Not Resident - When true, this flag indicates that the he System Segment Address Table and the System Segment Information Table. The former contains all information which is segment is either swapped out or that the segment table entry is not in use. When false, this flag  needed by the Q-Code micro-code (location, size, residency, etc). The latter contains other information which is only r indicates that the entry is in use and the segment it describes is resident in physical memoryeferenced by the operating system (reference, I/O and lock counts; maximum size; etc). 1.B.2.a System Segment Address Table . (See the "Segment Table Entry In Use" flag.) - 13 - PERQ The System Segment Address Table is a dynamic table, which is always resident in physical memory starting at physical  QCode Reference Manual 04 Feb 82 Recently Used - This flag is set when a segment address 0. This table contains two words per segment, and contains all information that the Q-Code micro-code needsis accessed. It is used by the swapper to determine which segments are likely candi to know about each segment. The information contained in this table is: 1) Segment Base Address (upper 12 bitsdates to be swapped out when space is needed. Moving - This flag, when true, indicates that the seg) 2) Segment Size (number of 256 word blocks - 1) 3) Flags Not Resident ment is being moved from one location in physical memory to another. If moving is true, ResiRecently Used Moving Shareable Segment Kind Segment Full dent will be false. Moving is used only by the swapper to determine how to handle segment fau | | | Exceptions m | | |  Segment Table Entry In Use The Segment Base Address is the upper 12 bits of the physical address of t! uced in any form or transmitted, in whole or in part, without the prior written authorization of Three Rivers Com - 1 - User's Guide to Features, Quirks and other Oddities II. Features and Oddities. puter Corporation. The information in this document is subject to change without notice and should not be c _________ PARTITION The Partition program does not turn off swapping. Ifonstrued as a commitment by Three Rivers Computer Corporation. The Company assumes no responsibility for any er the partition that is used for swapping is initialized, the PERQ must be rebooted. The Partition program is caserors that may appear in this document. Three Rivers Computer Corporation will make every effort to keep custo sensitive. A Partition name must be capitalized exactly as it is in the list printed by Partition. mers apprised of all documentation changes as quickly as possible. The Reader's Comments card is distrib ________ TYPEFILE If the TypeFile program thinks there is something wrong wi PERQ Operating System User's Guide to Features, Quirks and other Oddities uted with this document to request users' critical evaluation to assist us in preparing future documentation.  Compiled by Michael R. Kristofic July 17, 1 PERQ is a trademark of Three Rivers Computer Corporation. 981 Any new operating system, still under development, is bound t - ii - User's Guide to Features, Quirks and other Oddities I. Missing Documentation. o have features, quirks, and bugs. This document informs the user of all known oddities of th ______ _________ ____________ MEMORY ALIGNMENT REQUIREMENTS The hard disk requires that the PERQ and its current operating system. It explains quirks and bugs of the e buffers which it uses be aligned on 256 word boundaries. This is only relevent if the user is performing his own cal system, as well as makes up for shortcomings in the PERQ documentation, until approprials to UnitIO in the IO module or I/O routines in the DISKIO module. The standard filesystem calls (such as FSBlkRead)te corrections are made. Copyright (C) 1981 Three Rivers Computer Corporation 720 Gross Str use their own buffers for the actual transfer and then copy the data to the user buffer; hence any alignment is permitted feet Pittsburgh, PA 15224 (412) 621-6250 This document is not to be reprodor the user buffers. ! t Size | BA (16-19) | +--------------------------------+---------------+ d on a quad-word boundary. This is possible since the compiler knows that the base of the segment is also aligned on a qu - 14 - PERQ QCode Reference Manual 04 Feb 82 The positiad-word boundary. It should also be noted that each entry in the dictionary is exactly 2 quad-words long (8 words).lts. (Not used by the Q-Code micro-code). Shareable - When true, this flag indicates that a seons of the flags within the low byte of Word 0 are: Bit Flag --- ---gment may be shared by several processes. (Not used by the Q-Code micro-code) S- 0 Resident 1 Moving 2 Recently egment Kind - This flag indicates whether the segment is a data or code segment. (Not used by the Q-CodUsed 3 Shareable 4 Segment Kind 5 Se micro-code) Segment Full - This flag, when true, indicates that the entire degment Full 6 Table Entry In Use 7 not used 1.B.2.b System Segmata segment has been allocated (via the Pascal New procedure). This flag is needed to ent Information Table There is no information in the System Segment Information Table which is needed by the Q-Code mic distinguish full and empty data segments (and has no relevant meaning for code segments). (Not used by ro-code; hence it is not described here. See "Module Memory" in the Operating System Manual. 1.B.2.c Code Segment Organiza the Q-Code micro-code) Segment Table Entry In Use - This flag is set true when the tion A code segment contains the code for all routines in a segment and a routine dictionary which contains vital infosegment table entry describes a valid segment. The arrangement of these fields within the two words are shown below: rmation about each of these routines. The first word of every code segment is the offset from the base of the s Bit 15 8 7 0 +------------------------+-----------------------+ Word 0 egment to the first word of the routine dictionary. The second word contains the number of routines which are defined in the  | Base Addr (bits 8-15) | Flags | +------------------------+-----------------------+ Bit 15  segment. These two words are followed by the actual code which comprise the routines. Finally, the code is followed by the r 4 3 0 +--------------------------------+---------------+ Word 1 | Segmenoutine dictionary. The code is padded with 0 to 3 words of zero (by the compiler) so that the routine dictionary is aligne" ard disk must still be able to perform a "locate disk heads" operation. Opening or closing the floppy drive door duose names contain those characters. To delete, rename or copy such files, the Shell quote facility must be used. Foring I/O to the hard disk usually causes recoverable disk errors. A Readln on the last line of a file that does r example, to delete a file named *, the command: delete *'* must be used. Repnot contain an end-of-line marker causes a run-time error. - 2 - User's Guide eated use of ^S and ^Q to control the display causes the PERQ to "beep". These "beeps" may be ignored. to Features, Quirks and other Oddities Delete, Rename and Copy ignore extra arguments. Directories can b - 4 - e easily overwritten by specifying a filename of the form "directoryName>" to many utilities. If you dismount the program HowAFileShouldLook; {--------------------------------------------------------------- { { This is a single line of tsystem device the system may not be able to find the SHELL program and you will have to reboot PERQ. Real numbers aitle and author. { Copyright (C) 1980 - Three Rivers Computer Corperation. { { Abstract: { This file provides a template re not implemented. -for all files that are to { be part of the new PERQ software. { { Files are divided into four sections. Each section  3 - User's Guide to Features, Quirks and other Oddities III. Bugs. ______ ______is seperated by a { page break. This is done by placing a formfeed character between { the sections. { { The firstth the file it is displaying, it advises that the Scavenger program should be run. This is not necessary in the case __ PASCAL COMPILER Documentation on bugs in the PERQ Pascal compiler is contained in the dof improperly closed files. If you want to correct the file length, run the Scavenger to rebuild directories and checkocument "PERQ Pascal Extensions." ______ EDITOR The file lengths. ______ ________ PASCAL COMPILER Documentation  editor sets the default filename to the name typed on its command line. If the editor prompts for a filename, the defau on features and oddities in the PERQ Pascal compiler is contained in the document "PERQ Pascal Extensions." lt filename is not changed. _____________ Miscellaneous Sp _____________ Miscellaneous When booting the system from a floppy, the hecifying a wildcard character in the destination filename of many utilities (e.g. the Editor, Plx) may result in files wh" -------+ | not used 2 | +-------------------------------+ | RD Entry for Routine 2 | +-------------------------------+ | RD Entry for Routine 3  toward high memory The Entry and Exit Addresses are the offsets from code base (CB) to the beginning of | +-------------------------------+ toward high memory  the routine and the beginning of the "terminate code" of the routine.  - 17 - PERQ QCode Reference Manual  - 16 - PERQ QCode Reference Manual 04 Feb 82  04 Feb 82 1.C Error Handling and Fault Conditions Error processing is done through an exception han The following is a sample of a code segment containing 3 routines: +-----------------------------dling mechanism. The syntax of exception and handler is described in the PERQ Pascal Extensions manual. The QCodes used to The routine dictionary is indexed by (Base Address of Dictionary)+8*RN. --+ | Pointer to Routine Dictionary | >--+ +-------------------------------+ |  - 15 - PERQ QCode Reference Manual 04 Feb 82 Each entry has the follow | Number of Routines (3) | | +-------------------------------+ | | ing form: +-------------------------------+ | Parameter Size (PS) |  | | | Code for Routine 1 | v |  +-------------------------------+ | Result + Parameter Size (RPS) | +---------------------- | | +-------------------------------+ | | | | ---------+ | Local + Temporary Size (LTS) | +-------------------------------+  | Code for Routine 2 | v | | | +-- | Entry Address Within Segment | +-------------------------------+ | Exit Address Within Se-----------------------------+ | | | | | Code for Routine gment | +-------------------------------+ | Lexical Level (LL) | 3 | v | | | +-------------------------------+  +-------------------------------+ | not used 1 | +------------------------ | | RD Entry for Routine 1 | <--+ +-------------------------------+ #  entry in the log starts with the date, version number and { name of the person who made the change. This is followed by aunction does. { { Parameters: { This section describes the parameters if there are any. { If there are no parameters tn { entry of one or more lines. Each entry is terminated by a { open/close comment pair. { { The third section of his section may be omited. { { Environment: { This section describes any state that must be set up before { the procedthe file contains the global declarations for { the file. This includes both the Exports, if there are any, and { the Pure is called. It may say that the procedure { expects a file to be opened on the file variable Foo. { If there is no srivate parts of the file. { { The forth section of a file starts the list of procedures. Each { procedure consists of etup needed this section may be omited. { { Results: { For a function this section describes the return value. { { Side a procedure header followed by a block of { documentation for the procedure followed by the declarations and code { for Effects: { This section describes any global state that the procedure { may modify. If there are no side effects then tthe procedure. Procedures should appear one per page. { See the procedures in this file for more details on how they { his section { may be omited { { Errors: { This section describes the errors that may occure during the { executioshould be structured. { { {--------------------------------------------------------------- { } { This is a formfeed charan of this procedure. This section must describe the errors { AND how they are reported to the outside world. { If therecter } { 21-Nov-80 1.1 Don Scelza { Updated this file. Moved the copyright notice. { Added the second change log entry.  are no errors then this section may be omited. { { Calls: { This section gives a list of the procedures that are called b{} { 10-Nov-80 1.0 Don Scelza { This is the change log section of the file. { It contains information about the last tiy this { procedure. If there are no procedures called then this section { may be omited. { { Design: { This sectime that the file was changed. { New entries go at the top of the list. { } { } Exports function Funct(Parm1, Parm2: ): ; Private Const Version = '1.1'; { }------------------------------------------------------- begin end;  section contains a) the author, b) the copyright notice { and c) the abstract for the file. The abstract gives a general function Funct(Parm1, Parm2: ): ; {------------------------------------------------------ { { Abstract:  { indication of what can be found in the file. { { The second section of the file contains the change log. Each {  { This is how a procedure/function should look. { The Abstract section gives a description of what the { procedure/f# eption handler is simply a procedure--handlers may not return a value. An exception handler is enabled by declaring it rds are popped from the run-time stack along with the rest of the activation record. - 1inside some routine. This outer routine is called the enabler of the handler. The code segment numbers and global pointer8 - PERQ QCode Reference Manual 04 Feb 82 When an exception is raised, the Qs of the enabler and handler are the same. The static link of the handler is the same as the activation pointer of thCode interpreter microcode calls the procedure RaiseP in the module Except. This routine searches back through the rue enabler. Thus an exception handler is uniquely identified by the ACB of the enabler and the routine number of the handn-time stack to find the most recent routine which contains a handler for that exception. Once such a candidate is fouler. An exception enable record consists of the definition of the exception to be handled (ER and ES), the round, the stack is searched again to determine if that handler is already active. If it is, the search for a candidate conttine number of the handler (HR), and a link to the next exception enable record (NE). ER and ES are negative for a handler oinues. This implementation ensures that while a particular instance of a handler is active, it will not be activated agaf all exceptions. +-----------------------------------------+ | Exception Segment Number (ES) in. A recursive routine may contain a handler, and there may be several instances of the same handler. In this cas | +-----------------------------------------+ | Exception Routine Number (ER) | e, each handler is activated separately. Determining if a handler is active by searching the stack is not the bes enable and raise exceptions are described in Section "Routine Calls and Returns." An exception is declared in a way +-----------------------------------------+ | Handler Routine Number (HR) | +------------- which is similar to a procedure declaration. Therefore it is convenient to assign a routine number at the point o----------------------------+ | Next Exception Pointer (NE) | +-----------------------------f definition of an exception. There is a corresponding entry in the routine dictionary to describe this exception. This ------------+ When a routine is called, the exception pointer (EP) within the new ACB is set to zero to indicatentry describes a procedure with the correct number of parameters along with no locals or temporaries. The system segmee that there are no exception handlers. If exception handlers are declared within the routine, the compiler generates apnt number of the module, which contains the exception, and its routine number uniquely identify the exception. An excpropriate QCodes to add those handlers to the routine's exception list. When a routine is exited, the exception reco$ o keep customers apprised of all documentation changes as quickly as possible. The Reader's Comments card is dumber of directories. The main directory in a partition (the one you get if you simply specify the partition name) is the istrib- uted with this document to request users' critical evalu- ation to assist us in preparing future documentation. PERQ is a trademark of Three Rivers Computer Corporation.  PERQ File System Utilities Manual Brad - ii - PERQ File System Utilities Manual - Notation Conventions 04 Feb 82 1.  A. Myers This manual describes the PERQ file system utilities: Partition, Scavenger, M Preface: Notation Conventions. The notations used below have been clearly and consistently used throughout this docakeBoot, and FixPart. Other utili- ties are described in the manual "PERQ Utility Programs Manual." In additionument. ______ _______ SYMBOL MEANING , relevant parts of the file system are described so the programs can be understood. Copyright (C) [] optional feature {} 0 to n repetitions CAPI 1981, 1982 Three Rivers Computer Corporation 720 Gross Street Pittsburgh, PA 15224 (412) 621-6250 PETALS literal lowercase or LowerCase metaname ^ RQ File System Utilities Manual 04 Feb 82 This document is not to  control key CR carriage return SHIFT be reproduced in any form or transmitted in whole or in part, without the prior written authorization of Thre shift key | or e Rivers Computer Corporation. The information in this document is subject to change without notice and s - 1 - PERQ File System Utilities Manual - Introduction 04 Feb 82 2. Introduction. Thould not be construed as a commitment by Three Rivers Computer Corporation. The Company assumes no responsibilihe PERQ has a hierarchical, multi-directory file system which supports search lists and noncontiguous files. Devices (e.ty for any errors that may appear in this document. Three Rivers Computer Corporation will make every effort tg., hard and floppy disks) are divided into a number of sections called "partitions." Each partition can contain any n$ xception. This should rarely be burdensome because it is not expected that there will be more than one or two active ha Instructions on the Q-machine are one byte long followed by zero to four parameters. Parameters are either a signed byte ndlers for a given exception. Recursive routines that pass exceptions up the call stack are pathological cases.  (B : range -128 to 127), an unsigned byte (UB : range 0 to 255) or a word (W). Words need not be word aligned (unless spec When an unused enable for the exception is found, the associated handler is called. The handler has the option ofified). The low byte is first in the instruction byte stream. Any exceptions to these formats are noted with the ins exiting to the routine which enabled the exception (via a Goto) or of returning to the point where the exception watructions where they occur. 3. Pointers There are five different types of pointers, defined as follows: (Note: 2s raised (by falling off the end of the procedure). If no handler is found, the default handler is called. The se0-bit offsets may only exist on the EStack). Word Pointer: A 20-bit offset from StackBase (StackBase is the arch order for a certain routine's exception list is the reverse of the order in which they were enabled. If a handler 20 bit physical address of the base of the stack). Byte Pointer: A 20-bit offset from StackBase to the base of the  of all exceptions is declared within a certain routine, the compiler enables it first. A handler of all excep byte array (TOS-1) and a byte offset into the array (TOS). String Pointer: Same as a byte pointer. Packed Fitions is called in a special way. When it is called, the parameters that were passed when the exception was raised have alreld Pointer: A 20-bit offset from StackBase to the base of the word the field is in (TOS-1) and a one word field eady been pushed onto the stack. A new activation record for the handler is built above those parameters. Such a han descriptor (TOS). Field Descriptor: Bits 0-3: The field width (in bits) minus 1 Bidler for all exceptions must have four words of parameters: the segment and routine numbers of the exception that was rats 4-7: The rightmost bit of the field. Pascal Pointer: Obtained by declaring a variable as a pointer to anothised, a pointer to the first word of the original parameters, and a pointer to the first word after the original parameterser data type (i.e., var I: ^Integer;). (TOS-1) is the system segment number that contains the datum. (TOS) t method. If we assume that the depths of handler activation records are related to the number of active handlers, t. The two pointers are represented as integer offsets from the base of the stack. hen the total stack search time for raising an exception is related to the square of the number of active handlers of that e - 19 - PERQ QCode Reference Manual 04 Feb 82 2. Instruction Format %  read a file system floppy. To create a file system floppy, use the Partition program described below. The user pros this constraint. No file or directory can be in more than one partition (a file cannot cross a partition boundary). grams that handle the file system are described in the "PERQ Utility Programs Manual" and only Partition, Scavenger, Ma Therefore, having free blocks in one partition does not prevent you from running out of free blocks in another. ThkeBoot, and FixPart are described in detail here. To create a file system on a blank disk, it is necessary to run the commae Partition program is used to create and modify the partitions on a device. Creating a partition usually destroys all old datnd file "InitDisk.Cmd" which is found on the boot floppy in every release package. A heavily-commented printed copy ofa in the area where the partition is made. The device should first be formatted (by using DTST on hard disks or FLOPPRoot directory for that parti- tion. All directories can contain other directories and files. Directories are stored  this command file is provided as instructions for how to initialize a blank device. To create a file system on aas standard files and can be accessed by any program. However, the system knows special things about their format. Al floppy, use the Partition program described below. The manual "How To Make a New System" describes the process necessaryl files in this file system can be noncontiguous; blocks for files may be scattered throughout the partition in which they  to create a system using the MakeBoot program. This manual provides the background necessary to understand these processes. reside. The naming conventions for filenames are described in detail in "The PERQ Introductory User Manual" but all - 2 - PERQ File System Utilities Manual - Partitions 04 Feb  are of the form: [[[device]:partition]>]{directory>}[filename] Files may be stored on floppy disks in two ways. The82 3. Partitions and the Partition Program. The partitions on a device are restricted to be fewer than 32768 blo FLOPPY program can be used to transfer files to and from the floppy, or the floppy can be initialized as part of the file cks, where each block is 256 words (512 bytes, 4096 bits). The block size is fixed for all devices. On a 12-megabyte di system. These types of floppy disks are called "FLOPPY floppies" and "filesystem floppies" respectively. NOTE: Flopsk or a floppy, the entire device can be in one partition. On a 24-megabyte disk, at least 2 partitions are needed. We recompies of one type CANNOT be used for the other; the formats are totally incompatible. Floppy disks that contain files transfer-mend, however, that each partition have 10080 or fewer blocks in them, otherwise Scavenger (described below) cannot ha red by the program FLOPPY must be accessed by the FLOPPY program (and not by the file system directly), and FLOPPY cannotndle the partition in one pass. All partitions must start and end on cylinder boundaries; the Partition program enforce% assignment of all EQU,NEQ,LEQ,LES) NEQBool = 34; (GEQ and GTR qcodes are important LEQBool = 35; LESBool  LDLB = 107; LDLW = 108; LDL0 = 109; LDL1 = 110; LDL2 = 111; LDL3 =  is the offset from the segment base to the datum. Implementation Note: Stacks grow from low addresses to high = 36; GEQBool = 37; GTRBool = 38; - 21 - PERQ QCode Reference Manu addresses (i.e., if the address of TOS is 10 then the address of TOS-1 is 9 -- not 11). al 04 Feb 82 EQUI = 39; NEQI = 40; LEQI = 41; LESI  - 20 - PERQ QCode Reference Manual 04 Feb 82 4. QCode Descrip = 42; GEQI = 43; GTRI = 44; EQUStr = 51; NEQStr = 52; LEQStr = 53; LEtions This section provides a detailed description for each QCode. The QCode descriptions appear categorically. ThSStr = 54; GEQStr = 55; GTRStr = 56; EQUByt = 57; NEQByt = 58; LEQByt = 59; e following lists the QCodes and equates each with its respective QCode number. Thus, if you only know the QCode number, yo LESByt = 60; GEQByt = 61; GTRByt = 62; EQUPowr = 63; NEQPowr = 64; LEQPowr = 65; u can use the list to equate the number to the named QCode. QCode OpCode Definitions: LDC0 = 0; (Assi SGS = 66; (there is no LESPowr GEQPowr = 67; SRS = 68; (there is no GTRPowr EQUWord = 69gnment of Byte/Word opcodes are important) LDC1 = 1; LDC2 = 2; LDC3 = 3; LDC4 = 4; ; (Word is the last comparison and only EQU NEQWord = 70; and NEQ exist) ABI = 71; ADI = 72;  LDC5 = 5; LDC6 = 6; LDC7 = 7; LDC8 = 8; LDC9 = 9; LDC10 = 10;  NGI = 73; SBI = 74; MPI = 75; DVI = 76; MODI = 77; CHK = 78; LDC11 = 11; LDC12 = 12; LDC13 = 13; LDC14 = 14; LDC15 = 15; LDCMO = 16 INN = 88; UNI = 89; QINT = 90; DIF = 91; EXITT = 92; NOP =; LDCB = 17; LDCW = 18; LSA = 19; ROTSHI = 20; STIND = 21; LDCN  93; REPL = 94; REPL2 = 95; MMS = 96; MES = 97; LVRD = 98; LSSN = 22; LDB = 23; STB = 24; LDCH = 25; LDP = 26; STPF = 27; STCH  = 99; XJP = 100; RASTOP = 102; STRTIO = 103; INTOFF = 105;  = 28; EXGO = 29; QAND = 30; QOR = 31; QNOT = 32; EQUBool = 33; (Opcode  - 22 - PERQ QCode Reference Manual 04 Feb 82 INTON = 106; &  you want to partition the entire disk. Answer "YES" if you are starting from scratch (for example, on a newly formatt The next question is whether to test after initializing the pages. Although this slows down the initialization somewhat, it ed floppy or when installing the file system on a new machine). If you want to modify an existing device, answer "NO". Ifis good practice to do this testing. If any pages are found to be bad during testing, they are removed from the free list so you answered "YES" to initialize the entire disk, then the program asks for information about each partition in tur they will never be accessed again. The final question asked before initiali- zation is whether to write every page twice. n. The device must first be given a name (eight or fewer characters). Next, each of the partitions must be given a na This provides some additional protection from bad pages since random data is written into the header and body of each me (also eight or fewer characters). Examples of partition names used for the hard disk include "boot", "user", and "ex block. It has been found in practice that some bad blocks on the disk will pass the first test and fail this one. p". There is no problem with having a partition with the same name as a device, but all the partitions must have uniAfter all the blocks on the device have been included in a partition, the program displays some data about the devicque names. The size of each partition is also requested. As mentioned earlier, we have found that 10080 or fewer blockse and asks whether to remount the device. Only mounted devices can be accessed, so if you plan to use the device, saY for floppy disks). After formatting, Partition is the first program to run. Partition asks whether you want to "debug". I are desirable; otherwise Scavenger (described below) cannot handle the partition in one pass. This means there are 3 f you answer "YES", then nothing will be modified on the device. Answer "NO" if you want to make modifications. Nexpartitions on a 12-megabyte disk and 5 on a 24-megabyte disk. The minimum size for partitions is 120 blocks on a 12 megabytet, Partition requires that you tell it what device you want to modify. The choices are the harddisk or floppy. If you spec disk, 240 blocks on a 24-megabyte disk, and 6 blocks on a floppy disk. The sizes of all partitions must be multiples oify the harddisk, Partition checks to see whether the disk is a 12 or 24-megabyte disk. It then asks for confirmation f the mimimum size for - 3 - PERQ File System Utilities Manual - Partitions of the size chosen. If you specified the floppy, you then have to tell partition whether the floppy is or single or double-sid 04 Feb 82 that device. For each partition on the device, the program asks whether to initialize the partitioed. A floppy that is formatted on both sides can be partitioned as either single or double sided. Next, the program asks ifn pages. This process puts all the pages in the partition on the free list and therefore should be done for a new device. & OB = 157; STOW = 158; STO0 = 159; STO1 = 160; STO2 = 161; STO3 = 162 = 224; IXA3 = 225; IXA4 = 226; TLATE0 = 227; TLATE1 = 228; TLATE2 = 229; ; STO4 = 163; STO5 = 164; STO6 = 165; STO7 = 166; MVBB = 167; MVBW  EXCH = 230; EXCH2 = 231; INCB = 232; INCW = 233; CALLXB = 234; CALLXW  = 168; MOVB = 169; MOVW = 170; INDB = 171; INDW = 172; IND0 = 173;  = 235; LDMC = 236; LDDC = 237; LDMW = 238; LDDW = 239; STLATE = 240;  IND1 = 174; IND2 = 175; IND3 = 176; IND4 = 177; IND5 = 178; IND6  QLINE = 241; ENABLE = 242; QRAISE = 243; LDAP = 244; ROPS = 250; (See below for 2n112; LDL4 = 113; LDL5 = 114; LDL6 = 115; LDL7 = 116; LDL8 = 117; LD = 179; IND7 = 180; LDIND = 173; (Same as IND0)) LGAWW = 181; STMW = 182; STDW L9 = 118; LDL10 = 119; LDL11 = 120; LDL12 = 121; LDL13 = 122; LDL14 = 123 = 183; SAS = 184; ADJ = 185; CALLL = 186; CALLV = 187; ATPB = 188; ; LDL15 = 124; LLAB = 125; LLAW = 126; STLB = 127; STLW = 128; STL0  ATPW = 189; WCS = 190; JCS = 191; LDGB = 192; LDGW = 193; LGAB  = 129; STL1 = 130; STL2 = 131; STL3 = 132; STL4 = 133; STL5 = 134;  = 194; LGAW = 195; STGB = 196; STGW = 197; RETURN = 200; MMS2 = 201;  STL6 = 135; STL7 = 136; LDOB = 137; LDOW = 138; LDO0 = 139; LDO1  MES2 = 202; LDTP = 203; JMPB = 204; JMPW = 205; JFB = 206;  = 140; LDO2 = 141; LDO3 = 142; LDO4 = 143; LDO5 = 144; LDO6 = 145;  - 24 - PERQ QCode Reference Manual 04 Feb 82 JFW =  LDO7 = 146; LDO8 = 147; LDO9 = 148; LDO10 = 149; LDO11 = 150; LDO12 =207; JTB = 208; JTW = 209; JEQB = 210; JEQW = 211; JNEB = 212; JN 151; LDO13 = 152; LDO14 = 153; LDO15 = 154; LOAB = 155; EW = 213; IXP = 214; LDIB = 215; LDIW = 216; LIAB = 217; LIAW = 218 - 23 - PERQ QCode Reference Manual 04 Feb 82 LOAW = 156; ST; STIB = 219; STIW = 220; IXAB = 221; IXAW = 222; IXA1 = 223; IXA2 '  Before renaming a device or partition it is important to note that every Run file on the device has incorporated in it the dns 04 Feb 82 order of the partitions on the disk matters. If you want to erase the new, bigger partition, sevice and partition name where it was linked. If you rename the device, then no program on that device can be run (incay that you want to initialize the pages. If not, then all the files on both partitions can be saved. Just after Partiluding the Shell, Login, Partition, for example). If you rename a partition, no program in that partition can be run. tion exits, you must run Scavenger program (see below) on the new partition. When running the Scavenger in this case If you did not rename the device, you are asked which partition you want to modify. Type the name of one of the par, be sure to tell it to rebuild the directories so that the directories of the two partitions can be joined together. Ptitions. The program then asks what you want to do to the partition. You can split a partition into two parts, merge a artition also can change the name of a partition. Do not change the name of the partition that is used in the current path  partition with another, initialize a partition, or change the name of a partition. It is never a good idea to split a pasince the default path name then becomes invalid. In addition, all entries in the search list that refer to the partition renrtition with files in it since files cannot cross partition boundaries. Any file which has blocks in both partitions will bamed will no longer work. After a rename, therefore, the system may not be able to find the Shell or any other programs. e destroyed. It is safe to split an empty partition or one that you plan to erase. The program asks how much of the partit Finally, you can initialize the partition. This is a fast way to delete all the files in the partition. After askingion to leave with the old name; the rest of the blocks in the partition will be put in the partition just created. The pr whether to initialize the partition, the program asks whether to initialize the partition pages. If you answer "NO", you musogram will ask if you want to initialize the partition pages to create a new free list. This is recommended. Next, a name t use Scavenger program to recreate the directory immediately after running Partition. There are few reasons to initialiy "YES". If you said that you did not want to initialize the entire device, the program reads the device information blfor the new partition is solicited and the pages are initialized if desired. It is much safer to merge two partitions togetock (which is in a reserved, fixed location on cylinder 0) to find what partitions are currently on the device. These arher than to split one apart. You specify the first partition and it is joined with the partition which is next on the dise displayed in the order they appear on the disk. The first question asked is whether to rename the device. NOTE:k. This is the only time the - 4 - PERQ File System Utilities Manual - Partitio'  NGL = 3; SBL = 4; MPL = 5; DVL = 6; MODL = 7; ABL hes the word with offset UB in the current activation record and = 8; EQULong = 9; NEQLong = 10; LEQLong = 11; LESLong = 12; GEQLong = 13; pushes it on the EStack. LDLW W 108 Load Local Word/Word Offset. Fetches the GTRLong = 14; LUnused = 15; 4.A Variable Fetching, Indexing, Storing and Transferring 4.A.1 Loads and Stores word with offset W in the current activation record and pushes it on the EStack.  of One Word 4.A.1.a Constant One Word Loads LDC0..15 0-15 Load Word Constant. Pushes the value  LLAB UB 125 Load Local Address/Byte Offset. Pushes a word pointer to the word with (0..15), with high byte zero, onto the EStack. LDCN 22 Loa offset UB in the current activation record on EStack. LLAW W 126 Load Local Address/Wod Constant Nil. Pushes the value of NIL onto the EStack. LDCMO 16 Load Constant -1.rd Offset. Pushes a word pointer to the word with offset W in the curre - 26 - PERQ QCode Reference Manual 04 Feb 82 nt activation record on EStack. STL0..7 129-136 Short Store Local Word. Store (ETOS) into d byte) INCDDS = 251; LOPS = 252; (See below for 2nd byte) BREAK = 254; ReFillOp = 255;  LDCB B 17 Load Constant Byte. Pushes the next byte on the EStack, with sign extenReal Operations - Second byte of ROPS opcode: TNC = 0; FLT = 1; ADR = 2; NGR =d. LDCW W 18 Load Constant Word. Pushes the next word on the EStack.  3; - 25 - PERQ QCode Reference Manual 04 Feb 82  - 27 - PE SBR = 4; MPR = 5; DVR = 6; RND = 7; ABR = 8; EQUReal = 9;RQ QCode Reference Manual 04 Feb 82 4.A.1.b Local One Word Loads and Stores LDL0..15  NEQReal = 10; LEQReal = 11; LESReal = 12; GEQReal = 13; GTRReal = 14; RUNUSED = 109-124 Short Load Local Word. LDLx fetches the word with offset x in the current activation 15; Long Operations - Second byte of LOPS opcode: CVTLI = 0; CVTIL = 1; ADL = 2;  record and pushes it onto the EStack. LDLB UB 107 Load Local Word/Byte Offset. Fetc( ze the partition without initializ- ing the pages. The Partition program can take a switch on the command line. If it is Scavenger checks and fixes some system information and then checks all files in a partition for consistency and recre invoked with the /BUILD switch, then the entire device is partitioned. Note that the arguments must be specified ates the free list. It can also recreate the directories. The Scavenger also removes bad boots. The Scavenger should on the command line. This is a dangerous thing to do and it is only recommended for command files which bring up an be run whenever an inconsistency is found in the file system or when some program aborts and asks you to run the Scavenger. entire disk. The format for this switch is Partition/Build ... where  WARNINGS: 1) As with the Partition program, do not type Control-C (^C) to Scavenger after it has begun wr is either "H" for the hard disk or "F" for the floppy. The device name is given next followed by enough partition namesiting on the device. During the read pass, it is safe to ^C. If you type ^C after it begins r for the entire device. The partition names are used in the order specified so the first name will be used for the fiebuilding the directory, you may not be able to access anything in the directo- ry. If this haprst partition on the disk. All partitions except the last will be the standard size (10080 blocks). If extra partition npens, rerun Scavenger from another partition. 2) Scavenger will not be able to recreate the direcames are specified, they are ignored. If the device seems to be already formatted, the program requires confirmation befotory if there are no free blocks in the partition. Therefore, if your partition is full, you musre erasing the device. If the user answers NO, then partition is run the normal way asking the user all the questions. t delete some files before running Scavenger. If you cannot delete any files due to a bad  - 5 - PERQ File System Utilities Manual - Scavenger directory and there are no free blocks, then there is currently no way to rebuild the directory.  04 Feb 82 4. The Scavenger Program. The Scavenger program fixes a partition on a device that contains us In this case, you must initialize the partition, thus losing all files there. Fortunately, eful files. It checks all files for consistency, rebuilds the free list, and creates a new directory structure for the pawe have never seen this happen in practice. Scavenger program fixes one partition at a time. It is possible (and somertition. The Scavenger should only be run on devices that have already been initialized by the Partition program. The times necessary) to scavenge partitions other that the one you are currently running in. It is usually safe, however, t( et W in the current activation record. Implementation Note: The address of the first local B UB 157 Store Own Word/Byte Offset. Stores (ETOS) into the word with offset UB in the (offset 0) is contained in the Local Pointer register (LP). The address of the Nth local is computed as (LP) + N. current Global Data Block (GDB). STOW W 158 Store Own Word/Word Offset. Stores (ETOS - 28 - PERQ QCode Reference Manual 04 F) into the word with offset W in the current Global Data Block (GDB). eb 82 4.A.1.c Own One Word Loads and Stores LDO0..15 139-154 Short Load Own Word. LDOx fetches the word  Implementation Note: The address of the first own (offset 0) is contained in the Global Pointer register (GP). The addr with offset x in the current Global Data Block (GDB) and pushes it on the EStaess of the Nth own is computed as (GP)+N. - 29 - PERQ Qck. LDOB UB 137 Load Own Word/Byte Offset. Fetches the word with offset UB in the currCode Reference Manual 04 Feb 82 4.A.1.d Global One Word Loads and Stores LDGB UB1,Uent Global Data Block (GDB) and pushes it on the EStack. LDOW W 138 Load Own Word/WorB2 192 Load Global Word/Byte Offset. Loads the word with offset UB2 in the Global Data d Offset. Fetches the word with offset W in the current Global Data Block Block (GDB) for program segment UB1 onto EStack. LDGW UB,W 193  (GDB) and pushes it on the EStack. LOAB UB 155 Load Own Address/Byte Offset. Pushes a word Load Global Word/Word Offset. Same as LDGB except a full word offset is used. LGAB UB1,UB2 194  pointer to the word with offset UB in the current Global Data Block (GDB) on EStack. LOAW  Load Global Address/Byte Offset. Pushes a word pointer to the word with offset UB2 in  word with offset x in the current activation record. STLB UB 127 Store Local Word/Byte  W 156 Load Own Address/Word Offset. Pushes a word pointer to the word with offset W in BOffset. Store (ETOS) into word with offset UB in the current activationASE activation record on EStack. STO0..7 159-166 Short Store Own Word. STOx stores (ETOS record. STLW W 128 Store Local Word/Word Offset. Store (ETOS) into word with offs) into the word with offset x in the current Global Data Block (GDB). STO) is bad file in phase three of Scavenger. In phase three, the directories for the partition are completely rebuilt. Scs, for example, happens when a transfer is aborted. The Scavenger asks the user a number of questions before it begins pravenger will delete the old directories, if desired. Otherwise, the old directories are marked as such and their names hocessing the partition. First, it asks whether to look at the floppy or hard disk. It then checks that device to see how ave a "$" added to the end. If there is not enough room for copies of all the directories in the partition to be created,  big it is and then asks if its choice is correct. When it has this information, Scavenger asks if it can make changes too scavenge the current partition. Scavenger program has three separate phases. In phase one, it checks and updatesScavenger will crash leaving the directories only partially created. In this case, you have to delete some of the files in t some of the system information. In this phase, bad boots are deleted. If a boot has been defined by MakeBoot (see below) he directory and then rerun Scavenger. Before entering any name in a directory or creating a new directory, Scavenger firstbut either the microcode or system code files have been deleted, the boot is known to be bad. The Scavenger cannot tel checks to make sure the name seems reasonable as a filename. Certain characters are not allowed in filenames. These incl, however, if a boot file is deleted and another created in the same place before Scavenger is run. In this case, the bolude any control characters, "<", "/", ":", and " ". In addition, the name may not end with a ">" or contain ">ot will seem valid but will not work. During the second phase of the scavenge, the partition specified by the user is ch..>" or ">.>". If a bad name is found, or two files have the same name, Scavenger requests a new filename from the user. ecked for consistency. All blocks are read and a new free list is generated in ascending disk order (the old free list is di After Scavenger is finished, you can examine the files with bad names to see whether they contains any useful informatscarded). In addition, blocks that are not readable are marked as "bad", and if they cannot be rewritten, they are maion. If so, rename or edit the files to recover the data. Otherwise, simply delete the files. The Scavenger in this pass arked as "incorrigible" and removed from the file system. All blocks that - 6 - lso makes sure the length of all files are correct and allow you to specify a new length. Note that this refers to the stPERQ File System Utilities Manual - Scavenger 04 Feb 82 were in files containing bad or incorrigible blocks ored length rather than the number of blocks in a file. Certain files, like directories and swap files, do not bother to sare put in the bad file. In addition, any malformed chains are added to the bad file. The user is asked for a name for thet the length field. File lengths usually become wrong when the file is opened and written but not closed properly. Thi)  the Global Data Block (GDB) for program segment UB1 onto EStack. LGAW UB,W b 82 4.A.1.e Intermediate One Word Loads and Stores LDIB UB1,UB2 215 Load Intermediate Word/Byte Offset.  195 Load Global Address/Word Offset. Same as LGAB except a full word offset is used. LGAWWUB1 indicates the number of static links to traverse to find the activat W1,W2 181 Load Global Address/Word Segment, Word Offset. Same as LGAB except a full woion record to use. UB2 is the offset within the activation recordrd is used both for the segment number and the offset. STGB UB1,UB2  of the desired word. The datum is pushed on EStack. LDIW UB,W 216 Load Intermediate Wor196 Store Global Word/Byte Offset. Stores (ETOS) in word with offset UB2 in the Global d/Word Offset. Same as LDIB except a word offset is used. LIAB UB1,UB2 217 Load Intermediate Data Block (GDB) for program segment UB1. STGW UB,W 197 Store Global Word/Word Offset. Same as Address/Byte Offset. A word pointer is pushed on EStack (determined as in STGB except a full word offset is used. Note: To achieve LDGW and STGW w LDIB). LIAW UB,W 218 Load Intermediate Address/Word Offset. A word pointer is pushed ith full word segment numbers, use LGAWW with LDIND or STIND. Impleon EStack (determined as in LDIW). STIB UB1,UB2 219 Store Intermediate Word/Byte Offset. Stomentation Note: Self-relative pointers to the Global Data Blocks (GDB) for each externally referenced segment are contained inres (ETOS) in memory (address determined as in LDIB). STIW UB,W 220 the External Segment Table (XST), pointed to by the Global Pointer (GP). The address of the first global (offset 0) in th Store Intermediate Word/Word Offset. Stores (ETOS) in memory (address determined as in e designated GDB is computed as GP - 2 * ISN, where ISN (Internal Segment Number) is the program segment number specified LDIW). Implementation Note: The Activation Pointer register (AP) contains the address of the cu in the load or store instruction. The Nth global is addressed by the base address (computes as above) plus N. rrent Activation Control Block (ACB). Within the ACB is the Static Link (SL) to the previous ACB. To compute the addre - 30 - PERQ QCode Reference Manual 04 Fess of the first intermediate word of the desired level, traverse the Static Links to the correct ACB. Within the ACB is the * aborts due to FullMemo- ry, answer "NO" to one of these questions. To avoid the FullMemory condition on machines with 256k ed by the previous scavenge of this partition is added to the free list. Finally, Scavenger asks if it can rewrite babytes of main memory, the default - 7 - PERQ File System Utilities Manual - Scavend blocks. If a block cannot be successfully read in the specified number of retries, it is possible that writing new data ger 04 Feb 82 for serial number checking is no. Just type CR to get the default answer. Then Scavenger  onto the block will fix the problem. However, for our hard disks, this seems to have a small chance of fixing the problem. asks if there is enough memory to do the scavenge in one pass. If your partition has 10080 or fewer blocks in it and if the Therefore, the default answer is "NO". However, if you answer "YES", the bad blocks will be rewritten. If the write or a  screen has been shrunk (the Shell shrinks the screen when it knows you are running the Scavenger), then the answer is "YEsubsequent read fails, then the block is "incorrigible", otherwise it is "bad". If rewritting is not permitted, thenS". If your partition is bigger than 10080 blocks, then answer "NO". Three passes will then be used and the program will the block is marked "incorrigible" as soon as the read fails. If there are only transient read errors, the block is left alo the device in the first two phases of the program (the directory fixing is handled later). This is like the "debug option" be correspondingly slower. The next question is how many retries for a suspect read. The default is 15. If the Sca for the Partition program. If you answer "NO", then Scavenger checks the partition for errors and reports them but does nvenger aborts with the error "block xx was found bad during... but was thought to be good before" or if it aborts duringot fix anything. If you are running Scavenger only to fix the directory, it is about twice as fast to answer "NO" to this rebuilding of the directories, try rerunning the Scavenger with a smaller number. One is the smallest valid answer. I question; otherwise, "YES" is a good idea. Next, Scavenger asks if it should do logical block number consisten- cy testinf you answered "YES" when asked if Scavenger could change your disk, you will be asked three more questions about ways g and serial number consistency testing. The header of every block contains information about the state of that block. TheScavenger might change the disk. First, Scavenger asks whether it should delete temporary files. Temporary files ex information includes the count of the block in the file (is it the first, second, etc.) and a two-word identifier for thist for swapping; all user files are permanent. Second, the Scavenger asks if it should delete old bad segments. As descre file the block belongs to. These numbers are checked for correctness if you answer "YES". If the Scavenger continually ibed above, files with bad blocks in them are marked as bad. If you answer "YES" to this question, then the bad file creat*  double word and (ETOS-2) is a word pointer to a double word block of memory.  Store Byte. Store the low byte of (ETOS) into the location specified by byte pointer  The double word is popped from ESTACK into the double word pointed to by (E (ETOS-1),(ETOS-2). MVBB UB 167 Move Bytes/Byte Counter. (ETOS),(ETOS-1) is TOS-2). 4.A.2.b Multiple Word Loads and Stores (Sets) LDMC UB, 236 Load Multiple Word Constant. UB is th a source byte pointer to a block of UB bytes, and (ETOS-2),(ETOS-3) is the Local Pointer (LP) for that activation record. - 31 - e number of words to load, and is a block of UB words, in revers PERQ QCode Reference Manual 04 Feb 82 4.A.1.f Indirect One Word Loads and Stores STe word order. Load the block onto the MStack. LDMW 238 Load Multiple words. (ETOS-1IND 21 Store Indirect. (ETOS) is stored into the word pointed to by word pointer (ETO) is a word pointer to the beginning of a block of (ETOS) words. PS-1). LDIND 173 Load Indirect. Word pointed to by word pointer (ETOS) is pushed ush the block onto the MStack. STMW 182 Store Multiple Words. The MStack containon EStack. s a block of (ETOS) words, (ETOS-1) is a word pointer to a similar block - 32 - PERQ QCode Reference Manual 04 Feb 82 4.A.2 Loads and Stores of Mult. Transfer the block from MStack to the destination block. iple Words 4.A.2.a Double Word Loads and Stores (Reals and Pointers) LDDC 237 Load Double Word Constant.  - 33 - PERQ QCode Reference Manual 04 Feb 82 4.A.3 Byte is a double word constant. Load the constant onto EStack.  Arrays Note: A byte pointer is loaded onto the stack with a LLA, LOA or LGA of the base address of the array followeLDDW 239 Load Double Word. (ETOS) is a word pointer to a double word. The double wordd by the computation of the offset. LDB 23 Load Byte. Push the byte (after zeroing the  is pushed onto EStack. STDW 183 Store Double Word. (ETOS),(ETOS-1) is a  high Byte) pointed to by byte pointer (ETOS),(ETOS-1) on EStack. STB 24 + ither, the problem may be that: 1) you specified the wrong device type to the first question; 2) the device is not a file sys some more reads and writes are necessary to make the bad blocks into a well-formed chain. After this pass, Scavenger tem device (e.g. a FLOPPY floppy); 3) the device has not been initialized; or 4) the device has been messed up beyond  writes the new partition information block. Next, the directory building pass is started. Scavenger asks whetherrepair. Unfortunately, the only fix in this case is to re-partition the device from scratch. After the device and part it should rebuild the directory. Sometimes it recommends that you do this, otherwise there is no default. If you suspition information checks out, Scavenger displays a list of the partition names and asks which one it should work on. Typect there is a problem with the directories and if there are enough free blocks, answer "YES". The old directories will be e the name of the partition to be scavenged. Next, Scavenger will display some information about the specified parti- tdeleted, if you so specify. Otherwise they are saved for later inspection. A "$" is appended to the end of their names andion. The values are those stored in the partition information - 8 - PERQ File S their file type is changed to ExDirFile (directories all have the type DirFile). New director- ies are then created whenystem Utilities Manual - Scavenger 04 Feb 82 block before the scavenge. Now Scavenger makes a read pass throever needed. This means that empty directories are not recreated. The old directories are just files that you can deleugh the partition building tables of each block's next and previous link (this is the data usually visible in the lowerte after the scavenge. Note: This scheme makes it easy to recover from overwriting or deleting a directory since the portion of the screen). The pass is done in eight parts for efficiency. There- fore, the Scavenger cursor goes down th directory reappears after a scavenge. As described above, the Scavenger checks and allows fixing file lengths if desne. After you answer all of the questions, Scavenger can get to work. The title line of the window is updated to show e screen eight times before the next step. The tables built by Scavenger are now checked for consistency, and the cursowhat Scavenger is working on. In addition, various cursors are used to show the progress of the different passes. Fir changes to show that checking is in progress. If any loops are found, Scavenger breaks the loops and blinks the screrst, Scavenger does phase one checking as described above, fixing any discrepancies if you allowed changes. If Scavenger finen to show that a loop has been fixed. Afterwards, if changing the device is allowed, the Scavenger rebuilds the free list.ds a problem with the partition or device information blocks it cannot fix, it asks for help. If you cannot figure it out e This requires a write pass for all blocks on the free list and a write cursor is displayed. If any bad blocks were found,+ tual address of UB is pushed followed by a zero). UB is word aligned. SAS S-2); otherwise, a run-time error occurs.  184 String Assign. (ETOS-1),(ETOS-2) is the source string pointer, and (ETOS-3),(ET - 35 - PERQ QCode Reference Manual 04 Feb 82 4.A.5 Record and Array IOS-4) is the destination string pointer. (ETOS) is the declared length of ndexing and Assignment MOVB UB 169 Move Words/Byte Counter. (ETOS) is a word pointer the destination. The length of the source and destination are compared, and ito a block of UB words, and (ETOS-1) is a word pointer to a similar block. The f the source string is longer than the destination, a run-time error occ block pointed to by (ETOS) is transferred to the block pointed to by (ETOS-1). MOVW 1urs. Otherwise all bytes of source containing valid information are transferred 70 Move Words/Word Counter. Same as MOVB except (ETOS-1) is the source pointer,  destination byte pointer to a similar block. Transfer the source block to the destinatio to the destination string. LDCH 25 Load Character. (ETOS),(ETOS-1) is a string n block. MVBW 168 Move Bytes/Word Counter. Same as MVBB  pointer. (ETOS) is checked to insure that it lies within the dynamic length of the  except (ETOS-1), (ETOS-2) is the source byte pointer, (ETOS-3), (ETOS-4) is the  string. If so, the character pointed to by (ETOS),(ETOS-1) is pushed; otherwise,  destination byte pointer, and (ETOS) is the number of bytes to transfer.  a run-time error occurs. STCH 28 Store Character. (ETOS) is a character and  - 34 - PERQ QCode Reference Manual  (ETOS-1),(ETOS-2) is a string pointer. (ETOS-1) is checked to insure that  04 Feb 82 4.A.4 Strings LSA UB, 19 Load String Address. UB is the length of it lies within the dynamic length of the string. If so, the character (ETO the string constant . A string pointer is pushed on EStack (the virS) is stored in the string, at the position pointed to by (ETOS-1),(ETO, lows you to specify a new stored length. This can be any value, but making it bigger than the number of blocks in the fil its use appears in the manual "How To Make a New System". The "PERQ Introductory User Manual" describes the bootine is not recommended. The default for the stored length is the number of blocks in the file. The Scavenger does not cg process. MakeBoot creates a boot file taking a stand alone run file (such as a system) and then associates this boot fileheck the lengths for directory files or files with their type field set to "SWAPFILE." Each file has a table which points to with a letter. The lower case letters are assigned to the hard disk and the upper case letters are assigned to the floppy each logical block of the file. This allows the file system to find a random logical block without searching down th disk. The default that is used when no keys are held down is lower case "a". Boot letters can be freed of the associatede chain from the file start. This table is called the "Random Index Table." Scavenger, as part of the directory building phas boot by deleting the system and/or interpreter boot files. Any program can be made to work "stand-alone" (so it can e, can rebuild the random indices for all files. There is a separate question for this with a default answer of "NO". Tbe booted) by initializing various modules as the System program does. It is generally not necessary or desirable to have phere is usually no reason to rebuild the indices unless Scavenger asks you to. Building the random indices for large filerograms other than the System be stand-alone. The run file name given to MakeBoot determines on which device and partitios takes a long time. If a bad file was created, Scavenger will ask for a name for the that file at the end of the diren the boot will be. MakeBoot takes the directory part of the file name and uses that to determine on which device actory building phase. If you allow Scavenger to enter and fix the indices for the bad file, you can then type and editnd partition to put the boot. Therefore, to make a boot somewhere, first copy the run file to that partition. After spec it as a normal file. In this way some useful - 9 - PERQ File System Utilities Manuifying the run file, Makeboot asks for the configuration file. This file tells MakeBoot which System modules are swappablal - Scavenger 04 Feb 82 information may be reclaimed. e. The format of the file is: Module-name swappability where swappability is "sw" for swappable, - 10 - PERQ File System Utilit "um" for unmovable (stronger than unswappable), or "us" or blank for unswappable. The default is unswappable so only tired. For each file, it checks the stored length with the actual number of blocks in the file. If they do not match, it alies Manual - MakeBoot 04 Feb 82 5. MakeBoot. The MakeBoot program creates new systems. An overview of,  Static Index and Load Word/Byte Index. Indexes the word pointer (ETOS) by UB words,  04 Feb 82 used for the array element size. IXA1..4 223-226 Index Array/Sho and pushes the word pointed to by the result on ESTACK. INDW W 172 Staticrt Array Size. Same as IXAB except array element sizes are fixed at 1-4. IXP UB 214 I Index and Load Word/Word Index. Same as INDB except a full word index is used. INCB UB 232ndex Packed Array. (ETOS) is an integer index, and (ETOS-1) is a word pointer the  Increment Field Pointer/Byte Index. The word pointer (ETOS) is indexed by UB words  base of the array. Bits 4-7 of UB contain the number of elements per word minus 1, and  and the resultant pointer is pushed on ESTACK. INCW W 233 Increm bits 0-3 contain the field width (in bits) minus 1. Compute and push a pacent Field Pointer/Word Index. Same as INCB except a full word index is used. Note: INCB and INCW arked field pointer. LDP 26 Load a Packed Field. Push the field e equivalent to add UB or W to (ETOS). IXAB UB 221 Index Array/Byte Array Size. (ETOS) is an  described by the packed field pointer (ETOS),(ETOS-1) on ESTACK. STP  integer index, (ETOS-1) is a word pointer to the base of the array, and UB is the size  27 Store into Packed Field. Store (ETOS) in the field described by the packed field  (in words) of an array element. A word pointer to the first word of the i pointer (ETOS-1),(ETOS-2). ROTSHI UB 20 Rotate/Shift. (ETOS-1) is the argument to  (ETOS-2) is the destination pointer, and (ETOS) is the number of words tondexed element is pushed on ESTACK. IXAW 222 Index Array/Word Array Size. Same as  be transferred. SIND0-7 173-180 Short Index and Load Word. SINDx indexes IXAB except (ETOS-1) is the integer index, (ETOS-2) is the word pointe the word pointer (ETOS) by x words, and pushes the word pointed to by the result on r to the base of the array, and (ETOS) is the size (in words) of an array el ESTACK. (Note: SIND0 is synonymous to LDIND). INDB UB 171 ement. (Gen1A) full word is - 36 - PERQ QCode Reference Manual - rs are defined for a device, there is only one set of boot microcode so this only needs to be written when putting theun file), in the root directory of the partition. It doesn't matter if the boot files are in a subdirectory in the partit first boot onto a device. The standard boot microcode files are "SysB" and "Vfy". There are two files associated with eachion; the run files mentioned above must be in the Root directory. The MakeBoot program will take a switch on the commandhe modules in your system that you want to be swappable or unmovable need to be listed. The default system config file (na boot letter. The system boot file is Pascal and the interpreter boot file is microcode. The system boot file is created med System.nn.Config) is: *SAT* UM *SIT* US *Cursor* UM by MakeBoot by reading the supplied run file. The standard microcode is usually used with all boot files. It is used by Ma *Screen* UM *Font* US *IO* UM System SW keBoot to create the interpreter boot file if you so specify. If you have already created a boot for the current letter and  Stream SW Writer SW IOErrMessages SW Loader SW you have not changed microcode, it is not necessary to make a new interpreter boot file, but it never hurts to do so. If yo Reader SW Perq_String SW Screen SW FileSystem SW u want to load the standard microcode and it is found by MakeBoot, type CR when it asks for an interpreter microcode file.  Code SW GetTimeStamp SW FileDefs SW Memory SW  Included in the system code is the default character set font. MakeBoot looks for the default font (currently, "Fix13.ks IO_Init SW - 11 - PERQ File System Utilities Manual - MakeBoot t") in all the search paths. If it is not found, you will have to supply a font file name. Note: For the Editor and 04 Feb 82 RunRead SW FileDir SW Scrounge SW Th certain other programs to work, the default font must be fixed width and thirteen bits high and nine bits wide. MakeBoot e system data segments that the hardware uses are required to be unmovable, the data used by software (*SIT* and *FONT*) are  puts the output boot files wherever you specify but it is important that the interpreter and system boot files be in the samrequired to be unswappable, and everything else that is not used by the swapping system itself can be swappable. The e partition. The device and partition in which the boot file is created will be the default path after the boot. Thisnext question MakeBoot asks is whether to write the boot microcode onto the device. No matter how many boot lette means that there must be at least a "Login.nn.run" and a "Shell.nn.run" (where "nn" is the version number of the system r-  0 then a right rotate occurs, and if UB is 1 then a shift occurs. The dir. ADI 72 Add Integers. Add (ETOS) and (ETOS-1). NGI 73 Negate Integer. Take the twos cection of the shift is determined from (ETOS); If (ETOS) >= 0 then a left omplement of (ETOS). SBI 74 Subtract Integers. Subtract (ETOS) from shift occurs; otherwise, a right shift. (ETOS) must be in the range from  (ETOS-1). MPI 75 Multiply Integers. Multiply (ETOS) and (ETOS--15 to +15. - 37 - PERQ QCode Reference Man1). This instruction may cause overflow if the result is larger than 16 ual 04 Feb 82 4.B Top of Stack Arithmetic and Comparisons 4.B.1 Logical LAND  bits. DVI 76 Divide Integers. Divide (ETOS-1) by (ETOS) and push quotient ( 30 Logical Add. AND (ETOS) into (ETOS-1). LOR 31 Logical Or. OR (ETOS) into (ETOS-1). LNOT as defined by Jensen and Wirth). MODI 77 Modulo Integers. Divide (ETOS-1) by (ETO 32 Logical Not. Take one's complement of (ETOS). EQUBOOL 33 BooleS) and push the remainder (as defined by Jensen and Wirth). CHK an =, NEQBOOL 34 <>, LEQBOOL 35 <=, LESBOOL 36  78 Check Against Subrange Bounds. Insure that (ETOS-1) <= (ETOS-2) <= (ETOS), leaving  <, GEQBOOL 37 >=, GTRBOOL 38 and > c (ETOS-2) on top of the stack. If conditions are not met a run-time error occurs. omparisons. Compare (ETOS-1) to (ETOS) and push true or false on ESTACK.  EQUI 39 Integer =, NEQI 40 <>, LEQI 41 <=,  - 38 - PERQ QCode Reference Manual  LESI 42 <, GEQI 43 >=, GTRI 44  04 Feb 82 4.B.2 Integer ABI 71 Absolute Value of Integer. Take ab and > comparisons. Compare (ETOS-1) to (ETOS) and push true or  be rotated or shifted, and (ETOS) is the distance to rotate or shift. If UB issolute value of (ETOS). Result is undefined if (ETOS) is initially -32768.  ____ ____ Note: It is very rare that the device and partition information blocks get broken, so Scavenger sh - iii - ould always be run first to see if the problem is actually elsewhere. FixPart first asks if you are sure you want to  PERQ Micro-Programmer's Guide Brianrun the program. Next, it asks for the device type. It then goes through and checks each partition for consistency with t Rosen John P. Strait This manual provides an introduction to the he other partitions and with the device information block. If a name is dubious it asks if it is valid or not. After all parPERQ micro- programmable CPU. Copyright (C) 1981, 1982 Three Rivers Computer Corporation titions are checked, the program gives a summary of the errors. If none were found, then it exits; otherwise, you  720 Gross Street Pittsburgh, PA 15224 (412) 621-6250 PERQ Micro-Programmer's Guide  line. If it is invoked with the /BUILD switch, all arguments are specified on the command line and the user is not  can specify new start and end addresses for the partition and fix the names. If the device information block is not wriasked any questions. The format for this switch is: MakeBoot []System./Build where is ateable, then you have to reformat the entire device and, unfortunately, lose all the data on it. If one of the partition in optional directory, is the system version number and is the character to boot from. Makeboot then usesnformation blocks is not writeable, then you may be able to save some information by using the partition program to join th the default answers for all questions. - 12 - PERQ File System Utilities Manual - Fie partition with the bad information block to the partition before and then scavenging. If it is the first partition, howevexPart 04 Feb 82 6. FixPart. FixPart is an experimental program for fixing the Device and r, your device will have to be reformatted. - ___ ___________ Partition information blocks. It is not recommended that customers try to 13 - Table of Contents 04 Feb 82 1 Preface: Notation Conventions  use it without assistance. Unlike the other programs described above, FixPart is only partially automatic and can cau 2 Introduction 3 Partitions and the Partition Program 6 The Scavenger Program 11 Makese a lot of damage. Unfortunately, it is currently the only way to fix bad partition and device information blocks. Boot 13 FixPart . S-2),(ETOS-3). 5 - Multiply (ETOS),(ETOS-1) and (ETOS-2),(ETOS-3). 6 - Divide (ETOS),(ETOS-1) by (ETOS pushed (a zero is pushed on ESTACK, the MSTACK is not altered). SRS 68 Bu-2),(ETOS-3). 7 - The real (ETOS),(ETOS-1) is rounded (as defined by Jensen and Wirth), truncaild SubRange Set. The integers (ETOS) and (ETOS-1) are checked as in SGS, the set  false on ESTACK. - 39 - PERQ QCode Reference Manual ted and converted to an integer, and pushed onto EStack. 8 - Take the absolute value of the real 04 Feb 82 4.B.3 Real Operations ROPS UB 250 Real Operations. Arithmetic operation (ETOS),(ETOS-1). 9 - = of two real values. (ETOS) = true or false. 10 - <> of two real values. s on floating point (32 bit) values. In general, (ETOS) is the low-order word 11 - <= of two real values. - 40 - PERQ QCode Reference Manual  and (ETOS-1) is the high-order word of the value. When two floating point v 04 Feb 82 12 - < of two real values. 13 - >= of two real values. alues are involved, (ETOS-2) is the low-order word of the second real and (ETO 14 - > of two real values. S-3) is the high-order word. All over/underflows cause a run-time error. Di - 41 - PERQ QCode Reference Manual 04 Feb 82 4.B.4 Sevision by zero (0) also causes a run-time error. UB determines the operatiots ADJ UB 185 Adjust Set. The set on the top of the MSTACK is forced to occupy n according to the following table: 0 - The real (ETOS),(ETOS-1) is truncated (as definUB words, either by expansion or compression, and its length word is popped fed by Jensen and Wirth), converted to an integer, and pushed onto EStack. 1 - The inrom ESTACK. SGS 66 Build Singleton Set. The integer (ETOS) is checked to insure tteger (ETOS) is converted to a floating-point number and pushed onto EStack. 2 - Add (ETOS),(ETOShat 0 <= (ETOS) <= 4,095, the set [(ETOS)] is pushed on MSTACK, and the siz-1) and (ETOS-2),(ETOS-3). 3 - Negate the real (ETOS),(ETOS-1). 4 - Subtract (ETOS),(ETOS-1) from (ETOe of the set is pushed on ESTACK. If (ETOS) is out of range, the null set is / s quickly as possible. The Reader's Comments card is distrib- uted with this document to request users' critical eort outputs, multiplexed with an 8- or 16-bit constant via the BMUX, form the B input to the ALU. The ALU outputs (R) avalu- ation to assist us in preparing future documentation. PERQ is a trademark of Three Rivers Computer Corre fed back to the XY registers as well as the memory data output and memory address registers. Memory data coming froporation. - ii - PERQ Micro-Programmem the memory is sent to the ALU via the AMUX. The IO bus (IOB) connects the CPU to IO devices. It consists of an 8-bit adr's Guide 08 Feb 82 ____________ __ ___ ________ Introduction to the Hardware dress (IOA) which is driven from a microword field and a 16-bit bidirectional data bus (IOD) which is read via AMUX and writte PERQ is implemented with a high-speed microprogrammed processor which has a 170 nanoseconds microcycle time. The microinstn from R. Opcodes and operands that are part of the instruction byte stream are buffered in a special 8 x 8 RAM (truction is 48 bits wide. Most of the data paths in the micro engine are 20 bits wide. The data coming in and out of thhe OP file). The OP file is loaded 16 bits at a time from the memory data inputs. The output of the OP file is 8 bits we processor (IO and Memory data for instance) are 16 bits wide. The extra 4 bits allow the microprogrammed processor to ide and can be read via AMUX or can be sent to the micro-addressing section for opcode dispatch. The read port of the OP fcalculate real addresses in a 1 megaword addressing space. The assumption is that virtual addresses are kept in a doubleword ile is addressed by the 3-bit BPC (Byte Program Counter). A shift matrix (SHIFT), which is part of the special hardwa 08 Feb 82 This document is not to be reproduced in any form or transmitted in whin memory but calculations on addresses can be single precision within the processor. The programmer of the virtual machiole or in part, without the prior written authorization of Three Rivers Computer Corporation. The information in tne never sees the 20 bit paths. The major data paths are diagrammed below: his document is subject to change without notice and should not be construed as a commitment by Three Rivers Co - 1 - PERQ Micro-Programmer's Guide mputer Corporation. The Company assumes no responsibility for any errors that may appear in this document.  08 Feb 82 The XY registers (256 registers x 20 bits) form a double ported file of general-purpose regis Three Rivers Computer Corporation will make every effort to keep customers apprised of all documentation changes aters. The X port outputs are multi- plexed with several other sources (the AMUX) to form the A input to the ALU. The Y p/ the length of the result on ESTACK. DIF 91 Set Difference. The difference of the  - 44 - PERQ QCode Reference Manual  two sets contained on the top of MSTACK, and sizes (ETOS) and (ETOS-1) 04 Feb 82 4.B.6 Byte Arrays EQUBYT UB 57 Byte Array =, NEQBYT UB 58  is pushed on MSTACK, and the length of the result on ESTACK. EQUPO <>, LEQBYT UB 59 <=, LESBYT UB 60 <, GEQBYT UB 6WR 63 Set =, NEQPOWR 64 <>, - 42 - PERQ Q1 >=, GTRBYT UB 62 and > compaCode Reference Manual 04 Feb 82 LEQPOWR 65 <= (subset of), GEQPrisons. <=, <, >=, and > are only emitted for packed arrays of characters.  [(ETOS-1)..(ETOS)] is pushed onto MSTACK, and the size of the set is pushed on ESTACK. OWR 67 and >= (superset of) comparisons of the two sets on t (The null set is pushed if (ETOS-1) > (ETOS) or either is out of range). INN op of ESTACK, with sizes (ETOS) and (ETOS-1).  88 Set Membership. See if integer (ETOS) is in set contained on the top of MSTACK, and - 43 - PERQ QCode Reference Manual  with length (ETOS-1), pushing TRUE or FALSE on ESTACK. UNI  04 Feb 82 4.B.5 Strings EQUSTR 51 String =, NEQSTR 52 <>, 89 Set Union. The union of the two sets contained on the top of MSTACK (with sizes  LEQSTR 53 <=, LESSTR 54 <, GEQSTR 55  (ETOS) and (ETOS-1)) is pushed on MSTACK, and the length of the result on ESTACK >=, GTRSTR 56 and > comparisons. The string poi. INT 90 Set Intersection. The intersection of the two sets contained on thented to by string pointer (ETOS-2),(ETOS-3) is lexicographically com top of MSTACK (with sizes (ETOS) and (ETOS-1)) is pushed on MSTACK, and pared to the string pointed to by string pointer (ETOS),(ETOS-1). 0  the Q-code interpreter to evaluate expressions. BPC and the microstate condition codes can be read as the Micro State Regis ALU 4 ALU function: 0 A 1 B 2 not A ter (USTATE) via AMUX. - 2 - PE 3 not B 4 A and B 5 A and not B 6 A and B RQ Micro-Programmer's Guide 08 Feb 82 _____ ___________ ______ Micro Instruction For 7 A or B 10 A or not B 11 A nor B 12 A xomat 8 8 3 1 1 1 4 2 4 8 4 4 +-------+-------+---+-+-+-+-----+--+----+-------+----+----+ |r B 13 A xnor B 14 A + B 15 A + B + OldCarry  X | Y | A |B|W|H| ALU | F| SF | Z |CND | JMP| +-------+-------+---+-+-+-+-----+--+----+-------+----+----+ _____ 16 A - B 17 A - B - OldCarry - 3 - PERQ Micro-Programmer's _____ ___ Field Width Use X 8 Address for X port of XY. Also address used to write X Guide 08 Feb 82 F 2 Function: Controls usage of SF and Z fields. Y. Y 8 Address for Y port of XY. Also low 8 bits of constant. A 3 AMUX Select: _ __ ___ _ ___ F SF use Z use 0 Special Func. Consta 0 SHIFT 1 NextOp 2 IOD 3 MDI Memnt/Short Jump 1 Memory Control Short Jump 2 Special Func. Shift Control ory Data Inputs, AMUX[19..16] := 0 AMUX[15..00] := MD[15..00]  3 Long Jump Long Jump SF 4 Special Function: Upper 4 bits of address for  4 MDX Memory Data Input extended AMUX[19..16] := MD[03..00] AM long jump and memory control functions (see F). When used as Special Function: 0 LoUX[15..00] := 0 5 USTATE 6 XY (RAM) 7 ESTK B 1 ng Constant 1 ShiftOnR 2 StackReset 3 TOS := (R) (Top Of Ere provided for the RasterOp operator, can be accessed by loading an item to be shifted via the R bus, and reading the shi BMUX select: 0 = XY[Y], 1 = Constant. W 1 Write: XY[X] := R if W = 1. H 1 Hold: If set, do nfted result on AMUX. A 16-level push down stack (ESTK) is written from R and read on AMUX. The stack is used by ot allow IO devices to access memory. Also used with JMP field to modify address inputs. 0 he array. If UB equals 0, then (ETOS) is the size of the array. long values. 12 - < of two long values. 13 - >= of two long values. 14 - > of two long val - 46 - PERQ QCode Reference Manual ues. - 47 - PERQ QCode Reference Manual 04 04 Feb 82 4.B.8 Long Operations LOPS UB 252 Long Operations. Arithmetic  Feb 82 4.C Jumps JMPB B 204 Unconditional Jump/Byte Offset. B is added to toperations on long (32 bit) values. In general, (ETOS) is the low-order wohe IPC. Negative values of B cause backward jumps. JMPW W 205 Unconditional Jump/Wrd and (ETOS-1) is the high-order word of the value. When two long valuesord Offset. W is added to the IPC. Negative values of W cause backward are involved, (ETOS-2) is the low-order word of the second long and  jumps. JFB B 206 False Jump/Byte Offset. Jump (as in JMPB) if (ETOS) is false.  (ETOS-3) is the high-order word. UB determines the operation according to the JFW W 207 False Jump/Word Offset. Jump (as in JMPW) if (ETOS) is false. JTB B  following table: 0 - Converts the long value (ETOS), (ETOS-1) to a single word 208 True Jump/Byte Offset. Jump (as in JMPB) if (ETOS) is true. JTW W 209 Tr The argument, UB, if non-zero, is the size of the array. If UB is equal to 0, then . The high- order word must be 0 or all 1's, as it is truncated. If not, a runtime error is  (ETOS) is the size of the array.  generated. 1 - Converts a single word (ETOS) into a long value. 2 - Adds two long values.  - 45 - PERQ QCode Reference Manual 04 Feb 82 4.B.7 Array 3 - Negates long value. 4 - Subtracts two long values. 5 - Multiplies two long values.  and Record Comparisons EQUWORD UB 69 Word or multiword structure = NEQWORD UB 70  6 - Divides two long values. 7 - Mods two long values. 8 - Absolute value of a long value.  and <> comparisons. The argument, UB, if non-zero, is the size of t 9 - = of two long values. (ETOS) = true or false. 10 - <> of two long values. 11 - <= of two 1  - 4 - PERQ Micro-Programmer's Guide 08 Feb 82 JMP 4 Jump Control: See AMD 2or/Dispatch H = 0 NIA:=Vector NIA:=CIA+1 +STK) 4 Push (ESTK) 5 Pop (ESTK) 6 CntlRasterOp := (Z) 910 documentation for further details. CIA = Current Instruction Address.  7 SrcRasterOp := (R) 10 DstRasterOp := (R) 11 WidthRasterOp := (R) NIA = Next Instruction Address. Addr = SF,,Z (Long) or CIA,,Z (Short).  12 LoadOp (OP := MDI) 13 BPC := (R) 14 WCS[15..00] := (R)  ZAddr = Z(UpperBits),,0,,Z(LowerBits). S = internal address register. 15 WCS[31..16] := (R) 16 WCS[47..32] := (R) 17 IOB Function  CSTK = top of five level call stack. Push = push CIA+1 onto call stacZ 8 Low 8 bits of Jump Address, high 8 bits of Constant, Shift Control (see F), or IOB address. k. Pop = pop call stack. ____ ____ ____ ____  CND 4 Condition (what to test during conditional jump): 0 True - always jump  Code Name Pass Fail 0 JumpZero NIA:=0 NIA:=0  1 False - never jump 2 IntrPend - interrupts pending 3 unused  1 Call NIA:=Addr NIA:=CIA+1 Push 2 4 BPC[3] - OP file is empty 5 C19 - no carry out of bit 19 of the ALU 6  NextInst/ReviveVictim H = 0 NIA:=OP NIA:=OP Odd - ALU bit 0 7 ByteSign - ALU bit 7 10 Neq - not equal to 11  +ZAddr +ZAddr H = 1 NIA:=Victim NIA:=Victim 3  Leq - less than or equal to 12 Lss - less than 13 OverFlow - 16 bit overflow in t GoTo NIA:=Addr NIA:=CIA+1 4 PushLoad NIA:=CIA+1 NIA:=CIA+1 he ALU 14 Carry - carry out of bit 15 of the ALU 15 Eql - equal to  Push Push S:=Addr 5 Call 16 Gtr - greater than 17 Geq - greater than or equal to S NIA:=Addr NIA:=S Push Push 6 Vect1 ord Offset. Jump (as in JMPW) if integer (ETOS) equals (ETOS-1). JNEB B 212 Not Equal and Returns Note: There can be at most 256 routines in a segment. CALL  Jump/Byte Offset. Jump (as in JMPB) if integer (ETOS) is not equal to UB 186 Call Routine. Call routine UB, which is in the current segment. CALLXB UB1,UB2 23 (ETOS-1). JNEW W 213 Not Equal Jump/Word Offset. Jump (as in JMPW) if integer4 Call External Routine/Byte Segment. UB1 is the internal segment number (ISN) which  (ETOS) is not equal to (ETOS-1). XJP W1,W2,W3, 100 C contains the routine numbered UB2 to be called. First the ISN is translated to ase Jump. W1 is word-aligned, and is the minimum index of the table. W2 is the  the correct SSN, and residency of that segment is checked. If the segment  maximum index. W3 is the offset to the code to be executed if the case specified has no is resident, the call proceeds; if not, the PC is backed up so that the call entry in the case table. The case table is W2 - W1 + 1 words long and contain will be re-executed, and a segment fault occurs. The second attempt is guars offsets to the code to be executed for each case. If (ETOS), the actual inanteed to succeed, since the process is unable to resume execution until the segment dex, is not in the range W1..W2 then W3 is added to PC. Otherwise, ( SSN is resident. CALLXW W,UB 235 Call External Routine/Word Segment. Same as CALLXBETOS) - W1 is used as an index into the case table and the index entry is  except the internal segment number (ISN) is given in a full word. LVRD W,UB1,UB2 98 Load  - 48 - PERQ QCode Reference Manual 04 Feb 82 aVariable Routine Descriptor. This Q-Code pushes a Variable Routine Descriptor ue Jump/Word Offset. Jump (as in JMPW) if (ETOS) is true. JEQB B 210 Equal Jump/Byte Odded to PC. ffset. Jump (as in JMPB) if integer (ETOS) equals (ETOS-1). JEQW W 211 Equal Jump/W - 49 - PERQ QCode Reference Manual 04 Feb 82 4.D Routine Calls2  S:=Addr S:=Addr 15 Loop NIA:=CSTK NIA:=CIion field. _________ Constants Constants can be 8 or 16 bits wide. If B = 1, the B input to the AA+1 Pop 16 Next NIA:=CIA+1 NIA:=CIA+1 LU is a constant. If F = 0 or 3 and SF = 0, the Y and Z fields form a 16 bit constant. If SF <> 0 and F <> 0 or 3 then Y is 17 ThreeWayBranch if S <> 0 NIA:=CIA+1 NIA:=CSTK  an 8 bit constant. - 6 - PERQ Micro-Programmer's Guide  Pop S:=S-1 S:=S-1 if S = 0 NIA:=C 08 Feb 82 ________ OldCarry OldCarry (in ALU functions 15 and 17) is the carryZAddr H = 1 NIA:=Dispatch NIA:=CIA+1 +ZAddr IA+1 NIA:=Addr Pop Pop The Z field is used for many things: as 7 GotoS NIA:=Addr NIA:=S 10 RepeatLoop  part of a jump address, the upper 8 bits of a constant, Shift Control, and as an IOB address. The F field decodes do if S <> 0 NIA:=CSTK NIA:=CSTK S:=S-1 S:=S-1  not necessarily enforce restric- tions on the use of the Z field, they merely enable some of them. In particular, B = 1 if S = 0 NIA:=CIA+1 NIA:=CIA+1 Pop Pop , SF = 0, and F = 0 or 3 selects a long constant using the Z field. When F <> 2, the Z field is used for a jump address.11 Repeat if S <> 0 NIA:=Addr NIA:=Addr S:=S-1 When SF = 17 and F = 0 or 3, the Z field is used for an IOB address. When F = 2, the Z field is loaded into the Shi S:=S-1 if S = 0 NIA:=CIA+1 NIA:=CIA+1 12 Return ft Control register. These are the only specific actions taken by the hardware that affect the usage of the Z field. TheNIA:=CSTK NIA:=CIA+1 Pop - 5 - PER hardware does nothing to prevent the Z field from being used for several things at once. For example, it could be used for Q Micro-Programmer's Guide 08 Feb 82 13 JumpPop NIA:=Addr Na long constant and a jump address at the same time, or it could be used as an IO address and a jump address at the same time.IA:=CIA+1 Pop 14 LoadS NIA:=CIA+1 NIA:=CIA+1  The assembler, however, will flag an error if the programmer tries to load two different values into the same microinstruct2  - 50 - PERQ QCode Reference Manual 04 Feb 82  enabled. UB2 is the routine number of the handler. A new exception enable record is  on the EStack for the routine UB1 in segment ISN W, at lexical level UB2. The following  the routine dictionary, if the RA which is being returned to is 0, the return is  values (which comprise a variable routine descriptor) are pushed: (ETOS) = Sy performed to the exit code of that routine. (This proves useful for the EXIT andstem Segment Number (SSN); (ETOS-1) = Global Pointer, represented as an EXGO Q-Codes described below). EXIT W,UB 92 Exit from Routine. Exit from all routines offset from SB; (ETOS-2) = Routine Number; and (ETOS-3) = Static Link (d up to and including the most recent invocation of the routine UB in etermined as if a call were actually performed to the routine here). CALLV 187 Call VISN W. This is accomplished by setting the RAs in all the ACBs to 0, from ariable Routine. The ESTACK elements (ETOS) --- (ETOS-3) are a variable routine the most recent through and including the first ACB which was created  descriptor (as described above in LVRD). Residency of the segment are checked. If from an invocation the routine to be exited, and jumping to the exit code of the  the segment is resident, the call is made as will CALL, except the GP and SL are t current routine. EXGO W1,UB,W2 29 Exit and Goto. Exit from all routines up to, but noaken from the variable routine descriptor; if not, a segment fault occurs t including, routine UB in ISN W1, and then jump to the instruction with offset as with CALLX. RETURN 200 Return from Routine. Return from the current routine W2 from CB. The implementation is similar to EXIT, except the last RA modified is . If the routine was a function, the function value is left on the top  loaded with W2. ENABLE W,UB1,UB2 242 Enable Exception Handler. W and UB1 are the iof the MStack. Since the first word of a code segment is not code, but an offset to nternal segment and routine numbers, respectively, of the exception being 3 dition codes compare the 16-bit ALU result against zero. C19 is designed for unsigned address comparisons. Assu 4 address) 10 Fetch4R Fetch 4 words, transport in reverse order 11 Store4R Store 4 words, transportming that A and B are registers containing 20-bit addresses and T is a temporary register, the following code fragments sho in reverse order 14 Fetch2 Fetch 2 words (0 mod 2 address) 15 Store2 Store 2 words (0 mod 2 addrew how to compare A and B. A - 1; if C19 Goto(Label); ! Jumps if A = 0, doesn't jump if A <> 0 T := A; ss) In the following discussion of the memory controller, the terms "Fetch" and "Store" are used for the memory functio T := T - B; T - 1; if C19 Goto(Label); ! Jumps if A = B, doesn't jump if A <> B A - B; if C19 Gns which fetch or store exactly one word. The generic terms "fetch type" and "store type" are used for any type of fetchingoto(Label); ! Jumps if A < B, doesn't jump if A >= B B - A; if C19 Goto(Label); ! Jumps if A > B, doesn't jump or storing memory reference. The address for all memory references comes from R. For all fetch type references,  if A <= B - 7 - PERQ Micro-Programmer's Guide  the address (and the request itself) are latched at t3 and data is available from MDI or MDX (A = 3 or 4) at t2. If MDI  08 Feb 82 ______ _______ Memory Control The memory system cycles in 680 ns (exactly 4 mior MDX is used during a t0 or t1 following a fetch type memory reference, the processor is suspended until t2. Any addr from the immediately preceeding microinstruction, it is used for multiple precision arithmetic. _________crocycles). Microcycles are numbered starting at 0 (t0, t1, t2 and t3). Requests must be made in a particular cycle  _____ Condition Codes All ALU related condition codes test the result of the ALU operation from the previo(which cycle depends on the type of request). If a memory request is made in the wrong cycle, the processor will be susus micro cycle. Thus the normal sequence is to perform an ALU operation and test its result in the next microinstructiopended until the correct cycle. In some contexts, however, a request made in an improper cycle will be ignored--these conten. For example, comparison of two registers A and B could be done this way: A - B; if Gtr Goto(Label); ! Jumpxts are explained below. There are 8 types of memory references, coded into the SF field when F = 1. __ ____ s if A > B All ALU tests with the exception of C19 test the lower 16 bits of the ALU. These are intended for  ___________ SF Type Description 16 Fetch Fetch 1 word from Memory. 17 Store data comparisons. After a subtraction, these condition codes compare the two operands. After other operations, these con Store 1 word into Memory 12 Fetch4 Fetch 4 words (0 mod 4 address) 13 Store4 Store 4 words (0 mod3 (ETOS-1), then push original (ETOS)). MMS 96 Move to Memory Stack. Push (ETOS) ont functions performed to combine the two pictures are described below. o MTOS (16-bit transfer). MES 97 Move to Expression Stack. Push (MTOS) onto  RasterOp can be used on memory other than that used for the screen bitm ETOS (16-bit transfer - top 4 bits are zeroed). MMS2 201 Moap. There are two parameters that specify the areas of memory to be used ve Double to Memory Stack. Transfer the top two words from the EStack to the MStack.  for the source and destination: a pointer to the start of the memory bl pushed (quad word aligned) onto the MStack and linked into the routine's The order is reversed; old (ETOS) is (MTOS-1), (ETOS-1) is (MTOS). MES2  current exception list. RAISE W1,UB,W2 243 Raise Exception. W1 and UB1 are the  202 Move Double to Expression Stack. Transfer the top two words from the MStack to the  internal segment and routine numbers, respectively, of the exception to be r EStack. THe order is reversed; old (MTOS) is (ETOS-1), (MTOS-1) is (ETOS). Raised. W2 is the number of words of parameters that have already been pushed ASTER-OP 102 RasterOp. RasterOp is a special QCode which is used to manipulate blocks of  onto the memory stack. The exception is raised. memory of arbitrary sizes. It is especially useful for creating and modi - 51 - PERQ QCode Reference Manual 04 Feb 82 4.E Systems Programs Suppofying displays on the screen. RasterOp modifies a rectangular area (callert Procedures BREAK 254 Breakpoint QCode. Causes a Qcode level breakpoint to thed the "destination") of arbitrary size (to the bit). The picture drawn into  microcode kernel (KRNL). NOOP 93 No-Operation. REPL 94 Replicate. Replicate (ETOS). R this rectangle is computed as a function of the previous contents of the destination and EPL2 95 Replicate Two. Replicate two top-of-estack words (i.e., first push original  the contents of another rectangle of the same size called the "source". The 4 uad-word aligned. If it is not quad-word aligned, the two low-order bits are ignored. After the Fetch4, the first word  ... (t0) ... (t1) must be read at t2, and the succeeding words must be read at t3, t0, and t1. Any address may be used with a Store Data0 := MDI; (t2) Data1 := MDI; (t3) Fetch4: MA := Addr, F. The address and Store command are given in a t2 cycle and the data to be written is supplied on R in the following tetch4; (t3) ... (t0) ... (t1) 3. The address for a Store2 must be even (double-word aligned). If it is odd, the low-order bit of the address is Data0 := MDI; (t2) Data1 := MDI; (t3)  ignored. The address and Store2 are given in a t3 cycle, and the data is supplied on R in the following t0 and t1.  Data2 := MDI; (t0) Data3 := MDI; (t1) Fetch4R: MA := Addr, Fetch - 8 - PERQ Micro-Programmer's Guide 08 Feb 82 The4R; (t3) ... (t0) ... (t1)  address for a Store4 must be quad-word aligned. If it is not quad-word aligned, the two low-order bits are ignored. T Data3 := MDI; (t2) Data2 := MDI; (t3) Dathe address and Store4 are given in a t3 cycle, and the data is supplied in the next four cycles (t0, t1, t2 and t3). Ta1 := MDI; (t0) Data0 := MDI; (t1) Store: MA := Addr, Store; he Fetch4R and Store4R types are identical to the Fetch4 and Store4 references except that word 3 of the quad word is receive (t2) MDO := Data; (t3) Store2: MA := Addr, Store2; (t3) d or sent first and word 0 last. (This is generally only useful for RasterOp so that it can do left to right as well as  MDO := Data0; (t0) MDO := Data1; (t1) Store4: MA ess may be used with a Fetch, and the memory word may be read during any cycle from t2 until the following t1. The a right to left transfers.) Here are examples of each type of reference and how they are coded: Fetch: ddress for a Fetch2 must be even (double-word aligned). If it is odd, the low-order bit of the address is ignored. After a  MA := Addr, Fetch; (t3) ... (t0) ...  Fetch2, the first word must be read at t2, and the second word must be read at t3. The address for a Fetch4 must be q (t1) Data := MDI; (t2) Fetch2: MA := Addr, Fetch2; (t3) 4  and, for the screen, (767, 1023) would be the lower right. The EStaAndNot Dst gets Dst AND NOT Src 4 ROr Dst gets Dst OR Src 5 ck must be arranged in the following order for RASTER-OP: (ETOS-10) F ROrNot Dst gets Dst OR NOT Src 6 RXor Dst gets Dst XOR Src unction (ETOS-9) Width (ETOS-8) Height (ET 7 RXNor Dst gets Dst XNOR Src - 53 - PERQ QCode Reference Manual OS-7) Destination-X-Position (ETOS-6) Destination-Y-Position (ETOS-5)  04 Feb 82 "Width" specifies the size in the  Destination-Area-Line-Length (ETOS-4) Destination-Memory-Pointer (ETOS horizontal ("x") direction of the source and destination rectangles (given in bits). -3) Source-X-Position (ETOS-2) Source-Y-Position (ETOS-1) Source-Area "Height" specifies the size in the vertical ("y") direction of the source -Line-Length (ETOS) Source-Memory-Pointer The values on the  and destination rectangles (given in scan lines). ock and the length (in words) of - 52 - PERQ QCode Reference Manual  stack are defined below: "Function" defines how the source and  04 Feb 82 scanlines in the block. A scanline is one  the destination are to be combined to create the final picture stored at the destin of the elements that cross the block. On the screen, for example, a scanline is one ation. The RasterOp functions are as follows (Src represents the source  of the horizontal lines with a length of 48 words. Within these regions, the positions  and Dst the destination): Function Name Action  of the source and destination rectangles are given as offsets from the poin -------- ---- ------ 0 RRpl Dst gets Src 1 ter. Thus position (0,0) would be at the upper left corner of the region, RNot Dst gets NOT Src 2 RAnd Dst gets Dst AND Src 3 R5 := Addr, Store4; (t3) MDO := Data0; (t0) MDO := Data1; to consider them. The following rules define the way the memory controller treats memory requests. 1) After a Fetch or (t1) MDO := Data2; (t2) MDO := Data3; (t3)  Fetch2 (in t3), any memory reference in t0 or t1 is ignored. A Store specified in the t3 will start immed - 9 - PERQ Micro-Programmer's Guide 08 Feb 82 Storeiately, but all others will abort until the correct time. 2) Fetch4 and Fetch4R follow the rules for Fetch and Fetch2 wit4R: MA := Addr, Store4R; (t3) MDO := Data3; (t0) MDO := Dah the exception that a Store4 (in the same direction--forward or reverse) can be specified in t1, but this is ta2; (t1) MDO := Data1; (t2) MDO := Data0; (t3) only used for RasterOp. 3) After a Store (in t2), any memory reference in t3 or t0 is ignored. Reference The IO system can request memory cycles at any time. The memory system gives priority to the IO system sos started in t1 are aborted until the correct cycle. 4) After a Store2, Store4 or Store4R (in t3), any memory r that if both the processor and the IO system make memory requests, the IO is served first while the processor is delayed.eference in t0 through t3 is ignored. Memory references started in t0 are aborted until the correct cycle. 5 The Hold bit, if set, locks out IO requests while it is set. To be effective, Hold must be asserted in a t2. This) To be effective, Hold must be asserted in a t2. You must be careful about aborts caused by using MDI in the wrong  is necessary only when doing overlapped memory references. See the high performance rules below. Combinations of memcycle-- you may be aborted past the t2, causing the Hold to be ignored. You may not specify Hold too often--yoory references are tricky. There are a few rules which, if followed, will never let you go wrong, but they may preclude somu must allow an IO reference at least once in every 3 memory cycles. - 10 - e clever twist of microcoding to save some cycles. The simple rules are: 1) Never start a memory reference after a f PERQ Micro-Programmer's Guide 08 Feb 82 6) After a Fetch, MDI is valid from t2 through etch type reference until you have taken all the data. 2) Never start a memory reference during the four instructthe following t1 (four full cycles). For Fetch2, Fetch4, and Fetch4R, each MDI is valid for a single microcycle.ions which follow a store type request. The full rules are complicated, but to achieve high-performance you need  Following these rules, we can construct many interesting overlapped memory requests. Note that in the follo5 e destination rectangle. The value is offset from Destination-Memoryropriate value to use when operating on the screen is 48. The specified value -Pointer (see below). "Destination-Area-Line-Length" is the number of must be a multiple of four (4) and within the range 4 through 48.  words which comprise a line in the destination region (hence defining the  - 54 - PERQ QCode Reference Manual 04 Feb 82  region's width). The appropriate value to use when operating on the screen is 48. The  "Source-Memory-Pointer" is the virtual address of the top left corner of the source  specified value must be a multiple of four (4) and within the range 4 through 48.  region. This pointer MUST be quad-word aligned, however. LINE 241 Li "Destination-Memory-Pointer" is the virtual address of the top left ne Drawing. (ETOS) is a pointer to the origin (relative 0,0) of the area on which corner of the destination region. This pointer MUST be quad-word aligned, h the line is drawn. (ETOS-4) and (ETOS-3) are the x and y coordinates (respectively) owever. "Source-X-Position" is the bit offset of the left side of th of the first endpoint of the line. (ETOS-2) and (ETOS-1) are the x and y cooe source rectangle. The value is offset from Source-Memory- Pointer (serdinates (respectively) of the second endpoints on the line. (ETOS-5) is te below). "Source-Y-Position" is the scan-line offset of the top ohe style of the line where a value of 1 means erase the line, 2 means to x "Destination-X-Position" is the bit offset of the left side of the destination f the source rectangle. The value is offset from Source-Memory- Pointer ( rectangle. The value is offset from Destination-Memory-Pointer (see below).see below). "Source-Area-Line-Length" is the number of words which comp "Destination-Y-Position" is the scan- line offset of the top of thrise a line in the source region (hence defining the region's width). The app6  Again, Hold is asserted in t2. Note that this differs from the previous example in that the Hold and Fetch, Hold;" first tries to execute in t2, but is aborted until t3 because it contains a store. > are not done in the same instruction. These two examples show that for indirect fetches, the two fet The MDI is still valid because MDI is valid from t2 to the following t1 after a Fetch. MAches may be separated by two or three other instructions. Indirect stores: MA := Addr, Fetch;  := Addr, Fetch; (t3) instruction or Nop; (t0) must be explicit instruction or Nop; wing examples, Hold is always asserted in a t2. A Fetch ... Store sequence is an exception--you need not use Hold, but it (t3) instruction or Nop; (t0) must be explicit instruction or Nop; (t1) must b doesn't hurt performance, so we assert it for consistency. Indirect fetches: MA := Addr, Fetch; (t3e explicit MA := MDI, Store, Hold; (t2) MDO := Data; (t3) In this case) instruction or Nop; (t0) must be explicit instruction or Nop; (t1) must be explici, the MDI, the Store, and the Hold all execute in t2. - 11 - PERQ t MA := MDI, Fetch, Hold; (t2, t3) any type of fetch ... Data := MDI; Micro-Programmer's Guide 08 Feb 82 MA := Addr, Fetch2; (t3) instr(t2) ... Hold is asserted in t2 so that IO requests do not pre-empt the processor. The iuction or Nop; (t0) must be explicit instruction or Nop; (t1) must be explicit MA :=nstruction "MA := MDI, Fetch, Hold;" first tries to execute in t2, but is aborted until t3 because  MDI, Store, Hold; (t2) MDO := MDI; (t3) In this case, the first fetched word is  it contains a fetch. The MDI is still valid because MDI is valid from t2 to the following t1 after a  used as an address, and the second is used as data to be stored. MA := Addr, Fetch; (t3) Fetch. MA := Addr, Fetch; (t3) instruction or Nop; (t0) must be explicit  instruction or Nop; (t0) must be explicit instruction or Nop; (t1) must be explicit instruction or Nop; (t1) must be explicit instruction, Hold; (t2) MA := MDI, Fetch, Hold; (t2, t3) any except Store MDO := Data; (t0) ...>; (t3) any type of fetch ... Data := MDI; (t2) ...  Hold is asserted in t2 so that IO requests do not pre-empt the processor. The instruction "MA := M6 or the line and anything else means to draw the line. STARTIO 103 (ETOS) is the chann 04 Feb 82 STLATE UB 240 Special Translate. This translate is similar to theel on which to start IO. INTOFF 105 Disable interrupts. INTON 106 Enable interrupts. EXCH  previous translate Q-Codes, except that it can specify a greater depth th 230 Exchange. (ETOS) and (ETOS-1) are swapped. EXCH2 231 Exchange Double. The pair (ETOS) an TLATE3, and that it may specify the translation of 2 virtual addresses. Each  and (ETOS-1) are swapped with the pair (ETOS-2) and (ETOS-3). TLATE1  half of UB is interpretted as the depth of the System Segment Number word of the  227 Translate Top of Stack. (ETOS),(ETOS-1) is a virtual address. If the segment SSN  virtual address to be translated (prior to any stack alteration). A dept (ETOS-1) is resident, convert the virtual address to an offset from stach of 0 indicates no translation. All segments specified in the STLAk base (SB) and execute the next Q-Code (what ever it may be), with out inTE must be resident before any translations occur; otherwise a segment faulterrupts, to competion. If the segment SSN (ETOS-1) is non-resident, restore t occurs. Note, if both nibbles of UB are non-zero then the low-order nibble the EStack to its previous state, backup the PC to re-execute the TLATE1 and (bits 0-3) must be less than the high-order nibble (bits 4-7). LSSN 99 Load Stack  perform a segment fault. TLATE2 228 Translate Top of Stack - 1. Same as TLATE1 exc Segment Number. Pushes the system segment number of the MStack onto ept the virtual address is at (ETOS-1),(ETOS-2). TLATE3 229 Translate Top EStack. LDTP 203 Load Top Pointer (plus 1). Pushes the value of Top Pointer (TP) pluof Stack - 2. Same as TLATE1 except the virtual address is at (ETs 1 onto EStack. LDAP 244 Load Activation Pointer. The current activation poiOS-2),(ETOS-3). - 55 - PERQ QCode Reference Manual nter (as an offset from the base of the stack) is pushed onto the ES7 ocation to another. Unfortunately, two or four word copies are not possible because the times when daThe instruction which executes NextOp must be capable of being executed twice (once when BPC overflowed and again whta must be read and written are different for the fetches and stores. en it is re-executed after Refill). This precludes instructions such as "R := NextOp + R". In order for Refill to - 12 - PERQ Micro-Programmer's Guide 08 Feb 82 _______ ___ ________ Opco get back to the instruction which needs to be re-executed, the address of the failed NextOp is saved in a hardware registedes and operands The OP file contains a 4-word sequence of instruction bytes. A quad-word address is contained in a XYr (Victim) if NextOp is executed when BCP[3] is set. The last instruction in Refill is coded with ReviveVictim (JMP=2, H=1) register (UPC), and the 8 bytes pointed to by UPC are loaded into the OP file. The lower 3 bits of the byte address (, which sends control back to the "failed" NextOp. BPC can be set without re-loading the OP file, and so the currbyte within the quad word) are kept in BPC, a hardware register. BPC addresses the OP file to choose a byte. BPC is ent quad word can be re-read without fetching it from memory a second time. The NextInst jump enables a byte of (t1) must be explicit instruction, Hold; (t2) MA := MDI, Store; (t3) actually a 4-bit counter. It is incremented after each a byte is taken out of the OP file by NextInst (JMP=6, H=0) or Neany type except Store MDO := Data; (t0) ... Again, Hold is asserted in t2. xtOp (A=1). The 4th bit of BPC (BPC[3]), which is the "overflow" of the counter, is testable via a jump condition and indica Note that this differs from the previous example in that the Hold and Store are not done in thetes that all bytes in OP have been used. The NextOp function (A=1) gets the next byte out of the instruction  same instruction. These two examples show that for indirect stores, the Fetch and the Store may be byte stream for use as an operand. The assembler automatically adds an "If BPC[3] GoTo(Refill)" jump clause. If BPC oseparated by two or three other instructions. Copy operations: MA := Addr1, Fetch; (t3) instrverflows, then control will go to Refill which increments UPC by 4, set BPC to 0, and starts a Fetch4 to the OP file. Theuction or Nop; (t0) must be explicit instruction or Nop; (t1) must be explicit MA := special function LoadOp must be executed in the t1 after the Fetch4 to cause the Op file to be loaded with the data coming o Addr2, Store, Hold; (t2) MDO := MDI; (t3) A word is copied from one memory ln MDI. Refill must then jump back to the instruction which needed the byte so that instruction may be re-executed. 7 REFILLOP 255 Refill the OpFile. This instruction causes execution to proceed from the be 2 DVI 39 EEB 3ginning of the next quad-word. INCDDS 251 Increment Diagnostic Display. The value of  ENABLE 51 Enabling an Exception 3 EP  the diagnostic display is incremented and the contents of the EStack is ch 3 EQUBOOL 38 EQUBYT tack. ATPB SB 188 Add to Top Pointer/Byte Value. Adds SB to TP. ATPW 18ecked. If the EStack is not empty, a runtime error is generated. 9 Add to Top Pointer/Word Value. Adds (ETOS) to TP. WCS 190 Write Control Stor - 57 - PERQe. A control store word is written from information on the EStack. (ETOS) QCode Reference Manual 04 Feb 82 INDEX  is the address (with bytes exchanged) in the control store to which the word will  ABI 39 ACB 3 Activation Record  be written. (ETOS-1) is the value to be written into the high-order third, (ETOS-2)  1 ADI 39 ADJ 42  is the value to be written into the middle third and (ETOS-3) is to be written into AP 2 ATPB 56 ATPW  the low-order third. JCS 191 Jump to a Location in the Control Store.  56 BREAK 52 CALL 50  Control is transferred to the control store address (with bytes exchanged) given  CALLV 50 CALLX 50 CALLX in (ETOS). A routine called with JCS should exit with a NextInst(0) jump.  50 CB 1 CHK 39  - 56 - PERQ QCode Reference Manual 04 Feb 82  CS 2 DIF 42 DL 8  ReviveVictim. To speed up the execution of Refill, the LoadOp Special Function loads all 4 words via hardwarehift 0-15 The item to be shifted is placed on R, and the shifted and masked result can be read via SHIFT (A = 0) on the n. The LoadOp should be given in the tl following the Fetch4. The instruction which follows the LoadOp can go back to the Next instruction. The shift control logic keeps the last value loaded so that the shifter can shift a succession of wordsextInst/NextOp since the first byte is quaranteed to be in. The three remaining words arrive and are placed in OP by without respecifying the shift control function. The shift outputs always have the shifted value of what was last on R hardware without further microcode assistance. If BPC is set to a non-zero value (to start reading in the middle of the. ________ ShiftOnR The ShiftOnR special function allows a shift function to be a variable. The s quad word), the Refill code must wait until the correct byte is in the OP file. - 13 -hift control is obtained from the R bus and thus can be a data item. The usage sequence is: 1) Put the shift control (uni PERQ Micro-Programmer's Guide 08 Feb 82 _____ _______ Shift Control Tverted) on R and execute ShiftOnR, 2) Put the item to be shifted on R, and 3) Read the shifted result on SHIFT. he PERQ shifter can rotate a 16 bit item 0 to 15 places and apply a mask to the shifter outputs. To use the shift hardware, __________ _____ Expression Stack The expression stack is used to evaluate expressions. Items are pushed o the Z field of the instruction can be coded with the type of shift to be done with the F field set to F = 2. Coding of then the stack by placing them on R and using the Push special function: "TOS := Data, Push". Items can be popped off the st shift control uses two 4 bit nibbles (shift control is inverted in the Z field): _____ _______ _____ ack with the Pop special function. The top of the stack can be written without pushing or popping with the "TOS := Data"  the OP file (which is inverted for NextInst) into the Addr input of the micro-sequencer. The inverted byte is shifted leShift Control Shift 0-17,0 1 bit field starting at bit 0-15 0-16,1 2 bit field staft by 2 bits and OR-ed with ZAddr, sending control to address ZAddr + (OP' * 4). If BPC[3] is true, OP is forced to 37rting at bit 0-14 0-15,2 3 bit field starting at bit 0-13 ... 0-2,15 147, sending control to location ZAddr, which is another version of Refill. This version of Refill also does the Fetch4 to  bit field starting at bit 0-2 0-1,16 15 bit field starting at bit 0-1 0-17,17 Left shiftthe OP file, zeroes BPC, increments UPC by 4, and does the LoadOp, but then repeats the NextInst instead of returning via 0-15 10-17,16 Rotate Right 8-15 10-17,15 Rotate Right 0-7 0-17,17-0 RightS8  GEQI 39 GEQPOWR 43 GEQSTR  48 JNEB 48 JNEW 48  44 GL 3 GP 2  JTB 48 JTW 48 LAND  - 58 - PERQ QCode Reference Manual 04 Feb 82  38 LDAP 56 LDB 34  GTRBOOL 38 GTRBYT 45 GTRI  LDC0 26 LDCB 26 LDCH  39 GTRSTR 44 HR 4  35 LDCMO 26 LDCN 26  INCB 36 INCDDS 57 INCW  LDCW 27 LDDC 33 LDDW  45 EQUI 39 EQUPOWR 42  36 INDB 36 INDW EQUSTR 44 EQUWORD 46 ER  36 INN 42 INT 42 I 4 ES 4 ESTACK 1 NTOFF 55 ISN 1 IXA1  ETOS 1 Exception 4 Exception Handler  36 IXAB 36 IXAW 36  4 EXCH 55 EXCH2 55  IXP 37 JCS 56 JEQB  EXGO 51 EXIT 51 GDB  48 JEQW 48 JFB 48  1 GEQBOOL 38 GEQBYT 45  JFW 48 JMPB 48 JMPW 9  The stack can be reset (no items on the stack) by the StackReset special function. Stack empty can be read as a bit in urrent instruction address plus 1, and 4) The Victim register. There are three jumps which are multi-way branches. TheUSTATE. - 14 - PERQ Micro-Programmer's Guide 08 Feb  three are: 1) NextInst, which is a 256-way branch based on a byte from the OP file; 2) Dispatch, which is a 16 way (or f82 ____________ ___ Input/Output Bus IOB is the input/output bus for PERQ. The IOB is a 16-bit bi-ewer) branch on the lower 4 bits of the SHIFT outputs; and 3) Vector, which branches to 1 of 8 micro-interrupt service routindirectional data bus plus a 7-bit address bus. The addresses are supplied on the Z Field. The eighth bit of the Z field ines. For all of these branches, the Z field of the micro-instruction supplies the other bits of the address. For NextInst, tdicates the direction of transfer (1=write, 0=read). To read an IO register, set SF = 1 and F = 0 or 3. The IO regihe resulting address is: O O O O O O O O Z Z P P P P P P P P Z Z 7 6 7 6 5 4 3 2 1 0 1 0 whister is latched in the processor such that a succeeding microinstruction can read it from IOD (A = 2). IO registers can bch results is a 256 way branch with a spacing of 4 instructions. For Dispatch, the address is: Z Z Z Z Z Z S S S S e written by putting a data value on R, putting the appropriate address in Z, and coding the IOB special function (SF = 1,Z Z 7 6 5 4 3 2 3 2 1 0 1 0 which also results in a spacing of 4 instructions. The Vector jump uses the outputs F = 0 or 3). _____ Jumps A jump needing an address normally gets it from the Z field. Since Z  of the micro-interrupt priority encoder (V), which determines the highest priority micro-interrupt condition. The addris only 8 bits wide and the control store is 4K, another 4 bits of address are needed. Short jumps branch to a location on theess is: - 15 - PERQ Micro-Programmer's Guide 08 Feb  same 256-word page as the current microinstruction (CIA). To go to an arbitrary location, the F field can specify long j82 Z Z Z Z Z Z - V V V Z Z 7 6 5 4 3 2 0 2 1 0 1 0 which also has a spacing of four instructions. ump (F = 3) which uses the SF field for the upper 4 bits of address. The address for jumps might not come from t __________ Interrupts The hardware implements a microlevel interrupt which is used to allow the microphe Z (and SF). Other sources for jump addresses are: 1) The S register (which is internal to the micro-sequencer), 2) A frocessor to serve IO devices. There are (a maximum of) 8 interrupt requests which are assigned priorities by the hardw special function. The value on the top of the stack can be read at any time from TOS (A = 7). The stack is 16 levels deep. ive level call stack (also internal to the micro-sequencer) which is pushed for a Call and popped for a Return, 3) The c9  LDMW 33 - 59 - PERQ QCode Reference Manual  3 LSA 35 LSSN 56  04 Feb 82 LDO0 29 LDOB  LTS 2 LVRD 50 Memory Organization  29 LDOW 29 LDP 37  5 MES 52 MES2 52  LDTP 56 LEQBOOL 38 LEQBYT  MMS 52 MMS2 52 MODI  45 LEQI 39 LEQPOWR 42  39 MOVB 36 MOVW 36  LEQSTR 44 LESBOOL 38 LESBYT  MPI 39 MSTACK 1 MTOS  45 LESI 39 LESSTR 44  1 MVB 34 MVB 34  LGAB 30 LGAW 30 LGAWW  NE 4 NEQBOOL 38 NEQBYT  30 LIAB 31 LIAW 31  45 NEQI 39 - 60 - P 33 LDGB 30 LDGW  LINE 55 LL 2 LLA  30 LDIB 31 LDIND 32 L 28 LLAW 28 LNOT DIW 31 LDL0 28 LDLB 38 LOAB 29 LOAW 29 LO 28 LDLW 28 LDMC 33 PS 47 LOR 38 LP :  not UState(Register), Field(14,4); Result := Shift; ! Result[3:0 | 'Decimal' | 'Nop' | 'Case' '(' constant ',' constant ')' | 'Place' '(' co] := Register[19:16] - 16 - PERQ Micro-Programmer's Guide nstant ',' constant ')' . PascalStyleConstant = name '=' constant . - 17 -are. When any of the interrupt requests is asserted, the branch condition IntrPend will succeed. The intended usage of  08 Feb 82 ______ __ ______________ Syntax of Micro-Programs This describes the syntax o this feature is that at convenient places in the microcode an instruction which has "If IntrPend Call(VecSrv)" is used. If af Perq micro-programs recognized by the PrqMic assembler. The syntax is described with a meta-language called EBNF (extendeny interrupts are pending, control will pass to VecSrv which should contain a Vector jump to send control to ZAddr + Vector*d BNF). The following meta-symbols are used. ' ' - surround literal text. | - sep4 in the control store. The address of the interrupted instruction is on the call stack, and the interrupt microcode can serarate alternatives. [ ] - surround optional parts. { } - surround parts which may be rve the device and return like a subrou- tine would. ______ USTATE The USTATE register contains vepeated zero or more times. ( ) - are used for grouping. . arious interesting items packed in a single word. The USTATE register (A=5) looks like: 19 16 15 12 11  - ends a description. name = letter {letter | digit} . number = ['2#' | '8#' | '10#' | '#' ] digit {digit} .  9 8 7 6 5 4 3 0 +-----------+-----------+--------+--+--+--+--+--+-----------+ | 0 | BMUX 1constant = name | number . register = name . label = name . empty = . MicroProgram 9:16| unused |SE| N| C| Z| V| BPC | +-----------+-----------+--------+--+--+--+--+--+-----------+ BPC = {Instruction ';'} 'end' ';' . Instruction = {label ':'} Field {',' Field} . Field = empty | PseudByte Program Counter N Negative (ALU result < 0) Z Zero (ALU result = 0) C Carry (ALU caro | PascalStyleConstant | {Result ':='} ALU | Jump | Special . Psry out of bit 15) V Overflow (ALU overflow occured) SE ESTK Empty (inverted data -- 0 = empty) Beudo = 'Define' '(' name ',' constant ')' | 'Constant' '(' name ',' constant ')' | 'Opcode' 'MUX 19:16 Upper 4 Bits of BMUX, used to read bits 19:16 a register (inverted data). Do it this way: (' constant ')' | 'Loc' '(' constant ')' | 'Binary' | 'Octal' :  NEQSTR 44 NEQWORD 46 NGI  STARTIO 55 STB 34 STCH  39 NOOP 52 PC  35 STDW 33 STGB 31 PS 2 Q-Machine Architecture 1 RA 0 STGW 30 STIB 31 STI 3 RAISE 51 Raising an Exception ND 32 STIW 31 STL0  4 RASTER-OP 52 RD 3  28 STLATE 55 STLB 28  REFILLOP 56 REPL 52 REPL2  STLW 28 STMW 33 STO0  52 RETURN 50 RN 2  29 STOB 29 STOW 29  ROPS 40 ROTSHI 37 RPS  - 61 - PERQ QCode Reference Manual 04 Feb 82  2 RR 3 RS 3  STP 37 TL 2 TLATE1  SAS 35 SB 1 SBI  55 TLATE2 55 TLATE3 55  39 Segment 1 SGS 42  TP 2 UNI 42 WCS  SIND 36 SL 2 SRS  56 XGP 3 XJP 48 ERQ QCode Reference Manual 04 Feb 82 NEQPOWR 42  42 SS 2 SSN 2 ;  | 'C19' | 'IntrPend' | 'Odd' | 'ByteSign' | 'Eql' | 'Neq' d anywhere. The exception to this rule is that a new micro-instruction begins with a new line, i.e. you may not | 'Gtr' | 'Geq' | 'Lss' | 'Leq' | 'Carry' | 'OverFlow' . Goto = 'Goto' | 'Ca place more than one instruction per line. 2) Names may be any length, but only 10 characters are significant wll' | 'Return' | 'Next' | 'JumpZero' | 'LoadS' | 'GotoS' | 'CallS' | 'NextInst' | 'Revhen two names are compared. 3) Comments may be indicated by an exclamation mark: '!'. The remainder of the line fiveVictim' | 'PushLoad' | 'Vector' | 'Dispatch' | 'RepeatLoop' | 'Repeat' | 'JumpPop' ollowing the exclamation mark is ignored. Comments may also be enclosed in braces Pascal style: '{' and '}' or '(*' and | 'Loop' | 'ThreeWayBranch' . Addr = label | constant . Special = Nonary | Una'*)'. 4) Numeric constants preceded by a '#' are octal constants. 5) Constants may be defined Pascal style: nam PERQ Micro-Programmer's Guide 08 Feb 82 Result = register | SpecialResult . ry | Binary . Nonary = 'WCSlow' | 'WCSmid' | 'WCShi' | 'LoadOp' | 'Hold' | 'StackReset' | ' SpecialResult = 'TOS' | 'MA' | 'MDO' | 'BPC' | 'SrcRasterOp' | 'DstRasterOp' Push' | 'Pop' | 'Fetch' | 'Fetch2' | 'Fetch4' | 'Fetch4R' | 'Store' | 'Store2' | 'Stor | 'WidRasterOp' . ALU = ['not'] (Amux | Bmux) | Amux Op ['not'] Bmux e4' | 'Store4R' | 'LatchMA' | 'ShiftOnR' . Unary = UnaryName '(' constant ')' .  | Amux '+' Bmux ['+' 'OldCarry'] | Amux '-' Bmux ['-' 'OldCarry'] | Amux 'amux' Bm UnaryName = 'LeftShift' | 'RightShift' | 'Rotate' | 'IOB' |ux | Amux 'bmux` Bmux . Amux = register | 'Shift' | 'NextOp' | 'IOD' | ' 'CntlRasterOp' . - 18 - PERQ Micro-Programmer's Guide MDI' | 'MDX' | 'TOS' | 'UState' ['(' register ')'] . Bmux = register | constant .  08 Feb 82 Binary = BinaryName '(' constant ',' constant ')' . BinaryName = 'Field' .  Op = 'and' | 'or' | 'xor' | 'nand' | 'nor' | 'xnor' . Jump = [Test] Goto ['(' A _____ __ ___ ______ Notes on the Syntax 1) Programs are typed in free format. That is, a single micro-ddr ')'] . Test = 'If' Condition . Condition = 'True' | 'False' | 'BPC[3]'  instruction may extend to as many lines as desired. Blank lines and lines consisting only of comments may be inserte; t is subject to change without notice and should not be construed as a commitment by Three Rivers Computer Corpotains flags which are set by the compiler. Bit 0, the least significant bit, indicates whether the segment is a program oration. The Company assumes no responsibility for any errors that may appear in this document. Three Rivr module. (A program is a special instance of a module, which includes a main body.) The remaining 7 bits are reserved  XST 3 ers Computer Corporation will make every effort to keep customers apprised of all documentation changes as quick - 62 - ly as possible. PERQ is a trademark of Three Rivers Computer Corporation.  PERQ Segment Files Ed Frankenberry  - ii - PERQ Segment File Format - Introduction 17 Jul 81  July 1981 A segment file is an object file produced when a program  Introduction Segment files are produced by compilers for use by the linker, loader and debugger. Segment files is compiled. The segment file is used primarily to hold the actual QCodes which the PERQ executes. In addition to the  have the extension ".SEG". Along with a run file, a collection of segment files contains all information necessary for QCodes, the segment file includes information used for linking, loading and debugging. This document describes  execution of a program. Segment files must conform to certain formatting conventions. A segment file consists of 2the current format of segment files as defined in the POS. The reader is assumed to be familiar with the QCode Re56 word blocks organized in four groups: 1) a header block; 2) one or more code blocks; 3) an import list; 4) a routine namference Manual. Copyright (C) 1981 Three Rivers Computer Corporation 720 Gross Street e list. The header block contains information about the size and contents of the module. The code blocks contain the QCod Pittsburgh, PA 15224 (412) 621-6250 PERQ Segment File Format 17 Jul 81 es and routine dictionary generated by the compiler. The code blocks are followed by a list of imported modules and a lis This document is not to be reproduced in any form or transmitted, in whole or in pat of the routine names declared in the current module. Header Block The first portion of the segment file contart, without the prior written authorization of Three Rivers Computer Corporation. The information in this documenins 9 fields, shown in the figure below (precise sizes of fields may be found in the appendix). The first byte con<  a single instruction. For example, TOS := MA := 10; is valid, but TOS := BPC := 10;  req JumpPop opt req Loop opt ThreeWay is invalid. The 'Micro Instruction Format' section shows which fields of a micro-instruction are used by aBranch opt req _________ ________ Assembler Commands There are several commands  particular action. The rule is that a certain field may be used only once. Thus since 'TOS :=' and 'BPC :=' both uwhich are directives to the assem- bler and placer to perform special actions. Assembler commands are indicated by a '$' ise the SF (special function) field, they both may not be used in a single micro-instruction. n column 1. The entire line is considered to be an assembler command. You may not type other micro-instructions on the same - 19 - PERQ Micro-Programmer's Guide 08 Feb 82 8) Some goto types do not al line. '$Include' FileName The text in the named file is inserted into the micro- program low tests (are unconditional), and for some the test is optional. Similarly, some do not allow addresses, som as though it were present in the original source file. Included files may not be nested. Only the orginal e require them, and for some the address field is optional. This table gives the rules. req - required, opt - o source file may contain an Include command. '$Title' TitleString The TitleString is printed on the aptional, - not allowed ____ ____ ____ _______ Goto type test ssembly listing on the first line of every page. The first Title command sets the main title which ise = value; This allows including a file which contains constant definitions into both a Pascal program and a micro-pr address Goto opt req Call opt req ogram. 6) The following ALU functions are allowed by the syntax descrip- tion, but do not exist. The assembler disall Return opt Next JumpZero LoadS req ows them. Amux 'nand' 'not' Bmux Amux 'nor' 'not' Bmux Amux 'xor' 'not' Bmux (equivalent to  GotoS opt opt CallS opt opt NextInst Amux 'xnor' Bmux) Amux 'xnor' 'not' Bmux (equivalent to Amuv 'xor' Bmux) 7) The syntax allows constructions whic req ReviveVictim PushLoad opt req Vector h are semantically incorrect. In other words, there are many combinations of actions which cannot be represented in opt req Dispatch opt req RepeatLoop Repeat < ------------------| | Import Block Number | |---------------------------------------rd 2 of this block. The QCodes for each routine follow those of the previous routine on the next word boundary. The code se| | Size of Global Data Block (GDB) | |---------------------------------------| | ction of the segment file may occupy several consecutive blocks. The routine dictionary is aligned on the next quad-word boun version string | |---------------------------------------| | copyrightdary following the end of the QCodes. +---------------------------------------+ | Offset to string | |---------------------------------------| | reserved  Routine Dictionary | |---------------------------------------| | Number of Routines in this Se | +---------------------------------------+ toward high memory gment | |---------------------------------------| | QCode | for future use. The high-order byte of this word contains the version number of the QCodes generated by the compiler. The - 3 - PERQ Segment File Format - Header Block 17 Jul 81 The third field gives next field contains the name of the module (as it appears in the source file). Module names are currently unique to 8  the number of imported segments. This is followed by the number of the block containing the import list (described bel characters. The name of the source file from which the segment file was generated follows the module name. The fileow) and the size of the global data block (referred to as the GDB in the QCode Reference Manual). The "version" and "cname string contains the full pathname of the source file from which the segment file was generated. MSB 1opyright" fields complete the information stored in the first block. These strings may be specified using compiler switch5 LSB 0 +---------------------------------------+ | QCode version # | es. The remainder of the header block is reserved for future use. Code Blocks The second block (block number  flags | |---------------------------------------| | module name | 1) is the start of the code portion of the segment file. Word 0 points to the routine dictionary which follows |---------------------------------------| | file name | |--- the code. The value in word 0 is the offset (in words) from the beginning of block 1 to the first word of the routine ------------------------------------| | Number of Segments | |---------------------dictionary. Word 1 contains the number of routines within the segment. The QCodes generated by the compiler start with wo=  08 Feb 82 '$NoList' The listing is turned off until a List command is encounteror- PrqPlace Once a micro-program has been assembled and placed, you can use it in one of thesed. This command has an effect only if a listing is requested when the placer is executed. '$List' The lise ways: a. Load it into another Perq with OdtPrq. b. Load it into the same Perq with the ControlStore module. c. ting is resumed if it was turned off by a NoList command. This command has an effect only if a listing is Write it into a boot file with MakeBoot. - 22 - PERQ Micro-Programmer's Guide requested when the placer is executed.  08 Feb 82 ________ _______ _____ _____ ___ Writable Control Store (WCS) Map  - 21 - PERQ Micro-Programmer's Guide 08 Feb 82  The following provides a map of the Writable Control Store (WCS) and describes the micro code register usage. When yo ________ ____________ Assembly Instructions Before a micro-program can be run it must be assembled with u boot the system, VFY.MICRO runs memory diagnostics. SYSB.MICRO then loads microcode from the MBoot file. At boot timPrqMic and then placed with PrqPlace. PrqMic translates the program into binary machine language, and PrqPlace assigns physie, microcode can only be loaded into WCS addresses 0 through 7377. At the end of the boot, only PERQ.MICRO and IO.MICRO acal micro- store locations to those instructions which are not assigned by the micro-programmer. The following showsre in the WCS. This leaves 7000 through 7777 for user defined microcode. (You can use 7000 through 7377 for bootable special how to assemble and place a micro-program. A micro-program source file name has the form .MICRO. is called the ro purpose microcode.) PERQ.MICRO -PERQ Q-Code interpreter microcode. Temporary registers store state information during Q-ot name. assemble: PrqMic Root file name? -or- Code interpretation. Registers: 3-21, 51-57, 64-67, 370. Temporary registers: 30-50, 61-63, 70-77. Placement: 0-4377.  PrqMic place with listing: PrqPlace Root file name? IO.MICRO - Input/Output microcode. Registers: 200-207, 211-217, 221-233, 235-252, 255-260, 262-266, 276, 277, 327,  printed at the left of each page. Each subsequent Title command sets the subtitle which is printed at t List file name? -or- PrqPlace place without listing: he right of each page. - 20 - PERQ Micro-Programmer's Guide  PrqPlace Root file name? List file name? -= (8 character) module name followed by the full pathname of the source file. Each entry is word aligned. Block = ^SegBlock; SegBlock = packed record case boolean of { .SEG file definition } { first bl - 4 - PERQ Segment File Format - Routine Dictionary Entries 17 Jul 81 Routine Namock: } true: (ProgramSegment: boolean; SegBlkFiller : 0..127; { low order byte List After the list of imported segments, the compiler provides the names of the routines. The first routine name e } QVersion : QVerRange; { high order byte } ModuleName : SNArray begins immediately after the last import entry. The entries in the routine name list are 8 characters long, are word-alig; FileName : FNString; NumSeg : integer; ned, and are ordered by routine number.  ImportBlock : integer; GDBSize : integer; Version : st - 5 - Appendix - Relevant Pascal Declarations 17 Jul 8ring[CommentLen]; Copyright : string[CommentLen]); false:(Block: array[0..2551 Appendix Users who need to manipulate segment files are encouraged to import the declarations found in the f] of integer) end; CImpInfo = record case boolean of { Import List Info - as } ile "Code.Pas". The necessary definitions to access portions of segment and run files may be found in this file. Pertinent s { generated by the compiler } true: ( ModuleName: SNArray; { module identifier  | . . . | +---------------------------------------+ The dictionary conections are included here which give the actual definitions and lengths for fields described above. Exports consttains an entry for each routine in the module, and is padded to the end of the current block. A more complete descriptio QCodeVersion = 2; { Current QCode Version Number } FileLength = 100; { max chars in a file name } n of the routine dictionary may be found in the QCode Reference Manual. Import List The import list begins  SegLength = 8; { max chars in a segment name } CommentLen = 80; { max chars in a comment string }  in the block following the routine dictionary. Imports refer to segments which are external to the current module.  type SNArray = packed array[1..SegLength] of Char; { segment name } FNString = String[FileLength]; { file  The import list is ordered by segment number (the compilergenerated ISN). Each entry in the import list consists of the name } QVerRange = 0..255; { range of QCode version numbers } { Segment file: } pSeg> ode does it). - The Z field is inverted for all addresses (assembler fixes it). - IOB functions are executed373, 374. Temporary registers: 220, 261. Placement: 4400-5777. LINK.MICRO - 16 bit parallel interface microcode. (Not  twice if an abort occurs. - C19 will not be valid if an abort occurs on the test. - C19 test is inverted sense (i.e. j normally booted into WCS). Registers: 350, 351. Placement: 6744-7400. SYSB.MICRO - system boot microcode. Registers: ump if no carry out of bit 19). - UState[15:12] (the upper BMux bits) are inverted. - Condition codes are not qui0-64. Placement: 7000-7777. IOE3.MICRO - Microcode for 3MBaud ETHERNET. This area is available if the system will notte right after double precision adds and subtracts. See the `Condition Codes` section. - Condition codes are invalid  use ETHERNET. Registers: 270-274. Place- ment: part of IO.MICRO. BOOT.MICRO - Boot microcode. Registers: 0-2, 4, 10, 20 after ReadProduct, ReadQuo- tient, and ReadVictim. , 40, 100, 200, 252, 277, 307, 337, 350, 357, 367, 373, 375, 376, 377. Placement: 0-777. KRNL.MICRO - PERQ micro - 24 - PERQ Micro-Programmer's Guide 08 Feb 82 code kernel. Registers: 0, 357-377. Place- ment: 7400-7777. GOODBY.MICRO - Power down microcode. Placement: 5000-5377.  _____ __ ________ Table of Contents 1 Introduction to the Hardware 3 Micro Instruction Forma ETHER10.MICRO - 10MBaud ETHERNET microcode. Registers: 300-321. Placement: 7000-7300 RO.MICRO - Raster-op microcode. t 6 Constants 7 OldCarry 7 Condition Codes 8 Memory Control 13 Opcodes and Oper Registers: 100-124, 130-142, 370. Placement: part of PERQ.MICRO. LINE.MICRO - Line drawing microcode. Registers: 100, 1ands 14 Shift Control 14 ShiftOnR 14 Expression Stack 15 Input/Output Bus 15 Jumps 01, 103-116. Placement: part of PERQ.MICRO. VFY.MICRO - Verifies that the hardware seems to work. Registers: 0-16, 300, 16 Interrupts 16 USTATE 17 Syntax of Micro-Programs 19 Notes on the Syntax 20 Assem 301, 370. Placement: 4000-6377. - 23 - PERQ Micro-Programmer's Guide bler Commands 22 Assembly Instructions 23 Writable Control Store (WCS) Map 24 Quirks  08 Feb 82 ______ Quirks As of 12/1/80, the following quirks are known: - The Z - iii -  field is inverted for Shift functions (assembler fixes this). - The Op file is inverted on NextInst (assembler Opc> gBlock; - 6 - Table of Contents 17 Jul 81 3 Introduction 3 Header Block 4 Code Blocks 4 Routine Dictionary Sides 2 Density SINGLE Fast ! DOCUMENTATION-1 - DOCUMENTATION ! Created 10 Feb 82 15:26:30 Get EDITOR.DOC   EDITOR.DOC Get EDITK.DOC EDITORK.DOC Get EXAMPL.DOC EXAMPLES.DOC Get FAULT.DOC FAULT.DOC Ge - iii - t FEATUR.DOC FEATURES.DOC Get FILE.FOR FILE.FORMAT Get FILES.DOC FILES.DOC Get MICRO.DOC  MICRO.DOC Get MAKESY.DOC MAKESYSTEM.DOC Get PASCAL.DOC PASCAL.DOC Get PERQZ8.DOC PERQ_Z80.DOC Get QCODE.DOC QCODE.DOC Get SEGMEN.DOC SEGMENT.DOC Get SETBAU.DOC SETBAUD.DOC  10 Sep 81 PROGRAM SETBAUD Program SetBaud allows the user to set the RS232 baud rate to any valid rate. It is called by typing SETBAUD [rate] Where rate is the desired baud rate. Valid baud rates are 9600, 2400, 1200, 600, 300, 150, and 110. If the rate is not on the command line the user will be prompted for it. If the rate is not a valid one, the user will be prompted for a new rate. A second The user must remember the size used with NewP since DisposeP takes the size as a parameter.  invalid baud rate will result in a list of valid baud rates being displayed on the console. A successful change in baud  - 2 - Programming Examples - Allocating Memory 08 Feb 82 Procedure DisposeP(var p:} FileName: FNString { file name } ); false:( Arrate will result in a message telling the user that the new baud rate is what he asked for. y: array [0..0] of integer) end; { used with range checking disabled } SegFileType = file of Se - 1 - ?  documentation changes as quickly as possible. The Reader's Comments card is distrib- uted with this document to ant files on floppy disks before you begin changing the PERQ Operating System. While it is improbable that you will derequest users' critical evalu- ation to assist us in preparing future documentation. PERQ is a trademark of stroy any files by changing the system, the importance of backup files cannot be stressed too much. 2. Maintain atThree Rivers Computer Corporation. - ii -  least one partition of the disk that runs the old system. This enables you to boot your PERQ in the event that  How to Make a New System 08 Feb 82 ___ _____ __ ____ ______ The Scope of This Manualyour new system contains bugs. When you receive your PERQ, the hard disk is divided into several partitions. At lea How to Make a New System John P.  This is a "how to" manual. If you follow the instructions of this manual, barring errors in the manual and Strait This manual describes how to change modules contained in the Three Rivers PERQ Operatinbugs in your modifications to the system, you should be successful in making a new system. The instructions in this mag System and how to create a new version of that system. Copyright (C) 1981, 1982 Three Rivernual are not guaranteed to show you the most efficient way of making your changes. It only shows you a reliable way of mas Computer Corporation 720 Gross Street Pittsburgh, PA 15224 (412) 621-6250 How to Make a New System king the changes. This manual doesn't attempt to explain why the system is organized the way it is nor why each  08 Feb 82 This document is not to be reproduced in any form or step is required. If your changes are not too major, this manual will help you to create a new system. It does not exp transmitted in whole or in part, without the prior written authorization of Three Rivers Computer Corporation. lain how to change low-level interface (e.g., interface to the Stream module) or low-level data structures (e.g., the se The information in this document is subject to change without notice and should not be construed as a commitmengment tables or the structures on disk). _______________ Recommendations We make several recommendations to helt by Three Rivers Computer Corporation. The Company assumes no responsibility for any errors that may appear inp you avoid errors that will make your system non-bootable. Remember, if you can no longer boot your PERQ, you can always  this document. Three Rivers Computer Corporation will make every effort to keep customers apprised of all boot from the "PERQ System Boot Floppy". Therefore, you always have a way of bringing up your PERQ. 1. Back up import? ot be enough memory to hold the large segment and all other necessary data. Therefore, the user should divide the data  MakePtr(seg, i*256, pDirBlk)); The MakePtr creates a pointer to the i-th block (the i*256-th word) of the segment. WARN MMPointer; size: integer); The size MUST be the same size used with NewP. One way to insure this is to store the size ainto separate segments, each of which is about 10 blocks large. For example, this is what the editor does to hold the ps a field in a record. As an example of NewP, we make a variable length array of strings: Type s25 = String[25]; iece table. - 3 - Programming Examples - Reading in Large Files  NameDesc = RECORD numCommands: integer; recSize: integer; commands: array[ 08 Feb 82 3. Reading in Large Files. There are a number of ways to read in a font or a picture from the 1..1] of s25; {vbl length array} END; pNameDesc = ^NameDesc; To allocate a pNameDesc with NUM namedisk. The fastest and most straightforward way is to use MultiRead. This is a special procedure that uses the micro-code's s in the segment seg, the following would be done: var p: MMPointer; size: integer; names: pNameDesability to read multiple blocks at once. The read, therefore, occurs at the maximum possible speed (the actual speed depc; begin size := 2*WordSize(integer) + { for the 2 integers } NUM*WordSize(s25); { the variable paends on how contiguous the blocks are on the disk). To use multi-read on a file called FileName do the following: varrt } NewP(seg, 1, p.p, size); names := RECAST(p.p, pNameDesc); names^.recSize := size; names^.numCommand fid: FileID; {imported from FileSystem} blocks, bits: integer; seg: Integer; begin fid := FSLookUps := NUM; {$R-} {turn range checking off to assign names} for i := 1 to NUM do names^.commands[i] := ''; {$R=} {return range checking to the previous state} end; Since Dynamic uses special places in the segmen {allocate} MultiRead(fid, MakePtr(seg, 0, pDirBlk), 0, blocks); end; end; MultiRead takes a fileIDt to store the free list information used by NEW, it is bad practice to mix NEW and MakePtr on the same segment. Whe, a pointer to the start of the block of memory, the first block to read of the file to read, and the number of blocks. n a program requires a large amount of data, consider the swapping characteristics of the operating system. Since POThe above code reads in the entire file. If you do not wish to import MultiRead, you can read in each block of the file uS swaps an entire segment at once, a big segment will take much longer to read in and write out. Also, there may simply nsing FSBlkRead. Replace the MultiRead call above with the following for i := 0 to blocks - 1 do FSBlkRead(fid, i,@ tition for your new experimental files when you begin making your changes to the system. Copy the sources of the fompile those modules and programs that import the ones you are chang- ing. 2. Are you adding exports but notiles you want to change into this area before you begin editing. Compile all new .Seg files into this area. Do no changing any that already exist? If you don't change existing exports, you need to re-compile only those modulet use the root directory in the default partition: the one that is entered by the default boot letter ("a" is des that you change. You must, however, add your new exports at the end of the export list. By adding at the enfault--the same as not holding down a key). The default boot files are System..a.Boot and System..a.MBoot. d of the export list, you do not change the storage allocation of existing variables or the routine numbers of exist - 1 - How to Make a New System 08 Feb 82 If youing procedures and functions. If you change either of these, you must re-compile all modules and programs t do not change the default boot files or the files in the root directory of the default partition, you will still havhat import the ones you are chang- ing. 3. Are you changing the definition of data structures which are knoe source and binary files that you can fall back on. ________ Overview Creating a new system usually consiswn by the microcode (e.g., memory manager tables) or data structures that live across boots (e.g., struc- turesst one partition contains a pair of boot files: System...Boot and System...MBoot. The in the file namts of the following steps. 1. Evaluate the change you intend to make 2. Create a directory to work in 3. Edit and come is the current system version number, and the in the file name represents the character that you hold down tpile system modules 4. Edit and compile system programs 5. Link the system and system programs 6. Prepare the system coo use the corresponding boot files and partitions. The .Boot file contains the Operating System, and the .MBonfiguration file 7. Write a boot file 8. Test the new system 9. Iterate at step 3 ________ ___ ______ ___ ____ot file contains the QCode interpreter microcode. 3. Do not change System..a.Boot and System..a.MBoot until yo__ __ ____ Evaluate the Change You Intend to Make Before you begin, you should determine how extensive the changur new system is completely debugged. These are the default boot files. If you do not change these files, you caes are. The following criteria tell you how much you need to change. 1. Are you changing the existing exports of n boot the old system in the case that your new system contains errors. 4. Create a new directory or select an unused parany system modules? If not, you need only re-compile those modules that you change. If so, you may need to re-c@ 300, 400, SScreenW, SScreenP, 300, 400, SScreenW, SScreenP); We do this by Xoring the area withnt of this size and a RasterPtr to its start: - 5 - Programming Examples - RasterOp a itself. Similarly, to clear an area to black, use the function RXNor. The function names are exported by the module nd Line 08 Feb 82 CreateSegment(seg, 89, 1, 89); p := MakePtr(seg, 0, RasterPtr); Now weRaster. To move a rectange from one area of the screen to another, simply use a different source and destination position. R might read a file into this buffer as described in Section 3. Next, we want to transfer the picture onto the screen, say emember that the destination is specified first. To move a rectangle one bit down: RasterOp(RRpl, 100, 200, 300, 400, SS at position (10, 100). We use RasterOp(RRpl, 543, 632, 10, 100, SScreenW, SScreenP, 0, ING: The multi-block read exported by FileAccess does not work. creenW, SScreenP, 300, 399, SScreenW, SScreenP); The position (0,0) is in the upper left cor - 4 - Programming Examples - RasterOp and Line 08 Feb 82 4. RasterOp and Line. RasterOner; the lower right corner is (767, 1023). RasterOp does not validate the widths or positions so be careful. Be espep and Line are the chief graphics primitives of the PERQ. Each is fast. TThe primitives allow drawing of rectangles cially careful to avoid negative widths and heights since these are taken as large positive numbers. The available RasterOp fand lines, respectively. RasterOp is described in the PERQ Pascal Extensions manual and Line is exported by the Screen unctions are: RRpl {dest get src} RNot {dest get invert of src} RAnd {dest gets dest AND src} RNmodule. Use RasterOp to clear a rectangle (either white or black); transfer a picture from one place to another; or combiAnd {dest gets dest AND invert of src} ROr {dest gets dest OR src} RNor {dest gets dest OR invert of src} ne two pictures. Use Line to draw a single width line on the screen at any orientation. RasterOp is a general utility. It  RXor {dest gets dest XOR src} RXNor {dest gets dest XOR invert of src} RasterOp can also move a picture from orcan be used on buffers that are not on the screen. Therefore, it takes parameters that describe the dimensions of the buf to an off-screen buffer. Suppose a picture is 543 bits wide and 632 bits high. The buffers used by RasterOp must be a multfer. For the Screen, the two constants SScreenW and SScreenP are exported by the Screen module. As a first example, weiple of 4 words in width. Therefore, allocate a buffer that is 36 words (=576 bits) wide and 632 bits high. This is 22 will clear an area of the screen 100 bits wide, 200 bits tall, starting at position (300, 400): RasterOp(RXor, 100, 200, 752 words. Since segments can only be allocated on block boundaries, round up to 22784 words or 89 blocks and create a segmeA e, Dynamic, and Stream). If so, you again need to do a complicated bootstrapping opera- tion. This too, is beyorun files for System, Login, Shell, and Link should be in the root directory of the partition which contains your new snd the scope of this manual. 5. Are you changing the format of .Seg files? If so, you need to do a complicated bystem. You should use the following link commands to link your new system (assuming that the partition name is Part): ootstrapping operation which is beyond the scope of this manual. ______ _ __________ _____ ___ _______ Create a Link SystemSystem.100/System Link LoginLogin.100 Link ShellShell.100 Link LinkLink.100 Directory, Edit, and Compile Create a new directory for your experimental files. You do this with the MakeDir util - 3 - How to Make a New System 08 Feb 82 _______ ___ ____ity program. This new directory should be in the partition which contains the old system (probably the Boot partition). C__ _____________ ____ Prepare the System Configuration File Before you write the boot file, you must create a sysopy sources of the system modules and programs into this directory. You may choose instead to work in a partition whtem configuration file which describes the swappability of segments in the system. You probably can just copy the configuich, up until now, has not been used. Using a new partition is somewhat safer than merely creating a new directory in ration file for the current version of the operating system. The default configura- tion file is named System..Config.some old partition. Edit the modules and programs that you need to change. Re-compile those modules and prog If you need to change the swappability of segments in the system, you can copy the old file and edit it. Each line in trams that you have changed and any others indicated by your evaluation of your changes. ____ ___ ___ ______ Link the Nhe file describes the swappability of a single segment in the form: The ew System Once all necessary changes and compilations have been done, you should link the new system and system program is chosen from the following: SW - segment is swappable. LS - segment is swappable but the memory manager sho on disk)? If so, you may need to do a complicated bootstrapping operation to bring up your new system. This is s. Choose a new system version number. Three Rivers Computer Corporation intends to use the version numbers between 1 beyond the scope of this manual. - 2 - How to Make a New System and 99 for releases of the official PERQ Operating System. You should avoid these numbers to prevent conflicts with futu 08 Feb 82 4. Are you changing the existing exports of modules that the compiler knows about (Codre Three Rivers Computer's releases. For exam- ple, you should choose version number 100 for your new system. The new A idth 48 (e.g. the screen). Line is defined as: Line(style: LineStyle; x1, y1, x2, y2: integer; p: RasterPtr); w on each side. On the top there may be a title line which is a band of black with white letters in it. Once a window is here the style is DrawLine, XOrLine or EraseLine. Use SScreenP for p. created, it cannot be moved or re-signed. Creating a new window automatically changes output to go to the new window. Gi - 6 - Programming Examples - Windows 08 Feb 82 5. Windowsven a set of windows, you can change amonst them by using the ChangeWindow command. The procedure GetWindowParms returns . POS currently supports multiple, overlapping windows. However, POS does not know when two windows overlap. Thus parameters of the current window. Unfortuneately, you must do transformations on the numbers returned to get the all windows are "transparent" in that anything written to a covered window will "show through" any windows that a inside and outside areas of windows: GetWindowParms(var windx: WinRange; orgX, orgY, width, height: integer; re on top. Even with this restriction, windows are useful for a number of applications. For example, if multiple thin var hasTitle: boolean); windx is the current window number and hasTitle tells whether there is a title line. Cgs are going on and the user wants to separate the input and output of each. The Screen package handles scrolling of alculate the outside of the window as follows: begin orgX := orgX - 2; width := width + 5; orgY := orgY - 0, 36, p); The destination (given first) is (10, 100) on the screen, but the source is now the buffer. The bit width t the text inside windows automatically. Therefore separate windows scroll separately (if they do not overlap). This io transfer is 543 (the second argument), but the word width of the buffer is 36. (SScreenW is 48, the number of words acrs useful, for example, in a graphics package where there are commands typed in a small window with the rest of the areaoss the screen). p is the pointer to the buffer. A picture can be transfered from the screen into a buffer, or between used for the graphics (an example is the CursDesign program from the User Library). The user must maintain the allocat buffers in a similar manner. If you want to allocate a buffer using NEW or NewP for RasterOping to or from, be sure to maion of windows; the user tells the screen package where each window is and is expected to remember the number for each windoke the allignment 4. Line is used for drawing straight, single width lines on the screen. It takes a source and destination w. Window zero is reserved for the system and its size should not be changed. Use CreateWindow to create a new window. x and y position, a style and a pointer to the buffer to draw in. Currently, it can only draw lines in buffers that have wThe parameters passed are for the outside of the window. There are two bits of border, then a hair line, then two more bitsB uld be reluctant to swap it out (this is not implemented yet). US - segment is not swappable but may be moved  Perq_String SW Screen SW FileSystem SW GetTimeStamp SW FileDefs SW Memory SW IO_Init Sin memory. UM - segment is neither swappable nor movable. Names with asterisks are recognized as special segment namesW RunRead SW FileDir SW Scrounge SW _____ _ ___ ____ ____ Write a New Boot File You are now r. They are chosen from the following list: *SAT* - Segment address table (default UM) *SIT* - Segment infoeady to write a boot file using the MakeBoot program. Before you run MakeBoot, choose a boot-letter for this new systemrmation table (default US) *Cursor* - Display cursor (default UM) *Screen* - Display screen (default UM) *Font; use one not already in use. You can run the Details program to find out which letters are in use. After choosing a boot let* - Character set (default US) *Stack* - Run-time stack (default US) *Names* - System segment names (default SW)ter, run MakeBoot and answer the questions in the following way: -- Underlined text is what the PERQ types -- Commentary is *IO* - Input/output tables (default UM) The default for code segments (modules) is US. We strongly suggest that given inside { } -- means type the RETURN key without entering any text -- In this example, assume you have chosen the b you do not change the swappability of the special segments and, unless you are sure you know what you are doing, do not changoot letter "z" _ :MakeBoot _______________ Root file name: System.100 _______________________ ____________________ Coe the swappability of existing system modules. System data segments that the hardware or microcode uses cannot be moved, monfiguration file name [System.100.Config]: _____________________________ Which character to boot from? z ____________st data used by the operating system cannot be swapped, and the code that makes up the swapping system itself cannot be s____________________________ Do you want to write the boot area [No]: { The boot area of the disk contains a microwapped. Since the default for code segments is US, you should add entries to the configuration file if you add modules toprogram which runs diagnostics and reads the .Boot and .MBoot files. You need to rewrite this only if you are mak the system. The default system configuration file is: *SAT* UM *SIT* US *Cursor* UM *Screen* ing modifications to Vfy.Micro or SysB.Micro. } _______________________________ Write a system boot file [Yes]: _UM *Font* US *IO* UM System SW Stream SW Writer SW IOErrMessages SW Loader SW ______________________________________________________ Enter name of new system boot file [System.100.z.Boot]: ___________ - 4 - How to Make a New System 08 Feb 82 Reader SW _________________________________________________ Existing boot file to copy (type return to build a new one): ___________B  if hasTitle then begin orgY := orgY + 2; height := height - 4; end; end; One thing to nontP onto the screen by hand (at position (xPos, yPos)), use the following form (copied from SPutChr in Screen): ote: the title line for a window is written in the font that was in effect before the window was created. This font wivar Trik: Record Case Boolean of true: (F: FontPtr); false: (seg, ofst: integer); ll also be remembered as the font to use the next time the window that was in use before the CreateWindow is used again.  end; begin with FontP^.Index[ord(ch)] do if width > 0 then begin Trik.f := F - 8 - ontP; RasterOp(RRpl, width, FontP^.height, xPos, yPos-FontP^.Base, SScreenW, SScreenP, Programming Examples - Fonts 08 Feb 82 6. Fonts. The definition of fonts is give Offset, Line*FontP^.height, SScreenW, MakePtr(Trik.seg, Trik.Ofst+#404, FontPtr)); n in the Screen module. Fonts currently can be variable width, but there is no kerning. A font starts with some global end; end; The #404 is the size of the introductory part of a font. Trik is used to create a pointer to the ac information: the height of the font in bits and the offset of the baseLine. Next is an array, which for each character htual bit pattern part of a font. - 9 - Programming Examplas the position and width of that character in the font. A width of zero means the character is not defined. After this es - Cursors 08 Feb 82 7. Cursors. Unfortuneately, the term "Cursor" is used in two wayarray is the actual bit pictures for the characters which are defined. Fonts can be created by using the FontEd programs in PERQ-land. First, it is the position where the next character will be placed on the screen. This "cursor" is usually si from the User Library available from the Sales department. To use a font, it must first be loaded into memory. See the segnified by an underline "_". The second "cursor" is the arrow or other picture that usually follows the pen or puck on t2; height := height + 5; if hasTitle then begin orgY := orgY - 15; height := height + 15; ction on reading files above. The Screen package allows you to change the font to one you have defined. First, you should de end; end; Calculate the inside of the window as follows: - 7 - Programmfine a new window so that you don't change the font for the default system. Now simply call the function SetFont passiing Examples - Windows 08 Feb 82 begin orgX := orgX + 2; width := width - 4; ng it a pointer to the top of the segment into which you read the font. If you wish to RasterOp a character (ch) using font FC terpreter microcode, you need only write this part once for a given boot letter. Note that you may add other micrtion the system hangs. - 6 - How to Make a New System ocode files to the boot file (as long as they do not overlap the standard microcode). } ____ __ 08 Feb 82 _______ _____ ____ _____ Rewrite Other Boot Files Once your new system is debug_ ___ ______ Test the New System You are now ready to boot your new system and test it. Hold down the boot key yged and working, you can use MakeBoot to rewrite the boot files associated with other boot letters. Before you rew_____________________________ Enter name of character set [Fix13.Kst]: { This writes the boot file containing the Paou selected ("z" in the example) and press the Boot button. If all goes well, your new system will announce itself. scal part of the system and special system segments such as the segment tables, the cursor, and the character seNote that when you try to run most programs, the loader informs you that they were linked under the old system. This meanst. Note that you may specify a character set which is different than the standard (Fix13.Kst). If you use a non-sta you must re-link them for your new system. It is a good idea to create another new directory to hold these run files. ndard character set, some programs (like the Editor) may not work well. } - 5 -  By putting the new run files in a directory by themselves, these run files will not get in your way when you are running the How to Make a New System 08 Feb 82 _____________________________________ Write an int old system. If you want, you can make a Login profile to add this directory to your search list when you log in undeerpreter boot file [Yes]: _______________________________________________________ Enter name of new micro boot file [Syster your new system. Once you are running the new system, you need to link the system utility programs. Set youm.100.z.MBoot]: ____________________________________________________________ Existing boot file to copy (type return to bur path to the new directory that you created to contain the run files. Push the directory containing the old .Seg files oild a new one): ________________________________________________ Use standard interpreter microcode files? [Yes]: __nto your search list, and then push the directory containing the new .Seg files. Now, type: Link ProgramName f_________________________ Interpreter microcode file: ETHER10 ___________________________ Interpreter microcode$file: or each utility program you wish to link. Re-compile any programs that import modules whose exports have changed.  { This writes the boot file containing the microcode which is the Q-machine interpreter. Unless you are changing the in If your system doesn't come up at all, you can look at the diagnostic display to determine where in system initializaC he tablet. This section discusses the latter form. The picture in the cursor can be set by the user. POS currently DefaultCursor which is the upper-left pointing arrow. The cursor can be used in a number of ways. If you want the cursor tuses a number of different pictures. The default arrow cursor, the "scroll" and "do-it" cursors for PopUp menus, the hand o follow the tablet and then read the tablet coordinates, use the cursor mode TrackCursor. IOCursorMode(TrackCursor); that moves down the side of the screen, and the Busy Bee are all examples of cursors. The program CursDesign from the Us Be sure to turn the tablet on using IOSetModeTablet(relCursor). If you want to explicitly set the position of the cursor,er Library can be used to create cursors. Once a picture has been created, it can be read into Memory from the file (se use cursor mode IndepCursor. To set the cursor position, use the function IOSetCursorPos(x,y); Note that if you sete above) and then copied into the Cursor. Each cursor is 56 bits wide and 64 bits tall which comes to 4 words wide and 6 the cursor position in Track mode, it will be overwritten almost immediately by the position of the tablet. You can st4 bits tall or exactly one block. Therefore a file with one cursor in it can be read in directly into the cursor buffer. Till read the tablet in IndepCur- sor mode if it has been turned on; the tablet position is simply not used to set the cursor phe definition of the cursor and all utility procedures for manipulating it are in IO_Others. var curs: CurPatPtr; bosition. - 10 - Programming Examples - Cursors 08 Feb 8egin New(0,4,curs); Fid := FSLookup(CursorFile, blks, bits); FSBlkRead(fid, 0, RECAST(curs, pDirBlk)); end; 2 To read the tablet position, use the function IOReadTablet. It returns the last x and y position read from the tab Note that the cursor buffer must be quad-word aligned (since a RasterOp is done from it by the system). To set a culet. If the pen or puck is away from the tablet, it may be an old point. It is not possible to tell if the tablet is sensirsor, use the function IOLoadCursor. It takes a CurPatPtr and two integers to tell it the x and y offsets in the cursorng the pen or puck. The buttons can be read using the variables TabSwitch, TabYellow, TabBlue, TabWhite, and TabG from where the cursor is positioned. Thus, for a "bull's eye" cursor where the center is the interesting point, the offsereen. TabSwitch tells if any button was pressed. For a puck, the other booleans tell which button it was. For a pen, the ts would be the offsets from the top left of the center. For a right pointing arrow, the offsets would describe the poin"colored" booleans will always be false. These booleans are true while the button is held down. The user is reqt of the arrow. The user then does not need to compensate when reading the cursor position. IO_Others exports the cursor uired to wait for a press-let up event: repeat until tabswitch; while tabswitch do; { read tablet position, or whaD 6 Test the New System 7 Rewrite Other Boot Files ible. The Reader's Comments card is distributed with this document to request users' critical evaluation to a - iii - ssist us in preparing future documentation. PERQ is a trademark of Three Rivers Computer Corporation.  - ii - Table of Contents  PERQ Pascal Extensions Miles Barel  1. Introduction 2. Declarations 2.1 Identifiers 2.2 Declaration Relaxation 2.3 Files 3.  Michael Kristofic January 7, 1982 PERQ PaNumbers 3.1 Whole Numbers 3.2 Floating Point Numbers 3.3 Type Coercion Intrinsics 3.4 Assignment Comscal is an upward-compatible extension of the standard programming language Pascal. Thispatibility 3.5 Mixed Mode Expressions 4. Extended Constants 4.1 Constant Expressions 4.2 Unsigned Ocrite the old boot files, you must be sure that some partition contains all files that make up the new system. This includes  document describes only the extensions to PASCAL. Copyright (C) 1982 files that you have not changed. If you fail to make a partition containing all source, binary, and run files, you run the Three Rivers Computer Corporation 720 Gross Street Pittsburgh, PA 15224 (412) 621-6250  risk of deleting portions of your new system when you delete the old system.  This document is not to be reproduced in any form or transmitted, in whole or in part, without the - 7 - How to Make a New System  prior written authorization of Three Rivers Computer Corporation. The information in this document is subjec 08 Feb 82 _____ __ ________ Table of Contents 1 The Scope of This Manual 1 Recomt to change without notice and should not be construed as a commitment by Three Rivers Computer Corporation. Themendations 2 Overview 2 Evaluate the Change You Intend to Make 3 Create a Directory, Edit, and Com Company assumes no responsibility for any errors that may appear in this document. Three Rivers Computer pile 3 Link the New System 4 Prepare the System Configuration File 5 Write a New Boot File Corporation will make every effort to keep customers apprised of all documentation changes as quickly as possD  The normal PASCAL character Read waits for an entire line to be typed before returning any characters. This allows edipe something. Do a SCurOn (from Screen) before requesting input and an SCurOff when done to make the underline prompt apting of the line (backspace, etc.) as described in the PERQ Introductory Manual. If you want to get the characters exactlypear. The HELP key and ^C are handled specially by the IO system. If the HELP key is hit, an exception is raised. If you when they are hit, you must call IOCRead in IO_Unit. The normal form for this call is If IOCRead(TransKey, c) = IOEIOC  do not handle this exception (called HelpKey, exported by System), "/HELP" will be put into the input stream as iftever } The Cursor functions determine how the cursor interacts with the picture on the screen under the cursor. Thethen { c is a valid character } where IOEIOC is a constant defined in the module IOErrors and c is a character variable.  cursor function also determines the background color. The even functions have zeroes in memory represented as white and onIf IOCRead returns some value other than IOEIOC, then no character has been hit. "Transkey" tells IO that you want thes as black (this is the default: white background with black characters). Odd functions have zeroes represented as black e standard ASCII interpretation of the character. If you use "KeyBoard" instead, you will get the actual 8 bits returned by  and ones as white. The functions are as follows (inverted means screen interpretation as just described): CTWhite: the keyboard. This code allows you to distinguish the special keys (INS, DEL, HELP, etc.) from the other keys and allo Screen picture is not shown, only cursor. CTCursorOnly: Same as CTWhite only inverted. CTBlackHole: This ws you to distinguish CONTROL-SHIFT-key from CONTROL-key. You will have to experiment to get the code for the desired kefunction doesn't work. CTInvBlackHole: This function doesn't work either. CTNormal: Ones in the cursor are blacky. There is no way to tell when a key has been let up. IOCRead does not write out the character typed. If you want i, zeros allow screen to show through. CTInvert: Same as CTNormal only inverted. CTCursCot printed, you should use Write(c). If you want to print all the special symbols in the font file (there is a picture asmpl: Ones in the cursor are XORed with screen, zeros allow screen to show through. CTInvCursCompsociated with every control character), you can set the high bit of the character. This prevents the Screen package from intel: Same as CTCursCompl only inverted. - 11 - rpreting the character as its special meaning if any. Thus, you could print the picture for RETURN by using Write(c Programming Examples - Reading Characters 08 Feb 82 8. Reading Characters from the Keyboard. hr(LOr(RETURN, #200))); IOCRead also does not turn on the input marker ("_") which shows the user that he is supposed to tyE 1 IMPORTS 13.2 EXPORTS 14. Exceptions 15. Dynamic Space Allocation and Deallocation 15.1 New  04 Feb 82 1. Introduction PERQ Pascal is an upward-compatible extension of the pr - iii - Table of Contents 15.2 Dispose 16. Sinogramming ______ ____ ______ ___ ______ language Pascal defined in PASCAL User Manual and Report [JWgle Precision Logical Operations 16.1 And 16.2 Inclusive Or 16.3 Not 16.4 Exclusive Or 16.5 Shift 74]. This ______ document describes only the extensions to 16.6 Rotate 17. Input/Output Intrinsics 17.1 REWRITE 17.2 RESET 17.3 READ/READLN 17.4 WRITE/ Pascal. Refer to PASCAL ____ ______ ___ ______ User Manual and Report for a fundamental definition of Pascal. This WRITELN 18. Miscellaneous Intrinsics 18.1 StartIO 18.2 Raster-Op 18.3 WordSize 18.4 MakePtr 18.5  ______ ____ ______ ___ ______ document uses the BNF notation used in PASCAL User Manual and R MakeVRD 18.6 InLineByte 18.7 InLineWord 18.8 InLineAWord 18.9 LoadExpr 18.10 LoadAdr 18.11 eport. The existing BNF is not repeated but is used in the syntax definition of the extensions. The semantics are defined in StorExpr 18.12 Float 18.13 Stretch 18.14 Shrink 19. Command Line and Compiler Switches 19.1 Commandformally. These extensions are designed to support the construction of large systems programs. A major attempt ha Line 19.2 Compiler Switches 19.2.1 File Inclusion 19.2.2 List Switch 19.2.3 Range Checking 19.2.4 s been made to keep the goals of Pascal intact. In particular, attention is directed at simplicity, efficient run-t Quiet Switch 19.2.5 Symbols Switch 19.2.6 Automatic RESET/REWRITE 19.2.7 Procedure/Function Names 19.2.8 ime implementation, efficient compilation, language security, upward-compatibility, and compile-time checking. These tal Whole Numbers 5. Type Compatibility 5.1 Type Coercion - RECAST 6. Extended Case Statement 7. Con Version Switch 19.2.9 Comment Switch 19.2.10 Message Switch 19.2.11 Conditional Compilation 19.2.12 Errortrol Structures 7.1 EXIT Statement 8. Sets 9. Record Comparisons 10. Strings 10.1 Length Functifile Switch 19.2.13 Help Switch 20. Quirks and Other Oddities - iv - on 11. Generic Types 11.1 Generic Pointers 11.2 Generic Files 12. Procedure/Function Parameter Types 12 Table of Contents 21. References Index .1 Parameter Lists 12.2 Function Result Type 12.3 Procedures and Functions as Parameters 13. Modules 13. - v - PERQ Pascal Extensions E  won't abort program} goto 1; {top of command loop} end; (IOKeyClear comes from IO_Others. do {handle all the switches} begin ConvUpper(switches^.switch); i := UniqueCmdIndex(switches^.switch) Another special character to know about is ^S. This character prevents any further output to the screen until a ^Q is , switchAr, NumSwitches); case i of 1 : 2 : otherwise: StdError(ErBadSwitch, switches^.switch, true);  - 13 -  end; switches := switches^.next; end; if (outs^.name <> '') or (outs^.next <> NIL) then S Programming Examples - CmdParse and PopCmdParse 08 Feb 82 9. CmdParse and PopCmdParse. CmdParse and PoptdError(ErNoOutFile, '', true); if ins^.next <> NIL then StdError(ErOneInput, '', true); CmdParse export a number of procedures that help read and parse strings of commands and arguments. Procedures exist for h if ins^.name = '' then begin Write(': '); ReadLn(s); ok := ParseString typed. If you do handle this exception, you can put chr(7) into the input stream: the code for HELP. When ^C is typed,andling command files (which may be nested), for parsing a string containing inputs, outputs and switches into its compone the exception CtlC is raised (also defined in System). If not caught, nothing special is done until the second ^C is hit nts, and for getting a command index from a string or a PopUp menu. The modules CmdParse and PopCmdParse document how when CtlCAbort is raised. This causes the program to exit. Note that the ^C's are put into the input stream. ^SHIFT-C c each of the procedures work. This section provides an example of how to use the parsing procedures in CmdParse. var ins, auses a separate exception to be raised. If the user wants one ^C to do something special in a program (for example, abort outs: pArgRec; switches: pSwitchRec; switchAr: CmdArray; err: String; ok, leave: boolean; c: Char;  type-out and go to top level as in FLOPPY), put the following Handler at the top level: Handler CtlC; begin  s: CString; isSwitch: boolean; i: integer; begin c := NextString(s, is WriteLn('^c'); IOKeyClear; {remove the ^C from input stream} - Switch); {remove ""} if (c<>' ') and (c<>CCR) then StdError(ErIllCharAfter, '', true); ok := Par12 - Programming Examples - Reading Characters 08 Feb 82 CtrlCPending := false; {so next ^CseCmdLine(ins, outs, switches, err); repeat if not ok then StdError(ErAnyError, err, true); while switches <> NILF ng Extensions to the Pascal Language [UCSD79] and, most notably, Pascal* [P*]. s PERQ Pascal permits the use of files as the component type of arrays, pointers and record fields.  - 1 - PERQ Pascal Extensions 04 F - 2 - PERQ Pascal Extensions 04 Feb 82 3. Numbers eb 82 2. Declarations You must declare all data items in a Pascal program. To declare a data item, specify the id 3.1 Whole Numbers Single precision whole numbers are of the predefined type INTEGER. They occupy 16 bientifier and then what it represents. 2.1 Identifiers PERQ Pascal permits the inclusion of the underscore charactets (15 bits and a sign bit) and range in value from -32768 to +32767. Whole numbers of the predefined type LONG are dour "_" as a significant character in identifiers. 2.2 Declaration Relaxation The order of declaration for labels, ble precision. They occupy 32 bits (31 bits and a sign bit) and range in value from -2147483648 to +2147483647. Arithmeticconstants, types, variables, procedures and functions has been relaxed. These declaration sections may occur in any order a operations and comparisons are defined for both single and double precision whole numbers. See the section "Extended Cond any number of times. It is required that an identifier be declared before it is used. Two exceptions exist to this rule:nstants" for a discussion of single and double precision constants. 3.2 Floating Point Numbers PERQ Pascal float 1) Pointer types may be forward referenced as long as the declaration occurs within the same type-deing point numbers (type REAL) occupy 32 bits and conform to the IEEE floating point format. See [FP80]. Positive valuesfinition-part, and 2)Procedures and functions may be predeclared with a forward declaration. T range from approximately 1.1754945e-38 to 3.402823e+38 and negative values range from approximately -1.1754945ehe new syntax for the declaration section is: ::= ::= | ::= | |  Intrinsics The STRETCH intrinsic can be used to explicitly convert a single precision whole number into a double