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 | |
2c2764b7 AT |
5 | programs. For an example, see `examples/hello-stdlib`. This also means |
6 | `cpp` syntax must be respected. | |
92a92075 | 7 | |
32c440bf AT |
8 | # Reservations # |
9 | ||
92a92075 AT |
10 | Since all labels share a global namespace, the standard library makes the |
11 | following reservations: | |
12 | ||
32c440bf AT |
13 | ## Label ## |
14 | ||
15 | 00000000 0xxxxxxx - reserved for stdlib function entry points | |
2c2764b7 | 16 | 00000000 1xxxxxxx - available for use in user programs |
32c440bf AT |
17 | 0xxxxxxx xxxxxxxx - reserved for private use by stdlib |
18 | 1xxxxxxx xxxxxxxx - available for use in user programs | |
19 | ||
bb21580a | 20 | ## Heap and Pointers ## |
32c440bf | 21 | |
bb21580a | 22 | The first 16 heap addresses (`0-15`) are reserved when using the stdlib. |
6cb31a3e | 23 | Within that reservation, heap[0] is used by `random` and the block |
2c2764b7 | 24 | heap[1]-heap[15] by the stack rotation subroutines which time-share |
6cb31a3e | 25 | pseudo-registers between the various stdlib subroutines. |
bb21580a AT |
26 | |
27 | By convention, functions which return a pointer will use the address `0` to | |
28 | represent a `NULL` pointer. | |
32c440bf AT |
29 | |
30 | # Entry Points # | |
31 | ||
32 | The following labels are entry points to stdlib functions. Read the | |
33 | header comment for each function to learn the call and return stack. | |
34 | ||
3625ff3a | 35 | 000xxx - reserved |
23d17247 AT |
36 | 001xxx - core functions |
37 | 1000 ----- printf (stdio.pvvs) | |
38 | 1001 ----- print number from stack (stdio.pvvs) | |
39 | 1010 ----- stackrotate (stack.pvvs) | |
a67867ae | 40 | 1011 ----- stackrotatereverse (stack.pvvs) |
f0499c77 | 41 | 1100 ----- deepdup (stack.pvvs) |
3625ff3a | 42 | 010xxx - math functions |
2612f47f | 43 | 10000 ----- random (math.pvvs) |
3625ff3a | 44 | 10001 ----- absolute value (math.pvvs) |
37372ed0 | 45 | 10010 ----- greatest common divisor (math.pvvs) |
3695b659 AT |
46 | 011xxx - heap functions |
47 | 11000 ----- memset (heap.pvvs) | |
3d75b928 | 48 | 11001 ----- memcpy (heap.pvvs) |
d63de3fa | 49 | 11010 ----- memrand (heap.pvvs) |
87d27426 | 50 | 11011 ----- memcmp (heap.pvvs) |
fd04fb41 | 51 | 11100 ----- memsrch (heap.pvvs) |
bb21580a AT |
52 | 11101 ----- <empty> |
53 | 11110 ----- slurp (heap.pvvs) | |
54 | 11111 ----- spew (heap.pvvs) | |
ae1f85a1 AT |
55 | 100xxx - string functions |
56 | 100000 ----- strlen (string.pvvs) | |
0e0d0a4a | 57 | 100001 ----- isdigit (string.pvvs) |
0c56152e AT |
58 | 101xxx - logic functions |
59 | 101000 ----- not (logic.pvvs) | |
60 | 101001 ----- and (logic.pvvs) | |
61 | 101010 ----- or (logic.pvvs) | |
62 | 101011 ----- xor (logic.pvvs) | |
63 | 101100 ----- rshift (logic.pvvs) | |
64 | 101101 ----- lshift (logic.pvvs) | |
1a56830d | 65 | 110xxx - conversion functions |
b6bea2cf | 66 | 110000 ----- atoi (convert.pvvs) |
1a56830d AT |
67 | 111xxx - debug functions |
68 | 111000 ----- dump heap (debug.pvvs) | |
ae1f85a1 | 69 | 111001 ----- dump stack (debug.pvvs) |
9f7f68e5 AT |
70 | 111010 ----- print sign (debug.pvvs) |
71 | 111011 ----- print magnitude (debug.pvvs) | |
72 | 111100 ----- print string (debug.pvvs) | |
4fba07dc | 73 | 111101 ----- print signed number (debug.pvvs) |
3625ff3a | 74 | 1xxxxxx - reserved for less common entry points |
e0d5136c | 75 | 1000000 ----- lowbitand (logic.pvvs) |
75098baa | 76 | 1000001 ----- <empty> |
ae1f85a1 AT |
77 | 1000010 ----- print sign of number (stdio.pvvs) |
78 | 1000011 ----- print magnitude of number (stdio.pvvs) | |
b8b65c17 AT |
79 | 1000100 ----- print string from stack (stdio.pvvs) |
80 | 1000101 ----- print string from heap (stdio.pvvs) | |
32c440bf AT |
81 | |
82 | # Misc # | |
83 | ||
2c2764b7 AT |
84 | ## Private Label Space ## |
85 | ||
86 | By convention, each public stdlib label will have 8 bits of private label space | |
87 | associated with it, formed as follows: | |
32c440bf AT |
88 | |
89 | 00001000 xxxxxxxx - for use by 1000 | |
90 | 00001001 xxxxxxxx - for use by 1001 | |
92a92075 | 91 | ...etc |
2c2764b7 AT |
92 | |
93 | ## Extending Heap Reservation ## | |
94 | ||
95 | By default, the stdlib uses the first 16 heap addresses. All heap access (other | |
96 | than heap[0] as a seed) occurs through `stackrotate` and `stackrotatereverse`. | |
97 | Edit these functions to increase the stdlib's heap reservation. | |
98 | ||
99 | The remainder of the stdlib is written to automatically use the new allocation. | |
100 | Functions like `printf`, for example, allow more substitutions when the heap | |
101 | allocation is increased. |