# read: analogously to write, support reading from in-memory streams in
# addition to file descriptors.
#
# We can pass it either a file descriptor or an address to a stream. If a
# file descriptor is passed in, we _read from it using the right syscall. If a
# stream is passed in (a fake file descriptor), we read from it instead. This
# lets us initialize input for tests.
#
# A little counter-intuitively, the output of 'read' ends up in.. a stream. So
# tests end up doing a redundant copy. Why? Well, consider the alternatives:
#
# a) Reading into a string, and returning a pointer to the end of the read
# region, or a count of bytes written. Now this count or end pointer must be
# managed separately by the caller, which can be error-prone.
#
# b) Having 'read' return a buffer that it allocates. But there's no way to
# know in advance how large to make the buffer. If you read less than the
# size of the buffer you again end up needing to manage initialized vs
# uninitialized memory.
#
# c) Creating more helpful variants like 'read-byte' or 'read-until' which
# also can take a file descriptor or stream, just like 'write'. But such
# primitives don't exist in the Linux kernel, so we'd be implementing them
# somehow, either with more internal buffering or by making multiple
# syscalls.
#
# Reading into a stream avoids these problems. The buffer is externally
# provided and the caller has control over where it's allocated, its lifetime,
# and so on. The buffer's read and write pointers are internal to it so it's
# easier to keep in a consistent state. And it can now be passed directly to
# helpers like 'read-byte' or 'read-until' that only need to support streams,
# never file descriptors.
#
# Like with 'write', we assume our data segment will never begin at an address
# shorter than 0x08000000, so any smaller arguments are assumed to be real
# file descriptors.
#
# As a reminder, a stream looks like this:
# write: int # index at which to write to next
# read: int # index at which to read next
# data: (array byte) # prefixed by size as usual
== code
# instruction effective address register displacement immediate
# . op subop mod rm32 base index scale r32
# . 1-3 bytes 3 bits 2 bits 3 bits 3 bits 3 bits 2 bits 2 bits 0/1/2/4 bytes 0/1/2/4 bytes
read: # f: fd or (addr stream byte), s: (addr stream byte) -> num-bytes-read/eax: int
# . prologue
55/push-ebp
89/copy 3/mod/direct 5/rm32/ebp . . . 4/r32/esp . . # copy esp to ebp
# if (f < 0x08000000) return _read(f, s) # f can't be a user-mode address, so treat it as a kernel file descriptor
81 7/subop/compare 1/mod/*+disp8 5/rm32/ebp . . . . 8/disp8 0x08000000/imm32 # compare *(ebp+8)
73/jump-if-addr>= $read:fake/disp8
# . . push args
ff 6/subop/push 1/mod/*+disp8 5/rm32/ebp . . . . 0xc/disp8 . # push *(ebp+12)
ff 6/subop/push 1/mod/*+disp8 5/rm32/ebp . . . . 8/disp8 . # push *(ebp+8)
# . . call
e8/call _read/disp32
# . . discard args
81 0/subop/add 3/mod/direct 4/rm32/esp . . . . . 8/imm32 # add to esp
# return
eb/jump $read:end/disp8
$read:fake:
# otherwise, treat 'f' as a stream to scan from
# . save registers
56/push-esi
57/push-edi
# esi = f
8b/copy 1/mod/*+disp8 5/rm32/ebp . . . 6/r32/esi 8/disp8 . # copy *(ebp+8) to esi
# edi = s
8b/copy 1/mod/*+disp8 5/rm32/ebp . . . 7/r32/edi 0xc/disp8 . # copy *(ebp+12) to esi
# eax = _buffer-4(out = &s->data[s->write], outend = &s->data[s->size],
# in = &f->data[f->read], inend = &f->data[f->write])
# . . push &f->data[f->write]
8b/copy 0/mod/indirect 6/rm32/esi . . . 0/r32/eax . . # copy *esi to eax
8d/copy-address 1/mod/*+disp8 4/rm32/sib 6/base/esi 0/index/eax . 0/r32/eax 0xc/disp8 . # copy esi+eax+12 to eax
50/push-eax
# . . push &f->data[f->read]
8b/copy 1/mod/*+disp8 6/rm32/esi . . . 0/r32/eax 4/disp8 . # copy *(esi+4) to eax
8d/copy-address 1/mod/*+disp8 4/rm32/sib 6/base/esi 0/index/eax . 0/r32/eax 0xc/disp8 . # copy esi+eax+12 to eax
50/push-eax
# . . push &s->data[s->size]
8b/copy 1/mod/*+disp8 7/rm32/edi . . . 0/r32/eax 8/disp8 . # copy *(edi+8) to eax
8d/copy-address 1/mod/*+disp8 4/rm32/sib 7/base/edi 0/index/eax . 0/r32/eax 0xc/disp8 . # copy edi+eax+12 to eax
50/push-eax
# . . push &s->data[s->write]
8b/copy 0/mod/indirect 7/rm32/edi . . . 0/r32/eax . . # copy *edi to eax
8d/copy-address 1/mod/*+disp8 4/rm32/sib 7/base/edi 0/index/eax . 0/r32/eax 0xc/disp8 . # copy edi+eax+12 to eax
50/push-eax
# . . call
e8/call _buffer-4/disp32
# . . discard args
81 0/subop/add 3/mod/direct 4/rm32/esp . . . . . 0x10/imm32 # add to esp
# s->write += eax
01/add 0/mod/indirect 7/rm32/edi . . . 0/r32/eax . . # add eax to *edi
# f->read += eax
01/add 1/mod/*+disp8 6/rm32/esi . . . 0/r32/eax 4/disp8 . <style>pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008800 } /* Keyword.Pseudo */
.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.highlight .na { color: #336699 } /* Name.Attribute */
.highlight .nb { color: #003388 } /* Name.Builtin */
.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
.highlight .nd { color: #555555 } /* Name.Decorator */
.highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.highlight .nl { color: #336699; font-style: italic } /* Name.Label */
.highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.highlight .py { color: #336699; font-weight: bold } /* Name.Property */
.highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #336699 } /* Name.Variable */
.highlight .ow { color: #008800 } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */
.highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */
.highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */
.highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */
.highlight .vc { color: #336699 } /* Name.Variable.Class */
.highlight .vg { color: #dd7700 } /* Name.Variable.Global */
.highlight .vi { color: #3333bb } /* Name.Variable.Instance */
.highlight .vm { color: #336699 } /* Name.Variable.Magic */
.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */</style><div class="highlight"><pre><span></span><span class="nv">#</span><span class="w"> </span><span class="nv">Wrappers</span><span class="w"> </span><span class="nv">around</span><span class="w"> </span><span class="nv">interaction</span><span class="w"> </span><span class="nv">primitives</span><span class="w"> </span><span class="nv">that</span><span class="w"> </span><span class="nv">take</span><span class="w"> </span><span class="nv">a</span><span class="w"> </span><span class="nv">potentially</span><span class="w"> </span><span class="nv">fake</span><span class="w"> </span><span class="nv">object</span>
<span class="nv">#</span><span class="w"> </span><span class="ow">and</span><span class="w"> </span><span class="nv">are</span><span class="w"> </span><span class="nv">thus</span><span class="w"> </span><span class="nv">easier</span><span class="w"> </span><span class="k">to</span><span class="w"> </span><span class="nv">test</span><span class="o">.</span>
<span class="nv">exclusive</span><span class="o">-</span><span class="nv">container</span><span class="w"> </span><span class="nv">event</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="nv">text</span><span class="o">:</span><span class="nv">character</span>
<span class="w"> </span><span class="nv">keycode</span><span class="o">:</span><span class="nv">number</span><span class="w"> </span><span class="nv">#</span><span class="w"> </span><span class="nv">keys</span><span class="w"> </span><span class="nv">on</span><span class="w"> </span><span class="nv">keyboard</span><span class="w"> </span><span class="nv">without</span><span class="w"> </span><span class="nv">a</span><span class="w"> </span><span class="nv">unicode</span><span class="w"> </span><span class="nv">representation</span>
<span class="w"> </span><span class="nv">touch</span><span class="o">:</span><span class="nv">touch</span><span class="o">-</span><span class="nv">event</span><span class="w"> </span><span class="nv">#</span><span class="w"> </span><span class="nv">mouse</span><span class="o">,</span><span class="w"> </span><span class="nv">track</span><span class="w"> </span><span class="nv">ball</span><span class="o">,</span><span class="w"> </span><span class="nv">etc</span><span class="o">.</span>
<span class="w"> </span><span class="nv">resize</span><span class="o">:</span><span class="nv">resize</span><span class="o">-</span><span class="nv">event</span>
<span class="w"> </span><span class="nv">#</span><span class="w"> </span><span class="nv">update</span><span class="w"> </span><span class="nv">the</span><span class="w"> </span><span class="nv">assume</span><span class="o">-</span><span class="nv">console</span><span class="w"> </span><span class="nv">handler</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="nv">you</span><span class="w"> </span><span class="nv">add</span><span class="w"> </span><span class="nv">more</span><span class="w"> </span><span class="nv">variants</span>
<span class="p">]</span>
<span class="nv">container</span><span class="w"> </span><span class="nv">touch</span><span class="o">-</span><span class="nv">event</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="nv">type</span><span class="o">:</span><span class="nv">number</span>
<span class="w"> </span><span class="nv">row</span><span class="o">:</span><span class="nv">number</span>
<span class="w"> </span><span class="nv">column</span><span class="o">:</span><span class="nv">number</span>
<span class="p">]</span>
<span class="nv">container</span><span class="w"> </span><span class="nv">resize</span><span class="o">-</span><span class="nv">event</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="nv">width</span><span class="o">:</span><span class="nv">number</span>
<span class="w"> </span><span class="nv">height</span><span class="o">:</span><span class="nv">number</span>
<span class="p">]</span>
<span class="nv">container</span><span class="w"> </span><span class="nv">console</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="nv">index</span><span class="o">:</span><span class="nv">number</span>
<span class="w"> </span><span class="nv">data</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">array</span><span class="o">:</span><span class="nv">event</span>
<span class="p">]</span>
<span class="nv">recipe</span><span class="w"> </span><span class="nv">new</span><span class="o">-</span><span class="nv">fake</span><span class="o">-</span><span class="nv">console</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="k">local</span><span class="o">-</span><span class="nv">scope</span>
<span class="w"> </span><span class="nv">result</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">console</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">new</span><span class="w"> </span><span class="nv">console</span><span class="o">:</span><span class="nv">type</span>
<span class="w"> </span><span class="nv">buf</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">array</span><span class="o">:</span><span class="nv">event</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">get</span><span class="o">-</span><span class="nv">address</span><span class="w"> </span><span class="o">*</span><span class="nv">result</span><span class="o">,</span><span class="w"> </span><span class="nv">data</span><span class="o">:</span><span class="nv">offset</span>
<span class="w"> </span><span class="o">*</span><span class="nv">buf</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="k">next</span><span class="o">-</span><span class="nv">ingredient</span>
<span class="w"> </span><span class="nv">idx</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">number</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">get</span><span class="o">-</span><span class="nv">address</span><span class="w"> </span><span class="o">*</span><span class="nv">result</span><span class="o">,</span><span class="w"> </span><span class="nv">index</span><span class="o">:</span><span class="nv">offset</span>
<span class="w"> </span><span class="o">*</span><span class="nv">idx</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">copy</span><span class="w"> </span><span class="m">0</span>
<span class="w"> </span><span class="nv">reply</span><span class="w"> </span><span class="nv">result</span>
<span class="p">]</span>
<span class="nv">recipe</span><span class="w"> </span><span class="nv">read</span><span class="o">-</span><span class="nv">event</span><span class="w"> </span><span class="p">[</span>
<span class="w"> </span><span class="k">local</span><span class="o">-</span><span class="nv">scope</span>
<span class="w"> </span><span class="nv">x</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">console</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="k">next</span><span class="o">-</span><span class="nv">ingredient</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">break</span><span class="o">-</span><span class="nv">unless</span><span class="w"> </span><span class="nv">x</span>
<span class="w"> </span><span class="nv">idx</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">number</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">get</span><span class="o">-</span><span class="nv">address</span><span class="w"> </span><span class="o">*</span><span class="nv">x</span><span class="o">,</span><span class="w"> </span><span class="nv">index</span><span class="o">:</span><span class="nv">offset</span>
<span class="w"> </span><span class="nv">buf</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">array</span><span class="o">:</span><span class="nv">event</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">get</span><span class="w"> </span><span class="o">*</span><span class="nv">x</span><span class="o">,</span><span class="w"> </span><span class="nv">data</span><span class="o">:</span><span class="nv">offset</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="nv">max</span><span class="o">:</span><span class="nv">number</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">length</span><span class="w"> </span><span class="o">*</span><span class="nv">buf</span>
<span class="w"> </span><span class="nv">done</span>?<span class="o">:</span><span class="nv">boolean</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">greater</span><span class="o">-</span><span class="ow">or</span><span class="o">-</span><span class="nv">equal</span><span class="w"> </span><span class="o">*</span><span class="nv">idx</span><span class="o">,</span><span class="w"> </span><span class="nv">max</span>
<span class="w"> </span><span class="k">break</span><span class="o">-</span><span class="nv">unless</span><span class="w"> </span><span class="nv">done</span>?
<span class="w"> </span><span class="nv">dummy</span><span class="o">:</span><span class="nv">address</span><span class="o">:</span><span class="nv">event</span><span class="w"> </span><span class="o"><-</span><span class="w"> </span><span class="nv">new</span><span class="w"> </span><span class="nv">event</span><span class="o">:</span><s