These files have been made freely available by SGS-Thomson and may not be used to generate commercial products without explicit permission and agreed licensing terms OR placed in a public archive or given to third parties without explicit written permission from SGS-Thomson in Bristol.

Tony Debling, SGS-Thomson Microelectronics Ltd, 1000 Aztec West, Almondsbury, Bristol BS12 4SQ, England. June 7, 1995.

Converted to HTML via RTFtoHTML, PERL5 and by hand by Dave Beckett <D.J.Beckett@ukc.ac.uk>.

WARNING: This has been converted from RTF format and may have mistakes compared to the printed version. If you find any in this file, please send them to me, and I will update it.

Dave Beckett <D.J.Beckett@ukc.ac.uk>

Library Description Source provided Compiler libraries No occamx.lib Multiple length integer arithmetic Floating point functions 32-bit IEEE arithmetic functions 64-bit IEEE arithmetic functions 2D block move library Bit manipulation CRC functions Supplementary floating point support Dynamic code loading support Transputer-related functions User libraries snglmath.lib Single length mathematical functions Yes dblmath.lib Double length mathematical functions Yes tbmaths.lib T400/T414/T425/T426 optimized maths Yes hostio.lib Host file server library Yes streamio.lib Stream I/O library Yes string.lib String handling library Yes convert.lib String conversion library Yes crc.lib Block CRC library Yes xlink.lib Extraordinary link handling library No debug.lib Debugging support library No msdos.lib DOS specific hostio library Yes

Table 1.1 - occam libraries

Any use of a library routine must be in scope with the#USE "hostio.lib"

If the library uses a file of predefined constants (see section 1.2.3) then
this must be declared by an ` #INCLUDE` directive, before the
associated

#INCLUDE "hostio.inc"

File Description hostio.inc Constants for the host file server interface (hostio library) streamio.inc Constants for the stream i/o interface (streamio library) mathvals.inc Maths constants linkaddr.inc Addresses of transputer links ticks.inc Rates of the two transputer clocks msdos.inc DOS specific constants

Table 1.2 - LIbrary constants

Include files should always be declared before the related library.Separate compiler libraries are supplied for different types and families of processors. Processor types supported are:

- T2 family
- T8 family
- 32-bit processors

File Processor types supported occam2.lib T212/T222/T225/M212 occam8.lib T800/T801/T805 occama.lib T400/T414/T425/T426/TA/TB occamutl.lib All virtual.lib All

File names of the compiler libraries must not be changed. The
compiler assumes these filenames, and generates an error if they are
not found. (See section A.4 in the *occam 2 Toolset Reference
Manual* for details of the mechanism for locating files.)

The compiler `` E`' option disables all of the compiler
libraries except

The *occam 2 Reference Manual* contains formal descriptions of
many of the compiler library routines.

As an example of how they may be used, consider an application which
requires compliance with the IEEE standards for **NaNs** (`Not a
Number') and **Infs** (`+/- infinity'). The occam compiler
defaults to non-IEEE behavior i.e. **NaNs** and **Infs** are
treated as errors, whereas ANSI/IEEE 754-1985 requires there to be
error and overflow handling. To obtain IEEE behavior the appropriate
compiler library function must be called.

The following code fragments show a simple addition can be implemented by default or using IEEE-compatible functions.

If ` A`,

A := B + C -- default occam behavior. A := REAL32OP(B, 0, C) -- IEEE function, round -- to nearest only. The 0 -- indicates a `+' -- operation. b, A := IEEE32OP(B, 1, 0, C) -- IEEE function with -- rounding option. The -- 1 indicates round to -- nearest. The 0 -- indicates a `+' -- operation.

Result(s) Function name Parameter specifiers REAL32 ABS VAL REAL32 x REAL32 SQRT VAL REAL32 x REAL32 LOGB VAL REAL32 x INT, REAL32 FLOATING.UNPACK VAL REAL32 x REAL32 MINUSX VAL REAL32 x REAL32 MULBY2 VAL REAL32 x REAL32 DIVBY2 VAL REAL32 x REAL32 FPINT VAL REAL32 x BOOL ISNAN VAL REAL32 x BOOL NOTFINITE VAL REAL32 x REAL32 SCALEB VAL REAL32 x, VAL INT n REAL32 COPYSIGN VAL REAL32 x, y REAL32 NEXTAFTER VAL REAL32 x, y BOOL ORDERED VAL REAL32 x, y BOOL, ARGUMENT.REDUCE VAL REAL32 x, y, y.err INT32, REAL32 REAL32 REAL32OP VAL REAL32 x, VAL INT op, VAL REAL32 y REAL32 REAL32REM VAL REAL32 x, y BOOL,REAL32 IEEE32OP VAL REAL32 x, VAL INT rm, op, VAL REAL32 y BOOL,REAL32 IEEE32REM VAL REAL32 x, y BOOL REAL32EQ VAL REAL32 x, y BOOL REAL32GT VAL REAL32 x, y INT IEEECOMPARE VAL REAL32 x, y REAL64 DABS VAL REAL64 x REAL64 DSQRT VAL REAL64 x REAL64 DLOGB VAL REAL64 x INT,REAL64 DFLOATING.UNPACK VAL REAL64 x REAL64 DMINUSX VAL REAL64 x REAL64 DMULBY2 VAL REAL64 x REAL64 DDIVBY2 VAL REAL64 x REAL64 DFPINT VAL REAL64 x BOOL DISNAN VAL REAL64 x BOOL DNOTFINITE VAL REAL64 x REAL64 DSCALEB VAL REAL64 x, VAL INT n REAL64 DCOPYSIGN VAL REAL64 x, y REAL64 DNEXTAFTER VAL REAL64 x, y BOOL DORDERED VAL REAL64 x, y BOOL, DARGUMENT.REDUCE VAL REAL64 x, y, y.err INT32, REAL64 REAL64 REAL64OP VAL REAL64 x, VAL INT op, VAL REAL64 y REAL64 REAL64REM VAL REAL64 x, y BOOL, REAL64 IEEE64OP VAL REAL64 x, VAL INT rm, op, VAL REAL64 y BOOL, REAL64 IEEE64REM VAL REAL64 x, y BOOL REAL64EQ VAL REAL64 x, y BOOL REAL64GT VAL REAL64 x, y INT DIEEECOMPARE VAL REAL64 x, y INT LONGADD VAL INT left, right, carry.in INT LONGSUM VAL INT left, right, carry.in INT LONGSUB VAL INT left, right, borrow.in INT, INT LONGDIFF VAL INT left, right, borrow.in INT, INT LONGPROD VAL INT left, right, carry.in INT, INT LONGDIV VAL INT dividend.hi, dividend.lo, divisor INT, INT SHIFTLEFT VAL INT hi.in, lo.in, places INT, INT SHIFTRIGHT VAL INT hi.in, lo.in, places INT, INT, INT NORMALISE VAL INT hi.in, lo.in INT ASHIFTLEFT VAL INT argument, places INT ASHIFTRIGHT VAL INT argument, places INT ROTATELEFT VAL INT argument, places INT ROTATERIGHT VAL INT argument, places

` ASHIFTRIGHT`,

Procedure Parameter Specifiers MOVE2D VAL [][]BYTE Source, VAL INT sx, sy, [][]BYTE Dest, VAL INT dx, dy, width, length DRAW2D VAL [][]BYTE Source, VAL INT sx, sy, [][]BYTE Dest, VAL INT dx, dy, width, length CLIP2D VAL [][]BYTE Source, VAL INT sx, sy, [][]BYTE Dest, VAL INT dx, dy, width, length

PROC MOVE2D (VAL [][]BYTE Source, VAL INT sx, sy, [][]BYTE Dest, VAL INT dx, dy, width, length)

Moves a data block of sizebywidthstarting at bytelengthto the block starting atSource[sy][sx]. This is equivalent to:Dest[dy][dx]

SEQ y = 0 FOR length

[Dest[y+dy] FROM dx FOR width] :=

[Source[y+sy] FROM sx FOR width]

PROC DRAW2D (VAL [][]BYTE Source, VAL INT sx, sy, [][]BYTE Dest, VAL INT dx, dy, width, length)

Asbut only non-zero bytes are transferred. This is equivalent to:MOVE2D

SEQ line = 0 FOR length

SEQ point = 0 FOR width

VAL temp IS Source[line+sy][point+sx] :

IF

temp <> (0(BYTE))

Dest[line+dy][point+dx] := temp

TRUE

SKIP

PROC CLIP2D (VAL [][]BYTE Source, VAL INT sx, sy, [][]BYTE Dest, VAL INT dx, dy, width, length)

Asbut only zero bytes are transferred. This is equivalent to:MOVE2D

SEQ line = 0 FOR length

SEQ point = 0 FOR width

VAL temp IS Source[line+sy][point+sx] :

IF

temp = (0(BYTE))

Dest[line+dy][point+dx] := 0(BYTE)

TRUE

SKIP

Result Function name Parameter Specifiers INT BITCOUNT VAL INT Word, CountIn INT BITREVNBITS VAL INT x, n INT BITREVWORD VAL INT x

INT FUNCTION BITCOUNT (VAL INT Word, CountIn)

Counts the number of bits set to 1 in, adds it toWord, and returns the total.CountIn

INT FUNCTION BITREVNBITS (VAL INT x, n)

Returns ancontaining the n least significant bits ofINTin reverse order. The upper bits are set to zero. The operation is invalid ifxis negative or greater than the number of bits in a word.n

INT FUNCTION BITREVWORD (VAL INT x)

Returns ancontaining the bit reversal ofINT.x

Result Function name Parameter Specifiers INT CRCWORD VAL INT data, CRCIn, generator INT CRCBYTE VAL INT data, CRCIn, generatorA cyclic redundancy check value is the remainder from modulo 2 polynomial division. Consider bit sequences as representing the coefficients of polynomials; for example, the bit sequence 10100100 (where the leading bit is the most significant bit) corresponds to

(x^(n) H(x) +F(x))/G(x)

where:

F(x) corresponds to(the whole word fordata; only theCRCWORDmostsignificant byte for)CRCBYTE

When representingG(x) corresponds togeneratorH(x) corresponds toCRCInnis the word size in bits of the processor used (i.e.nis 16 or 32). (can be viewed as the value that would be pre-loaded into the cyclic shift register that is part of hardware implementations of CRC generators.)CRCIn

A similar situation holds on a 32-bit processor, so that:

*G*(*x*) = *x*^(32) + *x*^(26) + *x*^(23)
+*x*^(22) + *x*^(16) + *x*^(12) + *x*^(11) + *x*^(10)
+ *x*^(8) + *x*^(7) + *x*^(5) +*x*^(4) + *x*^(2) +
*x* + 1

is encoded in ` generator` as #04C11DB7.

It is possible to calculate a 16-bit CRC on a 32-bit processor. For
example if *G*(*x*) = *x*^(16) + *x*^(12) + *x*^(5) +
1, then ` generator` is #10210000, because the most significant 16
bits of the 32-bit integer form a 16-bit generator and for:

, the least significant 16 bits ofCRCWORDform the initial CRC value; the most significant 16 bits ofCRCInform the data; and the calculated CRC is the most significant 16 bits of the result.data, the most significant 16 bits ofCRCBYTEform the initial CRC value; the next 8 bits ofCRCIn(the third most significant byte) form the byte of data; and the calculated CRC is the most significant 16 bits of the result.CRCIn

INT FUNCTION CRCWORD (VAL INT data, CRCIn, generator)

Takes the whole of the wordto correspond todataF(x) in the above formula. This implements the following algorithm:

INT MyData, CRCOut, OldCRC :

VALOF

SEQ

MyData, CRCOut := data, CRCIn

SEQ i = 0 FOR BitsPerWord -- 16 or 32

SEQ

OldCRC := CRCOut

CRCOut, MyData := SHIFTLEFT (CRCOut, MyData, 1)

IF

OldCRC < 0 -- MSB of CRC = 1

CRCOut := CRCOut >< generator

TRUE

SKIP

RESULT CRCOut

INT FUNCTION CRCBYTE (VAL INT data, CRCIn, generator)

Takes themostsignificant byte ofto correspond todataF(x) in the above formula. This implements the following algorithm:

INT MyData, CRCOut, OldCRC :

VALOF

SEQ

MyData, CRCOut := data, CRCIn

SEQ i = 0 FOR 8

SEQ

OldCRC := CRCOut

CRCOut, MyData := SHIFTLEFT (CRCOut, MyData, 1)

IF

OldCRC < 0 -- MSB of CRC = 1

CRCOut := CRCOut >< generator

TRUE

SKIP

RESULT CRCOut

where(x-^(k)H(x) + ^( )F(x))/G(x)

Result(s) Function name Parameter Specifiers INT FRACMUL VAL INT x, y INT, INT, INT UNPACKSN VAL INT x INT ROUNDSN VAL INT Yexp, Yfrac, Yguard

INT FUNCTION FRACMUL (VAL INT x, y)

Performs a fixed point multiplication ofandx, treating each as a binary fraction in the range [-1, 1), and returning their product rounded to the nearest available representation. The value of the fractions represented by the arguments and result can be obtained by multiplying theiryvalue by 2^(INT-31) (on a 32-bit processor) or 2^(-15) (on a 16-bit processor). The result can overflow if bothandxare -1.0. This routine is compiled inline into a sequence of transputer instructions on 32-bit processors, or as a call to a standard library routine for 16-bit processors.y

INT, INT, INT FUNCTION UNPACKSN (VAL INT x)

This returns three parameters; from left to right they are,Xfrac, andXexp.Typeis regarded as an IEEE single length real number (i.e. ax). The function unpacksRETYPED REAL32intox, the (biased) exponent, andXexpthe fractional part, with implicit bit restored. It also returns an integer defining theXfracofType, ignoring the sign bit:x

Type Reason 0 X is zero 1 X is a normalized or denormalized number 2 X is Inf 3 X is NaN

Examples:

returnsUNPACKSN (#40490FDB)returns#C90FDB00 ,#00000080, 1

UNPACKSN (#00000001)returns#00000100 ,#00000001, 1

UNPACKSN (#7FC00001)#40000100 ,#000000FF, 3

This routine is compiled inline into a sequence of transputer instructions on 32-bit processors such as the, which do not have a floating support unit, but do have special instructions for floating point operations. For other 32-bit processors the function is compiled as a call to a standard library routine. It is invalid on 16-bit processors, sinceIMS T425cannot fit into anXfrac.INT

INT FUNCTION ROUNDSN (VAL INT Yexp, Yfrac, Yguard)

This takes a possibly unnormalized fraction, guard word and exponent, and returns the IEEE single length floating point value it represents. It takes care of all the normalization, post-normalization, rounding and packing of the result. The rounding mode used is round to nearest. The exponent should already be biased. This routine is not intended for use withandYexprepresenting an infinity or aYfracNaN.Examples:

ROUNDSN(#00000080,#C90FDB00,returns#00000000)#40490FDB

ROUNDSN(#00000080,#C90FDB80,returns#00000000)#40490FDC

ROUNDSN(#00000080,#C90FDA80,returns#00000000)#40490FDA

ROUNDSN(#00000080,#C90FDA80,returns#00003000)#40490FDB

ROUNDSN(#00000001,#00000100,returns#00000000)#00000001

The function normalizes and post-normalizes the number represented by,YexpandYfracinto local variablesYguard,Xexp, andXfrac. It then packs the (biased) exponentXguardand fractionXexpinto the result, rounding using the extra bits inXfrac. The sign bit is set to 0. If overflow occurs,Xguardis returned. This routine is compiled inline into a sequence of transputer instructions on 32-bit processors such as the IMS T425, which do not have a floating support unit, but do have special instructions for floating point operations. For other 32-bit processors the function is compiled as a call to a standard library routine. It is invalid on 16-bit processors, sinceInfcannot fit into anXfrac.INT

Procedure Parameter Specifiers KERNEL.RUN VAL []BYTE code, VAL INT entry.offset, []INT workspace, VAL INT no.of.parameters LOAD.INPUT.CHANNEL INT here, CHAN OF ANY in LOAD.INPUT.CHANNEL.VECTOR INT here, []CHAN OF ANY in LOAD.OUTPUT.CHANNEL INT here, CHAN OF ANY out LOAD.OUTPUT.CHANNEL.VECTOR INT here, []CHAN OF ANY out LOAD.BYTE.VECTOR INT here, VAL []BYTE bytes

Result(s) Function name Parameter Specifiers INT WSSIZEOF routinename INT VSSIZEOF routinename

PROC KERNEL.RUN (VAL []BYTE code, VAL INT entry.offset, []INT workspace, VAL INT no.of.parameters)

The effect of this procedure is to call the procedure loaded in thebuffer, starting execution at the locationcode. Thecode[entry.offset]to be called must begin at a word-aligned address. To ensure proper alignment either start the array at zero or realign the code on a word boundary before passing it into the procedure. Thecodebuffer is used to hold the local data of the called procedure. The required size of this buffer, and the code buffer, must be derived by visually inspecting the executable code file (workspacefile) to be loaded using the binary lister tool.rsc. Alternatively, a routine can be written to read this file and pass the information toilist. The format of theKERNEL.RUNfile is described in section 18.4 of the.rscTools Reference Manual. The parameters passed to the called procedure should be placed at the top of thebuffer by the calling procedure before the call ofworkspace. The call toKERNEL.RUNreturns when the called procedure terminates. If the called procedure requires a separate vector space, then another buffer of the required size must be declared, and its address placed as the last parameter at the top ofKERNEL.RUN. As calls ofworkspaceare handled specially by the compiler it is necessary forKERNEL.RUNto be a constant known at compile time and to have a value . 3. The workspace passed tono.of.parametersmust be at least:KERNEL.RUN

[ws.requirement + (no.of.parameters + 2)]INT

whereis the size of workspace required, determined when the called procedure was compiled and stored in the code file, andws.requirementincludes the vector space pointer if it is required. The parameters must be loaded before the call ofno.of.parameters. The parameter corresponding to the first formal parameter of the procedure should be in the word adjacent to the savedKERNEL.RUNIptrword, and the vector space pointer or the last parameter should be adjacent to the top of workspace where theWptrword will be saved.

LOAD.INPUT.CHANNEL (INT here, CHAN OF ANY in)

The variableis assigned the address of the input channelhere. The normal protocol checking of channel parameters is suppressed; therefore channels of any protocol may be passed to this routine. The channel parameter is considered by the compiler to have been used for input.in

LOAD.INPUT.CHANNEL.VECTOR (INT here, []CHAN OF ANY in)

The variableis assigned the address of the base element of the channel arrayhere(i.e. the base of the array of pointers). The normal protocol checking of channel parameters is suppressed; therefore channels of any protocol may be passed to this routine. The channel parameter is considered by the compiler to have been used for input.in

LOAD.OUTPUT.CHANNEL (INT here, CHAN OF ANY out)

The variableis assigned the address of the output channelhere. The normal protocol checking of channel parameters is suppressed; therefore channels of any protocol may be passed to this routine. The channel parameter is considered by the compiler to have been used for input.out

LOAD.OUTPUT.CHANNEL.VECTOR (INT here, []CHAN OF ANY out)

The variableis assigned the address of the base element of the channel arrayhere(i.e. the base of the array of pointers). The normal protocol checking of channel parameters is suppressed; therefore channels of any protocol may be passed to this routine. The channel parameter is considered by the compiler to have been used for input.out

LOAD.BYTE.VECTOR (INT here, VAL []BYTE bytes)

The variableis assigned the address of the byte arrayhere. This can be used in conjunction withbytesto find the address of any variable.RETYPES

INT FUNCTION WSSIZEOF (routinename)

This function returns the number of workspace `slots' (words) required by the procedure or functionroutinename.or predefined routines are not permitted.INLINE

INT FUNCTION VSSIZEOF (routinename)

This function returns the number of vectorspace `slots' (words) required by the procedure or function.routinenameor predefined routines are not permitted.INLINE

Procedure Parameter Specifiers CAUSEERROR () RESCHEDULE ()

CAUSEERROR()

Inserts instructions into the program to set the transputer error flag. If the program is in STOP or UNIVERSAL mode instructions to stop the current process are also inserted. The error is then treated in exactly the same way as any other error would be treated in the error mode in which the program is compiled. For example, in HALT mode the whole processor will halt and in STOP mode that process will stop, leaving the transputer error flag set. If run-time error checking has been suppressed (e.g. by a command line option), this stop is suppressed. The difference betweenTRUEand theCAUSEERROR()process, is thatSTOPguarantees to set the transputer's error flag.CAUSEERROR

RESCHEDULE()

This causes the current process to be rescheduled by inserting instructions into the program to cause the current process to be moved to the end of the current priority scheduling queue. This occurs even if the current process is a `high priority' process.effectively forces a `timeslice', even in high priority.RESCHEDULE

Procedure Parameter Specifiers ASSERT VAL BOOL test

PROC ASSERT (VAL BOOL test)

At compile time the compiler will check the value ofand if it istestthe compiler will give a compile time error; if it isFALSE, the compiler does nothing. IfTRUEcannot be checked at compile-time then the compiler will insert a run-time check to detect its status. This run-time check may be disabled by means of a command line option.testis a useful routine for debugging purposes. Once a program is working correctly the compiler option `ASSERT' can be used to prevent code being generated to check forNAs at run-time. If possibleASSERTs will still be checked at compile time.ASSERT