README

-----------------------------------------------------------------------------
 OpenVCL - Free VCL Pre-Processor
 Copyright (C) 2004 Jesper Svennevid, Daniel Collin
-----------------------------------------------------------------------------

Piracy ruins the industry. Don't be a moron, buy your games.

License
-------

Licensed under the AFL v2.0. See the file LICENSE included with this
distribution for licensing terms.

Disclaimer
----------

OpenVCL has been constructed from reading the public VCL documentation and
analysing VCL source-examples. Nothing has been reverse-engineered.

VU Command Line(tm) is a trademark of Sony Computer Entertainment. VCL is the
abbreviated name for VU Command Line(tm).

Installation
------------

The program is installed by executing 'make install'. If you have your PS2DEV
environment variable setup, it will install into $PS2DEV/bin, otherwise you
will have to do 'PREFIX=/usr/local make install' to complete installation.
Users of BSD will have to substitute make with gmake.

Usage
-----

OpenVCL is a software development tool that simplifies VU programming by
preprocessing source into standard VSM/DSM. It merges both pipelines into one
single path, manages register allocation and (in the near future) reschedules
instructions for efficient execution.

This kind of software has previously only been available for registered
developers and purchasers of PS2 Linux. For others, the functionality has
been unavailable, and hampered development of easily managed VU programs.

Documentation for how to write VCL-code is available at this location:

http://playstation2-linux.com/files/vcl/

If no input is specified, OpenVCL will read from standard input. Likewise,
if no output file is specified, OpenVCL will write the resulting source to
standard output.

The command-line parameters are as follows:

  -c              Emit nearly original source code as comments.
  -C              Disable the code reduction pass.
  -d              Dumb code is generated.
  -e              Disable the generation of [E] bits at the end of the code.
  -f              Disable the generation of alignment directives (.align n)
  -g              Run gasp on the input before any VCL-specific task is done
                    Commandline: "-p -s -c ';'". "-I" is also passed.
  -G              Run the C preprocessor on the input.
  -h              Print out the command-line help.
  -I<includepath> To be used with "-g"; tells gasp where to find include-files.
  -K              Temporary files created by pre-processors are not deleted.
  -L              Globally disable loop code generation.
  -M              Kept for compatibility with VCL.
  -m              Generate ".mpg" and DMA tags automatically.
  -n              Enable new syntax.
  -o<output>      Output filename.
  -P              Kept for compatibility with VCL.
  -t<timeout>     Specify optimizer timeout.
  -u<string>      <string> is used as a unique string for label generation.
  -Z              Kept for compatibility with VCL.

  OpenVCL exclusive parameters:
  --gasp <name>   Execute <name> instead of 'gasp' when preprocessing.
  --cpp <name>    Execute <name> instead of 'cpp' when preprocessing.
  --bthres <val>  Number of times a dynamic branch can be visited. (Default: 16)

The parameters are setup to match those of VCL, to allow for a drop-in
replacement in either direction. Many (most who influence how code is
generated) have no function today.

Please note that there is NO optimization going on at this stage. The code
generated by OpenVCL could be compared to passing -d to VCL. This will
change as the tool evolves.

Expression Solver
-----------------

The expression solver has a few extensions that allows for more clean way of
writing values with LOI. This will however make the source incompatible with
the standard VCL, but if you don't care, this is for you:

Function        Result
--------        ------

abs( x )        Absolute value of x
exp( x )        Exponential function of x
sin( x )        Sine of x (from radians)
sinh( x )       Hyperbolic sine of x (from radians)
asin( x )       Arcsine of x
cos( x )        Cosine of x (from radians)
cosh( x )       Hyperbolic cosine of x (from radians)
acos( x )       Arccosine of x
tan( x )        Tangent of x (from radians)
tanh( x )       Hyberbolic tangent of x (from radians)
atan( x )       Arctangent of x
atan2( x, y )   Arctangent of y/x
pow( x, y )     Calculate x raised to the power of y
log( x )        Calculate the logarithm of x
log10( x )      Calculate the base-10 logarithm of x
sqrt( x )       Compute the square-root of x
pi()            Returns pi (3.14159...)

Example of usage:

  loi sin(45 * (pi()/1.8e2)) ; compute the sine at 45 degrees and store in I

Function-names are case-sensitive.

Differences
-----------

This pre-processor differs from the original VCL on a few key issues:

 * If an alias contains a valid register-field declaration and that
   argument-slot does not support it, it will be rejected. This differs
   from VCL where that declaration would have been included in the alias.

 * The register I may NOT be used as an alias for integer registers. This
   forces a better style of programming.

 * The only immediates that are evaluated are the ones passed to LOI, as
   GAS does not handle float-expressions. This may be extended in the
   future.

 * When running with old syntax, accessing register fields by just adding
   them at the end of the alias is not supported (e.g. mtir dest, srcx),
   as it hurts the readability of the source. Please use the new syntax
   instead (mtir dest, src[x]).

 * When using syntax simplifications, selecting a specific branch of
   the simplification (for example MULA) limits the simplification to
   that specific operand and does not (like VCL) expand back to the
   full simplification. This means that operations like 'mula d,s,t'
   will result in an error.

What about GASP?
----------------

As most will notice, gasp has been removed from newer versions of the
binutils. To reduce the loss of this tool, the contrib/ folder contains
a version of MASP. This version is slightly modified to fix a bug with
comments, and does the job of replacing gasp a lot easier. To enable the
use of this tool, compile and install it, and then pass '--gasp "masp"' as
an argument to OpenVCL. MASP is licensed under the GPL, please read the MASP
documentation for licensing terms.