VIRTUOSO for LOGICAL SYSTEMS C -- Release 3.092 (7/3/1994) ___________________________________________________________________________ 0. INTRODUCTION This is the release of VIRTUOSO version 3.092 for Logical Systems C. A number of features are missing or not fully operational in this version : - Some functions are missing in the TL debugger : - network info - task manager - The KS_Abort function will stop a task, but does not clean up in case the task was in the middle of a kernel service. We are rethinking this system, as is it incredibly complicated to support correctly in a multiple processor system. The task abort services may be replaced by something more like POSIX signals in future versions. ___________________________________________________________________________ 1. INSTALLATION An INSTALL.BAT file is provided. You will have to specify the source and destination drives. The root directory (default \VIRTUOSO.309\LSC) can be modified by editing INTSTALL.BAT. The batch file will create the following directory structure : C:\VIRTUOSO.309\LSC\BIN : This directory contains .EXE and .BAT files and should be included in your DOS path. C:\VIRTUOSO.309\LSC\LIB : Virtuoso libraries. C:\VIRTUOSO.309\LSC\INC : Header files necessary for application development. This directory should be part of the compiler include search path. C:\VIRTUOSO.309\LSC\SOURCE : Sources for the kernel, the host program, the C preprocessor, and the system generation tool. C:\VIRTUOSO.309\LSC\EXAMPLES : Some example programs We assume the compiler is installed in C:\LSC. If not, the makefiles should be modified accordingly. ___________________________________________________________________________ 2. APPLICATION DEVELOPMENT HINTS The easiest way to start is to copy and modify one of the supplied examples. Some of the necessary files have fixed names, so each application should be put in a separate directory. The following files will be needed for each application : SYSDEF : the VIRTUOSO system definition file. The SYSGEN utility will read this file and generate the NODE#.C, NODE#.H and ALLNODES.H files. MAKEFILE : the makefiles supplied in the EXAMPLES directory can easily be modified for your application. They also show how to organise things so you can optionally include the task level debugger. MAIN#.C : this contains some more configuration options, and the C 'main' function. Copy from one of the examples. In most cases, all MAIN#.C files are identical. A number of configuration options are defined in this file, so they can be changed without requiring recompilation of all sources (this would be necessary if SYSDEF is modified). CLCKFREQ : this should be defined to be the clock frequency of the hardware timer used to generate the TICKS time. This is 1MHz for all transputers. TICKTIME : the TICK period in microseconds. TICKUNIT : the TICK period in CLCKFREQ units (so equals TICKTIME) TICKFREQ : the TICK frequency in Hertz. MONITSIZE : see below MONITMASK : see below The number of available timers, data and command packets are also defined in this file. How much you need of each depends on your application, but the following guidelines may be followed : - TIMERS can be allocated by user tasks, and are used to implement timeouts. - COMMAND PACKETS are used for remote services and timers. A good starting value will be NUMBER OF TASKS * 5. - DATA PACKETS are used to buffer raw and message data when passing through a node (not at the endpoints - if you have less than three nodes, you don't need data packets). Four buffers for each concurrent data transmission will usually be enough. MAIN#.C also defines some variables used by the console driver tasks, the clock system, the debugger task, and the graphics system. These are included automatically if you use the standard names for the required kernel objects. YOUR SOURCE FILES. ___________________________________________________________________________ 3. THE HOST PROGRAM In this release, only the server function of the host program must be used. The files produced by the LSC tools are not in a format that can put straight onto a transputer link. For booting a network, the LSC tool LOAD-NET.EXE should be used (see the LSC manual). When the network has been loaded, LINKHOST.EXE should be started to provide services to the network (the LSC server tool CIO.EXE can not be used with VIRTUOSO). So for each application, there will be a *.NIF file (for LOAD-NET), and a *.NLI file (for LINKHOST). Although LINKHOST is not used for booting the network, the NLI file is still required as it contains the interface address to be used by the server. Since LNKHOST does not like to see empty networks, a dummy network (just one processor will do) must be specified in the NLI file. The file \BIN\RUN.BAT is provided to load an application. Sample NIF and NLI files are provided with the examples. Clearly, all this could be simplified by stripping LINKHOST.EXE. Please contact ISI for details in case you want to port the host program to another system. ___________________________________________________________________________ 4. NEW FEATURES IN THIS RELEASE 4.1 Task level monitor ------------------ The task level monitor (part of the TL debugger) keeps a record of the recent execution history of an application. Three types of information can be traced : - Task swaps - Kernel services - Task state changes The monitor is configured by two defines in the MAIN#.C files. These can be modified if necessary. MONITSIZE : the length of the circular buffer used to store monitoring information (number of items stored). MONITMASK : the type of information to be traced. It can be MON_ALL, to trace all types listed above, or a bitwise OR of any of MON_TSWAP, MON_KSERV, and MON_STATE, or zero (no monitoring). MONITMASK is used to initialise a global variable 'int monitmask', that can be modified at run time, e.g. if you want to monitor only part of an application. 4.2 server_getarg () ---------------- As all server_... functions, this service is available on the ROOTNODE only. It can be used to read arguments following the network file name on the host program command line. Syntax : int server_getarg (int argnum, char *buffer, int buflen); The function returns nom-zero if the arument is present, and zero otherwise. Argument 0 is the *.NLI filename. An example of this call can be found in EXAMPLES\B2\MASTER.C 4.3 server_putstring () ---------------- As all server_... functions, this service is available on the ROOTNODE only. This function was introduced mainly for use by the debugger task. It can be used to print strings to the screen in applications not using STDIO. Syntax : int server_putstring (char *string); 4.4 user host service ----------------- The host program can easily be extended by the user. See SOURCE\LINKHOST\USER.C and EXAMPLES\USER\TEST1.C 4.5 support for Parsytec boards --------------------------- For parsytec boards, simply replace the call to 'netload ()' in all main#.c files by 'parsytec_netload ()'. This subroutine uses the special Parsytec reset hardware. ___________________________________________________________________________