.TITLE ^MULTI-^SYSTEM ^EXECUTIVE
.SPACING 1
.PAPER SIZE 58,58
.FLAGS CAPITALIZE
.LEFT MARGIN 5
.RIGHT MARGIN 60
.CENTER
^MULTI-^SYSTEM ^EXECUTIVE
.SKIP 4
.LEFT MARGIN 10
.RIGHT MARGIN 55
\\
.PARAGRAPH
^THE <MSX-11 OPERATING SYSTEMS ARE DESIGNED TO PROVIDE A MEANS
TO HANDLE MULTIPROCESSING PROBLEMS USING THE <PDP11 LINE OF COMPUTERS.
^THESE SYSTEMS MAY EXECUTE EITHER AS STAND-ALLONE SYSTEMS, OR MAY
RUN UNDER THE <RSX-11 OPERATING SYSTEMS AS EMULATED PROCESSORS.
^TASKS USING <MSX-11 NEED NOT BE MODIFIED GOING FROM ONE SUCH
ENVIRONMENT TO ANOTHER, AND <MSX-11 PROVIDES A RICH SET OF
SERVICES FOR A MULTIPROGRAMMED, MULTIPROCESSED ENVIRONMENT
ON <PDP11 COMPUTERS. ^IT IS ASSUMED THAT THE <PDP11 <CPU\S
USED HAVE THE <EIS INSTRUCTIONS <ASH AND <SOB, AND, FOR THE
STAND-ALONE VERSION, MEMORY MAPPING HARDWARE. ^A ^PROCESSOR
^STATUS ^WORD ADDRESSABLE FROM THE <UNIBUS IS ALSO ASSUMED.
(^THAT IS, A NETWORK OF SOMETHING LIKE <PDP11/23 OR <PDP11/44
<CPU\S IS ENVISIONED.)
.PARAGRAPH
<MSX-11 IS A SINGLE-USER, MULTI-TASKING, MULTIPROCESSING SYSTEM. ^AS
SUCH, IT IS DISTINGUISHED FROM MULTI-USER SYSTEMS LIKE <RSX-11 IN THAT
IT ASSUMES THAT TASKS RUNNING UNDER <MSX FORM PART OF A COORDINATED
PLAN, AND THAT COMPREHENSIVE VALIDATION OF ARGUMENTS SENT TO THE
<MSX EXECUTIVE IN SERVICE REQUESTS IS NOT NEEDED. ^SOME CRUDE
VALIDATION IS PERFORMED, BUT ON THE WHOLE, <MSX IS NOT ABLE TO
DETECT ALL INVALID REQUESTS. ^IT WILL ATTEMPT TO IGNORE INVALID
REQUESTS, BUT FAILURES DUE TO ERRORS IN CALLING CODE WILL NOT
NECESSARILY BEHAVE IN AN ORDERLY WAY.
.PARAGRAPH
^THIS DOCUMENT DESCRIBES <MSX-11 ^V001^A, AS WRITTEN BY ^^G.C. EVERHART\\
AND IS CURRENT AS OF 1/12/1980.
.LEFT MARGIN 5
.RIGHT MARGIN 60

.PAGE
.SKIP 2
^^I.INTRODUCTION \T\O MSX - 11\\
.PARAGRAPH
^THE <MSX (^MULTI-^SYSTEM ^EXECUTIVE) SYSTEM WAS DEVELOPED AS A MEANS
OF SUPPORTING SOFTWARE RUNNING ON INTERCONNECTED COMPUTERS. ^THE
<PDP11 WAS USED AS A BASE SYSTEM FOR HISTORICAL REASONS (MAINLY THE
AVAILABILITY OF A MULTIPROGRAMMED SYSTEM IN THE PUBLIC DOMAIN FOR
IT), BUT THE SYSTEM WILL SUPPORT HIGHER LEVEL LANGUAGES AND IS
USABLE AS A BASE FOR DEVELOPMENTS WITH DIFFERENT HARDWARE.
.PARAGRAPH
<MSX IS A SYSTEM EXECUTIVE SUPPORTING PROGRAMS EXECUTING ON SEVERAL
PROCESSORS AT A TIME, EACH OF WHICH IS MULTIPROGRAMMED. ^ITS DESIGN IS
PARTLY TUTORIAL IN NATURE, THOUGH IT IS SUFFICIENTLY POWERFUL FOR
USE AS IS. ^IT IS NOT, HOWEVER, EQUIPPED TO PERFORM CONSISTENCY
CHECKS, VALIDITY CHECKS ON ARGUMENTS SUPPLIED TO IT BY ITS TASKS,
OR DECISIONS ABOUT ALLOCATION OF RESOURCES WHERE TASKS CONFLICT.
^IT IS FOR THIS REASON A SINGLE-USER (OR AT LEAST A SINGLE-USE)
SYSTEM, UNLIKE <RSX-11 OR SIMILAR MULTI-USER SYSTEMS WHICH DO
PERFORM THESE CHECKS. ^THE EXPECTATION IS THAT TASKS RUN ON A
<MSX SYSTEM ARE COORDINATED ENOUGH NOT TO MAKE CONFLICTING DEMANDS
ON THE <MSX EXECUTIVE, AND THAT THEIR ARGUMENTS ARE CORRECT WHERE
THEY REQUEST <MSX SERVICES. <MSX WILL THEN PERFORM ^I/^O, RUN
THE TASKS, AND MAINTAIN MEANS FOR THEIR COMMUNICATION, AUTOMATICALLY
SELECTING A <CPU AMONG ELIGIBLE <CPU\S WHERE MORE THAN ONE MAY HOST A 
TASK. <MSX ALSO HAS PROVISION FOR NOTIFYING TASKS OF ERRORS SEEN
IN OTHER TASKS THEY INITIATED AND OTHERWISE PROVIDING A USABLE
EXECUTION ENVIRONMENT. ^A TASK RUNNING UNDER <MSX IS PERMITTED,
IF MAPPED TO THE ^I/^O PAGE OF THE <PDP11 IT IS RUNNING ON,
TO ALTER ITS OWN MAPPING REGISTERS AT ANY TIME. ^IT MAY GAIN
CONTROL AFTER <IOT, <BPT, <EMT, AND <TRAP INSTRUCTIONS (EXCEPT
FOR <TRAP#375, WHICH IS USED BY <MSX ITSELF), ON FATAL ERRORS,
(WITH LIMITED RIGHTS HOWEVER), AND IT MAY PERFORM TIMING
TO A 1-SECOND GRANULARITY OR USE A FLOATING POINT PROCESSOR IF
ONE IS PRESENT. <MSX MUST BE ASSEMBLED CORRECTLY TO USE <FPP
OR A CLOCK, HOWEVER.
.PARAGRAPH
^THE CRUCIAL ASSUMPTION MADE BY <MSX-11 IS THAT SYSTEMS EXECUTING
ON A MULTIPROCESSOR CONFIGURATION CAN BE BROKEN INTO PIECES THAT
EXECUTE MOSTLY INDEPENDENTLY OF ONE ANOTHER ON SINGLE <CPU\S. ^THESE
ARE CALLED "<TASKS" HEREIN, IN CONFORMITY WITH THE <DEC TERMINOLOGY
FOR <RSX-11. ^THESE TASKS MAY COMMUNICATE WITH ONE ANOTHER, AND
THE SYSTEMS RUNNING IN EACH <CPU KNOW WHICH TASKS ARE EXECUTING IN
WHICH <CPU\S. ^A "KERNEL" OPERATING
SYSTEM RESIDES IN EACH MACHINE AND TALKS TO
THE OTHER KERNELS BY A PHYSICAL PATH WHICH MAY BE CHANGED RATHER
DRASTICALLY WITHOUT CHANGE TO MORE THAN ABOUT 4 LOW-LEVEL SUBROUTINES
OF THE <MSX OPERATING SYSTEM. ^THUS, THE <MSX SYSTEM IS DESIGNED TO
HANDLE CONFIGURATIONS WHERE THE COMPUTERS ARE CONNNECTED BY COMMON
MEMORY, BY BUSSES (ONE OR MORE), OR BY GENERALIZED NETS.
^THE <MSX SYSTEM PROVIDES A COMMON TASK COMMUNICATION STRUCTURE ALLOWING
A TASK TO SEND MESSAGES TO ANOTHER TASK, REQUEST ANOTHER TASK, OR
ABORT ANOTHER TASK. ^A FEW OTHER CONTROL PATHS ARE ALSO IMPLEMENTED, AND
TASKS MAY IF THEY WISH MODIFY THEIR PRIORITIES OR SYNCHRONIZE WITH
OTHER TASKS IN SEVERAL WAYS. ^THE SYSTEM IS ASYNCHRONOUS IN NATURE,
ATTEMPTING TO RECLAIM AS MUCH TIME AS POSSIBLE FOR USEFUL WORK.
^FURTHER, THE <MSX SYSTEM ATTEMPTS TO PERFORM LOAD BALANCING AND
ERROR RECOVERY IN REASONABLE WAYS. ^A TASK MAY (UNLESS SPECIFICALLY
PROHIBITED) RUN ON MANY <CPU\S, AND <MSX WILL ATTEMPT TO DETERMINE
DYNAMICALLY WHICH <CPU IS BEST ABLE TO RUN IT. ^IT WILL OF COURSE
DO BETTER AT THIS WHERE COMMON MEMORY OR A BROADCAST IS AVAILABLE
TO CHECK WITH, BUT IT IS ABLE TO PERFORM A REASONABLE APPROXIMATION
EVEN LACKING THESE. ^ERROR RECOVERY IS HANDLED BY CLEANUP ROUTINES
IN TASKS ABORTED WHERE POSSIBLE, AND BY NOTIFICATION OF CALLER
TASKS. ^WHERE A TASK HIERARCHY IS DESIRED, <MSX SUPPORTS IT BY
GUARANTEEING THAT ABORTING A PARENT TASK WILL ABORT ALL
CHILDREN AS WELL.
^A TASK MAY, OF COURSE, HANDLE ITS OWN EXCEPTIONS IF DESIRED AND
RETURN TO EXECUTION, BUT WILL NOT NORMALLY DO SO EVEN THOUGH THE
CAPABILITIES ARE PROVIDED.

.PARAGRAPH
<CPU\S ARE ALLOCATED AT TASK STARTUP, INITIALLY USING A COUNT OF
ACTIVE TASKS MAINTAINED BY EACH <CPU. ^EACH <CPU HAS COUNTS FOR
ALL <CPU'S, AND IT IS EXPECTED THAT EACH <CPU, WHEN A TASK REQUESTS
ANOTHER TASK TO RUN, DECIDES LOCALLY WHERE THE TASK SHOULD GO
AND EMITS A MESSAGE (REBROADCAST BY OTHER <CPU'S IF NEEDED) SAYING
WHICH <CPU MUST START THE TASK. ^ALL <CPU'S EVENTUALLY GET THE MESSAGE
AND MARK THE TASK ACTIVE THERE. ^THERE IS SOME COLLISION HANDLING
(RESULTING IN TASK EXIT AND AN ERROR STATUS "NET ERROR"), AND
FAILURE TO RECEIVE A MESSAGE WILL EVENTUALLY SIGNAL THE ROUTING
TASK (ONE PER <CPU) TO MARK A NODE DOWN. ^THE ROUTING TASK SHOULD
THEN ABORT ALL TASKS ACTIVE ON THE FAILED <CPU.
.PARAGRAPH
^ERROR HANDLING PRIMITIVES PERMIT TASKS TO ABORT ONE ANOTHER OR FAIL
FOR ERRORS NOTIFYING THE PARENT TASKS (IF THEY ARE STILL THERE) THAT
THE ABORT TOOK PLACE. ^ALL SUCCESSORS OF AN ABORTED OR EXITED TASK
ARE AUTOMATICALLY ABORTED (FORCED TO EXIT), BUT A TASK MAY RUN ANOTHER
TASK SO THAT IT IS INDEPENDENT, AND ANY TASK MAY SPECIFY AN ABORT
ENTRY WHICH WILL BE ENTERED TO DO CLEANUP VIA AN <AST PRIOR TO
ACTUAL TASK EXIT. ^HOWEVER, A TASK REENTERED THIS WAY MAY NOT
HAVE ANOTHER ERROR CONDITION OR BE ABORTED AND REENTERED A SECOND
TIME; THE SECOND ABORT ATTEMPT WILL NOT ENTER AT THE TASK'S
ABORT ENTRY BUT WILL SIMPLY CAUSE FORCED TASK EXIT, PREVENTING A
LOOP CONDITION.
.PARAGRAPH
^INPUT AND OUTPUT ARE DONE TO ATTACHED DEVICES IN A STANDARD WAY
WITH NO FURTHER ACTION FROM THE SYSTEM. ^WHERE ^I/^O MUST BE
DONE TO REMOTE <CPU\S, DATA IS SENT TO DEVICE HANDLER TASKS
WHICH PERFORM THE REQUESTED OPERATIONS AND RETURN RESULTS VIA
MESSAGES TO THE CALLERS. ^THIS ASPECT OF THE SYSTEM IS TRULY A
DISTRIBUTED OPERATING SYSTEM. ^THE ROUTING AND WATCHDOG TASKS
ARE LIKEWISE ORDINARY TASKS, UNUSUAL ONLY IN THAT THEY ARE
PERMITTED ACCESS TO SYSTEM TABLES WHICH WOULD NOT BE ACCESSIBLE
TO MOST TASKS DIRECTLY. ^THIS KEEPS THE SCHEDULER REASONABLY SIMPLE
AND AVOIDS POSSIBLE DIFFICULTY IF <MSX NEEDS TO BE MOVED TO A
DIFFERENT <CPU TYPE.
.PARAGRAPH
^THE TASKS PERFORMING THE ACTUAL <QTRAN CALLS TO <MSX WILL NOT ONLY
PERFORM DEVICE HANDLING; THEY ALSO MUST IMPLEMENT FURTHER ^I/^O
PROTOCOLS SUCH AS FILE SYSTEMS. ^THE INTERPROCESS DATA MUST BE
256. WORDS OR LESS LONG (1 DISK BLOCK), BUT CONTROL SIGNALS MAY
BE IMPLEMENTED IN THE ^I/^O ^HANDLER ^TASKS TO PERFORM FILE
ORIENTED TRANSACTIONS. ^THUS, THE <IOHT\S IN <MSX FILL MUCH THE
SAME ROLE AS <ACP\S IN THE <RSX SYSTEMS. ^THAT IS, THE <IOHT
MAPS CRUDE REQUESTS FOR DATA TRANSFERS INTO PROCESSES THAT PERFORM
ORDERLY TRANSACTIONS. ^THE COMPLEXITY OF THESE IS LIMITED ONLY BY
THE <IOHT.

.PARAGRAPH
<MSX COMES IN BASICALLY 2 FLAVORS. ^THE <STAND-ALONE FLAVOR
RUNS WITH NOTHING ELSE IN THE MACHINE BUT <MSX AND ITS TASKS.
^IT HAS AN INTEGRAL SYMBOLIC DEBUGGER AND HANDLERS FOR SEVERAL
HARDWARE DEVICES, BUT IS NORMALLY GENERATED ON ANOTHER SYSTEM.
^THE <RSX FLAVOR OF <MSX RUNS AS A TASK UNDER THE <RSX-11
OPERATING SYSTEM. ^ALL <MSX TASKS AND THE SYSTEM ITSELF
APPEAR TO <RSX-11 AS A SINGLE TASK, AND SUCH SYSTEMS MAY
BE CONNECTED VIA REAL HARDWARE INTERCONNECTIONS, OR BY
SIMULATED CONNECTIONS IN A SINGLE <CPU. ^THIS FEATURE PERMITS
ONE TO DEFINE A COMPLETELY EMULATED MULTI-<CPU SYSTEM WITHIN
A SINGLE PROCESSOR, AVOIDING THE UNCERTAINTIES OF NEW AND
SPECIAL HARDWARE. ^TASKS DEVELOPED UNDER SUCH A SYSTEM WIL
RUN UNDER THE STAND-ALONE ONE AS IS, SO A SINGLE PROCESSOR
MAY BE USED AS A DEVELOPMENT BASE FOR A PRODUCTION SYSTEM
WITH A FAIRLY WIDE VARIETY OF CONNECTION PATHS.
^THE <RSX FLAVOR OF <MSX ALSO HAS ACCESS TO THE FULL <RSX-11
FILE SYSTEM. ^THIS PERMITS A QUICK AND DIRTY NETWORK TO
CONTAIN MOSTLY STAND-ALONE <MSX SYSTEMS COMMUNICATING WITH
AN <RSX-BASED SYSTEM WITH DEVICE HANDLER TASKS TO CARRY OUT
THE ^I/^O IN A FILE-STRUCTURED WAY.
.PARAGRAPH
^THE INITIAL VERSION OF <MSX DOES NOT ADDRESS DOWNLOADING OF
CODE, THOUGH IT IS DESIGNED SO AS TO PERMIT IT WITHOUT
UNDUE DIFFICULTY. ^TASKS WILL EVENTUALLY BE LOADABLE VIA
THE ADDITION OF A "LOADER" TASK THAT WILL BE PERMANENTLY A
PART OF THE KERNEL, AND THE OPERATING SYSTEM LOAD OPERATION
CAN BE DEFINED WHEN THE INTERCONNECTION IS; THE SYSTEM IS
EASILY STARTED AFTER COPYING INTO MEMORY AND MAKES NO
ASSUMPTIONS ABOUT WHERE IT CAME FROM. ^THE SOURCE CODE IS
AVAILABLE AND SIMPLE TO UNDERSTAND (COMMENTS ARE EXTENSIVE
AND DESCRIBE OVERALL FUNCTIONS AS WELL AS DETAILS), SO LITTLE
DIFFICULTY IS EXPECTED. ^HOWEVER, THE SYSTEM EMULATION
FUNCTION IS BEING SET UP FIRST.

.PARAGRAPH
^THE <MSX SYSTEM IS SET UP TO HAVE A "MAXIMAL" CONTEXT AND TO TOLERATE
CONDITIONS SUCH AS NOT FINDING A TASK DEFINED LOCALLY (THIS IS TO
ALLOW TASKS TO BE DEFINED ONLY WHERE THEY ARE NEEDED IN A TASK CLUSTER).
^THE CONTEXT INCLUDES THE ENTIRE MACHINE'S ADDRESS SPACE IF DESIRED,
PLUS THE <IOT, <BPT, <EMT, AND <TRAP VECTORS (EXCEPT THE ^^TRAP#375\\
INSTRUCTION USED BY <MSX ITSELF). ^THE <MSX KERNEL IS CONCEPTUALLY
QUITE SIMPLE, SINCE IT IS DESIGNED AS A VEHICLE FOR INVESTIGATING
DISTRIBUTED COMPUTING PROBLEMS. ^HOWEVER, SUFFICIENT GENERALITY IS
PROVIDED TO ALLOW FURTHER DEVELOPMENT.
.PARAGRAPH
^THE <MSX EXECUTIVE EXISTS IN SEVERAL MAIN PARTS. ^THE FIRST PART IS
THE SCANNER, WHICH IS LOCATED IN FILE <MXSCNS AND WHICH IS THE
ROUTINE CALLED AFTER INTERRUPTS, TRAPS, OR WHEREVER THE SYSTEM HAS
BEEN AWAKENED TO FIND WORK. ^IT LOOKS DOWN THE <SYSTEM <TASK <LIST
TO FIND THE NEXT TASK ABLE TO BE RUN AND RUNS IT; THE LOOKING IS
FROM EITHER THE START OF THE LIST OR FROM THE LAST POSITION WHERE
IT WAS EXAMINED DEPENDING ON WHETHER ANYTHING HAS HAPPENED TO
SET THE "SIGNIFICANT EVENT" FLAG (E.G., ^I/^O COMPLETION). ^THIS
SEARCH IS DONE IN PRIORITY ORDER BY AN AUXILIARY LIST THAT POINTS TO
THE REAL <STL, TO ALLOW VARIABLE PRIORITIES. ^THIS LIST IS A DOUBLE
ENDED QUEUE KEPT IN PRIORITY ORDER. ^THE SCANNER ALSO CHECKS AT EACH
SCAN WHETHER A TASK'S STATE SHOULD BE CHANGED AND CHANGES IT IF
IT IS CORRECT TO DO SO. ^A TASK MAY BE RUNNING, EXITED, SUSPENDED,
WAITING FOR A WORD TO GO NONZERO IN ITS OWN OR THE SYSTEM'S SPACE,
WAITING FOR ONE OF A LIST OF WORDS TO GO NONZERO (OR POSITIVE) IN
EITHER SPACE, OR MAY BE AWAITING OR RUNNING AN ASYNCHRONOUS ENTRY
ON MESSAGE RECEIVED, EXIT OF A TASK IT IS THE PARENT OF, OR HANDLING
AN ERROR CONDITION TO CLEAN ITSELF UP PRIOR TO EXIT. ^IT MAY ALSO
MAP ANY PART OF MEMORY TO ITSELF, ALLOWING SHARED REGIONS TRIVIALLY,
AND MAY AWAIT MESSAGES OR EVENT VARIABLES OR COMBINATIONS OF THE
TWO. ^THE EVENT VARIABLE MECHANISM IS PRIMARILY FOR IN A SINGLE
<CPU, BUT SINCE THE SYSTEM MAINTAINS SOME VARIABLES FOR MESSAGES
OR OTHER TASKS, THE MECHANISM CAN ALSO SYNCHRONIZE ACROSS MACHINES,
AND SOME PRIMITIVES FOR A WAY OF SETTING SUCH FLAGS ACROSS A CPU
BOUNDARY ARE ALREADY IN THE SYSTEM. ^A TASK HAS ACCESS TO ITS OWN
DATA BASE (THIS MAY BE DENIED WHERE PRIVILEGES ARE IMPLEMENTED) AND
CAN SET UP ITS OWN TRAP ADDRESSES OR LEAVE THEM FOR THE SYSTEM.
^FINALLY, STAND-ALONE <MSX HAS AN INTEGRAL SYMBOLIC DEBUGGER, <DDT.
^WHEN, FOR EXAMPLE, A TASK IS WAITING FOR AN EVENT VARIABLE TO GO
NONZERO, EVERY SCAN DONE BY THE SCANNER WILL CHECK IT AND IF IT
IS NONZERO, THE TASK WILL BE MARKED RUNNING AND STARTED UP.
.PARAGRAPH
^THE SECOND PART OF <MSX IS ALSO IN <MXSCNS AND IS THE MESSAGE INPUT
INTERRUPT HANDLING LOGIC. ^THIS LOGIC HANDLES INPUT MESSAGES AND CAUSES
THEM TO HAVE THE DESIRED EFFECT ON TASK STATES.
.PARAGRAPH
^THE THIRD PART OF <MSX IS THE TRAP HANDLER IN <MXTRPS. ^THIS CODE
IS ACTIVATED BY THE <TRAP#375 INSTRUCTION AND INTERPRETS THE FOLLOWING WORD
AS A CODE FOR THE ACTION TO TAKE, WITH ARGUMENTS ON THE TASK STACK.
(<MSX HAS A SEPARATE STACK USED FOR INTERRUPTS, BUT EACH TASK HAS ITS
OWN STACK AS WELL.) ^IN GENERAL, THE TRAP HANDLING SEQUENCE PERFORMS
STATE CHANGES AND INITIATES MESSAGES, THEN GOES AND CALLS THE SCANNER
TO LOOK FOR WORK. ^THERE ARE A FEW SHORTCUTS, BUT THIS IS THE BASIC LOGIC.
^THE BASIC ^I/^O DIRECTIVE <QTRAN IS LOCATED IN <MXTRPS ALSO AS A TRAP
HANDLING ROUTINE; THIS IS USED ON A <CPU WITH ^I/^O DEVICES CONNECTED
TO IT, THOUGH ALL OTHER <CPU'S ON THE SYSTEM USE NORMAL MESSAGES TO
AN ^I/^O ^HANDLER ^TASK TO DO ^I/^O.
.PARAGRAPH
^THE FOURTH PART OF <MSX IS THE DATA BASE, IN <MXTBLS AND <MXSTLS,
WHICH DEFINES THE SYSTEM'S LISTS. ^IT IS EXPECTED THAT THE TABLE
STRUCTURES DEFINED IN <MXSTLS WILL BE DUPLICATED IN ANY OTHER ^^TCB\\
USED IN THE SYSTEM, AND THAT THE <TCB MACRO DEFINED THERE WILL BE USED
TO SPECIFY TASKS OR SPACES TO PUT TASKS. ^NOTE THAT TASKS MAY SHARE A
COMMON POOL AREA FOR MESSAGES IF DESIRED; IT IS ONLY NECESSARY TO
USE A COMMON SET OF CONTROL INFORMATION. ^NORMALLY, IT IS EXPECTED
THEY ARE SEPARATE.
.PARAGRAPH
^THE FIFTH PART OF <MSX IS THE COMMON SERVICE ROUTINES IN <MXSUBS AND
<MXCONN. ^THE <MXSUBS ROUTINES ARE THOSE EXPECTED NOT TO VARY FROM
ONE CONFIGURATION TO ANOTHER; THE ONES IN <MXCONN ARE THOSE THAT DEPEND
ON THE CONFIGURATION FOR OPERATION. ^EACH NEW SYSTEM CONFIGURATION TYPE
(COMMON MEMORY, BUSSES, 1 BUS, GENERALIZED GRAPH) WILL REQUIRE A
SOMEWHAT DIFFERENT VERSION OF <MXCONN AND GENERALLY VERY SIMILAR
VERSIONS OF THE OTHER MODULES. ^IT IS IMPLICIT THAT THE ACTUAL LOWEST-
LEVEL ^I/^O HANDLING ROUTINES FOR MESSAGES ARE IN <MXCONN, AND THE
SYSTEM ASSUMES THE LOW-LEVEL PROTOCOL INCLUDES SOME ERROR DETECTION
AND RETRANSMISSION SO THAT ERRORS DO NOT PROPAGATE OR OCCUR TOO OFTEN.
^ERRORS MUST BE NOTICED AND FLAGGED FOR HIGHER LEVELS IF THEY OCCUR
AND CANNOT BE REPAIRED. ^A MESSAGE BACK TO THE SENDER WITH AN ERROR
CODE IS THE CORRECT RESPONSE; SEE THE CODE IN THE INPUT MESSAGE
HANDLER FOR DETAILS.
.PARAGRAPH
^FINALLY, <MSX HAS LOCAL ERROR HANDLING CODE. ^THIS IS IN <MXCODS AND
CONTAINS ROUTINES TO FLAG ERRORS AND ALLOW A USER TO TYPE <C TO
CONTINUE OR ^D TO ENTER <DDT OR ^K TO KILL THE TASK IF THE ERROR IS
NONFATAL. ^A FATAL ERROR CAUSES A PRINTOUT OF A BIT OF DIAGNOSTIC
INFORMATION FOLLOWED BY ABORTING THE TASK. ^SYSTEM ERRORS LEAD TO
RESTART ATTEMPTS. ^THIS CODE IS QUITE SIMPLE MINDED AND WILL BE
EXPANDED AS NEEDED. ^IT MAY ATTEMPT TO FLAG ITS ERROR TO OTHER
<CPU'S, BUT THIS WILL NORMALLY BE DETECTED BY "WATCHDOG" TASKS IN
EACH MACHINE WHICH WILL ALSO EXCHANGE MESSAGES TO DO ROUTING
DYNAMICALLY. ^THESE WILL BE DEFINED AFTER THE SYSTEM ITSELF IS
DEBUGGED; THE FIRST CUT WILL USE STATIC ROUTING.

.SKIP 3
<II. <MACROS.
.PARAGRAPH
^THE <MSX SYSTEM IS USED FROM ASSEMBLY LANGUAGE (AND ULTIMATELY FROM
OTHER LANGUAGES) VIA A SET OF MACRO CALLS THAT PROVIDE THE INTERFACE
BETWEEN A USER TASK AND THE <MSX SYSTEM, AND VIA THAT SYSTEM, TO OTHER
USER TASKS IF DESIRED. ^THESE GENERATE (NORMALLY) TRAP CALLS. ^THE TRAP
CALLS MAY BE USING SEPARATE CODES OF THE <TRAP INSTRUCTION, OR THEY MAY
ALL USE THE <TRAP#375 INSTRUCTION FOLLOWED BY A CODE. ^THE LATTER IS THE
RECOMMENDED COURSE WHERE A SYSTEM MAY SUPPORT PASSING ALL OTHER TRAPS
BACK TO THE ISSUING TASK FOR HANDLING WHERE TRAP "VECTORS" ARE ALLOCATED
USING THE <MODSTT DIRECTIVE TO MODIFY THE 4 WORDS AFTER THE <APR SAVE
AREA TO THE ADDRESSES IN THE TASK TO HANDLE <BPT, <IOT, <EMT, AND
<TRAP INSTRUCTIONS. ^THE <PSW WILL NOT BE LOADED, SO ONLY 4 WORDS ARE
NEEDED. ^HOWEVER, RETURN FROM THESE TRAPS IS VIA <RTI AND THE ORIGINAL
<PSW AT THE TRAP WILL BE RESTORED. ^THE ODD ADDRESS OR ILLEGAL INSTRUCTION
TRAPS ARE HANDLED VIA THE TASK'S "ERROR ENTRY" FACILITY, ENABLED BY
SETTING THE <TCBABO WORD OF THE <STL TO THE ERROR <AST ENTRY. ^THIS
<AST ENTRY IS NORMALLY EXITED VIA AN <EXIT. DIRECTIVE, BUT A TASK
MAY CLEAN ITS STACK AND USE <MODSTT TO RESET ITS STATUS TO RUNNING
(STATE 4) AND RESET THE FLAGS BYTE (OFFSET 2 FROM START OF <TCB)
TO 0, THEN RETURN. ^NORMAL POLICY IS THAT TASKS DO NOT USE THESE
TRAPS IN THIS WAY, BUT IT CAN BE DONE.
.PARAGRAPH
^IN THE <MSX SYSTEM, A TASK MAY BE IN ONE OF 14. STATES NUMBERED
0 THROUGH 13. ^THESE ARE AS FOLLOWS:
.SKIP 3
.LEFT MARGIN 12
.INDENT -6
^A. ^STATE 0  -- IN THIS STATE, THE TASK IS EXITED (OR NEVER
REQUESTED). ^IT IS BYPASSED IN ALL SCANS. ^ITS ^SYSTEM ^TASK
^LIST ENTRY (IN ^^MX.TBL\\) MAY HAVE OLD <APR VALUES FROM A
PREVIOUS RUN, AND OLD REGISTER VALUES. ^HOWEVER, THE TASK MAY
DO NOTHING UNTIL IT IS RUN AGAIN.
.INDENT -6
^B. ^STATE 1 -- SUSPENDED.  ^IN THIS STATE, A TASK WILL BE BYPASSED
IN ANY <ATL SCANS WHERE <MSX IS LOOKING FOR WORK. ^HOWEVER, ITS
<PC AND <PS, ITS DYNAMIC STACK, AND ITS MAPPING ARE INTACT AND IT
MAY BE RESUMED BY A REQUEST FROM ANOTHER TASK AT EITHER THE
ADDRESS FOLLOWING THE ^SUSPEND DIRECTIVE IT HAS ISSUED, OR AT
ANY OTHER ADDRESS.
.INDENT -6
^C. ^STATE 2 -- WAITING. ^IN THIS STATE, THE TASK IS WAITING FOR
AN ^EVENT ^VARIABLE (A 16-BIT WORD) TO BECOME NONZERO.
^THE TASK WILL BE BYPASSED UNTIL THIS OCCURS, IN ANY ^ACTIVE
^TASK ^LIST (<ATL) SCANS. ^THE ^EVENT ^VARIABLE MAY BE ANYWHERE
IN THE TASK'S VIRTUAL ADDRESS SPACE. ^NOTE HOWEVER THAT ANY TASKS
ISSUING <WAIT. MACROS WILL HAVE TO BE MAPPED INTO AT EACH <ATL
SCAN, WHICH IS SOMEWHAT SLOWER THAN THE OTHER STATES 0,1, OR 4.
.INDENT -6
^D. ^STATE 3 -- ^ORWAITING. ^THE TASK IS WAITING FOR ONE OR MORE
OF A LIST OF EVENT VARIABLES TO BECOME NONZERO. ^IT WILL BE BYPASSED
IN ALL <ATL SCANS UNTIL THIS IS TRUE. (^THIS STATE HAS THE HIGHEST
OVERHEAD OF ANY TASK STATES.)
.INDENT -6
^E. ^STATE 4 -- ^RUNNING. ^IN THIS STATE, A TASK IS EXECUTING AND
WILL BE ACTIVATED ON ANY <ATL SCAN THAT GETS TO IT. ^TASKS ARE
ACTIVATED IN THE ORDER THEY APPEAR ON THE ^SYSTEM ^TASK ^LIST
(^^MX.TBL\\), WHICH DEFINES THEIR PRIORITY.
.INDENT -6
^F. ^STATE 5 -- ^WAITING FOR SIGNIFICANT EVENT. ^THIS STATE IS
ENDED AT THE FIRST <ATL SCAN AND THE TASK GOES TO ^STATE 4.
.INDENT -6
^G. ^STATE 6 -- ^WAITING FOR SIGNIFICANT EVENT IN KERNEL SPACE.
^THIS STATE IS LIKE ^STATE 2 EXCEPT THE <EV IS IN KERNEL (<MSX
EXECUTIVE) SPACE, NOT TASK VIRTUAL SPACE.
.INDENT -6
^H. ^STATE 7 -- ^PWAITING. ^THIS STATE IS SIMILAR TO ^STATE 2
EXCEPT THE TASK WAITS UNTIL THE <EV IS 0 OR POSITIVE.
.INDENT -6
^I. ^STATE 8 -- ^ABORT ^QUEUED. ^IN THIS STATE, A TASK IS BEING
FORCED TO EXIT AND WILL EITHER RUN AT ITS EXIT ROUTINE OR
EXIT AT THE NEXT SCAN. ALL ITS SPAWNED TASKS WILL BE ABORTED
ALSO.
.INDENT -6
^J. ^STATE 9 -- ^MESSAGE-^IN <AST QUEUED. ^IN THIS STATE, A TASK
HAS AN INPUT MESSAGE AND IT MAY BE DEQUEUED VIA AN <AST OR VIA
MESSAGE READ DIRECTIVES.
.INDENT -6
^K. ^STATE 10 - ^SPAWNED ^TASK ^EXIT <AST QUEUED. ^THE TASK HAS
SPAWNED ANOTHER TASK WHICH HAS EXITED OR BEEN ABORTED. ^AN <AST
TO NOTIFY THIS, THE CALLER, IS QUEUED.
.INDENT -6
^L. ^STATE 11 - ^PWAIT ON ^KERNEL ^EVENT ^VARIABLE. ^IN THIS
STATE, THE TASK AWAITS AN <EV IN <MSX EXECUTIVE SPACE BECOMING
0 OR POSITIVE. ^SINCE ONE OF THE ^SCRATCH ^CONTROL ^BLOCK
WORDS IS CONTINUALLY INCREMENTED EVERY SECOND BY THE CLOCK,
THIS STATE IS USED FOR TIMING PURPOSES BY TASKS.
.INDENT -6
^M. ^STATE 12 - ^ORPWAT. ^IN THIS STATE, THE TASK WAITS UNTIL
ANY <EV IN A LIST OF <EV'S BECOMES GREATER THAN 0. (THIS ALLOWS
COUNTERS AND FLAGS TO BE MIXED.). ^THE <EV'S ARE ALL IN THE TASK'S
SPACE.
.INDENT -6
^N. ^STATE 13 - ^TWAIT. ^IN THIS STATE, THE TASK WAITS FOR A CONDITION
OF THE EVENT VARIABLE SPECIFIED BY THE USER, OR UNTIL THE TASK SPECIFIED
BY THE USER HAS EXITED (IS SEEN IN ^STATE 0 BY THE SCANNER). <MSX MAY
BE ASSEMBLED TO PERMIT THIS STATE TO QUERY SEVERAL EVENT VARIABLES, AND
<EV\S ARE MASKED PRIOR TO TESTS, PERMITTING PARTS OF THEM TO BE
USED.
.LEFT MARGIN 0
.PARAGRAPH
^TASKS NORMALLY BEGIN IN ^STATE 0, EXCEPT THE STARTUP TASK WHICH
IS INITIALLY IN ^STATE 4. ^A TASK MAY REACH ^STATE 0 BY AN EXIT.
DIRECTIVE TO <MSX. ^IT REACHES ^STATE 1 BY A SUSPEND DIRECTIVE,
STATE 2 BY A WAIT. DIRECTIVE, AND STATE 3 BY AN ORWAIT. DIRECTIVE.
^IT MAY REACH ^STATE 4 BY EITHER A REQUEST DIRECTIVE (FROM STATE 0),
OR BY A RESUME DIRECTIVE (FROM STATE 1), OR BY ONE OR MORE EVENT
VARIABLES BECOMING NONZERO (E.G., AFTER AN ^I/^O TRANSACTION
COMPLETES) (FROM ^STATES 2 OR 3).
.SKIP 2
.PAGE
.CENTER
^MACROS FOR THE <MSX ^EXECUTIVE
.SKIP 2
.CENTER
^VERSION 1
.SKIP 7
.PARAGRAPH
^THE FOLLOWING IS A PARTIAL LIST OF MACROS AVAILABLE FOR USE
WITH THE <MSX SCHEDULER. ^THE USER SHOULD READ THE <MSX <USER
<GUIDE ALSO AS A GUIDE TO THE <MSX SYSTEM.

.PAGE
.SUBTITLE <DECLR.
.CENTER
<DECLARE (<DECLR.)
.SKIP 2
.PARAGRAPH
^THE <DECLR. MACRO WILL FLAG A SIGNIFICANT EVENT TO <MSX AND
CAUSE AN <ATL SCAN TO LOOK FOR WORK. ^CONTROL RETURNS WHEN
THE ISSUING TASK IS THE HIGHEST PRIORITY TASK TO RUN.
.PARAGRAPH
^THE FORMAT OF THE CALL IS
.SKIP 1
.INDENT 5
<DECLR.
.SKIP 1
^NO ARGUMENTS ARE NEEDED.
.PAGE
.SUBTITLE <EXIT.
.CENTER
<EXIT (<EXIT.)
.SKIP 2
.PARAGRAPH
^THE <EXIT. MACRO WILL CAUSE A TASK TO EXIT, AND OPTIONALLY SET
AN EVENT VARIABLE TO 1 TO SIGNAL (TO ANOTHER TASK) THAT IT HAS
EXITED.
^THE EVENT VARIABLE ADDRESS IS PUSHED; THE VARIABLE MAY BE ANYWHERE
IN THE TASK'S SPACE (THOUGH IT IS SENSELESS UNLESS THE SIGNALLED TASK
SHARES THE SPACE AT THE TIME OF THE REQUEST).
.PARAGRAPH
^THE FORMAT OF THE CALL IS
.SKIP 1
.INDENT 5
^^EXIT. EVADDR (\E.\G., EXIT. _#EV)\\
.SKIP 1
^THE ADDRESS IS PUSHED, NOT THE EVENT VARIABLE.
^THE ADDRESS IS A TASK VIRTUAL ADDRESS, ON A WORD BOUNDARY.
.PAGE
.SUBTITLE <GENDPB
.CENTER
<GENERATE ^DIRECTIVE ^PARAMETER ^BLOCK
.SKIP 2
.PARAGRAPH
^THE <GENDPB MACRO IS USED TO GENERATE A <DPB FOR USE WITH THE
<QTRAN DIRECTIVE. ^IN THE <RSX VERSION OF <MSX IT WILL EXPAND
TO A <QIO$ MACRO. ^IN THE STAND-ALONE VERSION, IT EXPANDS
TO THE <QBLOCK NEEDED BY THAT SYSTEM. ^THE FUNCTION ARGUMENT
MAY BE EITHER THE LITERAL "<READ" OR "<WRITE". ^THIS MACRO IS
USED IN THE STYLE OF THE <QIO$ MACRO (I.E., OUT-OF-LINE). ^IN THE
<RSX VERSION, IT WILL USE THE SAME <LUN AND ^EVENT ^FLAG NUMBERS;
THE STAND-ALONE VERSION HAS NO REDUNDANCY.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^GENDPB FUNCT,LUN,EVADR,STARTADDR,NBYTES,BLKNUMBER\\
.SKIP 1
WHERE AS SAID ABOVE ONLY "<READ" OR "<WRITE" ARE LEGAL
IN THE <FUNCT ARGUMENT. <EVADR IS THE ADDRESS OF THE MIDDLE
WORD OF A 3 WORD BLOCK USED AS THE ^EVENT ^VARIABLE AND THE
SIGNAL OF WHICH TASK TO ISSUE <QRUN ON AT ^I/^O DONE.
.SKIP 3
^THAT IS, ONE MIGHT PUT IN "<EVADR" LITERALLY AND HAVE CODE
THAT LOOKS LIKE THIS:
.SKIP 3
^^
############.WORD##0######;TASK TO QRUN (NONE HERE)
.BREAK
##EVADR:####.WORD##0######;EVENT VARIABLE
.BREAK
############.WORD##0######;2ND HALF OR RSX I/O STBK
.SKIP 3
\\

.PAGE
.SUBTITLE <ORWAT.
.CENTER
<ORWAIT (<ORWAT.)
.SKIP 3
.PARAGRAPH
^THE <ORWAT. MACRO PASSES THE ADDRESS OF A LIST
OF ^EVENT ^VARIABLES TO THE <MSX EXECUTIVE. ^THE TASK WILL
BE WAITING UNTIL ANY OF THEM BECOMES NONZERO. ^AT THIS POINT
THE TASK WILL AGAIN BE ELIGIBLE TO RUN.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^ORWAT. EVTBADR\\
.SKIP 1
WHERE <EVTBADR IS THE ADDRESS OF A TABLE OF ^EVENT ^VARIABLE
ADDRESSES TERMINATED BY A ZERO, SUCH AS THE FOLLOWING:
.SKIP 2
.NOFILL
^^
.BREAK
EVTAB:##.WORD##EV1######;ADDR OF EV1
.BREAK
########.WORD##EV2######;ADDR OF EV2
.BREAK
########.WORD##EV3######;ADDR OF EV3
.BREAK
########.WORD##EV4######;ADDR OF EV4
.BREAK
########.WORD##0########;LIST TERMINATOR
\\
.FILL
.PAGE
.SUBTITLE <PRIRQ.
.CENTER
^PRIORITY ^REQUEST (<PRIRQ.)
.SKIP 3
.PARAGRAPH
^THE <PRIRQ. MACRO REQUESTS A TASK, COMPARING ITS PRIORITY WITH
THE HIGHEST EXECUTING TASK (NOT IN STATE 0) AND SKIPPING A FULL
<ATL SCAN IF THE REQUESTED TASK IS HIGHEST. ^IN OTHER RESPECTS IT
IS LIKE <REQUEST (<RQST.). 
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^PRIRQ. TSKNAM,EVADR\\
.SKIP 1
WHERE <TSKNAM MAY BE EITHER THE <RAD50 TASK NAME FROM THE <MSX TASK
TABLE, OR ITS NUMBER (0 TO THE MAXIMUM NUMBER OF TASKS IN THE SYSTEM
TABLE). ^USING THE NUMBER IS FASTER. <EVADR IS AN EVENT VARIABLE ADDRESS;
THE EVENT VARIABLE WILL BE SET BY THE REQUEST LOGIC.
.PAGE
.SUBTITLE ^^QIOW.S\\
.CENTER
<PERFORM ^I/^O (^^QIOW.S\\)
.SKIP 3
.PARAGRAPH
^THE ^^QIOW.S\\ MACRO ACTS LIKE THE ^^QIOW$S\\ MACRO IN <RSX, THAT IS,
IT PUSHES A ^DIRECTIVE ^PARAMETER ^BLOCK ON THE STACK, STARTS ^I/^O,
AND AWAITS DONE. ^IN THIS CASE, "<FUNCT" MAY BE EITHER "<READ"
OR "<WRITE"; THE APPROPRIATE ^I/^O CODE IS PUSHED DEPENDING ON THE
SYSTEM.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^QIOW.S#FUNCT,LUN,EVADR,STADD,NBYTES,BLKNO\\
.SKIP 1
WHERE <FUNCT MAY BE "<READ" OR "<WRITE", <LUN IS THE LOGICAL
UNIT NUMBER, <EVADR IS THE ^EVENT ^VARIABLE ADDRESS (ACTUALLY
UNUSED AND MAY BE BLANK; THE <EV IS GENERATED ON THE STACK),
AND <STADD IS THE MEMORY ADDRESS (EVEN) AND <NBYTES IS THE
BYTE COUNT (SHOULD ALSO BE EVEN). <BLKNO IS THE DEVICE BLOCK
NUMBER FOR RANDOM ACCESS DEVICES. ^ONLY 16 BITS ARE SUPPORTED
AT THE MOMENT.

.PAGE
.SUBTITLE <QRUN
.CENTER
<QUICK <RUN (<QRUN)
.SKIP 3
.PARAGRAPH
^THE <QRUN MACRO IS USED TO REQUEST A TASK WITH NO PRIORITY
ARBITRATION OR ARGUMENTS AT ALL. ^IT IS A SHORT PATH PROVIDED
TO ALLOW INTERRUPTS OR ^I/^O COMPLETION ROUTINES TO START
TASKS WITHOUT THE OVERHEAD OF A FULL <ATL SCAN. ^IT ONLY
REQUESTS TASKS BY NUMBER (0 THROUGH N, WHERE N IS THE HIGHEST
NUMBERED TASK, AND THE MAXIMUM-1 NUMBER OF ENTRIES IN ^^MX.TBL\\.
^NOTE: ^TASK 0 CANNOT BE REQUESTED THIS WAY. <MSX MAY BE ASSEMBLED
SO THAT THIS DIRECTIVE IS NOT AVAILABLE; THIS PERMITS TASKS
TO ISSUE AND TRAP <EMT INSTRUCTIONS THEMSELVES.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^QRUN N\\
.SKIP 1
WHERE ^N IS THE TASK NUMBER.
.PAGE
.SUBTITLE <QXIT
.CENTER
<QXIT - ^QUICK ^EXIT
.SKIP 3
.PARAGRAPH
<QXIT IS A PATH TO ALLOW A TASK TO EXIT WITH LESS OVERHEAD OF
TRAP INTERPRETATION THAN USED FOR THE NORMAL PATH, BUT WITH NO
EVENT VARIABLE SIGNALLING. ^IT HAS NO ARGUMENTS.
<MSX WILL OFTEN BE ASSEMBLED TO OMIT THIS DIRECTIVE IF STAND ALONE.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^QXIT\\
.SKIP 1
.PAGE
.SUBTITLE <RESUM.
.CENTER
<RESUME ^TASK (<RESUM.)
.SKIP 3
.PARAGRAPH
^THE <RESUM. MACRO RESUMES A TASK THAT WAS SUSPENDED AT EITHER
THE ADDRESS AFTER ITS <SUSPN. CALL OR AT ANOTHER ADDRESS. ^THE TASK
IS MARKED READY TO RUN AND AN <ATL SCAN IS MADE TO START IT IF IT
IS HIGHEST PRIORITY.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^RESUM. TSKNAM,RESADR,EVADR\\
.SKIP 1
WHERE <TSKNAM IS THE TASK NAME OR NUMBER, <RESADR IS A VIRTUAL ADDRESS
TO RESTART THE TASK AT (IF NULL, DEFAULTS TO AFTER THE SUSPEND), AND
<EVADR IS THE ADDRESS OF AV ^EVENT ^VARIABLE TO SET AT THE RESUME
PROCESSING.
.PAGE
.SUBTITLE <READ.
.CENTER
<READ (<READ.)
.SKIP 3
.PARAGRAPH
^THE <READ. MACRO WILL GENERATE AN INLINE <DPB AND PERFORM INPUT
TRANSFERS ON <LUN FOR <SIZE BYTES STARTING AT WORD <STADD. ^THE
VARIABLE AT <EVADR WILL BE SET ON ^I/^O DONE.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^READ. LUN,EVADR,STADD,SIZE,BLKNBR\\
.SKIP 1
WHERE <BLKNBR IS THE DEVICE BLOCK NUMBER IF BLOCK STRUCTURED.
.PAGE
.SUBTITLE <RQST.
.CENTER
<REQUEST ^TASK (<RQST.)
.SKIP 3
.PARAGRAPH
^THE <RQST. DIRECTIVE IS THE NORMAL METHOD OF STARTING TASKS IN <MSX.
^IT MARKS THE TASK READY TO RUN AND STARTS AN <ATL SCAN TO START IT
IF IT IS THE FIRST TASK READY TO RUN. (^A FULL SCAN IS PERFORMED).
^IF SPECIFIED, THE ^EVENT ^VARIABLE WILL BE SET WHEN THE REQUEST IS
MADE.
.PARAGRAPH
^THE FORMAT OF THE DIRECTIVE IS:
.SKIP 1
.INDENT 5
^^RQST TSKNAM,EVADR\\
.SKIP 1
WHERE <TSKNAM IS THE TASK NAME OR NUMBER, AND <EVADR IS THE ADDRESS
OF AN EVENT VARIABLE. (^NOTE THAT THESE ARGUMENTS, LIKE MOST
<MSX CALLS, ARE PUSHED ONTO THE TASK STACK; THESE DIRECTIVES
MAY BE PUT IN-LINE.

.PAGE
.SUBTITLE <SUSPN.
.CENTER
<SUSPEND ^TASK (<SUSPN.)
.SKIP 3
.PARAGRAPH
^THE <SUSPN. MACRO CAUSES A <MSX TASK TO BE SUSPENDED UNTIL RESUMED
BY ANOTHER TASK (OR REQUESTED; A REQUEST FUNCTIONS IN THIS CASE AS
A RESUME WHERE THE TASK WAS SUSPENDED). ^IT HAS NO ARGUMENTS.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^SUSPN.\\
.SKIP 1
.PAGE
.SUBTITLE <TRAN.
.CENTER
^QUEUED ^DATA ^TRANSFER (<TRAN.) (ALSO CALLED <QTRAN)
.SKIP 3
.PARAGRAPH
^THE <TRAN. CALL IS THE MOST BASIC ^I/^O CALL WITHIN THE <MSX SYSTEM.
^IT WILL PERFORM THE ^I/^O FUNCTIONS SPECIFIED IN THE <QTRAN BLOCK
AT <DPBADR (IN THE FORMAT OF A <DOS-11 .<TRAN BLOCK) ON THE DEVICE
NUMBERED BY <LUN AND WILL SET THE ^EVENT ^VARIABLE AT <EVADR
NONZERO WHEN ^I/^O COMPLETES. (^IT CAN BE SET UP TO DO A <QRUN
ON ^I/^O DONE BY PUTTING A VALID, NONZERO TASK NUMBER IN THE WORD
AHEAD OF THE ^EVENT ^VARIABLE (I.E., AT <EVADR-2) ALSO, THOUGH THIS
PERFORMS NO FULL SCAN AND IS NOT RECOMMENDED.)
^IN THE <RSX VERSIONS OF <MSX, THE <EV IS THE <RSX <IOSB. ^IN THE
^STAND-^ALONE VERSIONS OF <MSX, THE <EV RETURNS A BYTECOUNT TRANSFERRED
OR A NEGATIVE NUMBER FOR ERRORS, AND IF ^^INT.SM\\ WAS DEFINED AT
<MSX ASSEMBLY, <EV+2 WILL SPECIFY AN INTERRUPT ENTRY AT ^^I/O\\
COMPLETION IF NONZERO. ^THIS WILL NOT BE A TRUE ASYNCHRONOUS ENTRY,
BUT WILL OCCUR ONCE THE TASK IS AGAIN ACTIVE. ^HOWEVER, IT WILL
APPEAR AS A TRUE INTERRUPT AND SHOULD BE EXITED VIA AN <RTI.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^TRAN. EVADR,DPBADR,LUNNO\\
.SKIP 1
WHERE <LUNNO IS THE <LUN NUMBER (LITERAL, NOT AN ADDRESS), AND THE
<DPB AT <DPBADR MAY BE GENERATED BY THE <GENDPB MACRO.
.PAGE
.SUBTITLE <WAIT.
.CENTER
<WAIT FOR ^NON-^ZERO ^EVENT ^VARIABLE (<WAIT.)
.SKIP 3
.PARAGRAPH
^THE <WAIT. DIRECTIVE CAUSES THE ISSUING TASK TO ENTER ^STATE 2
AND NOT RUN UNTIL THE EVENT VARIABLE AT <EVADR IS NONZERO. ^IF THE
VARIABLE IS NONZERO AT THE CALL, THE TASK MAY RESTART AT ONCE IF
IT IS THE HIGHEST ONE ELIGIBLE TO RUN.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^WAIT. EVADR\\
.SKIP 1
WHERE <EVADR IS THE ADDRESS OF THE VARIABLE TO WAIT FOR, ANYWHERE
IN THE TASK'S VIRTUAL ADDRESS SPACE.
.PAGE
.SUBTITLE <WRITE.
.CENTER
<WRITE.
.SKIP 3
.PARAGRAPH
^THE <WRITE. MACRO IS THE COMPLEMENT OF THE <READ. MACRO, AND
GENERATES AN INLINE <DPB TO PERFORM OUTPUT TRANSFERS FROM THE
AREA STARTING AT WORD <STADD FOR <SIZE BYTES TO DEVICE <LUN
ON BLOCK <BLKNBR, AND SIGNAL BY INCREMENTING THE <EV AT <EVADR
WHEN ^I/^ IS DONE.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^WRITE. LUN,EVADR,STADD,SIZE,BLKNBR\\
.SKIP 1
^THE <WRITE. OR THE <READ. MACRO BRANCH AROUND THE <DPB GENERATED AND
EITHER MAY BE PUT IN-LINE. ^THEY ARE MORE COMPACT THAN THE
^^QIOW.S\\ EXPANSION, BUT GENERATE <DPB'S USING ASSEMBLED IN
CALLS (AS THE <RSX <QIO$^C MACROS DO), SO THAT THE <DPB IS NOT
GENERATED AT RUNTIME IN THE <READ. OR <WRITE. MACROS. ^THE USER MUST
DECIDE WHICH FORM IS BEST FOR HIS NEEDS.
.PAGE
.SUBTITLE <SPAWN
.CENTER
<SPAWN
.SKIP 3
.PARAGRAPH
^THE <SPAWN MACRO CAUSES A TASK TO REQUEST ANOTHER TASK AND PRESERVE
INFORMATION ABOUT CALLER/CALLED RELATIONSHIPS. ITS ARGUMENTS ARE EXACTLY
THE SAME AS FOR REQUEST EXCEPT THAT THE "PRIORITY" ARGUMENT IS AN ADDRESS
OF AN <EV IN THE CALLER TO BUMP WHEN THE TASK EXITS. ^THIS ADDRESS IS
KEPT IN THE CALLED TASK'S <TCB. ^THE FORMAT IS:
.SKIP 1
.INDENT 5
^^SPAWN TSKNAM,XITEVA,CALEVA\\
.SKIP 1
^THE ARGUMENTS ARE PUSHED IN THE ORDER CALL <EV ADDRESS, EXIT <EV ADDRESS,
TASK NAME (<RAD50). ^THEN A <TRAP#11 OR ITS EQUIVALENT IS DONE TO PRODUCE
THE CALL. ^THE ^CALL <EV IS BUMPED AS SOON AS THE TASK IS MADE READY
TO RUN. ^THE EXIT <EV IS BUMPED ONLY AT CALLED TASK EXIT. ^NOTE THAT
THE CALLER MAY, USING <MODSTT, ELECT TO BE NOTIFIED BY AN <AST THAT
THE CALLED TASK EXITED. ^THIS IS IN ADDITION TO THE <EV NOTICE.
.PAGE
.SUBTITLE <MSGOUT
.CENTER
<MSGOUT
.SKIP 3
.PARAGRAPH
^THE <MSGOUT MACRO CAUSES A MESSAGE TO BE SENT TO ANOTHER TASK NAMED
IN THE DIRECTIVE. ^TO CONSERVE SPACE, ONLY THE ADDRESS OF A "MESSAGE
HEADER" IS SENT, IN THE TASK'S SPACE, GIVING THE LOCATION AND SIZE
OF THE TASK'S MESSAGE TO GO OUT AND WHICH <EV TO INCREMENT (OR SET
NEGATIVE IN CASE OF ERROR) ON MESSAGE RECEIPT BY THE CALLED TASK.
.PARAGRAPH
^THE FORMAT OF THE MESSAGE HEADER IS:
.LEFT MARGIN 10
.SKIP 2
.NOFILL
.TAB STOPS 10,15,20,25,30,35,40
^^
.INDENT -6
MSGHDR:	.WORD	0,0,MSGPRIORITY
.BREAK
	.RAD50	/NAM/	;CALLED TASK NAME
.BREAK
	.WORD	MSGLENGTH ;MSG SIZE, BYTES
.BREAK
	.WORD	EVENT..VARIABLE..ADDRESS
.BREAK
	.BLKB	MSGLENGTH ;DATA AREA
\\
.FILL
.LEFT MARGIN 0
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^MSGOUT##_#MSGHDR\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#12.
^NOTE THAT THE MSGPRIORITY IS A BYTE QUANTITY. IF THE HIGH BYTE IS
NONZERO, THE MESSAGE DATA ADDRESS IS ASSUMED TO FOLLOW THE FIRST
PART OF THE MESSAGE HEADER, AND THE MESSAGE DATA ITSELF MAY APPEAR
ANYWHERE IN A TASK'S VIRTUAL ADDRESS SPACE. ^NO MESSAGE SHOULD BE
MORE THAN 300 (DECIMAL) WORDS LONG, AND IT IS BEST TO RESTRICT IT
TO 256. WORDS IF FEASIBLE. ^THE ADDITIONAL CAPACITY IS PRESENT TO
ALLOW PROTOCOL LAYERS TO BE ADDED.
.PAGE
.SUBTITLE <MSGIN
.CENTER
<MSGIN
.SKIP 3
.PARAGRAPH
^THE <MSGIN DIRECTIVE IS USED TO RECEIVE MESSAGES WHEN A TASK
HAS NOT SPECIFIED AN <AST ENTRY TO RECEIVE THEM. ^IT <MUST BE
USED WITH THE <MSGFRE DIRECTIVE TO FREE THE MESSAGE SPACE, BUT
SIMPLY MAKES THE MESSAGE AVAILABLE BY FILLING IN THE ARGUMENTS
WHOSE ADDRESSES ARE GIVEN IN THE "<MSGLEN" AND "<MSGADR"
MACRO ARGUMENTS WITH THE MESSAGE BYTE COUNT AND ADDRESS IN TASK
VIRTUAL SPACE. ^THE "<MSGSTT" ARGUMENT IS USED FOR STATUS AND
MUST BE PRESENT AS THE ADDRESS OF A STATUS WORD.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^MSGIN ##_#MSGLEN,_#MSGADR,_#MSGSTT\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#13.
^THE TASK MAY SET UP AN <AST ENTRY (^ASYNCHRONOUS ^SYSTEM ^TRAP)
IN ITS <AST CONTROL BLOCK, USING <MODSTT, TO GAIN CONTROL VIA AN
<AST UPON RECEIPT OF A MESSAGE SO THAT THE <MSGIN DIRECTIVE IS
NOT NEEDED. ^THE <AST WILL RETURN THE MESSAGE STATUS, ADDRESS,
AND SIZE ON THE STACK AT THE <AST ENTRY SUCH THAT 4(<SP) IS THE
STATUS, 2(<SP) IS THE ADDRESS OF THE DATA, AND 0(<SP) IS THE
MESSAGE LENGTH. ^THE <AST NOTIFICATION IS IN ADDITION TO THE
^EVENT ^VARIABLE NOTIFICATION OF MESSAGE RECEIPT, BUT IS
STRICTLY COMPLEMENTARY TO THE USE OF <MSGIN / <MSGFRE.
.PAGE
.SUBTITLE <WSIG
.CENTER
<WSIG
.SKIP 3
.PARAGRAPH
^THE <WSIG MACRO IS USED TO WAIT FOR A SIGNIFICANT EVENT. ^THIS
CAUSES THE TASK TO WAIT UNTIL THE NEXT <ATL SCAN, AT WHICH TIME
THE TASK IS ACTIVATED AGAIN. ^THIS ALLOWS A TASK TO CHECK WAIT
CONDITIONS AND RETURN THE <CPU TO OTHER TASKS IN AN ORDERLY
WAY.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
<WSIG
.SKIP 1
^THIS CALL USES <TRAP#14.
.PAGE
.SUBTITLE <ABORT
.CENTER
<ABORT
.SKIP 3
.PARAGRAPH
<ABORT FORCES A TASK NAMED IN THE DIRECTIVE TO EXIT, WITH ALL ITS
SPAWNED TASKS. ^ONLY THE NAME OF THE TASK TO BE ABORTED IS PASSED.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
<ABORT##<TASKNAME
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#15.
.PAGE
.SUBTITLE <ALTGBL
.CENTER
<ALTGBL
.SKIP 3
.PARAGRAPH
^THE <ALTGBL DIRECTIVE PROVIDES A POWERFUL (IF NONSTRUCTURED) CAPABILITY
TO THE SYSTEM TO ALTER AN EVENT VARIABLE IN ANY TASK'S SPACE, OR THE
SYSTEM'S SPACE, INDEPENDENT OF <CPU. ^IF THE "<TASKNAME" ARGUMENT
IS FILLED IN WITH -1, ^KERNEL IS ASSUMED AND EXECUTIVE VARIABLES WILL
BE ALTERED. ^OTHERWISE, THE TASK GIVEN IS MODIFIED. ^THE AMOUNT
SPECIFIED WILL BE ADDED TO THE <EV UNLESS 0 IS SPECIFIED, AT WHICH
POINT 1 WILL BE ADDED. ^NOTE THAT THE ADDRESS, IN THE VIRTUAL ADDRESS
SPACE OF KERNEL OR THE TASK, IS UNCHECKED, SO THIS DIRECTIVE MUST BE
USED WITH <EXTREME CARE.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^ALTGBL##ADDRESS,TASKNAME,VALUE\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#16.
^ALL ARGUMENTS ARE LITERALS, NOT ADDRESSES OF LITERALS.
.PAGE
.SUBTITLE <MODSTT
.CENTER
<MODSTT
.SKIP 3
.PARAGRAPH
<MODSTT IS ANOTHER POWERFUL BUT UNSTRUCTURED DIRECTIVE USED TO
ALLOW A TASK TO MODIFY ITS OWN OR ANY OTHER TASK'S <TCB AND
AUXILIARY TABLES. ^THE "<CODE" ARGUMENT IS 0 FOR READ, 1 FOR
WRITE. ^IF THE <TASKNAME ARGUMENT IS FILLED WITH -1 OR
IF FILLED WITH 0, THE CALLING TASK IS ASSUMED; OTHERWISE THE
NAMED TASK IS USED IF IT EXISTS. ^THE <VALADR ARGUMENT IS THE
ADDRESS OF THE NUMBER TO WRITE TO THE <TCB OR THE PLACE TO
PUT THE INFORMATION FROM THE <TCB. <ID1 IS THE OFFSET FROM
THE START OF THE <TCB OF THE ITEM IN QUESTION (IN BYTES), AND
<ID2 IS THE INDEX INTO THE TABLE POINTED TO BY THE <TCB
IF THE <TCB POINTS TO A TABLE. ^NOTE THAT <ID2 IS ONLY USED
FOR TABLES OF INFORMATION, NOT FOR ENTRIES CONSTANT WITHIN
THE <TCB. ^HOWEVER, SUCH ENTRIES AS THE <EV ADDRESS ON WHICH
A TASK MAY BE WAITING ARE CONSIDERED TABLES.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^MODSTT CODE,VALADR,ID2,ID1,TASKNAME\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#17.
^THE FORMAT OF THE <TCB ENTRY IS AS FOLLOWS:
.LEFT MARGIN 10
.NOFILL
.TAB STOPS 10,15,20,25,30,35,40,45
.INDENT -6
^^<TCB:	.WORD <RAD50 TASK NAME (WORD)
.BREAK
	.BYTE FLAGS (1 IF EXITING)
.BREAK
	.BYTE STATUS
.BREAK
	.WORD TASK START ADDRESS
.BREAK
	.WORD INITIAL TASK <SP
.BREAK
	.WORD DYNAMIC TASK <SP
.BREAK
	.WORD SEGMENT NAME (<RSX BASED STARTUP ONLY)
.BREAK
	.WORD <APR AND TRAP TABLE ADDRESS
.BREAK
	.WORD <EV ADDRESS FOR WAITS
.BREAK
	.BLKW 16. ;IF STANDALONE <MSX ONLY
.BREAK
	;CONTAINING R5-R0, <APR0-7, <PS, <PC
.BREAK
	.BYTE <CPU NUMBER
.BREAK
	.BYTE BUS NUMBER
.BREAK
	.WORD TASK EXIT STATUS INFO.
.BREAK
	.WORD MSG QUEUE BLOCK ADDRESS
.BREAK
	.WORD <AST BLOCK ADDRESS
.BREAK
	.WORD SPAWN BLOCK ADDRESS
.BREAK
	.WORD ERROR <AST ENTRY ADDR
.BREAK
	.WORD SCRATCH CONTROL BLK ADDR
.BREAK
	.WORD KNL OR CALLER TASK'S <EV ADDR
.FILL
\\
.LEFT MARGIN 0
.PARAGRAPH
^SEE THE SOURCE OF <MXSTLS FOR FORMATS OF TABLES POINTED TO HERE.
^ONLY CRUDE RANGE CHECKS ARE PERFORMED  OF LEGALITY OF MODIFICATIONS.
^NOTE HOWEVER THAT WHERE, AS FOR EXAMPLE IN THE CASE OF AN ADDRESS
OF AN <EV TO NOTIFY ON MESSAGE RECEIPT, THE <STL (=^SYSTEM ^TASK
^LIST) ENTRY NEEDS AN ADDRESS, THE <MODSTT DIRECTIVE MUST BE GIVEN
THE ADDRESS OF THAT ADDRESS. ^THIS WILL CAUSE PROBLEMS IF NOT
CAREFULLY USED. ^IN GENERAL IT IS EXPECTED THAT <MODSTT WILL NOT BE
USED ITSELF, BUT THAT USERS WILL BE PERMITTED TO MODIFY CERTAIN
FIELDS ONLY VIA OTHER MACROS WHICH WILL USE THE <MODSTT MECHANISM
WITH FIXED OFFSETS BUILT IN, PERHAPS SYMBOLICALLY, TO AVOID USER
ERROR. ^SUCH MACROS SHOULD BE AWARE OF THE CHARACTERISTICS OF THE
SYSTEM'S DATA BASE IN THIS PARTICULAR.
\\
.PAGE
.SUBTITLE <LOCK
.CENTER
<LOCK
.SKIP 3
.PARAGRAPH
<LOCK WILL LOCK THE <MSX SCANNER TO PREVENT TASK SWITCHING UNTIL AN
<UNLOCK OCCURS. <USE <WITH <CARE.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
<LOCK
.SKIP 1
^THIS CALL USES <TRAP#20.
.PAGE
.SUBTITLE <UNLOCK
.CENTER
<UNLOCK
.SKIP 3
.PARAGRAPH
<UNLOCK FREES THE <MSX SCANNER AND ALLOWS TASK SWITCHING ON THE <CPU
WHERE CALLED AGAIN, UNDOING THE EFFECT OF A <LOCK.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
<UNLOCK
.SKIP 1
^THIS CALL USES <TRAP#21.
.PAGE
.SUBTITLE <PWAIT
.CENTER
<PWAIT
.SKIP 3
.PARAGRAPH
<PWAIT ALLOWS A TASK TO WAIT UNTIL AN <EVENT <VARIABLE (<EV) BECOMES
0 OR POSITIVE. ^IT IS OTHERWISE LIKE <WAIT. IN THAT THE <EV IS
ANYWHERE IN TASK SPACE, BUT ANY NEGATIVE VALUE IN THE <EV WILL
CAUSE IT TO CONTINUE TO WAIT.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^PWAIT EVADDRESS\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#22.
.PAGE
.SUBTITLE <ASTXIT
.CENTER
<ASTXIT
.SKIP 3
.PARAGRAPH
<ASTXIT IS USED TO EXIT FROM MESSAGE-IN <AST\S ONCE ALL ARGUMENTS ARE
PROCESSED. ^THE STACK MUST BE AS IT WAS ON <AST ENTRY.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
<ASTXIT
.SKIP 1
^THIS CALL USES <TRAP#23.
^NOTE THAT WHERE A MESSAGE IS RECEIVED VIA AN <AST RATHER THAN A <MSGIN,
THIS DIRECTIVE <MUST BE ISSUED TO COMPLETE THE PROCESSING  AND FREE THE
MESSAGE'S WORK AREA. ^THE TWO MECHANISMS ARE STRICTLY COMPLEMENTARY, SO
THAT IF A MESSAGE HAS BEEN RECEIVED VIA AN <AST, IT <MUST <NOT BE
THE  SUBJECT OF A <MSGIN (AND CANNOT BE). ^WHEN OTHER <AST ENTRIES ARE
PENDING AT THE END OF A MESSAGE, THE TASK WILL BE PLACED IN ANOTHER
<AST STATE AND THE NEXT <AST WILL BE QUEUED TO THE TASK. ^THE <AST
PENDING STATE IS AN ACTIVE TASK STATE, BUT BE AWARE THAT HIGHER PRIORITY
TASKS WILL BE SERVICED <BEFORE A TASK IN AN <AST STATE IF THEY ARE
ACTIVE AND RUNNABLE. ^THIS DIFFERS FROM THE <RSX PHILOSOPHY, AND SHOULD
BE NOTED FOR THOSE FAMILIAR WITH <RSX-11.
.PAGE
.SUBTITLE <KWAIT
.CENTER
<KWAIT
.SKIP 3
.PARAGRAPH
<KWAIT ACTS LIKE <WAIT. BUT THE <EV ADDRESS IS IN THHE <MSX EXECUTIVE'S
SPACE, NOT THE TASK'S.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^KWAIT EVADDRESS\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#24.
^NOTE THAT THIS CALL ONLY CHECKS THE EXECUTIVE'S SPACE IN THE <CPU
WHERE IT IS RUNNING. ^TASKS EXECUTING ELSEWHERE WILL BE ONLY IN
STATES 4 (RUNNING) OR 0 (EXITED), AND THEIR VOLATILE INFORMATION
WILL NOT BE AVAILABLE IN ANOTHER <CPU.
.PAGE
.SUBTITLE <MSGFRE
.CENTER
<MSGFRE
.SKIP 3
.PARAGRAPH
<MSGFRE IS CALLED AFTER A MESSAGE THAT WAS RECEIVED VIA THE <MSGIN
DIRECTIVE HAS BEEN PROCESSED AND BEFORE ANY NEW <MSGIN\S ARE PROCESSED.
^IT FREES THE MESSAGE AREA FOR REUSE BY THE <MSX SYSTEM.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^MSGFRE _#MSGLEN,_#MSGADR\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#25.
<MSGLEN AND <MSGADR ARE THE ADDRESSES OF THE MESSAGE LENGTH AND
ADDRESS POINTERS RETURNED BY <MSGIN. ^DO NOT USE THIS DIIRECTIVE
IF THE MESSAGE WAS RECEIVED VIA AN <AST; USE THE <AST EXIT DIRECTIVE
INSTEAD.
.PAGE
.SUBTITLE <XASTX
.CENTER
<XASTX
.SKIP 3
.PARAGRAPH
<XASTX IS USED TO EXIT FROM THE <AST CAUSED (WHEN SPECIFIED) BY THE
<EXIT. OF A SPAWNED TASK (VIA THE  <EXIT. DIRECTIVE OR VIA THE
<ABORT DIRECTIVE). ^IT FREES THE TASK TO RECEIVE ANOTHER <AST IF
ONE IS PENDING.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
<XASTX
.SKIP 1
^THIS CALL USES <TRAP#26.
^THIS DIRECTIVE FREES THE TASK FROM THE <AST AND PERMITS FURTHER
EXIT <AST\S TO OCCUR IF ANY MORE ARE PENDING. ^THIS DIRECTIVE IS
NEEDED AT THE END OF EXIT NOTIFICATION BECAUSE THE INFORMATION
ON THE STACK IS DIFFERENT FROM A MESSAGE'S <AST, NAMELY
THE EXITING TASK'S EXIT STATUS AT 4(<SP), ITS <TCB ADDRESS
AT 2(<SP), AND ITS <CPU NUMBER AT 0(<SP)

.PAGE
.SUBTITLE <ALTP
.CENTER
<ALTP
.SKIP 3
.PARAGRAPH
<ALTP IS USED TO ALTER A TASK'S RELATIVE PRIORITY ON THE <CPU WHERE
IT IS ACTIVE. ^THESE PRIORITIES RANGE FROM 1 TO 255. AND ARE INITIALLY
IN THE ORDER OF THE <STL, WITH HIGH PRIORITY MEANING A TASK HAS FIRST
CLAIM ON THE <CPU. ^THE DIRECTIVE HAS NO CROSS-<CPU EFFECT.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^ALTP NEWPRIORITY,TASKNAME\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#27.
^BE AWARE THAT IF THE TASK ENTERS A WAITING STATE, LOWER PRIORITY
TASKS WILL STILL RUN EVEN AFTER AN <ALTP.
.PAGE
.SUBTITLE <KPWAIT
.CENTER
<KPWAIT
.SKIP 3
.PARAGRAPH
^THE <KPWAIT DIRECTIVE PUTS A VALUE IN AN <EV IN KERNEL SPACE IN THE
CALLING <CPU AND WAITS UNTIL IT BECOMES 0 OR POSITIVE. ^IF THE <EV
ADDRESS IS GIVEN AS 0, THE ADDRESS WILL BE INSERTED OF A VARIABLE
INCREMENTED EVERY SECOND BY THE <MSX CLOCK ROUTINE, PERMITTING
TASKS TO WAIT FOR N SECONDS WITH THIS DIRECTIVE. ^ANY OTHER
<EV MAY BE WAITED FOR, HOWEVER, IF ITS ADDRESS IS KNOWN.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^KPWAIT VALUE-TO-START-IN-<EV,EV-ADDRESS\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#30.
.PAGE
.SUBTITLE <ORGWAT
.CENTER
<ORGWAT
.SKIP 3
.PARAGRAPH
<ORGWAT ALLOWS A TASK TO WAIT UNTIL ANY OF A SET OF <EV\S IN
ITS SPACE BECOME POSITIVE AND NONZERO. ^IT OTHERWISE IS LIKE
<ORWAIT EXCEPT THAT THE VARIABLES MUST BE POSITIVE FOR THE
WAIT TO END, NOT SIMPLY NONZERO. ^THIS PERMITS SOMEWHAT GREATER
FLEXIBILITY TO THE TASK, WHICH CAN MAP OVER THE <MSX EXECUTIVE
SPACE IF DESIRED TO WAIT FOR THE <MSX INTERNAL VARIABLES USED
TO INDICATE MESSAGE RECEIPT BY OTHER TASKS. (^NORMAL USE OF
<ORGWAT WILL BE LESS EXOTIC THAN THIS.)
^NORMALLY, ONE WILL USE <TWAIT FOR SYNCHRONIZATION HOWEVER.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^ORGWAT EVTABADDRESS\\
.SKIP 1
^THIS CALL PUSHES ARGS IN REVERSE ORDER AND USES <TRAP#31.
.PAGE
.SUBTITLE <TWAIT
.CENTER
<TWAIT
.SKIP 3
.PARAGRAPH
<TWAIT IS A CONDITIONAL WAIT DESIGNED FOR USE WITH EVENT VARIABLES
THAT ARE SET OR CLEARED FROM OTHER TASKS. ^IT <MUST BE USED TO AVOID
DEADLOCK WHERE INTERTASK SYNCHRONIZATION IS TO BE PERFORMED. ^THIS
FORM OF WAIT WILL FALL THROUGH WHERE EITHER THE WAIT IS SATISFIED OR
THE NAMED TASK EXITED (ENTERED STATE 0). ^IN THE CASE WHERE THE TASK
EXITED, THE <EV MAY BE EXAMINED TO DETERMINE THAT A TASK FAULT CAUSED
THE WAIT END. ^A VARIETY OF WAIT TYPES ARE AVAILABLE, AND IF <MULT15
IS DEFINED AT ASSEMBLY OF <MSX, THE TABLE PASSED MAY CONTAIN MULTIPLE
ENTRIES, ANY OF WHICH CAN SATISFY A WAIT.
.PARAGRAPH
^THE FORMAT OF THE CALL IS:
.SKIP 1
.INDENT 5
^^TWAIT TABLEADDRESS\\
.SKIP 1
^THIS CALL PUSHES THE ADDRESS AND ISSUES <TRAP#32. ^THE TABLE FORMAT IS
AS FOLLOWS:
.SKIP 2
^^
.INDENT 5
TABLE:##.WORD##EV#ADDRESS
.INDENT 5
########.WORD##TASKNAME
.INDENT 5
########.WORD##MASK
.INDENT 5
########.WORD##CONDITION
\\
.PARAGRAPH
^THE TASKNAME GIVEN DETERMINES WHEN THE WAIT WILL END ON TASK EXIT.
^THE MASK IS <AND\\ED WITH THE ^EVENT ^VARIABLE PRIOR TO TESTING.
^A ZERO MASK WILL BE IGNORED. ^THE CONDITION DETERMINES THE TYPE OF
WAIT. ^IF IT IS 0, THE WAIT AWAITS THE <EV NONZERO. ^IF <COND IS
-1, THE WAIT AWAITS THE <EV BECOMING LESS THAN 0. ^IF <COND IS
+1, THE WAIT AWAITS THE <EV BECOMING GREATER THAN 0. ^OTHERWISE,
THE WAIT AWAITS THE <EV BECOMING ZERO. ^IF <MULT15 IS CONDITIONED IN
WHEN <MXSCNS IS ASSEMBLED, THERE MAY BE MANY ENTRIES OF THIS FORM,
WITH THE LIST TERMINATED BY AN ENTRY CONTAINING ALL ZEROES. ^BE SURE
IN THAT CASE THAT THE TERMINATOR <IS PRESENT.
.PAGE
.SUBTITLE ^SUBSIDIARY ^CONTROL ^BLOCKS
.CENTER
^SUBSIDIARY ^CONTROL ^BLOCKS
.PARAGRAPH
^THE ADDITIONAL CONTROL BLOCKS REFERRED TO IN THE
<MODSTT MACRO HAVE THE FORMATS AS FOLLOWS:
.SKIP 2
.NOFILL
.TAB STOPS 1,5,10,15,20,25,30,35,40,45,50
^^
	FORMATS OF THE ADDITIONAL BLOCKS:

QUEUE BLOCK:
	NO. MESSAGES IN (WORD)
	INPUT MESSAGE FIRST ENTRY (QUEUE)
	INPUT MESSAGE LAST ENTRY (QUEUE)
	NO. MESSAGES OUT (WORD)
	OUTPUT MESSAGE QUEUE START
	OUTPUT MESSAGE QUEUE TAIL
	ADDRESS OF MESSAGE IN COUNT COPY IN TASK SPACE
	ADDRESS OF MESSAGE OUT COUNT COPY IN TASK SPACE

SPAWN TABLE:
	CALLER TASK NAME OR NUMBER
	CALLED TASK NAME OR NUMBER #1 (0 IF EMPTY)
	CALLED TASK NAME OR NUMBER #2 (0 IF EMPTY)
	.
	.
	.
	CALLED TASK NAME OR NUMBER #15 (0 IF EMPTY)

SCRATCH AREA CONTROL:
	PERMANENT BITMAP CONTROL BLOCK ADDRESS
	WORKING BITMAP CONTROL BLOCK ADDRESS
	STARTING NODE ADDRESS IN TASK (LIST HEADER A)
	ENDING   NODE ADDRESS IN TASK (LIST HEADER B)
	SPARE FOR CLOCK COUNTER (BUMPED EVERY SECOND)
	CLOCK VALUE TO ABORT AT OR 0 IF NO TIMEOUT
	SAVE AREA FOR OLD TASK STATUS DURING AST

BITMAP CONTROL BLOCKS ARE OF FORM (BOTH FOR WORKING COPY ADDR'S):

BCB:	NODE SIZE IN WORDS PER BIT OF BITMAP
	ADDR OF TOP OF BUFFER ADDRESS
	TOP OF BUFFER ADDRESS (POINTED AT BY PREVIOUS WORD)
	START ADDRESS OF NODE POOL USED (TSK MSG AREA)
	BITMAP START ADDRESS
	BITMAP END ADDRESS
	TOP ADDRESS OF NODE POOL USED

AST CONTROL BLOCK:
	MESSAGE-IN AST ENTRY ADDRESS (OR 0)
	MESSAGE-IN AST NUMBER PENDING AST'S
	MESSAGE-IN AST QUEUE HEAD
	MESSAGE-IN AST QUEUE TAIL
	EXIT-WITH-STATUS AST ENTRY ADDRESS (OR 0)
	EXIT-WITH-STATUS AST NUMBER PENDING AST'S
	EXIT-WITH-STATUS AST QUEUE HEAD
	EXIT-WITH-STATUS AST QUEUE TAIL

AN AST ENTRY HAS THE FORM:
	FORWARD POINTER
	BACKWARD POINTER
	STATUS WORD (FROM EXIT STATUS OR EV ADR IN CALLER FOR MSG IN)
	INFORMATION WORD 1 (MSG ADDR OR TASK NUMBER)
	INFORMATION WORD 2 (MSG BYTE COUNT OR TASK CPU/BUS #)
	PRIORITY OF AST
	MSG DATA HDR ADDR IN USER SPACE (HEADER FROM MSG DATA)

\\
.FILL
.PAGE
.SUBTITLE
.PARAGRAPH
^TASKS MAY BE PRIORITIZED IN <MSX BY A LIST NOT POINTED TO BY THE
<STL (^SYSTEM ^TASK ^LIST) (WHICH IS COMPOSED OF ^TASK ^CONTROL
^BLOCKS - <TCB\S). ^THIS LIST IS PRESENT ONLY WHEN <MSX IS ASSEMBLED
WITH <VARPRI DEFINED AND IS NAMED ^^MX.PRL\\.
^THIS LIST IS A DOUBLE ENDED QUEUE WHOSE 4 WORD ENTRIES ARE THE
FORWARD AND BACKWARD POINTERS FOR LINKAGE, THE <TCB ADDRESS OF
THE TASK, AND THE PRIORITY OF THE TASK. ^THE LIST IS CHANGED BY
THE <ALTP DIRECTIVE AND MACRO. ^AN ADDITIONAL LIST IS AVAILABLE IF
<CMNTCB IS DEFINED, WHICH SHOULD BE WHENEVER THE <TCB IS IN SHARED
MEMORY. ^THIS TABLE, <TCBFGS, IS USED TO DETERMINE WHEN  A <TCB BLOCK
MAY BE ACQUIRED BY A SINGLE <CPU FOR ITS (TEMPORARY) EXCLUSIVE USE.
^A "SPIN LOCK"  MECHANISM IS USED, AND THE LIST "<OWNCPU" CONTAINS
THE <CPU NUMBER OWNING A <TCB ENTRY AT ANY TIME. (^THIS ALLOWS A
<CPU TO MAKE MULTIPLE CALLS TO ACQUIRE A <TCB, AND WILL HELP RECOVER
SHOULD ONE <CPU GO DOWN.)
.PARAGRAPH
^THE STAND-ALONE <MSX HAS ^I/^O DRIVERS THAT RESEMBLE THE OLD <DOS-11
DRIVERS. ^THE FORMATS OF THE NECESSARY CONTROL BLOCKS ARE FOUND IN
THE <MXTRPS SOURCE CODE. ^HOWEVER, IF THESE ARE ASSEMBLED IN THE
DEFAULT WAY, THEY ACCEPT ANY BYTE COUNT, RATHER THAN THE WORD COUNT
<DOS-11 ASSUMED. ^THE KEYBOARD HANDLER HAS A FEATURE THAT THE FIRST
BYTE OF AN INPUT BUFFER, IF PRESENT, MAY BE PRINTED AS A PROMPT AS
PART OF AN INPUT TRANSACTION AUTOMATICALLY. ^THIS FEATURE IS
CONDITIONALLY ASSEMBLED IN <MXKBDRV. ^IT EXISTS TO MAKE IT
EASIER TO IDENTIFY WHICH OF (POSSIBLY) SEVERAL TASKS IS TRYING
TO DO INPUT AT A GIVEN MOMENT WHERE MANY READS MAY BE OUTSTANDING.
^THE <DEC\\TAPE DRIVER GIVEN IS AN EXAMPLE FOR THE OLD <DEC\\TAPE
DEVICE, A SMALL DISK-LIKE TAPE. ^IT IS AN EXAMPLE ONLY. <MSX DOES
NOT ACCOMMODATE (PRESENTLY) LARGE DISKS, HAVING ONLY 16 BITS OF
BLOCK NUMBERS TO USE. ^HOWEVER, THE DRIVERS ARE PASSED A POINTER
TO THE <TCB OF THE REQUESTING TASK, SO THEY HAVE ACCESS TO ANYTHING
IN THE <TCB DATA BASE. ^IT WOULD BE SIMPLEST TO ADD ANOTHER WORD OF
BLOCK NUMBER IN THAT AREA (IN THE SCRATCH CONTROL BLOCK PERHAPS)
SHOULD IT BE NEEDED. ^THE BYTE COUNT READ IS NORMALLY RETURNED IN
THE ^EVENT ^VARIABLE IN STANDALONE <MSX, WITH NEGATIVE CODES
RETURNED IF ERRORS HAPPEN. ^IN THE <RSX BASED VERSIONS, THE
SECOND WORD OF THE ^EVENT ^VARIABLE GETS THE NUMBER OF BYTES
TRANSFERRED.