Skip to content

Commit

Permalink
Update tutorial and fix bugs in traps
Browse files Browse the repository at this point in the history
Squashed commit of the following: dede7d5...9f75939
  • Loading branch information
smoynes committed Nov 14, 2023
1 parent 37a207b commit 18f0c4c
Show file tree
Hide file tree
Showing 11 changed files with 1,476 additions and 869 deletions.
2 changes: 1 addition & 1 deletion .go-version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.21.3
1.21.4
16 changes: 7 additions & 9 deletions docs/DEVGUIDE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,10 @@ ELSIE has the following dependencies:
- optionally, golangci-lint to check Go coding style.

As a learning tool, ELSIE has a design goal that its development should simple
and easy. To that end, dependencies are restricted to only tools, packages, and
and easy. To that end, dependencies are restricted to tools, packages, and
methods that are supported by the Go Development Team. This includes Go and its
standard library, of course, but also includes modules in the "golang.org/x"
namespace, modules for dependency management, and simple text file formats.
standard library, of course, but also modules in the "golang.org/x" namespace,
using modules for dependency management, and simple text file formats.

Each design decision that introduces a dependency adds complexity, limits
portability, and requires another skill or trivial knowledge from future
Expand All @@ -63,9 +63,7 @@ makes things unexpectedly more difficult over longer time scales. So, we limit
ourselves to essential tools only. Notably, this excludes some very common and
standard tools like make, shell and YAML.

Go is not perfect, nor are its developer's or corporate sponsors infallible; far
from it in fact. However, by acknowledging its flaws and yet embracing
minimalism and Normhaus design, we make space for essential understanding and
creativity to form and we build things that have a better chance of standing the
tests of time. So long as Go is maintained, we can expect some motivated people
to be able to fix its problems.
My acknowledging its flaws and embracing minimalism and Normhaus design, we make
space for essential understanding and creativity to form and we build things
that have a better chance of standing the tests of time. So long as Go is
maintained, we can expect some motivated people to be able to fix its problems.
40 changes: 20 additions & 20 deletions docs/README.txt
Original file line number Diff line number Diff line change
@@ -1,25 +1,26 @@
ELSIE: A Pedagogical LC-3 Emulator
π”Όπ•ƒπ•Šπ•€π”Ό: A Pedagogical LC-3 Emulator
================================================================================

The path is made in the walking of it. -- Zhuangzi

This is ELSIE, an exploration of the LC-3: a little computer that is simple,
comprehensive, and imaginary.
This is π”Όπ•ƒπ•Šπ•€π”Ό, an exploration of the LC-3: a little computer that is simple and
imaginary.

The project includes:

- a virtual machine, that executes instructions;
- an assembler, for translating from LCASM source to machine code;
- a loader, that puts programs into memory;
- a system monitor or BIOS, that implements system calls;
- virtual devices for display and keyboard I/O;
- a virtual machine that executes instructions;
- an assembler for translating LCASM source to machine code;
- a loader that puts programs into memory;
- a system monitor that implements system calls;
- virtual devices for display and keyboard I/O;
- many unnecessary words by your author; and
- maybe, more to come…

As a technical project, ELSIE is not useful: it isn't complete and it doesn't
work. In those terms, it is not good software. To the author, however, ELSIE
feels more like a story, a performance, or maybe even a convalescence. As such,
it is software useful for more than mere utility and is essential.
As a technical project, π”Όπ•ƒπ•Šπ•€π”Ό is not useful: it isn't complete and it doesn't
work. In those terms, it is not good software. However, to the author, the
project is not intended to be solely utilitarian -- it is also a story, a
performance, or maybe even a trail through a cozy wood. As such, it is software
that is essential and invaluable.

-----------------------------
Background
Expand All @@ -41,12 +42,11 @@ The LC-3 instruction set and architecture includes:
- an instruction set compact enough to fit on a single page.

Far from an abstract machine, the text begins with transistors and digital
logic. From there, it builds upon the titular bits and bytes and describes in
detail the entire computer architecture including the control-unit
state-machine, data and I/O paths. It is fascinating. As far as I know, a
complete implementation has never been physically built but, I can imagine, the
text will be invaluable when humanity has to recreate computers from first
principles.
logic. From there, it builds upon the titular bits and bytes and describes an
entire computer architecture in detail including the control-unit state-machine,
data and I/O paths. It is fascinating. As far as I know, a complete
implementation has never been physically built but, I can imagine, the text will
be invaluable when humanity has to recreate computers from first principles.

While similar in many respects to the x86 or ARM ISAs, the LC-3 is radically
simpler in almost every way. Unlike the sprawling x86, with thousands of
Expand All @@ -62,7 +62,7 @@ enough to write programs.
Project Goals
-----------------------------

ELSIE is not novel: hardware simulators already exist for the LC-3 architecture,
π”Όπ•ƒπ•Šπ•€π”Ό is not novel: hardware simulators already exist for the LC-3 architecture,
of course. The textbook publishers provide one and there are many others freely
available online.[1] This one is admittedly a mere reinvention of the wheel.
That said, the gift the design and engineering process affords is that sometimes
Expand Down Expand Up @@ -136,6 +136,6 @@ This work is dedicated to the MCM/70[2] and its pioneering designers.

-----------------------------

ELSIE Β© 2023 by Scott Moynes is licensed under CC BY-SA 4.0.
π”Όπ•ƒπ•Šπ•€π”Ό Β© 2023 by Scott Moynes is licensed under CC BY-SA 4.0.
See LICENCE.txt for terms. Send your lawyers here:
https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1
Loading

0 comments on commit 18f0c4c

Please sign in to comment.