## 1 Packages

### 1.18core

the core definitions

### 1.50posix

posix runtime defintions

### 1.51primus

the runtime state of the Primus Machine

### 1.52program

program-specific definitions (program global variables)

### 1.59target

target-specific definitions (registers, etc)

### 1.62user

the default user-space package

## 2 Macros

### 2.1non-zero

(non-zero X) is true if X is not zero

### 2.2compare

(compare X Y) returns 0 if X = Y, a negative value if X<Y and a positive value if X>Y

### 2.3array-set

(array-set T P N W) sets to W the N-th element of the array of elements of type T, pointed by P. Returns a pointer to the next element

### 2.4points-to

(points-to T P V) return true if t P points to a value of type T that is equal to V.

### 2.5is-in

(is-in X A B C …) returns true if X is equal A or B or C or …

### 2.6nth-byte-of-word

(nth-byte-of-word T N X) returns N-th byte of the word X that has type T

### 2.7ptr+1

(ptr+1 T P) increments the pointer P to a value of to type T.

### 2.8incr

(incr X Y …) increments the value bound with the variables X, Y, …

### 2.9when

(when CND BODY) if CND evaluates to true, then BODY is evaluated and the value of the last expression in BODY becomes the value of the whole expression. Otherwise, if CND evaluates to false, nil is returned.

### 2.10until

(until COND BODY) if COND evaluates to true, then the whole expression evaluates to nil and BODY is not evaluated. Otherwise, if COND evaluates to false, then BODY is evaluated until COND evaluates to true and the value of the last evaluation of BODY becomes the value of the whole expression.

### 2.12or

(or <expr> …) evaluates a sequence of expressions EXPR from left to right until it meets the first expression that evaluates to the truth value, that will become the value of the whole form. If no expression returned the truth value, then the result of the whole form is 0:1

### 2.13decr

(decr X Y …) decrements the value bound with the variables X, Y, …

### 2.14+=

(+= X Y) assigns a sum of X and Y to variable X

### 2.15+1

(+1 x) returns the successor of X

### 2.16-1

(-1 X) returns the predecessor of X

### 2.17assert

(assert COND) terminates program if COND is false

### 2.18array-get

(array-get T P N) gets the N-th element of the array of elements of type T, pointed by P

### 2.20write-word

(write-word T A X) writes the word X of type T to address A returns an address that points to the first byte that follows the just written word.

### 2.21min

(min X Y …) returns the lower bound of the (X,Y,…) set

### 2.22max

(max X Y …) returns the upper bound of the (X,Y,…) set

### 2.23unless

(unless CND BODY) if CND evaluates to false, then BODY is evaluated and the value of the last expression in BODY becomes the value of the whole expression. Otherwise, if CND evaluates to true, nil is returned.

### 2.26and

(and X Y …) evaluates expressions X,Y,… until the first expression that returns false. The value of the whole form is the value of the last evaluated expression.

### 2.27case

(case K K1 X1 K2 X2 … Kn Xn [DEF]) evaluates K then consequently evaluates keys K1 …Kn until a key Ki such that (= K Ki) is found. If such key is found then the whole form evaluates to Xi. If no matching key was found, then if the number of keys is equal to the number of expressions, nil is returned, otherwise, i.e., if an extra expression DEF is provided, then it becomes the value of the whole form. Examples: (defun dispatch-with-default-case (c) (case c 1 'hello 2 'cruel 3 'world 'unknown)) (defun dispatch-with-no-default (c) (case c 1 'hello 2 'cruel 3 'world))

### 2.29copy-left

(copy-left DST SRC LEN) copies LEN bytes from SRC to DST (right to left)

### 2.30copy-right

(copy-right DST SRC LEN) copies LEN bytes from SRC to DST (left to right)

### 2.31copy-byte-shift

(copy-byte-shift DST SRC) copies byte from SRC to DST and increments SRC and DST.

### 2.34ptr+

(ptr+ T P N) increments N times the pointer P to a value of type T.

### 2.35endian

(endian F X Y) expands to (F Y X) if applied in the little endian context OR (endian F X Y) expands to (F X Y) if applied in the big endian context

### 2.36copy-byte-shift-left

(copy-byte-shift-left DST SRC) copies byte from DST to SRC and decrements SRC and DST.

<internal>

### 2.38sign

returns 1 if X > 0, 0 if X = 0, and -1 if X < 0

### 2.39fold

(fold F A X Y …) expands to (F (F A X) Y) …

## 3 Constants

### 3.1false

false is another name for 0:1

### 3.2nil

nil is another name for false

### 3.3true

true is another name for 1:1

## 4 Functions

### 4.1ascii-sign

(ascii-sign S) is 1 if S is +, -1 if it -, or 0 otherwise

### 4.16getenv

finds a value of an environment variable with the given name

### 4.21ascii-is-digit

(ascii-is-digit s) is true if S is an ascii representation of decimal digit

### 4.26points-to-null

(points-to-null P) true if P points to a zero byte

### 4.29copy-byte

(copy-byte DST SRC) copies byte from the address SRC to DST.

### 4.42malloc

allocates a memory region of size N

### 4.68abort

terminates program with exit code 1

### 4.73free

frees the memory region pointed by P

### 4.75calloc

allocates memory and initializes it with zero

### 4.78ascii-is-whitespace

(ascii-is-whitespace S) is true if S is \t, \n, \r, or SPACE

### 4.96ascii-is-special

(ascii-special S) is true if S is an ascii special character

## 6 Parameters

### 6.1*malloc-uniform-max-value*

if set then defines the lower bound of the uniformely distributed random value that is used to represent an unitialized memory

### 6.2*malloc-arena-end*

the starting address of the malloc arena

### 6.4*malloc-max-chunk-size*

the maximum size of a single memory chunk, if nil then there is no limit.

### 6.6*malloc-arena-initial-size*

the maximum number of bytes totally allocated by malloc, if not set, then there is no limit

### 6.7*malloc-guard-edges*

if not nil, then add padding of the specified size around allocated chunks

### 6.8*malloc-guard-pattern*

a byte that will be used to fill guard edges

### 6.9*malloc-initial-value*

initialize allocated memory with the said value

### 6.10*malloc-arena-start*

the starting address of the malloc arena

### 6.12*malloc-zero-sentinel*

a pointer that is returned by (malloc 0)

### 6.14*malloc-uniform-min-value*

if set then defines the lower bound of the uniformely distributed random value that is used to represent an unitialized memory

### 6.15*malloc-initialize-memory*

if true then initialize allocated memory with malloc-initial-value

### 6.16*malloc-max-arena-size*

the maximum number of bytes totally allocated by malloc, if not set, then there is no limit

## 7 Primitives

### 7.1ieee754-eq

returns true if all operands are ordered with the eq order

### 7.2ieee754-ge

returns true if all operands are ordered with the ge order

### 7.3ieee754-gt

returns true if all operands are ordered with the gt order

### 7.4ieee754-le

returns true if all operands are ordered with the le order

### 7.5ieee754-lt

returns true if all operands are ordered with the lt order

### 7.6ieee754-ne

returns true if all operands are ordered with the ne order

### 7.7>

(< X Y Z …) is true if the list of arguments is a strict descending chain or if it is empty

### 7.8<

(< X Y Z …) is true if the list of arguments is an strict ascending chain or if it is empty

### 7.9=

(= X Y Z …) returns true if all arguments are equal. True if the list of arguments is empty

### 7.10*

(* X Y Z …) returns the product of arguments or 0 if the list of arguments is empty

### 7.11+

(+ X Y …) returns the sum of arguments, or 0 if there are no arguments,

### 7.12/

(/ X Y Z …) returns X / Y / Z / … or 0 if the list of arguments is empty

### 7.13-

(- X Y Z …) returns X - Y - Z - …, or 0 if there are no arguments.

### 7.14points-to-static-data

(points-to-static-data PTR LEN) is true iff (all-static-constant *PTR .. *(PTR+LEN-1))

### 7.15ieee754-sinh

applies sinh to the operand

### 7.16exec-addr

(exec-addr D) passes the control flow to D and never returns

### 7.17region-count

(region-count ID) the total number of regions in the set ID. Counts the number of regions (including intersecting) stored in the set of regions referenced by the symbol ID. Returns nil if there is no set with the given ID, otherwise returns the number of regions in that set.

### 7.18is-negative

(is-negative X Y …) returns true if all arguments are negative

### 7.19ieee754-tanh

applies tanh to the operand

### 7.20channel-close

(channel-close DESCR) closes a channel that has the specified descriptor DESCR. If no such channel exists, then returns -1. Otherwise returns 0. The descriptor of the closed channel will be reused by the consequent calls to channel-open'. If the channel had any data associated with it and not yet flushed, then the data is discarded.

### 7.21logand

(logand X Y Z …) returns X & Y & Z & … or 0 if the list of arguments is empty, where & is the bitwise AND operation. Returns ~0 if the list of arguments is empty

### 7.22logor

(logor X Y Z …) returns X | Y | Z | … or 0 if the list of arguments is empty, where | is the bitwise OR operation

### 7.23dict-add

(dict-add DIC KEY DATA) associates DATA with KEY in the dictionary DIC. Returns KEY.

### 7.24taint-introduce-indirectly

(taint-introduce-indirectly K X N) introduces a new taint of the kind K that is indirectly associated with X pointing to an object of the size N

### 7.26taint-sanitize-indirect

(taint-sanitize-indirect K X) removes any direct taint of the kind K that is indirectly associated with the value X

### 7.27taint-policy-set-default

(taint-policy-set-default P) makes P the default taint propagation policy.

### 7.28region-create

(region-create ID LOWER UPPER) adds [LOWER,UPPER] to the set ID. Adds a region denoted with the interval [LOWER,UPPER] to the set of regions denoted by the symbol ID. Values LOWER and UPPER are included into the interval. If the set of regions ID doesn't exist, then it is created.

### 7.29set-symbol-value

(set-symbol-value S X) sets the value of the symbol S to X. Returns X

### 7.30extract

(extract HI LO X) extracts bits from HI to LO (including both) from the word X

### 7.31exec-symbol

(exec-symbol D) passes the control flow to D and never returns

### 7.32taint-kind

(taint-kind t) returns the kind of the taint T.

### 7.33ieee754-cosh

applies cosh to the operand

### 7.34ieee754-hypot

reduces the list of operands with hypot

### 7.35word-width

(word-width) returns machine word width in bits

### 7.36ieee754-atan2

reduces the list of operands with atan2

### 7.37is-positive

(is-positive X Y …) returns true if all arguments are positive

### 7.38symbol-concat

(symbol-concat X Y Z …) returns a new symbol that is a concatenation of symbols X,Y,Z,…

### 7.39rshift

(rshift X N) logically shifts X right by N bits

### 7.40neg

(neg X) returns the two complement of X

### 7.41not

(not X) returns true if X is zero

### 7.42ieee754-mul

reduces the list of operands with mul

### 7.43ieee754-mod

reduces the list of operands with mod

### 7.44get-current-program-counter

(get-current-program-counter) returns current program cunnter

### 7.45ieee754-expm1

applies expm1 to the operand

### 7.46s/

(s/ X Y Z …) returns X s/ Y s/ Z s/ … or 0 if the list of arguments is empty, where s/ is the signed division operation

### 7.47>=

(< X Y Z …) is true if the list of arguments is a descending chain or if it is empty

### 7.48<=

(< X Y Z …) is true if the list of arguments is an ascending chain or if it is empty

### 7.49/=

(/= X Y Z …) returns true if at least one argument is not equal to another argument. Returns false if the list of arguments is empty

### 7.50exit-with

(exit-with N) terminates program with the exit codeN

### 7.51logxor

(logxor X Y Z …) returns X ^ Y ^ Z ^ … or 0 if the list of arguments is empty, where ^ is the bitwise XOR operation

### 7.52reg-name

(reg-name N) returns the name of the register with the index N

### 7.53dict-first

(dict-first DIC) is the first key in DIC or nil if DIC is empty.

### 7.54ieee754-log

applies log to the operand

### 7.55ieee754-floor

applies floor to the operand

### 7.56memory-write

(memory-write A X) stores by X to A

### 7.57dict-del

(dict-del DIC KEY) deletes any association with KEY in the dictionary DIC

### 7.58taint-introduce-directly

(taint-introduce-directly K X) introduces a new taint of the kind K that is directly associated with the value X

### 7.59dict-length

(dict-first DIC) is the total number of keys in DIC.

### 7.60mod

(mod X Y Z …) returns X % Y % Z % … or 0 if the list of arguments is empty, where % is the modulo operation

### 7.61channel-open

(channel-open PTR) creates a new channel that is associated with a null-terminated path pointed by PTR. Returns a non-negative channel descriptor, if the channel subsystem have a mapping from the obtained path to a physical file and this file is accessible. Otherwise returns a negative value.

### 7.62dict-get

(dict-get DIC KEY) returns data associated with KEY in the dictionary DIC, and returns NIL if either DIC doesn't exist on no data are associated

### 7.63region-move

(region-move DST SRC P) moves all regions that contain the point P from the set SRC to the set DST. Returns nil if SRC didn't contain any such region, otherwise returns t.

### 7.64ieee754-sqrt

applies sqrt to the operand

### 7.65ieee754-pow

reduces the list of operands with pow

### 7.66ieee754-pos

applies pos to the operand

### 7.67ieee754-log1p

applies log1p to the operand

### 7.68ieee754-log10

applies log10 to the operand

### 7.69ieee754-abs

applies abs to the operand

### 7.70ieee754-add

reduces the list of operands with add

### 7.72channel-flush

(channel-flush DESCR) forces data that were written to a channel that has the descriptor DESCR to be outputted to the associated destination. Returns -1 if no such channel exists or if in case of an IO error.

### 7.73signed-mod

(signed-mod X Y Z …) returns X % Y % Z % … or 0 if the list of arguments is empty, where % is the signed modulo operation

### 7.74ieee754-neg

applies neg to the operand

### 7.75taint-sanitize-direct

(taint-sanitize-direct K X) removes any direct taint of the kind K that is directly associated with the value X

### 7.76symbol-of-string

(symbol-of-string ptr) returns a symbol from a null-terminated string.

### 7.77ieee754-sin

applies sin to the operand

### 7.78ieee754-sub

reduces the list of operands with sub

### 7.80channel-input

(channel-input DESC) reads one byte from a channel that has the descriptor DESC. Returns -1 if no such channel exists, or if any IO error occurs, if the channel is not readable, or if the channel is in the end-of-file condition.

### 7.81lnot

(lnot X) returns the one complement of X

### 7.82dict-next

(dict-next DIC KEY) returns the next key after KEY Returns nil if KEY was the last key in the dictionary. Could be used together with DICT-FIRST for iterating.

### 7.83lshift

(lshift X N) logically shifts X left by N bits

### 7.84ieee754-cti

truncates to the nearest integer

### 7.85ieee754-cos

applies cos to the operand

### 7.86all-static-constant

(all-static-constant X Y ..) is true if X,Y,… are static constants. A value is a static constant if it was initialized from a constant value or computed from static constant values.

### 7.87ieee754-asin

applies asin to the operand

### 7.88is-zero

(is-zero X Y …) returns true if all arguments are zeros

### 7.89region-upper

(region-upper ID X) the upper bound of the region that contains X. Returns the upper bound of the region that contains point X or nil if there is no such region or such set of regions. See also, REGION-LOWER.

### 7.90arshift

(arshift X N) arithmetically shifts X right by N bits

### 7.91dict-has

(dict-has DIC KEY) returns T if the dictionary DIC has the key KEY

### 7.92ieee754-atan

applies atan to the operand

### 7.93ieee754-acos

applies acos to the operand

### 7.94memory-allocate

(memory-allocate P N V?) maps memory region [P,P+N), if V is provided, then fills the newly mapped region with the value V

### 7.95region-contains

(region-contains ID X) return the region in ID that has X. Returns the lower bound of the first region that contains value X in the set of regions with the given ID. Returns nil otherwise. Returns nil if a set with the given ID doesn't exist.

### 7.96ieee754-tan

applies tan to the operand

### 7.97region-lower

(region-lower ID X) the lower bound of region that contains X. Returns nil if ID doesn't exist or if it doesn't have a region that includes X. This fucntion is an alias for REGION-CONTAINS. See also, REGION-UPPER.

### 7.98channel-output

(channel-output DESCR CHAR …) outputs one or more characters to a channel that has the descriptor DESCR. Returns -1 if no such channel exits, if a channel is not writable, or if any IO error occurs in an associated physical file. Otherwise, returns 0. Note: the channel system is buffered, and the actual IO operation (as well as errors) could be delayed until (channel-flush DESCR) is called.

### 7.99ieee754-exp

applies exp to the operand

### 7.101taint-get-direct

(taint-get-direct K X) returns the direct taint of the kind K associatedwith the value X, or nil if there is no such taint

### 7.102ieee754-ceil

applies ceil to the operand

### 7.103concat

(concat X Y Z …) concatenates words X, Y, Z, … into one big word

### 7.104ieee754-div

reduces the list of operands with div

### 7.105taint-policy-select

(taint-policy-select K P) selects the taint propagation policy P for the taints of the kind K

### 7.106taint-get-indirect

(taint-get-indirect K X) returns the indirect taint of the kind K associated with the value X, or nil if there is no such taint

## 8 Signals

### 8.1storing

(storing A) is emitted before store to A occurs

### 8.2interrupt

(interrupt N) is emitted when the hardware interrupt N occurs

### 8.3fini

(fini) occurs when the Primus Machine is finished

### 8.4stored

(stored A X) is emitted when X is stored to A

### 8.5system-stop

(system-stop NAME) occurs when the system with the given name finished its execution. The machine is in the restricted mode in the body of the methods

### 8.6call-return

(call-return NAME X Y … R) is emitted when a call to a function with the symbolic NAME returns with the specified list of arguments X,Y,… and return value R.

### 8.7init

(init) occurs when the Primus Machine is initialized

### 8.9written

(written V X) is emitted when X is written to V

### 8.10machine-kill

(machine-kill) occurs when Machine is killed and could be used for machine cleanup/teardown and analysis summaries. The machine is in the resticted mode in the body of the methods.

### 8.12taint-finalize

(taint-finalize T L) is emitted when the taint T is finilized while still live if L is true or dead if T is false.

### 8.13jumping

(jumping C D) is emitted before jump to D occurs under the condition C

### 8.14pc-changed

(pc-change PC) is emitted when PC is updated

### 8.15call

(call NAME X Y …) is emitted when a call to a function with the symbolic NAME occurs with the specified list of arguments X,Y,…