PROJECT: MAC REPLACEMENT PROJECT DOC. TYPE: TECHNICAL NOTE TITLE: Illegal Instruction Code Utility Tasks ISF and RMF SUBJECT: New Tasks on [1,54] GROUP: SYSTEM EXTENSIONS AUTHOR: D.B.Curtis DOC NO.: 67 DATE: 25-JUN-79 14:20 FILE: ILLINS.RNO MODIFIED: 19 JUL 79 15:19 PAGE 2 1.0 INTRODUCTION This document is a result of document #34. This document and document #70 describe the use of the illegal instruction executive functions. 1.1 Objectives This document describes the use and structure of the ISF and RMF tasks. These tasks exist to insert and remove illegal instruction code from the system pool space. The document is separated into two sections: 1. User Information 2. Maintenance Information 1.2 Discussion The discussion of these tasks is in document #34. 2.0 USER INFORMATION This section describes how to use the ISF and RMF tasks. In general, these tasks are not to be used! They exist to simplify the loading and unloading of the illegal instruction code into and out of the system pool. Typically, the ISF task is run, and the system saved. This allows the illegal instruction facility to exist upon startup. Therefore, you must run these tasks at a privileged terminal. Usually, the tasks will be run only by the system maintenance people. 2.1 ISF - Insert Function This task inserts code into the system pool space. The code inserted must be position independent (PIC) and stored on disk as a sharable PIC library. This sharable library task image must be named "ILLINS.TSK". ISF first looks for "SY:ILLINS.TSK". If not found, ISF will then look for "LB:[1,1]ILLINS.TSK". If neither files exist, an error message is returned. PAGE 3 Once the file is found, space is reserved in the system pool and the code is loaded into the reserved space. Then the illegal instruction trap vector is connected to this code. If XDT exists, it is modified so that it does not overwrite the illegal instruction vector. Even if 2 concurrent ISF tasks are running, only one will load code. The other task will exit with an error. However, there does exist a very small window where illegal instructions from other tasks will not generate an illegal instruction trap. 2.1.1 ISF Errors - ISF may produce the following errors: 1. TERMINAL NOT PRIVILEGED 2. ATTEMPT TO EXCEED THE 4K LIMIT This error message occurs if the code that is being loaded into the pool is larger then 4K words. Since pool space is a valuable resource some limit needed to be imposed. An arbitrary 4K word limit was chosen. 3. UNABLE TO FIND ENOUGH POOL SPACE The limit was not exceeded, but the pool did not have enough contiguous free space to load the code. 4. READ ERROR The read of code from the file to the pool failed. 5. ILLEGAL INSTRUCTION CODE ALREADY INSTALLED 6. MISMATCHED COMMON AND FILE NAME The file name and common name must match. This match is performed by the "PAR" taskbuild option. 7. NOT A SHARABLE COMMON TASK IMAGE 8. PROGRAMMER ERROR Something is wrong with the sharable task image. See an expert. 9. COMMON FILE ERROR NUMBER ###### Some file error. At next version, the #s will be replaced by PAGE 4 the actual file error number. 2.2 RMF Task This task resets the illegal instruction trap vector and releases the space to the system pool. If XDT exists, the ISF XDT modification is reset. 2.2.1 RMF Errors - RMF will generate the following errors: 1. TERMINAL NOT PRIVILEGED 2. ILLEGAL INSTRUCTION CODE NOT INSTALLED 3.0 MAINTENANCE INFORMATION This section consists of the extracted task headers and other explanatory text. This information is: 1. ISF File Header 2. ISF Task Header 3. RMF File Header 4. RMF Task Header PAGE 5 3.1 ISF FILE HEADER FILE DESCRIPTION THIS TASK INSERTS EXECUTIVE FUNCTIONS INTO THE POOL SPACE THE EXECUTIVE FUNCTIONS ARE INVOKED BY THE USE OF ILLEGAL INSTRUCTIONS. THE TASK RMF REMOVES FUNCTIONS THE CODE THAT IS INSERTED EXISTS IN A SHARABLE LIBRARY TASK IMAGE THE FOLLOWING RESTRICTIONS APPLY: 1) THE CODE MUST BE PIC 2) THE CODE MUST BE BUILT IN THE SAME MANNER AS A SHARABLE LIBRARY AND CANNOT BE LARGER THEN 4K WORDS 3) THE LIBRARY IS NAMED ILLINS.TSK: THE CURRENT UIC IS CHECKED AND THEN THE LB:[1,1] AREA FOR THIS FILE 4) IF CODE IS ALREADY ATTACHED TO THIS FUNCTION, NOTHING BUT AN ERROR MESSAGE OCCURS. THE CODE MUST BE FIRST REMOVED BY RUNNING RMF. ASSEMBLE USING: =[200,200]RSXMC/PA:1,[X,Y]ILLINS PAGE 6 3.2 ISF TASK HEADER INPUTS SIDE EFFECTS: MODIFIED EXTERNALS NONE OTHER SIDE EFFECTS CODE IS LOADED INTO THE DYNAMIC POOL, AND LINKED TO THE ILLEGAL INSTRUCTION VECTOR (ILV) STANDARD REGISTER USAGE THIS TASK DOES THE FOLLOWING: BEGIN IF NOT PRIVILEGED THEN ERROR1; GET-LIBRARY-INFORMATION(,,,); IF STATUS NE OK THEN ERROR-ROUTINE; IF REQUIRED SPACE GT 4*1024 THEN ERROR2; SWITCH STACK ALLOCATE SPACE SWITCH TO USER STATE IF NO SPACE THEN ERROR3; SWITCH STACK IF ILL-CODE ALREADY LOADED ERROR5 FILL HEADER SWITCH TO USER READ CODE INTO SPACE; IF ERROR THEN ERROR4; IF XDT THEN FIX XDT; LINK ILLEGAL-INSTRUCTION-VECTOR TO SPACE; END THE INFORMATION IN THE POOL POINTED TO BY THE ILLEGAL INSTRUCTION TRAP VECTER IS OF THE FORM: --------------------------- | ILL (IN RAD50) | |-------------------------| | NUMBER OF BYTES IN AREA | |-------------------------| | ORIGINAL CONTENTS OF ILV| |-------------------------| ILV> | NOP | --------------------------- PAGE 7 3.3 RMF FILE HEADER FILE DESCRIPTION THIS TASK REMOVES THE EXECUTIVE FUNCTIONS INSERTED INTO THE POOL AND CONNECTED TO THE ILLEGAL INSTRUCTION INTERRUPT BY THE ISF TASK. THE POOL AREA IS DEALLOCATED, THE ILLEGAL INSTRUCTION INTERRUPT IS RESET; AND,IF XDT EXISTS, THE MODIFICATION TO XDT IS REMOVED. ASSEMBLE USING: =[200,200]RSXMC/PA:1,[X,Y]ILLREM PAGE 8 3.4 RMF TASK HEADER **-START-MAIN ROUTINE INPUTS: NONE OUTPUTS: NONE SIDE EFFECTS: MODIFIED EXTERNALS XDT VECTOR RESET TABLE IS RESTORED TO ORIGINAL STATE OTHER SIDE EFFECTS THE ILLEGAL INSTRUCTION VECTOR IS RESET TO ITS ORIGINAL VALUE AND THE POOL SPACE IS DEALLOCATED FROM THE SYSTEM POOL STANDARD REGISTER USAGE THIS TASK DOES THE FOLLOWING: BEGIN IF NON-PRIVILEGED TASK THEN ERROR1; IF ILL FUNCTIONS NOT INSTALLED THEN ERROR2; SWITCH STACKS; RESET ILLEGAL INSTRUCTION VECTOR RESET XDT; DEALLOCATE POOL BUFFER SWITCH TO USER STACK; END THE INFORMATION POINTED TO BY THE ILLEGAL INSTRUCTION VECTOR LOOKS LIKE: --------------------------- | ILL (IN RAD50) | |-------------------------| | NUMBER OF BYTES IN AREA | |-------------------------| | ORIGINAL CONTENTS OF ILV| |-------------------------| ILV> | NOP | --------------------------- PAGE 9 4.0 GLOSSARY