Usage instructions
==================

SC is a language with a C-like syntax. An SC program consists of the .sc source files in the current
directory, along with the source files in any specified module search paths. Each .sc source file
contains the code for the module with the same name. 
.. TODO details: modules, what compiles, etc

This is a simple SC program showing the syntax::

    byte foo = 4;

    void main()
    {
        byte bar;

        bar = 3;

        while (foo != 2)
        {
            foo = bar;
            bar--;
        }

        doTheFoo(5);
    }

    void doTheFoo(byte bar)
    {
        foo = bar + 2;
    }

To use functions and data fields from other modules, prefix their name with the module name and a
period. For example, ``foo.bar = 42;`` assigns ``42`` to the ``bar`` data field in the ``foo`` module.

.. TODO reference language spec

To compile the program, run ``scc.py``. If you want to specify a module search path, use the ``-m``
option. ``-m`` can be used multiple times to specify more search paths. Use the ``--help`` option to
see all options.

Assembling
----------

The compiler writes the output assembly to ``output.asm``. Use ``as504 output.asm`` (or ``as504.py
output.asm`` on Windows) to assemble the output and create ``output.hex``.

Uploading
---------

The uploader uses a subset of the functionality of the debugger. It's intended to quickly upload a
program to the board.

Run ``uploader.py SERIALPORT output.hex``, where ``SERIALPORT`` is the serial port on which the
board is connected.
To see which ports are available on your system, run ``uploader.py --list-ports``.
If you use an USB serial port, please install the driver if the port is not visible.

Sometimes, the hardware is in an incorrect state to receive commands, sometimes even directly after
a powering on. If this is the case, the uploader will warn that the board is not responding. Press
the reset button on the board to continue.

Debugging
---------

The debugger is an interactive command-line program that can show the current program execution
location, memory and register contents and allows single stepping.

Start the debugger with ``debugger.py SERIALPORT``. Like the uploader, ``debugger.py --list-ports``
shows the available ports on your system. (For listing ports, there's no difference between the
two.)

These commands are available in the debugger:

``list``: Shows the previous, current and next instructions located around the program counter. If
you add an address (like ``list 04A1``), it shows the instructions around that location. This
command requires debug information loaded with the ``load`` command.

``show <variable>``: Shows the contents of the specified variable. The variable name must contain
the module name, like ``show main.counter``.

``mem <location> <address>``: Shows the contents of a memory block. The location must be one of
direct, indirect, external and code, and may be abbreviated. Example: ``mem direct 3b``. The 32 byte
block containing that address is shown.

``step``: Executes one instruction. If you add a number (like ``step 12``), that number of
instructions are executed.

``load <filename>``: Uploads a program to the board and loads associated debug information, if
present. Uploading a program does only changes memory that will contain the program. Other memory
(including registers) is not reset.

``loaddebug <filename>``: Loads the debug information for a program. This is useful if the program
has already been uploaded but the debug information hasn't been loaded yet.

``run``: Starts execution of the program.

``stop``: Stops execution of the program. In certain conditions, the monitor program on the board
does not process the stop command. In that case, you have to reset the board to stop execution.
Note that resetting the board modifies the program counter and the special function registers.

``reset``: Sets the program counter to 0. This does not reset memory or special function registers.

``exit``: Quits the debugger.


.. vim: tw=100