NORD PL Developer Guide¶

A Comprehensive Introduction to NORD Programming Language for Developers

Version: 1.2
Last Updated: October 17, 2025
What's New: Chapter 12 - Practical Development Workflow with Hello World example, compilation, and testing guide

📍 Note: The complete SINTRAN III Kernel Documentation has been moved to the GitHub repository:
Location: SINTRAN\OS\
GitHub: https://github.com/[your-username]/NDInsight

For kernel internals, device drivers, memory management, and other OS-level documentation, please refer to the GitHub repository. This guide focuses on NPL language development.

Table of Contents¶

NPL Fundamentals & Philosophy
Basic Syntax & Data Types
Variables & Memory Layout
Subroutines & Memory Organization
Control Flow
Register Usage
Global Memory Access
Addressing Modes & Memory References
Arrays & Data Structures
Compiler Directives
Code Organization & Linking
Practical Development Workflow ⭐ NEW in v1.2 - 12.1 Hello World Example - 12.2 Creating the Source File - 12.3 Compiling with NPL - 12.4 Assembling with MAC - 12.5 Creating an Executable - 12.6 Running Your Program - 12.7 Common Errors and Solutions - 12.8 Development Tips
Common Patterns & Idioms
Real-World Patterns from SINTRAN ⭐ NEW in v1.1 - 14.1 Interrupt Handler Patterns - 14.2 Queue Manipulation Patterns - 14.3 Memory Management Patterns - 14.4 Device Driver Patterns - 14.5 Error Handling Patterns - 14.6 Multi-CPU Communication Patterns - 14.7 Optimization Patterns - 14.8 Debugging Patterns - 14.9 Code Organization Patterns - 14.10 Safety Patterns

Installing NPL¶

NPL (NORD-PL) ships as part of Subsystem Package II (ND-210400), Norsk Data's standard developer-tools bundle for SINTRAN III — the same package that provides MAC (NPL compiles down to MAC assembly) and the QED editor. Install that product first if NPL is not already on the system — full procedure (floppy, prerequisites, the @DUMP-REENTRANT addresses for every module, and how to keep it loaded across a cold start) is in ND-210400B — Subsystem Package II, version B.

1. NPL Fundamentals & Philosophy¶

1.1 What is NORD PL?¶

NORD PL (NORD Programming Language) is a machine-oriented medium-level language designed for the NORD-1 and NORD-10 computers. It stands between assembly code and high-level languages like FORTRAN or COBOL.

Key characteristics: - System programming language - Used to write SINTRAN III operating system, compilers, and device drivers - Direct hardware access - Full access to all registers, memory locations, and I/O operations - Readable assembly - More readable than MAC assembly but with similar efficiency - ALGOL-like syntax - Familiar control structures with machine-level power - Single-pass compilation - Compiles to MAC assembler source code

1.2 Design Philosophy¶

IMPORTANT: NORD PL is NOT a problem-oriented high-level language. It is a machine-oriented medium-level language. When writing any statement, you must always consider the influence on register contents!

Core principles: 1. Efficiency - Generate optimal object code equivalent to hand-written assembly 2. Control - Programmer has complete control over hardware 3. Readability - Code should be more maintainable than pure assembly 4. Flexibility - No fixed calling sequences or data structures 5. Transparency - Every NPL statement maps clearly to MAC instructions

1.3 When to Use NORD PL¶

Ideal for: - Operating system kernels and device drivers - Compilers and interpreters - Real-time control systems - Network protocol stacks - Performance-critical system code

Not ideal for: - Business applications (use COBOL) - Scientific computing (use FORTRAN) - General application programming

1.4 Prerequisites¶

Before learning NORD PL, you should understand: - MAC Assembly Language addressing structure - NORD-10 computer architecture - Register operations and addressing modes - Binary/octal number systems

2. Basic Syntax & Data Types¶

2.1 Identifiers¶

An identifier is a string of digits and letters where only the first 5 characters are significant. At least one of the first 5 characters must be a letter.

% Valid identifiers:
NEW
LOOP
INT2
1A
450 SLC       % Only "450 S" is significant
J2
1976 SALARY   % Only "1976 " is significant (includes space)

2.2 Reserved Identifiers¶

Reserved words include operators, statement symbols, and register names. See Appendix A for complete list.

Common reserved words: - Data types: INTEGER, DOUBLE, REAL, TRIPLE, ARRAY, POINTER - Control: IF, THEN, ELSE, FI, FOR, DO, OD, WHILE, GO, EXIT - Subroutines: SUBR, RBUS, CALL - Memory: BASE, ESAB, DISP, PSID - Registers: A, B, D, L, P, T, X, AD, TAD, K, Z

2.3 Data Types¶

2.3.1 Integer Variables (16-bit)¶

INTEGER INT1, INT2           % Two 16-bit integers initialized to 0
INTEGER TRE:=3               % Initialize to value 3
INTEGER COUNT:=0, MAX:=100   % Multiple initializations

MAC equivalent:

INT1, 0
INT2, 0
TRE, 3
COUNT, 0
MAX, 100

2.3.2 Double Variables (32-bit)¶

DOUBLE SYM                   % 32-bit value, initialized to 0
DOUBLE LONGVAL:=12345        % Initialize to value

MAC equivalent:

SYM, 0, 0
LONGVAL, [12345             % Uses octal representation

2.3.3 Real Variables (Floating Point)¶

REAL PI:=3.1415              % 48-bit floating point
REAL TEMP                     % Initialized to 0.0

MAC equivalent:

PI, [3.1415
TEMP, 0, 0, 0

2.3.4 Triple Variables (48-bit)¶

TRIPLE BIGNUM                % 48-bit integer

MAC equivalent:

BIGNUM, 0, 0, 0

2.3.5 Pointers¶

Pointers are 16-bit addresses pointing to variables. The pointer type indicates what it points to:

INTEGER POINTER PVAR:=VAR    % Points to an integer variable
DOUBLE POINTER DPTR          % Points to a double variable
REAL POINTER RPTR:=REALVAR   % Points to a real variable
TRIPLE POINTER TPTR          % Points to a triple variable

MAC equivalent:

PVAR, VAR
DPTR, 0
RPTR, REALVAR
TPTR, 0

Key point: A pointer is always 16 bits, regardless of what it points to. The type declaration tells the compiler how to dereference it.

2.4 Constants¶

2.4.1 Numeric Constants¶

% Decimal (default)
A:=100               % Decimal 100
A:=255               % Decimal 255

% Octal (using backtick or special prefix)
A:=`377              % Octal 377 (= decimal 255)
A:=377               % Usually interpreted as decimal unless context

% Negative
A:=-50               % Negative value

2.4.2 Character Constants¶

A:=##A               % Character 'A' (ASCII code)
A:=##0               % Character '0'

2.4.3 String Constants¶

INTEGER ARRAY TEXT:='STRING'   % Store string in memory

MAC equivalent:

TEXT, 'STRING'

2.5 Symbolic Constants¶

SYMBOL MAXSIZE=1000
SYMBOL L200=200, L210=L200+10
SYMBOL S0, S1, S2, S3         % S0=0, S1=1, S2=2, S3=3

Symbolic constants: - Do not allocate memory - Evaluated at compile time - Cannot be changed at runtime - Similar to C #define

3. Variables & Memory Layout¶

3.1 Variable Addressing Attributes¶

Every variable has ONE of four addressing attributes:

Attribute	Declared In	Addressing Mode	Access Method
Global	Outside SUBR-RBUS, BASE-ESAB, DISP-PSID	Indirect P-relative	`LDA I (VAR)`
Local	Inside SUBR-RBUS	Direct P-relative	`LDA VAR`
Base	Inside BASE-ESAB	B-relative	`LDA VAR,B`
Disp	Inside DISP-PSID	B-relative (symbolic displacement)	`LDA VAR,B`

3.2 Global Variables¶

Declared outside any subroutine, accessed indirectly:

% Outside any subroutine
INTEGER GVAR1, GVAR2
DOUBLE GLOBALD

SUBR ROUTINE
    % Access global variables
    ROUTINE: A:=GVAR1 + GVAR2
    EXIT
RBUS

MAC equivalent:

GVAR1, 0
GVAR2, 0
GLOBALD, 0, 0

ROUTINE, LDA I (GVAR1)
         ADD I (GVAR2)
         EXIT
         )FILL

Important: Global pointers can be accessed, but you cannot access through a global pointer (would require double-indirect addressing which is not supported).

3.3 Local Variables¶

Declared inside SUBR-RBUS, accessed directly:

SUBR CALCULATE
INTEGER LOCAL1, LOCAL2, RESULT
CALCULATE: LOCAL1 * LOCAL2 =: RESULT
           EXIT
RBUS

MAC equivalent:

LOCAL1, 0
LOCAL2, 0
RESULT, 0
CALCULATE, LDA LOCAL1
           MPY LOCAL2
           STA RESULT
           EXIT
           )FILL
           )KILL LOCAL1 LOCAL2 RESULT

Key advantage: Direct addressing is faster and uses shorter instructions. Local variables are automatically "killed" (removed from symbol table) after RBUS.

3.4 Memory Layout: Why Variables Come First¶

Critical design principle: In NORD-10, direct P-relative addressing has a limited range (256 words forward/backward from PC).

Best practice for subroutines:

SUBR EXAMPLE
% ============================================
% DECLARE ALL LOCAL VARIABLES FIRST!
% ============================================
INTEGER VAR1, VAR2, VAR3
INTEGER TEMP, COUNT
DOUBLE RESULT
% ... all other variables ...

% ============================================
% NOW THE CODE
% ============================================
EXAMPLE:
    % Code here can access all variables within
    % the P-relative addressing window
    A:=VAR1 + VAR2
    % ...
    EXIT
RBUS

Why this matters: - Variables are allocated sequentially in memory - Code follows after variables - P-relative addressing has ±256 word range - If variables are scattered throughout code, some become unreachable - Delta addressing calculations fail if variables are beyond P-relative range

Real example from SINTRAN source:

SUBR SINTR, TTMMAP
% All variables and arrays declared here at the top
INTEGER XR, CCBTST(0)
TRIPLE TRARDR
INTEGER POINTER FFLLREG

% Then comes the code
SINTR: 
    % Implementation...
    EXIT
RBUS

4. Subroutines & Memory Organization¶

4.1 Subroutine Structure¶

SUBR ENTRYPOINT1, ENTRYPOINT2, ENTRYPOINT3
    % Variables declared here (LOCAL scope)
    INTEGER VAR1, VAR2
    DOUBLE TEMP

    % Code for entry point 1
    ENTRYPOINT1:
        % ... implementation ...
        EXIT

    % Code for entry point 2
    ENTRYPOINT2:
        % ... implementation ...
        EXIT

    % Code for entry point 3
    ENTRYPOINT3:
        % ... implementation ...
        EXIT
RBUS

Key points: 1. SUBR starts the subroutine, lists all entry points (global labels) 2. Variables declared after SUBR are local to that subroutine 3. Entry points are global and can be called from anywhere 4. RBUS ends the subroutine (generates )FILL and )KILL directives) 5. Only one level of subroutines (no nested SUBR declarations)

4.2 Calling Subroutines¶

% Simple call
CALL SUBROUTINE

% Conditional call
IF condition THEN CALL SUBROUTINE FI

% Call with link register save (manual)
SUBR CALLER
INTEGER POINTER RETUR
CALLER: 
    A:=L:="RETUR"        % Save return address
    CALL OTHERSUBR
    EXIT
RBUS

4.3 Returning from Subroutines¶

EXIT                 % Return to caller (JMP through L register)

4.4 Label Declarations¶

SUBR PROCESS
    % Entry point (global label)
    PROCESS:
        GO LOOP

    % Local label (only visible in this subroutine)
    LOOP:
        % ... code ...
        IF condition THEN GO LOOP FI
        EXIT
RBUS

Entry points vs local labels: - Entry points: Declared in SUBR statement, global, can be called from anywhere - Local labels: Declared with LABEL:, local to subroutine, killed at RBUS

5. Control Flow¶

5.1 Unconditional Branch¶

GO LABEL             % Jump to LABEL
GO FAR LABEL         % Far jump (indirect): JMP I (LABEL)

5.2 Conditional Branching¶

5.2.1 IF Statements¶

% Simple IF
IF condition THEN
    % true branch
FI

% IF-ELSE
IF condition THEN
    % true branch
ELSE
    % false branch
FI

% Nested IF
IF condition1 THEN
    IF condition2 THEN
        % both true
    FI
ELSE
    % condition1 false
FI

5.2.2 Conditions¶

% Register comparisons
IF A=0 THEN ...  FI             % A zero?
IF A><0 THEN ... FI             % A not zero?
IF A<0 THEN ... FI              % A negative?
IF A>0 THEN ... FI              % A positive?
IF A>=0 THEN ... FI             % A non-negative?

% Variable comparisons
IF VAR1-VAR2=0 THEN ... FI      % VAR1 == VAR2?
IF VAR1-VAR2><0 THEN ... FI     % VAR1 != VAR2?
IF VAR1-VAR2<0 THEN ... FI      % VAR1 < VAR2?

% Complex conditions with explicit tests
A:=VAR1-VAR2
IF A<0 THEN ... FI

Real example from SINTRAN:

IF A><0 THEN
    A-1=:X:="ITB10"-"PITEX"
    X+A
    A:=MPIFPHPAGE SHZ 12
    X+A
    T:=MPIBANK
    *STZTX              % Clear entry
FI
EXIT

5.3 Loops¶

5.3.1 DO WHILE Loop¶

DO WHILE condition
    % loop body
OD

% Example
DO WHILE X<<D
    T:=RPIBANK
    *LDATX
    IF A-XA=0 THEN
        *STZTX
        EXIT
    FI
    X+1
OD

5.3.2 FOR Loop¶

FOR variable:=start, start+step UNTIL limit DO
    % loop body
OD

% Example
FOR I:=0, I+1 UNTIL 10 DO
    % Process element I
OD

5.4 Switch Statement (GOSW)¶

% A register contains index
A GOSW CASE0, CASE1, CASE2, CASE3

CASE0:
    % Handle case 0
    GO ENDSWITCH

CASE1:
    % Handle case 1
    GO ENDSWITCH

CASE2:
    % Handle case 2
    GO ENDSWITCH

CASE3:
    % Handle case 3
    % fall through

ENDSWITCH:

MAC equivalent:

RADD SA DP      % Add A to program counter
JMP CASE0
JMP CASE1
JMP CASE2
JMP CASE3

6. Register Usage¶

6.1 Register Overview¶

Register	Name	Size	Purpose
A	Accumulator	16-bit	Primary arithmetic register
D	D Register	16-bit	Secondary arithmetic register
T	T Register	16-bit	Temporary storage
X	Index Register	16-bit	Array indexing, address calculation
L	Link Register	16-bit	Return address storage
B	Base Register	16-bit	Base addressing for global data
P	Program Counter	16-bit	Instruction pointer
AD	Double Accumulator	32-bit	A and D combined
TAD	Triple Accumulator	48-bit	T, A, and D combined
K	Carry/Link bit	1-bit	Carry flag
Z	Zero flag	1-bit	Floating point overflow

6.2 Register Operations¶

6.2.1 Load Operations¶

% Load constant
A:=100                  % SAA 100
A:="0"                  % SAA 0 (quoted zero is a constant, not register)

% Load variable
A:=VAR                  % LDA VAR (local)
                        % LDA I (VAR) (global)

% Load from pointer
A:=PTR                  % LDA I PTR

% Register to register
A:=T                    % COPY ST DA
T:=X                    % COPY SX DT

6.2.2 Store Operations¶

% Store to variable
A =: VAR                % STA VAR (local)
                        % STA I (VAR) (global)

% Store to register
A =: T                  % COPY DA DT
D =: B                  % COPY DD DB

6.2.3 Swap Operations¶

% Swap two registers
A :=: T                 % SWAP SA ST
X :=: D                 % SWAP SX SD

6.3 Arithmetic Operations¶

% Addition
A + VAR                 % ADD VAR
A + 5                   % AAA 5
T + 3                   % AAT 3
X + 10                  % AAX 10

% Subtraction
A - VAR                 % SUB VAR
A - 5                   % AAA -5
T - 2                   % AAT -2

% Multiplication (integer and real only)
A * VAR                 % MPY VAR (integer)
TAD * RVAR              % FMU RVAR (real)

% Division (real only)
TAD / RVAR              % FDV RVAR

6.4 Logical Operations¶

% AND
A /\ VAR                % AND VAR (integer variable)
A /\ 177                % ANDA 177 (constant)
A /\ T                  % RAND SA ST (register)

% OR
A \/ VAR                % ORA VAR (integer variable)
A \/ 100                % ORA 100 (constant)
A \/ D                  % RORA SA SD (register)

% XOR
A XOR T                 % REXO SA ST

% One's complement
A —                     % COPY DA SA CM1

% Two's complement
A —                     % COPY DA SA CM2

6.5 Shift Operations¶

% Shift with zero fill
A SHZ 2                 % SHA ZIN 2 (left)
A SHZ -3                % SHA ZIN SHR 3 (right)

% Arithmetic shift
A SH 4                  % SHA ART 4

% Rotate
A SHR 2                 % SHA ROT 2

% Shift with link
A SHL 1                 % SHA LIN 1

6.6 Bit Operations¶

% Set bit
A BONE 5                % BSET ONE 5 DA

% Clear bit
A BZERO 7               % BSET ZRO 7 DA

7. Global Memory Access (B and X Registers)¶

7.1 The B Register (Base Register)¶

The B register is used for accessing global data structures that are not directly P-relative addressable. It holds a base address, and variables are accessed as offsets from this base.

7.1.1 BASE Variables¶

% Define a BASE field
BASE DATAFIELD
    INTEGER VAR1, VAR2
    INTEGER POINTER PSUB:=SUBROUTINE
    INTEGER ARRAY TABLE(100)
ESAB

% Using BASE variables
SUBR PROCESS
PROCESS:
    "DATAFIELD" =: B           % Load base address into B
    A:=VAR1                    % LDA VAR1-DATAFIELD,B
    VAR1 + VAR2 =: TABLE(0)    % Operations with base variables
    EXIT
RBUS

MAC equivalent:

DATAFIELD = *+200
VAR1, 0
VAR2, 0
PSUB, SUBROUTINE
TABLE = *
* + 100/

PROCESS, LDA (DATAFIELD
         COPY SA DB
         LDA VAR1-DATAFIELD,B
         ADD VAR2-DATAFIELD,B
         STX TABLE-DATAFIELD,B
         EXIT

Key points: - BASE variables are static (allocated at compile time) - Must load B register before accessing BASE variables - Offset is calculated as VAR - BASEFIELD - Used for large data structures that don't fit in P-relative space

7.1.2 DISP Variables (Dynamic Displacement)¶

% Define displacement field (NO initialization allowed)
DISP -200
    INTEGER D1, D2
    INTEGER ARRAY DARR(10)
    INTEGER ENDA
PSID

% DISP with field identifier
DISP DV=10
    INTEGER NILS, PER
PSID                    % DV is now 12

% Continue the DISP field
DISP DV
    INTEGER EVA, BERIT
PSID                    % DV is now 14

MAC equivalent:

D1 = -200
D2 = -177
DARR = -176
ENDA = -166

NILS = 10
PER = 11

EVA = 12
BERIT = 13

Key points: - DISP variables are symbolic only (no memory allocated) - Used for dynamic data structures (runtime-allocated) - Programmer must set B register to point to actual data - No initialization allowed (data doesn't exist at compile time)

Real example from SINTRAN:

% Device Control Block (DCB) structure
DISP 0
    INTEGER MLINK           % Monitor link
    INTEGER MFUNC           % Monitor function
    INTEGER STATUS          % Device status
    INTEGER BUFFER          % Buffer pointer
PSID

% Later, when processing a device:
SUBR PROCESS_DEVICE
PROCESS_DEVICE:
    % B register already points to the DCB
    T:=STATUS               % LDT STATUS,B
    IF T<0 THEN
        % Handle error
    FI
    EXIT
RBUS

7.2 The X Register (Index Register)¶

The X register is primarily used for: 1. Array indexing 2. X-relative addressing (chaining through data structures) 3. Address calculations

7.2.1 Array Indexing¶

INTEGER ARRAY TABLE(100)
INTEGER IDX:=5

% X register is automatically used for indexing
A:=TABLE(IDX)           % X:=IDX; LDA TABLE,X
A:=TABLE(10)            % X:=10; LDA TABLE,X
A:=TABLE(A)             % LDX A; LDA TABLE,X

Key point: The compiler automatically uses X for array indexing.

7.2.2 X-Relative Addressing (Structure Chaining)¶

This is the most powerful feature for traversing linked data structures.

% Define a linked list element structure
DISP 0
    INTEGER NEXT            % Next element pointer (offset 0)
    INTEGER PRIOR           % Previous element (offset 1)
    INTEGER D1, D2, D3      % Data fields (offsets 2, 3, 4)
PSID

% Traverse through structure fields
SUBR ACCESS_ELEMENT
ACCESS_ELEMENT:
    % A points to first element

    % Get D1 from current element
    T := A.D1               % COPY SA DX; LDT D1,X

    % Get D3 from NEXT element
    T := A.NEXT.D3          % COPY SA DX; LDX NEXT,X; LDT D3,X

    % Get D3 from element two steps forward
    T := A.NEXT.NEXT.D3     % COPY SA DX; LDX NEXT,X; LDX NEXT,X; LDT D3,X

    EXIT
RBUS

How it works: 1. Value before first . → loaded into X 2. Values between dots → loaded into X using X-relative addressing 3. Value after last . → loaded into primary register using X-relative addressing

Real SINTRAN example (following execution queue):

% RT-Description structure
DISP 0
    INTEGER TLNK            % Thread link
    INTEGER STATE, PRIORITY
    % ... more fields ...
    INTEGER WLINK           % Waiting link
PSID

% Follow the queue
HEAD.WLINK.WLINK.STATE      % Get state of element 2 steps into queue

8. Addressing Modes & Memory References¶

8.1 Addressing Mode Summary¶

Mode	Syntax	MAC	Description
Direct	`VAR`	`LDA VAR`	Local variable, direct P-relative
Indirect	`VAR`	`LDA I (VAR)`	Global variable, indirect
B-relative	`VAR`	`LDA VAR,B`	BASE or DISP variable
X-relative	`X.VAR`	`LDA VAR,X`	Variable indexed by X
Indexed array	`ARR(X)`	`LDA ARR,X`	Array element
Pointer	`PTR`	`LDA I PTR`	Dereference pointer

8.2 The Quote Operator (`" "`)¶

Quotes dereference one level - they give you the address instead of the value.

INTEGER VAR:=100
INTEGER POINTER PTR:=VAR

% Without quotes (normal access)
A:=VAR                  % Get VALUE from VAR (100)
A:=PTR                  % Get VALUE that PTR points to (100)

% With quotes (get address)
A:="VAR"                % Get ADDRESS of VAR
A:="PTR"                % Get VALUE of PTR (which is an address)

Complete example:

INTEGER TRE:=3
INTEGER POINTER PP:=TRE

A:=3                    % SAA 3 (constant)
A:="3"                  % SAA 3 (same - constant)
A:=TRE                  % LDA TRE (value from variable)
A:="TRE"                % LDA (TRE (address of variable)
A:=PP                   % LDA I PP (value via pointer)
A:="PP"                 % LDA PP (address stored in pointer)

8.3 Zero Register vs Zero Constant¶

% Bare 0 is the ZERO REGISTER (always contains 0)
0 =: T                  % COPY DT (copy from zero register)
0 =: VAR                % STZ VAR (store zero)

% Quoted "0" is a CONSTANT
"0" =: VAR              % SAA 0; STA VAR (load 0 then store)
A:="0"                  % SAA 0
A BONE "0"              % BSET ONE 0 DA (set bit 0)

8.4 Quoted Expressions¶

Expressions in quotes are evaluated at compile time:

SYMBOL OFFSET=10

A SHZ 2+5               % Shift by 2, then add 5
                        % SHA ZIN 2; AAA 5

A SHZ "2+5"             % Shift by 7 (evaluated at compile time)
                        % SHA ZIN 7

A:="TRE+OFFSET-5"       % Compile-time address calculation
                        % LDA (TRE+OFFSET-5

9. Arrays & Data Structures¶

9.1 Array Declaration¶

% Integer arrays
INTEGER ARRAY TABLE(100)        % 100 elements
INTEGER ARRAY BUF1(50), BUF2(50)

% Double arrays (32-bit elements)
DOUBLE ARRAY DTABLE(20)         % 20 double elements (40 words)

% Real arrays (48-bit floating point)
REAL ARRAY MATRIX(100)          % 100 real elements (300 words)

% Triple arrays (48-bit integers)
TRIPLE ARRAY BIGTABLE(10)       % 10 triple elements (30 words)

MAC equivalent:

TABLE = *
* + 100/

BUF1 = *
* + 50/

BUF2 = *
* + 50/

DTABLE = *
* + 20 + 20/                % 2 words per element

MATRIX = *
* + 100 + 100 + 100/        % 3 words per element

9.2 Array Initialization¶

% Initialize with data
INTEGER ARRAY TEXT:='STRING'

% Initialize with values
INTEGER ARRAY MDISCS:=(
    0,    0,    0,    0,
WWDIS,WWDIS,WWDIS,WWDIS,
BBDIS,BBDIS,BBDIS,BBDIS,
    0,    0,    0,    0
)

% Initialize with comma-separated expressions
INTEGER ARRAY PARLIST:=(LOGNO, AREA, "100", "15")

MAC equivalent:

TEXT, 'STRING'

MDISCS, 0, 0, 0, 0
        WWDIS, WWDIS, WWDIS, WWDIS
        BBDIS, BBDIS, BBDIS, BBDIS
        0, 0, 0, 0

PARLIST, LOGNO
         AREA
         (100
         (15

9.3 Array Access¶

% Access with constant index
A:=TABLE(0)             % First element
A:=TABLE(10)            % 11th element

% Access with variable index
INTEGER IDX:=5
A:=TABLE(IDX)           % Element at index IDX

% Access with register index
A:=10
A:=TABLE(A)             % Use A as index

% Access with expression (must be quoted)
SYMBOL OFFSET=5
A:=TABLE("OFFSET+2")    % Element 7 (compile-time calculation)

9.4 Multi-Word Element Arrays¶

For DOUBLE, REAL, and TRIPLE arrays, you must calculate the correct offset:

TRIPLE ARRAY BIGARR(100)        % Each element is 3 words

% To access elements:
TAD:=BIGARR(0)          % First element (words 0, 1, 2)
TAD:=BIGARR(3)          % Second element (words 3, 4, 5)
TAD:=BIGARR(6)          % Third element (words 6, 7, 8)

% To access element N:
% Index = N * 3

Real example:

REAL ARRAY DATA(10)             % 10 floating-point numbers

INTEGER N:=2                    % Want 3rd element (N=2)
A:=N*3                          % Calculate offset (2*3=6)
TAD:=DATA(A)                    % Access 3rd element

9.5 Array Pointers¶

% Declare array pointer
INTEGER ARRAY ARR(100)
INTEGER ARRAY POINTER ARRPTR:=ARR

% Access through pointer (same syntax as array)
A:=ARRPTR(0)            % First element
A:=ARRPTR(10)           % 11th element

% Point to different location
"ARR+50" =: "ARRPTR"    % Point to middle of array
A:=ARRPTR(0)            % Now accesses ARR(50)

9.6 Building Data Structures¶

Real SINTRAN example - Device Control Block (DCB):

% Structure definition
DISP 0
    INTEGER MLINK           % Link to next in queue
    INTEGER MFUNC           % Function code
    INTEGER RESLINK         % Resource link
    INTEGER RTRES           % RT program reserving this
    INTEGER BWLINK          % Backward link in waiting queue
    INTEGER STATUS          % Device status
PSID

% Create an array of these structures
BASE DCBS
    INTEGER ARRAY HDLC_DCB(6)    % HDLC device DCB (6 words)
    INTEGER ARRAY SCSI_DCB(6)    % SCSI device DCB
    INTEGER ARRAY TERM_DCB(6)    % Terminal DCB
ESAB

% Access structure fields
SUBR INIT_DEVICE
INIT_DEVICE:
    "DCBS" =: B                     % Load base
    0 =: HDLC_DCB(MLINK)            % Clear MLINK field
    0 =: HDLC_DCB(MFUNC)            % Clear MFUNC field
    EXIT
RBUS

10. Compiler Directives¶

10.1 Environment Control¶

10.1.1 @DEV - Device Selection¶

@DEV (S-S-L)FILENAME:NPL

Specifies output device and filename.

10.1.2 @ICR and @CR - Code Region¶

@ICR                    % Initialize Code Region
% ... declarations ...
@CR                     % Close Region

Used to group declarations and separate them from other sections.

10.2 Conditional Compilation¶

@IF <symbol>
    % Code included if symbol is defined
@ELSE
    % Code included if symbol is not defined
@ENDIF

Example:

@IF DEBUG
    % Debug code
    *IOF
    A:=ERROR_CODE
    *DEBUG
    *ION
@ENDIF

10.3 Assembly Code Inclusion¶

Any line starting with * is passed directly to the MAC assembler:

*IOF                    % Turn off interrupts
*ION                    % Turn on interrupts
*EXR ST                 % Execute IOX read status
*STZTX                  % Store zero via T and X
*LDATX                  % Load via T and X

% Monitor calls
*ENRF (SEGNO)           % Enter segment into RF
*OUTBT (LOGDEV, BUFFER) % Output byte

10.4 Useful Assembly Directives¶

*)FILL                  % Fill to page boundary
*)KILL VAR1 VAR2        % Remove symbols from table
*=*+100                 % Reserve 100 words

11. Code Organization & Linking¶

11.1 Program Structure¶

% File header
@DEV (S-S-L)MYPROGRAM:NPL

% Global data
INTEGER ARRAY GLOBAL_TABLE(100)
INTEGER GLOBAL_VAR1, GLOBAL_VAR2

% Subroutine 1
SUBR ROUTINE1, ROUTINE2
    INTEGER LOCAL1, LOCAL2

    ROUTINE1:
        % Code
        EXIT

    ROUTINE2:
        % Code
        EXIT
RBUS

% Subroutine 2
SUBR ROUTINE3
    INTEGER LOCAL_DATA
    BASE MYDATA
        INTEGER FIELD1, FIELD2
    ESAB

    ROUTINE3:
        "MYDATA" =: B
        % Code using base variables
        EXIT
RBUS

11.2 External References¶

% Reference subroutine in another file
CALL EXTERNAL_ROUTINE

% Reference global data
A:=EXTERNAL_VARIABLE

The MAC assembler and linker handle external symbol resolution.

11.3 Multi-File Projects¶

Typical SINTRAN file organization:

PH-P2-START-BASE.NPL    % Base system data structures
PH-P2-OPPSTART.NPL      % System initialization
MP-P2-HDLC-DRIV.NPL     % HDLC device driver
IP-P2-SCSI-DRIV.NPL     % SCSI device driver
RP-P2-MONCALLS.NPL      % Monitor call handlers

Each file: 1. Declares its own global data 2. Defines subroutines 3. References external symbols (resolved at link time)

12. Practical Development Workflow¶

This chapter provides a step-by-step guide to developing, compiling, and running NPL programs on SINTRAN III.

12.1 Hello World Example¶

Let's create a simple "Hello World" program in NPL. This program will output a message to the terminal and exit.

Complete Hello World Program:

% HELLO.NPL - Simple Hello World program
% Demonstrates basic NPL program structure

@DEV (DSK,HELLO):NPL          % Output to DSK:HELLO:NPL

% External monitor calls
@REF
    SUBR MONITOR
@

SUBR HELLO, START

% Message buffer
INTEGER ARRAY MESSAGE:='HELLO, WORLD FROM NORD PL!', 15, 12

START:
    % Write message to terminal
    % MONITOR call 43 = WRTSW (Write String)
    A:=43                       % Function code
    T:="MESSAGE"                % Address of message
    *MONITOR 43                 % Call monitor

    % Exit program
    % MONITOR call 3 = EXIT (Exit program)
    A:=3
    *MONITOR 3

RBUS

Key components: 1. @DEV directive specifies output file 2. @REF declares external references (MONITOR) 3. SUBR defines subroutine with entry point 4. Message stored as INTEGER ARRAY with text + CR/LF (15, 12) 5. Monitor calls for I/O and program termination

12.2 Creating the Source File¶

On a SINTRAN system:

@ED                            % Start editor
INPUT                          % Input mode
% Type or paste your NPL code
% ...
SAVE HELLO:NPL                 % Save file
QUIT                           % Exit editor

Alternative editors: - @EDIT - Full-screen editor (if available) - Transfer file via terminal/serial connection - Use PLANC editor: @PLANC HELLO:NPL

File naming conventions: - Use .NPL extension for NPL source files - Typical: PROGRAM-NAME:NPL or MODULE-NAME:NPL - SINTRAN files: Device:(Catalog,)Filename:Extension - Example: DSK:MYDIR,HELLO:NPL - Simple: HELLO:NPL (current directory)

12.3 Compiling with NPL¶

The NPL compiler translates NPL source code to MAC assembler source.

Basic compilation:

@NPL HELLO:NPL                 % Compile HELLO:NPL

Output: - Creates HELLO:MAC (MAC assembler source) - Displays any syntax errors - Shows compilation statistics

Compiler output example:

NPL COMPILER VERSION 3.5
SOURCE: HELLO:NPL
LISTING: (NONE)
OBJECT: HELLO:MAC

COMPILING...
PASS 1 COMPLETE
PASS 2 COMPLETE

LINES COMPILED: 24
ERRORS: 0
WARNINGS: 0

COMPILATION COMPLETE

Compilation options:

@NPL HELLO:NPL, HELLO:LST      % With listing file
@NPL HELLO:NPL, (OBJ)          % Object to terminal
@NPL HELLO:NPL, , (XREF)       % Cross-reference

Common compilation errors:

Error	Cause	Solution
`UNDEFINED SYMBOL`	Variable/label not declared	Check spelling, add declaration
`ILLEGAL OPERAND`	Wrong operand type	Check operator requirements
`PHASE ERROR`	Forward reference problem	Rearrange declarations
`TOO MANY ERRORS`	Too many syntax errors	Fix first errors, recompile

12.4 Assembling with MAC¶

The MAC assembler converts the .MAC file to relocatable object code.

Basic assembly:

@MAC HELLO:MAC                 % Assemble HELLO:MAC

Output: - Creates HELLO:BRF (Binary Relocatable Format) - Object code ready for linking

Assembly output example:

MAC ASSEMBLER VERSION 4.2
SOURCE: HELLO:MAC
BINARY: HELLO:BRF

ASSEMBLING...
PASS 1: 45 LINES
PASS 2: 45 LINES

ERRORS: 0
WARNINGS: 0

ASSEMBLY COMPLETE

Assembly options:

@MAC HELLO:MAC, HELLO:LST      % With listing file
@MAC HELLO:MAC, , (XREF)       % Cross-reference listing
@MAC HELLO:MAC, , (MAP)        % Memory map

Common assembly errors:

Error	Cause	Solution
`UNDEFINED SYMBOL`	External reference not resolved	Check @REF declarations
`MULTIPLY DEFINED`	Symbol defined twice	Remove duplicate definition
`VALUE ERROR`	Illegal value in expression	Check constant values
`RELOCATION ERROR`	Addressing mode problem	Check address calculations

12.5 Creating an Executable¶

Method 1: Direct Loading (Simple Programs)

For simple programs without external references:

@LD HELLO:BRF                  % Load and execute

Method 2: Creating RT Program (Recommended)

For programs that need to be run multiple times:

@NORD-LOAD                     % Start NORD loader
INPUT HELLO:BRF                % Input object file
CREATE HELLO:PROG              % Create executable program file
EXIT                           % Exit loader

Method 3: Using BINDER (Multiple Modules)

For programs with multiple object files:

@BINDER
INFILE HELLO:BRF
INFILE UTILS:BRF
INFILE IOLIB:BRF
OUTFILE HELLO:PROG
BIND                           % Link all modules
EXIT

BINDER commands:

Command	Purpose
`INFILE filename`	Add input object file
`LIBRARY libname`	Add library file
`OUTFILE filename`	Specify output executable
`BIND`	Perform linking
`MAP`	Show memory map
`XREF`	Show cross-reference

12.6 Running Your Program¶

From SINTRAN command level:

@HELLO                         % Run HELLO:PROG

Output:

HELLO, WORLD FROM NORD PL!
@                              % Back to command prompt

Alternative execution methods:

1. Direct execution with arguments:

@HELLO PARAM1 PARAM2          % Pass parameters

2. Run as RT program:

@RT HELLO                      % Run as real-time program

3. Background execution:

@BACKGROUND HELLO             % Run in background

4. Batch execution:

@BATCH
@HELLO
@ANOTHER-PROGRAM
@END-BATCH

12.7 Common Errors and Solutions¶

Compilation Errors¶

Error: "UNDEFINED SYMBOL: MONITOR"

% WRONG - Missing @REF
SUBR START
START:
    *MONITOR 43                % MONITOR not declared
    EXIT
RBUS

% CORRECT - Declare external reference
@REF
    SUBR MONITOR
@

SUBR START
START:
    *MONITOR 43                % Now works
    EXIT
RBUS

Error: "ILLEGAL ADDRESSING MODE"

% WRONG - Trying to use global variable directly
INTEGER GLOBALVAR

SUBR TEST
TEST:
    A:=GLOBALVAR               % Won't work - global variable
    EXIT
RBUS

% CORRECT - Use indirect addressing
INTEGER GLOBALVAR

SUBR TEST
TEST:
    A:=GLOBALVAR               % NPL compiler handles this automatically
    EXIT                       % Generates: LDA I (GLOBALVAR)
RBUS

Error: "PHASE ERROR IN PASS 2"

% WRONG - Forward reference in initialization
INTEGER VAR1:=VAR2            % VAR2 not yet defined
INTEGER VAR2:=100

% CORRECT - Define in order
INTEGER VAR2:=100
INTEGER VAR1:=VAR2            % Now VAR2 is known

Runtime Errors¶

Error: Program crashes immediately

Possible causes: 1. Stack overflow (too many nested calls) 2. Invalid memory access 3. Division by zero 4. Infinite loop

Debug approach:

% Add debug output
SUBR DEBUG_TEST
DEBUG_TEST:
    A:=1; CALL PRINTNUM         % Checkpoint 1
    CALL SOME_ROUTINE
    A:=2; CALL PRINTNUM         % Checkpoint 2
    % ... find where it crashes
    EXIT
RBUS

Error: "ILLEGAL INSTRUCTION"

Check P register value
Verify code is not being overwritten
Check for stack corruption

Error: "MEMORY VIOLATION"

Check array bounds
Verify pointer values
Check B register is set for BASE variables

12.8 Development Tips¶

Tip 1: Use Incremental Development¶

% Start simple
SUBR HELLO
HELLO:
    A:=43
    T:="MESSAGE"
    *MONITOR 43
    EXIT
RBUS

% Add functionality gradually
% Test after each addition

Tip 2: Create a Build Script¶

BUILD-HELLO.COM (Command file):

@NPL HELLO:NPL
@IF-ERROR @GOTO ERROR
@MAC HELLO:MAC
@IF-ERROR @GOTO ERROR
@LD HELLO:BRF
@GOTO END
@ERROR: @WRITELN COMPILATION FAILED
@END:

Run with:

@DO BUILD-HELLO:COM

Tip 3: Use Listing Files for Debugging¶

@NPL HELLO:NPL, HELLO:LST
@TYPE HELLO:LST                % View generated code

Listing file shows: - Generated MAC code - Variable addresses - Memory layout - Cross-references

Tip 4: Keep a Library of Utility Routines¶

UTILS:NPL:

% Utility routines used by multiple programs

@REF
    SUBR MONITOR
@

SUBR PRINTNUM, PRINTSTR, DELAY

% Print number in A register
PRINTNUM:
    % Convert to string and print
    % ... implementation ...
    EXIT

% Print null-terminated string
PRINTSTR:
    % ... implementation ...
    EXIT

% Delay for A milliseconds
DELAY:
    % ... implementation ...
    EXIT

RBUS

Use in your program:

@REF
    SUBR PRINTNUM, PRINTSTR     % From UTILS
@

% Your code uses these utilities

Tip 5: Standard Program Template¶

TEMPLATE:NPL:

% PROGRAM-NAME:NPL
% Description: [What this program does]
% Author: [Your name]
% Date: [Date]
% Version: 1.0

@DEV (DSK,PROGRAM-NAME):NPL

% External references
@REF
    SUBR MONITOR                % Monitor calls
    % Add other external references here
@

% Global constants
SYMBOL MAXBUFFER=1024
SYMBOL SUCCESS=0
SYMBOL ERROR=1

% Global data
BASE GLOBALS
    INTEGER STATUS
    INTEGER COUNTER
    INTEGER ARRAY BUFFER(MAXBUFFER)
ESAB

% Main program
SUBR MAIN, INIT, PROCESS, CLEANUP

% Local variables
INTEGER RESULT, TEMP

% Initialization
INIT:
    "GLOBALS" =: B              % Load globals base
    0 =: STATUS
    0 =: COUNTER
    EXIT

% Main processing
MAIN:
    CALL INIT
    CALL PROCESS
    CALL CLEANUP

    % Exit program
    A:=3                        % MONITOR EXIT
    *MONITOR 3

% Process routine
PROCESS:
    % Your code here
    EXIT

% Cleanup routine
CLEANUP:
    % Cleanup code here
    EXIT

RBUS

Tip 6: Commenting Strategy¶

% ============================================
% MODULE: Data Processing
% PURPOSE: Process input data
% INPUT: A = Data count, T = Buffer address
% OUTPUT: A = Result code (0=success)
% USES: X, D registers (modified)
% ============================================
SUBR PROCESS_DATA
INTEGER COUNTER, TEMP
PROCESS_DATA:
    % Save input parameters
    A =: COUNTER
    T =: TEMP

    % Validate inputs
    IF COUNTER < 1 THEN
        A:=ERROR                % Return error
        EXIT
    FI

    % Process each element
    DO WHILE COUNTER >< 0
        % ... processing ...
        COUNTER - 1 =: COUNTER
    OD

    % Success
    A:=SUCCESS
    EXIT
RBUS

Tip 7: Version Control¶

Keep track of changes:

HELLO:NPL.V1          % Original version
HELLO:NPL.V2          % Version 2
HELLO:NPL             % Current version
HELLO:BAK             % Backup

Tip 8: Performance Testing¶

% Measure execution time
SUBR BENCHMARK
INTEGER START_TIME, END_TIME

BENCHMARK:
    *MONITOR 25; A =: START_TIME    % Get time

    CALL YOUR_ROUTINE               % Test this

    *MONITOR 25; A =: END_TIME      % Get time again
    A:=END_TIME - START_TIME        % Calculate duration

    % Print result
    CALL PRINTNUM
    EXIT
RBUS

Tip 9: Memory Usage Monitoring¶

% Check available memory
*MONITOR 26                    % Get memory info
% Returns memory status in registers

Tip 10: Testing Strategy¶

Create test suite:

SUBR TEST_SUITE, TEST1, TEST2, TEST3

TEST_SUITE:
    CALL TEST1
    IF A><0 THEN GO FAILED FI

    CALL TEST2
    IF A><0 THEN GO FAILED FI

    CALL TEST3
    IF A><0 THEN GO FAILED FI

    % All tests passed
    A:=43; T:="PASS_MSG"; *MONITOR 43
    EXIT

FAILED:
    % Test failed
    A:=43; T:="FAIL_MSG"; *MONITOR 43
    EXIT

TEST1:
    % Test case 1
    % ...
    A:=0                        % 0 = success
    EXIT

% ... more test cases ...
RBUS

13. Common Patterns & Idioms¶

13.1 Saving and Restoring Link Register¶

SUBR NESTED_CALLER
INTEGER POINTER RETURN_ADDR

NESTED_CALLER:
    % Save return address
    A:=L:="RETURN_ADDR"

    % Call another subroutine
    CALL SOME_ROUTINE

    % Restore and return
    GO RETURN_ADDR              % JMP I RETURN_ADDR
RBUS

13.2 Table Lookup¶

SYMBOL MAXENTRIES=64
INTEGER ARRAY LOOKUP_TABLE(MAXENTRIES)

SUBR FIND_ENTRY
INTEGER INDEX
FIND_ENTRY:
    0 =: INDEX
    DO WHILE INDEX < MAXENTRIES
        A:=LOOKUP_TABLE(INDEX)
        IF A = TARGET THEN
            % Found!
            EXIT
        FI
        INDEX + 1 =: INDEX
    OD
    % Not found
    EXIT
RBUS

13.3 Linked List Traversal¶

% List element structure
DISP 0
    INTEGER NEXT            % Next pointer (0 = end)
    INTEGER DATA1
    INTEGER DATA2
PSID

SUBR TRAVERSE_LIST
INTEGER POINTER CURRENT
TRAVERSE_LIST:
    LIST_HEAD =: CURRENT

    DO WHILE CURRENT >< 0
        % Process element pointed to by CURRENT
        "CURRENT" =: B
        A:=DATA1                % Access data via B register

        % Move to next
        CURRENT.NEXT =: CURRENT
    OD
    EXIT
RBUS

13.4 Bit Manipulation¶

% Set specific bits
A:=STATUS
A BONE 5                    % Set bit 5
A BONE 7                    % Set bit 7
STATUS =: A

% Clear specific bits
A:=CONTROL
A BZERO 3                   % Clear bit 3
A BZERO 6                   % Clear bit 6
CONTROL =: A

% Test bit
A:=FLAGS
A /\ "1 SH 4"               % Test bit 4 (mask = octal 20)
IF A >< 0 THEN
    % Bit 4 is set
FI

% Extract bit field
A:=WORD
A /\ 17                     % Mask bits 0-3 (0017 octal)
% A now contains bits 0-3

13.5 Memory Block Operations¶

% Clear memory block
SUBR CLEAR_BLOCK
INTEGER POINTER START
INTEGER COUNT

CLEAR_BLOCK:
    START =: X
    DO WHILE COUNT >< 0
        *STZTX                  % Store zero at X
        X + 1 =: X
        COUNT - 1 =: COUNT
    OD
    EXIT
RBUS

13.6 Parameter Passing via Registers¶

% Caller
SUBR CALLER
CALLER:
    5 =: A                  % Parameter 1 in A
    10 =: D                 % Parameter 2 in D
    CALL PROCESS
    % Result in A
    EXIT
RBUS

% Callee
SUBR PROCESS
INTEGER TEMP
PROCESS:
    A + D =: TEMP           % Use parameters
    TEMP * 2 =: A           % Return result in A
    EXIT
RBUS

13.7 Error Handling¶

SUBR OPERATION
OPERATION:
    % Perform operation
    IF error_condition THEN
        GO ERROR_EXIT
    FI

    % Success
    A:=0                    % Return code 0 = success
    EXIT

ERROR_EXIT:
    A:=1                    % Return code 1 = error
    EXIT
RBUS

13.8 Real SINTRAN Pattern: Ident Code Table Clearing¶

From PH-P2-OPPSTART.NPL:

% Clear an entry in the ident code table for level 10
10IDCLEAR:
    IF A><0 THEN
        A-1=:X:="ITB10"-"PITEX"     % Calculate table offset
        X+A
        A:=MPIFPHPAGE SHZ 12        % Get physical page
        X+A
        T:=MPIBANK                  % Get bank
        *STZTX                      % Clear entry via T and X registers
    FI
    EXIT

Pattern breakdown: 1. Check if A is valid (non-zero) 2. Calculate offset into table (A-1) 3. Add base address of table 4. Calculate physical address 5. Use T and X registers for indirect access 6. Perform operation via assembly instruction

14. Real-World Patterns from SINTRAN¶

This section contains actual patterns, idioms, and techniques extracted from the SINTRAN III operating system source code.

14.1 Interrupt Handler Patterns¶

Pattern: Minimal Interrupt Service Routine

From RP-P2-MONCALLS.NPL - Keep interrupt handlers SHORT:

% Level 14 interrupt handler (Monitor Call)
% CRITICAL: Minimum time in interrupt context!

@LMCAL=*
MONCA:
    *SAVEX                      % Save ALL registers quickly
    "BMONQ"=:B                  % Load monitor queue base
    A:=BWLINK                   % Get queue head
    IF A=0 THEN                 % Empty queue?
        GO ERRMON               % Error handling
    FI
    A=:X                        % X = current mon call block
    T:=RESLINK; T=:BWLINK      % Update queue linkage
    *RESTX; EXIT                % Restore and return FAST

Key principles: 1. Save registers FIRST 2. Do MINIMAL work 3. Queue complex work for later 4. Restore and EXIT quickly

Pattern: Deferred Work Queue

% Don't do heavy work in interrupt - queue it!

INT_HANDLER:
    *SAVEX
    % Quick check and queue
    "WORKQ"=:B
    A:=CURRENT_TASK
    A=:BWLINK                   % Add to work queue
    *RESTX
    *MONITOR 10                 % Request monitor attention
    EXIT

% Later, in monitor context:
PROCESS_WORK:
    "WORKQ"=:B
    DO WHILE BWLINK><0
        X:=BWLINK               % Get work item
        T:=X.RESLINK
        T=:BWLINK               % Update queue
        CALL DOWORK             % Now safe to do heavy work
    OD

14.2 Queue Manipulation Patterns¶

Pattern: Circular Linked List with Head Node

From SINTRAN execution queue (BEXQU):

% Queue structure: Head node with MLINK and BWLINK
%   MLINK = Type/status
%   BWLINK = First element (or back to head if empty)
% Elements: WLINK points to next (or back to head)

% Add to queue (priority ordered)
ADDTOQUEUE:
    "BEXQU"=:B                  % B points to head
    A:=NEW_ELEMENT

    % Find insertion point
    X:=B                        % Start at head
    DO WHILE TRUE
        T:=X.BWLINK             % Get next
        IF T=B THEN GO INSERT FI % Reached end
        IF T.PRIORITY << A.PRIORITY THEN GO INSERT FI
        T=:X                    % Move to next
    OD

INSERT:
    T:=X.BWLINK                 % Get X's next
    A=:X.BWLINK                 % X now points to new element
    T=:A.WLINK                  % New element points to old next
    EXIT

% Remove from queue
REMOVEFROMQUEUE:
    "BEXQU"=:B
    A:=ELEMENT_TO_REMOVE

    % Find predecessor
    X:=B
    DO WHILE X.BWLINK><A
        X:=X.BWLINK
        IF X=B THEN EXIT FI     % Not in queue!
    OD

    % Remove it
    T:=A.WLINK                  % Get element's next
    T=:X.BWLINK                 % Predecessor points to next
    EXIT

Pattern: Wait Queue with Resource Linking

% From RT program wait queues
% Element structure:
%   TLNK - Time queue link
%   WLINK - Wait queue link (offset 20 octal = 16 decimal)
%   RESLINK - Resource wait link (offset 22 octal = 18 decimal)

WAITFORRESOURCE:
    "RESOURCE"=:B               % Point to resource datafield
    A:=CURRENT_RT_PROGRAM

    % Link into resource wait queue
    T:=B.RTRES                  % Get current waiter
    IF T=0 THEN
        % First waiter
        A=:B.RTRES
        0=:A.RESLINK
    ELSE
        % Add to end (FIFO for same priority)
        DO WHILE T.RESLINK><0
            T.RESLINK=:T
        OD
        A=:T.RESLINK
        0=:A.RESLINK
    FI

    % Mark program as waiting
    A.STATE BONE WAITING_BIT =: A.STATE
    EXIT

14.3 Memory Management Patterns¶

Pattern: Physical Page Allocation

From PH-P2-OPPSTART.NPL:

% GETAREA - Allocate contiguous physical pages
% Entry: A = Number of pages needed
%        T = Starting page to search from
% Exit:  A = First allocated page number
%        GO LABEL if failed

GETAREA:
    IF A<<1 THEN EXIT FI        % Nothing to allocate
    A=:NEEDED
    T=:START

SEARCH:
    X:=0                        % Counter
    D:=START                    % Current page

    DO WHILE X<<NEEDED
        CALL ISFREEPAGE         % Check if page is free
        IF A=0 THEN GO NEXTSTART FI % Page not free
        X+1; D+1                % Next page
        IF D>>LPHYSPAGE THEN GO FAILED FI % No more pages
    OD

    % Found contiguous area!
    A:=START
    X:=NEEDED
    DO WHILE X><0
        CALL MARKUSED           % Mark page as used
        A+1; X-1
    OD
    A:=START
    EXIT

NEXTSTART:
    START=:D; D+1=:START        % Try next starting point
    GO SEARCH

FAILED:
    GO LABEL                    % Jump to error handler

Pattern: Memory Bank Switching

% SINTRAN uses bank switching for accessing different memory regions
% Pattern: Save bank, switch, access, restore

ACCESSOTHERBANK:
    *TRR 10; A=:SAVED_BANK      % Save current bank (octal 10 = Level register)

    TARGET_BANK; *TRR 10        % Load target bank register

    % Now access memory in target bank
    T:=X.DATAFIELD
    A:=T.VALUE

    SAVED_BANK; *TRR 10         % Restore original bank
    EXIT

% Common pattern with *1BANK/*2BANK directives:
BANKED_ACCESS:
    *1BANK                      % Switch to bank 1
    A:=SOME_TABLE(X)           % Access data
    *2BANK                      % Switch back to bank 2
    % Process data

14.4 Device Driver Patterns¶

Pattern: Device Datafield Structure

From device drivers:

% Standard I/O datafield structure
BASE IODF
    INTEGER MLINK               % Link type (offset 0)
    INTEGER MFUNC               % Function code (offset 1)
    INTEGER RESLINK             % Resource link (offset 2)
    INTEGER RTRES               % RT program waiting (offset 3)
    INTEGER BWLINK              % Queue link (offset 4)
    INTEGER HDEV                % Hardware device address (offset 5)
    INTEGER STATUS              % Device status (offset 6)
    INTEGER BUFFER_ADDR         % DMA buffer address (offset 7)
    INTEGER BYTE_COUNT          % Transfer byte count (offset 8)
    INTEGER ERROR_CODE          % Last error (offset 9)
ESAB

% Access pattern:
DEVICE_OPERATION:
    "IODF"=:B                   % Load datafield base
    A:=HDEV                     % Get hardware address
    T:=BUFFER_ADDR              % Get buffer
    X:=BYTE_COUNT               % Get count
    CALL DRIVER                 % Call driver routine
    IF A><0 THEN                % Check for error
        A=:ERROR_CODE
    FI
    EXIT

Pattern: DMA Transfer Setup

% From disk driver (MP-P2-DISK-START.NPL)

SETUP_DMA:
    % Calculate physical address from logical
    A:=LOGICAL_ADDR
    CALL CNVWADR                % Convert to physical (if in 5MPM)

    % Setup DMA registers
    A=:MAR                      % Memory Address Register
    A:=BLOCK_NUMBER
    A=:DAR                      % Disk Address Register
    A:=BYTE_COUNT
    A=:COUNT_REG

    % Start DMA
    A:=CONTROL_BITS OR DMA_START
    A=:CONTROL_REG

    % Wait for completion (or interrupt)
    IF POLLING_MODE THEN
        DO WHILE STATUS_REG BIT BUSY_BIT
            % Poll
        OD
    FI
    EXIT

14.5 Error Handling Patterns¶

Pattern: Retry with Backoff

From disk drivers:

% Retry failed operation with counter

DISKIO:
    -6=:RETRY_COUNT             % Allow 6 retries

RETRY:
    CALL DISKOPERATION
    IF A=0 THEN EXIT FI         % Success!

    % Failed - retry?
    MIN RETRY_COUNT
    IF A<<0 THEN GO FATAL_ERROR FI % Out of retries

    % Wait a bit and retry
    CALL SHORTDELAY
    GO RETRY

FATAL_ERROR:
    CALL ERRFATAL               % Fatal error handler

Pattern: Error State Preservation

% Save error context for debugging

ERROR_HANDLER:
    *SAVEX                      % Save ALL registers

    % Record error information
    A=:ERROR_CODE
    P=:ERROR_PC                 % Where did it fail?
    X=:ERROR_X
    T=:ERROR_T

    % Save stack frame
    L=:ERROR_STACK_PTR
    A:=L
    DO I:=0 TO 10
        *ILDAL; A=:ERROR_STACK(I)
    OD

    % Now handle error
    CALL LOGERROR
    CALL CLEANUP
    *RESTX
    EXIT

14.6 Multi-CPU Communication Patterns¶

Pattern: Message Buffer Protocol (ND-500 ↔ ND-100)

From MP-P2-N500.NPL:

% Send message to ND-500
SEND_TO_500:
    % Fill message buffer in 5MPM
    "5MPM_BASE"=:B
    A:=PROCESS_NUMBER
    A*MESSAGE_SIZE              % Calculate buffer offset
    A=:MESSAGE_ADDR

    % Fill message fields
    A+B=:X                      % X = message buffer address
    FUNCTION_CODE=:X.MICFU
    BYTE_COUNT=:X.NRBYT
    ND500_ADDR=:X.N500A
    ND100_ADDR=:X.N100A

    % Set "in queue" flag
    X.5MSFL BONE 5ITMQUEUE =: X.5MSFL

    % Signal ND-500 via hardware
    A:=MESSAGE_ADDR
    T:=LCON5_REG                % ND-500 control register
    *IOXT                       % Write via I/O

    % ND-500 will interrupt ND-100 when done
    EXIT

% Receive reply from ND-500 (in interrupt handler)
RECEIVE_FROM_500:
    "5MPM_BASE"=:B
    A:=INTERRUPTED_PROCESS
    A*MESSAGE_SIZE+B=:X

    % Check if message ready
    IF X.5MSFL BIT 5ITMQUEUE=0 THEN EXIT FI % Not ready

    % Clear flag
    X.5MSFL /\ -5ITMQUEUE-1 =: X.5MSFL

    % Read result
    A:=X.5ERRC                  % Error code
    IF A=0 THEN
        % Success - process result
        T:=X.NRBYT              % Bytes transferred
        CALL PROCESS_RESULT
    FI
    EXIT

Pattern: Shared Memory Access with Cache Coherency

% Access multiport memory (5MPM) with proper segment capabilities
% CRITICAL: Data segment capability bit 13 (S flag) MUST be set!

INIT_5MPM_ACCESS:
    % Setup segment capability for 5MPM
    % Bit 15 (W) = Write allowed
    % Bit 13 (S) = Shared (bypass cache!)
    % Bits 11-0 = Physical segment number

    A:=5MPM_PHYS_SEG            % Physical segment in 5MPM
    A BONE 15                   % Set Write bit
    A BONE 13                   % Set Shared bit (CRITICAL!)
    A=:DATA_CAPABILITY(5MPM_SEG_NUM)

    % Now can safely access 5MPM
    % Both CPUs will see same data (no cache issues)
    EXIT

14.7 Optimization Patterns¶

Pattern: Loop Unrolling

% From memory initialization code

% SLOW - Loop overhead
CLEAR_SLOW:
    X:=0
    DO WHILE X<<1000
        0=:ARRAY(X)
        X+1
    OD
    EXIT

% FAST - Unrolled loop
CLEAR_FAST:
    X:=0
    DO WHILE X<<1000
        *STZ ,X; STZ 1,X; STZ 2,X; STZ 3,X
        *STZ 4,X; STZ 5,X; STZ 6,X; STZ 7,X
        X+10                    % 8 words per iteration
    OD
    EXIT

Pattern: Table-Driven Code

% From device type dispatch

% Instead of many IF statements:
DISPATCH_TABLE:
    INTEGER ARRAY HANDLERS:=(
        HDLC_HANDLER,           % Type 0
        PIOC_HANDLER,           % Type 1
        SCSI_HANDLER,           % Type 2
        TERM_HANDLER,           % Type 3
        X21_HANDLER)            % Type 4

DISPATCH:
    A:=DEVICE_TYPE
    IF A>>4 THEN GO ERROR FI   % Invalid type
    A+A                         % Word offset (2 bytes per entry)
    A+"HANDLERS"=:X
    *ILDAX                      % Load handler address
    *EXR SA                     % Jump to handler

Pattern: Bit Manipulation Shortcuts

% Fast bit operations from SINTRAN code

% Set multiple bits at once
A BONE "0" BONE "3" BONE "7" =: REGISTER    % Set bits 0, 3, 7

% Clear specific bits (careful with operator!)
A /\ -BIT_MASK-1 =: REGISTER                % Clear bit

% Test multiple bits
IF A /\ MASK = EXPECTED_VALUE THEN          % Check pattern

% Extract bit field
A SHZ -SHIFT_COUNT /\ FIELD_MASK            % Get field value

% Rotate through carry
A SH 1; IF C THEN A BONE "0" FI             % Rotate left with carry

14.8 Debugging Patterns¶

Pattern: Debug Trace Points

% Conditional debug output (enabled at compile time)

@*DEBUG
    SUBR TRACE
    INTEGER TRACE_BUFFER(100)
    INTEGER TRACE_INDEX=0

    TRACE:
        IF TRACE_INDEX>=100 THEN 0=:TRACE_INDEX FI
        A=:TRACE_BUFFER(TRACE_INDEX)
        TRACE_INDEX+1=:TRACE_INDEX
        EXIT
    RBUS
@

% In code:
@*DEBUG
    A:=12345                    % Debug marker
    CALL TRACE
@

Pattern: Register Dump on Error

% Save ALL registers for post-mortem analysis

SAVE_CONTEXT:
    P=:SAVED_P
    X=:SAVED_X
    T=:SAVED_T
    A=:SAVED_A
    D=:SAVED_D
    L=:SAVED_L
    *TRR STS; A=:SAVED_STS      % Status register
    B=:SAVED_B
    *TRR PIE; A=:SAVED_PIE      % Interrupt enable
    *TRR PID; A=:SAVED_PID      % Interrupt disable
    EXIT

14.9 Code Organization Patterns¶

Pattern: Module Structure

% Standard SINTRAN module organization

% 1. Header with module info
%********************************************************
% MODULE: MP-P2-HDLC-DRIV
% PURPOSE: HDLC Protocol Driver
% DATE: 1985-03-15
%********************************************************

% 2. External references
@REF
    SUBR MONITOR, ERRFATAL, GETAREA
@

% 3. Global data structures
BASE HDLCDATA
    INTEGER STATUS
    INTEGER BUFFER_ADDR
ESAB

% 4. Local variables (shared by subroutines)
INTEGER LOCAL_VAR1, LOCAL_VAR2

% 5. Subroutines (entry points first)
SUBR HDLC_INIT, HDLC_SEND, HDLC_RECEIVE

HDLC_INIT:
    % Initialization code
    EXIT

HDLC_SEND:
    % Send code
    EXIT

% 6. Internal helper routines
INTERNAL_HELPER:
    % Helper code
    EXIT

RBUS

% 7. Interrupt handlers (separate from main code)
@LINT11=*
HDLC_INTERRUPT:
    *SAVEX
    % Handle interrupt
    *RESTX
    EXIT

Pattern: Conditional Compilation

% Different code for different configurations

@*ND110
    % Code specific to ND-110
    SUBR SPECIAL110
    SPECIAL110:
        % ND-110 specific initialization
        EXIT
    RBUS
@

@*-ND110
    % Code for everything EXCEPT ND-110
    SUBR GENERIC
    GENERIC:
        % Generic code
        EXIT
    RBUS
@

14.10 Safety Patterns¶

Pattern: Critical Section Protection

% Disable interrupts for critical operations

CRITICAL_OPERATION:
    *IOF                        % Interrupts OFF

    % Critical section - must complete atomically
    A:=SHARED_COUNTER
    A+1
    A=:SHARED_COUNTER

    *ION                        % Interrupts ON
    EXIT

Pattern: Sanity Checks

% Always validate inputs in system code

VALIDATE_POINTER:
    % Check pointer is not null
    IF A=0 THEN GO ERROR FI

    % Check pointer is in valid range
    IF A<<MIN_ADDR THEN GO ERROR FI
    IF A>>MAX_ADDR THEN GO ERROR FI

    % Check pointer is word-aligned (even address)
    IF A BIT 0 THEN GO ERROR FI

    % Pointer is valid
    EXIT

ERROR:
    CALL ERRFATAL

Pattern: Resource Cleanup

% Always clean up resources even on error path

OPERATION_WITH_CLEANUP:
    CALL ALLOCATE_RESOURCE
    IF A=0 THEN GO ERROR FI
    A=:RESOURCE

    CALL DO_OPERATION
    IF A><0 THEN GO CLEANUP FI  % Error - cleanup!

    % Success path
CLEANUP:
    A:=RESOURCE
    CALL FREE_RESOURCE
    EXIT

ERROR:
    % Error before resource allocated
    EXIT

Appendix A: Quick Reference¶

Operators¶

Operator	Meaning	Example
`:=`	Load	`A:=VAR`
`=:`	Store	`A =: VAR`
`:=:`	Swap	`A :=: T`
`+`	Add	`A + 5`
`-`	Subtract	`A - 3`
`*`	Multiply	`A * B`
`/`	Divide (real)	`TAD / R`
`/\`	AND	`A /\ 177`
`\/`	OR	`A \/ 100`
`XOR`	XOR	`A XOR T`
`—`	One's comp	`A—`
`—`	Two's comp	`A—`
`SH`	Shift arith	`A SH 2`
`SHZ`	Shift zero	`A SHZ -3`
`SHR`	Rotate	`A SHR 1`
`SHL`	Shift link	`A SHL 1`
`BONE`	Set bit	`A BONE 5`
`BZERO`	Clear bit	`A BZERO 3`
`MIN`	Mem increment	`MIN VAR`
`GOSW`	Switch	`A GOSW L1,L2`

Addressing Modes¶

Type	Declaration	Access	Example
Global	Outside SUBR	Indirect	`LDA I (VAR)`
Local	Inside SUBR	Direct	`LDA VAR`
Base	Inside BASE-ESAB	B-relative	`LDA VAR,B`
Disp	Inside DISP-PSID	B-relative	`LDA VAR,B`

Data Types¶

Type	Size	Declaration	Example
INTEGER	16-bit	`INTEGER VAR`	`-32768 to +32767`
DOUBLE	32-bit	`DOUBLE VAR`	2 words
REAL	48-bit	`REAL VAR`	3 words (floating)
TRIPLE	48-bit	`TRIPLE VAR`	3 words (integer)
POINTER	16-bit	`INTEGER POINTER P`	Address
ARRAY	Variable	`INTEGER ARRAY A(N)`	N elements

Appendix B: Common Mistakes¶

1. Forgetting to Load B Register¶

% WRONG
BASE MYDATA
    INTEGER VAR1
ESAB

SUBR TEST
TEST:
    A:=VAR1                 % WILL NOT WORK! B not set
    EXIT
RBUS

% CORRECT
SUBR TEST
TEST:
    "MYDATA" =: B           % Load base address first
    A:=VAR1                 % Now it works
    EXIT
RBUS

2. Declaring Variables After Code¶

% WRONG - Variables may be out of P-relative range
SUBR BADEXAMPLE
BADEXAMPLE:
    % Lots of code here...
    % ...
    % ...
INTEGER VAR1, VAR2          % These might be unreachable!
    GO SOMEWHERE
RBUS

% CORRECT - All variables first
SUBR GOODEXAMPLE
INTEGER VAR1, VAR2          % Declare at top
GOODEXAMPLE:
    % All code here
    GO SOMEWHERE
RBUS

3. Using 0 Instead of "0"¶

% WRONG - Using zero register when constant intended
A BONE 0                    % Tries to use register 0 as bit number

% CORRECT
A BONE "0"                  % Use bit 0

4. Forgetting Array Element Size¶

% WRONG
TRIPLE ARRAY BIGARR(10)
TAD:=BIGARR(1)              % Gets words 1,2,3 (middle of element 0!)

% CORRECT
TAD:=BIGARR(0)              % Element 0: words 0,1,2
TAD:=BIGARR(3)              % Element 1: words 3,4,5
TAD:=BIGARR(6)              % Element 2: words 6,7,8

5. Operator Precedence Assumptions¶

% WRONG - NPL has NO precedence, evaluates left-to-right
A:=2 + 3 * 4                % Result: (2+3)*4 = 20, NOT 2+(3*4)=14

% CORRECT - Use explicit ordering
A:=3 * 4                    % 12
A + 2 =: RESULT             % 14

Appendix C: SINTRAN Code Examples¶

Example 1: SINTR - System Initialization (from PH-P2-OPPSTART.NPL)¶

SUBR SINTR,TTMMAP

% Main swapping disc data table
@ICR;
INTEGER ARRAY MDISCS:=(
        0,    0,    0,    0,    0,    0,    0,    0,   % 00 - 07
    WWDIS,WWDIS,WWDIS,WWDIS,WWDIS,WWDIS,    0,BBDIS,   % 10 - 17
    BBDIS,BBDIS,BBDIS,BBDIS,BBDIS,BBDIS,BBDIS,BBDIS,   % 20 - 27
    BBDIS,BBDIS,BBDIS,BBDIS,BBDIS,BBDIS,SCDIS,    0,   % 30 - 37
        0,    0,    0,    0,    0,    0,    0,    0);  % 40 - 47

INTEGER ARRAY WWDIS:=(WIGDI,1224,ZWDIS,WIDIS,   500);  % ST-506
INTEGER ARRAY BBDIS:=(BIGDI,1100,ZBDIS,BDISK,  1540);  % SMD
INTEGER ARRAY SCDIS:=(SCDI1,2210,SCSWD,SCSWD,144300);  % SCSI
@CR;

% Test if memory page exists
TRIPLE TRARDR
INTEGER XR,CCBTST(0); *BSKP ZRO DT

TTMMAP: 
    TAD=:TRARDR; X=:XR              % Save TAD and X
    A SHZ -6; AD SHZ -4             % Shift operations
    T:=TMMAP(A)                     % Get memory map entry
    AD SH 4                         % Shift back
    A/\17 SH 3+CCBTST              % Mask and shift
    *EXR SA                         % Execute
    L+1                             % Skip next instruction
    TAD:=TRARDR; X:=XR              % Restore TAD and X
    EXIT

Example 2: Clear Ident Code Table Entry¶

% Clear an entry in ident-code table for level 10
10IDCLEAR:
    IF A><0 THEN
        A-1=:X:="ITB10"-"PITEX"     % Calculate table entry address
        X+A
        A:=MPIFPHPAGE SHZ 12        % Get physical page number
        X+A
        T:=MPIBANK                  % Load bank
        *STZTX                      % Clear entry (assembly instruction)
    FI
    EXIT

Example 3: Remove Timer Table Element¶

RFTMTABLE:
    IF A><0 THEN
        A=:XA                       % Save value
        "TMRTA"-"PITEX"=:X          % Table start address
        RPIFPHPAGE SHZ 12=:D        % Physical page
        X+A                         % Add offset
        "ETMRT"-"PITEX"; D+A        % End of table

        DO WHILE X<<D               % Search through table
            T:=RPIBANK
            *LDATX                  % Load from table
            IF A-XA=0 THEN          % Found matching entry?
                *STZTX              % Clear it
                EXIT
            FI
            X+1                     % Next entry
        OD
    FI
    EXIT

Document History¶

Version	Date	Changes
1.0	Oct 16, 2025	Initial version - comprehensive NPL developer guide
1.1	Oct 17, 2025	Major update: Added Chapter 14 "Real-World Patterns from SINTRAN" with 10 comprehensive pattern categories extracted from actual SINTRAN III source code analysis
1.2	Oct 17, 2025	NEW: Added Chapter 12 "Practical Development Workflow" - complete Hello World example with step-by-step compilation, assembly, linking, and execution guide

What's New in v1.2:

This version adds Chapter 12: Practical Development Workflow with:

✅ Complete Hello World Program - Working NPL example with explanations
✅ Step-by-Step Compilation - NPL compiler usage and options
✅ MAC Assembly Process - Assembler commands and output
✅ Creating Executables - Three methods: direct loading, RT programs, BINDER
✅ Running Programs - Execution methods and parameter passing
✅ Error Solutions - Common compilation and runtime errors with fixes
✅ Development Tips - Build scripts, templates, testing strategies
✅ Production Workflow - Real-world development practices

What's New in v1.1:

This version adds 700+ lines of real-world patterns and techniques from SINTRAN III:

✅ Interrupt Handler Patterns - Minimal ISR, deferred work queues
✅ Queue Manipulation Patterns - Circular lists, wait queues, resource linking
✅ Memory Management Patterns - Page allocation, bank switching
✅ Device Driver Patterns - Datafield structure, DMA setup
✅ Error Handling Patterns - Retry with backoff, error state preservation
✅ Multi-CPU Communication - ND-500 ↔ ND-100 message passing, shared memory, cache coherency
✅ Optimization Patterns - Loop unrolling, table-driven code, bit manipulation
✅ Debugging Patterns - Trace points, register dumps
✅ Code Organization - Module structure, conditional compilation
✅ Safety Patterns - Critical sections, sanity checks, resource cleanup

All patterns include working code examples from the actual SINTRAN operating system.

End of NORD PL Developer Guide

NORD PL Developer Guide¶

Table of Contents¶

Installing NPL¶

1. NPL Fundamentals & Philosophy¶

1.1 What is NORD PL?¶

1.2 Design Philosophy¶

1.3 When to Use NORD PL¶

1.4 Prerequisites¶

2. Basic Syntax & Data Types¶

2.1 Identifiers¶

2.2 Reserved Identifiers¶

2.3 Data Types¶

2.3.1 Integer Variables (16-bit)¶

2.3.2 Double Variables (32-bit)¶

2.3.3 Real Variables (Floating Point)¶

2.3.4 Triple Variables (48-bit)¶

2.3.5 Pointers¶

2.4 Constants¶

2.4.1 Numeric Constants¶

2.4.2 Character Constants¶

2.4.3 String Constants¶

2.5 Symbolic Constants¶

3. Variables & Memory Layout¶

3.1 Variable Addressing Attributes¶

3.2 Global Variables¶

3.3 Local Variables¶

3.4 Memory Layout: Why Variables Come First¶

4. Subroutines & Memory Organization¶

4.1 Subroutine Structure¶

4.2 Calling Subroutines¶

4.3 Returning from Subroutines¶

4.4 Label Declarations¶

5. Control Flow¶

5.1 Unconditional Branch¶

5.2 Conditional Branching¶

5.2.1 IF Statements¶

5.2.2 Conditions¶

5.3 Loops¶

5.3.1 DO WHILE Loop¶

5.3.2 FOR Loop¶

5.4 Switch Statement (GOSW)¶

6. Register Usage¶

6.1 Register Overview¶

6.2 Register Operations¶

6.2.1 Load Operations¶

6.2.2 Store Operations¶

6.2.3 Swap Operations¶

6.3 Arithmetic Operations¶

6.4 Logical Operations¶

6.5 Shift Operations¶

6.6 Bit Operations¶

7. Global Memory Access (B and X Registers)¶

7.1 The B Register (Base Register)¶

7.1.1 BASE Variables¶

7.1.2 DISP Variables (Dynamic Displacement)¶

7.2 The X Register (Index Register)¶

7.2.1 Array Indexing¶

7.2.2 X-Relative Addressing (Structure Chaining)¶

8. Addressing Modes & Memory References¶

8.1 Addressing Mode Summary¶

8.2 The Quote Operator (" ")¶

8.3 Zero Register vs Zero Constant¶

8.4 Quoted Expressions¶

9. Arrays & Data Structures¶

9.1 Array Declaration¶

9.2 Array Initialization¶

9.3 Array Access¶

9.4 Multi-Word Element Arrays¶

9.5 Array Pointers¶

9.6 Building Data Structures¶

10. Compiler Directives¶

10.1 Environment Control¶

10.1.1 @DEV - Device Selection¶

10.1.2 @ICR and @CR - Code Region¶

10.2 Conditional Compilation¶

10.3 Assembly Code Inclusion¶

10.4 Useful Assembly Directives¶

11. Code Organization & Linking¶

11.1 Program Structure¶

11.2 External References¶

8.2 The Quote Operator (`" "`)¶