MSX (MULTI SYSTEM EXECUTIVE) MULTI-TASKER MSX IS A MULTITASKING SCHEME THAT RUNS USING DOS OR RSX IN CORE BUT DOING SOME OF ITS OWN I/O. IT LOOKS LIKE A MAIN PROGRAM TO DOS OR RSX AND IS RUN LIKE A MAIN PROGRAM. HOWEVER, ONCE STARTED IT HANDLES THINGS MORE OR LESS INDEPENDENTLY OF ANY UNDERLYING OPERATING SYSTEM. IN PARTICULAR, MSX CONTROLS STACK ALLOCATION. TASKS ARE DEFINED BY A TASK TABLE (ALL ARE CORE-RESIDENT OR THE USER DOES HIS OWN SWAPPING, POSSIBLY VIA TKB'S OVERLAY STRUCTURES)WHICH TELLS MSX WHAT STATE TASKS ARE IN. SYSTEM DIRECTIVES (TRAP CALLS) TELL MSX WHAT TO DO. THE MSX SYSTEM OCCUPIES 12-14K OF MEMORY IN ITS RSX VERSION, PLUS WHATEVER IS NEEDED FOR TASK TABLES. REMAINING SPACE IS THE VIRTUAL ADDRESS SPACE AVAILABLE PER TASK. THE STAND ALONE SYSTEM'S CORE NEEDS ARE COMPARABLE TO THIS; HOWEVER, SINCE STAND-ALONE MSX IS ALSO A MAPPED SYSTEM (WHICH COULD BE CHANGED VIA SOME ADDITIONAL ASSEMBLY CONDITIONALS), THE STAND-ALONE SYSTEM LEAVES 32K FOR EACH TASK, IN USER SPACE, AND HAS ROOM IN THE TCB TO STORE DATA PARS TO PERMIT I/D SPACE SEPARATION IF DESIRED IN USER MODE. STAND-ALONE MSX HAS A VERSION OF DDT NORMALLY AVAILABLE FOR DEBUGGING AT SYSTEM LEVEL, ENTERED WHENEVER ONE TYPES CONTROL-T TO THE CONSOLE HANDLER ON INPUT, AND ON BREAKPOINTS. THIS MAY BE REMOVED ONCE THE SYSTEM IS WORKING. EVERY CPU IN MSX CONTAINS A COPY OF MSX WITH INITIALLY IDENTICAL TASK TABLES. WHERE NO DYNAMIC LOADING IS PRESENT TASKS ARE ALSO PRESENT; OTHERWISE, A NAMELIST IN MXSUBS IS PRESENT GIVING TASK NAMES AND DISK LOCATIONS, AND SOME "EMPTY" TASK CONTROL BLOCKS (TASK NAME = 177775 OCTAL) ARE PRESENT IN EACH SYSTEM. THE SYSTEM TASK LIST (STL) AND EACH TASK CONTROL BLOCK (TCB) THAT IS AN ENTRY IN THE STL, ARE THE KEY DATA STRUCTURES FOR MSX TASKS. THESE ARE SET UP VIA THE TCB MACRO DEFINED IN MXSTLS.MAC. FILE FUNCTION MXSCNS MAIN PROGRAM AND TASK SCANNER ALSO MOST OF INPUT MESSAGE HANDLER FROM OTHER CPU'S AND CLOCK SERVICES. MXTRPS TRAP HANDLER FOR MSX DIRECTIVES MXTBLS TABLES; CONTROL TABLE; INTERRUPT VECTOR SAVE TABLE; FREE SPACE TABLE; LOGICAL UNIT TABLE MXCODS INTERRUPT POSTING; INTERRUPT VECTOR SAVE/RESTORE, IOT HANDLER, REG. SAVE/RESTORE MXIOHT BASIC, REQUIRED QTRAN PROCESSOR IF ANY QTRAN I/O IS DONE. RE-ENTRANT. MTIOHT MAGTAPE HANDLER TASK (DOS) KBIOHT KEYBOARD (CONSOLE) I/O HANDLER. (DL11) DTIOHT DT DECTAPE HANDLER (EXAMPLE OF 18 BIT DMA DEVICE HANDLER) VTIOHT CRIOHT DFIOHT LPIOHT LP LINEPRINTER HANDLER I/O HANDLER TASKS FOR QTRAN TO VARIOUS DEVICES. MXKBDRV STAND ALONE KEYBOARD DRIVER MXLPDRV STAND ALONE LINEPRINTER DRIVER MXDTDRV STAND ALONE DECTAPE DRIVER MXSTLS SYSTEM TASK LIST TCB DEFINER MACRO AND STL ITSELF ALSO SOME SYSTEMWIDE TABLES AND THE CPU NUMBER OF THE SYSTEM (MX.CPU). MXSUBS COMMON SUBROUTINES FOR MSX SUPPORT. ALSO LOADER SUPPORT AND MLS SUPPORT. MXCONN INTERPROCESSOR CONNECTION PRIMITIVES THAT MUST BE CUSTOM SUPPLIED FOR ANY GIVEN SYSTEM ARCHITECTURE. THIS MODULE MUST BE REDONE FOR EVERY SYSTEM CONNECTION; A VERSION PRESENTLY DONE IS FOR RSX MODE WITH INTER CPU COMMUNICATION EMULATING A GLOBAL BUS VIA A COMMON MEMORY AREA. MXMAP ROUTINE TO SET UP INITIAL MAPPING MXWDMG APR REMAPPING CODE FOR RSX BASED MSX VERSIONS THAT DO MEMORY MAPPING. MXINTS RSX BASED MSX INTERRUPT INTERFACING CODE EXAMPLE. FOR RSX VERSIONS, MXIOHT AND ALL IOHT TASKS ARE ABSENT. CODE IN MXTRAP HANDLES I/O VIA THE QIO$ DIRECTIVE, WITH MULTIPLE REQUESTS PER LUN QUEUED IN THE SYSTEM. IT WILL NORMALLY BE TRUE THAT TASKS WILL QUEUE THEIR REQUESTS ON INPUT AND A SPECIAL TASK WITHIN MSX WILL HANDLE I/O TO DISKS, TAPES, ETC., BUT THE QTRAN DIRECTIVE WILL ENSURE THAT ALL I/O SEEN BY RSX IS QUEUED EVEN IF MULTIPLE REQUESTS ARE OUTSTANDING BY POSSIBLY MORE THAN ONE TASK. THE STAND-ALONE VERSION OF MSX SUPPORTS DEVICES KB (INPUT AND OUTPUT, FULL-DUPLEX), LP, AND DT. THE VERSION OF 8-JUN-1979 INCLUDES 18-BIT ADDRESSING SUPPORT FOR THESE. 22-BIT SUPPORT IS EASIEST IN THIS CASE WITH STATIC ALLOCATION OF UMR'S (E.G. ON 11/70 OR 11/44). MEMORY MAPS ARE AS FOLLOWS: FOR THE DOS-11 VERSION: TOP OF MEMORY TASKN .......................... TASN N-1 .......................... . . . .......................... TASK 2 .......................... TASK 1 .......................... MSX SCHEDULER .......................... DOS DRIVERS, DDB'S, ETC. .......................... DOS-11 0 .......................... FOR THE RSX VERSION: ............................................................. APR 7 I/O PAGE DEVICE COMMON (R/W ACCESS TO ALL OF I/O PAGE) ............................................................. APR 6 COMMON TASKS (PAGES OF COMMON ROUTINES) ............................................................. APR 5 DATA AREAS (EACH TASK HAS ITS OWN MAPPING) ............................................................. APR 4 DATA AREAS (EACH TASK HAS ITS OWN MAPPING) ............................................................. APR 0 MSX SCHEDULER, TASK TABLES, MAPPING CONTROL ROUTINES TO WHATEVER IS NEEDED. MSX REMAPS ALL APRS FROM 1 THRU 6 PER TASK, BUT NOT ALL ACTUALLY CHANGE PER TASK. ............................................................. FOR THE STAND-ALONE, DUAL MODE VERSION: KERNEL SPACE ............................................................. APR 7 I/O PAGE ............................................................. APR 6 THRU APR 0 DDT, MSX SCHEDULER, TABLES, DRIVERS ............................................................. USER SPACE ............................................................. APR 7 INITIALLY I/O PAGE ............................................................. APR 6 THROUGH DATA/PROGRAM AREAS APR 1 ............................................................. APR 0 MSX TASK ENTRY POINT AREAS (APR 0 ALWAYS SET UP SAME AT TASK STARTUP) ............................................................. NOTE THAT IN USER SPACE, PREVIOUS MODE IS ALWAYS KERNEL, AND A TASK'S MAPPING IS PROPAGATED AS LONG AS IT RUNS (AND TENDS IN THE STANDALONE VERSION TO REMAIN PROPAGATED EVEN AFTER EXIT AND RE-REQUEST) IN USER MODE, MSX WILL NORMALLY SET UP ALL APRS TO INITIAL VALUES SPECIFIED IN THE TCB MACRO OR BY MXMAP. SPECIAL ENTRIES INTO MXTRAP ALLOW FOR A TASK TO REQUEST ANOTHER TASK DIRECTLY BY NUMBER OR NAME, OR TO EXIT, WITHOUT GOING THROUGH THE FULL TRAP DECODING LOGIC. IF THE TASK IS SPECIFIED BY NUMBER, MOST OF THE LOOKUP OVERHEAD MAY BE BYPASSED ON REQUEST (OR RESUME). TO DO RSX CALLS, THE TRAP INSTRUCTION IS SLOW SINCE IT IS AN SST. HENCE, SUBROUTINE ENTRIES ARE PROVIDED INSTEAD. THE TRAP SEQUENCES WILL WORK A LA DOS VERSION, BUT THE SUBROUTINE CALLS ARE FASTER. THERE ARE 2 SUBSTITUTE SEQUENCES. THE FIRST IS (PUSH ARGUMENTS FOR CALL ON STACK) JSR PC,MX.SVC ;CALL TRAP SERVICE .WORD TRAPCODE ;CODES ARE 0,1,2,3,4,5,6,7,10 THE SECOND IS SLIGHTLY FASTER: (PUSH ARGUMENTS FOR CALL ON STACK) JSR PC,MX.SV2 ;CALL TRAP SEQ. WITH DOUBLED CODES .WORD TRAPCODE+TRAPCODE ; THUS, 0,2,4,6,8,10,12,14,16 FOR REQUEST AND EXIT, THERE ARE IN ADDITION THE FOLLOWING ALTERNATIVES, FOR SPEED... REQUEST (REQPRI): (PUSH REQUEST ARGS ON STACK) CLR -(SP) ;FAKE A PSW JSR PC,MX.PRR ;PRIORITY REQUEST EXIT MOV #EV,-(SP) ;PUSH A 0 OR EV ADDR CLR -(SP) ;FAKE PSW JSR PC,MX.PRX ;SCRAM FASTER TASK TABLE DEFINITION MSX FINDS THE TASK TABLE, WHICH TELLS OF USER TASKS, STATES, AND PRIORITIES, BY THE GLOBAL "MX.TBL". THIS MUST BE THE FIRST WORD OF THE TABLE AND BE DECLARED GLOBAL. ONE EASY WAY TO DO SO IS TO CODE THUS: .TITLE MSXTBL .PSECT MX.TBL,D,GBL,RW .GLOBL MX.TBL MX.TBL: (ENTRIES.) .GLOBL MX.TBE MX.TBE: .WORD 0 ;TERMINATOR FOR TABLE. REQUIRED. EACH ENTRY IS 16 (32 IN STAND-ALONE) WORDS LONG, LAID OUT AS FOLLOWS: ENTRY: .RAD50 /NAM/ ;TASK NAME .BYTE PRI ;PRIORITY. (IGNORED NOW; PRIORITY IS DETERMINED BY TABLE POSITION, HIGH PRIORITY TASKS BEING THE FIRST ONES.) .BYTE STAT ;STATUS OF TASK. CURRENT STATE (0-4) IS SET ;BY SYSTEM HERE. INITIALLY VALUES MUST ;BE SET BY USER FOR INITIAL TASK ;CONTROL. .WORD BEGINADDRESS ;TASK START ADDRESS .WORD ISP ;INITIAL STACK POINTER. (MUST BE A POSITION NOT ;USED ON STACK BY TASK. MSX USES TOP WORD, ;THOUGH IN NORMAL DOS OPERATIONS IT WOULD ;NOT BE USED.) .WORD DSP ;DYNAMIC STACK POINTER. (SP WHEN TASK IS NOT ;RUNNING AND NOT IN STATE 0) .WORD CSP ;CHECK STACK POINTER. SUPPOSED TO LET MSX CHECK ;INDIVIDUAL STACK OVERFLOW. CURRENTLY UNUSED. .WORD 0 ;ADDRESS IN MSX OF TABLE OF INITIAL APRS, F.P. ;REGS, AND TASK TRAP ADDRESSES. .WORD EVA ;EVENT VARIABLE ADDR FOR WAITS AND ORWAITS. (AN ADDITIONAL 24 WORDS FOR A TOTAL OF 32 ARE INCLUDED IN THE STANDALONE MSX TABLES FOR REGISTER, PC, AND APR SAVES) ;THE MSX TABLE CONTAINS 8 WORDS FOR REGISTERS, PC, AND PS ;FOR STANDALONE VERSIONS (IN RSX VERSIONS, THIS IS IN THE ;STACK), AND 8 FOR APRS. IN ADDITION, 8 WORDS ARE USED ;TO POINT TO ADDITIONAL TABLES USED TO CONTROL THE TASK. ;SEE MXSTLS FOR DESCRIPTION. NAME, STAT,BEGINADDRESS, AND ISP SHOULD BE SET BY THE USER. STAT IS NORMALLY 0 IF TASKS ARE TO BE STARTED BY REQUEST DIRECTIVES OR 4 FOR TASKS WHICH SHOULD BE GIVEN CONTROL UPON STARTUP. AT LEAST 1 TASK, THE INITIALIZER, SHOULD BE SET AT STATE 4. DON'T FORGET TO PUT A 0 AT THE END OF THE TABLE AFTER THE LAST ENTRY TO MARK THE END OF THE TABLE. THE GLOBAL SYMBOL MX.TBE SHOULD BE DEFINED AFTER THE LAST STL ENTRY, AND THE SYMBOL MX.TBS IS THE NUMBER OF BYTES IN A TASK TABLE ENTRY (IT MUST BE A POWER OF 2) AND MX.CNT IS THE SHIFT COUNT FOR CONVERTING A NUMBER (0,1,2,3,4,5,...) INTO AN OFFSET FROM MX.TBL (FOR USE TO SPECIFY REQUESTING TASKS BY NUMBER STARTING AT 0 RATHER THAN BY RAD50 NAME). IF TASKS ARE TO BE MAPPED IN VIA APR 1 IN A MAPPED MSX, THE INITIAL CONTENTS OF APR 1 SHOULD BE SPECIFIED. IT MAY BE ASSUMED FOR THE RSX VERSIONS THAT MSX RESIDES AT PHYSICAL ZERO IN MEMORY; THE APR 1 VALUE WILL BE RELOCATED TO CORRESPOND TO THE ACTUAL LOCATION AT RUNTIME. IF BIT 7 (THE 200 BIT) IS SET IN THE TASK STATUS AT ANY TIME, THE MSX SCANNER WILL CONSIDER THE TASK DISABLED AND WILL BYPASS IT IN ANY SCAN FOR WORK. THIS ALLOWS A TASK TO SUSPEND ANOTHER TASK AS OF THE NEXT TIME THE OTHER TASK ISSUES A MSX DIRECTIVE. CLEARING THIS BIT AND ISSUING A DECLARE (SEE BELOW) WILL ALLOW THE TASK TO RESTART IF IT IS THE HIGHEST PRIORITY TASK ELIGIBLE TO RUN. IN ORDER TO PROVIDE MAXIMUM SPEED TRANSFERS, MSX SYSTEM TRANSFER PATHS ARE KEPT SHORT AND ORDERLY. SOME CARE IS NEEDED IN THE SCHEDULER IF CERTAIN VALIDITY TESTS ARE CONDITIONALLY EXCLUDED FROM ASSEMBLY, BUT THE MSX EXECUTIVE IS DESIGNED TO ALLOW EFFICIENT USE OF THE CPU BY CO-OPERATING TASKS. IT DIFFERS FROM RSX IN THIS PHILOSOPHY; WHEREAS RSX IS A MULTI-USER, MULTI-TASK SYSTEM, MSX IS A SINGLE-USER, MULTI-TASK SCHEDULER. AS SUCH, IT ASSUMES SOME CO-OPERATION AMONG ITS TASKS. IN PARTICULAR, MSX MAY BE ASSEMBLED TO ALLOW REQUESTS OF ALREADY ACTIVE TASKS (EFFECTIVELY A RESUME OR A NO-OP), AND ITS TASK TABLES MAY BE ALTERED BY TASKS. THIS IS AN EXTERMELY EFFICIENT WAY TO HANDLE SCHEDULING, AS TASKS MAY BE ENABLED TO RUN BY SETTING THEIR STATUSES UP TO RUNNING AND THEN REQUESTING THE FIRST. THE NORMAL PARTIAL SCAN WILL THEN RUN THEM SEQUENTIALLY. TASKS MAY SHARE A STACK IF THEY NEVER CAN RUN SIMULTANEOUSLY. TO ALLOW FAST I/O RESPONSE, MSX HAS A MECHANISM FOR RSX THAT PERMITS A TASK TO BE REQUESTED WHEN THE I/O COMPLETES. THIS MEANS THE NORMAL WAITING FOR EVENT VARIABLE MECHANISM MAY BE BYPASSED AND CONTROL TRANSFERRED DIRECTLY TO THE DESIRED ROUTINE ON I/O DONE. THIS IS NOT ESPECIALLY DESIRABLE MUCH OF THE TIME, SO STAND-ALONE MSX ALLOWS THE WORD BEFORE THE EVENT VARIABLE TO CONTAIN AN "INTERRUPT" ADDRESS FOR USE ON I/O COMPLETION. THIS WILL CAUSE A SIMULATED INTERRUPT ON I/O DONE. HOWEVER, NOTE THAT THIS WILL NOT OCCUR IF A LIBRARY HAS BEEN ENTERED AND THE "INTERRUPTS" MAY BE LOST IN THAT CASE. THIS IS DONE FOR SECURITY REASONS. MSX MAY BE ASSEMBLED TO CHECK PRIORITY LEVELS AND START A SCAN WITH THE HIGHEST PRIORITY TASK THAT HAS BEEN REQUESTED BUT NOT EXITED. WHERE THE TASK LIST IS VERY LONG, THIS CAN SAVE TIME AS 16 TASKS MAY BE TESTED AT ONCE AND SKIPPED IF NONE ARE ACTIVE. THIS FEATURE IS NOT NORMALLY SELECTED SINCE THE DYNAMIC PRIORITY SUPPORTED BY THE MSX AUXILIARY QUEUE CONFLICTS WITH IT. THE NORMAL I/O SCHEME UNDER MSX IS THE QTRAN DIRECTIVE, WHICH TRANSLATES INTO A QIO$ UNDER RSX. IF THE TASK IS CHECKPOINTABLE, RSX WILL SUSPEND THE TASK IF MORE THAN 1 I/O REQUEST IS PENDING ON A LUN. MSX WILL OVERCOME THIS PROBLEM BY QUEUING I/O REQUESTS INTERNALLY AND ISSUING THEM TO RSX 1 AT A TIME (PER LUN). IF THE TASK IS NON-CHECKPOINTABLE (AS IT MUST BE TO DO MEMORY MANAGEMENT), RSX WILL NOT SUSPEND THE TASK, AND THE INTERNAL QUEUING MAY BE EXCLUDED BY CONDITIONAL ASSEMBLY. INTERNAL QUEUING MECHANISMS FOR THE STAND-ALONE VERSION ARE SIMILAR IN CONCEPT, BUT NOT IN DETAIL. MSX ALLOWS MEMORY MAPPING BY CALLING SUBROUTINES TO ALTER APR'S (PARS MAY BE ALTERED, BUT PDR'S ARE ASSUMED FIXED AND WILL NORMALLY MAP 4K R/W REGIONS). UNDER RSX, IT DOES THIS BY CHANGING THE PHYSICAL HARDWARE AND THE RSX MAPPING DATA TOGETHER (EXTRACTING INFORMATION FROM RSX AT STARTUP ON THE LOCATIONS TO ALTER) IN AN INSTRUCTION SEQUENCE OF 5-15 INSTRUCTIONS (DEPENDING ON THE OPTIONS SELECTED FOR CHOOSING THE NEW ADDRESS). THE MSX TASKS RUNNING UNDER RSX11M MAY OF COURSE ISSUE RSX DIRECTIVES, BUT THE INTENT OF A QTRAN DIRECTIVE IS TO ENSURE THAT IF IT IS NECESSARY TO BYPASS SOME RSX CODE TO SPEED UP I/O TO RSX DEVICES, THE INTERFACE TO THE USER WILL BE TRANSPARENT. THE CURRENT IMPLEMENTATION PROVIDES 7 LOGICAL UNITS THAT CORRESPOND TO 7 FILES ON THE DISK IN ADDITION TO LUNS FOR CONSOLE, TAPE, ETC. THESE LOGICAL UNITS (LUNS) ARE ACCESSED BY IO.RVB OR IO.WVB TO READ AND WRITE VIRTUAL BLOCKS OF THE FILES; TO THE MSX TASKS, THEY MAY APPEAR TO BE ENTIRE VOLUMES. HOWEVER, THEY WILL BE ON PROTECTED DISK AREAS AND SAFE FROM OTHER RSX TASKS. THIS MECHANISM ALLOWS GREAT FLEXIBILITY IN HIGH-SPEED I/O OPERATIONS WITHOUT EXCESSIVE DANGER TO THE REST OF THE HOST RSX SYSTEM. UNDER THE STAND-ALONE VERSION, EACH LUN WOULD BE A PHYSICAL VOLUME. THESE FILES MAY BE INCREASED IN NUMBER, BUT THE METHOD IS CHOSEN TO AVOID EXCESSIVE DELAY FROM FILES-11 PROCESSING THAT CAN OCCUR DUE TO OPEN AND CLOSE TIMES. IT SHOULD BE NOTED THAT THE USE OF RSX LUNS FOR FILES IS CONDITIONALLY ASSEMBLED IN MSX AND PROBABLY WILL NOT BE USED SINCE OPEN/CLOSE LOGIC IN RSX11M BRINGS IN ABOUT 2K OF CODE IN ADDITION TO THE CONTROL BLOCKS USED. THEREFORE, QTRAN WILL SIMPLY ISSUE THE RSX CALLS TO QIO$ AND HANDLE COMPLETION AST'S WITH NO FURTHER ADO UNLESS AN EXTRA APR CAN BE SPARED FOR THE FILE HANDLING. FILES MAY BE HANDLED VIA ANOTHER TASK MAPPING TO THE SAME DATA REGION AS MSX. MSX IS SUPPLIED IN SOURCE FORM TO ALL WHO HAVE IT AND MAY BE EASILY TAILORED TO A SPECIFIC SET OF NEEDS. LIMITATIONS ERROR INDICATIONS FROM MSX (ODD ADDRESS TRAPS, ETC.) NORMALLY IN THE PRESENT VERSION WILL PRINT THE ADDRESS OF THE FAULT, THE TASK NAME, AND THE CONTENTS OF THE PAR FOR APR 1, THEN EITHER CONTINUE OR EXIT THE SYSTEM. PROVISION FOR DUMPING DATA IS PRESENT IN RUDIMENTARY FORM, BUT THE ERROR PROCESSING IS AT PRESENT MINIMAL AND PRELIMINARY. THIS MAY BE FIXED WITH A LITTLE WORK AND SOME IDEA WHAT IS WANTED. LINKING WITH DDT IS HOWEVER A GOOD FIRST STEP AT ALLOWING A MORE SENSIBLE RECOVERY UNTIL A CUSTOM METHOD IS AVAILABLE. SUFFICIENT INFORMATION TO ALLOW ERROR RECOVERY TASKS TO RUN IS AVAILABLE TO THE ERROR LOGGER; THESE ARE JUST NOT IMPLEMENTED. THE CONSOLE OUTPUT WILL LOOK A BIT LIKE OLD DOS-11 OUTPUT; MSX WAS ORIGINALLY DEVELOPED TO RUN USING DOS DEVICE DRIVERS AND HAD TO HANDLE THEIR IOT'S FOR DEVICE UNREADY CONDITIONS. THESE HISTORICAL ARTIFACTS ARE OF NO PRESENT CONCERN HOWEVER. NOTE THAT MSX DRIVERS, UNLIKE THEIR DOS COUNTERPARTS, ACCEPT BYTE COUNTS RATHER THAN WORD COUNTS. MSX SYSTEM DIRECTIVES NOTE: THE MACRO NAMES HERE ARE ONE SET OF CUSTOMARY ONES; THE ASSEMBLY EXPANSIONS ARE IMPORTANT, BUT OTHER MACROS ARE POSSIBLE (AND HAVE BEEN DEVISED) TO ALLOW EASIER CODING WHERE FEWER USER- SPECIFIED ARGUMENTS ARE NEEDED. THE FOLLOWING ARE THE OLDEST AND MOST BASIC MSX SYSTEM DIRECTIVES. FOR A FULL LIST, SEE MSX11.RNO. WAIT WAIT. #EV ;WAIT TILL EV BECOMES NON-ZERO ASSEMBLY: MOV #EV,-(SP) TRAP 0 ACTION: TASK ENTERS STATE 2 AND STAYS THERE TILL THE WORD EV BECOMES NON-ZERO. ON RETURN, CONDITION CODES REFLECT THE VALUE OF EV (EVENT VARIABLE) AT THE TIME OF THE TASK-SCAN. PRIREQ PRIREQ #NAM,#PRI,#EV ;REQUEST HIGHER PRIO TASK DIRECTLY ACTON: TASK IS DIRECTLY ENTERED WITHOUT A FULL SCAN, THOUGH A SIGNIFICANT EVENT IS RECORDED FOR LATER. IF A HIGHER PRIORITY TASK HAS BEEN STARTED BUT NOT EXITED, PRIREQ IS EXACTLY EQUIVALENT TO REQUEST. OTHERWISE IT GOES TO THE TASK LOCATION WITHOUT A SCAN. NOTE THAT THE HIGHEST PRIORITY TASK IS A WORD, NOT A LIST; IF TASKS ARE NESTED WRONG, THE LOGIC COULD OMIT A SCAN SOMETIMES WHERE IT MIGHT BE ADVISABLE TO HAVE IT. ASSEMBLY: MOV #EV,-(SP) MOV #PRI,-(SP) MOV #NAM,-(SP) ;OR TASK NUMBER FROM 0 TRAP 1 ORWAIT ORWAIT #EVTAB ;WAIT UNTIL ANY OF THE WORDS IN EVTAB ;BECOME NONZERO ASSEMBLY: MOV #EVTAB,-(SP) TRAP 2 ACTION: TASK ENTERS STATE 3 AND REMAINS UNTIL ONE OR MORE OF THE WORDS IN EVTAB IS NONZERO. THE FORMAT OF EVTAB IS: EVTAB: .WORD EV1 .WORD EV2 .WORD EV3 . . . .WORD 0 ;TERMINATOR WHERE THE EVENT VARIABLES EV1, EV2, EV3,...,EVN ARE WORDS IN MEMORY. SUSPEND SUSPEND ;STOP TASK UNTIL SOMEONE ELSE TELLS IT TO RESUME ASSEMBLY: TRAP 3 ACTION: TASK ENTERS STATE 1 AND REMAINS UNTIL ANOTHER TASK ISSUES A RESUME DIRECTIVE SPECIFYING THIS TASK. RESUME RESUME #NAM,#RA,#EV ASSEMBLY: MOV #EV,-(SP) MOV #RA,-(SP) ;RESUME ADDR MOV #NAM,-(SP) ;TASK NAME TO RESUME TRAP 4 ACTION: THE TASK WHOSE NAME IS AT NAM IS RESUMED AT ADDRESS RA. IF RA IS NOT SPECIFIED (IS 0), TASK NAM RESUMES AT THE INSTRUCTION FOLLOWING THE SUSPEND IT ISSUED TO GET INTO STATE 1. IF THE TASK WAS NOT SUSPENDED, RESUMING IT IS AN ERROR. THIS GETS REFLECTED IN THE EVENT VARIABLE EV. EV NONZERO MEANS RESUME PROCESSING IS COMPLETE. REQUEST REQUEST #NAM,#PRI,#EV ASSEMBLY: MOV #EV,-(SP) ;EV TO TELL WHEN TASK HAS BEEN REQUESTED MOV #PR,-(SP) ;PRIORITY. (UNUSED) MOV #NAM,-(SP) ;NAM HAS TASK'S RAD50 NAME. TRAP 5 ACTION: THE TASK NAM IS STARTED. IF TASK NAM IS NOT IN STATE 0 (EXITED), THIS IS AN ERROR. NOTE THAT FOR REQUEST AND RESUME THE ACTUAL RAD50 TASK NAME IS PUSHED ONTO THE STACK. FOR RESUME THE RA IS LITERAL ALSO. IF A NUMBER IS PUSHED ONTO THE STACK AS TASK NUMBER FOR RESUME OR REQUEST, THE NUMBER (0,1,2,3,4,...) WILL BE TREATED AS THE NUMBER OF THE TASK (ITS PRIORITY...) FROM THE START OF THE STL. THAT TASK WILL THEN BE RESUMED OR REQUESTED AND WILL REQUIRE SOMEWHAT LESS TIME FOR TASK LOOKUP THAN THE NAME METHOD. THE TWO MAY BE INTERCHANGED. EXIT EXIT #EV ;EXIT. EV MAY BE REPLACED WITH 0 IF NOT NEEDED. ASSEMBLY: MOV #EV,-(SP) TRAP 6 ACTION: TASK BECOMES INACTIVE. IT MUST BE REQUESTED AGAIN TO RESTART. EV IS SET NONZERO WHEN TASK HAS EXITED. DECLARE DECLARE ;TELL MSX SOMETHING HAS HAPPENED SO IT SHOULD SCAN TASKS. ASSEMBLY: TRAP 7 ACTION: THIS MAKES MSX SCAN TASK TABLES TO SEE IF CONTROL SHOULD BE SWITCHED TO ANOTHER TASK. IF IT SHOULD, IT THEN WILL. SIMPLY SETTING AN EV NONZERO WILL NOT AUTOMATICALLY START ANOTHER TASK; THIS IS A WAY TO DO SO, WHILE INTERRUPTS ARE ANOTHER. QTRAN QTRAN #DEV,#QBLOCK,#EV ;DO I/O VIA QTRAN ASSEMBLY: MOV #EV,-(SP) MOV #QBLOCK,-(SP) ;DOS-STYLE TRAN BLOCK MOV #DEV,-(SP) ;WORD CONTAINING MSX LOGICAL UNIT/SUBUNIT # ;OF DEVICE. UNIT # IN LOW BYTE; SUBUNIT IN HIGH ;BYTE TRAP 10 ACTION: THIS REQUESTS SOME I/O BE DONE. EV IS NONZERO ON COMPLETION. EV POSITIVE IMPLIES SUCCESS; NEGATIVE IMPLIES ERROR IN I/O. NOTE THAT THE WORD AHEAD OF A QTRAN EV IS THE TASK TO REQUEST ON I/O COMPLETION. BE SURE IT IS 0 IF NONE SHOULD BE CALLED. MSX UNIT NUMBERS MAY REPLACE RAD50 DEVICE NAMES AS FOLLOWS: DEV LUN KB INPUT 1 KB OUTPUT 2 DF 3 (NOT SUPPORTED UNDER STD-ALONE) MT 4 (NOT SUPPORTED UNDER STD-ALONE) CR 5 (NOT SUPPORTED UNDER STD-ALONE) LP 6 DT 7 DK 8 (NOT SUPPORTED UNDER STD-ALONE) VT 9 (NOT SUPPORTED UNDER STD-ALONE) UNDER RSX, THERE ARE A FEW MODS TO QTRAN. QTRAN WILL STILL QUEUE UP I/O REQUESTS ON A PER-LUN BASIS AVOIDING THE IMPLIED SUSPENSION RSX IMPOSES WHEN 2 QIO$ REQUESTS ARE OUTSTANDING. HOWEVER, THE QBLOCK IS JUST THE QIO$ DIRECTIVE PARAMETER BLOCK (DPB), THE EV IS THE I/O STATUS BLOCK (SO 2 WORDS MUST BE RESERVED THOUGH ONLY THE FIRST IS TREATED AS AN EVENT VARIABLE BY MSX0), AND THE DEV ARGUMENT IS SIMPLY THE RSX LUN. IF A LUN IS IN THE RANGE PERMITTING QUEUING (ASSEMBLY PARAMETER), THE REQUESTS WILL BE QUEUED. IF EV AND/OR LUN ARGUMENTS ARE OMITTED, THEY WILL BE IGNORED AND THE DPB USED AS IS. THEY WILL BE FILLED IN FOR QIO$ ONLY. ANY OTHER RSX REQUEST MAY BE PASSED VIA QTRAN, BUT WILL JUST BE EXECUTED IMMEDIATELY. THE WORD PRIOR TO THE I/O STATUS BLOCK MAY CONTAIN A TASK NUMBER TO RUN ON I/O COMPLETION IN THE RSX VERSION. IF IT CONTAINS A NUMBER EITHER 0 OR TOO LARGE NOTHING WILL HAPPEN. IF THE NUMBER IS IN A LEGAL RANGE, THE NUMBERED TASK WILL BE EXECUTED ON I/O DONE. ************************************ NOTE!!!!!!!! *********************************** THIS REQUIRES THAT 3 WORDS BE RESERVED FOR THE I/O STATUS WORD, WITH ONE BEFORE AND ONE AFTER THE LABEL!! FOR SPEED, THE RSX VERSION ALLOWS TRAP CALLS TO MSX0 TO BE REPLACED BY A JSR PC SEQUENCE. TO REPLACE THE SEQUENCE TRAP N USE THE SEQUENCE JSR PC,MX.SVC .WORD N (AN ADDITIONAL ENTRY POINT, MX.SV2, MAY BE USED IF THE TRAP CODE IS DOUBLED.) THIS SAVES CONSIDERABLE TIME FOR RSX USE; THE RSX TRAP SERVICE OVERHEAD IS AVOIDED. RSX USERS SHOULD BE AWARE THAT FOR MSX0, THE EVENT VARIABLE IS A WORD, NOT A BIT!! MSX SCANS IN 2 MODES. FULL-SCAN LOOKS AT ALL TASKS. PART-SCAN LOOKS FROM THE CURRENT TASK'S POSITION DOWN THE TABLE, DONE WHEN THER IS NO LOGICAL REASON TO SUSPECT A TASK OF HIGHER PRIORITY COULD HAVE BECOME ACTIVE BY A MSX DIRECTIVE. ALL DIRECTIVES EXCEPT SUSPEND, WAIT, AND ORWAIT PERFORM FULL-SCANS. IN QTRAN I/O, THE QBLOCK IS SET UP EXACTLY AS A DOS TRAN BLOCK FOR READ/WRITE. FOR SPECIAL FUNCTIONS, IF BOTH THE 1 AND 2 BITS OF THE TRAN BLOCK STATUS WORD ARE 1, IT IS ASSUMED A SPECIAL FUNCTION IS WANTED. IN THAT CASE, THE MEMORY ADDRESS SLOT IN THE TRAN BLOCK IS CONSIDERED A POINTER TO A DOS-STYLE SPEC BLOCK. FOR THESE CALLS THE EV WILL CONTAIN THE SPEC BLOCK ADDRESS WHEN THE OPERATION IS DONE. THE FORMAT OF THE TRAN BLOCK IS: QBLOCK: .WORD 0 ;DEVICE BLOCK NUMBER .WORD MEMADD ;MEMORY START ADDR .WORD PWC ;POSITIVE WORD COUNT (BYTE COUNT EXCEPT UNDER DOS) .WORD FUNC ;BIT 2=WRITE; BIT 4=READ; NEITHER=.SPEC CALL .WORD 0 ;SPARE THE FUNC WORD IS SIMPLY PASSED TO THE DRIVER (AS ARE THE OTHERS) AND THE CONTENT OF A QBLOCK FOR A GIVEN DEVICE IS DEPENDENT ON THE DRIVER. THE WORD COUNT IS NEGATED BEFORE PASSING TO THE DRIVER, BUT THE OTHER ARGUMENTS ARE LEFT ALONE. THE UNIT NUMBER IS SENT TO THE DRIVER IN THE HIGH BYTE OF THE FUNC WORD AND THE LOW BYTE OF FUNC IS SENT INTACT. THE DRIVER (IN THE STANDALONE MSX) HAS ACCESS TO THE TCB ADDRESS OF THE TASK (AT ITS DDB+20) WHEN EXECUTING. THE FORMAT OF A DDB IS INCLUDED IN THE CODE IN MXTRPS. THE UNIT NUMBER MAY BE USED AS AN EXTENDED BLOCK NUMBER FOR AN APPROPRIATE DEVICE. SUBUNITS ARE CONTROLLED BY THE UNIT SPECIFIER IN THE DEV NUMBER IN THE CALL. MSX CANNOT HANDLE RAD50 DEVICE NAMES ACTUALLY BUT WANTS ITS LOGICAL UNIT NUMBER IN THE LOW BYTE AND THE SUBUNIT (DT0:,DT1:, DT2:, ETC. 0,1,OR 2, FOR EXAMPLE) IN THE HIGH BYTE. IF A .SPEC CALL IS ISSUED, THE FUNCTION IS GIVEN IN THE DEVICE BLOCK NUMBER SLOT. LP: OPEN AND CLOSE FOR INSTANCE WOULD BE THE OFFSETS FROM DRIVER START TO THE BYTE IN THE DRIVER CONTROL TABLE FOR THOSE FUNCTIONS. DRIVERS DETERMINE THESE FUNCTIONS. INTERRUPTS WHEN AN INTERRUPT OCCURS, MSX MUST BE NOTIFIED SO IT CAN MAINTAIN STACK USE CORRECTLY. IT USES 1 COMMON STACK FOR ALL INTERRUPT PROCESSING AND MUST KNOW WHEN THAT STACK IS TO BE ENTERED. A STANDARD POSTING PROCEDURE IS DONE IN MX.PST. THE CALL SEQUENCE IS JSR R5,MX.PST ;WITH ONLY INTERRUPT PS,PC ON STACK .BYTE PRI,RFLG PRI IS THE PRIORITY TO BE USED IN PS FOR THE REST OF THE INTERRUPT SERVICE ROUTINE AND MUST BE THE ACTUAL BYTE TO GO INTO THE PS. THE INTERRUPT VECTORS SHOULD ALWAYS HAVE PRIORITY 7 NEW-PS VECTORS AND USE THIS ROUTINE TO LOWER THE PRIORITY IF DESIRED. THE RFLG BYTE TELLS WHETHER TO SAVE REGISTERS (R5-R0) IF NONZERO, OR NOT. RFLG=0 IMPLIES DO NOT SAVE REGS; RFLG= NOT-0 IMPLIES SAVE REGS. REGS ARE SAVED ON THE COMMON (INTERRUPT) STACK. ALL INTERRUPT ROUTINES SHOULD END IN RTI AFTER RESTORING ANY REGISTERS. THE ROUTINE MUST RESTORE REGS ITSELF USING EITHER THE MSX OR DOS REGISTER-RESTORE ROUTINES. TASKS CAN PREVENT TASK SCANNING BY SETTING THE LOW BYTE OF MX.LOK NONZERO (SYSTEM USES HIGH BYTE) (ZERO?) WHICH WILL LET INTERRUPTS OCCUR BUT KEEP CONTROL IN A TASK, POSSIBLY FOR CRITICAL TABLE MANIPULATIONS. USERS MUST UNLOCK THE SYSTEM TOO WHEN DONE. (ONE MAY HAVE TO ISSUE A DECLARE TO ENSURE NOTHING IMPORTANT HAS BEEN MISSED TOO.) STAND-ALONE MSX0 THERE IS A VARIANT OF MSX0 THAT WORKS IN A MEMORY-MAPPED STANDALONE ENVIRONMENT. TASKS RUN IN USER SPACE, NORMALLY IN APR 0 UP, AND MSX0 AND HANDLERS RUN IN KERNEL SPACE. IN THIS VERSION OF MSX, DEVICES ARE CONTROLLED BY HANDLERS THAT WORK AS EXECUTIVE PROCESSES, AND THE TASK STATUS IS ALL SAVED IN THE SYSTEM TASK LIST. THE STL ENTRIES ARE 24 WORDS LONGER FOR STANDALONE MSX THAN FOR THE NORMAL RSX/DOS VERSIONS, AND THE EXTRA 24 WORDS OF EACH ENTRY ARE LOCATED AFTER THE ONES DESCRIBED ABOVE. THEIR CONTENT IS AS FOLLOWS: TASK R0 TASK R1 TASK R2 TASK R3 TASK R4 TASK R5 TASK APR 0 TASK APR 1 TASK APR 2 TASK APR 3 TASK APR 4 TASK APR 5 TASK APR 6 TASK APR 7 TASK PC TASK PSW THE MAPPING HERE IS ADEQUATE FOR 22-BIT SUPPORT PROVIDED MX.BGN IS MODIFIED TO TURN IT ON. HOWEVER, NPR DRIVERS (AT PRESENT, ONLY DT:) NEED TO BE MODIFIED TO HANDLE THE UMR MAPPING TO WORK IN THIS MODE. ADDITIONAL WORDS ARE USED TO SUPPORT THE MULTIPLE-CPU STRUCTURES OF THE MSX SYSTEM. WHEN A TASK IS STARTED, ITS START ADDRESS IS COPIED OVER THE PC AND ITS "START APR1" WORD IS COPIED OVER APR 0. THE NORMAL STATUS RESTORE IS THEN USED TO BRING THE TASK UP. THE MSX STL IS EXPECTED TO HAVE ANY APR OR REGISTER CONTENTS SET UP INITIALLY AS NEEDED, BUT THEREAFTER THE STL ENTRY WILL HAVE ALL THIS INFORMATION COPIED INTO IT FROM THE TASK WHENEVER THE TASK IS INTERRUPTED BY ANOTHER (OR BY A DIRECTIVE). THIS MEANS THAT THE CONTENTS OF APRS 1 THROUGH 7 AND REGISTERS WILL TEND TO PROPAGATE ACROSS CALLS, BUT THIS DIFFERS FROM THE RSX VERSION AND SHOULD NOT BE COUNTED UPON. WHENEVER MSX STARTS A TASK, IT WILL SET THE PREVIOUS MODE TO KERNEL AND THE CURRENT MODE TO USER IN THE TASK'S PSW, TO ALLOW TASKS TO ACCESS KERNEL SPACE IF THEY WISH TO DO SO (E.G. TO SET MX.LOK OR TO FLAG A SIGNIFICANT EVENT.) IN THE STANDALONE MSX, ONE CANNOT USE A JSR PC SEQUENCE TO ENTER AN EXECUTIVE ROUTINE. THE TRAP SEQUENCES QUOTED ABOVE WILL HAVE THE DESIRED FUNCTIONS HOWEVER. TO PERMIT I/O TO BE DONE (AFTER A FASHION) FROM KERNEL PROCESSES, THERE IS A SUBROUTINE, KNLQIO, THAT WILL ISSUE A QTRAN AND A WAIT. IT IS CALLED VIA JSR PC WITH R1 POINTING TO THE EVENT VARIABLE, R2 POINTING TO THE (DOS-STYLE) QTRAN BLOCK, AND R3 CONTAINING THE LUN NUMBER FOR THE OPERATION. CONTROL WILL RETURN AFTER DONE; THE ACTIVE TASK (IF ANY) IN USER SPACE WILL BE DISABLED FROM EXECUTION UNTIL THE I/O COMPLETES. THIS IS BASICALLY TO ALLOW DDT TO PATCH USING THE AVAILABLE I/O FACILITIES, OR TO DO DEVICE-INDEPENDENT THINGS. FOR A BIT OF EXTRA SPEED, THE STANDALONE VERSION OF MSX SOMETIMES MAY BE SET TO USE THE EMT INSTRUCTION FOR TASK REQUESTS OR EXITS WITH NO ARGUMENTS, AS AN ALTERNATIVE TO THE TRAPS ALREADY NOTED. EMT NNN WILL REQUEST TASK NUMBER NNN (LEGAL WHERE NNN IS 177 OCTAL OR LESS, AND WHERE NNN IS A VALID TASK NUMBER). IF THE C BIT IS SET AT THE TIME THE EMT IS ISSUED, THE REQUEST WILL BE EFFECTIVELY A QRUN, WITH NO PRIORITY ARBITRATION PERFORMED. IF THE C BIT IS CLEAR, MSX WILL ENSURE THAT TASK NNN IS REALLY THE HIGHEST PRIORITY ELIGIBLE TASK BEFORE STARTING IT (EFFECTIVELY A PRIREQ). EMT NNN WHERE NNN IS HIGHER THAN THE MAXIMUM VALID TASK NUMBER (OR NEGATIVE), WILL ACT AS AN EXIT DIRECTIVE. STANDALONE MSX USES THE DOS FORMAT TRAN BLOCKS FOR ITS QTRAN DIRECTIVE. HOWEVER, THE EVENT VARIABLE IS REALLY A BLOCK OF AT LEAST 2 WORDS. THE LABEL IS ON THE SECOND, AND THE FIRST GIVES THE TASK NUMBER TO REQUEST WHEN THE I/O COMPLETES. IF THIS TASK NUMBER IS NONZERO AND WITHIN THE VALID RANGE FOR THE SYSTEM, THAT TASK WILL BE REQUESTED BY AN EFFECTIVE QRUN (NO PRIORITY ARBITRATION) WHEN THE COMPLETION INTERRUPT IS SERVICED. THE MX.PST ROUTINE ACTS SOMEWHAT DIFFERENTLY IN STANDALONE MSX THAN IN THE RSX VERSION. IN THE STANDALONE VERSION, INTERRUPTS WHEN POSTED WILL MODIFY THE STACK ONLY WHEN THE SCANNER IS INTERRUPTED. IF A TASK IS INTERRUPTED NO ACTION IS TAKEN, BUT COMPLETION RETURNS JUMP TO MX.RTI TO SEE IF A SWITCH IS NEEDED DIRECTLY. THIS IS DONE IN MXIOHT, WHICH IS PART OF THE I/O SYSTEM FOR STANDALONE MSX. IN THE STANDALONE VERSION, I/O IS DONE AS PROCESSES RATHER THAN TASKS, AND ACTIVATIONS OF I/O HANDLER TASKS ARE NOT NEEDED. ONLY COMPLETION RETURNS (WHICH ARE SIGNIFICANT EVENTS) REQUIRE CONTEXT SWITCHES. FOR USER INTERRUPTS WISHING TO ALLOW CONTEXT SWITCHING, THE CORRECT SEQUENCE IS TO SAVE THE CURRENT TASK STATUS AT INTERRUPT LEVEL AND THEN CALL THE SCANNER: ;(PROCESS INTERRUPT) ;(MUST SAVE/RESTORE ANY REGS USED) JSR PC,U.RSAV ;SAVE CURRENT TASK CONTEXT. TOP OF STACK ;MUST BE ONLY THE INTERRUPT. THIS MAY ;BE BEFORE OR AFTER MX.PST IS CALLED, ;AND ALL REGISTERS ARE FREE ONCE DONE JMP MX.RTI ;GO OFF SCANNING OR DO RTI IF MX.SEV NOT SET. NOTE THAT AT THE U.RSAV CALL THE ONLY THING ALLOWED ON THE TOP OF THE STACK IS THE PC,PS PAIR FROM THE INTERRUPT. U.RSAV WILL ITSELF CHECK THAT A TASK WAS THERE AND RETURN IMMEDIATELY IF NOT. THE CALL JSR PC,U.RRES WILL GET BACK A TASK CONTEXT IF ONE WAS THERE; THE C BIT WILL BE SET IF THE TASK WAS EXITED (USED WHEN STARTING NEW TASKS). THE USER MODE SP AND ALL APRS AND REGISTERS WILL BE SET UP. HOWEVER PLEASE NOTE: MSX MAKES NO VALIDITY CHECKS OF ANY REGISTERS OR APRS, INCLUDING SP AND PC. THERE IS A COMMAND WHICH MAY BE ASSEMBLED INTO DDT TO ALLOW ALL REGISTERS AND STATUS TO BE LOADED FROM A TCB; IT IS ADDRESS$UA IN THIS CASE, IF "ADDRESS" IS THE ADDRESS OF THE START (NAME WORD) OF A TCB ENTRY, DDT WILL LOAD ALL ITS CONTEXT WITH THE SAVED INFORMATION ABOUT A TASK IN THE FORMAT GIVEN ABOVE. THIS SHOULD MAKE IT EASY TO DEBUG MULTITASK SYSTEMS IN THIS ENVIRONMENT.