; Mu: An exploration on making the global structure of programs more accessible. ; ; "Is it a language, or an operating system, or a virtual machine? Mu." ; (with apologies to Robert Pirsig: http://en.wikipedia.org/wiki/Mu_%28negative%29#In_popular_culture) ; ;; Motivation ; ; I want to live in a world where I can have an itch to tweak a program, clone ; its open-source repository, orient myself on how it's organized, and make ; the simple change I envisioned, all in an afternoon. This codebase tries to ; make this possible for its readers. (More details: http://akkartik.name/about) ; ; What helps comprehend the global structure of programs? For starters, let's ; enumerate what doesn't: idiomatic code, adherence to a style guide or naming ; convention, consistent indentation, API documentation for each class, etc. ; These conventional considerations improve matters in the small, but don't ; help understand global organization. They help existing programmers manage ; day-to-day operations, but they can't turn outsider programmers into ; insiders. (Elaboration: http://akkartik.name/post/readable-bad) ; ; In my experience, two things have improved matters so far: version control ; and automated tests. Version control lets me rewind back to earlier, simpler ; times when the codebase was simpler, when its core skeleton was easier to ; ascertain. Indeed, arguably what came first is by definition the skeleton of ; a program, modulo major rewrites. Once you understand the skeleton, it ; becomes tractable to 'play back' later major features one by one. (Previous ; project that fleshed out this idea: http://akkartik.name/post/wart-layers) ; ; The second and biggest boost to comprehension comes from tests. Tests are ; good for writers for well-understood reasons: they avoid regressions, and ; they can influence code to be more decoupled and easier to change. In ; addition, tests are also good for the outsider reader because they permit ; active reading. If you can't build a program and run its tests it can't help ; you understand it. It hangs limp at best, and might even be actively ; misleading. If you can run its tests, however, it comes alive. You can step ; through scenarios in a debugger. You can add logging and scan logs to make ; sense of them. You can run what-if scenarios: "why is this line not written ; like this?" Make a change, rerun tests: "Oh, that's why." (Elaboration: ; http://akkartik.name/post/literate-programming) ; ; However, tests are only useful to the extent that they exist. Think back to ; your most recent codebase. Do you feel comfortable releasing a new version ; just because the tests pass? I'm not aware of any such project. There's just ; too many situations envisaged by the authors that were never encoded in a ; test. Even disciplined authors can't test for performance or race conditions ; or fault tolerance. If a line is phrased just so because of some subtle ; performance consideration, it's hard to communicate to newcomers. ; ; This isn't an arcane problem, and it isn't just a matter of altruism. As ; more and more such implicit considerations proliferate, and as the original ; authors are replaced by latecomers for day-to-day operations, knowledge is ; actively forgotten and lost. The once-pristine codebase turns into legacy ; code that is hard to modify without expensive and stress-inducing ; regressions. ; ; How to write tests for performance, fault tolerance, race conditions, etc.? ; How can we state and verify that a codepath doesn't ever perform memory ; allocation, or write to disk? It requires better, more observable primitives ; than we currently have. Modern operating systems have their roots in the ; 70s. Their interfaces were not designed to be testable. They provide no way ; to simulate a full disk, or a specific sequence of writes from different ; threads. We need something better. ; ; This project tries to move, groping, towards that 'something better', a ; platform that is both thoroughly tested and allows programs written for it ; to be thoroughly tested. It tries to answer the question: ; ; If Denis Ritchie and Ken Thompson were to set out today to co-design unix ; and C, knowing what we know about automated tests, what would they do ; differently? ; ; To try to impose *some* constraints on this gigantic yak-shave, we'll try to ; keep both language and OS as simple as possible, focused entirely on ; permitting more kinds of tests, on first *collecting* all the information ; about implicit considerations in some form so that readers and tools can ; have at least some hope of making sense of it. ; ; The initial language will be just assembly. We'll try to make it convenient ; to program in with some simple localized rewrite rules inspired by lisp ; macros and literate programming. Programmers will have to do their own ; memory management and register allocation, but we'll provide libraries to ; help with them. ; ; The initial OS will provide just memory management and concurrency ; primitives. No users or permissions (we don't live on mainframes anymore), ; no kernel- vs user-mode, no virtual memory or process abstraction, all ; threads sharing a single address space (use VMs for security and ; sandboxing). The only use case we care about is getting a test harness to ; run some code, feed it data through blocking channels, stop it and observe ; its internals. The code under test is expected to cooperate in such testing, ; by logging important events for the test harness to observe. (More info: ; http://akkartik.name/post/tracing-tests) ; ; The common thread here is elimination of abstractions, and it's not an ; accident. Abstractions help insiders manage the evolution of a codebase, but ; they actively hinder outsiders in understanding it from scratch. This ; matters, because the funnel to turn outsiders into insiders is critical to ; the long-term life of a codebase. Perhaps authors should raise their ; estimation of the costs of abstraction, and go against their instincts for ; introducing it. That's what I'll be trying to do: question every abstraction ; before I introduce it. We'll see how it goes. ; --- ;; Getting started ; ; Mu is currently built atop Racket and Arc, but this is temporary and ; contingent. We want to keep our options open, whether to port to a different ; host language, and easy to rewrite to native code for any platform. So we'll ; try to avoid 'cheating': relying on the host platform for advanced ; functionality. ; ; Other than tha
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Mu - linux/406int32.mu</title>
<meta name="Generator" content="Vim/8.1">
<meta name="plugin-version" content="vim8.1_v1">
<meta name="syntax" content="none">
<meta name="settings" content="number_lines,use_css,pre_wrap,no_foldcolumn,expand_tabs,line_ids,prevent_copy=">
<meta name="colorscheme" content="minimal-dark">
<style type="text/css">
<!--
pre { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #a8a8a8; }
body { font-size:12pt; font-family: monospace; color: #000000; background-color: #a8a8a8; }
a { color:inherit; }
* { font-size:12pt; font-size: 1em; }
.PreProc { color: #c000c0; }
.Special { color: #ff6060; }
.LineNr { }
.Delimiter { color: #c000c0; }
.Constant { color: #008787; }
.muFunction { color: #af5f00; text-decoration: underline; }
.muComment { color: #005faf; }
-->
</style>
<script type='text/javascript'>
<!--
/* function to open any folds containing a jumped-to line before jumping to it */
function JumpToLine()
{
var lineNum;
lineNum = window.location.hash;
lineNum = lineNum.substr(1); /* strip off '#' */
if (lineNum.indexOf('L') == -1) {
lineNum = 'L'+lineNum;
}
var lineElem = document.getElementById(lineNum);
/* Always jump to new location even if the line was hidden inside a fold, or
* we corrected the raw number to a line ID.
*/
if (lineElem) {
lineElem.scrollIntoView(true);
}
return true;
}
if ('onhashchange' in window) {
window.onhashchange = JumpToLine;
}
-->
</script>
</head>
<body onload='JumpToLine();'>
<a href='https://github.com/akkartik/mu/blob/main/linux/406int32.mu'>https://github.com/akkartik/mu/blob/main/linux/406int32.mu</a>
<pre id='vimCodeElement'>
<span id="L1" class="LineNr"> 1 </span><span class="muComment"># Some slow but convenient helpers</span>
<span id="L2" class="LineNr"> 2 </span>
<span id="L3" class="LineNr"> 3 </span><span class="muComment"># slow, iterative shift-left instruction</span>
<span id="L4" class="LineNr"> 4 </span><span class="muComment"># preconditions: _nr >= 0, _dr > 0</span>
<span id="L5" class="LineNr"> 5 </span><span class="PreProc">fn</span> <span class="muFunction"><a href='406int32.mu.html#L5'>repeated-shift-left</a></span> nr: int, dr: int<span class="PreProc"> -> </span>_/<span class="Constant">eax</span>: int <span class="Delimiter">{</span>
<span id="L6" class="LineNr"> 6 </span> <span class="PreProc">var</span> result/<span class="Constant">eax</span>: int <span class="Special"><-</span> copy nr
<span id="L7" class="LineNr"> 7 </span> <span class="Delimiter">{</span>
<span id="L8" class="LineNr"> 8 </span> compare dr, <span class="Constant">0</span>
<span id="L9" class="LineNr"> 9 </span> <span class="PreProc">break-if-<=</span>
<span id="L10" class="LineNr">10 </span> result <span class="Special"><-</span> shift-left <span class="Constant">1</span>
<span id="L11" class="LineNr">11 </span> decrement dr
<span id="L12" class="LineNr">12 </span> <span class="PreProc">loop</span>
<span id="L13" class="LineNr">13 </span> <span class="Delimiter">}</span>
<span id="L14" class="LineNr">14 </span> <span class="PreProc">return</span> result
<span id="L15" class="LineNr">15 </span><span class="Delimiter">}</span>
<span id="L16" class="LineNr">16 </span>
<span id="L17" class="LineNr">17 </span><span class="muComment"># slow, iterative shift-right instruction</span>
<span id="L18" class="LineNr">18 </span><span class="muComment"># preconditions: _nr >= 0, _dr > 0</span>
<span id="L19" class="LineNr">19 </span><span class="PreProc">fn</span> <span class="muFunction"><a href='406int32.mu.html#L19'>repeated-shift-right</a></span> nr: int, dr: int<span class="PreProc"> -> </span>_/<span class="Constant">eax</span>: int <span class="Delimiter">{</span>
<span id="L20" class="LineNr">20 </span> <span class="PreProc">var</span> result/<span class="Constant">eax</span>: int <span class="Special"><-</span> copy nr
<span id="L21" class="LineNr">21 </span> <span class="Delimiter">{</span>
<span id="L22" class="LineNr">22 </span> compare dr, <span class="Constant">0</span>
<span id="L23" class="LineNr">23 </span> <span class="PreProc">break-if-<=</span>
<span id="L24" class="LineNr">24 </span> result <span class="Special"><-</span> shift-right <span class="Constant">1</span>
<span id="L25" class="LineNr">25 </span> decrement dr
<span id="L26" class="LineNr">26 </span> <span class="PreProc">loop</span>
<span id="L27" class="LineNr">27 </span> <span class="Delimiter">}</span>
<span id="L28" class="LineNr">28 </span> <span class="PreProc">return</span> result
<span id="L29" class="LineNr">29 </span><span class="Delimiter">}</span>
<span id="L30" class="LineNr">30 </span>
<span id="L31" class="LineNr">31 </span><span class="PreProc">fn</span> <span class="muFunction"><a href='406int32.mu.html#L31'>abs</a></span> n: int<span class="PreProc"> -> </span>_/<span class="Constant">eax</span>: int <span class="Delimiter">{</span>
<span id="L32" class="LineNr">32 </span> <span class="PreProc">var</span> result/<span class="Constant">eax</span>: int <span class="Special"><-</span> copy n
<span id="L33" class="LineNr">33 </span> <span class="Delimiter">{</span>
<span id="L34" class="LineNr">34 </span> compare n, <span class="Constant">0</span>
<span id="L35" class="LineNr">35 </span> <span class="PreProc">break-if->=</span>
<span id="L36" class="LineNr">36 </span> result <span class="Special"><-</span> negate
<span id="L37" class="LineNr">37 </span> <span class="Delimiter">}</span>
<span id="L38" class="LineNr">38 </span> <span class="PreProc">return</span> result
<span id="L39" class="LineNr">39 </span><span class="Delimiter">}</span>
</pre>
</body>
</html>
<!-- vim: set foldmethod=manual : -->