Decoded: Sopwith (1984) by David L. Clark
Source file: _INTC.C
Beginner friendly, line-by-line code walkthrough by MaiZure

_INTC.C provides interrupt manipulation functions for the custom handlers used
in Sopwith

Original code:
http://davidlclark.com/page/sopwith-source-code

Original code with line numbers
http://www.maizure.org/projects/decoded-sopwith/_INTC_linenum.txt

1     COMMENT
2     COMMENT
3     BLANK
4     COMMENT
5     COMMENT
6     COMMENT
7     COMMENT
8     COMMENT
9     COMMENT
10    COMMENT
11    COMMENT
12    COMMENT
13    COMMENT
14    BLANK
15    COMMENT
16    BLANK
17    COMMENT
18    COMMENT
19    COMMENT
20    COMMENT
21    COMMENT
22    BLANK
23    COMMENT
24    COMMENT
25    COMMENT
26    BLANK
27    COMMENT
28    COMMENT
29    BLANK
30    COMMENT
31    COMMENT
32    COMMENT
33    BLANK
34    COMMENT
35    COMMENT
36    BLANK
37    COMMENT
38    COMMENT
39    COMMENT
40    BLANK
41    COMMENT
42    BLANK
43    COMMENT
44    BLANK
45    COMMENT
46    COMMENT
47    BLANK
48    BLANK
49    Include the main game header (sw.h)
50    Define macro for maximum interrupts as 10
51    BLANK
52    BLANK
53    BLANK
54    BLANK

DEFINES OUR LOCAL INTERRUPT TABLE
55    BLOCK START - Interrupt override data structure definition
56    Holds the entry point address for the new interrupt handler
57    Holds the entry point address for the original interrupt handler
58    Holds the interrupt number of this entry
59    BLOCK END - Interrupt override data structure definition
60    BLANK
61    BLANK
62    BLANK

OVERRIDE AN INTERRUPT
63    Declares and defines _intsetup with 2 arguments
64    Arguments 1 and 2 are an interrupt number and a function pointer
65    BLOCK START - _intsetup, overrides DOS interrupts with Sopwith handlers
66    Declare two function pointers for the handlers
67    Declare two functions defined in _INTA.ASM
68    Declares another function from _INTA.ASM
69    Declares a local iterator
70    BLANK
71    BLANK
72    COMMENT
73    COMMENT
74    COMMENT
75    BLANK
76    Loop through the interrupt table to find an empty slot
77    If slot is empty..
78    Stop iteration, i now indexes the empty table slot
79    If i reaches the maximum allowable interrupts...
80    Return failure
81    Otherwise, we found a slot so set it's number to the input number + 1.
      We need to ensure that the interrupt number is non-zero if in use. Portability
      concern?
82    BLANK
83    BLANK
84    BLANK
85    COMMENT
86    COMMENT
87    COMMENT
88    COMMENT
89    BLANK
90    Save a pointer to the old interrupt handler (code in _INTA.ASM)
91    Set the pointer to the new interrupt handler
92    Set a pointer to the base of our interrupt vector table. The call to _intsetup
      ensures proper segments are set up beforehand.
93    Set a pointer to the offset within that table
94    Sets the DOS interrupt vector to our new handler (via int 0x21/0x25 in
      INT_A.ASM)
95    BLANK
96    Return the table position
97    BLOCK END - _intsetup
98    BLANK
99    BLANK
100   BLANK

RESTORE A SINGLE INTERRUPT
101   Declares and defines _intreset with 1 argument
102   Argument 1 is the index within the Sopwith interrupt table
103   BLOCK START - _intreset, restores original DOS interrupt handlers
104   COMMENT
105   COMMENT
106   COMMENT
107   BLANK
108   If the interrupt index isn't valid, too small, large...
109   or not defined...
110   Return failure
111   BLANK
112   BLANK
113   COMMENT
114   COMMENT
115   COMMENT
116   BLANK
117   Set the interrupt handler to the original handler saved during init
118   Set the interrupt table index to unused
119   BLANK
120   Return the table index
121   BLOCK END - _intreset
122   BLANK
123   BLANK
124   BLANK

RESTORE ALL OVERRIDDEN INTERRUPTS
125   Declare and define _intterm with no arguments
126   BLOCK START - _intterm, restores all Sopwith modified interrupts
127   Declares a local index iterator
128   BLANK
129   Loop through all entries of the interrupt table
130   If the interrupt has been overridden..
131   Restore the original interrupt handler
132   BLOCK END - _intterm
133   EOF