DDDCPU16 - DeathlyDeep's DCPU16, a DCPU16 emulator.

=== SUMMARY ====================================================================

DDDCPU16 is a DCPU16 emulator written by Sylvain "DeathlyDeep" Boilard, student
at French IT engineer school EFREI, while he had way more urgent things to do.

The DCPU16 is an imaginary CPU designed by Markus "Notch" Personn for his
eventually-upcoming, nerd-friendly, space-exploration-and-stuff game "0x10c".

This software features efficient DCPU16 emulation, at arbitrary speed and
frequency, and a plugin system, mainly used for hardware emulation and
debugging. It runs on GNU/Linux and should be easy to port on any other
POSIX-friendly system.

Currently (and when I am not too lazy) development efforts are focused on
hardware support. See the TODO section of this file.

DDDCPU16 is hosted on GitHub at https://github.com/DeathlyDeep/DDDCPU16 .

=== USAGE ======================================================================

Synopsis:

  dddcpu16 [options...] ram_image

ram_image
    The content of this binary file will be loaded in the RAM on the DCPU16 at
    the beginning of the emulation, and the execution will begin at address 0.
    You can generate this file by running a DASM16 assembler on a DASM16 source
    file, but DDDCPU16 does not provide such a tool.


Options:

The options are evaluated from left to right so, for example, if you set the
emulation speed twice, the second value will be recorded.

-s speed
    Select the speed of the emulation. Default is 1. Do not confuse with
    emulation frequency, which is a different value.

    This value can be a decimal value with up to 3 digits in the decimal part.
    For example, with a value of 0.125 , you will slow the emulation speed to
    1/8 of the normal behaviour.

-f frequency
    Select the frequency of the emulation. Default is 100kHz. Do not confuse
    with emulation speed, which is a different value.

    This value can be suffixed with Hz, kHz, MHz or GHz to indicate a value
    expressed in Hertz, kilo-Hertz, mega-Hertz or giga-Hertz. If no suffix is
    given, the value is considered to be in Hertz.

-p plugin [options...] [--]
    Load a plugin. You can pass options to the plugin by adding them after the
    plugin's name, and you can separate the plugin's options from the rest of
    the command line with --. So, if you want to load multiple plugins, you will
    go with something like this:

    $ dddcpu16 ram_image.bin -p clock.so -- -p m35fd.so

-B, -L
    Select desired endianness (Big or Little) for the ram image. Default is
    little endian.

-G granularity
    Select time granularity. The value can be suffixed with ms, us or ns to give
    a value in milli, micro or nano-seconds. If no suffix is added, the value is
    considered to be nanoseconds. This value must be lesser than 1 second.
    Default is 1 millisecond.

    This value represents the granularity of time for the emulation process. For
    example, with default values of frequency and speed, a granularity of 1
    millisecond means that, each millisecond,
      * 100 emulation cycles are performed.
      * If less than a millisecond passed, the emulator sleeps the time needed
        to match this delay.

    Doing this is necessary because the overhead of the sleep function is not
    negligible, and sleeping between each instruction would simply not work.
    (This does not mean that the emulation timing is imprecise. The overhead of
    time spent to sleep and the overhead of cycles executed during a time chunk
    are compensated in the next chunk, leading to correct behaviour
    asymptotically.)

    If for some reasons you need a smoother emulation, try to decrease this
    value. If you want to run the emulator at a high speed and/or frequency but
    end up using all of your computer's resources, you can enhance a bit the
    performance of the emulator by increasing it.


Commands:

 * quit

    Exit gracefully from the emulator.

=== PLUGINS USAGE ==============================================================
====== CLOCK PLUGIN ============================================================

Synopsis:

  clock.so [clock_number]

clock_number
    Select the number of clocks to connect to the DCPU16. Default is 1.

====== M35FD PLUGIN ============================================================

Synopsis:

  m35fd.so [options...]

Options:

-n m35fd_number
    Select the number of m35fd to connect to the DCPU16. Default is 1.

-B,-L
    Select default endianness (Big or Little) for the newly inserted floppies.
    Default is little endian.


Commands:

 * m35fd.insert [options...] floppy

    Inserts a floppy in a drive.

floppy
    This file will be used to read and possibly write the floppy. If it does not
    exist, it will be created.


Options:

-n drive_number
    Select drive in which to insert the floppy. Default is 0.

-p
    Set write protection.

-B,-L
    Select endianness (Big or Little) for the floppy to insert. If this option
    is not present, the default endianness is selected.


 * m35fd.eject [drive_number]

    Ejects a floppy from a drive.

drive_number
    Select drive from which to eject the floppy. Default is 0.


=== RETURN VALUES ==============================================================

0 : Everything went well.
1 : Wrong argument in command line.
2 : Run-time error.

=== KNOWN BUGS =================================================================

DCPU16 catching fire.
 * The non-basic instruction 0x07 HCF (Hang Catch Fire) is not implemented.
 * If the size of the interrupts queue grows longer than 256, the DCPU16
   processor is supposed to catch fire. Practically, this would lead to random
   words in the RAM getting randomly corrupted every once in a while, quickly
   ending up with chaotic behaviour.

   In DDDCPU16, instead of this, if the size of the queue reaches 256, the queue
   is considered emptied, and subsequent interrupts are then queued normally.

=== TODO =======================================================================

Emulator
 * Add firmware support.
 * Implement a shared configuration system for the core emulator and plugins.
 * Events system
   * Allow arbitrary large number of simultaneous scheduled events.
   * Optimize events canceling.
 * Prevent drifting in emulation timing (none appears with default values, but
   it would be a good idea to do it eventually).
 * Console
   * Allow arbitrary large command lines.
   * Use '\n' as command line terminator instead of supposing the last read
     character is.
   * Add basic 'help' command to list available commands.

Plugins
 * Make plugins get API entries with dlopen instead of via a context structure.
 * Implement debug plugin.
 * Hardware
   * Finish to implement lem1802.
   * Implement keyboard.
   * Implement sped-3.
   * m35fd
     * Allow starting with floppies already inserted.
     * Fix crashing when legitimately trying to access data at the end of a
       floppy while the underlying file is smaller than an entire floppy.

General
 * Check const-correctness.
 * Write documentation.

=== AUTHOR =====================================================================

Sylvain "DeathlyDeep" Boilard
 * e-mail : boilard@crans.org
 * Twitter : @DeathlyDeep
 * GitHub : https://github.com/DeathlyDeep/

=== LICENSE ====================================================================

DDDCPU16 - DeathlyDeep's DCPU16, a DCPU16 emulator.
Copyright (C) 2012-2013 Sylvain Boilard <boilard@crans.org>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.