# Module `forall` - Definitions available to all occam-pi programs

Definitions available to all occam-pi programs.

The definitions in this module are provided by the compiler or the support library, and are automatically made available for all programs. It is not necessary to explicitly include `forall.module`.

## Index

- Function `ASHIFTLEFT` - Arithmetic left shift on a double length quantity
- Function `ASHIFTRIGHT` - Arithmetic right shift on a double length quantity
- Process `ASSERT` - Causes an error if a condition is false
- Process `BIND.MOBILE` - Bind a piece of (virtual) memory to a mobile
- Process `BIND.MOBILE.HW` - Bind a piece of physical memory to a mobile
- Process `CAUSEERROR` - Set the error flag
- Process `DECPRI` - Obsolete synonym for
- Function `DMA.CAPABLE` - Test whether a mobile is DMA capable
- Process `GETAFF` - Get the affinity of the current process
- Process `GETPRI` - Get the priority level of the current process
- Process `INCPRI` - Obsolete synonym for
- Process `KILLCALL` - Kill a blocking FFI call
- Function `LONGADD` - Signed addition with a carry in
- Function `LONGDIFF` - Unsigned subtraction with a borrow in and a borrow out
- Function `LONGDIV` - Unsigned division of a double length number, producing a single length result
- Function `LONGPROD` - Unsigned multiplication with a carry in, producing a double length result
- Function `LONGSUB` - Signed subtraction with a borrow in
- Function `LONGSUM` - Unsigned addition with a carry in and carry out
- Process `LOWER.PRIORITY` - Lower the priority of the current process by one level
- Process `MAKE.DMA.CAPABLE` - Move a mobile to DMA capable memory
- Process `MEMORY.BARRIER` - Generate a read-write memory barrier
- Function `NORMALISE` - Normalise a double length quantity
- Process `RAISE.PRIORITY` - Raise the priority of the current process by one level
- Process `READ.MEMORY.BARRIER` - Generate a read memory barrier
- Process `RESCHEDULE` - Force rescheduling
- Process `RESIZE.MOBILE.ARRAY.1D` - Resize a 1D mobile array
- Function `ROTATELEFT` - Rotate a word left
- Function `ROTATERIGHT` - Rotate a word right
- Function `RealIDiv` - Perform an unsigned part divide operation
- Process `SETAFF` - Set the affinity of the current process
- Process `SETPRI` - Set the priority level of the current process
- Function `SHIFTLEFT` - Left shift on a double length quantity
- Function `SHIFTRIGHT` - Right shift on a double length quantity
- Function `UNPACKSN` - Unpack a real number in IEEE single precision format
- Function `VSSIZEOF` - Calculate the vectorspace size (in words) of a process
- Process `WAIT.FOR.INTERRUPT` - Wait for a hardware interrupt
- Process `WRITE.MEMORY.BARRIER` - Generate a write memory barrier
- Function `WSSIZEOF` - Calculate the workspace size (in words) of a process

## Declarations

### `unpacksn.occ`:44Function `UNPACKSN`

`INT, INT, INT FUNCTION UNPACKSN ( VAL INT X )`

Unpack a real number in IEEE single precision format

The sign of X is ignored.

#### Parameters:

`VAL INT` | `X` | a REAL32 which has been retyped to an INT

#### Returns:

`INT` |  | the fractional part with the implicit bit before the binary point restored
`INT` |  | the biased exponent, i.e. the actual exponent + 127
`INT` |  | 0 if X is zero; 1 if X is a normalised or denormalised number; 2 if X is "infinity"; 3 if X is a Not-a-Number

### `ridiv.occ`:40Function `RealIDiv`

`INT, INT, INT FUNCTION RealIDiv (VAL INT Hi, Lo, Guard, VAL [2]INT Yfrac)`

Perform an unsigned part divide operation.

#### Parameters:

`VAL INT` | `Hi` | the most significant word of the dividend
`VAL INT` | `Lo` | the middle word of the dividend
`VAL INT` | `Guard` | the least significant word of the dividend
`VAL [2]INT` | `Yfrac` | the two words of the divisor

#### Returns:

`INT` |  | the quotient
`INT` |  | the most significant word of the remainder
`INT` |  | the least significant word of the remainder

### `intrinsics.occ`:44Function `LONGADD`

`INT FUNCTION LONGADD (VAL INT a, b, carry)`

Signed addition with a carry in.

(a + b) + carry

Overflow is an error.

#### Parameters:

`VAL INT` | `a`, `b` | Integers to add.
`VAL INT` | `carry` | Carry flag.

#### Returns:

`INT` |  | Addition of a and b.

### `intrinsics.occ`:55Function `LONGSUM`

`INT, INT FUNCTION LONGSUM (VAL INT a, b, carry)`

Unsigned addition with a carry in and carry out.

(a + b) + carry

#### Parameters:

`VAL INT` | `a`, `b` | Integers to add.
`VAL INT` | `carry` | Carry in flag.

#### Returns:

`INT` |  | The resulting carry out flag.
`INT` |  | The sum of a and b.

### `intrinsics.occ`:67Function `LONGSUB`

`INT FUNCTION LONGSUB (VAL INT a, b, borrow)`

Signed subtraction with a borrow in.

(b - a) - borrow

Overflow is an error.

#### Parameters:

`VAL INT` | `a`, `b` | Integers to subtract.
`VAL INT` | `borrow` | Borrow flag.

#### Returns:

`INT` |  | Subtraction of a and borrow from b.

### `intrinsics.occ`:78Function `LONGDIFF`

`INT, INT FUNCTION LONGDIFF (VAL INT a, b, borrow)`

Unsigned subtraction with a borrow in and a borrow out.

(b - a) - borrow

#### Parameters:

`VAL INT` | `a`, `b` | Integers to subtract.
`VAL INT` | `borrow` | Borrow in flag.

#### Returns:

`INT` |  | Borrow out flag.
`INT` |  | Subtraction of a and borrow from b.

### `intrinsics.occ`:89Function `LONGPROD`

`INT, INT FUNCTION LONGPROD (VAL INT a, b, carry)`

Unsigned multiplication with a carry in, producing a double length result.

(a * b) + carry

#### Parameters:

`VAL INT` | `a`, `b` | Integers to multiply.
`VAL INT` | `carry` | Carry in flag.

#### Returns:

`INT` |  | High order word of result.
`INT` |  | Low order word of result.

### `intrinsics.occ`:103Function `LONGDIV`

`INT, INT FUNCTION LONGDIV (VAL INT u1, u0, v)`

Unsigned division of a double length number, producing a single length result.

[u1, u0] / v

Overflow is an error.

#### Parameters:

`VAL INT` | `u1` | High order word of quantity being divided.
`VAL INT` | `u0` | Low order word of quantity being divided.
`VAL INT` | `v` | Divisor.

#### Returns:

`INT` |  | High order word of result.
`INT` |  | Low order word of result.

### `intrinsics.occ`:115Function `SHIFTRIGHT`

`INT, INT FUNCTION SHIFTRIGHT (VAL INT a1, a0, shift)`

Right shift on a double length quantity.

[a1, a0] >> shift

#### Parameters:

`VAL INT` | `a1` | High order word of quantity being shifted.
`VAL INT` | `a0` | Low order word of quantity being shifted.
`VAL INT` | `shift` | Number of bit places to shift right.

#### Returns:

`INT` |  | High order word of result.
`INT` |  | Low order word of result.

### `intrinsics.occ`:127Function `SHIFTLEFT`

`INT, INT FUNCTION SHIFTLEFT (VAL INT a1, a0, shift)`

Left shift on a double length quantity.

[a1, a0] << shift

#### Parameters:

`VAL INT` | `a1` | High order word of quantity being shifted.
`VAL INT` | `a0` | Low order word of quantity being shifted.
`VAL INT` | `shift` | Number of bit places to shift left.

#### Returns:

`INT` |  | High order word of result.
`INT` |  | Low order word of result.

### `intrinsics.occ`:140Function `NORMALISE`

`INT, INT, INT FUNCTION NORMALISE (VAL INT a1, a0)`

Normalise a double length quantity.

Shift the double word quantity left until the most significant bit is one.

#### Parameters:

`VAL INT` | `a1` | High order word of quantity being normalised.
`VAL INT` | `a0` | Low order word of quantity being normalised.

#### Returns:

`INT` |  | Number of places shifted.
`INT` |  | High order word of result.
`INT` |  | Low order word of result.

### `intrinsics.occ`:151Function `ASHIFTRIGHT`

`INT FUNCTION ASHIFTRIGHT (VAL INT a, shift)`

Arithmetic right shift on a double length quantity.

The operand is expanded to a double length quantity, then arithmetically shifted right, and the low order word returned.

#### Parameters:

`VAL INT` | `a` | The integer being shifted.
`VAL INT` | `shift` | Number of bit places to shift right.

### `intrinsics.occ`:162Function `ASHIFTLEFT`

`INT FUNCTION ASHIFTLEFT (VAL INT a, shift)`

Arithmetic left shift on a double length quantity.

The operand is expanded to a double length quantity, then arithmetically shifted left, and the low order word returned.

#### Parameters:

`VAL INT` | `a` | The integer being shifted.
`VAL INT` | `shift` | Number of bit places to shift left.

### `intrinsics.occ`:170Function `ROTATERIGHT`

`INT FUNCTION ROTATERIGHT (VAL INT val, shift)`

Rotate a word right.

#### Parameters:

`VAL INT` | `val` | The integer being rotated.
`VAL INT` | `shift` | Number of bit places to rotate right.

#### Returns:

`INT` |  | val rotated shift places to the right.

### `intrinsics.occ`:178Function `ROTATELEFT`

`INT FUNCTION ROTATELEFT (VAL INT val, shift)`

Rotate a word left.

#### Parameters:

`VAL INT` | `val` | The integer being rotated.
`VAL INT` | `shift` | Number of bit places to rotate left.

#### Returns:

`INT` |  | val rotated shift places to the left.

### `intrinsics.occ`:186Process `CAUSEERROR`

`PROC CAUSEERROR ()`

Set the error flag.

Sets the runtime error flag, causing either the runtime to error out or the current process to stop, depending on compile-time flags and runtime settings.

### `intrinsics.occ`:195Process `RESCHEDULE`

`PROC RESCHEDULE ()`

Force rescheduling.

This gives the scheduler an opportunity to switch to another process. It may simply return control to the caller if no other process needs to run.

### `intrinsics.occ`:209Process `ASSERT`

`PROC ASSERT (VAL BOOL condition)`

Causes an error if a condition is false.

Asserts that a given condition is true. If the condition is false then the behaviour is that of `CAUSEERROR`.

The compiler may detect false assertions at compile time through static analysis.

#### Parameters:

`VAL BOOL` | `condition` | The condition to test.

### `intrinsics.occ`:219Function `WSSIZEOF`

`INT FUNCTION WSSIZEOF (PROC process)`

Calculate the workspace size (in words) of a process.

#### Parameters:

`PROC` | `process` | Process for which the workspace size is to be calculated.

#### Returns:

`INT` |  | Number of workspace words required by process.

### `intrinsics.occ`:227Function `VSSIZEOF`

`INT FUNCTION VSSIZEOF (PROC process)`

Calculate the vectorspace size (in words) of a process.

#### Parameters:

`PROC` | `process` | Process for which the vectorspace size is to be calculated.

#### Returns:

`INT` |  | Number of vectorspace words required by process.

### `intrinsics.occ`:251Process `GETPRI`

`PROC GETPRI (RESULT INT pri)`

Get the priority level of the current process.

Priority 0 is the highest priority available, and priority 31 is the lowest priority. Priorities are only hints to the scheduler; you must not assume that high-priority processes will always run before low-priority processes.

#### Parameters:

`RESULT INT` | `pri` | The priority of the calling process.

### `intrinsics.occ`:262Process `SETPRI`

`PROC SETPRI (VAL INT pri)`

Set the priority level of the current process.

See `GETPRI` for the meanings of priority levels.

#### Parameters:

`VAL INT` | `pri` | The requested priority for the calling process. Invalid values will be ignored.

### `intrinsics.occ`:270Process `INCPRI`

`PROC INCPRI ()`

Obsolete synonym for `RAISE.PRIORITY`.

Deprecated: do not use in new code.

### `intrinsics.occ`:278Process `DECPRI`

`PROC DECPRI ()`

Obsolete synonym for `LOWER.PRIORITY`.

Deprecated: do not use in new code.

### `intrinsics.occ`:286Process `RAISE.PRIORITY`

`PROC RAISE.PRIORITY ()`

Raise the priority of the current process by one level.

See `GETPRI` for the meanings of priority levels.

### `intrinsics.occ`:294Process `LOWER.PRIORITY`

`PROC LOWER.PRIORITY ()`

Lower the priority of the current process by one level.

See `GETPRI` for the meanings of priority levels.

### `intrinsics.occ`:306Process `GETAFF`

`PROC GETAFF (RESULT INT aff)`

Get the affinity of the current process.

The affinity is a bitmap of logical execution units on which this process may run. The value `-1` means that the process may run on any execution unit.

#### Parameters:

`RESULT INT` | `aff` | The affinity of the calling process.

### `intrinsics.occ`:317Process `SETAFF`

`PROC SETAFF (VAL INT aff)`

Set the affinity of the current process.

See `GETAFF` for the meanings of affinity values.

#### Parameters:

`VAL INT` | `aff` | The requested affinity for the calling process. Invalid values will be ignored.

### `intrinsics.occ`:331Process `KILLCALL`

`PROC KILLCALL (CHAN OF ANY chan, INT res)`

Kill a blocking FFI call.

Kill a `BX.` blocking foreign-function-interface call associated with a channel.

#### Parameters:

`CHAN OF ANY` | `chan` | The channel passed when making the blocking call.
`INT` | `res` | `0` if termination was successfully initiated; `-1` if the call has not yet started; `1` if the call has already terminated.

### `intrinsics.occ`:344Process `WAIT.FOR.INTERRUPT`

`PROC WAIT.FOR.INTERRUPT (VAL INT n, mask, RESULT INT count)`

Wait for a hardware interrupt.

This call is specific to RMoX, and will not be useful for most occam-pi programs.

#### Parameters:

`VAL INT` | `n` | The number of the interrupt to wait for.
`VAL INT` | `mask` | CPU or interrupt mask, implementation dependent.
`RESULT INT` | `count` | The number of missed interrupts.

### `intrinsics.occ`:365Process `BIND.MOBILE`

`PROC BIND.MOBILE (MOBILE.ANY mobile, VAL INT addr)`

Bind a piece of (virtual) memory to a mobile.

Associates a piece of memory with a mobile. The memory at the given address becomes the backing store for the mobile. This is intended for use with `EMPTY` mobiles.

For example, to associate a mobile with memory address `#1000`: `MOBILE []BYTE x: SEQ x := MOBILE EMPTY [1024]BYTE BIND.MOBILE (x, #1000)`

#### Parameters:

`MOBILE.ANY` | `mobile` | The mobile to bind.
`VAL INT` | `addr` | The address of the memory.

### `intrinsics.occ`:377Process `BIND.MOBILE.HW`

`PROC BIND.MOBILE.HW (MOBILE.ANY mobile, VAL INT hw.addr)`

Bind a piece of physical memory to a mobile.

Acts as `BIND.MOBILE`, except a physical address is used. This may be converted to a virtual address by the runtime system.

#### Parameters:

`MOBILE.ANY` | `mobile` | The mobile to bind.
`VAL INT` | `hw.addr` | Hardware address of the memory.

### `intrinsics.occ`:389Function `DMA.CAPABLE`

`BOOL FUNCTION DMA.CAPABLE (MOBILE.ANY mobile)`

Test whether a mobile is DMA capable.

Test to see if a mobile is backed by DMA-accessible memory. The `HWADDROF` operator is only valid on DMA-capable mobiles.

#### Parameters:

`MOBILE.ANY` | `mobile` | The mobile to test.

#### Returns:

`BOOL` |  | Whether the mobile is DMA accessible by hardware.

### `intrinsics.occ`:399Process `MAKE.DMA.CAPABLE`

`PROC MAKE.DMA.CAPABLE (MOBILE.ANY mobile)`

Move a mobile to DMA capable memory.

Make a mobile DMA-capable. If necessary, this will reallocate the mobile in DMA-accessible memory and copy the contents over. If the mobile is already DMA-capable, this is has no effect.

#### Parameters:

`MOBILE.ANY` | `mobile` | The mobile to upgrade.

### `intrinsics.occ`:416Process `RESIZE.MOBILE.ARRAY.1D`

`PROC RESIZE.MOBILE.ARRAY.1D (MOBILE.ANY mobile, VAL INT count)`

Resize a 1D mobile array.

Change the size of a one-dimensional mobile array. The memory associated with the mobile may or may not be reallocated by the runtime system depending on its memory allocator.

All data within the bounds of the new size of the array, and present in the old bounds of the array will be preserved.

#### Parameters:

`MOBILE.ANY` | `mobile` | Mobile array to resize.
`VAL INT` | `count` | The new element count.

### `intrinsics.occ`:430Process `MEMORY.BARRIER`

`PROC MEMORY.BARRIER ()`

Generate a read-write memory barrier.

A memory barrier is unrelated to occam-pi `BARRIER`s; it is a synchronisation point for memory operations within a computer system. After the completion of a memory barrier instruction, the affected memory operations are guaranteed to be visible to peripherals and other processors.

This is equivalent to executing both `READ.MEMORY.BARRIER` and `WRITE.MEMORY.BARRIER`.

### `intrinsics.occ`:438Process `READ.MEMORY.BARRIER`

`PROC READ.MEMORY.BARRIER ()`

Generate a read memory barrier.

See `MEMORY.BARRIER` for the semantics of memory barriers.

### `intrinsics.occ`:446Process `WRITE.MEMORY.BARRIER`

`PROC WRITE.MEMORY.BARRIER ()`

Generate a write memory barrier.

See `MEMORY.BARRIER` for the semantics of memory barriers.