git.subgeniuskitty.com - vvhitespace/.git/blame_incremental

... / ...

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