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 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.