summary refs log tree commit diff stats
path: root/bouml/134786.diagram
blob: b4333029456e8aa2f31f16afea0f0c4bc2612373 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
format 70

classinstance 128002 class_ref 128002 // FM
  name ""   xyz 38 4 2000 life_line_z 2000
classinstance 128386 class_ref 128642 // Environment
  name ""   xyz 375 6 2000 life_line_z 2000
classinstance 128898 class_ref 136578 // Directory
  name "pwd"   xyz 510 4 2000 life_line_z 2000
classinstance 129794 class_ref 128130 // UI
  name ""   xyz 101 4 2000 life_line_z 2000
classinstance 130306 class_ref 136578 // Directory
  name "pathway[-1]"   xyz 614 4 2000 life_line_z 2000
classinstance 131714 class_ref 129282 // WDisplay
  name ""   xyz 157 4 2000 life_line_z 2000
durationcanvas 128514 classinstance_ref 128002 // :FM
  xyzwh 57 96 2010 11 40
end
durationcanvas 128642 classinstance_ref 128386 // :Environment
  xyzwh 416 98 2010 11 300
  overlappingdurationcanvas 129282
    xyzwh 422 112 2020 11 49
  end
  overlappingdurationcanvas 130434
    xyzwh 422 245 2020 11 147
    overlappingdurationcanvas 130690
      xyzwh 428 275 2030 11 89
    end
  end
end
durationcanvas 129026 classinstance_ref 128898 // pwd:Directory
  xyzwh 553 190 2010 11 25
end
durationcanvas 129538 classinstance_ref 128898 // pwd:Directory
  xyzwh 553 140 2010 11 25
end
durationcanvas 129922 classinstance_ref 128002 // :FM
  xyzwh 57 473 2010 11 56
end
durationcanvas 130050 classinstance_ref 129794 // :UI
  xyzwh 120 475 2010 11 85
end
durationcanvas 130946 classinstance_ref 130306 // pathway[-1]:Directory
  xyzwh 681 294 2010 11 28
end
durationcanvas 131202 classinstance_ref 130306 // pathway[-1]:Directory
  xyzwh 681 348 2010 11 47
  overlappingdurationcanvas 131458
    xyzwh 687 364 2020 11 25
  end
end
durationcanvas 131842 classinstance_ref 131714 // :WDisplay
  xyzwh 188 496 2010 11 72
end
durationcanvas 132098 classinstance_ref 128898 // pwd:Directory
  xyzwh 553 515 2010 11 25
end
durationcanvas 132354 classinstance_ref 128898 // pwd:Directory
  xyzwh 553 550 2010 11 25
end
msg 128770 synchronous
  from durationcanvas_ref 128514
  to durationcanvas_ref 128642
  yz 98 2015 msg operation_ref 139522 // "enter_dir()"
  show_full_operations_definition default drawing_language default
  label_xy 205 77
msg 129154 synchronous
  from durationcanvas_ref 128642
  to durationcanvas_ref 129026
  yz 192 2015 msg operation_ref 139394 // "load_content_if_outdated()"
  show_full_operations_definition default drawing_language default
  label_xy 429 176
reflexivemsg 129410 synchronous
  to durationcanvas_ref 129282
  yz 112 2025 msg operation_ref 139650 // "get_directory()"
  show_full_operations_definition default drawing_language default
  label_xy 432 91
msg 129666 synchronous
  from durationcanvas_ref 129282
  to durationcanvas_ref 129538
  yz 140 2025 msg operation_ref 139778 // "new()"
  show_full_operations_definition default drawing_language default
  label_xy 472 124
msg 130178 synchronous
  from durationcanvas_ref 129922
  to durationcanvas_ref 130050
  yz 475 2015 msg operation_ref 128002 // "draw()"
  show_full_operations_definition default drawing_language default
  label_xy 76 456
reflexivemsg 130562 synchronous
  to durationcanvas_ref 130434
  yz 245 2025 msg operation_ref 139906 // "assign_correct_cursor_positions()"
  show_full_operations_definition default drawing_language default
  label_xy 326 220
reflexivemsg 130818 synchronous
  to durationcanvas_ref 130690
  yz 275 2035 msg operation_ref 139650 // "get_directory()"
  show_full_operations_definition default drawing_language default
  label_xy 455 259
msg 131074 synchronous
  from durationcanvas_ref 130690
  to durationcanvas_ref 130946
  yz 294 2040 msg operation_ref 139778 // "new()"
  show_full_operations_definition default drawing_language default
  label_xy 566 272
msg 131330 synchronous
  from durationcanvas_ref 130690
  to durationcanvas_ref 131202
  yz 348 2045 msg operation_ref 138626 // "move_pointer_to_file_path()"
  show_full_operations_definition default drawing_language default
  label_xy 471 328
reflexivemsg 131586 synchronous
  to durationcanvas_ref 131458
  yz 364 2025 msg operation_ref 139266 // "load_content_once()"
  show_full_operations_definition default drawing_language default
  label_xy 700 382
msg 131970 synchronous
  from durationcanvas_ref 130050
  to durationcanvas_ref 131842
  yz 496 2015 msg operation_ref 130434 // "draw()"
  show_full_operations_definition default drawing_language default
  label_xy 140 480
msg 132226 synchronous
  from durationcanvas_ref 131842
  to durationcanvas_ref 132098
  yz 515 2015 msg operation_ref 139394 // "load_content_if_outdated()"
  show_full_operations_definition default drawing_language default
  label_xy 291 499
msg 132482 synchronous
  from durationcanvas_ref 131842
  to durationcanvas_ref 132354
  yz 550 2015 msg operation_ref 140162 // "sort_if_outdated()"
  show_full_operations_definition default drawing_language default
  label_xy 320 534
end
am <vc@akkartik.com> 2015-11-11 09:13:40 -0800 committer Kartik K. Agaram <vc@akkartik.com> 2015-11-11 09:17:16 -0800 2426' href='/akkartik/mu/commit/Readme.md?h=main&id=322416056beae917b0877f984ccc2b4b930a14ce'>32241605 ^
9a524793 ^



32241605 ^
ac8b37f9 ^



c7db6a16 ^
9a524793 ^
7b5ad602 ^
32241605 ^
9a524793 ^
32241605 ^
9a524793 ^

6e1eeeeb ^
9a524793 ^

46bb1d31 ^
7817fdb2 ^






30b2fcf8 ^
9a524793 ^
ef401599 ^
9a524793 ^

8f9ec2fb ^
7817fdb2 ^






f8a4a457 ^
9a524793 ^
9f589350 ^
9a524793 ^






6e1eeeeb ^
9a524793 ^
6e1eeeeb ^
9a524793 ^
2c9aa92f ^
9a524793 ^
797a46d5 ^
9a524793 ^
797a46d5 ^
7817fdb2 ^









e420279a ^
9a524793 ^
e9e06638 ^
9a524793 ^
b338e82e ^




e2e0f5cc ^
b338e82e ^

9a524793 ^
6e1eeeeb ^
9a524793 ^
4f33ff22 ^
9a524793 ^

4f33ff22 ^
9a524793 ^
d0a1e1b6 ^
7b5ad602 ^
bb1a1ac2 ^
9a524793 ^

bb1a1ac2 ^
9a524793 ^

bb1a1ac2 ^
9a524793 ^

bb1a1ac2 ^
9a524793 ^
924ed08a ^
9a524793 ^

b7b6ee50 ^
9a524793 ^
bb1a1ac2 ^
9a524793 ^
a7088a2f ^
784e17d4 ^









784e17d4 ^


784e17d4 ^



52564867 ^

9a524793 ^


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
                            
 

                                                                         
 


                                                                              
 







                                          
 

                                                                                                             






                                                                                                    
 


                  
 

                                                                                                               
                                            

                                                                            
                                                                            



                                                                                                                  

                                                                          

                                        
 

            

                                                                             
                                                                    
                                                                      

                                                                            
                                                                            
                                                                                                                           
                                                                                                                      


                                                                            
            
 



                                                                            
 



                                                                             
 
                                                                                
                                               
 
                    
 

                                                                         
 

                                                                          
 






                                                                                
 
                                                                                                                    
 

                                                                              
 






                                                                                              
 
         
 






                                                                              
 
                                
 
                                        
 
                                         
 
                                  
 









                              
 
                                             
 
        




                                                                              
                                                                          

                               
             
 
                                                                
 

                                                                          
 
                                                                           
 
                                                             
 

                                                                                       
 

                                                                                        
 

                                                                                        
 
                                                                      
 

                                                                         
 
                                                                                                          
 
                                                                                                      
 









                                                                                                      


                                                                                     



                                                                        

                                                                              


                                                                                                                                                              
# Mu: a human-scale computer

Mu is a minimal-dependency hobbyist computing stack (everything above the
processor and OS kernel).

Mu is not designed to operate in large clusters providing services for
millions of people. Mu is designed for _you_, to run one computer. (Or a few.)
Running the code you want to run, and nothing else.

```sh
$ git clone https://github.com/akkartik/mu
$ cd mu
$ ./translate_mu apps/ex2.mu  # emit a.elf
$ ./a.elf  # adds 3 and 4
$ echo $?
7
```

[![Build Status](https://api.travis-ci.org/akkartik/mu.svg?branch=master)](https://travis-ci.org/akkartik/mu)

Rather than start from some syntax and introduce layers of translation to
implement it, Mu starts from the processor's instruction set and tries to get
to _some_ safe and clear syntax with as few layers of translation as possible.
The emphasis is on internal consistency at any point in time rather than
compatibility with the past. ([More details.](http://akkartik.name/akkartik-convivial-20200607.pdf))

Currently Mu requires a 32-bit x86 processor and Linux kernel.

## Goals

In priority order:

- [Reward curiosity.](http://akkartik.name/about)
  - Easy to build, easy to run. [Minimal dependencies](https://news.ycombinator.com/item?id=16882140#16882555),
    so that installation is always painless.
  - All design decisions comprehensible to a single individual. (On demand.)
  - All design decisions comprehensible without needing to talk to anyone.
    (I always love talking to you, but I try hard to make myself redundant.)
  - [A globally comprehensible _codebase_ rather than locally clean code.](http://akkartik.name/post/readable-bad)
  - Clear error messages over expressive syntax.
- Safe.
  - Thorough test coverage. If you break something you should immediately see
    an error message. If you can manually test for something you should be
    able to write an automated test for it.
  - Memory leaks over memory corruption.
- Teach the computer bottom-up.

## Non-goals

- Speed. Staying close to machine code should naturally keep Mu fast enough.
- Efficiency. Controlling the number of abstractions should naturally keep Mu
  using far less than the gigabytes of memory modern computers have.
- Portability. Mu will run on any computer as long as it's x86. I will
  enthusiastically contribute to support for other processors -- in separate
  forks. Readers shouldn't have to think about processors they don't have.
- Compatibility. The goal is to get off mainstream stacks, not to perpetuate
  them. Sometimes the right long-term solution is to [bump the major version number](http://akkartik.name/post/versioning).
- Syntax. Mu code is meant to be comprehended by [running, not just reading](http://akkartik.name/post/comprehension).
  For now it's a thin veneer over machine code. I'm working on memory safety
  before expressive syntax.

## Toolchain

The Mu stack consists of:
- the Mu type-safe language;
- SubX, an unsafe notation for a subset of x86 machine code; and
- _bare_ SubX, a more rudimentary form of SubX without certain syntax sugar.

All Mu programs get translated through these layers into tiny zero-dependency
ELF binaries. The translators for most levels are built out of lower levels.
The translator from Mu to SubX is written in SubX, and the translator from
SubX to bare SubX is built in bare SubX.

Mu programs can be run in emulated mode to emit traces, which permit time-travel
debugging. ([More details.](subx_debugging.md))

### incomplete tools

The Mu translator is still a work in progress; not all incorrect programs
result in good error messages.

Once generated, ELF binaries can be packaged up with a Linux kernel into a
bootable disk image:

```sh
$ ./translate_mu apps/ex2.mu  # emit a.elf
# dependencies
$ sudo apt install build-essential flex bison wget libelf-dev libssl-dev xorriso
$ tools/iso/linux a.elf
$ qemu-system-x86_64 -m 256M -cdrom mu_linux.iso -boot d
```

The disk image also runs on [any cloud server that supports custom images](http://akkartik.name/post/iso-on-linode).

Mu also runs on the minimal hobbyist OS [Soso](https://github.com/ozkl/soso).
(Requires graphics and sudo access. Currently doesn't work on a cloud server.)

```sh
$ ./translate_mu apps/ex2.mu  # emit a.elf
# dependencies
$ sudo apt install build-essential util-linux nasm xorriso  # maybe also dosfstools and mtools
$ tools/iso/soso a.elf  # requires sudo
$ qemu-system-i386 -cdrom mu_soso.iso
```

## Syntax

The entire stack shares certain properties and conventions. Programs consist
of functions and functions consist of statements, each performing a single
operation. Operands to statements are always variables or constants. You can't
say `a + b*c`, you have to break it up into two operations. Variables can live
in memory or in registers. Registers must be explicitly specified. There are
some shared lexical rules; comments always start with '#', and numbers are
always written in hex.

Here's an example program in Mu:

<img alt='ex2.mu' src='html/ex2.mu.png'>

[More details on Mu syntax &rarr;](mu.md)

Here's an example program in SubX:

```sh
== code
Entry:
  # ebx = 1
  bb/copy-to-ebx  1/imm32
  # increment ebx
  43/increment-ebx
  # exit(ebx)
  e8/call  syscall_exit/disp32
```

[More details on SubX syntax &rarr;](subx.md)

## Forks

Forks of Mu are encouraged. If you don't like something about this repo, feel
free to make a fork. If you show it to me, I'll link to it here, so others can
use it. I might even pull your changes into this repo!

- [mu-normie](https://git.sr.ht/~akkartik/mu-normie): with a more standard
  build system and C++ modules.

## Desiderata

If you're still reading, here are some more things to check out:

- The references on [Mu](mu.md) and [SubX](subx.md) syntax, and also [bare
  SubX](subx_bare.md) without any syntax sugar.

- [How to get your text editor set up for Mu and SubX programs.](editor.md)

- [Some tips for debugging SubX programs.](subx_debugging.md)

- [Shared vocabulary of data types and functions shared by Mu programs.](vocabulary.md)
  Mu programs can transparently call low-level functions written in SubX.

- [A summary](mu_instructions) of how the Mu compiler translates instructions
  to SubX. ([colorized version](http://akkartik.github.io/mu/html/mu_instructions.html))

- [Some starter exercises for learning SubX](https://github.com/akkartik/mu/pulls)
  (labelled `hello`). Feel free to [ping me](mailto:ak@akkartik.com) with any questions.

- [Commandline reference for the bootstrap C++ program.](bootstrap.md)

- The [list of x86 opcodes](subx_opcodes) supported in SubX: `./bootstrap
  help opcodes`.

- [Some details on the unconventional organization of this project.](http://akkartik.name/post/four-repos)

- Previous prototypes: [mu0](https://github.com/akkartik/mu0), [mu1](https://github.com/akkartik/mu1).

## Credits

Mu builds on many ideas that have come before, especially:

- [Peter Naur](http://akkartik.name/naur.pdf) for articulating the paramount
  problem of programming: communicating a codebase to others;
- [Christopher Alexander](http://www.amazon.com/Notes-Synthesis-Form-Harvard-Paperbacks/dp/0674627512)
  and [Richard Gabriel](http://dreamsongs.net/Files/PatternsOfSoftware.pdf) for
  the intellectual tools for reasoning about the higher order design of a
  codebase;
- [David Parnas](http://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf)
  and others for highlighting the value of separating concerns and stepwise
  refinement;
- The folklore of debugging by print and the trace facility in many lisp
  systems;
- Automated tests for showing the value of developing programs inside an
  elaborate harness;
- [Minimal Linux Live](http://minimal.linux-bg.org) for teaching how to create
  a bootable disk image.
- [&ldquo;Bootstrapping a compiler from nothing&rdquo;](http://web.archive.org/web/20061108010907/http://www.rano.org/bcompiler.html) by Edmund Grumley-Evans.
- [&ldquo;Creating tiny ELF executables&rdquo;](https://www.muppetlabs.com/~breadbox/software/tiny/teensy.html) by Brian Raiter.
- [StoneKnifeForth](https://github.com/kragen/stoneknifeforth) by [Kragen Sitaker](http://canonical.org/~kragen).