From 063741b4a2edfd64cd639ebc108d051af269ef5c Mon Sep 17 00:00:00 2001 From: Kartik Agaram Date: Mon, 26 Nov 2018 01:21:57 -0800 Subject: 4783 --- subx/Readme.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'subx/Readme.md') diff --git a/subx/Readme.md b/subx/Readme.md index cfc7a3fb..e58cd9f3 100644 --- a/subx/Readme.md +++ b/subx/Readme.md @@ -337,6 +337,52 @@ Running `subx` will transparently compile it as necessary. building general infrastructure here for all of the x86 instruction set. SubX is about programming with a small, regular subset of 32-bit x86. +## SubX library + +A major goal of SubX is testable wrappers for operating system syscalls. +Here's what I've built so far: + +* `write`: takes two arguments, `f` and `s`. + - `s` is an address to an _array_. Arrays in SubX are always assumed to + start with a 4-byte length. + - `f` is either a file descriptor to write `s` to, or (in tests) a _stream_. + Streams are in-memory buffers that can be read or written. They consist of + a `data` array of bytes as well as `read` and `write` indexes into the + array, showing how far we've read and written so far. + + Comparing this interface with the Unix `write()` syscall shows two benefits: + + 1. SubX can handle 'fake' file descriptors in tests. + + 1. `write()` accepts buffer and its length in separate arguments, which + requires callers to manage the two separately and so can be error-prone. + SubX's wrapper keeps the two together to increase the chances that we + never accidentally go out of array bounds. + +* `read`: takes two arguments, `f` and `s`. + - `s` is an address to a _stream_ to save the read data to. We read as much + data as can fit in `s`, and no more. + - `f` is either a file descriptor to write `s` to, or (in tests) a _stream_. + + Like with `write()`, this wrapper around the Unix `read()` syscall adds the + ability to handle 'fake' file descriptors in tests, and reduces the chances + of clobbering outside array bounds. + + One bit of weirdness here: in tests we do a redundant copy from one stream + to another. See [the comments before the implementation](http://akkartik.github.io/mu/html/subx/058read.subx.html) + for a discussion of alternative interfaces. + +* `stop`: takes two arguments: + - `ed` is an address to an _exit descriptor_. Exit descriptors allow us to + `exit()` the program normally, but return to the test harness within + tests. That allows tests to make assertions about when `exit()` is called. + - `value` is the status code to `exit()` with. + + For more details on exit descriptors and how to create one, see [the + comments before the implementation](http://akkartik.github.io/mu/html/subx/057stop.subx.html). + +* ... _(to be continued)_ + ## Resources * [Single-page cheatsheet for the x86 ISA](https://net.cs.uni-bonn.de/fileadmin/user_upload/plohmann/x86_opcode_structure_and_instruction_overview.pdf) -- cgit 1.4.1-2-gfad0