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 directive which references the associated library. The scope of a library, like any occam declaration, depends on its level of indentation within the text.#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 #USE. For example:
#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:
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 Alloccamutl.lib contains routines which are called from within some of the other compiler libraries and virtual.lib is used to support interactive debugging. These two libraries support all processor types and error modes.
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 virtual.lib, which can be disabled by the `Y' option.
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, B, and C are REAL32s and b is a BOOL:
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, ASHIFTLEFT, ROTATERIGHT and ROTATELEFT are all invalid when the number of places to shift is negative or exceeds the transputer's word length.
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
MOVE2D
PROC MOVE2D (VAL [][]BYTE Source,
VAL INT sx, sy, [][]BYTE Dest,
VAL INT dx, dy, width, length)
Moves a data block of size width by length starting at byte Source[sy][sx] to the block starting at Dest[dy][dx]. This is equivalent to:
DRAW2D
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)
As MOVE2D but only non-zero bytes are transferred. This is equivalent to:
CLIP2D
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)
As MOVE2D but only zero bytes are transferred. This is equivalent to:
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 xBITCOUNT
INT FUNCTION BITCOUNT (VAL INT Word, CountIn)
Counts the number of bits set to 1 in Word, adds it to CountIn, and returns the total.BITREVNBITS
INT FUNCTION BITREVNBITS (VAL INT x, n)
Returns an INT containing the n least significant bits of x in reverse order. The upper bits are set to zero. The operation is invalid if n is negative or greater than the number of bits in a word.BITREVWORD
INT FUNCTION BITREVWORD (VAL INT x)
Returns an INT containing the bit reversal of x.
Result Function name Parameter Specifiers
INT CRCWORD VAL INT data, CRCIn,
generator
INT CRCBYTE VAL INT data, CRCIn,
generator
A 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 P(x) = x^(7) +
x^(5) + x^(2). CRCWORD and CRCBYTE
calculate the remainder of the modulo 2 polynomial division:
(x^(n) H(x) +F(x))/G(x)
F(x) corresponds to data (the whole word for CRCWORD; only the most significant byte for CRCBYTE)
G(x) corresponds to generator H(x) corresponds to CRCIn n is the word size in bits of the processor used (i.e. n is 16 or 32). (CRCIn 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.)When representing G(x) in the word generator, note that there is an understood bit before the msb of generator. For example, on a 16-bit processor, with G(x) = x^(16) + x^(12) + x^(5) + 1, which is #11021, then generator must be assigned #1021, because the bit corresponding to x^(16) is understood. Thus, a value of #9603 for generator, corresponds to G(x) = x^(16) + x^(15) + x^(12) +x^(10) + x^(9) + x + 1, for a 16-bit processor.
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:
CRCWORD, the least significant 16 bits of CRCIn form the initial CRC value; the most significant 16 bits of data form the data; and the calculated CRC is the most significant 16 bits of the result. CRCBYTE, the most significant 16 bits of CRCIn form the initial CRC value; the next 8 bits of CRCIn (the third most significant byte) form the byte of data; and the calculated CRC is the most significant 16 bits of the result.CRCWORD
INT FUNCTION CRCWORD (VAL INT data, CRCIn, generator)
Takes the whole of the word data to correspond to F(x) in the above formula. This implements the following algorithm:
CRCBYTE
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 the most significant byte of data to correspond to F(x) in the above formula. This implements the following algorithm:
Note: The predefines CRCBYTE and CRCWORD can be chained together to help calculate a CRC from a string considered as one long polynomial. A simple chaining would calculate:
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 F(x) corresponds to the string and k is the number of bits in the string. This is not the same CRC that is calculated by CRCFROMMSB and CRCFROMLSB in crc.lib, section 1.9, because these latter routines shift the numerator by x^(n).(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, YguardFRACMUL
INT FUNCTION FRACMUL (VAL INT x, y)
Performs a fixed point multiplication of x and y, 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 their INT value by 2^(-31) (on a 32-bit processor) or 2^(-15) (on a 16-bit processor). The result can overflow if both x and y are -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.UNPACKSN
INT, INT, INT FUNCTION UNPACKSN (VAL INT x)
This returns three parameters; from left to right they are Xfrac, Xexp, and Type. x is regarded as an IEEE single length real number (i.e. a RETYPED REAL32). The function unpacks x into Xexp, the (biased) exponent, and Xfrac the fractional part, with implicit bit restored. It also returns an integer defining the Type of x, ignoring the sign bit:
Type Reason 0 X is zero 1 X is a normalized or denormalized number 2 X is Inf 3 X is NaN
Examples:
UNPACKSN (#40490FDB) returns #C90FDB00 ,#00000080, 1
UNPACKSN (#00000001) returns #00000100 ,#00000001, 1
UNPACKSN (#7FC00001) returns #40000100 ,#000000FF, 3
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, since Xfrac cannot fit into an INT.ROUNDSN
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 with Yexp and Yfrac representing an infinity or a NaN. Examples:
ROUNDSN (#00000080, #C90FDB00, #00000000) returns #40490FDB
ROUNDSN (#00000080, #C90FDB80, #00000000) returns #40490FDC
ROUNDSN (#00000080, #C90FDA80, #00000000) returns #40490FDA
ROUNDSN (#00000080, #C90FDA80, #00003000) returns #40490FDB
ROUNDSN (#00000001, #00000100, #00000000) returns #00000001
The function normalizes and post-normalizes the number represented by Yexp, Yfrac and Yguard into local variables Xexp, Xfrac, and Xguard. It then packs the (biased) exponent Xexp and fraction Xfrac into the result, rounding using the extra bits in Xguard. The sign bit is set to 0. If overflow occurs, Inf is 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, since Xfrac cannot fit into an 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 routinenameKERNEL.RUN
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 the code buffer, starting execution at the location code[entry.offset]. The code 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. The workspace buffer 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 (.rsc file) to be loaded using the binary lister tool ilist. Alternatively, a routine can be written to read this file and pass the information to KERNEL.RUN. The format of the .rsc file is described in section 18.4 of the Tools Reference Manual. The parameters passed to the called procedure should be placed at the top of the workspace buffer by the calling procedure before the call of KERNEL.RUN. The call to KERNEL.RUN returns 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 of workspace. As calls of KERNEL.RUN are handled specially by the compiler it is necessary for no.of.parameters to be a constant known at compile time and to have a value . 3. The workspace passed to KERNEL.RUN must be at least:
[ws.requirement + (no.of.parameters + 2)]INT
where ws.requirement is the size of workspace required, determined when the called procedure was compiled and stored in the code file, and no.of.parameters includes the vector space pointer if it is required. The parameters must be loaded before the call of KERNEL.RUN. The parameter corresponding to the first formal parameter of the procedure should be in the word adjacent to the saved Iptr word, and the vector space pointer or the last parameter should be adjacent to the top of workspace where the Wptr word will be saved.LOAD.INPUT.CHANNEL
LOAD.INPUT.CHANNEL (INT here, CHAN OF ANY in)
The variable here is assigned the address of the input channel in. 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.LOAD.INPUT.CHANNEL.VECTOR
LOAD.INPUT.CHANNEL.VECTOR (INT here,
[]CHAN OF ANY in)
The variable here is assigned the address of the base element of the channel array in (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.LOAD.OUTPUT.CHANNEL
LOAD.OUTPUT.CHANNEL (INT here, CHAN OF ANY out)
The variable here is assigned the address of the output channel out. 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.LOAD.OUTPUT.CHANNEL.VECTOR
LOAD.OUTPUT.CHANNEL.VECTOR (INT here,
[]CHAN OF ANY out)
The variable here is assigned the address of the base element of the channel array out (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.LOAD.BYTE.VECTOR
LOAD.BYTE.VECTOR (INT here, VAL []BYTE bytes)
The variable here is assigned the address of the byte array bytes. This can be used in conjunction with RETYPES to find the address of any variable.WSSIZEOF
INT FUNCTION WSSIZEOF (routinename)
This function returns the number of workspace `slots' (words) required by the procedure or function routinename. INLINE or predefined routines are not permitted.VSSIZEOF
INT FUNCTION VSSIZEOF (routinename)
This function returns the number of vectorspace `slots' (words) required by the procedure or function routinename. INLINE or predefined routines are not permitted.
Procedure Parameter Specifiers CAUSEERROR () RESCHEDULE ()CAUSEERROR
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 TRUE. If run-time error checking has been suppressed (e.g. by a command line option), this stop is suppressed. The difference between CAUSEERROR() and the STOP process, is that CAUSEERROR guarantees to set the transputer's error flag.RESCHEDULE
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. RESCHEDULE effectively forces a `timeslice', even in high priority.
Procedure Parameter Specifiers ASSERT VAL BOOL testASSERT
PROC ASSERT (VAL BOOL test)
At compile time the compiler will check the value of test and if it is FALSE the compiler will give a compile time error; if it is TRUE, the compiler does nothing. If test cannot 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. ASSERT is a useful routine for debugging purposes. Once a program is working correctly the compiler option `NA' can be used to prevent code being generated to check for ASSERTs at run-time. If possible ASSERTs will still be checked at compile time.