
PalmOS  Pascal  Compiler

Version 2.10 (full version including native 68k and ARM code generation,  OS>=5)
Version 1.19 (Standard VFSDos version for 68k code generation only, OS<=4.1)

2005/07/18

by Philippe GUILLOT

ph.guillot@wanadoo.fr

forum : http://www.ppcompiler.org

INTRODUCTION:
-------------

 PP  is a freeware standard Pascal compiler for PalmOS. PP generates true native
68000 or ARM executable code (.PRC) from standard Pascal source  code.  You  can
use your favorite Palm DOC editor to write your code, and either run PP from the
VFSdos console, PPShell or PIAF to compile and run your program.

 VFSDos  applications  created by PP have all the same Palm unique registered ID
'pDOS',  which  is  the standard ID for all VFSdos applications. This means that
your  compiled  applications can be executed from either the PP shell interface,
the PIAF IDE, or the VFSdos console, and you do not need to register a unique ID
for them. For more information about VFSdos, please visit the VFSdos web page.

 PP is also able compile Palm graphical UI applications, hack extensions, shared
libraries, multi segment applications and DA (see further and provided samples).

 PP  has  been  tested  on  the following handhelds: Palm III, m500, m505, m515, 
Sony  Clie T625, TRGpro,  Tungsten  T,  T3,  T5.  Although  PP  has  been tested
extensively, like any other Palm application, it may have bugs.  Please  contact
http://www.ppcompiler.org for any suggestions or bug reports.


REQUIREMENTS:
-------------

- PalmOS 3.5 or greater. PalmOS >=5.0 is required to execute armlet.
- 140 k of free dynamic heap memory.
- Mathlib library (only if the program uses one the mathematical functions:
  arctan, cos, sin, log, exp or sqrt).
- PPShell, PIAF or the VFSDos (*) console interface.

(*) NOTE :  If you wish you may use PP within the VFSdos console, instead of  PP
    Shell.  VFSdos is a DOS-alike console interface for PalmOS. You can find the
    latest version of VFSdos from the following site:

    http://pages.total.net/~hkonstas/vfsdos.html


DOWNLOAD:
---------

You can download the current version of PP from the following link:

  http://www.ppcompiler.org


INSTALLATION:
-------------

Distribution files :
--------------------
ppARM/PP_EXE.PRC  The full version 2.10 for also compiling armlet on OS5
    devices (e.g. Tungsten T|T, Zire 71).

pp68k/PP_EXE.PRC:   The Standard Pascal compiler for VFSdos, version 1.19.
    Install this version on OS <= 4.xx devices with >= 8 Mb RAM such as m5xx,
    Cli T625.

ppLight/PP_EXE.PRC A version of the compiler for low memory (<= 4 Mb RAM)
    device such as m100, Zire, etc.


STDIOLIB.PRC: The latest STDIO library (version >= 2.16 required).

PPSHELL.PRC:  The compiler gui shell application (if you do not use VFSdos
              on your handheld).

Examples/*.PAS:        Pascal source code samples in DOC format.

Optional files (NOT included in the distribution ZIP):

VFSDOS.PRC:   The Harry Konstas VFSdos console.

MATHLIB.PRC:  The mathlib library required for optional math transcendental
              operations.

QED.PRC:      The doc editor (shareware) available at http://www.qland.de/qed/

Piaf.prc:     The standard PP IDE.

Installation instructions :
---------------------------
  Install one of the "pp_exe.prc"  according  to  your  device  and  the  latest
version of the STDIO library, StdioLib.prc. If you are already  using  an  older
version of StdioLib, please install the version included  in  this  distribution
zip file. You may also install PPshell.prc if you do not have  VFSdos  installed 
on your handheld. You may find useful to also install the  pascal  sample  files
included in the zip to get you started. Please note that source code  files  are
databases in uncompressed DOC format, readable by any DOC reader.

  If a message "unable to initialize" appears, you may try to install  the  file
included in the folder ppLight. This version has  a  lower  memory  requirement.
In counter part, some huge source may not compile and  the  executable  size  is
limited to 24 ko.

  The version 2.10 included in the ppArm folder has the  same  features  as  the
standard PP and in addition, it may compile native armlet (using  the  directive
{$armlet xxxx,yyyy,zzzz,nnn}  similar to the {$code...} directive  described  in
the sequel). It support  most  Pascal  features  except  standard i/o  and  real
transcendental functions (sin, cos, etc.) which are  not  yet  implemented.  The
compiler runs on 68k devices, but generated arm code runs only on OS>=5.

************** CAVEAT  :  ARM CODE DOES NOT RUN ON POSE ************************


USAGE:
------

 Launch the PP Shell application and you will see the list of the sample  source
code files (all in DOC format, having the .pas  extension).  Simply  select  the
file you want to compile, and press the GO button.  Once  the  source  has  been
successfully compiled, select the EXECUTE button. Now you will see the  list  of
all the compiled PP applications. You can enter optional arguments in  the  text
field under the list, and press the GO button to execute your  application.  Use
the DEL button to delete a selected application from the list. In compile  mode,
the EDIT button launch QED doc editor (if present) on the selected file.

 If you have VFSdos installed on your handheld and will be using PP from  within
the VFSdos console, you simply launch pp with the source filename as a
parameter directly from the VFSdos prompt:

   c:>pp sourcename

where 'sourcename' is the name of your application source database. This example
compiles the doc database named 'sourcename.pas'.

If the program header in your source code is:

    program exename; ...

then a PRC database named 'exename.exe' is created.

Finally, to execute your compiled application, just type it in the VFSdos
command prompt:

  c:>exename  <param n>

where <param n> are the optional application parameters (if any). When run is
over, any key hit returns to VFSDos or PPShell.

PP supports  cooperation  with  doc  editor  QED (  http://www.qland.de/qed/  ).
Version >= 2.73 is required.  If  an  error  occurs  when  compiling,  a  prompt
"goto error ?[y/up]" proposes you to hit "y" or "Pgm up" hard button  to  launch
QED on error position.


PP  LANGUAGE FEATURES:
----------------------

 The langage syntax is compliant to the ISO 7185:1990 level 0. In particular, it
supports
- nonlocal goto,
- procedure and function as parameter,
- standard syntax for new and dispose for pointer to record with variant.

 The conformant array parameters are NOT supported.

 There is no runtime range control.

See http://www.moorecad.com/standardpascal/home.html for a complete  description
and  the demo sources for examples.

 In addition, the language supports some of the Turbo Pascal extensions such  as
strings, @ operator (non standard use), bitwize operators, etc.

Files:
------

Files are stored as uncompressed doc database in binary format.  Files  of  char
and text are readable by any doc reader. The read functions  support  compressed
doc.

Files other than input and output which are declared in  the  program  parameter
list are assigned to the actual parameters of the command line.

The function reset(f) opens a file for reading which is specified in the program
parameter list.

To open a file while is not  in  the  program  parameter  list,  the  syntax  is
reset(f,name), where name is a string. The same convention  applies  to  open  a 
file for writing using the procedure rewrite.

The (non standard) function close(f) must be called for all open files.

The standard input supports interactive mode (lazy I/O) for  get  procedure  and
when reading characters on the VFSDos console.

Runtime error codes:
--------------------

102: Program parameter missing.
103: VFSDOSdata database not found.
105: File not open for inspection.
106: Unexpected end of file (EOF) while reading.
110: File not open for generation.
120: Invalid integer or real format.
158: Incorrect width parameter on text write.
201: mathlib library not found.
206: Unable to open file.
301: log or sqrt has negative parameter.
1000: Internal error (unexpected case, NULL handle, etc.).


Misc:
-----

- Real are 32 bit float IEEE 754 compatible;
- Integer are 32 bit signed int;
- Enumerated type size is 8 bit for maximum value  up  to  255,  is  16  bit for
  maximum value up to 65535 and else is 32 bit;
- Record size is limited to 32k, but array size is unlimited (32 bit  addressing
  mode).
- Unititialized global data storage is limited to 32k
- Initialized global data storage is limited to 32 k
- Integer sets are limited to the range 0..255
- Packed structured type are implemented as unpacked types. Adresses are aligned
  to the even memory location for data greater than one byte.
- Standard functions pack and unpack are not currently supported.
- Subrange types are packed: a variable declared of type 0..65535 uses  2  bytes
  in memory.
- Function odd and sqr are  implemented  inline  and  may  not  be  invoqued  as 
  function parameter.
- Boolean expressions are evaluated from left to right  and  the  evaluation  is
  aborted as soon as the result is  known :  in  the  expression  a  or  b,  the 
  expression b is not evaluated if the value of a is true.
- Other expressions and assignement statements are evaluated from right to left.
  In the statement t[i]:=a+b, the expression b is evaluated first,  then  a  and
  then i (it may be important in the case of function with side effect).
- Program paramater may be of type file, text or string.

Additional functions and procedures:
------------------------------------

- gotoxy(x,y), procedure, positions the cursor at the desired  screen position.
- textmode(mode), procedure, selects video mode: 1=32 cols 0=40 cols.
- clrscr, procedure, clears the screen.
- delay(n) waits for n milliseconds.
- random(n) returns a pseudo-random integer in the range 0..n-1.


Non standard features:
----------------------

1. Most constant expression computable at compilation time are allowed  anywhere
a constant value is expected.

examples :

const
  n  = 5;
  nn = 2*n;

type
  table = array[0..nn-1] of n..3*n;

Mathematical functions sin, exp, arctan, sqrt, log are not allowed  in  constant
declaration.

2. The packed array [1..?] of char type not supported for reading  and  writing.
It is replaced in version >= 1.01a by the usual string type.

-  string[n] denotes a zero terminated string of at most n characters;
-  the default size is 63 characters not including the terminal zero. Therefore,
   string is equivalent to string[63];
-  the first character of a string s is accessed by s[1];
-  The null string '' is allowed, it is equivalent to chr(0);

The following operators are supported for string types:
-  comparison with lexicographic order <, <=, >, >=, =, <>
-  concatenation +

The string type is compatible with the char type and with any other string type,
A string type var parameter is comptatible with any other string type  variable.
The inline function "length" returns the actual string length

The string type is allowed as return type of a function.

The directive {$MaxString nnn} may change the default string size (see further).

3. The directive "inline" allows to insert 68000 or THUMB native code such as
   PalmOS API systrap's. When calling an inline procedure or function,
   the specified sequence of 16 bit constant in inserted. The constant in an
   inline sequence may be
    - any 16 bit integer constant;
    - any string constant (completed by zero for word alignement);
    - @VariableIdentifier, to define the 16 bit offset of the variable relative
      to A5 for global variables and to A6 for locals (mode 68k only, not in ARM
      mode).
    - @ProcedureOrFunctionIdentifier to define the offset of the defined
      procedure or function relative to the current program counter pc (mode 68k
      only, not in ARM mode).

4. Character '$' starts hexadecimal representation integers.

5. Underscore '_'is allowed inside identifiers.

6. Hard button page up stops the program while writing on the console.

7. The read procedure applied to a character is bufferised (batch mode). To use
   the interactive mode, use c:=input^; get(input). The variable input must be
   declared in the program parameters : program name(input); ...

8. The C++ style comment is supported : character following // are ignored until
   the end of line.

9. A predefined type "pointer" is assignement compatible with all other pointer
   types. The domain type of the "pointer" type is "pointer".

10.Typeless Var parameter are supported. In this case, any variable is
   compatible in the actual parameter list.

11."const" keyword is allowed in a procedure or function formal parameter list.
   If the parameter type is 4 bytes or less, the value of the actual parameter
   is pushed in the function/procedure call. If the parameter type is a string,
   a set or greater that 4 bytes, the address of the actual parameter is pushed.
   
12.Additionnal keywords "shl" and "shr" are the usual shift operators. They have
   the same precedence as *.

13.Additionnal keyword "xor" performs the exclusive or with the same precedence
   as "or"

14.Boolean operators "or", "and" and "xor" perform bitwise operations when they
   apply on integer.

15.Function "sizeof" applied to a variable defines a constant equal to the
   number of byte of the variable.

16.Procedural type are allowed, e.g.
   type ProcType=procedure(var i:integer);

17.Adress operator '@' applied to a variable, a function or a procedure returns
   a pointer type, e.g. p:=@f;

18.Set are allowed in constant declaration. e.g.
   const op = ['+','-','*','/'];

19.In the armlet mode (see {$armlet ...} directive further), the directive
   "systrap" defines a procedure or function as a call to a OS function. The
   syntax is 
   
   systrap <systrap number>[.<selector>] e.g.
   
   Procedure WinDrawChars(const chrs:string;len:Int16;x,y:Coord); systrap $220;
   Type FlpDouble=record lo,hi:integer end;
   Procedure f_ftod(var y:FlpDouble;x:real); systrap $306.11
   
   The systrap number is anded with $00000fff. Only the three last hexadecimal
   digits are taken into account in the systrap number. The compiler
   automatically generates endian swapping call for parameter and result
   conversion.

20.You may assign a ordinal integer value to an enumerated contant, e.g.
   Type DayOfWeek=(mon=1,tue,wed,thu,fri,sat,sun);
   Any integer type value is supported ; values must be declared in increasing
   order. By default, the ordinal values start on zero and are incremented by
   one on each enumerated constant.

21.Functions may be invoqued as procedure and ignoring the return value.

22.Global variables may be initialized as follow :
   var i,j : integer = 5;
       r   : record x,y:integer end = (x:1,y:2); // any order for fields
       t   : array[1..5] of boolean = (true, true, false, true, true);
       s   : array[boolean] of set of char=(['a'..'z'],['O','1','2']);
   These variables are defined in initialized part of global data (negative
   A5 offsets).

23.The keyword "nil" is allowed as actual parameter congruent to a "var"  formal
   parameter or a "const string" parameter. In this case, the value 0 is  passed
   to the procedure. This allows to define PalmOS API such  that  FrmAlertCustom
   or DmDatabaseInfo with such parameter and to use the ability of passing "nil"
   if the corresponding parameter is not required.

Compilation directives
----------------------

{$i filename} include the file at the position specified

{$r resourcefilename} specifies a resource file to include to the PRC file. Only
the last resource file declared is taken into account.

{$appl creator} specifies to build a 'appl' type PRC with the specified creator.
The creator must be a sequence of 4 characters in the range '!'..'~'  (33..127).
In this case the following standard features are not allowed
  - all file and text type;
  - file and text standard function (get, put, read(ln), write(ln), eof, eoln) ;
  - mathematical functions (sin, arctan, exp, log, sqrt, cos);
  - additionnal console function (gotoxy, clrscr);

Launch parameters cmd (16 bit integer), cmdPBP (pointer),  launchFlags  (16  bit 
integer) must be declared if needed in the program header and in global variable
section if used. The scope of these variables is the main  program  section  and
they cannot be invoqued in other functions or procedure.
If a program is lauched with a nonzero cmd value, the global  variables  segment
is not initialised. The non local goto's in  destination  of  the  main  program
section, constant strings and precomuted sets invoque global memory and must not
be used in a program section executed  with  nonzero  cmd  parameter.  See  demo
ppShell.pas (source code of PPShell rewriten in Pascal) for further details.

{$code xxxx,yyyy,zzzz,nnn} creates a resource of type zzzz  identifier  and  nnn
(a sequence of digits). xxxx is the type and yyyy is the creator of the PRC. The
name is specified in the program header. This directive allows to  use  PP as  a
code resource editor useful for programming hackmaster extensions, multi-segment
application  and  shared  libraries  (see sample  CaseHack.pas,  Multi.pas   and
GaussLib.pas).
The code segment contains in this order
- the main program section if it is not empty
- the procedures and functions in the order they are declared.
You may declare global variables in a code segment, but the  corresponding  data
resource is not created. These declarations should  only  be  used  in  case  of
multi-segment application where the same declaration occurs in the main  program
file. They are used to define the variable access to the  data  segment  in  the
compiled code.

Program parameter must be declared as global variable. The scope of the  program
parameters is the main program section. They cannot be invoqued in other
procedure or functions.

{$armlet xxxx,yyyy,zzzz,nnn} creates a resource of type zzzz identifier and  nnn
(a sequence of digits). xxxx is the type and yyyy is the creator of the PRC. The
generated code is native ARM and the created resource may be called throught the
pceNativeCall function. The global variable section of an armlet corresponds  to
the data passed  to  pceNativeCall  function.  They  must  be  declared  in  the
program header and in the global variable section.
The result is an error code it is nonzero in case of integer division by zero.
Transcendental functions (exp, log, sin, cos, arctan) are not yet implemented in
this mode.

{$define xxxx} sets symbol xxx as defined. 100  symbols  are  allowed  (16  with
ppLight) with no interaction with other identifier nor keyword

{$undef xxxx} set symbol xxxx as undefined, but do not erase it.

{$ifdef xxxx} {$ifndef xxxx} {$else} {$endif} are usual conditionnal compilation
directives.

{$c+} {$c-} have no effect. They exist for source compatibility reason.

{$cleanup} erases the previous PRC. Otherwise, only onvewrite the  new  compiled
resources.

{$version vvv} adds in PRC a resource 'tVer 1000' initialised with string vvv.

{$appname nnn} adds in PRC a resource 'tAIN 1000' (application name displayed by
the launcher) initialised with string nnn.

{$MaxString nnn} changes the default size value for strings. This directive
may be invoqued anywhere in the program. Variables of type string allocates
the numnber of bytes specified. It also changes room allocated in stack for
strings operations. Any value <= 32767 is allowed, but too large value shoule
not be used as it may cause crash due to stack overflow.

HOW TO:
-------

a) declare PalmOS API functions and procedure:
You have to get the PalmOS Programmer's API Reference available at the
PalmSource site. This document decribes almost all the available functions. You
also have to get the PalmOS SDK which defines those functions in C language.

For instance, the WinDrawLine function is described as a procedure that draws a
line on the current display window.

The Pascal definition of this function is:

- 68k mode :
procedure WinDrawLine(x1,y1,x2,y2:Coord); inline($4e4f,$a213);
$4e4f is the code for "trap 15" 68k instruction.
 
- Arm mode
procedure WinDrawLine(x1,y1,x2,y2:Coord); systrap $a213;

The systrap address $a213 is found in the "CoreTraps.h" file of the SDK.

Some other API calls are "systrap with selector" (float manager, VFS manager,
serial manager, etc.). In this case the declaration is (for instance)

-68k mode :

function VFSFileClose(FileRef:UInt32):UInt16; inline($7400+4,$4e4f,$a348);

$7400+4 is a 68k instruction that load immediate value 4 in d2 register. This
value is the "selector" for the VFSFileClose function found in "VFSMgr.h" SDK
file.
$4e4f is the standard PalmOS trap call.
$a348 is the common trap value for all VFS manager procedures.

-Arm Mode :
function VFSFileClose(FileRef:UInt32):UInt16; systrap $a348.4;

b) change return value of an UI application:

In appl and code mode, the default return value is 0. In the main section, it is
possible to return another value by invoquing the following inline procedure:

procedure exit(code:integer);inline($2017,$4e5e,$4e75);
// move.l (a7),d0
// unlk   a6
// rts

example:
// main section
begin
  error:=StartApplication;
  if error<>0 then exit(error);
  EventLoop;
  StopApplication;
end.


TRICKS
------

1. Alignment contrainst:
- In 68k mode, variable of more that 2 bytes are aligned on even address.
- In Arm mode, variables of 2 bytes are aligned on even address. Variable of
more that 3 bytes are aligned on address multiple of 4.

2. The entries addresses respect alignment contrainsts thus, the total
size of an array does NOT always equal the entry size times the number of
entries. One has to consider the lowest even or multiple of 4 number greater or
equal to the entry size.

e.g.
var t : array[1..100] of string[4];

Each entry is 5 bytes long (4 characters plus the terminal zero). In 68k mode,
each entry is aligned on an even address; the whose array size is 6 x 100 = 600.
In Arm mode, each entry is aligned on a multiple of 4 address; the whole array
size is 8 x 100 = 800.


Link:
-----
 Please visit the ppCompiler site (French and English) dedicated to  PP  (forum,
tutorials,  program samples) :

                        http://www.ppcompiler.org


Disclaimer:
-----------

 The PP compiler is distributed as freeware, and like any software  application,
although  well  tested,  it  may  contain  bugs.  The  author  cannot  be   held
responsible for any data loss. The user  takes  full  responsibility  for  using
the program.

Acknowledgement:
----------------

Thanks to (alphabetic order)

- Nicolas Arnoux
- Pierre Brothier
- Philippe Charrire
- Laurent Duveau
- Michael Green
- Dmitry Grimberg
- Harry Konstas
- John Newell
- Peter Obukhov

for their contribution and help in the development of PP.

HISTORY:
--------
2.10   application return value can be changed, {$MaxString xxx} directive,  bug
       fixes, improvement of internal memory management.

2.08   Jul  14th  2004 :  bug  fixes,  minor  improvements. "cleanup", "appname"
       and "version" directives. Keyword nil allowed in place of  var  or  const
       string parameter. Supression of the array size limit.

2.07   Apr  20th  2004 :  bug  fixes.  minor  improvement.  Nil  is  assignement
       compatible  with  procedural  variables.  Suppression of the 4k limit for
       local variables.

2.06   Nov 20th 2003 : bug fixes. Initialised variables. Increase number of
       defines.

2.05   Nov 13th 2003 : bug fixes. Allows to hit Pgm Up hard key to return to QED
       on compilation error. Run time library and code generation improvements.

2.04   oct 6th 2003 : bug fix in code generation (constant  real  comparison and
       set constructor); bug fix in forward pointer  domain  type  declaration ;
       support for any integer valued assignation to enumerated type. Some parts
       of  the  compiler  are  now  written in Pascal with PP.
       
2.03   sep 4th 2003 : function statement ignoring return value, minor fixes  and
       improvements in runtime library.

2.02   aug 14th 2003 : minor bug fixes and optimization (jump, runtime library).
       Adaptation to co-operate with the Piaf editor (see
       http://www.ppcompiler.org)

2.01   jun 21th 2003 : Assignement of enumerated constant, systrap with selector
       in ARM mode, allows to declare a resource file in console mode.

2.00   may 2nd. 2003 : Real computation and systrap directive in ARM mode, minor
       fixes.

1.08   apr 8th.  2003 : bug fixes, string type allowed as program parameter, set
       allowed in constant declaration. Sets in ARM mode.

1.07   feb 14th.  2003 : minor changes, bug fixes (with statement, real and
       string comparison, strings in armlets)

1.06   feb  5th.  2003 : large code bug fix, conditionnal directives, {$c+/-}
       directive, change in the {$code ...} directive syntax, inline extensions.

1.05d  jan 17th.  2003 : bug fix in "in" operator.

1.05c  jan. 1st.  2003 : bug fixes : infinite loop when execute readln; StdioLib
       update (accepts bookmark in source doc file); bug in reset(f,'filename');

1.05b  Dec. 25th. 2002 : bug fixes : with statement and pointers, char to string
       conversion.

1.05a  Dec  10th. 2002 : procedural type, address operator.

1.04d  Nov  20th. 2002 : sizeof function and code directive.

1.03g  Nov  15th. 2002 : Bugs fixes.

1.03f  Nov. 11th. 2002 : additionnal support for Palm applications. 32 bit
       integers, pointer type, xor and shift operator, bitwise operations and
       the usual bug fixes.

1.01a: Oct. 1st,2002: Bug Fixes on reals, Constant set precomputation,
       additionnal features (strings, inline functions and procedures, include
       directive).

1.00d: Sept. 13th,2002: Bug Fixes, code optimization, samples.

1.00c: Sept. 7th,2002: Bug fixes, speed and code optimizations. 

1.00b: Sept. 2nd, 2002: Minor update (bug fixes, PPshell updated).

1.00a: August 31st, 2002: Initial Release.


* The PP compiler has been developped by Philippe Guillot on a Tungsten T  using
  OnBoardC, QED, RsrcEdit, Piaf and previous version of PP.

* PP Shell was written by Harry Konstas  on  a  m505  using  OnBoardC,  QED  and
  RsrcEdit, translated into Pascal by Philippe Guillot.



Philippe GUILLOT
ph.guillot@wanadoo.fr

