README.TXT

   1 Information about BIF as of April 2019.\r
   2 \r
   3         Author: Joel Matthew Rees, Amagasaki, Hyogo, Japan.\r
   4                                         https://ja.osdn.net/projects/bif-6809/\r
   5                                         joel.rees+knock at gmail dot 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 from 2000 to 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 THE AUTHORS DISCLAIM ALL \r
  43 WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED \r
  44 WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE\r
  45 AUTHORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL \r
  46 DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR \r
  47 PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER \r
  48 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR \r
  49 PERFORMANCE OF THIS 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 at all to fail to \r
  57 include either the BIFDOC.TXT file and this README.TXT file.\r
  58 \r
  59 In the present world, it also makes no sense to fail to include the \r
  60 source code, or at least a link to a known good repository -- such as \r
  61 \r
  62 https://ja.osdn.net/projects/bif-6809/\r
  63 https://ja.osdn.net/projects/bif-6809/scm/git/bif-6809/\r
  64 \r
  65 \r
  66 If you do something like that and you or anyone that gets the \r
  67 resulting distribution has problems with it, and somebody comes \r
  68 to me looking for help, expect to be teased mercilessly about it. \r
  69 And expect to be on the bottom of my priority list, not out of \r
  70 spite, out of self-protection.\r
  71 \r
  72 -----\r
  73 \r
  74 I have reconstructed something approximating my source disks (using the \r
  75 great emulator, xroar: https://www.6809.org.uk/xroar/ and the imgtool\r
  76 distributed with MAME, along with the *nix tools). Some useful commands \r
  77 are noted in commands.txt.\r
  78 \r
  79 The name of the disk image is (appropriately?) bifsource.dsk. It can be \r
  80 directly attached by xroar's disk emulator tools, and should be similarly \r
  81 useable with VCC, MAME, etc. al.\r
  82 \r
  83 -----\r
  84 \r
  85 The assembler source files are readable by the a variety of text editors,\r
  86 that respond flexibly about line termination. But if you try editing them\r
  87 with a normal editor and then assembling the result with EDTASM+, be very \r
  88 careful about line termination. Be prepared to use *nix command line tools \r
  89 like tr, cut, sed/awk, perl, etc. \r
  90 \r
  91 The source files retain the original line numbers as used by EDTASM+, \r
  92 which is why you will want the *nix tools. But I have included source to a \r
  93 short C program, stripln.c, which strips the line numbers. This program \r
  94 may also be useful for converting line endings, if that is necessary. Look \r
  95 for it in the junkbox directory, and be prepared to compile it. \r
  96 \r
  97 If you are under the burden of using Microsoft OSses, the Cygwin project \r
  98 should be of quite a bit of assistance, including the *nix command line \r
  99 tools and gcc and clang, etc.\r
 100 \r
 101 -----\r
 102 \r
 103 Macros are used in the source, but shouldn't cause too much confusion \r
 104 to a programmer with assembler experience. If anyone is brave enough \r
 105 to try to port it, key routines will be EMIT, KEY, ?TERMINAL, CR, R/W, \r
 106 and several routines in the EDITOR vocabulary where I used direct \r
 107 video I/O out of laziness.\r
 108 \r
 109 -----\r
 110 \r
 111 BIF might be useful for experimentation and for learning about FORTH, \r
 112 for someone who has access to a Color Computer or an emulator. The \r
 113 executable file may be run on the Color Computer by LOADMing it via \r
 114 Color Computer Disk BASIC. (More details in BIFDOC.TXT.) \r
 115 \r
 116 It is assembled to be EXECed at hexadecimal 1300 (&H1300). \r
 117 \r
 118 -----\r
 119 \r
 120 One specific warning must be given:\r
 121 \r
 122 DO NOT ATTEMPT TO ACCESS ORDINARY DISKS FORMATTED FOR USE BY OTHER\r
 123 OPERATING SYSTEMS WHILE BIF IS RUNNING! Because of disk buffering, it \r
 124 will be difficult to avoid unintentional writes to the disk. \r
 125 \r
 126 If you do try looking at an OS-9 or Color Computer DOS (etc.) disk with \r
 127 BIF, don't blame me if you destroy the directory and/or other valuable \r
 128 data.\r
 129 \r
 130 -----\r
 131 \r
 132 I tried a re-write in C (bif-c), but it's not working well. Issues with \r
 133 file systems (no real file system in BIF) and the current standardization \r
 134 committees ideas about what is meaningful code, problems with my own \r
 135 attention span, etc. keep it full of bugs. And I used a number of neat \r
 136 tricks that get in the way in C. \r
 137 \r
 138 One thing I want to retain is the use of nested binary trees in the \r
 139 symbol table. \r
 140 \r
 141 Incidentally, said re-write has been in process for over thirty years.\r
 142 Real life keeps getting in the way.\r
 143 \r
 144 -----\r
 145 \r
 146 I am including source to a Q&D C program, 32col.c, which will re-format \r
 147 files extracted from BIF disks for normal text editors. Mac-isms and \r
 148 Codwarrior-isms can probably be discerned by comparing it with stripln.c, \r
 149 mentioned above. \r
 150 \r
 151 When I brought the BIF high-level source with me, I used some feature of \r
 152 Color Computer BASIC and BIF that I have forgotten to dump some of the \r
 153 Forth style screen listings. \r
 154 \r
 155 The program stripln can be used to strip line numbers from such screen \r
 156 listings, as well. \r
 157 \r
 158 I really should put in more work on the tools for converting between \r
 159 normal text files and Forth/BIF screens, but those projects aren't even \r
 160 on my back burners any more. Maybe later. In the meantime, you're \r
 161 welcome to take a crack at it.\r
 162 \r
 163 -----\r
 164 \r
 165 The documentation is ASCII text, with CR/LF line termination, and should\r
 166 be examined carefully by anyone considering a port.  Bear in mind that\r
 167 it was written toward Color Computer users.\r
 168 \r
 169 I apologize for not alphabetizing the FORTH words by name. I did it once \r
 170 with a C program, but got too ambitious and lost the results in the \r
 171 process of trying to split it up into modules. I haven't had enough time \r
 172 to finish the modularization, yet, either. (Getting an iBook so I could \r
 173 work on the train just gave me more things to do on the train.)\r
 174 \r
 175 -----\r
 176 \r
 177 There are four subdirectories at this point:\r
 178 \r
 179 * junkbox -- \r
 180 \r
 181 Various tools I've used. Most are one-time tools that might be useful \r
 182 again in a similar situation.\r
 183 \r
 184 * edtasm_v --\r
 185 \r
 186 This is where I'm recreating what I used at college, to use as a baseline\r
 187 in further projects. The code here can be assembled by the disk-based \r
 188 EDTASM+ tools. \r
 189 \r
 190 Put the EDTASM+ disk (image) in the 1st drive (Coco drive 0) and the \r
 191 source code disk (image) in the 2nd (Coco drive 1). Assemble with \r
 192 something like\r
 193 \r
 194    AD BIF6809X.BIN:1 /WE\r
 195 \r
 196 to save the binary in BIF6809X on the 2nd drive (Coco drive 1) and \r
 197 wait for errors so you can see what happened before it scrolls off \r
 198 the screen.\r
 199 \r
 200 I've essentially frozen my work on this version, to provide a point\r
 201 of reference if someone wants to port BIF-6809 to a non-Coco machine.\r
 202 \r
 203 See BIFDOC.TXT for further information about use.\r
 204 \r
 205 * cross_v --\r
 206 \r
 207 I have been using the lwtools assembler and the MAME imgtool utility \r
 208 as the basis of a cross-assembly environment. (See the commands.txt \r
 209 file for clues.) At this point, assembly is successful, and execution \r
 210 succeeds to the point of being able to load the post-fix assembler \r
 211 which I put together for college, which resides in the tools.dsk image.\r
 212 \r
 213 This code is essentially a mirror of edtasm_v, with source code changes\r
 214 that allow assembly using the lwtools assembler, and line endings \r
 215 friendly to *nix tools.\r
 216 \r
 217 Again, see BIFDOC.TXT for further information about use.\r
 218 \r
 219 * reorg_v\r
 220 \r
 221 Now that I have the baseline sort-of re-established, and am able \r
 222 to compile the post-fix assembler and other tools, I'll use the \r
 223 cross-development tools to reorganize and restructure the code \r
 224 to make it more generally useful. \r
 225 \r
 226 That work will start in reorg_v.\r
 227 \r
 228 \r
 229 ===================\r
 230 \r
 231 Files --\r
 232 \r
 233 -----\r
 234 * Top-level directory, ./ :\r
 235 \r
 236 README.TXT\r
 237         this file.\r
 238 \r
 239 BIFDOC.TXT\r
 240         general explanations, including descriptions of every word.\r
 241 \r
 242 commands.txt\r
 243         *nix command lines that I want to remember. May be useful.\r
 244 \r
 245 -----\r
 246 * edtasm_v/ and cross_v/ :\r
 247 \r
 248 BIFU.I\r
 249         structure of the per-user variable page.\r
 250 \r
 251 BIF.M\r
 252         macros, including the inner interpreter (basis of the virtual machine),\r
 253         the dictionary (symbol table) structure offsets,\r
 254         and invocations for the fundamental objects.\r
 255 \r
 256 BIFDP.A\r
 257         things kept in the direct page, \r
 258         including the behaviours for the fundamental objects (was not a good idea after all),\r
 259         and the index to the per user variable page. \r
 260 \r
 261 BIFST.A\r
 262         cold and warm boot routines and the initial value table for the per-user variable page.\r
 263 \r
 264 BIF.ASM\r
 265         the main source file (includes other parts),\r
 266         basic expression evaluation, more of the inner interpreter, \r
 267         basic vocabulary access, basic symbol parsing.\r
 268 \r
 269 BIFB.A\r
 270         basic I/O, more of the inner interpreter, extended expression evaluation,\r
 271         the rest of the basic symbol table access.\r
 272 \r
 273 BIF1.A\r
 274         data movers, common expression evaluation,\r
 275         stack pointer access, more of the inner interpreter,\r
 276         high-level compiler.\r
 277 \r
 278 BIF1B.A\r
 279         common expression evaluation, extended expression evaluation,\r
 280         innards of the high-level compiler, more of the high-level compiler,\r
 281         compiler directive.\r
 282 \r
 283 BIF2.A\r
 284         more common expression evaluation, common constants,\r
 285         I/O constants, character typing constants,\r
 286         symbol table globals, compiler globals, parser globals, I/O globals.\r
 287 \r
 288 BIF2B.A\r
 289         compiler globals, more high-level compiler,\r
 290         more common expression evaluation, formatted output.\r
 291 \r
 292 BIF3.A\r
 293         more basic symbol table, symbol table, more compiler, more formatted output,\r
 294         more data movers, more low-level parser (formatted input), more I/O,\r
 295         more extended expression evaluation, more expression evaluation, \r
 296         more compiler directives, an extension to the inner interpreter.\r
 297 \r
 298 BIF3B.A\r
 299         more formatted output, more innards of the high-level compiler,\r
 300         more high-level compiler.\r
 301 \r
 302 BIF4.A\r
 303         more innards of the expression evaluator, more common expression evaluation,\r
 304         more I/O (buffer handling).\r
 305 \r
 306 BIF4B.A\r
 307         more high-level compiler, more compiler directive.\r
 308 \r
 309 BIF5.A\r
 310         more innards of the high-level compiler, more I/O (buffering),\r
 311         disk access, error handling, more formatted output.\r
 312 \r
 313 BIF5B.A\r
 314         more error handling, screen-based sector (character) editor.\r
 315 \r
 316 BIF6.A\r
 317         more parser (formatted input), I/O (terminal), compiler (input),\r
 318         symbol table (lookup).\r
 319 \r
 320 BIF6B.A\r
 321         symbol table, compiler innards, null vector test, \r
 322         more screen-based sector editor.\r
 323 \r
 324 BIF7.A\r
 325         compiler, formatted output, compiler directives\r
 326 \r
 327 BIF7B.A\r
 328         error handling, symbol tables, compiler directives.\r
 329 \r
 330 bifsource.dsk\r
 331         The Color Computer Disk Extended BASIC format disk image with \r
 332         the above assembly language source files readable under EDTASM+ . \r
 333 \r
 334         Under cross_v, the only interesting file in bifsource.dsk is the \r
 335         object file, BIF6809.BIN, which is the output of the lwtools \r
 336         assembler. I'm reusing the disk image from edtasm_v for my own \r
 337         convenience. \r
 338 \r
 339 tools.dsk\r
 340         The startup disk for the FORTH/BIF system. \r
 341 \r
 342         You basically want this disk (image) in your first drive whenever\r
 343         bif-6809 is running.\r
 344 \r
 345         Important contents include the following:\r
 346 \r
 347         SCREEN 0: Human readable index. (Forth had no file system of its own.)\r
 348 \r
 349         SCREEN 4: Human readable error message text. \r
 350 \r
 351         SCREEN 6: Basic disk SCREEN (sector, for Coco) listing and editing tools.\r
 352 \r
 353         SCREEN 16: Post-fix assembler.\r
 354 \r
 355         Once you get used to it, you can copy the error messages in \r
 356         SCREEN 4 of the tools.dsk (image) to a fresh disk (image) and \r
 357         use it instead. (And you'll probably want SCREENs 6-15, as well.)\r
 358 \r
 359 blank.dsk (not present)\r
 360         You can make blank, unformatted disk images with a *nix command\r
 361         something like\r
 362 \r
 363         dd if=/dev/zero of=blank.dsk bs=256 count=630\r
 364 \r
 365 -----\r
 366 * reorg_v\r
 367 \r
 368 (More later.)\r
 369 \r
 370 \r
 371 -----\r
 372 * junkbox\r
 373 \r
 374 stripln.c,\r
 375 32col.c, \r
 376         C language source and Macintosh executables for stripping line \r
 377         numbers and reformatting 32 column source code "screens". The two \r
 378         XXX.GXX.out files below are output of the 32col program.\r
 379 \r
 380 TOOLS.G00, TOOLS.G00.out\r
 381         FORTH source for disk listing, screen handling, definition dumping, \r
 382         sector copying, forward referencing, buffer maintenance, \r
 383         experimenting with hardware, double (32 bit) integer math, etc.,\r
 384         and a post-fix assembler.\r
 385 \r
 386         This is how I brought the contents of the tools.dsk image with \r
 387         me. Probably not useful to anyone except me.\r
 388 \r
 389 PAIRS.G28, PAIRS.G28.out\r
 390         a "database" example from one of my FORTH books. Might be \r
 391         interesting for those wondering how the dictionary (symbol\r
 392         table) works.\r
 393 \r
 394 TOOLS_G00_ERRORS.text\r
 395         Contains the tools output readable in regular text editor format \r
 396         and the error messages, with their corresponding number in \r
 397         hexadecimal. I should make a separate file for the error messages\r
 398         (or something).\r
 399 \r
 400         This may be useful for understanding the contents of tools.dsk .\r
 401 \r
 402 SCR33.ARR\r
 403         One way to do arrays. Probably not useful for anyone except me.\r
 404 \r
 405 SCR34.LOC\r
 406         Some random math. Probably not useful for anyone except me.\r
 407 \r
 408 SCR40.431\r
 409         A test suite. Probably not useful for anyone except me.\r
 410 \r
 411 ===================\r
 412 \r
 413 \r