Commit | Line | Data |
---|---|---|
92a92075 AT |
1 | # Overview # |
2 | ||
3 | This folder contains a library of useful functions written in VVhitespace. | |
4 | Standard include guards are used with `cpp` to include the stdlib in user | |
5 | programs. For an example, see `examples/hello-stdlib`. | |
6 | ||
32c440bf AT |
7 | # Reservations # |
8 | ||
92a92075 AT |
9 | Since all labels share a global namespace, the standard library makes the |
10 | following reservations: | |
11 | ||
32c440bf AT |
12 | ## Label ## |
13 | ||
14 | 00000000 0xxxxxxx - reserved for stdlib function entry points | |
15 | 00000000 1xxxxxxx - unassigned | |
16 | 0xxxxxxx xxxxxxxx - reserved for private use by stdlib | |
17 | 1xxxxxxx xxxxxxxx - available for use in user programs | |
18 | ||
bb21580a | 19 | ## Heap and Pointers ## |
32c440bf | 20 | |
bb21580a AT |
21 | The first 16 heap addresses (`0-15`) are reserved when using the stdlib. |
22 | ||
23 | By convention, functions which return a pointer will use the address `0` to | |
24 | represent a `NULL` pointer. | |
32c440bf AT |
25 | |
26 | # Entry Points # | |
27 | ||
28 | The following labels are entry points to stdlib functions. Read the | |
29 | header comment for each function to learn the call and return stack. | |
30 | ||
3625ff3a AT |
31 | 000xxx - reserved |
32 | 001xxx - print functions | |
33 | 1000 ----- print string from stack (stdio.pvvs) | |
34 | 1001 ----- print string from heap (stdio.pvvs) | |
35 | 1010 ----- print number from stack (stdio.pvvs) | |
36 | 010xxx - math functions | |
2612f47f | 37 | 10000 ----- random (math.pvvs) |
3625ff3a | 38 | 10001 ----- absolute value (math.pvvs) |
3695b659 AT |
39 | 011xxx - heap functions |
40 | 11000 ----- memset (heap.pvvs) | |
3d75b928 | 41 | 11001 ----- memcpy (heap.pvvs) |
d63de3fa | 42 | 11010 ----- memrand (heap.pvvs) |
87d27426 | 43 | 11011 ----- memcmp (heap.pvvs) |
fd04fb41 | 44 | 11100 ----- memsrch (heap.pvvs) |
bb21580a AT |
45 | 11101 ----- <empty> |
46 | 11110 ----- slurp (heap.pvvs) | |
47 | 11111 ----- spew (heap.pvvs) | |
ae1f85a1 AT |
48 | 100xxx - string functions |
49 | 100000 ----- strlen (string.pvvs) | |
3625ff3a | 50 | 101xxx - unassigned |
1a56830d AT |
51 | 110xxx - conversion functions |
52 | 111xxx - debug functions | |
53 | 111000 ----- dump heap (debug.pvvs) | |
ae1f85a1 | 54 | 111001 ----- dump stack (debug.pvvs) |
3625ff3a | 55 | 1xxxxxx - reserved for less common entry points |
ae1f85a1 AT |
56 | 1000000 ----- slurp registers (heap.pvvs) |
57 | 1000001 ----- spew registers (heap.pvvs) | |
58 | 1000010 ----- print sign of number (stdio.pvvs) | |
59 | 1000011 ----- print magnitude of number (stdio.pvvs) | |
32c440bf AT |
60 | |
61 | # Misc # | |
62 | ||
63 | By convention, each public stdlib label will have 8 bits of | |
64 | private label space associated with it, formed as follows: | |
65 | ||
66 | 00001000 xxxxxxxx - for use by 1000 | |
67 | 00001001 xxxxxxxx - for use by 1001 | |
92a92075 | 68 | ...etc |
fd04fb41 | 69 | |
bb21580a AT |
70 | # Slurp and Spew # |
71 | ||
72 | The stdlib uses heap[1] to heap[15] as registers. | |
73 | ||
ae1f85a1 AT |
74 | The `slurpreg` and `spewreg` functions facilitate this by `spew`ing the stack |
75 | onto the heap's pseudo-registers or `slurp`ing the pseudo-registers back to the | |
bb21580a AT |
76 | stack. The functions preserve order in complementary fashion. |
77 | ||
ae1f85a1 | 78 | The `spewreg` function uses `heap[0]` for storage. |