Index: doc/man/README =================================================================== --- doc/man/README (revision 99f41650a8adbc2f6b81ca53ccea7c333e2bb273) +++ doc/man/README (revision 99f41650a8adbc2f6b81ca53ccea7c333e2bb273) @@ -0,0 +1,5 @@ +There are two troff variables at the beginning of the source files that define +the home path to cfa and the version number. The version variable should be +set properly (we sometimes forget); change the path for the home variable to +the location where cfa is installed. There is a command at the beginning of the +source file to format the manual entry. Index: doc/man/cfa.1 =================================================================== --- doc/man/cfa.1 (revision 99f41650a8adbc2f6b81ca53ccea7c333e2bb273) +++ doc/man/cfa.1 (revision 99f41650a8adbc2f6b81ca53ccea7c333e2bb273) @@ -0,0 +1,186 @@ +.\" -*- Mode: Nroff -*- +.\" +.\" uC++ Version 6.1.0, Copyright (C) Peter A. Buhr 1994 +.\" +.\" u++.1 -- +.\" +.\" Author : Peter A. Buhr +.\" Created On : Sat Jul 2 21:47:05 1994 +.\" Last Modified By : Peter A. Buhr +.\" Last Modified On : Fri Apr 6 13:44:28 2012 +.\" Update Count : 52 +.\" +.\" nroff -man u++.1 +.\" +.ds Ho "/usr/local +.ds Vr "u++\-6.1.0 +.TH u++ 1 +.SH NAME +u++ \- uC++ Translator and Concurrency Runtime System +.SH SYNOPSIS +u++ [-option [...]] [filename [...]] +.SH DESCRIPTION +The u++ command compiles uC++ and C++ source files and links C++ object files +named on the command line. + +The u++ command introduces a translator pass over the specified source files +after the C preprocessor but before the actual C++ compilation. The translator +converts several new uC++ constructs into C++ statements. The u++ command also +provides the runtime concurrency library, which must be linked with each uC++ +application. + +The command line options depend on the particular C++ compiler used. As with +most C compilers, the output is sent to the file a.out(5) unless the -o option +is present on the command line. See the reference pages for g++(1) and CC(1) +for more information. +.SH OPTIONS +When multiple conflicting options appear on the command line, e.g., +.B -debug +followed by +.B -nodebug, +the last option takes precedence. +All of the options available to the C++ compiler are available to u++, plus the +following: +.IP -debug 3 +The program is linked with the debugging version of the unikernel or +multikernel. The debug version performs runtime checks to help during the +debugging phase of a uC++ program, but substantially slows the execution of the +program. This option is the default. +.IP -nodebug +The program is linked with the non-debugging version of the unikernel or +multikernel, so the execution of the program is faster. However, no runtime +checks or asserts are performed so errors usually result in abnormal program +termination. +.IP -yield +When a program is translated, a random number of context switches occur at the +beginning of each member routine so that during execution on a uniprocessor +there is a better simulation of parallelism. (This non-determinism in +execution is in addition to random context switching due to pre-emptive +scheduling. The extra yields of execution can help during the debugging phase +of a uC++ program, but substantially slows the execution of the program. +.IP -noyield +Additional context switches are not inserted in member routines. This option +is the default. +.IP -verify +When a program is translated, a check to verify that the stack has not +overflowed occurs at the beginning of each member routine. Verifying the +stack has not overflowed is important during the debugging phase of a uC++ +program, but slows the execution of the program. +.IP -noverify +Stack-overflow checking is not inserted in member routines. This option is the +default. +.IP -multi +The program is linked with the multikernel. See the uC++ RUNTIME KERNELS +section below. +.IP -nomulti +The program is linked with the unikernel. This option is the default. See the +uC++ RUNTIME KERNELS section below. +.IP -quiet +The uC++ compilation message is not printed at the beginning of a +compilation. +.IP -noquiet +The uC++ compilation message is printed at the beginning of a compilation. +This option is the default. +.IP -U++ +Only the C preprocessor and the uC++ translator steps are performed and the +transformed program is written to standard output, which makes it possible to +examine the code generated by the uC++ translator. +.IP "-compiler path-name" +The path-name of the compiler used to compile a uC++ program(s). The default +is the compiler used to compile the uC++ runtime library. It is unsafe to use +a different compiler unless the generated code is binary compatible. +.SH uC++ RUNTIME KERNELS +There are two versions of the uC++ kernel: the unikernel, which is designed to +use a single processor; and the multikernel, which is designed to use several +processors. Thus, the unikernel is sensibly used on systems with a single +hardware processor or when kernel threads are unavailable; the multikernel is +sensibly used on systems that have multiple hardware processors and when kernel +threads are available. The table below shows the situations where each kernel +can be used. The unikernel can be used in a system with multiple hardware +processors and kernel threads but does not take advantage of either of these +capabilities. The multikernel can be used on a system with a single hardware +processor and kernel threads but performs less efficiently than the unikernel +because it uses multiprocessor techniques unnecessarily. +.DS B + +-----------+-------------------------+ + | no kernel | kernel | + | threads | threads | + +----------+-----------+-------------------------+ + |single |uni: yes |uni: yes | + |processor |multi: no |multi: yes (inefficient) | + +----------+-----------+-------------------------+ + |multiple |uni: yes |uni: yes (no parallelism)| + |processors|multi: no |multi: yes | + +----------+-----------+-------------------------+ +.DE +.SH PREPROCESSOR VARIABLES +When programs are compiled using u++, the following preprocessor variables are +available. These variables allow conditional compilation of programs that must +work differently in these situations. +.IP __U_CPLUSPLUS__ 3 +is always available during preprocessing and its value is the current major +version number. +.IP __U_CPLUSPLUS_MINOR__ +is always available during preprocessing and its value is the current minor +version number. +.IP __U_CPLUSPLUS_PATCH__ +is always available during preprocessing and its value is the current patch +version number. +.IP __U_DEBUG__ +is available during preprocessing if the -debug compilation option is +specified. +.IP __U_YIELD__ +is available during preprocessing if the -yield compilation option is +specified. +.IP __U_VERIFY__ +is available during preprocessing if the -verify compilation option is +specified. +.IP __U_MULTI__ +is available during preprocessing if the -multi compilation option is specified. +.SH FILES +.DS B +file.{cc,C} - uC++ source file +.br +file.s - assembly language file +.br +file.o - object file +.br +\*(Ho/bin/u++ - translator +.br +\*(Ho/\*(Vr/doc - reference manual and license +.br +\*(Ho/\*(Vr/inc - header files +.br +\*(Ho/\*(Vr/lib - run time libraries +.br +\*(Ho/\*(Vr/man - command documentation +.br +\*(Ho/\*(Vr/src - source code (optional) +.DE +.SH SEE ALSO +CC(1), cpp(1), g++(1) +.br +.I "uC++ Annotated Reference Manual" +.br +.I "Understanding Control Flow with Concurrent Programming using uC++" +.SH REFERENCES +.HP 3 +.I "uC++: Concurrency in the Object-Oriented Language C++," +by P.A. Buhr, G. Ditchfield, R.A. Stroobosscher, B.M. Younger, C.R. Zarnke; +Software-Practise and Experience, 22(2):137--172, February 1992. This paper +describes uC++ v2.0, which has been significantly extended. +.HP +.I "Examining uC++," +by Peter A. Buhr and Richard C. Bilson; +Dr. Dobb's Journal : Software Tools for the Professional Programmer, +31(2):36--40, February 2006. +.HP +.I "uC++ Annotated Reference Manual" +most up-to-date features. +.SH BUGS +Bugs should be reported to usystem@plg.uwaterloo.ca. +.SH COPYRIGHT +This library is covered under the GNU Lesser General Public License. +.SH AUTHORS +Peter A. Buhr (pabuhr@plg.uwaterloo.ca) and many others, Programming Languages +Group, University of Waterloo, Ontario, Canada, N2L 3G1.