diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 000000000..771c1d049 --- /dev/null +++ b/man/Makefile @@ -0,0 +1,35 @@ +all: + -tbl macro.v7 ack.1 | nroff >ack.opr + -nroff macro.v7 arch.1 >arch.1.opr + -nroff macro.v7 arch.5 >arch.5.opr + -nroff macro.v7 libmon.7 > libmon.opr + -nroff macro.v7 libpc.7 > libpc.opr + -nroff macro.v7 em_ass.6 > em_ass.opr + -nroff macro.v7 em_decode.6 > em_decode.opr + -nroff macro.v7 em_opt.6 > em_opt.opr + -nroff macro.v7 em_pem.6 > em_pem.opr + -nroff macro.v7 pc_prlib.7 > pc_prlib.opr + -nroff macro.v7 uni_ass.6 >uni_ass.opr + +install: + -tbl ack.1 >/usr/man/man1/ack.1 + -cp arch.1 /usr/man/man1/arch.1 + -cp arch.5 /usr/man/man5/arch.5 + -cp libmon.7 /usr/man/man7/em_libmon.7 + -cp libpc.7 /usr/man/man7/em_libpc.7 + -cp em_ass.6 /usr/man/man6/em_ass.6 + -cp em_decode.6 /usr/man/man6/em_decode.6 + -cp em_opt.6 /usr/man/man6/em_opt.6 + -cp em_pem.6 /usr/man/man6/em_pem.6 + -cp pc_prlib.7 /usr/man/man7/em_pc_prlib.7 + -cp uni_ass.6 /usr/man/man6/uni_ass.6 + +opr: + make pr | opr + +pr: + @make all >make.pr.out 2>&1 & + @cat *.opr + +clean: + -rm -f *.opr diff --git a/man/a.out.5 b/man/a.out.5 new file mode 100644 index 000000000..6f6289779 --- /dev/null +++ b/man/a.out.5 @@ -0,0 +1,45 @@ +.TH A.OUT 5 +.SH NAME +a.out \- universal assembler load format +.SH DESCRIPTION +The load files produced by the universal assemblers look very +much alike. +These load files consist of sequences of variable length +records, each describing a part of the initialized memory. +Bss type memory is left uninitialized by the universal assembler +and has to be initialized at run-time. +The EM header em_head will perform this task on most systems. +Each record consists of a \fIcount\fP, an \fIaddress\fP and +\fIcount\fP bytes. +The first byte should be placed at \fIaddress\fP, the second at +\fIaddress+1\fP, etc. + +.nf +struct loadf { + unsigned short l_addr[2] ; /* address */ + short l_cnt ; /* count */ + unsigned char data[] ; /* data */ +} ; +.fi + +This representation is machine dependent in two ways. +First, the byte order in the first three fields is the byte order +of the machine the universal assembler is running. +Second, the format of the address differs from machine to machine. +.br +For example, for the Intel 8086 the first entry contains a +16-bit offset and the second entry a segment number. +The segment number has to be multiplied by 16 and added to +the addres to obtain the address of the first byte to be +initialized. +.br +The PDP 11 version stores the address in l_addr[0] and the type +of the initialized memory in l_addr[1]. +Types 1 and 3 are absolute, 4 is text, 5 is data and 6 BSS. +.br +For all other currently available machines the +array of shorts is 'replaced' by a long. +This long contains the 32-bit address. +.SH "SEE ALSO" +uni_ass(VI) +.SH BUGS diff --git a/man/arch.1 b/man/arch.1 new file mode 100644 index 000000000..92c74ffe6 --- /dev/null +++ b/man/arch.1 @@ -0,0 +1,134 @@ +.TH ARCH 1 +.SH NAME +arch \- archive and library maintainer +.SH SYNOPSIS +.B arch +key [ posname ] afile name ... +.SH DESCRIPTION +.I Arch +maintains groups of files +combined into a single archive file. +Its main use +is to create and update library files as used by a linker. +It can be used, though, for any similar purpose. +The Amsterdam compiler kit provides its own archiver with a +fixed, machine-independent format, much like the UNIX-V7 +archive format. +EM programs using libraries assume archives in EM format. +.PP +.I Key +is one character from the set +.B drqtpmx, +optionally concatenated with +one or more of +.B vuaibcl. +.I Afile +is the archive file. +The +.I names +are constituent files in the archive file. +The meanings of the +.I key +characters are: +.TP +.B d +Delete the named files from the archive file. +.TP +.B r +Replace the named files in the archive file. +If the optional character +.B u +is used with +.B r, +then only those files with +modified dates later than +the archive files are replaced. +If an optional positioning character from the set +.B abi +is used, then the +.I posname +argument must be present +and specifies that new files are to be placed +after +.RB ( a ) +or before +.RB ( b +or +.BR i ) +.IR posname . +Otherwise +new files are placed at the end. +.TP +.B q +Quickly append the named files to the end of the archive file. +Optional positioning characters are invalid. +The command does not check whether the added members +are already in the archive. +Useful only to avoid quadratic behavior when creating a large +archive piece-by-piece. +.TP +.B t +Print a table of contents of the archive file. +If no names are given, all files in the archive are tabled. +If names are given, only those files are tabled. +.TP +.B p +Print the named files in the archive. +.TP +.B m +Move the named files to the end of the archive. +If a positioning character is present, +then the +.I posname +argument must be present and, +as in +.B r, +specifies where the files are to be moved. +.TP +.B x +Extract the named files. +If no names are given, all files in the archive are +extracted. +In neither case does +.B x +alter the archive file. +.TP +.B v +Verbose. +Under the verbose option, +.I arch +gives a file-by-file +description of the making of a +new archive file from the old archive and the constituent files. +When used with +.B t, +it gives a long listing of all information about the files. +When used with +.BR p , +it precedes each file with a name. +.TP +.B c +Create. +Normally +.I arch +will create +.I afile +when it needs to. +The create option suppresses the +normal message that is produced when +.I afile +is created. +.TP +.B l +Local. +Normally +.I arch +places its temporary files in the directory /tmp. +This option causes them to be placed in the local directory. +.SH FILES +/tmp/v* temporaries +.SH "SEE ALSO" +em_ass(I), arch(V), +.SH BUGS +If the same file is mentioned twice in an argument list, +it may be put in the archive twice. diff --git a/man/arch.5 b/man/arch.5 new file mode 100644 index 000000000..33cc2502a --- /dev/null +++ b/man/arch.5 @@ -0,0 +1,51 @@ +.TH ARCH 5 +.SH NAME +arch \- archive (library) file format +.SH SYNOPSIS +.B #include "/usr/em/h/arch.h" +.SH DESCRIPTION +The archive command +.I arch +is used to combine several files into +one. +Archives are used mainly as libraries to be searched +by the EM assembler/linker em_ass(VI) or the universal +assembler/linker em_unias(VI). +.PP +A file produced by +.I arch +has a magic number at the start, +followed by the constituent files, each preceded by a file header. +The magic number and header layout as described in the +include file are: +.RS +.PP +.nf +.ta \w'#define 'u +\w'ARMAG 'u +.so ../h/arch.h +.fi +.RE +.LP +The name is a null-terminated string; +The sizes of the other entries are determined as follows: +long's are 4 bytes in PDP-11 order, int are 2 bytes, low order +byte first, char's are 1 byte. +The date is in the +form of +.IR time (2); +the user ID and group ID are numbers; the mode is a bit pattern +per +.IR chmod (2); +the size is counted in bytes. +.PP +Each file begins on a even offset; +a null byte is inserted between files if necessary. +Nevertheless the size given reflects the +actual size of the file exclusive of padding. +.PP +Notice there is no provision for empty areas in an archive +file. +.SH "SEE ALSO" +arch(I), em_ass(VI), em_unias(VI) +.SH BUGS +Coding user and group IDs as characters is a botch. diff --git a/man/em.1 b/man/em.1 new file mode 100644 index 000000000..ff29ed65e --- /dev/null +++ b/man/em.1 @@ -0,0 +1,86 @@ +.TH EM I +.ad +.SH NAME +em \- calling program for em interpreters +.SH SYNOPSIS +em [-t] [+fcp] [loadfile [args ... ...] ] +.SH DESCRIPTION +The loadfile ("e.out" if not specified) is opened to read the first 8 word header. +The format of this header is explained in e.out(V). +One of these 8 words is a flag word +specifying the interpreter options requested at compile time. +The usual setting of these options is +t -f -c -p. +One of these options may be overridden at run time +by the corresponding flag of em. +Based on these options the name of the appropriate interpreter +is constructed. +.PP +This interpreter is first searched for in /usr/em/mach/pdp/int, then in the current +directory. +.PP +The flags control the following options that can be turned off +or on by prepending them with - or + respectively: +.IP t +run time tests for undefined variables, array bounds etc... +This option costs a small amount of memory and some time. +However, it is very useful for debugging. +.IP p +profiling of the entire program. The interpreter maintain tables containing +an estimate of the number of memory cycles used per source line. +This option is expensive in time as well as in memory space. +The result tables made at run time are dumped onto a file named +em_runinf. This file is converted to human readable format +by the program eminform(I) which writes the profiling information +on a file called em_profile. +.IP f +maintain a bit map of all source lines that have been executed. +This map is written also onto the file em_runinf and can be interpreted by eminform(I) which writes in this case the file em_flow. +This option is almost free in time and space. +.IP c +count line usage in tables that +contains for every source line the number of times it +was entered. +These tables are also written onto em_runinf. +Eminform(I) can be used to convert this information into the +file em_count. +Cheap in time, expensive in memory space. +.PP +These flags +give rise to 5 different interpreters which are in the +directory /usr/em/mach/pdp/int +.PP +If the interpreter exits with a non-zero exit status, then the line numbers +of the 64 last executed source lines are dumped on the file +em_runinf +in the current directory. Eminform(I) writes this information +on the human readable file em_last. +.SH "FILES" +.IP /usr/em/mach/pdp/int/em_???? 35 +interpreters proper +.PD 0 +.IP /usr/em/lib/pdp_int/em_???? +source of interpreter +.IP /usr/em/mach/pdp/int/?+ +positive option switch +.IP /usr/em/mach/pdp/int/?- +negative option switch +.IP em_runinf +memory dump containing runtime information +.IP em_profile +profile data +.IP em_count +source line count data +.IP em_flow +source line flow data +.IP em_last +last lines executed +.PD +.SH "SEE ALSO" +eminform(I), ack(I), int(I) +.SH BUGS +Most error messages are self explanatory. +The interpreter stops in case of lack of space with an error +message SEGVIO stack overflow. +If runtime flags are turned on it is advisable to try again +with the default options. +Bugs should be reported to Evert Wattel. diff --git a/man/em_cg.6 b/man/em_cg.6 new file mode 100644 index 000000000..f7f6ca0e9 --- /dev/null +++ b/man/em_cg.6 @@ -0,0 +1,31 @@ +.TH EM_CG VI +.ad +.SH NAME +em_cg \- EM to assembly code translator +.SH SYNOPSIS +/usr/em/lib/mach_cg [-d] [-p\fIn\fP] [-w\fIn\fP] [ infile [ outfile ] ] +.SH DESCRIPTION +Em_cg reads a compact EM-program, argument or standard input, +and produces an assembly program on argument or standard output +for the machine that is in its name. +Flags recognized are: +.IP -d +Run in debugging mode, +only possible when the translator is compiled in the right way. +.IP -p\fIn\fP +Set the ply to \fIn\fP, default 1. +The ply is the maximum lookahead depth the code generator may take. +Effects of this flag are machine dependent. +.IP -w\fIn\fP +Set the weight percentage for size to \fIn\fP %, default is 50. +This sets the size/time tradeoff in the codegenerator. +Effects are again machine dependent. +.SH "SEE ALSO" +ack(I) +.PD 0 +.IP [1] +A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan +Stevenson "Description of a machine architecture for use with +block structured languages" Informatica report IR-81. +.SH AUTHOR +Hans van Staveren, Vrije Universiteit diff --git a/man/em_decode.6 b/man/em_decode.6 new file mode 100644 index 000000000..3413f86ce --- /dev/null +++ b/man/em_decode.6 @@ -0,0 +1,39 @@ +.TH EM_DECODE VI +.ad +.SH NAME +em_decode,em_encode \- compact to readable EM and v.v. +.SH SYNOPSIS +/usr/em/lib/em_decode [ inputfile [ outputfile ] ] +.br +/usr/em/lib/em_encode [ inputfile [ outputfile ] ] +.SH DESCRIPTION +Most programs involved with the EM project only produce and accept +EM programs in compact form. +These files are only machine readable. +A description of this compact form can be found in [1]. +To inspect the code produced by compilers or to patch them for one reason +or another, you need human readable assembly code. +Em_decode will do the job for you. +.PP +Em_decode accepts the normal compact form in both optimized and +unoptimized form +.PP +Sometimes you have to make some special routines directly +in EM, for instance the routines implementing the system calls. +At these times you may use em_encode to produce compact routines +out of these human readable assembly modules. +.PP +The first argument is the input file. +The second argument is the output file. +Both programs can act as a filter. +.SH "SEE ALSO" +.IP [1] +A.S.Tanenbaum, Ed Keizer, Hans van Staveren & J.W.Stevenson +"Description of a machine architecture for use of +block structured languages" Informatica rapport IR-81. +.IP [2] +ack(I) +.SH DIAGNOSTICS +Error messages are intended to be self-explanatory. +.SH AUTHOR +Johan Stevenson, Vrije Universiteit. diff --git a/man/eminform.1 b/man/eminform.1 new file mode 100644 index 000000000..5030ec136 --- /dev/null +++ b/man/eminform.1 @@ -0,0 +1,50 @@ +.tr ~ +.TH EMINFORM I +.ad +.SH NAME +eminform \- converts runtime information of interpreted em to +human readable form. +.SH SYNOPSIS +eminform +.SH DESCRIPTION +The EM interpreter, em(I), has several debugging features built in. +They can be activated by flag options to em(I). +The EM interpreter collects the information while it runs the program. +When the program is terminated, the interpreter dumps this information onto +a file called em_runinf. +Eminform converts this information in human readable form onto +a set of files with fixed names, the file em_runinf itself is unlinked. +.PP +.in +15 +.ti -13 +~~em_last~~~~A circular buffer is used to keep track of +the last collection of executed source lines. +.ti -13 +~~em_flow~~~~A bit map for all source lines tells which lines +are executed. +.ti -13 +~~em_count~~~Count the number of times each source line was entered. +.ti -13 +~~em_profile~Estimate the number of memory cycles +spent on each source line. +.in -15 +.LP +The most common use of eminform is to print the numbers of the last executed +source lines if an execution error occurred. +No arguments are needed in this case. +.LP +Eminform will create only those files for which there were +interpreter flags turned on. If no runtime error occurred and +no flag was turned on the file em_runinf is not created. In +this case eminform will give the error message "read header +failed". +.SH FILES +em_runinf, em_last, em_flow, em_count, em_profile +.SH "SEE ALSO" +ack(I), int(I), em(I). +.SH BUGS +If an entire procedure is not touched, the the file name in +which this procedure occured is unknown. +If no em_runinf is available the error message is "read header +failed" and a core dump is created. +Bugs should be reported to Evert Wattel diff --git a/man/libmon.7 b/man/libmon.7 new file mode 100644 index 000000000..2d7fac790 --- /dev/null +++ b/man/libmon.7 @@ -0,0 +1,97 @@ +.TH LIBMON VII +.ad +.SH NAME +libmon \- library of system call routines with EM calling sequence +.SH DESCRIPTION +The modules in this library contain the UNIX system calls with EM calling sequence. +This library is written in EM assembly language and can be used +for interpreted programs, and 'a.out' programs. +If these routines are used in Pascal programs, then the calling sequence +requires some attention. +Some hints may be useful: +.IP - +The c-option {$c+} allows you to declare zero-terminated string +constants in Pascal like "/etc/passwd". +Moreover, the identifier 'string' is then defined as type identifier for +a pointer to these zero-terminated strings. +.IP - +The d-option {$d+} allows you to use double precision integers (longs). +The lseek system call, for instance, needs a long argument and returns a long result. +.IP - +If the system call requires a pointer as argument use a 'var' parameter. +For instance declare times as: +.br + procedure times(var t:timesbuf); extern; +.br +Note that a 'string' is already a pointer. +.IP - +When defining types, use packed records if two bytes must be allocated +in a single word, as in +.br + device = packed record +.br + minor,major:0..255; +.br + end; +.IP - +If a collection of bits is needed, then define an enumerated type and +a set of this enumerated type. The create mode of a file, for example, +can be declared as: +.br + modebits = (XHIM,WHIM,RHIM, +.br + XYOU,WYOU,RYOU, +.br + XME, WME, RME, +.br + TEXT,SGID,SUID,... ); +.br + creatmode = set of XHIM..SUID; +.IP - +There are special system call routines 'uread' and 'uwrite' in libpc(VII), +because the names 'read' and 'write' are blocked by similar functions in Pascal. +.PP +The system call 'signal' exists, but uses 'sigtrp'. +This EM system call has the +following calling sequence: +.br + function sigtrp(signo,trapno:integer):integer; +.br +The action values of 'signal', odd for 'ignore' and zero +for 'get back to default', +may interfere with the EM procedure identification in some +implementations. +In most interpreters procedures in EM are numbered consecutively from zero up. +The first argument of 'sigtrp' is the signal number 'signo' as for 'signal'. +The second argument is an integer 'trapno', indicating the action to be performed +when the signal is issued: +.IP -2 8 +Reset the action for signal 'signo' to the default. +.IP -3 +Ignore signal 'signo'. +.IP "0-252" +Perform an EM instruction TRP with error code 'trapno', +whenever the signal 'signo' is issued. +Note that the error codes 0-127 are reserved for EM machine errors +and language runtime system errors. +.PP +The routine 'sigtrp' returns the old 'trapno' or -1 if an erroneous +signal number is specified. +Only the signal numbers 1, 2, 3, 13, 14, 15 and 16 may be used as argument +for 'sigtrp'. +.SH FILES +.IP /usr/em/mach/*/lib/tail_mon +.PD +.SH "SEE ALSO" +em(I), ack(I), *(II), libpc(VII) +.SH DIAGNOSTICS +All routines put the UNIX error code in the global variable 'errno'. +Errno is not cleared by successful system calls, so it always gives +the error of the last failed call. +One exception: ptrace clears errno when successful. +.SH AUTHOR +Ed Keizer, Vrije Universiteit +.SH BUGS +There should be additional routines giving a fatal error when they fail. +It would be pleasant to have routines, +which print a nice message and stop execution for unexpected errors. diff --git a/man/libpc.7 b/man/libpc.7 new file mode 100644 index 000000000..214318002 --- /dev/null +++ b/man/libpc.7 @@ -0,0 +1,298 @@ +.TH LIBPC VII +.ad +.SH NAME +libpc \- library of external routines for Pascal programs +.SH SYNOPSIS +.ta 11 +const bufsize = ?; +.br +type br1 = 1..bufsize; +.br + br2 = 0..bufsize; +.br + br3 = -1..bufsize; +.br + ok = -1..0; +.br + buf = packed array[br1] of char; +.br + alfa = packed array[1..8] of char; +.br + string = ^packed array[1..?] of char; +.br + filetype = file of ?; +.br + long = record high,low:integer end; + +{all routines must be declared extern} + +function argc:integer; +.br +function argv(i:integer):string; +.br +function environ(i:integer):string; +.br +procedure argshift; + +procedure buff(var f:filetype); +.br +procedure nobuff(var f:filetype); +.br +procedure notext(var f:text); +.br +procedure diag(var f:text); +.br +procedure pcreat(var f:text; s:string); +.br +procedure popen(var f:text; s:string); +.br +procedure pclose(var f:filetype); + +procedure trap(err:integer); +.br +procedure encaps(procedure p; procedure q(n:integer)); + +function perrno:integer; +.br +function uread(fd:integer; var b:buf; len:br1):br3; +.br +function uwrite(fd:integer; var b:buf; len:br1):br3; + +function strbuf(var b:buf):string; +.br +function strtobuf(s:string; var b:buf; len:br1):br2; +.br +function strlen(s:string):integer; +.br +function strfetch(s:string; i:integer):char; +.br +procedure strstore(s:string; i:integer; c:char); + +function clock:integer; +.SH DESCRIPTION +This library contains some often used external routines for Pascal programs. +Two versions exist: one for the EM interpreter and another one +that is used when programs are translated into PDP-11 code. +The routines can be divided into several categories: +.PP +Argument control: +.RS +.IP argc 10 +Gives the number of arguments provided when the program is called. +.PD 0 +.IP argv +Selects the specified argument from the argument list and returns a +pointer to it. +This pointer is nil if the index is out of bounds (<0 or >=argc). +.IP environ +Returns a pointer to the i-th environment string (i>=0). Returns nil +if i is beyond the end of the environment list (UNIX version 7). +.IP argshift +Effectively deletes the first argument from the argument list. +Its function is equivalent to 'shift' in the UNIX shell: argv[2] becomes +argv[1], argv[3] becomes argv[2], etc. +It is a useful procedure to skip optional flag arguments. +Note that the matching of arguments and files +is done at the time a file is opened by a call to reset or rewrite. +.PD +.PP +.RE +Additional file handling routines: +.RS +.IP buff 10 +Turn on buffering of a file. Not very useful, because all +files are buffered except standard output to a terminal and diagnostic output. +Input files are always buffered. +.PD 0 +.IP nobuff +Turn off buffering of an output file. It causes the current contents of the +buffer to be flushed. +.IP notext +Only useful for input files. +End of line characters are not replaced by a space and character codes out of +the ASCII range (0..127) do not cause an error message. +.IP diag +Initialize a file for output on the diagnostic output stream (fd=2). +Output is not buffered. +.IP pcreat +The same as rewrite(f), except that you must provide the filename yourself. +The name must be zero terminated. Only text files are allowed. +.IP popen +The same as reset(f), except that you must provide the filename yourself. +The name must be zero terminated. Only text files are allowed. +.IP pclose +Gives you the opportunity to close files hidden in records or arrays. +All other files are closed automatically. +.PD +.PP +.RE +String handling: +.RS +.IP strbuf 10 +Type conversion from character array to string. +It is your own responsibility that the string is zero terminated. +.PD 0 +.IP strtobuf +Copy string into buffer until the string terminating zero byte +is found or until the buffer if full, whatever comes first. +The zero byte is also copied. +The number of copied characters, excluding the zero byte, is returned. So if +the result is equal to the buffer length, then the end of buffer is reached +before the end of string. +.IP strlen +Returns the string length excluding the terminating zero byte. +.IP strfetch +Fetches the i-th character from a string. +There is no check against the string length. +.IP strstore +Stores a character in a string. There is no check against +string length, so this is a dangerous procedure. +.PD +.PP +.RE +Trap handling: +.RS +These routines allow you to handle almost all +the possible error situations yourself. +You may define your own trap handler, written in Pascal, instead of the +default handler that produces an error message and quits. +You may also generate traps yourself. +.IP trap 10 +Trap generates the trap passed as argument (0..252). +The trap numbers 128..252 may be used freely. The others are reserved. +.PD 0 +.IP encaps +Encapsulate the execution of 'p' with the trap handler 'q'. +Encaps replaces the previous trap handler by 'q', calls 'p' and restores +the previous handler when 'p' returns. +If, during the execution of 'p', a trap occurs, +then 'q' is called with the trap number as parameter. +For the duration of 'q' the previous trap handler is restored, so that +you may handle only some of the errors in 'q'. All the other errors must +then be raised again by a call to 'trap'. +.br +Encapsulations may be nested: you may encapsulate a procedure while executing +an encapsulated routine. +.br +Jumping out of an encapsulated procedure (non-local goto) is dangerous, +because the previous trap handler must be restored. +Therefore, you may only jump out of procedure 'p' from inside 'q' and +you may only jump out of one level of encapsulation. +If you want to exit several levels of encapsulation, use traps. +See pc_emlib(VII) and pc_prlib(VII) for lists of trap numbers +for EM machine errors and Pascal run time system errors. +Note that 'p' may not have parameters. +.PD +.PP +.RE +UNIX system calls: +.RS +The routines of this category require global variables or routines +of the monitor library libmon(VII). +.IP uread 10 +Equal to the read system call. +Its normal name is blocked by the standard Pascal routine read. +.PD 0 +.IP uwrite +As above but for write(II). +.IP perrno +Because external data references are not possible in Pascal, +this routine returns the global variable errno, indicating the result of +the last system call. +.PD +.PP +.RE +Miscellaneous: +.RS +.IP clock 10 +Return the number of ticks of user and system time consumed by the program. +.PD +.PP +.RE +The following program presents an example of how these routines can be used. +This program is equivalent to the UNIX command cat(I). +.nf + {$c+} + program cat(input,inp,output); + var inp:text; + s:string; + + function argc:integer; extern; + function argv(i:integer):string; extern; + procedure argshift; extern; + function strlen(s:string):integer; extern; + function strfetch(s:string; i:integer):char; extern; + + procedure copy(var fi:text); + var c:char; + begin reset(fi); + while not eof(fi) do + begin + while not eoln(fi) do + begin + read(fi,c); + write(c) + end; + readln(fi); + writeln + end + end; + + begin {main} + if argc = 1 then + copy(input) + else + repeat + s := argv(1); + if (strlen(s) = 1) and (strfetch(s,1) = '-') + then copy(input) + else copy(inp); + argshift; + until argc <= 1; + end. +.fi +.PP +Another example gives some idea of the way to manage trap handling: +.nf + + program bigreal(output); + const EFOVFL=4; + var trapped:boolean; + + procedure encaps(procedure p; + procedure q(n:integer)); extern; + procedure trap(n:integer); extern; + + procedure traphandler(n:integer); + begin if n=EFOVFL then trapped:=true else trap(n) end; + + procedure work; + var i,j:real; + begin trapped:=false; i:=1; + while not trapped do + begin j:=i; i:=i*2 end; + writeln('bigreal = ',j); + end; + + begin + encaps(work,traphandler); + end. +.fi +.SH FILES +.IP /usr/em/mach/*/lib/tail_pc 20 +.PD +.SH "SEE ALSO" +ack(I), pc_pem(VI), pc_prlib(VII), libmon(VII) +.SH DIAGNOSTICS +Two routines may cause fatal error messages to be generated. +These are: +.IP pcreat 10 +Rewrite error (trap 77) if the file cannot be created. +.PD 0 +.IP popen +Reset error (trap 76) if the file cannot be opened for reading +.PD +.SH AUTHOR +Johan Stevenson, Vrije Universiteit. +.br +encaps: Ed Keizer, Vrije Universiteit. diff --git a/man/macro.v7 b/man/macro.v7 new file mode 100644 index 000000000..b72df9699 --- /dev/null +++ b/man/macro.v7 @@ -0,0 +1,63 @@ +.de TH +.PD +.lc +.nr in 5 +.de hd +'sp 2 +'tl '\\$1(\\$2)'Amsterdam Compiler Kit'\\$1(\\$2)' +'sp 2 +\\.. +.wh -6 fo +.wh 0 hd +.nr pi 5 +.. +.de fo +'sp 2 +'tl ''- % -'' +'bp +.. +.de PD +.nr pd 0.5v +.if \\n(.$ .nr pd \\$1 +.. +.de SH +.nr in 5 +.nr pi 5 +.in \\n(in +.ti 0 +.sp \\n(pdu +.ne 2 +.fi +\s+3\fB\\$1\fP\s0 +.br +.. +.de LP +.PP +.. +.de PP +.sp \\n(pdu +.ne 2 +.in \\n(in +.nr pi 5 +.ns +.. +.de IP +.if \\n(.$-1 .nr pi \\$2 +.sp \\n(pdu +.in \\n(in+\\n(pi +.ta \\n(in \\n(in+\\n(pi +.ti 0 +\fB\\$1\fR\c +.if \w'\fB\\$1\fP'-\\n(pin+1n .br +.. +.de RS +.nr in +5 +.in +5 +.. +.de RE +.in -5 +.nr in -5 +.. +.de RF +\fI\\$1\fP(\\$2)\\$3 +.. diff --git a/man/pc_prlib.7 b/man/pc_prlib.7 new file mode 100644 index 000000000..6fa2bb654 --- /dev/null +++ b/man/pc_prlib.7 @@ -0,0 +1,758 @@ +.TH PC_PRLIB VII +.ad +.SH NAME +pc_prlib \- library of Pascal runtime routines +.SH SYNOPSIS +.ta 11 +type alpha=packed array[1..8] of char; +.br + pstring= ^packed array[] of char; + +function _abi(i:integer):integer; +.br +function _abl(i:long):long; +.br +function _mdi(j,i:integer):integer; +.br +function _mdl(j,i:long):long; +.br +function _abr(r:real):real; +.br +function _sin(r:real):real; +.br +function _cos(r:real):real; +.br +function _atn(r:real):real; +.br +function _exp(r:real):real; +.br +function _log(r:real):real; +.br +function _sqt(r:real):real; +.br +function _rnd(r:real):real; + +type compared=-1..1; +.br + gotoinfo=record +.br + pcoffset:^procedure; { procedure id. without static link } +.br + nlocals: integer; +.br + end; + +function _bcp(sz:integer; s2,s1:pstring):compared; +.br +function _bts(size,high,low:integer; base:^set 0..(8*size-1)) + :set of 0..(8*size-1); +.br +procedure _gto(lb:^integer; p:^gotoinfo); + +procedure _new(size:integer; var p:^integer); +.br +procedure _dis(size:integer; var p:^integer); +.br +procedure _sav(var p:^integer); +.br +procedure _rst(var p:^integer); + +type arrdescr=record +.br + lowbnd: integer; +.br + diffbnds:integer; +.br + elsize: integer; +.br + end; +.br + arr1=array[] of ?; +.br + arr2=packed array[] of ?; + +procedure _pac(var ad,zd:arrdescr; var zp:arr2; i:integer; +.br + var ap:arr1); +.br +procedure _unp(var ad,zd:arrdescr; i:integer; var ap:arr1; +.br + var zp:arr2;); +.br +function _asz(var dp:arrdescr):integer; + +procedure _ass(line:integer; b:boolean); +.br +procedure procentry(var name:alpha); +.br +procedure procexit(var name:alpha); + +const lowbyte=[0..7]; +.br + MAGIC =[1,3,5,7]; +.br + WINDOW =[11]; +.br + ELNBIT =[12]; +.br + EOFBIT =[13]; +.br + TXTBIT =[14]; +.br + WRBIT =[15]; +.br +type file=record +.br + ptr: ^char; +.br + flags: set of [0..15]; +.br + fname: string; +.br + ufd: 0..15; +.br + size: integer; +.br + count: 0..buflen; +.br + buflen: max(512,size) div size * size; +.br + bufadr: packed array[1..max(512,size)] +.br + of char; +.br + end; +.br + filep=^file; +.br +const NFILES=15; +.br + _extfl:^array[] of filep; + +procedure _ini(var args:integer; var hb:integer; + var p:array[] of filep; var mainlb:integer); +.br +procedure _hlt(status:0..255); + +procedure _opn(size:integer; f:filep); +.br +procedure _cre(size:integer; f:filep); +.br +procedure _cls(f:filep); + +procedure _get(f:filep); +.br +procedure _put(f:filep); +.br +function _wdw(f:filep):^char; +.br +function _efl(f:filep):boolean; + +function _eln(f:filep):boolean; +.br +function _rdc(f:filep):char; +.br +function _rdi(f:filep):integer; +.br +function _rdl(f:filep):long; +.br +function _rdr(f:filep):real; +.br +procedure _rln(f:filep); +.br +procedure _wrc(c:char; f:filep); +.br +procedure _wsc(w:integer; c:char; f:filep); +.br +procedure _wri(i:integer; f:filep); +.br +procedure _wsi(w:integer; i:integer; f:filep); +.br +procedure _wrl(l:long; f:filep); +.br +procedure _wsl(w:integer; l:long; f:filep); +.br +procedure _wrr(r:real; f:filep); +.br +procedure _wsr(w:integer; r:real; f:filep); +.br +procedure _wrf(ndigit:integer; w:integer; r:real; f:filep); +.br +procedure _wrs(l:integer; s:pstring; f:filep); +.br +procedure _wss(w:integer; l:integer; s:pstring; f:filep); +.br +procedure _wrb(b:boolean; f:filep); +.br +procedure _wsb(w:integer; b:boolean; f:filep); +.br +procedure _wrz(s:string; f:filep); +.br +procedure _wsz(w:integer; s:string; f:filep); +.br +procedure _wln(f:filep); +.br +procedure _pag(f:filep); +.SH DESCRIPTION +This library is used by the Pascal to EM compiler and +contains all the runtime routines for standard Pascal programs. +Most routines are written in C, a few in EM assembly language. +These routines can be divided into several categories. +A description of each category with its routines follows. +.PP +Arithmetic routines: +.RS +.IP _abi +Compute the absolute value of an integer. +.PD 0 +.IP _abl +Compute the absolute value of a long. +.IP _mdi +Perform the Pascal modulo operation on integers. +.IP _mdl +Perform the Pascal modulo operation on longs. +.IP _abr +Compute the absolute value of a real. +.IP _sin +Compute the sine of a real. +.IP _cos +Compute the cosine of a real. +.IP _atn +Compute the arc tangent of a real. +.IP _exp +Compute the e-power of a real. +.IP _log +Compute the natural logarithm of a real. +.IP _sqt +Compute the square root of a real. +.IP _rnd +Return a real that when truncated will +result in the nearest integer (-3.5->-4). +.PD +.PP +.RE +Miscellaneous routines: +.RS +.IP _bcp +Compare two strings. Use dictionary ordering with the ASCII +character set. The EM instruction CMU can not be used, because it needs +an even number of bytes. +.PD 0 +.IP _bts +Include a range of elements from low to high in a set of size bytes +at address base.(size can be divided by the wordsize) +.IP _gto +Execute a non-local goto. Lb points to the +local base of the target procedure. +A lb of zero indicates a jump to the program body, the lb of the main +program is found in _m_lb, which is set by _ini. +The new EM stack pointer is calculated by adding the number of locals +to the new local base +(jumping into statements is not allowed; there are no local generators +in Pascal!). +.PD +.PP +.RE +Heap management: +.RS +.PP +There is one way to allocate new heap space (_new), but two different +incompatible ways to deallocate it. +.PP +The most general one is by using dispose (_dis). +A circular list of free blocks, ordered from low to high addresses, is maintained. +Merging free blocks is done when a new block enters the free list. +When a new block is requested (_new), the free list is searched using a +first fit algorithm. +Two global variables are needed: +.IP _highp 10 +Points to the free block with the highest address. +.PD 0 +.IP _lastp +Points to the most recently entered free block or to a block +in the neighborhood of the most recently allocated block. +.PD +The free list is empty, when one of these pointers (but then at the same +time both) is zero. +.PP +The second way to deallocate heap space is by using +mark (_sav) and release (_rst). Mark saves the current value of the +heap pointer HP in the program variable passed as a parameter. +By calling release with this old HP value as its argument, the old HP value +is restored, effectively deallocating all blocks requested between +the calls to mark and release. +The heap is used as second stack in this case. +.PP +It will be clear that these two ways of deallocating heap space +can not be used together. +To be able to maintain the free list, all blocks must be a multiple +of n bytes long, with a minimum of n bytes, +where n is the sum of the size of a word and a pointer in the +EM implementation used. +.PP +In summary: +.IP _new +Allocate heap space. +.PD 0 +.IP _dis +Deallocate heap space. +.IP _sav +Save the current value of HP. +.IP _rst +Restore an old value of HP. +.PD +.PP +.RE +Array operations: +.RS +.PP +The only useful form of packing implemented, is packing bytes into words. +All other forms of packing and unpacking result in a plain copy. +.IP _pac +Pack an unpacked array 'a' into a packed array 'z'. 'ap' and 'zp' +are pointers to 'a' and 'z'. 'ad' and 'zd' +are pointers to the descriptors of 'a' and 'z'. 'i' is +the index in 'a' of the first element to be packed. +Pack until 'z' is full. +.PD 0 +.IP _unp +Unpack 'z' into 'a'. 'ap', 'zp', 'ad' and 'zd' are as for _pac. 'i' is +the index in 'a' where the first element of 'z' is copied into. +Unpack all elements of 'z'. +.IP _asz +Compute array size. Used for copying conformant arrays. +.PD +.PP +.RE +Debugging facilities: +.RS +The compiler allows you to verify assertions. +It generates a call to the routine _ass to check the assertion at runtime. +Another feature of the compiler is that it enables you to trace the +procedure calling sequence. If the correct option is turned on, then +a call to the procedure 'procentry' is generated at the start of each +compiled procedure or function. Likewise, the routine 'procexit' is called +just before a procedure or function exits. +Default procedure 'procentry' and 'procexit' are available in this library. +.IP _ass 10 +If 'b' is zero, then change eb[0] to 'line' +(to give an error message with source line number) and call the error routine. +.PD 0 +.IP procentry +Print the name of the called procedure with up to seven argument words +in decimal on standard output. Output must be declared in the program heading. +.IP procexit +Print the name of the procedure that is about to exit. +Same remarks as for procentry. +.PD +.PP +.RE +Files: +.RS +.PP +Most of the runtime routines are needed for file handling. +For each file in your Pascal program a record of type file, as described +above, is allocated, static if your file is declared in the outermost block, +dynamic if it is declared in inner blocks. +The fields in the file record are used for: +.IP bufadr 10 +IO is buffered except for standard input and output if +terminals are involved. The size of the buffer is the maximum of 512 +and the file element size. +.PD 0 +.IP buflen +The effective buffer length is the maximum number of file elements +fitting in the buffer, multiplied by the element size. +.IP size +The file element size (1 or even). +.IP flags +Some flag bits are stored in the high byte and a magic pattern +in the low byte provides detection of destroyed file +information. +.IP ptr +Points to the file window inside the buffer. +.IP count +The number of bytes (the window inclusive) left in the buffer +to be read or the number of free bytes (the window inclusive) for output files. +.IP ufd +The UNIX file descriptor for the file. +.IP fname +Points to the name of the file (INPUT for standard input, +OUTPUT for standard output and LOCAL for local files). +This field is used for generating error messages. +.PD +.PP +The constants used by the file handling routines are: +.IP WINDOW 10 +Bit in flags set if the window of an input file is initialized. +Used to resolve the famous interactive input problem. +.PD 0 +.IP EOFBIT +Bit in flags set if end of file seen +.IP ELNBIT +Bit in flags set if linefeed seen +.IP TXTBIT +Bit in flags set for text files. Process linefeeds. +.IP WRBIT +Bit in flags set for output files +.IP MAGIC +Pattern for the low byte of flags +.IP NFILES +The maximum number of open files in UNIX +.PD +.PP +.RE +Prelude and postlude: +.RS +.PP +These routines are called once for each Pascal program: +.IP _ini +When a file mentioned in the program heading is opened by reset or +rewrite, its file pointer must be mapped onto one of the program +arguments. +The compiler knows how to map and therefore builds a table with +a pointer to the file structure for each program argument. +One of the first actions of the Pascal program is to call this procedure +with this table as an argument. +The global variable _extfl is used to save the address of this table. +Another task of _ini is to initialize the standard input and output files. +For standard output it must decide whether to buffer or not. +If standard output is a terminal, then buffering is off by setting +buflen to 1. +Two other task of _ini are the copying of two pointers from +the argument list to global memory, mainlb to _m_lb and hb to _hbase. +The first contains the local base of the program body, the second +contains the address of the hol containing the global variables +of the program. +A last task of _ini is to set the global variables _argc, _argv and _environ +from args for +possible reference later on. +Args points to the argument count placed on the stack by the EM runtime system, +see chapter 8 in [1]. +.PD 0 +.IP _hlt +If the program is about to finish, the buffered files must be flushed. +That is done by this procedure. +.PD +.PP +.RE +Opening and closing: +.RS +.PP +Files in Pascal are opened for reading by reset and opened for writing by +rewrite. +Files to be rewritten may or may not exist already. +Files not mentioned in the program heading are considered local files. +The next steps must be done for reset and rewrite: +.IP 1. +If size is zero, then a text file must be opened with elements of +size 1. +.PD 0 +.IP 2. +Find out if this file is mentioned in the program heading +(scan table pointed to by _extfl). +If not, then it is a local file and goto 7. +.IP 3. +If the file is standard input or output then return. +.IP 4. +If there are not enough arguments supplied, generate an error. +.IP 5. +If the file was already open, flush the buffer if necessary and close it. +Note that reset may be used to force the buffer to be flushed. +This is sometimes helpful against program or system crashes. +.IP 6. +If it is a reset, open the file, otherwise create it. +In both cases goto 9. +.IP 7. +If the local file is to be written, then close it if it was open and +create a new nameless file. First try to create it in /usr/tmp, then in /tmp +and if both fail then try the current directory. +See to it that the file is open for both reading and writing. +.IP 8. +If the local file is to be read +and the file is opened already, then +flush the buffer and seek to the beginning. +Otherwise open a temporary file as described in 7. +.IP 9. +Initialize all the file record fields. +.PD +.PP +The necessary procedures are: +.IP _opn +Reset a file +.PD 0 +.IP _cre +Rewrite a file +.IP _cls +Close a file. Closing of files is done for local files when the procedure +in which they are declared exits. +The compiler only closes local files if they are not part of a structured type. +Files allocated in the heap are not closed when they are deallocated. +There is an external routine 'pclose' in libP(VII), that may be called +explicitly to do the closing in these cases. +Closing may be necessary to flush buffers or to keep the number of +simultaneously opened files below NFILES. +Files declared in the outermost block are automatically closed when the +program terminates. +.PD +.PP +.RE +General file IO: +.RS +.PP +These routines are provided for general file IO: +.IP _put +Append the file element in the window to the file and advance the +window. +.IP _get +Advance the file window so that it points to the next element +of the file. +For text files (TXTBIT on) the ELNBIT in flags is set if the new character +in the window is a line feed (ASCII 10) and the character is then changed +into a space. +Otherwise the ELNBIT is cleared. +.IP _wdw +Return the current pointer to the file window. +.IP _eof +Test if you reached end of file. +Is always true for output files. +.PD +.PP +.RE +Textfile routines: +.RS +.PP +The rest of the routines all handle text files. +.IP _eln +Return true if the next character on an input file is an end-of-line marker. +An error occurs if eof(f) is true. +.PD 0 +.IP _rdc +Return the character currently in the window and advance the window. +.IP _rdi +Build an integer from the next couple of characters on the file, +starting with the character in the window. +The integer may be preceded by spaces (and line feeds), tabs and a sign. +There must be at least one digit. +The first non-digit signals the end of the integer. +.IP _rdl +Like _rdi, but for longs. +.IP _rdr +Like _rdi, but for reals. Syntax is as required for Pascal. +.IP _rln +Skips the current line and clears the WINDOW flag, so that the +next routine requiring an initialized window knows that it has to +fetch the next character first. +.IP _wrc +Write a character, not preceeded by spaces. +.IP _wsc +Write a character, left padded with spaces up to a field width +of 'w'. +.IP _wri +Write an integer, left padded with spaces up to a field width +of 6. +.IP _wsi +Write an integer, left padded with spaces up to a field width +of 'w'. +.IP _wrl +Write a long, left padded with spaces up to a field width +of 11. +.IP _wsl +Write a long, left padded with spaces up to a field width +of 'w'. +.IP _wrr +Write a real in scientific format, +left padded with spaces up to a field width of 13. +.IP _wsr +Write a real in scientific format, +left padded with spaces up to a field width of 'w'. +.IP _wrf +Write a real in fixed point format, with exactly 'ndigit' digits +behind the decimal point, the last one rounded; it is left padded up to +a field width of 'w'. +.IP _wrs +Write a string of length 'l', without additional spaces. +.IP _wss +Write a string of length 'l', left padded up to a field +width of 'w'. +.IP _wrb +Write a boolean, represented by "true" or "false", left padded +up to a field width of 5. +.IP _wsb +Write a boolean, represented by "true" or "false", left padded +up to a field width of 'w'. +.IP _wrz +Write a C-type string up to the zero-byte. +.IP _wsz +Write a C-type string, left padded up to a field width of w. +.IP _wln +Write a line feed (ASCII 10). +.IP _pag +Write a form feed (ASCII 12). +.PD +.PP +.RE +All the routines to which calls are generated by the compiler are described above. +They use the following global defined routines to do some of the work: +.IP _rf 10 +Check input files for MAGIC and WRBIT. +Initialize the window if WINDOW is cleared. +.PD 0 +.IP _wf +Check output files for MAGIC and WRBIT. +.IP _incpt +Advance the file window and read a new buffer if necessary. +.IP _outcpt +Write out the current buffer if necessary and advance the window. +.IP _flush +Flush the buffer if it is an output file. +Append an extra line marker if EOLBIT is off. +.IP _wstrin +All output routines make up a string in a local buffer. +They call _wstrin to output this buffer and to do the left padding. +.IP _skipsp +Skip spaces (and line feeds) on input files. +.IP _getsig +Read '+' or '-' if present. +.IP _fstdig +See to it that the next character is a digit. Otherwise error. +.IP _nxtdig +Check if the next character is a digit. +.IP _getint +Do the work for _rdi. +.IP _ecvt +Convert real into string of digits for printout in scientific notation. +.IP _fcvt +Convert real into string of digits for fixed point printout +.IP -fif +Split real into integer and fraction part +.IP _fef +Split real into exponent and fraction part +.PD +.PP +The following global variables are used: +.IP _lastp 10 +For heap management (see above). +.PD 0 +.IP _highp +For heap management (see above). +.IP _extfl +Used to save the argument p of _ini for later reference. +.IP _hbase +Used to save the argument hb of _ini for later reference. +.IP _m_lb +Used to store the local base of the main program. +.IP _curfil +Save the current file pointer, so that the +error message can access the file name. +.IP "_pargc, _pargv, _penvp" +Used to access the arguments of the main program. +.PD +.SH FILES +.IP /usr/em/lib/mach/*/lib/tail_pc 20 +The library used by ack[5] to link programs. +.IP /usr/em/etc/pc_rterrors +The error messages +.PD +.SH "SEE ALSO" +.IP [1] +A.S. Tanenbaum, Ed Keizer, Hans van Staveren & J.W. Stevenson +"Description of a machine architecture for use of +block structured languages" Informatica rapport IR-81. +.PD 0 +.IP [2] +K.Jensen & N.Wirth +"PASCAL, User Manual and Report" Springer-Verlag. +.IP [3] +An improved version of the ISO standard proposal for the language Pascal +ISO/TC97/SC5-N462, received November 1979. +.IP [4] +Ed Keizer, "The Amsterdam Compiler Kit reference manual". +.br +(try 'nroff /usr/emi/doc/pcref.doc'). +.IP [5] +ack(I), pc_pem(VI) +.PD +.SH DIAGNOSTICS +All errors discovered by this runtime system cause an EM TRP instruction +to be executed. This TRP instruction expects the error number on top +of the stack. See [1] for a more extensive treatment of the subject. +.PP +EM allows the user to specify a trap handling routine, called whenever +an EM machine trap or a language or user defined trap occurs. +One of the first actions in _ini is to specify that the routine _fatal, +available in this library, will handle traps. +This routine is called with an error code (0..252) as argument. +The file "/usr/em/etc/pc_rterrors" is opened and searched for a message +corresponding with this number. +If the file can not be opened, or if the error number is not recorded +in the file, then the same trap is generated again, but without +a user-defined trap handler, so that the low levels generate an +error message. +Otherwise the following information is printed +on file descriptor 2: +.IP - +The name of the Pascal program +.PD 0 +.IP - +The name of the file pointed to by _curfil, if the error number +is between 96 and 127 inclusive. +.IP - +The error message (or the error number if not found). +.IP - +The source line number if not equal to 0. +.PD +.PP +The routine _fatal stops the program as soon as the message is printed. +.PP +The following error codes are used by the Pascal runtime system: +.IP 64 +more args expected +.PD 0 +.IP 65 +error in exp +.IP 66 +error in ln +.IP 67 +error in sqrt +.IP 68 +assertion failed +.IP 69 +array bound error in pack +.IP 70 +array bound error in unpack +.IP 71 +only positive j in 'i mod j' +.IP 72 +file not yet open +.IP 73 +dispose error +.sp +.IP 96 +file xxx: not writable +.IP 97 +file xxx: not readable +.IP 98 +file xxx: end of file +.IP 99 +file xxx: truncated +.IP 100 +file xxx: reset error +.IP 101 +file xxx: rewrite error +.IP 102 +file xxx: close error +.IP 103 +file xxx: read error +.IP 104 +file xxx: write error +.IP 105 +file xxx: digit expected +.IP 106 +file xxx: non-ASCII char read +.PD +.PP +.SH AUTHORS +Johan Stevenson and Ard Verhoog, Vrije Universiteit. +.SH BUGS +Please report bugs to the authors. diff --git a/man/uni_ass.6 b/man/uni_ass.6 new file mode 100644 index 000000000..cfff7a9eb --- /dev/null +++ b/man/uni_ass.6 @@ -0,0 +1,332 @@ +.tr ~ +.TH UNI_ASS VI +.ad +.SH NAME +uni_ass \- universal assembler/loader +.SH SYNOPSIS +/usr/em/lib/\fImachine\fP_as [options] argument ... +.SH DESCRIPTION +The universal assembler is a framework allowing easy +generation of an assembler for any byte oriented machine. +The framework includes common pseudo instructions for name +definition, label usage, storage allocation and initialization +and expression evaluation. +The resulting program assembles and links assembly modules. +Arguments may be flags, assembly language modules or libraries. +.br +Flags are: +.IP -d[\fIn\fP] +Produce a listing on standard output, the octal number +\fIn\fP is mainly used for debugging purposes. +The default is 700. 500 and 600 give slightly different +listings. +.IP -s[\fIn\fP] +Produce a human-readable symbol table on standard output. +The default for \fIn\fP is 3. +The value 2 causes a listing of only the symbols internal to +the modules. +The value 1 causes a listing of external symbols only. +.IP -o +The argument following this flag is taken as the name of the +resulting load file. +The default name is \fBa.out\fP. +.PD +.PP +The assemblers assemble +and link together assembly language modules +machine +from files and libraries, +producing an a.out file. +.PP +Two different types of arguments are allowed: +.IP "1-" +Assembly language modules +.PD 0 +.IP "2-" +UNIX archives, as maintained by arch(I). These archives must +only contain +assembly language modules with \fI.define\fP as their first +statement. +.PD +.PP +Note that it is not possible to do a partial load; +loading starts from assembly language and produces binary +machine code. No symbol table and no relocation bits are produced. +.SH "SEGMENTS and TYPES" +The statements allocating and initializing space, +like instructions and +some pseudo-instruction reserve that space in the current +segment. +The currently reigning type of segment is determined by +one of the pseudo-instructions: \fI.text, .data, .bss\fP and +\&\fI.org\fP. +The assembler concatenates all space allocated in each of the +text, data and bss segments. +That is: every byte in a text segment is followed by another +byte in the text segment except the last, of which there is +only one in each program. +The org segment differs from the other three in the sense that +the assembler makes no attempt to concatenate pieces of org +segments. +Each \fI.org\fP pseudo-instruction has a parameter telling where it +should start allocating space. +In the final stages of the assembly the text, data and bss +segments are concatenated in that order after the length of +each segment has been made a multiple of a machine dependent +constant. +The first segment (text) starts at location 0. +.br +The start address of each segment can be set by the .base +pseudo-instruction. +.sp +The labels defined in a particular segment +have the type of that +segment, other types are: \fIundefined\fP and \fIabsolute\fP. +All variables that do not have a value have the type +\fIundefined\fP, a good example is an unsatisfied external +reference. +Numbers have the type \fIabsolute\fP. +The type of expressions depends on both the operators and the +operands used. +Generally, but not always, the following rule holds: whenever +one of the operands is absolute and the resulting type is that +of the other operand. +Not every operation is allowed on every combination of types, +for example: it is not allowed to add two \fItext\fP values. +.SH SYNTAX +.IP letters +Both upper and lower case may be used and are seen as +different. +The underscore '_' is considered to be a letter. +.IP identifiers +Identifiers are a sequence of letters and digits, starting with +a letter or a period '.'. +Only the first eight characters are remembered by the +assemblers, identifiers with the same first eight characters +are considered to be identical. +Identifiers can, only once, receive a value through assignment or a +label definition. +.IP "local labels" +Local labels consist of a single digit. +They can only be defined in the label part of a statement and +used anywhere an identifier is allowed. +They can be redefined at will. +Two forms of use exist: \fIf\fPorward and \fIb\fPackward +references. +The first consists of the digit followed by an \fIf\fP +and refers to the first definition of that label following the +reference. +The second consists of the digit followed by an \fIb\fP +and refers to the last definition of the label before the +reference. +.IP strings +Strings are enclosed in single "'" or double """ quotes. +The use of \eddd where ddd is an octal number and \en, \er, +\et, \eb and \ef is allowed and has the same meaning as in the +C language. +.IP numbers +Numbers are a sequence of letters and digits, starting with a +digit. +No difference is made between small and capital letters. +.br +The base of the number is determined in the following way: +.nf +if the number ends with an 'h' it is hexadecimal else + if the number starts with '0x' it is hexadecimal else + if the number starts with '0' it is octal else + it's decimal. +.fi +Note that the number '0x10h' is an illegal hexadecimal number, +because 'x' is an illegal hexadecimal digit. +The number should be written as '0x10' or '10h'. +The range of numbers depends on the machine. +A rule of the thumb is that the width of the machine's registers +the same is as the number of bits allowed in numbers. +.IP expressions +The following operators are recognized: +.nf +.sp 1 + op type action + + | binary bitwise or + & binary bitwise and + ^ binary bitwise exclusive or + + binary two's complement addition + + unary no effect + - binary two's complement subtraction + - unary two's complement negation + * binary two's complement multiplication + / binary two's complement division + % binary two's complement remainder +.tr ~~ + ~ unary one's complement negation +.tr ~ +.sp 1 +.fi +The operator precedence is the same as in C. +.br +The operands allowed are: identifiers, numbers and expressions. +The evaluation order can be changed using the brackets '[' and +\&']'. +.sp +.IP comment +The character '!' denotes the start of comment, every character +up to the next newline is skipped. +Exclamation marks in strings are not recognized as the start of +comment. +.IP statements +Statements are separated by newlines and ';' and can be +preceded by label definitions. +Label definitions have the form "\fIidentifier\fP~:" or +"\fIdigit\fP~:". +Statements can be: empty, an assignment, an instruction or a +pseudo-instruction. +.IP assignment +An assignment has the form: +.br + \fIidentifier\fP = \fIexpression\fP +.br +The identifier receives the value and type of the expression. +.IP instruction +The syntax of an instruction depends on the type of the target +machine. +An example of a assembly file is presented at +the end of the document. +.IP pseudo-instruction +.de Pu +.sp 1 +.ti +5 +\&\\$1 +.sp 1 +.. +.Pu ".extern \fIidentifier [, identifier]*\fP" +The identifiers mentioned in the list are exported and can be +used in other modules. +.Pu ".define \fIidentifier [, identifier]*\fP" +Used for modules that are to be part of a libary. +The .define pseudo's should be the first in such modules. +When scanning a module in a library the univeral assembler +checks whether any of its unsatified external references is +mentioned in a .define list. If so, it includes that module in +the program. +The identifiers mentioned in the list are exported and can be +used in other modules. +.Pu ".byte \fIexpression [, expression]*\fP" +Initialize a sequence of bytes. +This is not followed by automatic alignment. +.Pu ".short \fIexpression [, expression]*\fP" +Initialize a sequence of shorts (2-byte values). +This is not followed by automatic alignment. +.Pu ".long \fIexpression [, expression]*\fP" +Initialize a sequence of longs (4-byte values). +This is not followed by automatic alignment. +.Pu ".word \fIexpression [, expression]*\fP" +Initialize a sequence of words. The number of bytes occupied by +a word depends on the target machine. +This is not followed by automatic alignment. +.Pu ".ascii \fIstring\fP" +Initialize a sequence of bytes with the value of the bytes in +the string. +This is not followed by automatic alignment. +.Pu ".asciz \fIstring\fP" +Initialize a sequence of bytes with the value of the bytes in +the string and terminate this with an extra zero byte. +This is not followed by automatic alignment. +.Pu ".align [\fIexpression\fP]" +Adjust the current position to a multiple of the value of the +expression. +The default is the word-size of the target machine. +.Pu ".space \fIexpression\fP" +Allocate the indicated amount of bytes. +The expression must be absolute. +.Pu ".org \fIexpression\fP" +Start an org segment with the location counter at the indicated +value. +The value of the expression must be absolute. +.Pu ".text" +.Pu ".data" +.Pu ".bss" +Start an segment of the indicated type. +.Pu ".base \fIexpresssion\fP" +Set the starting address of the current segment to the value of +the expression. +The expression must be absolute. +.Pu ".errnz \fIexpression\fP" +Stop with a fatal error message when the value of the +expression is non-zero. +.SH "SEE ALSO" +ack(I), arch(I), a.out(V) +.SH "EXAMPLE" +An example of INtel 8086 assembly code. +.sp 2 +.nf +.ta 8 16 32 40 48 56 64 + .define begbss + .define hol0,.diverr,.reghp + .define EIDIVZ + + EIDIVZ = 6 + + base = 0x01C0 + topmem = 0xFFF0 + + .org topmem-16 + .extern __n_line + maxmem: + __n_line: + .space 16 + .errnz __n_line-0xFFE0 + + .base base + + .text + cld + xor ax,ax + mov (2),cs + mov (0),.diverr + mov sp,maxmem + mov di,begbss + mov cx,[[endbss-begbss]/2]&0x7FFF + ! xor ax,ax ! ax still is 0 + rep stos + mov ax,1 + push ax + call _start + 3: + jmp 3b + .diverr: + push ax + mov ax,EIDIVZ + call .error + pop ax + iret + cmp 0,4(bx)(di) ! just to show this addr. mode + + .data + begdata: + hol0: + .word 0,0 + .word 0,0 + .word 3f + .reghp: + .word endbss + 3: + .asciz "PROGRAM" + .sp 3 +.fi +.SH DIAGNOSTICS +Various diagnostics may be produced. +The most likely errors, however, are unresolved references, +probably caused by the omission of a library argument. +.SH BUGS +The resulting a.out file contains no information about the size +and starting address of the segments. +.br +The resulting a.out file does not contain a symbol table. +.br +The alignment might give rise to internal assertion errors when +the alignment requestes is larger than the machine dependent +segment alignment. +.br +Identifiers declared as externals cannot be used as locals in +any following module. diff --git a/util/ack/ack.1.X b/util/ack/ack.1.X new file mode 100644 index 000000000..16b420806 --- /dev/null +++ b/util/ack/ack.1.X @@ -0,0 +1,259 @@ +.TH ACK I +.ad +.SH NAME +ack \- Amsterdam Compiler Kit +.SH SYNOPSIS +\fBack\fP arguments +.br +\fBacc\fP arguments +.br +\fBapc\fP arguments +.br +\fImachine\fP arguments +.SH DESCRIPTION +This program transforms sources in several +languages to load files for a variety of machines, +internally using several phases. +The transformation can be stopped at any phase. +Combining sources from several languages is allowed. +The run-time system of the first language mentioned, +either in the program call name or in the arguments, +is automatically included. +The libraries of all other languages mentioned, +containing most of the run-time systems, +are also automatically included. +Two types of load files can be distinguished, +\fIa.out\fP files containing machine code and \fIe.out\fP +files containing virtual EM machine code. +The last type is designed for interpretation. +Compilation time for interpretation is fast and gives many +runtime checks, +but execution is about seven times slower. +Which combinations of languages and machines are allowed varies +in time and depends on the installation. +.PP +The actions of \fIack\fP are to repeatedly transform files with a +particular suffix into files with another suffix, +finally combining the results into a load file. +.PP +\fIAck\fP recognizes the following suffixes: +.IP .p +Pascal program. +.IP .c +C module. +.IP .e +EM assembly module in human readable form. +.IP .k +Compact EM assembly code. +.IP .m +Optimized compact EM assembly code. +.IP .s +Machine assembly language code. +.IP .o +Object file. +.PP +\fIAck\fP accepts the following flags: +.IP \-m\fImachine\fP +This flag tells \fIack\fP to generate a load file for \fImachine\fP. +\fIMachine\fP can also be used as the program call +name, instead of \fIack\fP. +e.g. \fIack \-m8086 file.p\fP is equivalent to \fI8086 +file.p\fP. +.IP \-o +The the next argument as the name of the resulting load file, +instead of the default \fIa.out\fP or \fIe.out\fP. +.IP \-O +Use the EM peephole optimizer, +this flag is superfluous when an machine code is generated. +.IP \-LIB +This flag tells the peephole optimizer +.RF em_opt VI +to add information about the visibility of the names used +to each output module. +This is needed by most +assembler/linkers when these modules are to be inserted +in libraries. +.IP \-l\fIname\fP +Tells \fIack\fP to insert a library module at this point. +For example: the library \fImon\fP contains the +routines for systems calls needed by both C and Pascal. +.IP \-r.\fIsuffix\fP +Most frontends and backends use one or +more run-time libraries. +These flags tell \fIack\fP to include the libraries needed when +a file with \fIsuffix\fP would be included in the arguments. +.IP \-L +Disable the generation of code by the front ends to +record line number and source file name at run-time. +.IP \-p +This flag tells both the Pascal and C front ends to include +code enabling the user to do some monitoring/debugging. +Each time a routine is entered the routine \fBprocentry\fP +is called and just before each return \fBprocexit\fP is called. +These routines are supplied with one parameter, a pointer +to a string containing the name of the routine. +.IP \-w +Suppress all warning messages. +.IP \-v +Verbose. +Print information while juggling with files. +.IP \-g +Try to run the resulting load file. +No arguments can be passed this way, +so it is only useful in simple cases. +.IP \-I\fIdir\fP +\&\`#include\' files whose names do not begin with \`/\' are +always sought first in the directory of the \fIfile\fP argument, +then in the directories named in \fB\-I\fP options, +then in directories on a standard list. +.IP \-D\fIname=def\fP +.IP \-D\fIname\fP +Define the \fIname\fP to the preprocessor, +as if by \`#define\'. +If no definition is given the \fIname\fP is defined as 1. +.IP \-U\fIname\fP +Remove any initial definition of \fIname\fP, before +preprocessing. +.IP \-c\fI.suffix\fP +.IP \-c +\fIAck\fP tries to transform each source into a file with the \fIsuffix\fP. +When no \fIsuffix\fP is specified \fIack\fP stops just +before the phase where it combines all arguments into a load file, +thereby transforming the sources into \fI.k\fP, \fI.s\fP, +\&\fI.o\fP or \fI.m\fP files. +One extra \fIsuffix\fP is recognized here, \fI.i\fP, +this tells \fIack\fP to only preprocess all human readable sources, +producing files with \fIsuffix\fP \fI.i\fP. +Note: \fIack\fP refuses to overwrite argument \fI.e\fP files. +.IP \-t +Preserve all intermediate files. +.IP \-k +Do not stop when an error occurs, but try to transform all +other arguments as far as possible. +.IP \-R\fIprogram=xxx\fP +Replace the \fIprogram\fP by the pathname \fIxxx\fP. +The program names referred to later in this manual are allowed here. +.IP \-R\fIprogram\-xxx\fP +The flag argument \fI\-xxx\fP is given to \fIprogram\fP. +.IP \-E +Produce a complete listing of each Pascal source program. +Normally for each error, one message, +including the source line number, is given. +.IP \-e +List only the erroneous lines of each Pascal source program. +.IP \-{xxx} +The string starting after \`{\' and terminated by a \`}\' is passed +as an option string to the Pascal compiler and supersedes corresponding +options given in the source file. +See the ACK reference manual [4] for a list of options. +.IP "\-+xxx, \-\-xxx" +When you want to interpret your program, you may select some +options during interpretation, like test, profile, flow, extra and count. +A short description of these flags follows: +.RS +.IP " t(est)" 12 +test for undefined, overflow, array bound etc. +.IP " f(low)" +keep track of executed source lines. +.IP " c(ount)" +count the number of times a source line is executed. +.IP " p(rofile)" +count the memory cycles executed per source line. +.RE +.IP "" 5 +Test is on by default, the others are off. Normally, you give these +flag options each time you run the interpreter. +The EM assembler/linker gives you the opportunity to change +the defaults per program. +The changed options are recorded in the "e.out" header. +These flags \-\- and \-+ are passed to the assembler for this purpose. +So, \-\-t and \-+pfce invert the defaults. +.IP \-.\fIsuffix\fP +When linking multiple \fI.o\fP or \fI.m\fP files created by +separate calls of \fIack\fP together, \fIack\fP cannot deduce +the run-time system needed, +unless called as \fIapc\fP or \fIacc\fP. +This flag serves to tell \fIack\fP which runtime system is +needed in such a case. +For example: "ack \-c x.c ; ack \-.c x.o". +.PP +All arguments without a suffix or with an unrecognized suffix +are passed to the loaders, as for flags. +.SH PREPROCESSOR +All C source programs are run through the preprocessor +before they are fed to the compiler proper. +Other human readable sources (Pascal programs and +machine assembly) are only preprocessed when they start with a \`#\'. +.PP +\fIAck\fP adds a few macro definitions when it calls the +preprocessor. +These macro\'s contain the word- and pointer-size and the sizes +of some basic types used by the Pascal and/or C compiler. +All sizes are in bytes. +.PP +.TS +tab(:); +l l l l. +EM_WSIZE:wordsize:EM_PSIZE:pointer size +EM_SSIZE:size of shorts (C):EM_LSIZE:size of longs (C+Pascal) +EM_FSIZE:size of floats (C):EM_DSIZE:size of doubles (C+Pascal) +.TE +.PP +The name of the \fImachine\fP or something like it when +the machine name is numeric is also defined (as 1). +.SH PROGRAMS +\fIAck\fP uses one or more programs in each phase of the +transformation. +The table below gives the names \fIack\fP uses for these +programs. +Internally \fIack\fP maintains a mapping of these names to pathnames +for load files. +The table specifies which type of files are accepted by each +program as input and the file type produced as output. +.TS +tab(:); +l l l l. +input:name:output:description +\&.c:cem:.k:C front end [4,5,6] +\&.p:pc:.k:Pascal front end [2,3,6] +\&.e:encode:.k:Compactify EM assembly language [1] +\&.k:opt:.m:EM peephole optimizer +\&.k .m:decode:.e:Produce human readable EM assembly +\&.k .m:emass:e.out:Linker producing EM machine code [1] +\&.m:be:.s:backend +\&.s:asld:a.out:Assembler/linker producing machine code +\&.s:as:.o:Assembler +\&.o:ld:a.out:Linker producing machine code +.TE +.SH "SEE ALSO" +.PD 0 +em_opt(VI), em_ass(VI), em_cg(VI) +.IP [1] +A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan +Stevenson "Description of a machine architecture for use with +block structured languages" Informatica report IR-81. +.IP [2] +K. Jensen and N. Wirth +"PASCAL, User manual and report" Springer Verlag. +.IP [3] +The ISO Pascal standard proposal ISO/TC97/SC5-N462. +.IP [4] +B.W. Kernighan and D.M. Ritchie, \fIThe C Programming +language\fP, Prentice-Hall, 1978 +.IP [5] +D.M. Ritchie, \fI C Reference Manual\fP +.IP [6] +E.G. Keizer, Amsterdam Compiler Kit, reference manuals and UNIX manual pages. +.PD +.SH DIAGNOSTICS +.PD +The diagnostics are intended to be self\-explanatory. +.SH BUGS +The -g flag is inoperative. +.br +Not all warning messages are superseded by \fB\-w\fP. +.br +Argument assembly files are not preprocessed when fed into the +universal assembler. +.SH AUTHOR +Ed Keizer, Vrije Universiteit, Amsterdam diff --git a/util/ass/em_ass.6 b/util/ass/em_ass.6 new file mode 100644 index 000000000..4003c7216 --- /dev/null +++ b/util/ass/em_ass.6 @@ -0,0 +1,67 @@ +.TH EM_ASS VI +.ad +.SH NAME +em_ass \- EM assembler/loader +.SH SYNOPSIS +/usr/em/lib/em_ass [options] argument ... +.SH DESCRIPTION +Em_ass assembles and links EM modules. +Arguments may be flags, EM modules or libraries. +Flags recognized are: +.IP "-ss, -sm, -sl" +Indicate that your program is small, medium or large. +Medium is the default. +.IP -p +List all procedure names together with base-address (decimal and octal), +procedure number and module of definition. +.IP -d +Used for debugging em_ass itself. +.PD +.PP +em_ass assembles and links together compact EM assembly language modules +from files and libraries, +producing an e.out file as described in [1]. +.PP +Two different types of arguments are allowed: +.IP "1 -" +Compact EM assembly language modules (optimized or not), recognized by a +magic number in the first word. +.PD 0 +.IP "2 -" +UNIX archives, as maintained by arch(I). These archives must contain +EM modules only. +.PD +.PP +EM modules may contain a library message specifying the names +of procedures and external data defined inside the module. +These will only be loaded +if they contain definitions of procedures or data imported by +previously assembled modules. +When \fIack\fP(I) is provided with the -LIB flag it tells the +EM-optimizer \fIem_opt\fP(VI) to insert a library messages +when optimizing modules. +The EM-archiver \fIarch\fP(I) can be used to create libraries +from EM modules. +.PP +Note that it is not possible to do a partial load; +loading starts from compact EM code and produces binary +EM code. No symbol table and no relocation bits are produced. +.SH "SEE ALSO" +ack(I), arch(I) +.PD 0 +.IP [1] +A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan +Stevenson "Description of a machine architecture for use with +block structured languages" Informatica report IR-81. +.SH DIAGNOSTICS +Various diagnostics may be produced. In the case of compiler +produced code the only messages to expect are "Out of memory" +or of the +form: Overflow in XXXX. The latter can usually be cured by giving +a -sl flag, +the former means your program is too big, dimishing +the size of very large procedures can sometimes help. +The most likely errors, however, are unresolved references, +probably caused by the omission of a library argument. +.SH AUTHOR +Ed Keizer, Vrije Universiteit diff --git a/util/misc/em_decode.6 b/util/misc/em_decode.6 new file mode 100644 index 000000000..3413f86ce --- /dev/null +++ b/util/misc/em_decode.6 @@ -0,0 +1,39 @@ +.TH EM_DECODE VI +.ad +.SH NAME +em_decode,em_encode \- compact to readable EM and v.v. +.SH SYNOPSIS +/usr/em/lib/em_decode [ inputfile [ outputfile ] ] +.br +/usr/em/lib/em_encode [ inputfile [ outputfile ] ] +.SH DESCRIPTION +Most programs involved with the EM project only produce and accept +EM programs in compact form. +These files are only machine readable. +A description of this compact form can be found in [1]. +To inspect the code produced by compilers or to patch them for one reason +or another, you need human readable assembly code. +Em_decode will do the job for you. +.PP +Em_decode accepts the normal compact form in both optimized and +unoptimized form +.PP +Sometimes you have to make some special routines directly +in EM, for instance the routines implementing the system calls. +At these times you may use em_encode to produce compact routines +out of these human readable assembly modules. +.PP +The first argument is the input file. +The second argument is the output file. +Both programs can act as a filter. +.SH "SEE ALSO" +.IP [1] +A.S.Tanenbaum, Ed Keizer, Hans van Staveren & J.W.Stevenson +"Description of a machine architecture for use of +block structured languages" Informatica rapport IR-81. +.IP [2] +ack(I) +.SH DIAGNOSTICS +Error messages are intended to be self-explanatory. +.SH AUTHOR +Johan Stevenson, Vrije Universiteit. diff --git a/util/opt/em_opt.6 b/util/opt/em_opt.6 new file mode 100644 index 000000000..12ebc4836 --- /dev/null +++ b/util/opt/em_opt.6 @@ -0,0 +1,34 @@ +.TH EM_OPT VI +.ad +.SH NAME +em_opt \- EM peephole optimizer +.SH SYNOPSIS +/usr/em/lib/em_opt [-Ln] [ argument ] +.SH DESCRIPTION +Em_opt reads a compact EM-program, argument or standard input, +and produces another compact EM program on standard output +that is functionally equivalent, +but smaller. +Some other functions are here that make this program mandatory +before running a codegenerator, +it may be left out when interpretation is wanted. +Flags recognized are: +.IP -L +Make a library module. +This means that the output will start with a message giving +the names of all exported entities in this module. +.IP -n +Do not optimize. +No peephole optimizations will be performed, +other functions will be carried out. +.SH "FILES" +/usr/tmp/emopt??????, is used when the -L flag is given only. +.SH "SEE ALSO" +ack(I) +.PD 0 +.IP [1] +A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan +Stevenson "Description of a machine architecture for use with +block structured languages" Informatica report IR-81. +.SH AUTHOR +Hans van Staveren, Vrije Universiteit