7523

There's a dependency cycle here:

- draw-grapheme (Mu) uses read-grapheme (Mu) to be unicode-aware.
- read-grapheme uses read-byte (SubX). Streams are a fundamental data
  structure in Mu. For the Mu compiler to be able to reason about the
  safety of stream operations, they need to be an opaque type. All
  stream primitives are written in SubX. To manipulate a stream's
  internals we force people to reach for SubX. That way if there's no
  SubX code there's confidence that things are safe.
- read-byte and other stream operations have unit tests, like they
  should. The unit tests need to print data to screen when say a test
  fails. To do this they use various check- functions (SubX) that take a
  string argument.
- Printing a string to screen uses draw-grapheme (Mu).

Perhaps I should maintain variants of drawing primitives that operate
only on ASCII.

6 files changed, 21 insertions, 4 deletions

diff --git a/baremetal/106stream.subx b/baremetal/106stream.subx
index 84d0580b..9949ee7d 100644
--- a/baremetal/106stream.subx
+++ b/baremetal/106stream.subx
@@ -8,6 +8,9 @@
 # some primitives for operating on streams:
 #   - clear-stream (clears everything but the data size)
 #   - rewind-stream (resets read pointer)
+#
+# We need to do this in machine code because streams need to be opaque types,
+# and we don't yet support opaque types in Mu.
 
 == code
 #   instruction                     effective address                                                   register    displacement    immediate
diff --git a/baremetal/108write.subx b/baremetal/108write.subx
index 4f3b0b7f..43e9bf9b 100644
--- a/baremetal/108write.subx
+++ b/baremetal/108write.subx
@@ -1,9 +1,7 @@
 # write: write to in-memory streams
 #
-# A stream looks like this:
-#   read: int  # index at which to read next
-#   write: int  # index at which writes go
-#   data: (array byte)  # prefixed by size as usual
+# We need to do this in machine code because streams need to be opaque types,
+# and we don't yet support opaque types in Mu.
 
 == code
 #   instruction                     effective address                                                   register    displacement    immediate
diff --git a/baremetal/109stream-equal.subx b/baremetal/109stream-equal.subx
index 8f6cf1bf..ad0dcb7c 100644
--- a/baremetal/109stream-equal.subx
+++ b/baremetal/109stream-equal.subx
@@ -1,4 +1,7 @@
 # some primitives for checking stream contents
+#
+# We need to do this in machine code because streams need to be opaque types,
+# and we don't yet support opaque types in Mu.
 
 == code
 #   instruction                     effective address                                                   register    displacement    immediate
diff --git a/baremetal/112read-byte.subx b/baremetal/112read-byte.subx
index f86498bb..c6dd3ddf 100644
--- a/baremetal/112read-byte.subx
+++ b/baremetal/112read-byte.subx
@@ -1,3 +1,8 @@
+# Read a single byte from a stream.
+#
+# We need to do this in machine code because streams need to be opaque types,
+# and we don't yet support opaque types in Mu.
+
 == code
 #   instruction                     effective address                                                   register    displacement    immediate
 # . op          subop               mod             rm32          base        index         scale       r32
diff --git a/baremetal/115write-byte.subx b/baremetal/115write-byte.subx
index af32f610..3ac587f0 100644
--- a/baremetal/115write-byte.subx
+++ b/baremetal/115write-byte.subx
@@ -1,3 +1,8 @@
+# Write a single byte to a stream.
+#
+# We need to do this in machine code because streams need to be opaque types,
+# and we don't yet support opaque types in Mu.
+
 == code
 #   instruction                     effective address                                                   register    displacement    immediate
 # . op          subop               mod             rm32          base        index         scale       r32
diff --git a/translate_subx_baremetal b/translate_subx_baremetal
index 7058003c..29750abb 100755
--- a/translate_subx_baremetal
+++ b/translate_subx_baremetal
@@ -7,6 +7,9 @@
 #   version of translate_subx_debug for baremetal.
 # * Don't pass in numbered .subx files without translated .mu files. Our test
 #   harness is in test.mu, and only Mu programs can run tests in baremetal.
+#
+# The baremetal directory is in general not as rigorous about avoiding
+# dependency cycles as the top-level.
 
 set -e