Decoded: Rogue (1980) by Toy, Arnold, Wichman
DOS version (1983) by Mel Sibony and Jon Lane
Source file: SBRK.ASM
Beginner friendly, line-by-line code walkthrough by MaiZure

SBRK.ASM implements low level memory allocation in x86. SBRK syscall is the
underlying mechanism for calls to malloc.

Original code:
https://britzl.github.io/roguearchive/

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



1     COMMENT (recommended viewing is with tab stop at 8 spaces)
2     COMMENT
3     Set the current segment to data with paragraph alignment
4     The 16-byte $MEMRY is the top of the heap (Aztec C compiler symbol)
5     Imports the heap+1 and stack pointer
6     Imports errno return
7     End of the data segment
8     Beginning of the code segment
9     Assume the usual suspects for the 16-bit memory model
10    COMMENT
11    COMMENT
12    COMMENT

SBRK
This procedure allocates new memory at the top of the heap. Note that the input
to the procedure expects the input value to be the amount of memory requested
in bytes. It is a two byte value stored relative to the stack pointer at call
time.

13    Export the procedure 'sbrk' to any linked programs
14    Define sbrk_ within the same code segment
15    Move the stack pointer in to BX
16    Save the current destination index we're about to clobber
17    Move the amount of memory requested in to AX (recall that BX = SP)
18    Save the original break value in to DI (we'll return this later since
      it becomes the base of the new memory request)
19    Add the requested memory to the old break value. This becomes the 
      absolute address of the next top of the heap. Result in AX
20    Push the result on to the stack
21    Call BRK using AX - BRK uses absolute addresses, not increments
22    Pop the top of the heap in to CX (not used, but restores stack state)
23    If there is an error condition in flags from brk, jump to end (line 25)
24    Move the old break value to AX to return as base pointer of new memory
      allocation
25    Label for clean up of sbrk. Can jump here on error
26    Restore the stored destination index
27    Clear flags that may have changed during memory allocation
28    Return to caller
29    COMMENT
30    COMMENT
31    COMMENT
32    COMMENT

BRK
Absolute address of memory after allocation. Called by SBRK and the new top
of the heap should be at the top of the stack

33    Export the procedure 'brk' to any linked programs
34    Define the brk_ procedure to allocate new heap top at address at sp+2
35    Move the stack pointer to BX
36    Move the new desired heap top in to AX
37    Compare the new top of the heap with the sbot variable (stack+safety).
38    If overflow jump to line 47 (Stack overflow means cmp resulted in CF==1)
39    Recheck against the current stack pointer just in case
40    Jump to 47 if there is an issue
41    COMMENT
42    COMMENT
43    Move the new top of the heap in to the system break value
44    Clear out AX
45    Return AX=0 -- success
46    COMMENT
47    Label for stack overflow
48    Apparently this is the errno in DOS for stack overflow...doubt it
49    Return -1 failure to caller
50    Clear the flags
51    Return to caller
52    COMMENT
53    COMMENT
54    COMMENT
55    COMMENT
56    COMMENT
57    Label rsvstk for making a safety buffer after stack (Not used in Rogue)
58    Save the stack pointer in to BX
59    Subtrack the input argument (safety buffer size?) from stack pointer
60    Export this new value to the system variable for the stack bottom
61    Return to caller
62    End of the sbrk procedure
63    End of the code segment
64    End of assembly file
65    EOF˙