From ec522f259ed1f7b11fd6ab2e850194c4c0491115 Mon Sep 17 00:00:00 2001 From: Peter Evans Date: Mon, 12 Feb 2018 21:15:20 -0600 Subject: [PATCH] Add block comments to describe source files --- src/apple2.bank.c | 11 +++++++++++ src/apple2.c | 5 +++-- src/apple2.dbuf.c | 6 ++++++ src/apple2.dd.c | 7 +++++++ src/apple2.dec.c | 3 +++ src/apple2.draw.c | 4 ++++ src/apple2.enc.c | 9 +++++++++ src/apple2.kb.c | 5 +++++ src/apple2.mem.c | 5 +++++ src/apple2.reflect.c | 3 +++ src/mos6502.dis.c | 22 +++++++++++++++++++++- src/objstore.c | 5 +++++ src/vm_area.c | 7 +++++++ src/vm_bitfont.c | 9 +++++++++ src/vm_event.c | 5 +++++ src/vm_reflect.c | 4 ++++ 16 files changed, 107 insertions(+), 3 deletions(-) diff --git a/src/apple2.bank.c b/src/apple2.bank.c index 44e28aa..fe3540e 100644 --- a/src/apple2.bank.c +++ b/src/apple2.bank.c @@ -1,5 +1,16 @@ /* * apple2.bank.c + * + * Handle reads and writes to bank-switchable memory, as well as the + * soft switches that manage access to bank-switched memory spaces. + * Bank-switchable memory is located from $D000..$FFFF, and those + * addresses may point to 1) system ROM; 2) main memory RAM; 3) + * auxiliary memory RAM; 4) a separate 4k bank of RAM in the + * $D000..$DFFF range, one for _each_ of main and aux memory. That is, + * you are allowed to fit a separate 16k RAM in 12k address space for + * both main and auxiliary memory. + * + * Are you confused yet? Keep reading! */ #include "apple2.h" diff --git a/src/apple2.c b/src/apple2.c index 0cdcb82..7590ded 100644 --- a/src/apple2.c +++ b/src/apple2.c @@ -1,8 +1,9 @@ /* * apple2.c * - * Here we have support for the apple2 machine. I suspect that we will - * need to break this file up into components in the future... + * This file handles the top-level domain code for the Apple II machine. + * It's also a bit of a catch-all for logic which doesn't need its own + * file. */ #include diff --git a/src/apple2.dbuf.c b/src/apple2.dbuf.c index 210814c..c1220e0 100644 --- a/src/apple2.dbuf.c +++ b/src/apple2.dbuf.c @@ -1,5 +1,11 @@ /* * apple2.dbuf.c + * + * Handle reads and writes to our display buffers and the soft switches + * that manage them. There are a number of conditions which may cause + * our I/O to use the auxiliary memory segment instead of the main one; + * additionally, we can signal to the VM that we need to redraw stuff + * when writes do happen. */ #include "apple2.dbuf.h" diff --git a/src/apple2.dd.c b/src/apple2.dd.c index 7b062ee..687d1b1 100644 --- a/src/apple2.dd.c +++ b/src/apple2.dd.c @@ -1,5 +1,12 @@ /* * apple2.dd.c + * + * This file encompasses the logic we use to handle disk drives in the + * Apple II machine. You'll find a lot of references to what may seem to + * be hardware implementation details, like stepper motor phases, but + * these are necessary because those details were exposed to software, + * and software was required to use those details to correctly position + * itself. */ #include "apple2.dd.h" diff --git a/src/apple2.dec.c b/src/apple2.dec.c index 6b5f15d..c88c0e5 100644 --- a/src/apple2.dec.c +++ b/src/apple2.dec.c @@ -1,5 +1,8 @@ /* * apple2.dec.c + * + * Decode 6-and-2 encoding to get back to the "raw" state that image + * data has. You can read more on why this is necessary in apple2.enc.c. */ #include diff --git a/src/apple2.draw.c b/src/apple2.draw.c index 52b2420..602af48 100644 --- a/src/apple2.draw.c +++ b/src/apple2.draw.c @@ -1,5 +1,9 @@ /* * apple2.draw.c + * + * Draw pretty pixels on the screen in the way that Apple II would work. + * NB: this code is pretty rough, and I expect some changes as we get + * further into development. */ #include "apple2.h" diff --git a/src/apple2.enc.c b/src/apple2.enc.c index b9b9701..c3451a3 100644 --- a/src/apple2.enc.c +++ b/src/apple2.enc.c @@ -1,5 +1,14 @@ /* * apple2.enc.c + * + * Encode disk image data with 6-and-2 encoding, which in effect + * "nibbilizes" them (in exactly the way a .NIB file is saved). This + * process is somewhat complicated, and I don't blame you if you gently + * bop your head on your desk and ask woz, pleadingly, why, why, why. + * + * The reason for "why" is that early disk drives were pretty limited, + * and specifically could not have zero bits next to each other. Which + * is _crazy_. Hence the crazy code below. */ #include "apple2.enc.h" diff --git a/src/apple2.kb.c b/src/apple2.kb.c index 039faf1..a073740 100644 --- a/src/apple2.kb.c +++ b/src/apple2.kb.c @@ -1,5 +1,10 @@ /* * apple2.kb.c + * + * Handle soft switches to read keyboard state, which are surprisingly + * few and lightweight. The state would be the last key pressed, whether + * a key is pressed _right now_, and the keyboard strobe (which is used + * to determine if you've read last key pressed before or not). */ #include "apple2.kb.h" diff --git a/src/apple2.mem.c b/src/apple2.mem.c index ed720f8..c5c2230 100644 --- a/src/apple2.mem.c +++ b/src/apple2.mem.c @@ -1,5 +1,10 @@ /* * apple2.mem.c + * + * Implement code to handle soft switches for memory modes in Apple II, + * to handle zero-page accesses, and to handle ROM initialization. If + * that sounds like a lot of not-necessarily-related stuff, you're + * right! FIXME: we should break this file up into smaller parts. */ #include "apple2.bank.h" diff --git a/src/apple2.reflect.c b/src/apple2.reflect.c index 7c16d42..bdace0b 100644 --- a/src/apple2.reflect.c +++ b/src/apple2.reflect.c @@ -1,5 +1,8 @@ /* * apple2.reflect.c + * + * Implement the reflection handlers for the virtual machine when the + * apple2 machine is being emulated. */ #include "apple2.h" diff --git a/src/mos6502.dis.c b/src/mos6502.dis.c index be240e1..19b77cd 100644 --- a/src/mos6502.dis.c +++ b/src/mos6502.dis.c @@ -1,7 +1,27 @@ /* * mos6502.dis.c * - * Disassembly of the mos6502 machine code into an assembly notation. + * Disassembly of the mos6502 machine code into an assembly notation. I + * should note that there is no formal grammar (that I know of!) for + * 6502 assembly--just an informal notation that is de-facto supported + * by one assembler or another. The general format we use is as follows: + * + * LABEL: + * INS $OPER ; comment + * + * Where LABEL is a--well, a label; INS is an instruction; $OPER is a + * hexadecimal number; and a semicolon denotes a comment follows until + * the end of the line. + * + * You will find a number of variants of `$OPER`, as the assembly + * notation uses those variants to denote a specific kind of address + * mode. `$OPER` is absolute mode; `$OP` (just two hex digits) is + * zero-page mode; `$(OP),Y` is indirect-indexed mode; etc. (Please + * refer to mos6502.addr.c for more details on those modes!) + * + * The code here generally pushes disassembled notation into FILE stream + * objects. If you need them in a string, for instance, you can mess + * with `setvbuf()` (as we indeed do in our unit-testing code!). */ #include diff --git a/src/objstore.c b/src/objstore.c index fffce0e..0eab91f 100644 --- a/src/objstore.c +++ b/src/objstore.c @@ -1,5 +1,10 @@ /* * objstore.c + * + * The code here allows us to work with the object store, which is an + * entity that allows us to toss all of our binary data needs into a big + * glob of stuff that we can unpack and use at runtime. Examples of such + * data are bitmap fonts, ROM data, etc. */ #include diff --git a/src/vm_area.c b/src/vm_area.c index 3990ee3..6097edc 100644 --- a/src/vm_area.c +++ b/src/vm_area.c @@ -1,5 +1,12 @@ /* * vm_area.c + * + * The area code defines a library-independent "area" struct, because we + * don't want to write virtual machine code which makes literal use of + * SDL_Rects. Any time you need to pass a screen area (which would be a + * rectangle of a certain width and height, offset from the top-left of + * the screen by a given x/y coordinate), you would use a vm_area + * struct to do so. */ #include "vm_area.h" diff --git a/src/vm_bitfont.c b/src/vm_bitfont.c index ad55c5c..e9f0401 100644 --- a/src/vm_bitfont.c +++ b/src/vm_bitfont.c @@ -1,5 +1,14 @@ /* * vm_bitfont.c + * + * The bitfont code allows us to define and work with a bitmapped font. + * You can find the bitmap font glyphs in the `/fonts` subdir within the + * repository root, as well as bmp files that are compiled from those + * glyphs (via `/tools/build-fonts`). + * + * We do not have support for truetype fonts (nor other types of fonts) + * at this time, but the glyph system is pretty easy to work with, even + * if it is a hack. */ #include "vm_bitfont.h" diff --git a/src/vm_event.c b/src/vm_event.c index f65c8aa..a85ba04 100644 --- a/src/vm_event.c +++ b/src/vm_event.c @@ -1,5 +1,10 @@ /* * vm_event.c + * + * The code here handles events for the virtual machine; it essentially + * is a wrapper for SDL, presenting an interface to events that is + * independent of SDL itself. You would handle keyboard events here, + * mouse events, and more. */ #include "vm_event.h" diff --git a/src/vm_reflect.c b/src/vm_reflect.c index e808cf6..1617474 100644 --- a/src/vm_reflect.c +++ b/src/vm_reflect.c @@ -1,5 +1,9 @@ /* * vm_reflect.c + * + * Here we have support for reflection, or perhaps meta-manipulation, of + * the virtual machine. You can create hooks to stop the machine, or + * disassemble opcodes from it, or handle state. */ #include