Pascal implementation

The Pascal-P6 Compiler

Scott A. Franco

1Introduction to Pascal-P6

To get started using Pascal-P6, skip to “3 Using Pascal-P6”.

Memory or type protected languages are a current fad, starting with Java, through C#, and now Rust. But type safe languages have been around since the beginning of computer languages.

Pascal, a language popular since it’s beginning over 50 years ago, has a common form that is not type safe, often referred to as Pascal-C. Its Pascal stripped of it’s type safety and combined with C type constructs such as type casting.

Original Pascal was a type and memory safe language, and has been since the beginning. The modern constructs of the Pascaline language extension bring the language up to the present day, giving you functionality equivalent to C, or even C++, but with complete type and memory safety.

Pascal-P6 is a compiler for an extended version of ISO 7185 Pascal known as “Pascaline”. This is a type secure language known for regularity of syntax and function. The original Pascal Language was created in the 1970s by Niklaus Wirth’s group in ETH Zurich.

The implementation package Pascal-P was created by Wirth’s group as a machine independent compiler interpreter. Pascal-P6 is the 6^th edition of that compiler. Pascal-P4 was a “subset” of the original Pascal language. Pascal-P5 supported the full ISO 7185 standard Pascal language. Pascal-P6 supports the original ISO 7185 Pascal language and a set of extensions known as “Pascaline”.

The original Pascal language is well documented. The files accompanying the Pascal-P6 compiler in the doc directory are:

For the original Pascal language, many good references exist:

Note that there are countless other books on Pascal. Avoid books that talk about one specific implementation, or are meant for Borland Pascal (see below).

Pascal-P6 can be used as an ISO 7185 language compiler, as a Pascaline compiler, or a mixture of both. Pascaline is completely downward compatible with ISO 7185 Pascal.

Please note that Borland or “Delphi” Pascal is a distinct language from original Pascal (despite bearing the same name), created in around 1983. The two languages are not compatible. For more information on the Borland language series see their documentation.

Note that this document covers very little about the Pascal or Pascaline languages themselves. See the above documentation for information on the languages covered.

Pascal-P6 has both an interpreter and a machine code generator. See “7: Different generation and run options: pint, pmach and cmach, and pgen”.

1.1History of Pascal-P6

The Pascal-P series compilers were the original proving compilers for the language Pascal. Created in 1973, Pascal-P was part of a “porting kit” designed to enable the quick implementation of a Pascal language compiler on new machines. It was released by Niklaus Wirth’s students at ETH in Zurich.

The implementation and description of the language Pascal in terms of itself and in terms of a “pseudo machine” were important factors in the propagation of the language Pascal. From the early version of Pascal-P came the CDC 6000 full compiler at Zurich, several independent compilers including an IBM-360 compiler and a PDP-11 compiler, and the UCSD “bytecode” interpreter.

The original article for the Pascal-P compiler is “The_Pascal_P_Compiler_implementation_notes.pdf” in the doc area of the Pascal-P6 project directory tree.

In the name “Pascal-P” the “P” stood for “portable”, and this was what Pascal-P was designed to do. It also stood for an example and reference implementation of Pascal. Niklaus Wirth later issued a paper, together with Tony Hoare for the “Axiomatic definition of Pascal”, which was also aimed at exactly specifying the semantics of Pascal.

As the importance of Pascal-P grew, the authors adopted a version number system and working methodology for the system. A new, cleaner and more portable version of the system was created in 1974 with the name Pascal-P2, and left the multiple early versions of the system as termed Pascal-P1.

From the Pascal-P2 revision of the compiler comes many of the original Pascal compilers, including UCSD. In 1976, Niklaus Wirth’s group made one last series of improvements and termed the results Pascal-P3 and Pascal-P4. Pascal-P3 was a redesigned compiler, but used the same pseudo machine instruction set as P2, and thus could be bootstrapped from an existing P2 implementation. P4 featured a new pseudo instruction set, and thus was a fully redesigned compiler.

Pascal-P was always an incomplete implementation of the Pascal language (a subset), and was designed to be so. After it was created, the ISO 7185 standard for Pascal was issued, and today Pascal-P4 exists and is still usable with minor changes to bring it into ISO 7185 compliance for its source (not the language it compiles).

Pascal-P4 has it’s legacy problem of being a subset compiler of the full language. Further, it is only usable for programs that avoid its weaknesses, such as string storage. Keep in mind that Pascal-P was never designed to be a general purpose system, but rather to compile itself on a new machine – and then rapidly be improved to become a full compiler.

In 2008 I set out to improve the Pascal-P4 code to accept the full language Pascal as stated by the ISO 7185 language standard. The name of the result was obvious: Pascal-P5.

Pascal-P5 exists as a separate project and is an interpreter only. It can form the basis for any ISO 7185 based project. The project intent was to only add the minimum code to the Pascal-P4 implementation to bring it up to ISO 7185 status. It also introduced a large suite of tests to verify compliance with the ISO 7185 Pascal standard.

The purpose of Pascal-P6 was to create a working compiler implementation from Pascal-P5. Thus Pascal-P5 serves as a working, interpretive model of ISO 7185 Pascal, and Pascal-P6 serves as an actual machine implementation of it.

The first task of the Pascal-P6 implementation was to create a series of extensions to ISO 7185 Pascal. All actual machine implementations of Pascal, including the original CDC 6600 implementation, include a series of extensions. With Pascal-P6, I wanted to introduce a series of extensions that would both bring the compiler to a usable state as practical compiler and also bring it up to the “state of the art” (at least as of 2024).

I realize that introducing a set of new features to Pascal is going to be controversial. I wanted the extensions to be more than just a laundry list of features added by a compiler implementer (as has happened with Pascal so many times in the past). Thus I collected the features implemented by Pascal-P6 as a formal language in its own right, as the language “Pascaline”. There is a formal specification accompanying Pascal-P6 (“pascaline.pdf”) as well as a rationale (“Pascaline_rationale.pdf”), a discussion of both the language, its features, and its implementation.

1.2Pascal-P6 as a strict ISO 7185 compiler

Pascal-P6 can easily be used as a strict ISO 7185 Pascal compiler. Using the s+/iso7185+ option, or “strict” flag, the source language for Pascal-P6 and the ISO 7185 language are identical. It is, however, important to understand the exact meaning of the s+/iso7185+ option.

I use the term “strict” for the s+/iso7185+ option, and not “standard”, because the Pascal-P6 compiler is fully compatible with the ISO 7185 Pascal language regardless of if the flag is off or on¹. In pascal-P6 the option has the following meanings when ON:

• All extended keywords from Pascaline are turned OFF, meaning they can be used as program identifiers.

• So called “force sequences” or “\” character special interpretations in strings is turned off, meaning the “\” character has no special meaning in strings.

Both of these are in compliance with the ISO 7185 standard. An implementation is allowed to define new keywords in ISO 7185 Pascal. Also the interpretation of characters in ISO 7185 Pascal is up to the implementation (it does not even specify ASCII).

I recommend that even if you are developing strict ISO 7185 Pascal source code that you leave the s flag OFF (the default). Why? If the flag is off, that allows you to use keywords that are reserved in Pascaline, or use the force character “\” in your source. This will cause problems later if you then decide to use Pascaline extensions. In fact, the best way to develop truly portable ISO 7185 Pascal programs is to avoid using other ISO 7185 Pascal implementations’ keywords as well. You might want to examine the keyword list for FPC (Free Pascal) as well to make sure.

The use of the force character (“\”) is trickier. If you put it in your ISO 7185 programs with the s flag OFF (s-), then you will need to specify “\\” to get just the force character. But if you then compile it on a system that does not understand force sequences, it will evaluate to “\\” (double “\”). The best method is to avoid the force character whenever possible. Fortunately, most ISO 7185 Pascal compilers today do understand force sequences.

When using Pascal-P6 as a ISO 7185 compiler, I recommend that you occasionally check your compiles by turning on the s+ switch. This will make sure that you have not inadvertently used Pascaline constructs in your source.

1.3Pascal-P6 vs. FPC (Free pascal), Borland, or other dialects

Pascal-P6 does not accept the common dialects² of Borland or FPC languages³. There are good implementations of these dialects, both by Borland themselves and by the FPC group. My recommendation is if you want to use that source language, use the best compiler for it, namely the FPC or Borland compilers. There is no plan for a Pascal-P series compiler that is also Borland dialect compatible, and further, the type protection model of the two are diametrically opposed.

FPC recently completed implementation of an ISO 7185 compliance switch. This makes it a good backup compiler for ISO 7185 Pascal compliant applications. See the FPC web site for more details.

See also then next section for comments on source language.

2The Pascal-P6 source language

Pascal-P6 understands the Pascaline source language as documented in pascaline.pdf, available in the doc or documents directory of Pascal-P6 project. Pascaline is fully compatible with ISO 7185. There are, however, several things you will find only in this documentation and not the Pascaline specific documentation:

• Features of Pascaline that are not (yet) implemented in Pascal-P6.

• Local extensions in Pascal-P6 that are not also in general Pascaline.

• Concrete details of features in Pascaline specific to Pascal-P6.

These will be detailed.

Pascal is the base language for Pascal-P6. Pascaline is a superset of Pascal. Pascal-P6 accepts both, but adds a few features of its own.

2.1Features of Pascaline NOT implemented in Pascal-P6

The following features of Pascaline are not yet implemented in Pascal-P6. The expectation is all of them will be implemented shortly. Also keep in mind that Pascal-P6 is still a project in development, and carries a version number < 1.0.

Please see “pascaline.pdf” in the doc file section for more details on the Pascaline language.

2.2Pascal-P6 implementation details

At this writing, there is a 16 bit, 32 bit and a 64 bit implementation of Pascal-P6. The following characteristics exist:

The maximum size of any input line, identifier, or string constant is 250 characters.

The base character set is ISO 8859-1, or 8 bit characters. The compiler has no reliance on any character in the range 128 to 255 and will accept any character in that range for input or output.

2.2.1Header files

All of the Pascaline header files are implemented, input, output, error, list and command. output, error and list all go to the standard output file. As detailed in Annex C of the Pascaline standard, undefined program header parameters must be declared in a type statement. Any type of valid Pascaline file is acceptable, including complex structured types.

The filenames corresponding to the names of the header file parameters are read from the command line:

program print(myfile, output);

var myfile: text;

…

executed with a command line of:

print document.txt

Will assign file myfile to the name on disk “document.txt”.

The command file reads the command line passed to the program on startup. There is only one line in the file, and eof() immediately follows eoln() in the file. When the command file is read as well as other parameters appear in the program header, then the command file will be positioned after all other header file names or entries have been read from the command line.

2.2.2Alternative header value input

Pascal-P6 can have integer or real parameters in the header file, in addition to just files:

program test(myint, myreal);

var myint: integer;

myreal: real;

Pascal-P6 automatically reads these values off of the command line and into the specified variables. If a they are mixed values on the header, they will be read in turn from the command line as specified in Annex C of the Pascaline standard.

2.2.3Character escapes

Pascal-P6 implements Pascaline Annex E: character escapes in total.

2.2.4Character sets

Pascal-P6 implements Annex D.1 “ISO 8859-1 Character Set Encodings”. However, it only relies on the parts of ISO 8859 that are common to all pages in the standard. Thus, Pascal-P6 will accept, and will generate, any character in any page in the set of ISO 8859 code pages.

Note that Pascal-P6 is dependent on ISO 8859 because it can generate force control characters specific to the ISO 8859 standard.

2.2.5Modular structure

Pascal-P6 implements modules by outputting an intermediate file for each module, then the intermediates are concatenated and loaded as a single file. The intermediate contains sufficient information for pint to understand the module structure, and it links the modules together.

In the case of pgen, each module is compiled to an assembly file, and then the modules are linked together as a stack of modules by the compiler/assembler for the target machine.

Modules in Pascal-P6 are implemented by the following method:

1. Each module calls its own initializer block, then calls the next module in the stacking order. When the module it calls returns, that module then calls the deinitializer for the module, and returns to the module that called it. Program modules only have a single initializer block. When the block is done, the program module returns.

2. Each module is stacked up on the last. The interpreter or runtime system arranges to call the first module in the stacking order, then when it returns, the entire program exits.

3. Its up to the user to stack the modules properly on the command line. If a module is called via a function or procedure, and accesses global data from that module, the program will fault with uninitialized access error. Module overrides are an exception. Each virtual function or procedure in the module is initialized to point to an error routine when the module is started, and attempts to override an uninitialized virtual vector will generate an error.

4. The program module MUST be the last module in the stacking order.

5. A process module is like a program module, but it starts a new processor thread to run its initialize block, then calls the next module in the stacking order. From the time the thread is branched off to run the process block, the main thread and the thread running the process module run in parallel.

2.2.6Implementation of Annexes G-O

Pascal-P6 has the ability to link to and run procedures and functions from the standard Pascaline libraries. These include:

At this writing, only the services module is implemented in pint.

The Pascaline libraries, originally written in Pascaline, were rewritten in C (for several reasons), and appear as the independent library called “Petit-ami”. They can be accessed by any language.

Note that not all Pascaline libraries appear in Petit-ami. For example the strings module is still written in Pascaline, and makes no sense for other languages outside of Pascaline.

2.2.6.1Enabling externals

External linking to Petit-ami is enabled via the EXTERNALS define when compiling Pascal-P6. When this definition is active, all modules with the names in the Pascaline external module table above will be redirected to external definitions.

2.2.6.2Using externals

The externals in Pascal-P6 are compiled with the system as object files that are linked into the system. Further, there is a block of code in pint that translates each call to the C language, in the file:

externals_<system>.inc

Where <system> is a specific compiler implementation. The existing implementations are:

Note that the ISO 7185 file essentially selects “no externals”, since ISO 7185 Pascal does not have that capability.

Programs that use the externals will simply use or join them the same way as any other module:

program dir(output);

uses services;

var fp: filptr;

begin

list(‘*.pas’, fp);

while fp <> nil do begin

writeln(fp^.name);

fp := fp^.next

end

end.

To allow the program to see the definitions, the module used must have a local Pascaline file:

services.pas

The module used should not be included (as normal modules are) in the input deck (usually created for you by the Pascal-P6 script). It will not harm anything, but it will do nothing and will take up space. All the functions in the module will be redirected to the externals handling in pint.pas.

The joins statement can be equally used to access externals. The above program using this method is:

program dir(output);

joins services;

var fp: services.filptr;

begin

services.list(‘*.pas’, fp);

while fp <> nil do begin

writeln(fp^.name);

fp := fp^.next

end

end.

3Using Pascal-P6

3.1Getting Pascal-P6: Repositories for Pascal-P6

Pascal-P6 is managed using git version control system. It is stored at the following repositories:

https://github.com/samiam95124/Pascal-P6

https://sourceforge.net/projects/pascal-p6/

You can obtain Pascal-P6 from a given version of the system, or from the current tip (the collection of most current files). Versioned trees contain code that has been extensively tested, but the tip will contain the latest code. The available versions can be found at:

https://github.com/samiam95124/Pascal-P6/releases

To obtain a release, go to the above page, find an archive type you want and click on it. The archive methods are zip and tar.gz. To unpack each is approximately:

$ unzip Pascal-P6-X.X.zip

$ tar -xvzf Pascal-P6-X.X.tar.gz

To download the tip typically is:

$ git clone https://github.com/samiam95124/Pascal-P6.git

Besides the advantage of having the current code, using git to obtain a file tree also gives you source control capabilities.

Please submit any bug tickets to:

https://github.com/samiam95124/Pascal-P6/issues

3.2Configuring Pascal-P6

Pascal-P6 has a simple configuration script to set up the binary, script files and compiler in use for the system, that uses the proper defaults for your system. Go to the root directory and execute:

[Windows]

> setpath

> configure

> buid (optional)

[Linux/BSD/Mac]

$ . setpath

$ ./configure

$ build (optional)

You can avoid the need for setpath by placing the ./bin directory on your path. You will also want to set the environment variable:

export PASCALP6="$PWD"

Different scripts in the archive reference this environment variable.

The configure script attempts to automatically determine the environment you are running under, choose the correct compiler, bit width of your computer, etc. You can override this by using the options for configure:

The configure script will take the preconfigured versions of the Pascal-P6 binaries, the script files and other files and install them for the specified host compiler.

Although the directory bin will contain working copies of the binaries and scripts, there is no guarantee which version it contains. Always run the configure script to setup the particular system you are using.

The configure script loads precompiled versions of the binaries for the system into the bin/ directory. At this writing, these are for Linux/Ubuntu 64 bit systems. If you do not have the means or don’t wish to rebuild the binaries, you can leave them to be the defaults and not run a make on the project.

Example configure:

Pascal-P6$ ./configure

Set up for iso7185

Bit length 64

Configure completed!

3.3Compiling and running Pascal programs with Pascal-P6

To simply compile a run a program, you can use the pc command:

$ pc hello

$ ./hello

When a pascal program is run this way, it gets it's input from the terminal (you), and prints its results there.

3.3.1Compiling on different run configurations

There are several types of run arrangements for Pascal-P6. The current options are:

Typical configurations are:

pc –pint test

For interpretation.

pc test

./test

For compilation to binary executable and run.

Note that a compiled binary, either –pgen or –package, results in a standalone binary that can run without need for interpretation.

3.4The basic programs

The pc program operates via the basic binary programs:

pcom <source file> [<intermediate file>] [<options>]

Compiles a Pascaline source file to produce an intermediate language file.

pint <intermediate file> <output file> [<options>]

Either interprets the given intermediate file or converts it to a binary deck to the output.

pmach <binary deck> <output file> [<options>]

Loads and interprets the given binary deck.

cmach <binary deck> [<options>]

Loads and interprets the given binary deck. The same as pmach, but it is encoded in C.

pgen <intermediate code> <assembly file> [<options>]

Converts the input intermediate code into assembly code for the current host processor. This is subsequently converted to a binary by an assembler or C compiler.

3.5Compiler options

Pascal-P6 uses a "compiler comment" to indicate options to the compiler, of the form:

(*$option+/-, ...*)

This option can appear anywhere a normal comment can. The first character of the comment MUST be "$". This is followed by any number if option switches separated by ",". If the option ends with "+", it means to turn it on. If the option ends with "-", it means turn it off. If neither appear, it means to turn the option on.

Example:

(*$l-*)

Turns the listing of the source code OFF.

Alternately, the options can be specified on the command line:

pc -[-]option[+/-]

Note that for command line options, either a single ‘-’ (hyphen) or double ‘–’ will introduce an option. Pascal-P6 does not support true GNU/Linux single character options like -ld where each of the letters are an option. Each option is a complete word. As with compiler comment options, ‘+’ turns the option on, and ‘-’ turns the option off, and if neither appear, the default is to turn the option on.

The following options are available:

It is possible to cause problems in the code if the options are turned on or off arbitrarily in the middle of the program. It is recommended that you place option sets at the top of the program only unless you are sure what you are doing.

Pascal-P6 provides a lot of switches for developers to use to debug the compiler. A good rule is: if you don’t know what a switch does, don’t use it. Pascal-P6 is a compiler developer’s compiler. This means that everything in the system is available to change, including things that make no sense for end users.

Note that a lot of the debug switches previously available in Pascal-P5 have been moved to the debug mode in Pascal-P6. See “6 Pascal-P6 debugger mode”.

3.5.1Option descriptions

List format is: short form, long form, description.

t+/- prttables+/- Print/don't print internal tables after each routine is compiled.

Prints the complete set of identifier and types declared in each block at the end of the block.

l+/- list+/- List/don't list the source program during compilation.

Enables the compiler to output a source listing.

d+/- chk+/- Add extra code to check array bounds, subranges, etc.

Enables several debug checks in the code.

c+/- lstcod+/- Output/don't output intermediate code.

Supresses the creation of the intermediate file contents. Note that the output intermediate file is always created, but it’s contents will be empty.

v+/- chkvar+/- Check variant records.

Perform active variant checks. Checks if the variant in a variant record is active when accessed.

r+/+ reference+/- Perform reference checking.

Checks if identifiers used in the program have been referenced by the code.

u+/- undestag+/- Perform Undiscriminated variant checking.

Forces checking on undiscriminated variants. These are variant records where the tagfield is not allocated, meaning there is no tagfield to check before accessing a given variant. The u flag forces the tagfield to be allocated as an anonymous member of the record, and will assign it the correct value any time a write access is done within a variant. On read access to the variant, the anonymous tag field value is checked, and faulted if not correct. This option actually generates more code than just specifying the tag field exists and setting it properly. However, the overhead of this check can be simply removed by removing the option. See also the v option.

s+/- iso7185+/- Restrict input language to ISO 7185 Pascal.

Produces errors on any Pascaline level language features. Disables all Pascaline extended keywords. Removes the ability to use force sequences in strings (“\”). Note that this is not a ISO 7185 compliance flag. Pascaline is completely compliant with ISO 7185 Pascal regardless of the state of the s option. It simply restricts the source language to ISO 7185 Pascal only.

x+/- prtlex+/- Dump lexical information during the run.

Outputs the lexical tolkens scanned from the input source.

b+/- prtlab+/- Print goto labels used at the end of the compile.

Prints all goto labels used in the compile. For debugging purposes.

y+/- prtdisplay+/- Dump display information at the end of the compile (symbols).

Performs a dump of all identifiers in the display at the end of the compile run. For debugging purposes.

i+/- varblk+/- Check VAR block violations.

Checks various faults caused by having a parameter VAR access outstanding. This includes changing a variant while there is an outstanding reference, or disposing a dynamic variable, etc. This is an expensive check, and thus normally set OFF. It should be enabled and used for advanced checking of a running program.

g+/- prtlabdef+/- Dump goto and other location labels at intermediate assembly time.

Dumps the interpreter label tables at the end of intermediate assembly.

h+/- sourceset+/- Add source line sets to code.

Adds source set instructions in the output byte code. These are used to produce error diagnostics indicating what source line was executing. Note that debug mode does not use these instructions for listing, only for breakpoints on given source lines.

n+/- recycle+/- Obey heap recycle requests. If false, no space is recycled.

This flag is used to turn off all recycling of dynamic variables. Any variables recycled will simply be left occupied, effectively quarantining them. This is used to debug recycle issue. Note that there are other options that fault on attempts to access variables that have previously been disposed, such as the p and m flags.

o+/- chkoverflo+/- Check for arithmetic overflow.

Enables checking for various overflow conditions.

p+/- chkreuse+/- Check for reuse of freed entry in heap space.

When variables are freed, the space returned is broken into a flagged entry that generates faults on use, followed by free space. This effectively enforces use after recycle checks but with low waste of freed blocks.

m+/- breakheap+/- Modifies the p flag to flag the remaining space as occupied.

The use of p option should check all attempts to use a previously freed block. However there are cases where, especially when mixed protection checks are enabled, that it is better not to reuse the recycled space at all. This is effectively a mixture of the n and p flags, and thus combines stoppage of recycling with flagging of reuse after dispose checks.

q+/- chkundef+/- Check accesses to undefined memory.

Checks if an undefined location is accessed in the code. The interpreter keeps a large bitmap of memory and checks read/write accesses. Note that some undefined checks such as pointer undefined cannot be turned off. Note also that this check is only performed in the interpreter.

w+/- debug+/- Enter debug mode (pint only).

Causes pint to enter debug mode before starting the program. See also “Pascal-P6 debugger mode”.

a+/- debugflt+/- Enter debugger on fault

Enters debug mode if any fault occurs. See also the w option.

f+/- debugsrc+/- Perform source level debugging.

Loads the source code file(s) for the current code, and cross indexes the source code lines. Debug mode then changes to source mode. See also “Pascal-P6 debugger mode”.

e+/- machdeck+/- Output binary deck from pint instead of running the assembled results.

Changes the way pint works. After the intermediate is assembled to byte code into the internal store, the entire byte code program is output in a hex file format. Then pint stops without running the resulting program. This flag is used to prepare binaries for pmach or cmach. Note that the output file, which normally contains output from the running program, now will contain the hex encoded binary, and thus should be treated differently.

3.6Errors

3.6.1Source errors

Source errors are output as follows:

1 -48 program test(output);

2 -48

3 -48 begin x

4 7

5 7 writeln('hello, world')

5 **** ^104,59

5 **** 104 Identifier not declared

5 **** 59 Error in variable

6 7

7 7 end.

7 **** ^51

7 **** 51 ':=' expected

Errors in program: 3

Error numbers in listing:

-------------------------

51 1 ':=' expected

59 1 Error in variable

104 1 Identifier not declared

The caret (‘^’) character indicates where in the line the error occurred. The error numbers are an expanded set of the original errors from the ETH compiler. pcom outputs an optional list of the error equivalents for error numbers.

At the end of the compiler run, a list of errors by number, the number of occurrences of each error, and the error text is output.

3.6.2Interpreter errors

When the program is run by pint, the errors appear as:

1 -48 program test(output);

2 -48

3 -48 begin

4 7

5 7 writeln('The number is: ', 10/0)

6 21

7 21 end.

Errors in program: 0

P6 Pascal interpreter vs. 0.1.x

Assembling/loading program

Running program

The number is:

*** Runtime error [5]: Zero divide

The source line number of the error text is given, followed by the error description.

3.7Runtime errors

When a binary executable is run, the errors appear as:

Compiling test...

P6 Pascal compiler vs. 0.2.x

Pascal-P6 complies with the requirements of Pascaline version 0.4

and the following annexes: A,B,C,E.

1 -8 program test(output);

2 -8

3 -8 begin

4 5

5 5 writeln(1/0)

6 14

7 14 end.

Errors in program: 0

P6 Pascal AMD64/gcc 64 bit code generator vs. 0.2.x

Generating program

Program generation complete

Running with pgen

/usr/bin/ld: /tmp/ccsmxSEo.o: in function `resetfn':

/home/samiam/projects/pascal/pascal-p6/source/AMD64/gcc/psystem.c:1846: warning: the use of `tmpnam' is dangerous, better use `mkstemp'

*** Runtime error: test:5:Zero divide

The module name where the error occurred and the line number of the error is given.

3.8Other operations

Within the Pascal-P6 toolset, you will find a series of scripts to perform common operations using Pascal-P6. This includes building the compiler and interpreter using an existing ISO 7185 compatible compiler, and also testing Pascal-P6.

The scripts used in Pascal-P6 are designed to be independent of what operating system you are running on. The Pascal-P6 system as been successfully run on the following systems⁴:

• Windows

• Ubuntu linux

• Mac OS X

To enable this to work, there are two kinds of scripts available, one for DOS/Windows command shells, and another for Unix/Bash. These two script files live side by side, because the DOS/Windows scripts use a .bat extension, and Bash scripts use no extensions. Thus, when a script command is specified here, the particular type of script file is selected automatically.

3.9Reliance on Unix commands in the Pascal-P6 toolset

Most of the scripts in this package, even the DOS/Windows scripts, rely on Unix commands like cp, sed, diff, chmod and others.

For Windows, the Mingw toolset is available:

http://www.mingw.org/

Mingw uses GNU programs that are compiled as native Windows .exe files without special .dll files

The scripts in Pascal-P6 are available in both DOS/Windows and bash versions. It is also possible to just use the bash shell that is provided with Mingw.

Using the Mingw toolkit, it is possible to use the bash scripts by simply executing bash under Windows.

Alternately, you can use the WSL or “Windows Subsystem for Linux”.

3.10The “flip” command and line endings

Every effort was made to make the Pascal-P6 compile and evaluate system independent of what system it is running on, from Windows command shell, to Linux with Bash shell. One common problem is that several utilities don’t appreciate seeing a line ending outside of their “native” line ending, such as CRLF for Windows, and LF for linux. Examples include “diff” (find file differences) and Bash.

Therefore many of the scripts try to remove the line ending considerations, either by ignoring such line endings, or by converting all of the required files to the particular line ending in use.

The key to this is the “flip” utility. “flip” is available on most systems. Unfortunately, even flip is not found on some systems. Thus Pascal-P6 includes the flip.c program with the distribution, and you can compile to form a binary on your system to replace the utility.

To make the flip utility, you run:

$ make_flip

Then flip will exist in the root directory.

4p2c: The Pascal to C translator

4.1Overview

p2c is a utility that translates Pascal source programs into C source code. It reads a single Pascal source file (.pas) and produces two output files: a C source file (.c) containing the translated program, and a C header file (.h) containing type definitions and function declarations. The generated C code can then be compiled with any standard C compiler (gcc, clang, etc.) to produce a native executable.

The purpose of p2c is to allow Pascal programs to be ported to environments where only a C compiler is available, or to integrate Pascal-written algorithms into C-based projects. The translation is designed to produce readable, human-comprehensible C code that preserves the structure and comments of the original Pascal source as closely as possible.

p2c is itself written in Pascal and is compiled and run using the Pascal-P6 compiler toolchain. It handles ISO 7185 Pascal and the Pascaline extensions supported by Pascal-P6, with the exception of the modular features (uses and joins statements), which are not yet supported.

4.2Executing p2c

p2c is invoked from the command line. It must be run from the directory containing the Pascal source file to be translated. The basic invocation is:

$ p2c <filename>

where <filename> is the name of the Pascal source file without the .pas extension. For example, to translate hello.pas:

$ cd sample_programs

$ ../bin/p2c hello

This produces hello.c and hello.h in the current directory. The C file can then be compiled with:

$ gcc -o hello hello.c ../libs/source/pas2csup.c -lm

The pas2csup.c file provides runtime support functions for set operations and typed file I/O. The -lm flag links the math library, which is needed if the Pascal program uses any mathematical functions (sin, cos, sqrt, etc.).

4.2.1Command-line options

p2c accepts the same compiler options as the Pascal-P6 compiler, specified with a dash prefix. Options can be negated with an "n" prefix. For example:

$ p2c -list hello

$ p2c -nlist hello

The first form enables listing of the source during translation; the second disables it. The option names are the same as documented in the compiler options section of this manual. Options that control code generation in the compiler (such as debug checking, heap recycling, overflow checking) are accepted by p2c for compatibility but have no effect on the C output.

4.2.2Building p2c from source

To build p2c from its Pascal source, run the following from the project root directory:

$ bin/pc utils/p2c

This compiles utils/p2c.pas using the Pascal-P6 compiler and produces the p2c executable. Copy it to the bin directory for convenience:

$ cp utils/p2c bin/p2c

4.2.3Running the regression tests

A regression test suite verifies that p2c correctly translates a set of sample programs. Run it from the project root:

$ bin/testp2cs

This translates each sample program, compiles the resulting C code with gcc, runs the executable, and compares the output against a known-good reference. The test report shows pass/fail status, gcc warnings, and any output differences.

4.3Generated file structure

For a Pascal source file named prog.pas, p2c produces two files:

4.3.1The C source file (prog.c)

The .c file contains, in order:

1. A comment banner identifying the file as p2c output and naming the source program.

2. Standard C library includes: stdio.h, stdlib.h, string.h, math.h, and setjmp.h.

3. An include of pas2csup.h, which provides runtime support for set operations and typed file I/O.

4. An include of the generated header file (prog.h).

5. Compatibility definitions for bool/true/false and helper macros for Pascal-style eof, eoln, and character reading.

6. Constant definitions as #define macros.

7. Enumeration types, structure types, and typedefs.

8. Global variable declarations.

9. jmp_buf declarations for any Pascal labels used in goto/longjmp translation.

10. Function and procedure implementations.

11. The main() function containing the translated program body.

4.3.2The C header file (prog.h)

The .h file contains:

1. An include guard (#ifndef prog_H / #define prog_H / #endif).

2. Include of stdbool.h.

3. The p2c_procptr typedef for procedure/function parameters.

4. Forward declarations of struct types.

5. Declarations of all global functions.

4.3.3The runtime support library (pas2csup.h / pas2csup.c)

The runtime support library provides:

Set operations: p2c_sclr (clear), p2c_sadd (add element), p2c_radd (add range), p2c_suni (union), p2c_sint (intersection), p2c_sdif (difference), p2c_scpy (copy), p2c_sisin (membership test), p2c_sequ (equality), p2c_sinc (subset test). Sets are represented as 32-byte unsigned char arrays (256 bits), matching Pascaline set semantics.

Typed file I/O: p2c_frewrite, p2c_freset, p2c_fput, p2c_fget, p2c_fwrite, p2c_fread, p2c_feof. These implement Pascal binary file semantics using C stdio.

4.4Translation of Pascal constructs to C

This section describes, construct by construct, how p2c translates Pascal source code into C. Understanding these translations is essential for reading and debugging the generated C code.

4.4.1Program structure

A Pascal program declaration becomes a C main() function. The program name is used for the header file include guard. Program parameters (input, output) are handled implicitly: input maps to stdin and output maps to stdout.

Pascal:

program hello(output);

begin

writeln('Hello, world')

end.

C:

int main(void)

{

printf("Hello, world\n");

}

Every function body, including main(), includes a declaration of two set temporaries (_stmp1 and _stmp2) marked with __attribute__((unused)). These are used by set operations if they appear in the function.

4.4.2Scalar types

Pascal scalar types are mapped to C types as follows:

integer maps to long. This provides at least 32 bits on all platforms, matching Pascal-P6 integer semantics.

real maps to double. Pascal-P6 uses 64-bit IEEE floating point.

char maps to char. Single-byte character.

boolean maps to bool (from stdbool.h, or emulated as int with true=1/false=0 for older compilers).

4.4.3Subrange types

Subrange types are mapped to the smallest C integer type that can represent the range. For example, a subrange 0..255 becomes unsigned char, a subrange 1..43 becomes unsigned char, and a general integer subrange becomes long. Char subranges remain char.

Pascal:

type index = 1..43;

C:

/* index represented as unsigned char in parameters and locals */

4.4.4Enumerated types

Pascal enumerated types become C enum declarations. The enumeration constants are available as integer values in expressions. Variables of the enumerated type are declared as int.

Pascal:

type mover = (user, prog);

var nextmove: mover;

C:

enum mover {

user,

prog

};

int nextmove;

4.4.5Constants

Pascal named constants become C #define preprocessor macros. Integer constants produce integer literals; real constants produce floating-point literals with full precision; character constants produce character literals; string constants produce string literals.

Pascal:

const maxstr = 43;

entsym = 'E';

C:

#define maxstr 43

#define entsym 'E'

4.4.6Arrays

Pascal arrays are translated to C arrays with adjusted dimensions to account for Pascal indexing conventions. Since Pascal arrays can start at any index (commonly 1), while C arrays always start at 0, p2c allocates extra space and accesses elements using the original Pascal indices directly.

For an array [0..N], the C dimension is N+1. For an array [1..N], the C dimension is N+1, leaving element 0 unused. For packed arrays of char (strings), two extra bytes are allocated to accommodate a null terminator.

Pascal:

var a: packed array [1..43] of char;

flags: array [0..8190] of boolean;

C:

char a[45]; /* 43 + 2 for 1-based indexing and null */

bool flags[8191]; /* 0..8190 = 8191 elements */

Multi-dimensional arrays follow the same pattern, with each dimension independently adjusted:

Pascal:

var galaxy: array [0..7, 0..7] of quadrec;

C:

quadrec galaxy[8][8];

4.4.7Strings (packed arrays of char)

Pascal strings (packed arrays of char) are represented as C char arrays. Because Pascal strings are 1-based, the C array is sized with extra room and element [0] is unused. String operations use the address of element [1] as the effective string pointer.

String assignment uses memmove with the address of element [1]. String comparison uses strncmp, also starting at element [1]. String constants in write statements are emitted as C string literals in printf format strings.

Pascal:

a := 'erhklhklgsdtsknsknskdlhfksghskhskeljefhjgkh';

C:

memmove(&a[1],"erhklhklgsdtsknsknskdlhfksghskhskeljefhjgkh", 43);

Pascal:

if whosemove = 'you' then ...

C:

if (strncmp(&whosemove[1], "you", 3) == 0) ...

String output in write/writeln uses printf with a precision-limited %s format specifier that prints exactly the declared length:

Pascal:

writeln('Result: ', a);

C:

printf("Result: %43.43s\n", &a[1]);

4.4.8Records

Pascal record types become C struct types, wrapped in a typedef so the struct tag and the type name are the same. Fields retain their original names and are translated to their corresponding C types.

Pascal:

type quadrec = record

ishistory: boolean;

klingnum: 0..maxdigit;

fedbasenum: 0..maxdigit;

starnum: 0..maxdigit

end;

C:

typedef struct quadrec quadrec;

struct quadrec {

bool ishistory;

unsigned char klingnum;

unsigned char fedbasenum;

unsigned char starnum;

};

Record field access uses dot notation for value types and arrow notation for pointer types, exactly as in C.

4.4.9Sets

Pascal set types are represented as p2c_settype, a typedef for unsigned char[32] (256 bits). This is sufficient to represent any set of 0..255, which covers all Pascaline set base types.

Set operations are translated to calls to runtime library functions from pas2csup.h:

Set construction: [a, b, lo..hi] is translated to a sequence of p2c_sclr (clear), p2c_sadd (add scalar element), and p2c_radd (add range) calls into a temporary _stmp2, followed by p2c_scpy to copy the result into _stmp1.

Set union (+): p2c_scpy(_stmp1, LHS) followed by p2c_suni(_stmp1, RHS).

Set intersection (*): p2c_scpy(_stmp1, LHS) followed by p2c_sint(_stmp1, RHS).

Set difference (-): p2c_scpy(_stmp1, LHS) followed by p2c_sdif(_stmp1, RHS).

Set membership (in): For constant sets, an inline bit-shift test is used. For variable sets, p2c_sisin(element, set) is called.

Set comparison (=, <=): p2c_sequ for equality, p2c_sinc for subset testing.

Set assignment (:=): p2c_scpy(destination, source).

4.4.10Pointers and dynamic allocation

Pascal pointer types (^type) become C pointer types (type*). Pointer dereference (p^) becomes C dereference (*p) or arrow notation (p->field) for record pointers. nil becomes NULL.

new(p) is translated to a malloc call with sizeof for the pointed-to type. dispose(p) is translated to free(p).

4.4.11Procedures and functions

Pascal procedures become C void functions. Pascal functions become C functions returning the appropriate type.

Value parameters are passed by value in C, as in Pascal. Var parameters are translated to pointer parameters: the formal parameter type becomes a pointer, and at call sites the actual parameter is prefixed with & (address-of). Inside the function body, var parameters are dereferenced with *.

Function return values: Pascal assigns the return value by assigning to the function name. In C, a local variable named functionname__result is declared at the top of the function body, assignments to the function name become assignments to this variable, and a return statement at the end returns it.

Pascal:

function square(x: integer): integer;

begin

square := x * x

end;

C:

long square(long x)

{

long square__result;

square__result = x * x;

return square__result;

}

4.4.12Nested procedures (procedure flattening)

C does not support nested function definitions, so p2c flattens nested Pascal procedures into top-level C functions. The naming convention is parent_child for a procedure "child" nested inside "parent".

When a nested procedure references variables from an enclosing scope (uplevel references), those variables are passed as additional pointer parameters with an __up suffix. At the call site, the address of the local variable is passed.

Pascal:

procedure prtlin(str: string80);

procedure prtkey(str: string10);

begin

{ accesses prtlin's locals }

end;

begin

prtkey(keywd[x]);

end;

C:

static void prtlin_prtkey(string10 str)

{

/* body of nested procedure */

}

void prtlin(string80 str)

{

prtlin_prtkey(keywd[x]);

}

Nested procedures that reference no uplevel variables are emitted as static functions (file-local scope). Procedures that reference uplevel variables receive additional pointer parameters to access the enclosing scope's variables.

4.4.13Control structures

Pascal control structures map directly to their C equivalents:

if/then/else becomes C if/else. Compound statements (begin..end) become C brace blocks. The condition is wrapped in parentheses as required by C syntax.

while/do becomes C while. The condition and body translate directly.

repeat/until becomes C do/while with an inverted condition. Pascal "repeat ... until condition" becomes C "do { ... } while (!(condition))" because Pascal repeats until the condition is true, while C repeats while the condition is true.

Pascal:

repeat

x := y; readln(y)

until y > 5000

C:

do {

x = y;

scanf("%ld", &y);

} while (!(y > 5000));

for loops require special treatment. The loop limit is evaluated once into a temporary variable _forlim, matching Pascal semantics (the limit expression is evaluated only at loop entry). The temporary is declared in a new block scope to allow nested for loops with their own _forlim.

Pascal:

for iter := 1 to iterations do begin

{ body }

end;

C:

{ long _forlim = 10;

for (iter = 1; iter <= _forlim; iter++) {

/* body */

}

}

For "downto" loops, the increment becomes a decrement (i--) and the comparison becomes >=.

Narrow-type for loop variables (char, boolean, small subranges) receive an overflow guard: "if (var == _forlim) break;" is inserted at the end of the loop body. This prevents undefined behavior when the loop variable would overflow its type at the final increment. For example, a for loop over all char values (0..255) with an unsigned char counter would wrap around without the guard.

C:

{ long _forlim = '7';

for (ch = '0'; ch <= _forlim; ch++) {

device[(unsigned char)ch].downtime = 0;

if (ch == _forlim) break;

}

}

case statements become C switch statements. Each case label becomes a C case. Case ranges (a..b) are expanded into individual case labels for each value. Each arm ends with a break statement. The Pascal "else" or "otherwise" clause becomes C "default:".

4.4.14With statements

Pascal "with" statements, which bring record fields into scope, are translated using a pointer temporary. A block is opened, a pointer to the record is stored in a temporary named _with1 (or _with2, etc., for nested "with" statements), and field references use arrow notation through the pointer.

Pascal:

with galaxy[i][j] do begin

ishistory := false;

klingnum := k

end

C:

{ quadrec *_with1 = &(galaxy[i][j]);

_with1->ishistory = false;

_with1->klingnum = k;

}

4.4.15Goto statements and labels

Pascal goto statements and labels are translated differently depending on whether the jump stays within the current procedure or crosses procedure boundaries.

Local gotos (within the same procedure) are translated to C goto with the label prefixed by _l. For example, Pascal "goto 99" becomes C "goto _l99;".

Non-local gotos (jumping out of a nested procedure to a label in an enclosing scope) are translated using setjmp/longjmp. At the label site, a setjmp establishes the jump target into a jmp_buf variable named _jmpenv_N (where N is the label number). At the goto site, longjmp transfers control. This is necessary because C goto cannot cross function boundaries.

Pascal:

label 4, 5, 6;

...

goto 4; { from nested procedure }

C:

jmp_buf _jmpenv_4;

jmp_buf _jmpenv_5;

jmp_buf _jmpenv_6;

...

longjmp(_jmpenv_4, 1);

...

if (setjmp(_jmpenv_4)) goto _l4;

4.4.16Write and writeln

Pascal write/writeln calls are translated to C printf/fprintf calls. The Pascal format specifiers (field width and decimal places) are converted to C printf format specifiers. writeln appends a "\n" to the format string.

Each Pascal type uses a specific format specifier:

Integers: %ld (long decimal). When a field width is specified, e.g., write(x:5), this becomes printf("%5ld", (long)(x)). When no field width is specified, the default Pascal field width of 11 is used: printf("%11ld", (long)(x)).

Reals: When both width and decimal places are given, e.g., write(r:10:2), the format is %10.2f. When only width is specified, %e (scientific notation) format is used. Variable field widths use the printf * specifier.

Characters: %c, with a cast to int: printf("%c", (int)(ch)).

Strings (packed arrays of char): %N.Ns where N is the declared array length. The argument is the address of element [1]: printf("%43.43s", &a[1]).

String literals in write statements are placed directly into the printf format string rather than as separate arguments.

Boolean values are written as the strings "true" or "false".

write to a specific file (write(f, ...)) uses fprintf(f, ...) instead of printf.

4.4.17Read and readln

Pascal read/readln calls are translated to C scanf/fscanf calls. readln includes a line-consumption sequence after reading values.

Integer reading: readln(x) becomes scanf("%ld", &x); followed by scanf("%*[^\n]"); scanf("%*c"); to consume the remainder of the line.

Character reading: read(ch) uses the p2c_readc macro, which reads a character and substitutes a space for end-of-line or end-of-file, matching Pascal semantics.

Reading from a file: read(f, x) becomes fscanf(f, ...) with the file variable as the first argument.

4.4.18File operations

Pascal text files are represented as C FILE* pointers. The standard files input and output are mapped to stdin and stdout respectively when they appear as program parameters.

reset(f) and rewrite(f) are translated to fopen calls with appropriate modes. close(f) becomes fclose(f). assign(f, name) associates a filename with a file variable.

eof(f) uses the p2c_eof macro, which performs a look-ahead read to accurately detect end-of-file. This is necessary because Pascal eof semantics differ from C feof: Pascal eof is true when no more data can be read, while C feof is only true after a read has failed.

eoln(f) uses the p2c_eoln macro, which peeks at the next character and checks for a newline (character 10) or EOF.

Typed (binary) files use the p2c_file structure from the runtime support library. The Pascal operations read/write on typed files become p2c_fread/p2c_fwrite calls.

4.4.19Arithmetic operators

Most Pascal arithmetic operators translate directly to their C equivalents: + to +, - to -, * to *.

Pascal div (integer division) translates to C / (integer division when both operands are integers).

Pascal mod translates to C %.

Pascal / (real division) always produces a real result, even when both operands are integers. In C, integer / integer produces an integer result. p2c handles this by casting at least one operand to double: (double)(x) / (double)(y).

4.4.20Relational and logical operators

Relational operators translate directly: = to ==, <> to !=, < to <, > to >, <= to <=, >= to >=.

Logical operators translate as: and to &&, or to ||, not to !. Note that Pascal and/or do not short-circuit (both operands are always evaluated), while C && and || do short-circuit. This semantic difference is accepted as a pragmatic compromise; in practice, most Pascal programs behave correctly with short-circuit evaluation.

4.4.21Standard functions and procedures

Pascal standard functions are translated to their C equivalents:

abs(x): abs(x) for integers, fabs(x) for reals.

sqr(x): expanded inline as x*x (or as a multiplication expression).

sqrt(x), sin(x), cos(x), exp(x), arctan(x): sqrt, sin, cos, exp, atan from math.h.

ln(x): log(x) from math.h.

ord(x): cast to long, e.g., (long)(x).

chr(x): cast to char, e.g., (char)(x).

succ(x): x + 1 (inline expansion).

pred(x): x - 1 (inline expansion).

odd(x): x % 2 (inline expansion).

trunc(x): cast to long, (long)(x).

round(x): lround(x) from math.h.

4.4.22Comments

Pascal comments are preserved in the C output. Both comment styles ({ } and (* *)) are converted to C /* */ comments. The text content of the comment is preserved as-is.

Star-decorated comment blocks (such as comment headers surrounded by asterisks) are translated with the Pascal delimiters converted to their C equivalents. For example, a Pascal comment beginning with "{***" is emitted as "/***" and the closing "***}" becomes "***/".

Comments are associated with the nearest following token and are emitted at the corresponding point in the C output. Comments that appear at the end of a Pascal line are placed as trailing comments on the corresponding C statement.

4.4.23Type definitions

Pascal type definitions are translated to C typedef declarations, which appear in the global scope before any function definitions. Named record types produce both a typedef and a struct definition. Named array types produce typedef with the array dimensions. Named scalar types produce typedef to the appropriate C base type.

Pascal:

type string10 = packed array [1..10] of char;

string80 = packed array [1..80] of char;

C:

typedef char string10[12];

typedef char string80[82];

4.5Limitations and known issues

p2c has been tested on a limited set of programs: the sample programs included with Pascal-P6 (hello, prime, qsort, roman, match, fbench, drystone, startrek, pascals, basics), the BASIC interpreter, and the ISO 7185 acceptance test (iso7185pat). All of these produce correct output after translation and C compilation.

The following limitations are known:

1. Module features not supported: The Pascaline "uses" and "joins" statements for modular programming are not supported. p2c can only translate single-file Pascal programs.

2. Short-circuit evaluation: Pascal and/or operators evaluate both operands, while C && and || short-circuit. Programs that depend on both operands being evaluated (e.g., for side effects) may behave differently in the C translation.

3. Identifier recycle warnings: During translation, p2c may report identifier recycle balance warnings. These are cosmetic and do not affect the correctness of the output.

4. The generated C code requires the pas2csup runtime library (pas2csup.h and pas2csup.c) for set operations and typed file I/O. These files must be available when compiling the generated C code.

5. The generated C code uses GCC statement expressions ({ }) in some helper macros (p2c_eof, p2c_eoln, p2c_readc). This is a GCC extension also supported by clang, but may not work with all C compilers.

6. Floating-point arithmetic may produce slightly different results between the Pascal interpreter and the C native code due to differences in intermediate precision and rounding.

5pc: The Pascal-P6 compiler integrator

5.1Overview

pc is a compiler shell that manages the entire compile-assemble-link pipeline for Pascal programs. Rather than invoking the compiler (pcom), code generator (pgen), assembler, and linker individually, pc handles the full process in a single command. It examines the dependency tree of a program (through uses and joins statements), checks file modification times, and rebuilds only those modules that have changed, similar to the Unix "make" utility.

The key difference between pc and make is that pc automatically determines which libraries and modules are needed by parsing the source code directly. There is no need to write or maintain a Makefile. pc builds a complete dependency tree, identifies which files are out of date, and performs only the necessary compilation and linking steps.

pc supports multiple compilation targets: native executables (the default, using pgen), and interpreted modes (pint, pmach, cmach) for use with the P-machine interpreters. It also supports a package mode for creating portable binaries.

5.2Command format

The basic command line format is:

$ pc [options] <file> [options]

where <file> is the Pascal source file to compile. The .pas extension is added automatically if not present. Options may appear before or after the filename. For example:

$ pc myprogram

$ pc -list myprogram.pas

$ pc myprogram -v -t

Options are specified with a dash prefix. Most options can be negated by adding an "n" prefix after the dash. For example, -list enables source listing and -nlist disables it. Options that have both a short form and a long form can be specified with either.

5.3Operation

When pc is invoked, it proceeds through the following stages:

1. Instruction file loading. pc searches for instruction files (pc.ins) in the program directory, the user home directory, and the current directory, and loads any that are found. It also loads any instruction file with the same base name as the target program (e.g., myprogram.ins). These files can set options, declare module paths, and exclude directories from recompilation.

2. Command line parsing. pc parses the command line for options and the target filename.

3. Dependency analysis. pc parses the target source file and recursively follows all uses and joins statements to build a complete dependency tree. Each module referenced by the program is located using the module path.

4. Registration. pc examines each file in the dependency tree and determines whether it needs to be rebuilt. A file needs rebuilding if its source (.pas) is newer than its compiled output (.p6, .o), or if the -rebuild option was specified. Files in excluded directories are never rebuilt.

5. Compilation. For each file that needs rebuilding, pc invokes the compiler (pcom) to produce intermediate code (.p6), then the code generator (pgen) to produce assembly (.s), then gcc to produce object code (.o). In interpreter modes (pint, pmach, cmach), only the compilation to .p6 is performed.

6. Linking. pc combines all outputs into the final result. For native executables, gcc links the .o files together with the runtime system. For interpreter modes, the .p6 files are concatenated. For package mode, an additional binary encoding step is performed.

5.4pc options

Options specific to pc control its behavior during compilation. These options are not passed through to the compiler.

5.4.1Option descriptions

v+/- verbose+/- Enable/disable verbose output.

When enabled (the default), pc prints progress messages showing each compilation step being performed. Disable with -nv or -nverbose for quiet operation.

t+/- tree+/- List/don't list the dependency tree.

Prints the complete dependency tree that pc has built by following uses and joins statements. Useful for understanding which modules are included in a build and their relationships.

a+/- action+/- List/don't list the actions being performed.

Prints each command that pc executes (compiler, assembler, linker invocations). Can be combined with -dry to preview what would be done without actually doing it.

d+/- dry+/- Enable/disable dry run mode.

When enabled, pc goes through all the analysis steps but does not actually execute any commands. Use with -action to see what commands would be run. This is useful for previewing large builds before committing to them.

r+/- rebuild+/- Force/don't force rebuild of all files.

When enabled, pc ignores file modification times and rebuilds every file in the dependency tree. This is equivalent to a clean build.

5.5Run configuration options

These options select the compilation target. Only one should be active at a time. If none is specified, pc defaults to generating a native executable (pgen mode).

pgen+/- Compile for native executable (default).

Generates a native executable by running the full pipeline: pcom (compiler), pgen (code generator), gcc (assembler and linker). This is the default mode.

pint+/- Compile for the pint interpreter.

Compiles only to .p6 intermediate code, suitable for execution by pint. The .p6 files for all modules are concatenated into a single file.

pmach+/- Compile for the pmach interpreter.

Compiles to .p6 intermediate code, then uses pint --machdeck to create a .p6o binary for execution by pmach.

cmach+/- Compile for the cmach interpreter.

Same as pmach, producing a .p6o binary suitable for execution by cmach.

package+/- Compile for package mode.

Produces a self-contained packaged binary. After creating the .p6o file, pc runs genobj to embed it in a C array, then compiles and links with gcc to create a standalone executable that carries the P-machine code within it.

5.6Graphical and symbol options

ktw+/- keepterminalwindow+/- Keep/don't keep the terminal window open for graphical applications.

When enabled, the terminal window remains open after a graphical application exits. This is useful for seeing any text output produced by a graphical program.

dt+/- defaultterminal+/- Default to terminal mode.

Forces the application to use terminal (text) mode I/O.

dg+/- defaultgraphical+/- Default to graphical mode.

Forces the application to use graphical mode I/O.

sc+/- symcoff+/- Generate/don't generate COFF symbols in the binary.

When enabled, generates COFF (Common Object File Format) debugging symbols in the output binary.

5.7Module path option

mp=<path> modulepath=<path> Specify the module search path.

Sets or appends to the module search path. Multiple paths are separated by colons. Modules referenced by uses and joins statements are located by searching these paths in order. The module path can also be set via the MODULEPATH environment variable or via a modulepath command in an instruction file.

Example:

$ pc -mp="../libs:../source" myprogram

5.8Compiler passthrough options

The following options are passed through to the Pascal compiler (pcom). They control compiler behavior such as runtime checking, listing output, and debugging features. Each option can be negated with an "n" prefix (e.g., -nlist). For full descriptions of what each option does, see the compiler options section.

prtlab+/- See the compiler options.

lstcod+/- See the compiler options.

chk+/- See the compiler options.

prtlabdef+/- See the compiler options.

sourceset+/- See the compiler options.

varblk+/- See the compiler options.

experror+/- See the compiler options.

echoline+/- See the compiler options.

l+/- list+/- See the compiler options.

breakheap+/- See the compiler options.

recycle+/- See the compiler options.

o+/- chkoverflo+/- See the compiler options.

chkreuse+/- See the compiler options.

chkundef+/- See the compiler options.

reference+/- See the compiler options.

s+/- iso7185+/- See the compiler options.

prttables+/- See the compiler options.

undestag+/- See the compiler options.

chkvar+/- See the compiler options.

debug+/- See the compiler options.

debugflt+/- See the compiler options.

f+/- debugsrc+/- See the compiler options.

prtlex+/- See the compiler options.

prtdisplay+/- See the compiler options.

lineinfo+/- See the compiler options.

mrkasslin+/- See the compiler options.

5.9Instruction files

Instruction files (.ins) allow configuration to be stored alongside programs rather than specified on the command line each time. They contain commands that set options, declare module paths, exclude directories from recompilation, and define packaged libraries.

5.9.1Instruction file search order

pc searches for instruction files in the following locations, in order. All files found are loaded and their commands are cumulative:

1. pc.ins in the directory where the pc executable itself resides (the program path).

2. pc.ins in the user's home directory (if different from the program path).

3. pc.ins in the current working directory (if different from both of the above).

4. <name>.ins alongside the target Pascal source file, where <name> matches the base name of the source file. For example, if compiling utils/p2c.pas, pc also looks for utils/p2c.ins.

5.9.2Instruction file format

Each line in an instruction file is either a command, a comment, or blank. Comments begin with "!" and extend to the end of the line. Commands may also have trailing comments after the command arguments.

! This is a comment

modulepath "../libs"

exclude "../libs" ! protect library from recompilation

5.9.3Instruction file commands

modulepath <path> Set the module search path.

Specifies one or more directories (colon-separated) where pc should search for module source files referenced by uses and joins statements. Multiple modulepath commands accumulate; each new path is appended to the existing path with a colon separator. Paths may be quoted if they contain spaces.

exclude <path> [<path>]... Exclude paths from recompilation.

Files in excluded directories are never rebuilt, even if their source is newer than the compiled output. This is used to protect library directories from unnecessary recompilation. Multiple paths may be listed on a single line. The standard pc.ins file typically excludes the libs directory.

package <name> = <file> [<file>]... Declare a packaged library.

Declares a named package consisting of one or more component files. When a program references any of the component files, the entire package is linked as a unit. This is used for pre-compiled library archives.

standard / nstandard Enable/disable ISO 7185 standard mode.

Equivalent to the -iso7185 / -niso7185 command line option.

overflow / noverflow Enable/disable overflow checking.

Equivalent to the -chkoverflo / -nchkoverflo command line option.

refer / nrefer Enable/disable reference checking.

Equivalent to the -reference / -nreference command line option.

keepterminalwindow / nkeepterminalwindow Keep/don't keep terminal window for graphical applications.

Equivalent to the -keepterminalwindow / -nkeepterminalwindow command line option.

symcoff / nosymcoff Generate/don't generate COFF symbols.

Equivalent to the -symcoff / -nsymcoff command line option.

5.9.4Example instruction file

The standard pc.ins file shipped with Pascal-P6 contains:

!

! Declare the main library and protect it from recompiles

!

modulepath "../libs"

exclude "../libs"

This tells pc to search the libs directory for module source files, and to never attempt to recompile files in that directory. Program-specific instruction files can add additional module paths; for example, p2c.ins adds paths for the little-endian and 64-bit machine parameter block source directories.

5.10File types

pc manages several file types during the compilation process:

.pas - Pascal source file. The input to the compiler.

.p6 - P6 intermediate code. Produced by the compiler (pcom). This is a text representation of the P-machine instructions.

.p6o - P-machine binary. Produced from .p6 by pint --machdeck. Used in pmach, cmach, and package modes.

.s - Assembly source. Produced by the code generator (pgen) from .p6 intermediate code.

.o - Object file. Produced by gcc from .s assembly source.

.a - Archive file. Pre-compiled library archive. Not produced by pc, but can be referenced in the link step.

.ins - Instruction file. Configuration file for pc.

(no extension) - Executable binary. The final output in pgen mode.

5.11Examples

Compile a program to a native executable (default pgen mode):

$ bin/pc myprogram

Compile with verbose output, showing the dependency tree and actions:

$ bin/pc -v -t -a myprogram

Preview what would be done without actually doing it (dry run):

$ bin/pc -a -d myprogram

Force a complete rebuild of all dependencies:

$ bin/pc -r myprogram

Compile for the pint interpreter:

$ bin/pc -pint myprogram

Compile with ISO 7185 standard mode and source listing enabled:

$ bin/pc -s -list myprogram

Compile with a custom module path:

$ bin/pc -mp="../libs:../source" myprogram

6Pascal-P6 debugger mode

Debug mode in Pascal-P6 gives you the ability to step through, set break points, dump variable values and other facilities to enable debugging of issues with Pascaline code, both at the machine level and also at source level.

It is possible to debug Pascal-P6 programs at the target machine code level. But pint includes a portable debugger that works the same and provides the same capabilities on any machine. It also provides capabilities that are difficult or impossible to do on a real machine, but easy to provide on a virtual machine. The price for this is run speed.

There are two levels you can debug a Pascal-P6 program at, the interpreter (byte code) level using pint and machine code level using gdb. With optimizing compilers, parts of the code can be reordered, changed or even completely removed. It is difficult, and sometimes impossible to track source lines positions in the code. In addition, gdb was not designed for the Pascaline language, so the ability to print values at machine code time can be poor.

For this reason I believe you will find debugging at the interpreter level a valuable tool. Using debug mode, you can:

• Trace through the code at source level.

• Print the contents of any variable in Pascal formatted form.

• Print what blocks are currently running.

• Watch changes in variables.

• Place breakpoints at source lines.

• Run profiles on the code.

And many other operations.

Debug mode is invoked in two different ways. You can enter debug mode before the program is run with the $w/$debug option, or you can enter debug mode only after a fault occurs with the $a/debugflt option.

The following options apply to debug mode:

Note that these options are invoked by ‘$’ in the source code, but ‘--’ (double dash) or ‘-’ (single dash) on the command line.

The w/debug option is used to debug the program always, starting from the first executed instruction. The $a/$debugflt option is used to enter the debugger mode only after a fault is encountered. The w/debug option is primary and will override $a/$debugflt.

The $f/$debugsrc option modifies the behavior of the w/debug or $a/$debugflt flags. It performs two actions:

1. The program is stopped at the first statement in the program block.

2. Program status, the location report after stepping, breakpoints, etc., are reported in source code terms.

6.1Commands

The commands possible in debug mode are:

Commands:

6.2Sample program for debug

The following program will be used for reference in the text. The sample run is here:

$ p6 test

Compiling test...

P6 Pascal compiler vs. 0.2.x

Pascal-P6 complies with the requirements of Pascaline version 0.4

and the following annexes: A,B,C,E.

1 -8 program test(output);

2 -8

3 -8 var a: array 10 of integer;

4 -8 i: integer;

5 -8

6 -8 function y(add: integer): integer;

7 -16

8 -16 var i: integer;

9 -24

10 -24 function q(x: integer): integer;

11 -24

12 -24 var z: integer;

13 -32

14 -32 begin

15 5

16 5 z := 42;

17 7

18 7 result x+i

19 8

20 8 end;

21 12

22 12 begin

23 12

24 12 i := 10;

25 14

26 14 result q(add)

27 15

28 15 end;

29 18

30 18 begin

31 18

32 18 for i := 1 to 10 do

33 28 a[i] := y(i);

34 46 for i := 10 downto 1 do writeln('Value: ', a[i]);

35 83

36 83 end.

Errors in program: 0

P6 Pascal interpreter vs. 0.2.x

Assembling/loading program

Running program

Value: 20

Value: 19

Value: 18

Value: 17

Value: 16

Value: 15

Value: 14

Value: 13

Value: 12

Value: 11

program complete

6.3Debug mode invocation

You invoke debug mode with a w/debug (debug always) or a/debugflt (debug on fault) option specified in the source or command line. The modifier for debug mode is f/debugsrc (debug source level).

To invoke the debug mode with source debugging on, we add the option comment “${w,f}” to the top of the program:

{$w,f}

program test(output);

...

Or by specifying:

$ p6 -–debug -–debugsrc test

As the command line.

As run, it executes:

$ p6 --list- --debug --debugsrc test

Compiling test...

P6 Pascal compiler vs. 0.2.x

Pascal-P6 complies with the requirements of Pascaline version 0.4

and the following annexes: A,B,C,E.

Errors in program: 0

P6 Pascal interpreter vs. 0.2.x

Assembling/loading program

Running program

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug>

Note that it is stopped at the first line of the program block.

If the program is debugged with P-code machine mode, the run is a bit different:

$ p6 --list- --debug test

Compiling test...

P6 Pascal compiler vs. 0.2.x

Pascal-P6 complies with the requirements of Pascaline version 0.4

and the following annexes: A,B,C,E.

Errors in program: 0

P6 Pascal interpreter vs. 0.2.x

Assembling/loading program

Running program

P6 debug mode

pc: 000000 sp: 1000000 mp: 1000000 np: FFFFFFFFFFFFFFFF

* 000000: 14 lnp* 00000000000005AC

debug>

In this case, the execution starts at location 0. The location printout here is in machine mode, which shows the registers pc, sp, mp and np.

6.4Debug mode expressions

Where a debug mode command takes a value, it can usually take an expression. Expressions follow (loosely) Pascal expression rules, from lowest to highest priority:

a = b, a <> b, a <= b, a >= b, a < b, a > b a in b

a + b, a – b, a or b, a xor b

a * b, a / b, a div b, a and b

not a, (a), [set]

Operands can be integer, real, string or set. Constants are:

Variables are any standard Pascaline variable reference. Qualident notation can be used.

test.y.i

Refers to the identifier i in the function y of the module test. Unlike Pascaline, qualidents can be used to refer to any given nested symbol.

Qualidents need only be used for symbols that are not local to the current execution context. So while executing inside function y:

i

y.i

and

test.y.i

All refer to the local variable i of the function y in module test.

All of the Pascaline variable operators function in debug:

The debugger can also read and write a set of special variables in the simulator:

Note that setting these special variables can cause the P-Machine to malfunction.

6.5Executing multiple commands

Any number of commands can be executed on a single command line by separating the commands with “;” (semicolon):

debug> p 1;p 2

1

2

6.6Breaking runs

The break key, usually Control-C, can be used to break out of any code run, listing run, or other continuous print in debug mode. If the running program is broken out of, the printout is:

*** Program stopped by user break

Note that Control-C also qualifies as a fault, so specifying the option $a/$debugflt will cause debug mode to be entered after the program is broken. If no debug mode is active, the program run will simply halt and pint will exit.

6.7Handling overloaded routines

At this writing, debug mode cannot deal with overloaded routines. It truncates the type information off of symbols. If an overloaded group of routines is present, debug mode will only refer to the first routine in the group.

6.8Debug mode Command descriptions

h or help Print help menu

The help or h command simply prints the command menu:

debug> help

Commands:

h|help Help (this command)

l [m] [s[ e|:l] List source lines

lc [m] [s[ e|:l] List source and machine lines coordinated

li [s[ e|:l] List machine instructions

p v Print expression

d[b|l][8|16|32|64] [s[ e|:l] Dump memory

e a v[ v]... Enter byte values to memory address

st d v Set program variable

pg Print all globals

pl [n] print locals for current/number of enclosing blocks

pp [n] print parameters for current/number of

enclosing blocks

ds Dump storage parameters

dd [n] Dump display frames

df [n] Dump frames formatted (call trace)

dst [n] Dump stack words

b [m] a Place breakpoint at source line

number/routine

tp [m] a Place tracepoint at source line

number/routine

bi a Place breakpoint at instruction

tpi a Place tracepoint at instruction

c [a] Clear breakpoint/all breakpoints

lb List active breakpoints

w a Watch variable

lw List watch table

cw [n] Clear watch table entry/all watch entries

lia List instruction analyzer buffer

lsa List source analyzer buffer

s [n] Step next source line execution

ss [n] Step next source line execution silently

si [n] Step instructions

sis [n] Step instructions silently

so [n] Step over next source line execution

sso [n] Step over next source line execution silently

sio [n] Step over instructions

siso [n] Step over instructions silently

ret Return from subroutine

hs Report heap space

ti Turn instruction tracing on

nti Turn instruction tracing off

tr Turn system routine tracing on

ntr Turn system routine tracing off

ts Turn source line tracing on

nts Turn source line tracing off

spf Turn on source level profiling

nspf Turn off source level profiling

an Turn on analyzer mode

nan Turn off analyzer mode

r Run program from current pc

ps Print current registers and instruction

q Quit interpreter

! Anywhere in line starts a comment

l [m] [s[ e|:l] List source lines

Lists source lines in the program:

debug> l

1: 1: program test(output);

2: 0:

3: 0: var a: array 10 of integer;

4: 0: i: integer;

5: 0:

6: 0: function y(add: integer): integer;

7: 0:

8: 0: var i: integer;

9: 0:

10: 0: function q(x: integer): integer;

The columns to the left:

2: 1: b* program test(output);

Have the following meaning. The first column is the source line number. The second number is the profile number, it is a count of the number of times that line has been executed. Next, if the line is marked with a “b”, it means there is a breakpoint on the line. If there is a “t”, it means there is a tracepoint on the line⁵. Next, if the column contains a “*” it means that this is the currently executing line.

If the l command is followed by a module, then the source is printed from that module. Thus:

l test

is the same command while executing in test as:

l

Even if there are not multiple modules in the current program, this can be useful:

Running program

P6 debug mode

pc: 000000 sp: 1000000 mp: 1000000 np: FFFFFFFFFFFFFFFF

* 000000: 14 lnp* 0000000000000574

debug> l

*** Module must be active

debug> l test

1: 0: program test(output);

2: 0:

3: 0: var a: array 10 of integer;

4: 0: i: integer;

5: 0:

6: 0: function y(add: integer): integer;

7: 0:

8: 0: var i: integer;

9: 0:

10: 0: function q(x: integer): integer;

Recall when we started the program in machine mode, it began in system code, outside of any module. But we simply specified a particular module, test, and then we can list it’s source.

The list command can specify a starting source line to list:

debug> l 20

20: 0: begin

21: 0:

22: 0: for i := 1 to 10 do

23: 0: a[i] := y(i);

24: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

25: 0:

26: 0: end.

You can also specify an end line:

debug> l 20 22

20: 0: begin

21: 0:

22: 0: for i := 1 to 10 do

Or alternatively, you can use a length, or number of lines to list:

debug> l 20:4

20: 0: begin

21: 0:

22: 0: for i := 1 to 10 do

23: 0: a[i] := y(i);

Note that the default number of lines to list, if not specified, is 10.

Note that lines outside of a module cannot be listed.

lc [s[ e|:l] List source and machine lines coordinated

The lc command combines the l (list source) and li (list instructions) commands. For each source line printed, the machine code generated by that source line is also printed:

debug> lc 6:10

6: 0: function y(add: integer): integer;

00008E: AE mrkl* 0000000000000006

000097: AE mrkl* 0000000000000007

7: 0:

000097: AE mrkl* 0000000000000007

0000A0: AE mrkl* 0000000000000008

8: 0: var i: integer;

0000A0: AE mrkl* 0000000000000008

0000A9: AE mrkl* 0000000000000009

9: 0:

0000A9: AE mrkl* 0000000000000009

0000B2: AE mrkl* 000000000000000A

10: 0: function q(x: integer): integer;

0000B2: AE mrkl* 000000000000000A

0000BB: AE mrkl* 000000000000000B

11: 0:

0000BB: AE mrkl* 000000000000000B

0000C4: AE mrkl* 000000000000000C

12: 0: var z: integer;

0000C4: AE mrkl* 000000000000000C

0000CD: AE mrkl* 000000000000000D

13: 0:

0000CD: AE mrkl* 000000000000000D

0000D6: AE mrkl* 000000000000000E

14: 0: begin

0000D6: AE mrkl* 000000000000000E

0000DF: AE mrkl* 000000000000000E

0000E8: 0B mst 02,FFFFFFFFFFFFFFE0,FFFFFFFFFFFFFFF0

0000FA: AE mrkl* 000000000000000F

15: 0:

0000FA: AE mrkl* 000000000000000F

000103: AE mrkl* 0000000000000010

This can be very useful if you are interested in what P-machine code goes with what source line.

The numbers used with the command are source line numbers.

Note that the default number of lines to list, if not specified, is 10.

Note that lines outside of a module cannot be listed.

li [s[ e|:l] List machine instructions

The list instructions command is the same as source list, but lists machine instructions:

debug> li

Addr Op Ins P Q

----------------------------------

* 000000: 14 lnp* 00000000000004E0

000009: 15 cal 000000000000004E

000012: 3A stp*

000013: F2 eext*

000014: F2 eext*

000015: F2 eext*

000016: F2 eext*

000017: F2 eext*

000018: F2 eext*

000019: F2 eext*

Note that you cannot specify which module to list from.

Just as for list source, you can specify start, start and end, or start and length:

debug> li 0 10

Addr Op Ins P Q

----------------------------------

* 000000: 14 lnp* 00000000000004E0

000009: 15 cal 000000000000004E

The numbers used for the command are the addresses in program store. The length, if specified, is the number of instructions to list after the starting address.

The meaning of the fields in the instruction listing are:

1. b,t,* Gives the break, trace, and current execution status of the line.

2. Addr Address of the instruction.

3. Op Opcode (byte code) of the instruction.

4. Ins Memnonic of the instruction.

5. P P or routine nesting index.

6. Q 0 or more operands of the instruction.

Note that the starting list address must be a valid instruction address. If not, the instruction listing will be invalid.

p v Print expression

Prints a Pascaline/debug mode expression.

The expression can be any of the Pascaline-like expressions shown in “Debug mode expressions”. Examples (at the source location line 15):

14: 1:

15: 1: b* result add+i

16: 0:

debug> p i

10

debug> p test.i

1

debug> p i+42

52

debug> p a

array 11, 12, 13, 14, 15, 16, 17, 18, 19, 20 end

Note in the function y(), there is a I that is local, and another that is global that we access via test.i.

The array a that is specified is printed in total. Any structured type that is printed is printed in whole with the exception of files. An example complex structure is:

var r: record a: (one, two, three);

b: integer;

c: array 5 of integer

end;

debug> p r

record

two(2),

42,

array -9, -8, -7, -6, -5 end

end

The p command prints structured values using the same syntax as the Pascaline “fixed” declaration.

The p command also obeys Pascal-P6 radix conversions:

debug> p 42$

2A

debug> p 42&

52

debug> p 42%

101010

debug> p $42$

42

Note that “$42$” means convert hex 42 into hex 42, IE., no-op.

If the value printed is undefined, a “*” will be printed:

debug> b test 23

debug> r

=== break ===

22: 10: a[i] := y(i);

23: 1: b* for i := 10 downto 1 do writeln('Value: ', a[i]);

24: 0:

debug> p i

*

We broke in after the for loop. Why is I undefined after the for loop? Its actually in the ISO 7185 specification: the loop variable on a for loop is specified as undefined after the for loop.

Note that when the print command prints an encoded value such as an enumerated type or character, it prints the decimal value in parentheses:

var c: char;

debug> p c

'c'(99)

d[b|l][8|16|32|64] [s[ e|:l] Dump memory

Dumps byte machine memory.

debug> d 0:50

000000: 14 E0 04 00 00 00 00 00 00 15 4E 00 00 00 00 00 ..........N.....

000010: 00 00 3A F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 ..:.............

000020: F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 F2 ................

000030: F2 F2

Note that the ASCII characters equivalent to the bytes are printed to the right. If the character is unprintable, defined as any character less than space or greater then 126, it is printed as ‘.’ (period).

Note also that dumping memory that is undefined (never has it’s value set) will be printed as U’s in both the hex and ASCII displays.

As with source line lists, you can specify a start address, a start and end address, or a start address and a length.

Note that the default length, if not specified, is 256 bytes.

The default dump size is byte or 8 bits. The command d8 is an alias for byte dump. In addition, the size of the dump words can be specified as 8, 16, 32, or 64 bits. The endian mode can also be specified, as b or big endian, and l or little endian. Big endian places the bytes of word in memory order, but little endian reverses them.

debug> d16 0 20

000000: E014 0004 0000 0000 1500 004E 0000 0000 .. .. .. .. .. .N .. ..

000010: 0000 F23A F2F2

Note the words are grouped in both the hex and ASCII sections.

Note that the bytes in the 16 bit words are reversed, since the dump mode is little endian by default.

debug> db16 0 20

000000: 14E0 0400 0000 0000 0015 4E00 0000 0000 .. .. .. .. .. .. .. ..

000010: 0000 3AF2 F2F2

In this dump the bytes are in order, since it is big endian.

The dump endian mode has nothing to do with the machine endian mode. The bytes or words are dumped in address order regardless of the machine endian mode. Thus it is up to you to determine what endian mode the machine is using, and choose a dump format accordingly.

debug> d64 0 20

000000: 000000000004E014 00000000004E1500 ........ .....N..

000010: F2F2F2F2F23A0000

This is a 64 bit little endian dump.

e a v[ v]... Enter byte values to memory address

Enters values to byte machine memory. The first value is the address to enter to. This is followed by 1 to n values to be placed into memory in turn:

debug> d 0:20

000000: 14 98 02 00 00 15 0B 00 00 00 3A AE 01 00 00 00

000010: AE 02 00 00

debug> e 0 1 2 3

debug> d 0:20

000000: 01 02 03 00 00 15 0B 00 00 00 3A AE 01 00 00 00

000010: AE 02 00 00

Note that there is no restriction on where you enter bytes into memory. You can just as easily rewrite the program code in memory. Enter is a sharp tool.

st d v Set program variable

Sets a variable in the current context. The first parameter is the variable to set. The second is the value to set the variable to. The variable to set can be any variable reference:

=== break ===

22: 10: a[i] := y(i);

23: 1: b* for i := 10 downto 1 do writeln('Value: ', a[i]);

24: 0:

debug> p a

array 11, 12, 13, 14, 15, 16, 17, 18, 19, 20 end

debug> st a[3] 42

debug> p a

array 11, 12, 42, 14, 15, 16, 17, 18, 19, 20 end

Set program variable is fairly flexible:

var s: packed array 10 of char;

debug> p s

'hi there '

debug> st s 'lo there '

debug> p s

'lo there '

var st: set of char;

debug> p st

['a'..'d','z']

debug> st st ['0'..'9']

debug> p st

['0'..'9']

Note that special variables (variables starting with ‘@’) can also be set. See “6.4 Debug mode expressions”

pg Print all globals

Prints the globals for the current program.

debug> pg

Globals:

i *

a array 11, 12, 13, 14, 15, 16, 17, 18, 19, 20 end

pl [n] print locals for current/number of enclosing blocks

Prints the locals for the current block or enclosing blocks:

debug> b q

debug> r

=== break ===

15: 1:

16: 1: b* z := 42;

17: 0:

debug> s

17: 1:

18: 1: * result x+i

19: 0:

debug> pl

Locals for block: q@f_i

z 42

If a number of blocks argument appears, then that number of enclosing blocks are printed:

debug> pl 2

Locals for block: q@f_i

z 42

Locals for block: y@f_i

i 10

Parameters are not considered part of the locals.

pp [n] print parameters for current/number of enclosing blocks

Prints parameters for the current or surrounding blocks:

debug> pp

Parameters for block: q@f_i

x 1

debug> pp 2

Parameters for block: q@f_i

x 1

Parameters for block: y@f_i

add 1

ds Dump storage parameters

ds prints the storage areas of the byte machine:

debug> ds

Storage areas occupied

Program 000000-0004C3 (1220)

Constants 0004C4-0004FB (56)

Globals 0004FC-0005AB (176)

Stack/Heap 0005AC-FFFFFF (16775764)

The program area is where the bytecode program lives. Constants is the location of the constants deck. Globals contains all of the program globals. Finally, the stack/heap contains the rest of the byte machine space, with the heap growing up, and the stack growing down.

dd [n] Dump display frames

Dumps the contents of all active display frames. This is mainly for debugging the interpreter. It shows all of the active stack marks and their contents.

debug> b q

debug> r

=== break ===

15: 1:

16: 1: b* z := 42;

17: 0:

debug> dd

Mark @FFFF28

ep: 00FFFF30: 00FFFF58

sb: 00FFFF38: 00FFFF08

et: 00FFFF40: 00FFFEF8

Mark @FFFF78

ep: 00FFFF80: 00FFFF98

sb: 00FFFF88: 00FFFF60

et: 00FFFF90: 00FFFF58

Mark @FFFFD0

ep: 00FFFFD8: 00000005

sb: 00FFFFE0: 00FFFFB8

et: 00FFFFE8: 00FFFF98

The number, if present, will specify how many stack frames to dump. The default is to dump all active stack frames.

df [n] Dump frames formatted (call trace)

The df or dump formatted command is like the dd command, but tells you what block was executing by name, what address within the block it was executing, and what the start and end address of the block of local variables is for that frame.

debug> b q

debug> r

=== break ===

15: 1:

16: 1: b* z := 42;

17: 0:

debug> df

q@f_i: addr: 0000010C locals/stack: 00FFFEF8-00FFFF10 (24)

15: 1:

16: 1: b* z := 42;

17: 0:

y@f_i: addr: 000001EB locals/stack: 00FFFF58-00FFFF60 (8)

25: 1:

26: 1: result q(add)

27: 0:

test: addr: 00000308 locals/stack: 00FFFF98-00FFFFB8 (32)

32: 2: for i := 1 to 10 do

33: 1: a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

Note that the program/module frame has very no locals, since its variables are global.

dst Dump stack words

Dump stack words.

debug> lc 34:1

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

000366: AE mrkl* 0000000000000022

00036F: 7B ldci 000000000000000A

000378: 02 stri 01,FFFFFFFFFFFFFFF0

000382: 7B ldci 0000000000000001

00038B: 02 stri 01,FFFFFFFFFFFFFFE8

000395: 00 lodi 01,FFFFFFFFFFFFFFF0

00039F: 03 sroi 00000000000005A4

0003A8: AE mrkl* 0000000000000022

0003B1: 01 ldoi 00000000000005A4

0003BA: 00 lodi 01,FFFFFFFFFFFFFFE8

0003C4: 95 geqi

0003C5: 18 fjp 0000000000000493

0003CE: 38 lca 00000000000004D4

0003D7: 05 lao 00000000000004FE

0003E0: 76 swp 0000000000000008

0003E9: 7B ldci 0000000000000007

0003F2: 76 swp 0000000000000008

0003FB: 7B ldci 0000000000000007

000404: 0F csp 0000000000000006

000406: 05 lao 0000000000000554

00040F: 01 ldoi 00000000000005A4

000418: 1A chki 00000000000004C4

000421: 39 deci 0000000000000001

00042A: 10 ixa 0000000000000008

000433: 09 indi 0000000000000000

00043C: 7B ldci 000000000000000B

000445: 0F csp 0000000000000008

000447: 0F csp 0000000000000005

000449: 75 dmp 0000000000000008

000452: 01 ldoi 00000000000005A4

00045B: 00 lodi 01,FFFFFFFFFFFFFFE8

000465: 89 equi

000466: 77 tjp 0000000000000493

00046F: 01 ldoi 00000000000005A4

000478: 39 deci 0000000000000001

000481: 03 sroi 00000000000005A4

00048A: 17 ujp 00000000000003A8

000493: AE mrkl* 0000000000000022

00049C: 05 lao 00000000000005A4

0004A5: BD inv

0004A6: AE mrkl* 0000000000000023

debug> b $445

*** Invalid source line

debug> bi $445

debug> r

Value:

=== break ===

33: 21: a[i] := y(i);

34: 2: b* for i := 10 downto 1 do writeln('Value: ', a[i]);

35: 0:

debug> dst

00FFFFA0: 000000000000000B (11)

00FFFFA8: 0000000000000014 (20)

00FFFFB0: 00000000000004FE (1278)

00FFFFB8: 0000000000000001 (1)

00FFFFC0: 000000000000000A (10)

00FFFFC8: 0000000000FFFFD0 (16777168)

00FFFFD0: 0000000001000000 (16777216)

00FFFFD8: 0000000000000005 (5)

00FFFFE0: 0000000000FFFFB8 (16777144)

00FFFFE8: 0000000000FFFF98 (16777112)

dst dumps either the specified number of words on the P-machine stack or the default 10 words. The first field is the address of the stack word, the second is the contents of the word in hex, then the contents in decimal.

dst is a low level facility. Here we have stopped the execution before a csp instruction that makes a wri system call, with the field width, the integer to print, then the address of the file variable.

The word size dumped is the word size of the machine. There is no intellgence to a stack dump, it does not know what the types are on the stack or how big the stack is. It just dumps the number f words you tell it to.

b [m] l|r Place breakpoint at source line number/routine

The b or break command places a source line or routine breakpoint. If the program is run, it will stop at that breakpoint.

debug> b 33

debug> r

=== break ===

32: 2: for i := 1 to 10 do

33: 1: b* a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

When the break occurs, the line the execution stopped on is printed, along with the line above and the line below, if they are available (the currently executing line could be at the start or end of the program).

There is a limit of 10 breakpoints outstanding. The module containing the source line can optionally be specified, otherwise the default is the current module executing.

Note that the breakpoint command will skip any source line markers, and will skip over the start of a routine if found (the mst or frame start instruction). The reason is to break at an active instruction inside of a routine.

tp [m] l|r Place tracepoint at source line number/routine

The tp or tracepoint command sets a tracepoint at the given source line or routine. Specifying the module containing the source line is optional.

Tracepoints are like breakpoints, but they do not stop after printing the currently executing line. Thus they will effectively “trace” the program execution through that point in the code.

debug> tp 23

*** Module must be active

debug> tp test 23

debug> r

22: 1: for i := 1 to 10 do

23: 1: t* a[i] := y(i);

24: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

22: 1: for i := 1 to 10 do

23: 2: t* a[i] := y(i);

24: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

22: 1: for i := 1 to 10 do

23: 3: t* a[i] := y(i);

24: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

...

Just as for source breakpoints, the module can be specified or left to the current default.

Note that the tracepoint command will skip any source line markers, and will skip over the start of a routine if found (the mst or frame start instruction). The reason is to break at an active instruction inside of a routine.

bi a Place breakpoint at instruction

Places a machine instruction level breakpoint. These breakpoints can be placed anywhere in the program, and thus no module is required.

debug> lc test 1 1000

1: 1: program test(output);

2: 0:

00006A: AE mrkl* 0000000000000002

000073: AE mrkl* 0000000000000003

3: 0: var a: array 10 of integer;

000073: AE mrkl* 0000000000000003

00007C: AE mrkl* 0000000000000004

4: 0: i: integer;

...

000353: AE mrkl* 0000000000000021

00035C: 05 lao 00000000000005A4

000365: BD inv

000366: AE mrkl* 0000000000000022

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

000366: AE mrkl* 0000000000000022

00036F: 7B ldci 000000000000000A

000378: 02 stri 01,FFFFFFFFFFFFFFF0

000382: 7B ldci 0000000000000001

00038B: 02 stri 01,FFFFFFFFFFFFFFE8

000395: 00 lodi 01,FFFFFFFFFFFFFFF0

00039F: 03 sroi 00000000000005A4

0003A8: AE mrkl* 0000000000000022

0003B1: 01 ldoi 00000000000005A4

0003BA: 00 lodi 01,FFFFFFFFFFFFFFE8

0003C4: 95 geqi

0003C5: 18 fjp 0000000000000493

debug> bi $3c5

debug> r

=== break ===

33: 21: a[i] := y(i);

34: 2: b* for i := 10 downto 1 do writeln('Value: ', a[i]);

35: 0:

debug>

Note that the break instruction print will be in source mode unless you change to machine mode.

Note also that there is only one breakpoint table, and it is shared by all source and machine level breakpoints and tracepoints.

Note that the breakpoint must be placed at the start of a valid instruction, or the result will be a crash.

tpi a Place tracepoint at instruction

Places an instruction level tracepoint.

Note that the break instruction print will be in source mode unless you change to machine mode.

Note that the tracepoint must be placed at the start of a valid instruction, or the result will be a crash.

c [a] Clear breakpoint/all breakpoints

Clears either a single breakpoint or tracepoint, or all of them from the table. The number to clear corresponds to the entry number in the table.

debug> lb

Breakpoints:

No Src Addr Trc/brk

=======================

1: 1: 000000 b

2:****: 00013E b

debug> c 2

debug> lb

Breakpoints:

No Src Addr Trc/brk

=======================

1: 1: 000000 b

lb List active breakpoints

Lists the breakpoints in the table.

debug> b test 15

debug> tp test 18

debug> bi 5

debug> tpi 10

debug> lb

Breakpoints:

No Src Addr Trc/brk

=======================

1: 1: 000000 b

2: 15: 000079 b

3: 18: 000096 t

4:****: 000005 b

5:****: 00000A t

The first entry in the table is the logical entry number. This is what you use to clear the breakpoint. The second entry is the source line number. This will be all “****” if there is no source line associated with it (it is a machine level breakpoint). This is followed by the address of the breakpoint, and then a “b” (for breakpoint) or “t” for tracepoint.

w a Watch variable

Set a variable watch. A variable watch prints a diagnostic every time the indicated variable is changed. Any Pascaline variable in the current scope can be watched.

debug> b test 22

debug> r

=== break ===

21: 1:

22: 1: b* for i := 1 to 10 do

23: 0: a[i] := y(i);

debug> w i

debug> r

Watch variable: @000000D1: i@00000298: * -> 1

Watch variable: @0000012E: i@00000298: 1 -> 2

Watch variable: @0000012E: i@00000298: 2 -> 3

Watch variable: @0000012E: i@00000298: 3 -> 4

...

The watch message line tells you what program instruction modified the variable, followed by what the variable was that was modified, and its’ address, then what the value of the variable was, and what it was changed to.

Only simple variables can be watched, not structured. If you want to watch a variable within a structured type, indicate what element you wish to watch:

debug> b test 22

debug> r

=== break ===

21: 1:

22: 1: b* for i := 1 to 10 do

23: 0: a[i] := y(i);

debug> w a[5]

debug> r

Watch variable: @00000112: a@00000280: * -> 15

When any block ends, any watches to variables within that block are automatically evicted.

lw List watch table

Lists the watch table:

debug> lw

Watch table:

1: 00000270

This gives the logical number of the watch entry, followed by the address the watch was placed on.

cw [n] Clear watch table entry/all watch entries

Clears either a specific watch entry by logical number, or clears the entire watch table.

lia List instruction analyzer buffer

Lists the contents of the instruction analyzer buffer. The instruction analyzer buffer is a queue that continually stores the address of the executing instructions and evicting the oldest addresses.

debug> an

debug> b test 22

debug> r

=== break ===

21: 1:

22: 1: b* for i := 1 to 10 do

23: 0: a[i] := y(i);

debug> lia

last instructions executed:

b * 0000B5: 7B ldci 00000001

0000B0: AE mrkl* 00000016

0000AB: AE mrkl* 00000015

0000A6: AE mrkl* 00000014

0000A1: AE mrkl* 00000013

00009C: AD ente FFFFFFF0

000097: 0D ents FFFFFFD8

000017: 0C cup 00,00000097

000015: 0B mst 00

000010: AE mrkl* 00000002

debug>

Because running instruction analysis slows down instruction execution a bit, it must be specifically enabled. This is done with the an (analysis on) command.

lsa List source analyzer buffer

Lists the contents of the source analyzer buffer. The source analyzer buffer is a queue that continually stores the address of the executing source lines and evicting the oldest addresses.

debug> b test 24

debug> an

debug> r

=== break ===

23: 10: a[i] := y(i);

24: 1: b* for i := 10 downto 1 do writeln('Value: ', a[i]);

25: 0:

debug> lsa

last source lines executed:

23: 10: a[i] := y(i);

24: 1: b* for i := 10 downto 1 do writeln('Value: ', a[i]);

18: 10: end;

17: 10:

16: 10: result add+i

15: 10:

14: 10: i := 10;

13: 10:

12: 10: begin

11: 10:

s [n] Step next source line execution

Steps source line execution. The current source line is executed and stopped at the following instruction.

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> s

32: 2: for i := 1 to 10 do

33: 1: * a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug> s

23: 1:

24: 1: * i := 10;

25: 0:

debug> s

25: 1:

26: 1: * result q(add)

27: 0:

debug> s

15: 1:

16: 1: * z := 42;

17: 0:

debug>

As stated, a side use of the s command is to go from the startup code to the first source line.

If a number appears on the s command, then that many steps are done:

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> s 5

32: 2: for i := 1 to 10 do

33: 1: * a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

23: 1:

24: 1: * i := 10;

25: 0:

25: 1:

26: 1: * result q(add)

27: 0:

15: 1:

16: 1: * z := 42;

17: 0:

17: 1:

18: 1: * result x+i

19: 0:

debug>

ss [n] Step next source line execution silently

The ss (step silent) command is the same as the s (step) command except that it does not print.

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> ss 5

debug> ps

17: 1:

18: 1: * result x+i

19: 0:

debug>

si [n] Step instructions

Steps a single machine level instruction, or optionally the number of instructions specified.

P6 debug mode

pc: 000000 sp: 1000000 mp: 1000000 np: FFFFFFFFFFFFFFFF

* 000000: 14 lnp* 00000000000005AC

debug> si

pc: 000009 sp: 1000000 mp: 1000000 np: 0005AC

* 000009: 15 cal 000000000000004E

debug> si

pc: 00004E sp: FFFFF8 mp: 1000000 np: 0005AC

* 00004E: AE mrkl* 0000000000000001

debug>

sis [n] Step instructions silently

Steps a single machine level instruction silently, or optionally the number of instructions specified.

P6 debug mode

pc: 000000 sp: 1000000 mp: 1000000 np: FFFFFFFFFFFFFFFF

* 000000: 14 lnp* 00000000000005AC

debug> sis

debug> sis

debug> sis

debug> ps

pc: 000057 sp: FFFFF8 mp: 1000000 np: 0005AC

* 000057: F5 sfr 0000000000000000

debug>

so [n] Step next source line execution over routines

Steps source line execution. The current source line is executed and stopped at the following instruction. Any subroutine calls are skipped over, that is, executed until they return. This is the same as s, but skips routine calls.

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> so

32: 2: for i := 1 to 10 do

33: 1: * a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug> so

32: 2: for i := 1 to 10 do

33: 2: * a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug> so

31: 1:

32: 3: * for i := 1 to 10 do

33: 2: a[i] := y(i);

debug> p i

2

debug>

sso [n] Step next source line execution over routines silently

Steps source line execution. The current source line is executed and stopped at the following instruction. Any subroutine calls are skipped over, that is, executed until they return. This is the same as s, but skips routine calls. No status print results. This is the same as ss, but steps over routine calls.

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> sso

debug> sso

debug> sso

debug> ps

31: 1:

32: 3: * for i := 1 to 10 do

33: 2: a[i] := y(i);

q

debug> p i

2

debug>

sio [n] Step instructions over routines

Steps a single machine level instruction, or optionally the number of instructions specified, skipping over subroutine calls. This is the same as si, but skips over routine calls.

debug> bi $2f6

debug> r

=== break ===

pc: 0002F6 sp: FFFFA8 mp: FFFFD0 np: 0005AC

b * 0002F6: 01 ldoi 00000000000005A4

debug> sio

pc: 0002FF sp: FFFFA0 mp: FFFFD0 np: 0005AC

* 0002FF: F6 cuf 000000000000016B

debug> sio

pc: 000308 sp: FFFFA8 mp: FFFFD0 np: 0005AC

* 000308: AE mrkl* 0000000000000021

debug>

siso [n] Step instructions silently over routines

Steps a single machine level instruction silently, or optionally the number of instructions specified, skipping over subroutine calls.

P6 debug mode

pc: 000000 sp: 1000000 mp: 1000000 np: FFFFFFFFFFFFFFFF

* 000000: 14 lnp* 00000000000005AC

debug> bi $2f6

debug> r

=== break ===

pc: 0002F6 sp: FFFFA8 mp: FFFFD0 np: 0005AC

b * 0002F6: 01 ldoi 00000000000005A4

debug> siso

debug> siso

debug> ps

pc: 000308 sp: FFFFA8 mp: FFFFD0 np: 0005AC

* 000308: AE mrkl* 0000000000000021

debug>

ret Return from routine

Continues execution until the currently executing routine exits.

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> s

32: 2: for i := 1 to 10 do

33: 1: * a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug> s

23: 1:

24: 1: * i := 10;

25: 0:

debug> ret

32: 2: for i := 1 to 10 do

33: 2: * a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug>

hs Report heap space

Prints the space allocated on the heap. This is mainly used for diagnostic purposes.

debug> b test 23

debug> r

=== break ===

22: 1: new(p);

23: 1: b* for i := 1 to 10 do

24: 0: a[i] := y(i);

debug> hs

Heap space breakdown

addr: 0002B0: 8: alloc

The first field is the address of the heap entry. The second is the length. The last indicates the entry is allocated.

ti Turn instruction tracing on

Turns on instruction tracing. When instruction tracing is on, a single line for each bytecode machine instruction is printed.

debug> b 20

*** Module must be active

debug> b test 20

debug> ti

debug> r

b * 000000/1000000: 14 lnp* 00000298

* 000005/1000000: 15 cal 0000000B

* 00000B/FFFFFC: AE mrkl* 00000001

* 000010/FFFFFC: AE mrkl* 00000002

* 000015/FFFFFC: 0B mst 00

* 000017/FFFFDC: 0C cup 00,00000092

* 000092/FFFFDC: 0D ents FFFFFFD8

* 000097/FFFFD4: AD ente FFFFFFF0

* 00009C/FFFFD4: AE mrkl* 00000012

* 0000A1/FFFFD4: AE mrkl* 00000013

* 0000A6/FFFFD4: AE mrkl* 00000014

* 0000AB/FFFFD4: AE mrkl* 00000015

b * 0000B0/FFFFD4: 13 brk

=== break ===

19: 1: begin

20: 1: b*

21: 1: for i := 1 to 10 do

The instruction trace lines consist of the following:

1. A column with space or “b” to indicate that instruction has a breakpoint set.

2. A column with space or “*” to indicate that the point of execution is on this instruction. Note that since the instruction is always active when tracing, this is always set.

3. The value of the pc register.

4. The value of the sp register.

5. The bytecode instruction value.

6. The memnonic for the instruction.

7. The p value for the instruction.

8. One or more parameters for the instruction.

nti Turn instruction tracing off

Turns off instruction tracing.

tr Turn system routine tracing on

Turns on system routine tracing. In this mode, a message line is produced each time a system routine is called.

debug> tr

debug> r

400/16777156-> 6

Value:

437/16777160-> 8

20

439/16777168-> 5

400/16777156-> 6

Value:

437/16777160-> 8

19

439/16777168-> 5

400/16777156-> 6

Value:

437/16777160-> 8

18

439/16777168-> 5

400/16777156-> 6

Value:

437/16777160-> 8

17

439/16777168-> 5

Note the routine messages here are intermixed with the program output.

The first value printed is the pc register. The second value is the sp register. The last value is the call number.

ntr Turn system routine tracing off

Turns system routine tracing off.

ts Turn source line tracing on

Turns source line tracing on. Source line tracing prints a trace each time a source line is executed.

P6 debug mode

31: 1:

32: 1: * for i := 1 to 10 do

33: 0: a[i] := y(i);

debug> b 33

debug> ts

debug> r

31: 1:

32: 2: * for i := 1 to 10 do

33: 0: b a[i] := y(i);

32: 2: for i := 1 to 10 do

33: 1: b* a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

=== break ===

32: 2: for i := 1 to 10 do

33: 1: b* a[i] := y(i);

34: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug>

For each source line executed, the line before, the current line executing, and the next line are printed.

nts Turn source line tracing off

Turns off source line tracing.

spf Turn on source level profiling

Turns on source level profiling. Source level profiling is a count kept for each source line that is incremented each time that line is executed.

debug> r

Value: 20

Value: 19

Value: 18

Value: 17

Value: 16

Value: 15

Value: 14

Value: 13

Value: 12

Value: 11

*** Stop instruction hit

=== break ===

*** No active module

debug> l test

1: 0: b {$w,f}

2: 1: program test(output);

3: 0:

4: 0: var a: array 10 of integer;

5: 0: i: integer;

6: 0:

7: 0: function y(add: integer): integer;

8: 0:

9: 0: var i: integer;

10: 10:

11: 10: begin

12: 10:

13: 10: i := 10;

14: 10:

15: 10: result add+i

16: 10:

17: 10: end;

18: 1:

19: 1: begin

20: 1:

21: 1: for i := 1 to 10 do

22: 10: a[i] := y(i);

23: 1: for i := 10 downto 1 do writeln('Value: ', a[i]);

24: 1:

25: 1: * end.

The source line profile count is the second number on the source listing after the line number.

Source line profiling is not time intensive, and defaults to on.

nspf Turn off source level profiling

Turns source line profiling off.

debug> nspf

The listing will have the source line profiling column removed.

an Turn on analyzer mode

Turns on analyzer mode. Both source and instruction analyzer collection is turned on. Note that analyzer mode does take a small amount of execution time, and so is normally set off.

nan Turn off analyzer mode

Turns off analyzer mode.

r Run program from current pc

The byte code interpreter runs from the current pc until a stop or breakpoint is hit.

ps Print current registers and instruction

Prints the current machine execution status. The format of the printout will depend on what mode the debugger is in, either source level or machine level debugging.

debug> b test 22

debug> r

=== break ===

21: 1: for i := 1 to 10 do

22: 1: b* a[i] := y(i);

23: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

debug> ps

21: 1: for i := 1 to 10 do

22: 1: b* a[i] := y(i);

23: 0: for i := 10 downto 1 do writeln('Value: ', a[i]);

For source level. Note that the status is printed each time the program breaks, automatically.

debug> b test 22

debug> r

=== break ===

pc: 0000E7 sp: FFFFD4 mp: FFFFFC np: 000298

b * 0000E7: 05 lao 0000026C

For machine level.

How can source level breakpoints be set even when not in source debugging mode (The “b test 22” above)? Debug mode understands line numbers even if it does not load the source text for the program.

q Quit interpreter

Exits the pint interpreter.

7Different generation and run options: pint, pmach and cmach, and pgen

pint

pint, the traditional interpreter for the Pascal-P series, can generate a binary deck in Pascal-P6 to be run by a separate byte code machine using the $e/$machdeck option. See “Compiler options”. A separate bye code machine does not have the overhead of assembly or debugging of the intermediate. Thus it can be smaller and (in some cases) faster than pint. There are two alternate byte code machines available:

pmach

This is the byte machine core from pint, and directly tracks pint. Because it comes from the same code base, it has identical run time. pmach tracks pint, meaning that updates to the pint byte code machine are copied to pmach.

cmach

This is the byte machine core from pint, but translated into the C language according to ISO 9899:1990 or ANSI/ISO C (no C99 constructs are used). The purpose of cmach is as a porting tool for Pascal-P6. Any compiler that obeys the original ANSI C language can be used to implement a Pascal-P6 system using this module. It is also can be nearly an order of magnitude faster than the mainline pint/pmach machine (with the proper options set).

package

cmach features a “packaged mode”, which enables the generation of executables from a Pascal-P6 source deck.

pgen

Besides the interpretation options, Pascal-P6 can also use the option to directly generate machine code for a particular processor. See “12 pgen – AMD64 code generator”.

As shown, pcom produces *.p6 intermediate files as output. This can be fed to pint or pgen. pint can produce a “machine deck” consisting of the object file for the Pascal-P6 “virtual machine”, which pint can either run itself or export to a file, *.p6o (or .p6 “object”). This file can then be run on either pmach or cmach. pgen takes a *.p6 intermediate and generates a *.s assembly file, which is then fed to a compiler/assembler such as gcc to become part of a binary executable.

7.1Running the different machines

The p6 script features flags to optionally run programs on the different machines:

–pgen Compile directly to executable binary (the default).

--pint Run on the pint interpreter.

--pmach Run on the pmach machine.

--cmach Run on the cmach machine.

–package Run in packaged mode.

Example:

p6 –pmach test

To run program test on the pmach machine.

7.2Difference between different generation modes

The differences between the number of source code lines and run times for different machines are detailed (at current writing, and using the “prime.pas” test in the sample_programs directory):

Note that for pint, pmach and cmach modes, the total time includes loading time for the intermediate. For pgen and package, it does not, since they are executables.

7.3Setting machine options on pmach and cmach

Because both pmach and cmach do not have access to the intermediate, they use the defaults for several run time options that are detailed in “Compiler options”. For both pmach and cmach, these options must be set in the source and then the modules recompiled.

For cmach, the options can be set via compiler flags as follows:

Where “-“ means “does not apply”. pint and pmach do not need their word size defined externally.

Note that all of the options are true/false except for WRDSIZ16, WRDSIZ32 and WRDSIZ64, which are defined/not defined options. This means they must be set to 0 (false) or 1 (true).

7.4Packaged application mode

cmach has the ability to create “packaged” applications. This means the given application byte code is united with the cmach interpreter and generated as an executable. The resulting program looks and behaves just as a fully machine compiled application would, but does not execute any faster than the interpreted version. A packaged application may be smaller than the equivalent machine compiled application, because byte machine code is often more dense than target machine code. This needs to be determined on a case by case basis.

An application does not typically get the “interpretation bonus” until it is large enough to overcome the overhead of needing to include its’ interpreter in the program, as well as the need to carry a full set of library routines, instead of just the minimal routines needed.

“running as a bytecode machine” may be a good idea on very small machines such as 16 bit or even 8 bit microprocessors⁶. For these types of machines, the key is finding a good, compact C compiler for cmach.c, or even recoding the interpreter in native assembly language. This was done, for example, with UCSD Pascal.

Packaged applications can be generated by the p6 script:

p6 --package test

Will generate a test or test.exe executable.

Using the $e/$machdeck option, pint generates a byte instruction code file in hex format. The program genobj takes this byte code and converts it to a static array in the C language, then it is compiled together with cmach.c to make a final program.

The pint generated hex file format

The generated bytecode from pint using the $e format appears as:

:100000000000000000141C250000150B0000003AAE010000005E

:100000000000000010AE02000000AE03000000AE04000000AEC1