4565

3 files changed, 22 insertions, 3 deletions

diff --git a/subx/011run.cc b/subx/011run.cc
index e8c7c4a6..2549ae04 100644
--- a/subx/011run.cc
+++ b/subx/011run.cc
@@ -48,7 +48,10 @@ cerr << "  syntax\n";
 # As you can see, comments start with '#' and are ignored.
 
 # Segment headers start with '==', specifying the hex address where they
-# begin. The first segment is always assumed to be code.
+# begin. There's usually one code segment and one data segment. We assume the
+# code segment always comes first. Later when we emit ELF binaries we'll add
+# directives for the operating system to ensure that the code segment can't be
+# written to, and the data segment can't be executed as code.
 == 0x1
 
 # We don't show it here, but all lines can have metadata after a ':'.
diff --git a/subx/012elf.cc b/subx/012elf.cc
index 3042b6b6..787d914c 100644
--- a/subx/012elf.cc
+++ b/subx/012elf.cc
@@ -1,5 +1,6 @@
-// Helper for debugging and testing.
-// Based on https://github.com/kragen/stoneknifeforth/blob/702d2ebe1b/386.c
+//: Generating ELF binaries for SubX programs.
+//: This will allow us to run them natively on a Linux kernel.
+//: Based on https://github.com/kragen/stoneknifeforth/blob/702d2ebe1b/386.c
 
 :(before "End Main")
 assert(argc > 1);
diff --git a/subx/034compute_segment_address.cc b/subx/034compute_segment_address.cc
index 0c569c65..f5f383b6 100644
--- a/subx/034compute_segment_address.cc
+++ b/subx/034compute_segment_address.cc
@@ -54,3 +54,18 @@ uint32_t num_bytes(const line& inst) {
   }
   return sum;
 }
+
+//: Dependencies:
+//: - We'd like to compute segment addresses before setting up global variables,
+//:   because computing addresses for global variables requires knowing where
+//:   the data segment starts.
+//: - We'd like to finish expanding labels before computing segment addresses,
+//:   because it would make computing the sizes of segments more self-contained
+//:   (num_bytes).
+//:
+//: Decision: compute segment addresses before expanding labels, by being
+//: aware in this layer of certain operand types that will eventually occupy
+//: multiple bytes.
+//:
+//: The layer to expand labels later hooks into num_bytes() to teach this
+//: layer that labels occupy zero space in the binary.