README.TXT

   1 Information about BIF as of April 2019.\r
   2 \r
   3         Joel Matthew Rees, Amagasaki, Hyogo, Japan.\r
   4                                         https://ja.osdn.net/projects/bif-6809/\r
   5                                         joel.rees+knock@gmail.com\r
   6                                         http://reiisi.blogspot.com\r
   7                                         https://defining-computers.blogspot.com/\r
   8                                         https://ja.osdn.net/users/reiisi/\r
   9                                         https://sourceforge.net/u/reiisi/profile/\r
  10                                         etc.\r
  11         Copyright 2000, 2019 Joel Matthew Rees\r
  12 \r
  13 -----\r
  14 \r
  15 (The following can be found in its original form in the bif-c \r
  16 repositories. bif-c is buggy, by the way.)\r
  17 \r
  18 -----\r
  19 \r
  20 BIF was a dialect of the early fig-standard FORTH.  It was a student\r
  21 project, not a commercial product, and no warranty has ever been made \r
  22 concerning it, whatsoever.  It was written on the Color Computer 2 in \r
  23 6809 assembler; the assembler used was disk EDTASM+.  It also ran on \r
  24 the Color Computer 3, with the expected limitations of requiring the \r
  25 32 column screen, etc. \r
  26 \r
  27 License information -- the rights to BIF and the materials with it, \r
  28 and restrictions on distribution -- are described in the file \r
  29 BIFDOC.TXT, which really should distributed with the source along with \r
  30 this README.TXT. \r
  31 \r
  32 The short version of the licensing information is that I am distributing \r
  33 BIF6809 under the essential terms of the Internet Systems Consortium \r
  34 ISC License:\r
  35 \r
  36 =========\r
  37 Permission to use, copy, modify, and/or distribute this software for \r
  38 any purpose with or without fee is hereby granted, provided that the \r
  39 accompanying copyright notices and this permission notice appear in \r
  40 all copies.\r
  41 \r
  42 THE SOFTWARE IS PROVIDED “AS IS” AND ISC DISCLAIMS ALL WARRANTIES \r
  43 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF \r
  44 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY \r
  45 SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES \r
  46 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN \r
  47 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, \r
  48 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS \r
  49 SOFTWARE.\r
  50 =========\r
  51 \r
  52 I add here the stipulation that I claim right to the word "BIF" as \r
  53 the name of a programming language.\r
  54 \r
  55 If you are going to distribute or redistribute the obect or source of \r
  56 bif in any of its forms, it really makes no sense not to include the \r
  57 BIFDOC.TXT and this README.TXT. If you do something like that and \r
  58 you or anyone that gets the results has problems with it, and you come \r
  59 to me looking for help, expect to be teased mercilessly about it. And \r
  60 expect to be on the bottom of my priority list, not out of spite, \r
  61 out of self-protection.\r
  62 \r
  63 -----\r
  64 \r
  65 I have reconstructed something approximating my source disks (using the \r
  66 great emulator, xroar: https://www.6809.org.uk/xroar/ and the imgtool\r
  67 distributed with MAME, along with the *nix tools). Some useful commands \r
  68 are noted in commands.txt.\r
  69 \r
  70 The name of the disk image is (appropriately?) bifsource.dsk. It can be \r
  71 directly attached by xroar's disk emulator tools, and should be similarly \r
  72 useable with VCC, MAME, etc. al.\r
  73 \r
  74 -----\r
  75 \r
  76 The assembler source files are readable by the a variety of text editors,\r
  77 that respond flexibly about line termination. But if you try editing them\r
  78 with a normal editor and then assembling the result with EDTASM+, be very \r
  79 careful about line termination. Be prepared to use *nix command line tools \r
  80 like tr, cut, sed/awk, perl, etc. \r
  81 \r
  82 The source files retain the original line numbers as used by EDTASM+, \r
  83 which is why you will want the *nix tools. But I have included source to a \r
  84 short C program, stripln.c, which strips the line numbers. This program \r
  85 may also be useful for converting line endings, if that is necessary. Look \r
  86 for it in the junkbox directory, and be prepared to compile it. \r
  87 \r
  88 If you are under the burden of using Microsoft OSses, the Cygwin project \r
  89 should be of quite a bit of assistance, including the *nix command line \r
  90 tools and gcc and clang, etc.\r
  91 \r
  92 -----\r
  93 \r
  94 Macros are used in the source, but shouldn't cause too much confusion \r
  95 to a programmer with assembler experience. If anyone is brave enough \r
  96 to try to port it, key routines will be EMIT, KEY, ?TERMINAL, CR, R/W, \r
  97 and several routines in the EDITOR vocabulary where I used direct \r
  98 video I/O out of laziness.\r
  99 \r
 100 -----\r
 101 \r
 102 BIF might be useful for experimentation and for learning about FORTH, \r
 103 for someone who has access to a Color Computer or an emulator. The \r
 104 executable file may be run on the Color Computer by LOADMing it via \r
 105 Color Computer Disk BASIC. (More details in BIFDOC.TXT.) \r
 106 \r
 107 It is assembled to be EXECed at hexadecimal 1300 (&H1300). \r
 108 \r
 109 -----\r
 110 \r
 111 One specific warning must be given:\r
 112 \r
 113 DO NOT ATTEMPT TO ACCESS ORDINARY DISKS FORMATTED FOR USE BY OTHER\r
 114 OPERATING SYSTEMS WHILE BIF IS RUNNING! Because of disk buffering, it \r
 115 will be difficult to avoid unintentional writes to the disk. \r
 116 \r
 117 If you do try looking at an OS-9 or Color Computer DOS (etc.) disk with \r
 118 BIF, don't blame me if you destroy the directory and/or other valuable \r
 119 data.\r
 120 \r
 121 -----\r
 122 \r
 123 I tried a re-write in C (bif-c), but it's not working well. Issues with \r
 124 file systems (no real file system in BIF) and the current standardization \r
 125 committees ideas about what is meaningful code, problems with my own \r
 126 attention span, etc. keep it full of bugs. And I used a number of neat \r
 127 tricks that get in the way in C. \r
 128 \r
 129 One thing I want to retain is the use of nested binary trees in the \r
 130 symbol table. \r
 131 \r
 132 Incidentally, said re-write has been in process for over thirty years.\r
 133 Real life keeps getting in the way.\r
 134 \r
 135 -----\r
 136 \r
 137 I am including source to a Q&D C program, 32col.c, which will re-format \r
 138 files extracted from BIF disks for normal text editors. Mac-isms and \r
 139 Codwarrior-isms can probably be discerned by comparing it with stripln.c, \r
 140 mentioned above. \r
 141 \r
 142 When I brought the BIF high-level source with me, I used some feature of \r
 143 Color Computer BASIC and BIF that I have forgotten to dump some of the \r
 144 Forth style screen listings. \r
 145 \r
 146 The program stripln can be used to strip line numbers from such screen \r
 147 listings, as well. \r
 148 \r
 149 The documentation is ASCII text, with CR/LF line termination, and should\r
 150 be examined carefully by anyone considering a port.  Bear in mind that\r
 151 it was written toward Color Computer users.\r
 152 \r
 153 I apologize for not alphabetizing the FORTH words by name. I did it once \r
 154 with a C program, but got too ambitious and lost the results in the \r
 155 process of trying to split it up into modules. I haven't had enough time \r
 156 to finish the modularization, yet, either. (Getting an iBook so I could \r
 157 work on the train just gave me more things to do on the train.)\r
 158 \r
 159 -----\r
 160 \r
 161 There are three subdirectories at this point:\r
 162 \r
 163 junkbox -- \r
 164 \r
 165 Various tools I've used. Most are one-time tools that might be useful \r
 166 again in a similar situation.\r
 167 \r
 168 edtasm_v --\r
 169 \r
 170 This is where I'm recreating what I used at college, to use as a baseline\r
 171 in further projects.\r
 172 \r
 173 cross_v --\r
 174 \r
 175 Once I have the baseline re-established, and am able to compile the \r
 176 assembler and other tools, I'll switch to using cross-development tools\r
 177 to reorganize and restructure the code to make it more generally useful.\r
 178 \r
 179 -----\r
 180 \r
 181 For the time being, until I get it more-or-less back to the state it \r
 182 was in when I used it in college, I'm focusing on the source in the\r
 183 edtasm_v subdirectory.\r
 184 \r
 185 ===================\r
 186 \r
 187 Files under edtasm_v --\r
 188 \r
 189 6809 Assembly Language Source files under edtasm_v:\r
 190 \r
 191 README.TXT\r
 192         this file.\r
 193 BIFDOC.TXT\r
 194         general explanations, including descriptions of every word.\r
 195 BIFU.I\r
 196         structure of the per-user variable page.\r
 197 BIF.M\r
 198         macros, including the inner interpreter (basis of the virtual machine),\r
 199         the dictionary (symbol table) structure offsets,\r
 200         and invocations for the fundamental objects.\r
 201 BIFDP.A\r
 202         things kept in the direct page, \r
 203         including the behaviours for the fundamental objects (was not a good idea after all),\r
 204         and the index to the per user variable page. \r
 205 BIFST.A\r
 206         cold and warm boot routines and the initial value table for the per-user variable page.\r
 207 BIF.ASM\r
 208         the main source file (includes other parts),\r
 209         basic expression evaluation, more of the inner interpreter, \r
 210         basic vocabulary access, basic symbol parsing.\r
 211 BIFB.A\r
 212         basic I/O, more of the inner interpreter, extended expression evaluation,\r
 213         the rest of the basic symbol table access.\r
 214 BIF1.A\r
 215         data movers, common expression evaluation,\r
 216         stack pointer access, more of the inner interpreter,\r
 217         high-level compiler.\r
 218 BIF1B.A\r
 219         common expression evaluation, extended expression evaluation,\r
 220         innards of the high-level compiler, more of the high-level compiler,\r
 221         compiler directive.\r
 222 BIF2.A\r
 223         more common expression evaluation, common constants,\r
 224         I/O constants, character typing constants,\r
 225         symbol table globals, compiler globals, parser globals, I/O globals.\r
 226 BIF2B.A\r
 227         compiler globals, more high-level compiler,\r
 228         more common expression evaluation, formatted output.\r
 229 BIF3.A\r
 230         more basic symbol table, symbol table, more compiler, more formatted output,\r
 231         more data movers, more low-level parser (formatted input), more I/O,\r
 232         more extended expression evaluation, more expression evaluation, \r
 233         more compiler directives, an extension to the inner interpreter.\r
 234 BIF3B.A\r
 235         more formatted output, more innards of the high-level compiler,\r
 236         more high-level compiler.\r
 237 BIF4.A\r
 238         more innards of the expression evaluator, more common expression evaluation,\r
 239         more I/O (buffer handling).\r
 240 BIF4B.A\r
 241         more high-level compiler, more compiler directive.\r
 242 BIF5.A\r
 243         more innards of the high-level compiler, more I/O (buffering),\r
 244         disk access, error handling, more formatted output.\r
 245 BIF5B.A\r
 246         more error handling, screen-based sector (character) editor.\r
 247 BIF6.A\r
 248         more parser (formatted input), I/O (terminal), compiler (input),\r
 249         symbol table (lookup).\r
 250 BIF6B.A\r
 251         symbol table, compiler innards, null vector test, \r
 252         more screen-based sector editor.\r
 253 BIF7.A\r
 254         compiler, formatted output, compiler directives\r
 255 BIF7B.A\r
 256         error handling, symbol tables, compiler directives.\r
 257 stripln.c,\r
 258 32col.c, \r
 259         C language source and Macintosh executables for stripping line \r
 260         numbers and reformatting 32 column source code "screens". The two \r
 261         XXX.GXX.out files below are output of the 32col program.\r
 262 \r
 263 -----\r
 264 \r
 265 Hopefully, I will shortly have time to reconstruct useful things from the \r
 266 following files on the tools.dsk disk image and/or the cs431 disk image:\r
 267 \r
 268 TOOLS.G00, TOOLS.G00.out\r
 269         FORTH source for disk listing, screen handling, definition dumping, \r
 270         sector copying, forward referencing, buffer maintenance, \r
 271         experimenting with hardware, double (32 bit) integer math, etc.,\r
 272         and a post-fix assembler.\r
 273 PAIRS.G28, PAIRS.G28.out\r
 274         a "database" example from one of my FORTH books.\r
 275 TOOLS_G00_ERRORS.text\r
 276         Contains the tools output readable in regular text editor format \r
 277         and the error messages, with their corresponding number in \r
 278         hexadecimal. I should make a separate file for the error messages\r
 279         (or something).\r
 280 \r
 281 and\r
 282 \r
 283 SCR33.ARR\r
 284         arrays for CS431.\r
 285 SCR34.LOC\r
 286         some math for CS431.\r
 287 SCR40.431\r
 288         test suite for CS431.\r
 289 \r
 290 ===================\r
 291 \r
 292 \r