The SMOKE-16 Tools ---------------------------------------------------
$Id: README,v 1.30 2002/07/28 23:26:33 bsittler Exp $
These tools simulate a virtual 16-bit RISC-like processor. I named it
SMOKE-16. Currently they only simulate the user mode, so you can't yet
port an O.S. to it. Included with the tools are several test programs
in SMOKE-16 assembler. There isn't yet a SMOKE-16 C compiler worth
using.                                                          --BCWS
----------------------------------------------------------------------

Note: The '.h' files mentioned below are in the 'include/smoke16' directory.
      The '.c' files are in the 'src' directory.

MODIFICATION AND REDISTRIBUTION

The file 'hashpjw.c' is derived from an algorithm found in Aho,
Sethi and Ullman's {Compilers: Principles, Techniques and Tools},
published by Addison-Wesley. This algorithm comes from
P.J. Weinberger's C compiler. I hereby place 'hashpjw.c' and
'hashpjw.h' in the public domain. To the best of my knowledge, the
algorithm is not patented.

With the exception of 'hashpjw.c' and 'hashpjw.h', this software is
distributed under the terms of the GNU General Public License, Version
2. See the accompanying COPYING for details. Programs are not
automatically derived from the SMOKE-16 tools just because they use
the SMOKE-16 system calls, so if you do not use the SMOKE-16 C library
(or if you manage to make dynamic linking work) in your program, then
your program will not automatically fall under the GNU General Public
License. This does not, however, preclude any other reason your
program might fall under the GNU General Public License.

CONTRIBUTION

If you contribute anything to this software, I encourage you to keep
the copyright for your contribution and to clearly comment it as being
copyrighted by you. I also encourage you to add a brief description of
your contribution, along with your name and the date you wrote your
contribution to the accompanying CREDITS file.

DOCUMENTATION

See the 'doc' directory. There isn't much there yet. Try the '--help'
option with the development tools, and read the source ;). The
assembler syntax is similar to that used by gas, but is far more
limited. I use the C preprocessor to make my assembly more readable
(see 'asm.h',) but may switch to gasp (the GNU assembly preprocessor)
for future releases.

RELEASE NUMBERS

Each release of the SMOKE-16 toolset is datestamped and the RCS
revision numbers of all files are recorded in an appropriate file in
the 'releases' directory. At this stage many files still change their
names, so the release files are not yet very useful for reconstructing
working copies of previous releases.

BUILDING

The toolset has been developed using several ports of the GNU tools,
so compiling on systems without gcc, bison, flex, and GNU make still
requires some effort.

* QUICK-AND-DIRTY

Linux and SunOS
   sh mkdirs
   make CC=gcc all test

Cygwin32, EMX and DJGPP:
   mkdirs
   make CC=gcc EXE_SUFFIX=.exe BAK_SUFFIX=.bak all test

* EXPLAINED

If you got the SMOKE-16 tools out of a ZIP file, you need to run the
'mkdirs' script to remake the output directories. If you're using
COMMAND.COM, try 'mkdirs.bat' instead.

If you're in a non-UNIX development environment, you might need to
change the file suffix macros in 'Makefile'. In particular, OS/2, DOS
and Windows users may wish to set 'EXE_SUFFIX=.exe' and
'BAK_SUFFIX=.bak'.

Next, run 'make'. If that doesn't work, try hacking it for your
architecture. If you have any success, send me the results.  After
(and if) you get 'make' to work, try 'bin/emu' with one of the
executables in 'bin16'. Some interesting options for 'bin/emu' are
'-disassemble', '-trace' and '-registers'. You can run 'make test' to
automatically run a few basic tests of the tools and test programs.

You can safely ignore preprocessor warnings about
__USER_LABEL_PREFIX__ being redefined. The GNU version of cpp doesn't
really expect to be used as a preprocessor for cross-targetted
assembly, but it works fine despite that warning.

You can make the tools very verbose by defining various DEBUG_*
symbols. See the source for specific debugging tokens. Note that some
options for 'bin/emu' are not available unless you define
corresponding DEBUG_* symbols. These may be defined in 'emu.c'.

If you define DEBUG_CRT in 'libc/src16/crt.s', libc will attempt to
check your SMOKE-16 programs for conformance to the calling
conventions described in 'doc/opcodes.txt'.

If you'd like to build all SMOKE-16 executables without symbol tables,
edit the LD16FLAGS variable in 'Makefile'. You can strip already-built
executables using ld -s.

MAGIC NUMBERS

If you'd like the 'file' command to know about SMOKE-16 object files,
add the contents of 'magic' to your magic file (usually /etc/magic or
/usr/lib/magic) or use it with '-m' option. Note that the 'file'
command included in some older Linux distributions is buggy.

TRANSPARENT BINARY EMULATION (Linux)

If you run Linux, and you've installed the 'binfmt_misc' binary
emulation subsystem, you can transparently execute SMOKE-16
executables using the 'emu--' version of the emulator. Run the
'regbfmts' script (but you may have to edit it first.)

Once you do this, you can invoke SMOKE-16 programs directly.

LIMITATIONS, BUGS, SHORTCOMINGS, TO DO...

- Some of the opcodes may not be implemented correctly in 'emu.c'.
  There should be a regression test for each opcode.

- The linker does not support common-format archives. Instead it
  uses an interim object archive format (LMAGIC) based on the a.out
  file format.

- There is no C compiler for the SMOKE-16. I desire a C compiler that
  is self-hosting, so this may take a while.

- There is no symbolic debugger for the SMOKE-16. The user-mode
  emulator (emu.c) is an obvious place to start hacking, since
  it already prints symbolic addresses when '-disassemble' or
  '-registers' causes the %pc register or other addresses to be
  printed.

- The user-mode emulator (emu.c) is fairly stable, but the
  processor simulator (sim.c) hasn't been written yet.
  This is not a high priority yet.

- SMOKE-16 has about thirty opcodes, since the instruction word is 16
  bits long. This can be rather restricting at times. The multi-word
  pseudo-instructions make this less of an issue than it once was.

- The number of syscalls that have actually been implemented is
  pitifully small. Nothing truly useful is yet possible, I'm afraid.
  Especially nice would be full I/O and signals.

- True binary compatibility across platforms is impossible, since
  emu uses <errno.h> for the errors returned by syscalls and passes
  host O.S. errno directly to the SMOKE-16 program. However, it may be
  "good enough".

- String portability to non-ASCII platforms is a troublesome
  issue. You can assemble portable executables using the '-portable'
  option to 'as', but the resulting executables will only work
  correctly when the emulator is run on an ASCII-compatible host. The
  problem is that the emulator passes SMOKE-16 strings directly to the
  host environment's C library, without performing any sort of
  character-set translation. One solution might be to write a SMOKE-16
  machine simulator, which could perform the translations at the
  'virtual console' level, and allow SMOKE-16 programs to communicate
  with the host machine using protocols like HTTP or NFS (which are
  ASCII-based,) thereby placing the translation onus on the host
  machine. The SMOKE-16 portable character encoding is documented in
  'doc/portable.txt'.

- Various versions of the tools have been built and tested under MacOS
  X, DJGPP (DOS/Win95), Linux (x86, alpha, sparc and ppc), Cygnus
  GNU-Win32 (Win95/NT), EMX (DOS, Win31, WinNT, OS/2), Solaris 2.5 and
  SunOS 4. More testing is needed. If you make changes to get the
  tools to compile for you, let me know what you did so I can add it
  to the main distribution. You can also add an entry to the 'CREDITS'
  file.

If there's anything I've missed, or anything you feel should be added
to this file, send me a patch or an updated copy.

All trademarks used are the property of their respective owners.
