Make *.md files markdown compliant
authorKevin Klues <klueska@cs.berkeley.edu>
Thu, 3 Sep 2015 04:02:33 +0000 (21:02 -0700)
committerBarret Rhoden <brho@cs.berkeley.edu>
Tue, 8 Sep 2015 14:24:58 +0000 (10:24 -0400)
Documentation/Contributing.md
GETTING_STARTED.md

index 0f4d40a..fff84a5 100644 (file)
@@ -1,30 +1,31 @@
 Akaros Contribution Policies
 ===========================
 Akaros Contribution Policies
 ===========================
-2015-04-27 Barret Rhoden (brho)
+**2015-04-27** Barret Rhoden (`brho`)
 
 Interested in contributing to Akaros?  This document covers coding standards,
 version control usage, and other contribution policies.
 
 Contents
 ---------------------------
 
 Interested in contributing to Akaros?  This document covers coding standards,
 version control usage, and other contribution policies.
 
 Contents
 ---------------------------
-Licensing
-Contribution Philosophy
-Contribution Steps
-Coding Standard
-Git Workflow
-       - Setup
-       - A Basic Commit
-       - A Bigger Change: Several Commits!
-       - Someone Changed origin/master; My Branch is Now Old
-       - Oh No, I Committed and Pushed Something I Want to Change
-       - Crap, Someone Reset a Branch I was Tracking!
-       - What Happens When Two People Push -f
+Licensing
+Contribution Philosophy
+Contribution Steps
+Coding Standard
+Git Workflow
+    - Setup
+    - A Basic Commit
+    - A Bigger Change: Several Commits!
+    - Someone Changed origin/master; My Branch is Now Old
+    - Oh No, I Committed and Pushed Something I Want to Change
+    - Crap, Someone Reset a Branch I was Tracking!
+    - What Happens When Two People `push -f`
 
 
 Licensing
 ---------------------------
 By contributing to Akaros, you are agreeing with the Developer Certificate of
 
 
 Licensing
 ---------------------------
 By contributing to Akaros, you are agreeing with the Developer Certificate of
-Origin (found in Documentation/ and at http://developercertificate.org/).
+Origin (found in [Documentation/Developer_Certificate_of_Origin](Developer_Certificate_of_Origin)
+and at <http://developercertificate.org/>).
 
 All contributions of any sort, including code from other projects, must be
 compatible with the GPLv2.
 
 All contributions of any sort, including code from other projects, must be
 compatible with the GPLv2.
@@ -60,10 +61,10 @@ Attacking people is not.
 Contribution Steps
 ---------------------------
 The short version of adding code to Akaros:
 Contribution Steps
 ---------------------------
 The short version of adding code to Akaros:
-- Email the list early and often
-- Push to a remote branch (not master)
-- Get someone (brho) to shepherd your work
-- Fix up your commits until they are merged
++ Email the list early and often
++ Push to a remote branch (not master)
++ Get someone (brho) to shepherd your work
++ Fix up your commits until they are merged
 
 Contact the list before starting on a major project.  I may already have plans
 or initial thoughts on the matter, and someone on the list can provide advice.
 
 Contact the list before starting on a major project.  I may already have plans
 or initial thoughts on the matter, and someone on the list can provide advice.
@@ -71,15 +72,15 @@ Likewise, don't break long term plans or be too invasive for no reason.
 Otherwise, I might not accept the change at all.
 
 The end goal for a major change is to have a sane series of patches that
 Otherwise, I might not accept the change at all.
 
 The end goal for a major change is to have a sane series of patches that
-applies cleanly to origin/master.  Sane, means there are not a lot of "oh wait,
+applies cleanly to `origin/master`.  Sane, means there are not a lot of "oh wait,
 this patch is wrong, reverting".  The patch series should tell a story of
 getting from A to B, where each patch is easily reviewable.
 
 Push your changes to a separate branch, and email the list asking for advice or
 review.  Someone, usually me, will shepherd your work, providing feedback and
 this patch is wrong, reverting".  The patch series should tell a story of
 getting from A to B, where each patch is easily reviewable.
 
 Push your changes to a separate branch, and email the list asking for advice or
 review.  Someone, usually me, will shepherd your work, providing feedback and
-TODOs.  Name your branch something reasonable (e.g. "inferno-b" and
-"inferno-r").  Your username is a suitable branch name, if you don't want to
-bother with a title.  If you do not have access to the brho:origin/ repo, then
+TODOs.  Name your branch something reasonable (e.g. `inferno-b` and
+`inferno-r`).  Your username is a suitable branch name, if you don't want to
+bother with a title.  If you do not have access to the `brho:origin/` repo, then
 push it somewhere else on github and email us your git remotes info.  The only
 people with push access are those I know personally.  As the group grows, that
 will not scale and people will need to start using their own repos.  For now, a
 push it somewhere else on github and email us your git remotes info.  The only
 people with push access are those I know personally.  As the group grows, that
 will not scale and people will need to start using their own repos.  For now, a
@@ -94,7 +95,7 @@ whatever branch you push.
 
 In general, I prefer not to merge, but it may be necessary based on the age of
 the changed branch.  If we scale out and have various submaintainers, we'll
 
 In general, I prefer not to merge, but it may be necessary based on the age of
 the changed branch.  If we scale out and have various submaintainers, we'll
-merge those branches into the main repo.  But at this point, the brho:origin/
+merge those branches into the main repo.  But at this point, the `brho:origin/`
 repo is a 'leaf' (the one and only leaf).  We'll hold off on merging until we
 have many leaves.
 
 repo is a 'leaf' (the one and only leaf).  We'll hold off on merging until we
 have many leaves.
 
@@ -110,7 +111,7 @@ but you don't want to change everything in one commit.
 
 If a patch relied on spatch, provide the commands or scripts used.
 
 
 If a patch relied on spatch, provide the commands or scripts used.
 
-Remember that someone other than yourself  has to look at each of these
+Remember that someone other than yourself has to look at each of these
 commits.
 
 
 commits.
 
 
@@ -119,64 +120,64 @@ Coding Standard
 Our coding standard is similar to the Linux kernel style (but with a tabstop of
 4), so when in doubt, do what they do.
 
 Our coding standard is similar to the Linux kernel style (but with a tabstop of
 4), so when in doubt, do what they do.
 
-- If you are bringing in code from a project other than Linux, run
-  scripts/lindent.sh on it.  Lindent isn't perfect, but it's close enough.
++ If you are bringing in code from a project other than Linux, run
+  `scripts/lindent.sh` on it.  Lindent isn't perfect, but it's close enough.
   Linux code is usually fine (even with 8 space tabs), and lindent sometimes
   does more harm than good on that code.
 
   Linux code is usually fine (even with 8 space tabs), and lindent sometimes
   does more harm than good on that code.
 
-- You'll note that old code may lack the correct style, especially due to the
++ You'll note that old code may lack the correct style, especially due to the
   large bodies of code from other systems involved.  Typically, we fix it when
   fixing the code for other reasons, so that git blame points at the most
   recent relevant change.
 
   large bodies of code from other systems involved.  Typically, we fix it when
   fixing the code for other reasons, so that git blame points at the most
   recent relevant change.
 
-- No spaces after the name of a function in a call.  For example,
-  printk("hello") not printk ("hello").
++ No spaces after the name of a function in a call.  For example,
+  `printk("hello")` not `printk ("hello")`.
 
 
-- Functions that take no arguments are declared f(void) not f().
++ Functions that take no arguments are declared `f(void)` not `f()`.
 
 
-- Function names are all lower-case, separated by underscores.
++ Function names are all lower-case, separated by underscores.
 
 
-- One space after commas.  For example foo(x, y, z), not foo(x,y,z);
++ One space after commas.  For example `foo(x, y, z)`, not `foo(x,y,z)`.
 
 
-- One space after keywords "if", "for", "while", "switch".  For example, if
-  (x) not if(x).
++ One space after keywords `if`, `for`, `while`, `switch`.  For example,
+  `if (x)` not `if(x)`.
 
 
-- Space before braces.  For example, if (x) { not if (x){.
++ Space before braces.  For example, `if (x) {` not `if (x){`.
 
 
-- For if/while/etc, the opening brace is on the same line as the if.  If you
-  have just one line, no brace is necessary.  If you have an if / else clause,
-  and one of them has braces, put braces on both.  An else line should start
++ For `if/while/etc`, the opening brace is on the same line as the `if`.  If you
+  have just one line, no brace is necessary.  If you have an `if / else` clause,
+  and one of them has braces, put braces on both.  An `else` line should start
   with a brace.
 
   with a brace.
 
-- Beginning-of-line indentation via tabs, not spaces.  Use spaces for
++ Beginning-of-line indentation via tabs, not spaces.  Use spaces for
   additional formatting (such as lining up text when word wrapping).
 
   additional formatting (such as lining up text when word wrapping).
 
-- Preprocessor macros are usually upper-case.  Try to avoid using macros
++ Preprocessor macros are usually upper-case.  Try to avoid using macros
   unless necessary (I prefer static inlines).
 
   unless necessary (I prefer static inlines).
 
-- Pointer declarations have the * on the variable.  void *x, not void* x.
++ Pointer declarations have the `*` on the variable: `void *x`, not `void* x`.
 
 
-- Multi-word names are lower_case_with_underscores.  Keep your names short,
++ Multi-word names are lower_case_with_underscores.  Keep your names short,
   especially for local variables.
 
   especially for local variables.
 
-- 'Permanent' comments in are C /* ... */ comments.  Only use C++ style (//)
++ 'Permanent' comments in are C `/* ... */` comments.  Only use C++ style (`//`)
   for temporary commenting-out, such as if you want to not call a function.
   for temporary commenting-out, such as if you want to not call a function.
-  If you want to block out large chunks of code, use #if 0 ... #endif
+  If you want to block out large chunks of code, use `#if 0 ... #endif`
 
 
-- In a function definition, the function name shoud NOT start a new line.  Old
++ In a function definition, the function name should NOT start a new line.  Old
   code incorrectly does this, and should be changed over time.
   code incorrectly does this, and should be changed over time.
-- Feel free to use gotos, especially in functions that have cleanup before
+
++ Feel free to use `goto`, especially in functions that have cleanup before
   they exit, or in other places that enhance readability.
 
   they exit, or in other places that enhance readability.
 
-- 80 characters per line.  When you wrap, try to line things up so they make
++ 80 characters per line.  When you wrap, try to line things up so they make
   sense, such as space-indenting so function arguments line up vertically.
 
   sense, such as space-indenting so function arguments line up vertically.
 
-- Do not typedef structs.  You can typedef function pointers when convenient.
++ Do not `typedef` structs.  You can `typedef` function pointers when convenient.
   Keep in mind that typedefs require people to look up the real type when they
   analyze the code.
 
   Keep in mind that typedefs require people to look up the real type when they
   analyze the code.
 
-- Try to avoid making lots of separate files or extravagant directory
++ Try to avoid making lots of separate files or extravagant directory
   hierarchies.  Keep in mind that people will need to work with and find these
   files (even via tab completion, it can be a pain).
 
   hierarchies.  Keep in mind that people will need to work with and find these
   files (even via tab completion, it can be a pain).
 
@@ -191,18 +192,19 @@ describe how I use git to make changes to Akaros.
 
 First off, visualizing the git tree is extremely useful.  I use:
 
 
 First off, visualizing the git tree is extremely useful.  I use:
 
-$ gitk --all &
+`$ gitk --all &`
 
 If you only have a terminal, you can use git log for a similar effect:
 
 
 If you only have a terminal, you can use git log for a similar effect:
 
-$ git log --graph --full-history --all --color
---pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m"
+`$ git log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m"`
 
 
-That's pretty crazy, so I have the following in my ~/.gitconfig
+That's pretty crazy, so I have the following in my `~/.gitconfig`
 
 
+```
 [alias]
 [alias]
-           gr  = log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m" 
+           gr  = log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m"
         grs = log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m" --simplify-by-decoration
         grs = log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m" --simplify-by-decoration
+```
 
 With those aliases, I only need to do `git gr`.
 
 
 With those aliases, I only need to do `git gr`.
 
@@ -212,33 +214,35 @@ With those aliases, I only need to do `git gr`.
 Let's say you want to make a minor change to say, the kernel monitor.  To start
 things off, make sure you are up to date.
 
 Let's say you want to make a minor change to say, the kernel monitor.  To start
 things off, make sure you are up to date.
 
+```
 $ git checkout master          # make sure you're on master
 $ git fetch                            # grab the latest from origin/
 $ git merge origin/master
 $ git checkout master          # make sure you're on master
 $ git fetch                            # grab the latest from origin/
 $ git merge origin/master
+```
 
 Many people simply do a git pull to get the latest.  I tend to fetch, then
 merge manually after glancing at the stream of changes.  If you ever see a
 (XCC) in one of the commit messages, then you may need to rebuild your
 toolchain.
 
 
 Many people simply do a git pull to get the latest.  I tend to fetch, then
 merge manually after glancing at the stream of changes.  If you ever see a
 (XCC) in one of the commit messages, then you may need to rebuild your
 toolchain.
 
-Time to make our change.  Let's make a branch called 'monitor-change':
+Time to make our change.  Let's make a branch called `monitor-change`:
 
 
-$ git checkout -b monitor-change
+`$ git checkout -b monitor-change`
 
 
-Edit, compile, and test a change, say in kern/src/monitor.c
+Edit, compile, and test a change, say in `kern/src/monitor.c`
 
 
-$ git add -p kern/src/monitor.c
+`$ git add -p kern/src/monitor.c`
 
 
-The -p flag allows you to incrementally add and review each diff chunk.  It's
+The `-p` flag allows you to incrementally add and review each diff chunk.  It's
 very useful for committing only what you want from a set of changes in your
 working directory.
 
 very useful for committing only what you want from a set of changes in your
 working directory.
 
-$ git status
+`$ git status`
 
 Take a look at things before you commit; see if you missed any files or added
 anything you don't want.
 
 
 Take a look at things before you commit; see if you missed any files or added
 anything you don't want.
 
-$ git commit
+`$ git commit`
 
 Write a descriptive message, with a short, one-line summary first.  e.g.
 
 
 Write a descriptive message, with a short, one-line summary first.  e.g.
 
@@ -248,22 +252,24 @@ Author: Barret Rhoden <brho@cs.berkeley.edu>
 Date:   Mon Jan 19 18:36:07 2015 -0500
 
     Fixes kernel argument checking in "m"
 Date:   Mon Jan 19 18:36:07 2015 -0500
 
     Fixes kernel argument checking in "m"
-    
+
     Need at least one argument before dereferencing.
     Need at least one argument before dereferencing.
-    
+
     Also, debugcmd is pretty handy.
 ```
 
 Oh wait, say you messed up the commit message or some part of the code.  You
 can make the change and amend the commit.
 
     Also, debugcmd is pretty handy.
 ```
 
 Oh wait, say you messed up the commit message or some part of the code.  You
 can make the change and amend the commit.
 
+```
 $ vi kern/src/monitor.c
 $ git add -p kern/src/monitor.c
 $ git commit --amend                   # can also change the commit message
 $ vi kern/src/monitor.c
 $ git add -p kern/src/monitor.c
 $ git commit --amend                   # can also change the commit message
+```
 
 Now that you are happy, push it.
 
 
 Now that you are happy, push it.
 
-$ git push origin monitor-change
+`$ git push origin monitor-change`
 
 Email the mailing list or your nearest shepherd, and we'll take a look!
 
 
 Email the mailing list or your nearest shepherd, and we'll take a look!
 
@@ -276,70 +282,78 @@ and probably should be several smaller, logically consistent commits.
 You may have already added some of the changes to the index.  To reset the
 index (what git will commit in the next commit):
 
 You may have already added some of the changes to the index.  To reset the
 index (what git will commit in the next commit):
 
-$ git reset HEAD
+`$ git reset HEAD`
 
 Now, your changes are unstaged.  Confirm with:
 
 
 Now, your changes are unstaged.  Confirm with:
 
-$ git status
+`$ git status`
 
 
-Now you want to add some, but not all, of your changes to monitor.c:
+Now you want to add some, but not all, of your changes to `monitor.c`:
 
 
-$ git add -p kern/src/monitor.c kern/src/other_files_too.c
+`$ git add -p kern/src/monitor.c kern/src/other_files_too.c`
 
 Select only the changes you want, then commit:
 
 
 Select only the changes you want, then commit:
 
-$ git commit  # write message
+`$ git commit  # write message`
 
 Then make further commits:
 
 
 Then make further commits:
 
+```
 $ git add -p kern/src/monitor ; git commit
 $ git add -p kern/src/monitor ; git commit
 
 $ git push origin monitor-change
 $ git add -p kern/src/monitor ; git commit
 $ git add -p kern/src/monitor ; git commit
 
 $ git push origin monitor-change
+```
 
 
 ### Someone Changed origin/master; My Branch is Now Old
 
 
 
 ### Someone Changed origin/master; My Branch is Now Old
 
-Typically, we want branches to descend from origin/master.  But if multiple
-people are working at a time, someone will fall behind.  With Git, dealing with
+Typically, we want branches to descend from `origin/master`.  But if multiple
+people are working at a time, someone will fall behind.  With git, dealing with
 this situation is extremely easy.  You just need to rebase your current branch
 on the new master.
 
 this situation is extremely easy.  You just need to rebase your current branch
 on the new master.
 
-Say you are on the branch monitor-change, and origin/master has updated.
+Say you are on the branch `monitor-change`, and `origin/master` has updated.
 Here's a reasonable workflow to deal with this situation:
 
 Here's a reasonable workflow to deal with this situation:
 
+```
 $ git fetch                            # notice origin/master changed
 $ git checkout master          # switch to master
 $ git merge origin/master      # fast-forward merge - straight line of commits
 $ git fetch                            # notice origin/master changed
 $ git checkout master          # switch to master
 $ git merge origin/master      # fast-forward merge - straight line of commits
+```
 
 
-Master is now up to date.  git pull --rebase does this too, though I prefer to
+Master is now up to date.  `git pull --rebase` does this too, though I prefer to
 always fetch first.
 
 always fetch first.
 
+```
 $ git checkout monitor-change  # needed if you aren't on monitor-change
 $ git rebase master
 $ git checkout monitor-change  # needed if you aren't on monitor-change
 $ git rebase master
+```
 
 Now monitor-change descends from the latest master.
 
 A short-cut for the last two commands is:
 
 
 Now monitor-change descends from the latest master.
 
 A short-cut for the last two commands is:
 
-$ git rebase master monitor-change
+`$ git rebase master monitor-change`
 
 The last parameter is simply an implied `git checkout`.
 
 Don't forget to recompile and skim the log from the master update.  If you
 already pushed your branch to the repo, you'll want to update that branch.
 
 
 The last parameter is simply an implied `git checkout`.
 
 Don't forget to recompile and skim the log from the master update.  If you
 already pushed your branch to the repo, you'll want to update that branch.
 
-$ git push -f origin monitor-change
+`$ git push -f origin monitor-change`
 
 
-The -f replaces the origin/monitor-change with your monitor-change.  See below
-for more on -f.
+The `-f` replaces the `origin/monitor-change` with your `monitor-change`.  See below
+for more on `-f`.
 
 If you don't want to bother with maintaining your master right now, you can cut
 
 If you don't want to bother with maintaining your master right now, you can cut
-it down to a few steps (assuming you are on SOMEBRANCH):
+it down to a few steps (assuming you are on `SOMEBRANCH`):
 
 
+```
 $ git fetch
 $ git rebase origin/master
 $ git push -f origin/SOMEBRANCH
 $ git fetch
 $ git rebase origin/master
 $ git push -f origin/SOMEBRANCH
+```
 
 
 ### Oh No, I Committed and Pushed Something I Want to Change
 
 
 ### Oh No, I Committed and Pushed Something I Want to Change
@@ -347,8 +361,9 @@ $ git push -f origin/SOMEBRANCH
 Fear not, adjusting git's history is very easy, and we do it all the time on
 branches other than origin/master.
 
 Fear not, adjusting git's history is very easy, and we do it all the time on
 branches other than origin/master.
 
-Let's say you have a string of commits, e.g.: (edited from my git gr)
+Let's say you have a string of commits, e.g.: (edited from my `git gr`)
 
 
+```
 * 876d5b0        (HEAD, vmmcp, origin/vmmcp) VMM: handle EPT page faults
 * f926c02        Fixes VMR creating off-by-one
 * f62dd6c        VMM: Removes the epte_t from pte_t   Crap - bugs!
 * 876d5b0        (HEAD, vmmcp, origin/vmmcp) VMM: handle EPT page faults
 * f926c02        Fixes VMR creating off-by-one
 * f62dd6c        VMM: Removes the epte_t from pte_t   Crap - bugs!
@@ -356,55 +371,69 @@ Let's say you have a string of commits, e.g.: (edited from my git gr)
 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
 * ddb9fa7        x86: EPT and KPT are contiguous
 * 1234567        (master, origin/master) Some Other Commit
 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
 * ddb9fa7        x86: EPT and KPT are contiguous
 * 1234567        (master, origin/master) Some Other Commit
+```
 
 
-You're working on the vmmcp branch, and you realize that d76b4c6 adds a bunch
-of debug printks in it and that there is a bug in HEAD that you introduced in
-f62dd6c.
+You're working on the `vmmcp` branch, and you realize that `d76b4c6` adds a bunch
+of debug `printk`s in it and that there is a bug in `HEAD` that you introduced in
+`f62dd6c`.
 
 
-The lousy option would be to make a new commit on top of 876d5b0 (HEAD) that
+The lousy option would be to make a new commit on top of `876d5b0 (HEAD)` that
 removes the prints and fixes the bugs.  The problem with this is that there is
 no reason for people to even know those existed in the first place, and by
 removes the prints and fixes the bugs.  The problem with this is that there is
 no reason for people to even know those existed in the first place, and by
-leaving the bugs and printks in old code you only increase the load on your
+leaving the bugs and `printk`s in old code you only increase the load on your
 shepherd.
 
 shepherd.
 
-Not to worry, you can use git rebase -i to interactively replay the commits
-from master..vmmcp and rewrite the commits along the way.
+Not to worry, you can use `git rebase -i` to interactively replay the commits
+from `master..vmmcp` and rewrite the commits along the way.
 
 
-First up, make sure you are on vmmcp and do a rebase -i.
+First up, make sure you are on `vmmcp` and do a `git rebase -i`.
 
 
+```
 $ git checkout vmmcp
 $ git rebase -i master
 $ git checkout vmmcp
 $ git rebase -i master
+```
 
 
-This will replay all commits from (1234567, 876d5b0] (not including 1234567) on
-top of master (1234567).  Check out git help rebase for more info, including some nifty diagrams.  In short, that rebase command is the shorthand for:
+This will replay all commits from (`1234567`, `876d5b0`] (not including `1234567`) on
+top of `master` (`1234567`).  Check out `git help rebase` for more info,
+including some nifty diagrams.  In short, that `rebase` command is the shorthand
+for:
 
 
-$ git rebase -i --onto master master vmmcp
+`$ git rebase -i --onto master master vmmcp`
 
 
-The rebase command -i option (interactive) will pop open an editor, where you
+The `rebase` command `-i` option (interactive) will pop open an editor, where you
 can change the order of commits, squash multiple commits into a single commit,
 can change the order of commits, squash multiple commits into a single commit,
-or stop and edit the commit.  Note that commits are presented in the order in which they will be committed, which is the opposite of gitk and git gr, where the newest commit is on top.
+or stop and edit the commit.  Note that commits are presented in the order in
+which they will be committed, which is the opposite of `gitk` and `git gr`, where
+the newest commit is on top.
 
 
-Let's edit the commit d76b4c6 (change 'pick' to 'e').  Save and exit, and the rebase will proceed.  When git hits that commit, it will stop and you can amend your commit.
+Let's edit the commit `d76b4c6` (change '`pick`' to '`e`').  Save and exit, and the
+rebase will proceed.  When git hits that commit, it will stop and you can amend
+your commit.
 
 
+```
 $ vi somefile                  # make your changes
 $ git add -p somefile          # add them to the index (building a commit)
 $ git commit --amend   # amend your *old* commit (d76b4c6)
 $ git status                   # see how you are doing
 $ git rebase --continue
 $ vi somefile                  # make your changes
 $ git add -p somefile          # add them to the index (building a commit)
 $ git commit --amend   # amend your *old* commit (d76b4c6)
 $ git status                   # see how you are doing
 $ git rebase --continue
+```
 
 
-Now check it out in gitk or git gr.  It's like your debug printks never
+Now check it out in `gitk` or `git gr`.  It's like your debug `printk`s never
 existed.
 
 Another approach is to build a temporary commit and use it as a fixup commit.
 existed.
 
 Another approach is to build a temporary commit and use it as a fixup commit.
-Let's do that to fix the bug in f62dd6c.
+Let's do that to fix the bug in `f62dd6c`.
 
 
+```
 $ git checkout vmmcp   # start from the top of the tree
 $ vi somefile                  # make your changes
 $ git add -p somefile  # stage the changes
 $ git commit -m WIP-fixes-vmm-bug
 $ git checkout vmmcp   # start from the top of the tree
 $ vi somefile                  # make your changes
 $ git add -p somefile  # stage the changes
 $ git commit -m WIP-fixes-vmm-bug
+```
 
 You now have something like:
 
 
 You now have something like:
 
+```
 * 13a95cc        (HEAD, vmmcp) WIP-fixes-vmm-bug
 * 876d5b0        (origin/vmmcp) VMM: handle EPT page faults
 * f926c02        Fixes VMR creating off-by-one
 * 13a95cc        (HEAD, vmmcp) WIP-fixes-vmm-bug
 * 876d5b0        (origin/vmmcp) VMM: handle EPT page faults
 * f926c02        Fixes VMR creating off-by-one
@@ -413,103 +442,108 @@ You now have something like:
 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
 * ddb9fa7        x86: EPT and KPT are contiguous
 * 1234567        (master, origin/master) Some Other Commit
 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
 * ddb9fa7        x86: EPT and KPT are contiguous
 * 1234567        (master, origin/master) Some Other Commit
+```
 
 Clearly you don't want that WIP commit (WIP = work in progress).  Let's rebase!
 
 
 Clearly you don't want that WIP commit (WIP = work in progress).  Let's rebase!
 
-$ git rebase -i master
+`$ git rebase -i master`
 
 
-Reorder the commits so that the WIP happens after f62dd6c, and change the WIP's
-command from 'pick' to 'f'.
+Reorder the commits so that the WIP happens after `f62dd6c`, and change the WIP's
+command from '`pick`' to '`f`'.
 
 Assuming everything applies cleanly, you're done.  The WIP approach is even
 
 Assuming everything applies cleanly, you're done.  The WIP approach is even
-easier than the rebase with amend.  I use it when a change applies to both the
+easier than the `rebase` with `amend`.  I use it when a change applies to both the
 current tip as well as the faulty commit.
 
 current tip as well as the faulty commit.
 
-You can even use git rebase to logically reorder commits so that together, the
+You can even use `git rebase` to logically reorder commits so that together, the
 'story' is more cohesive.
 
 'story' is more cohesive.
 
-But wait, your version of vmmcp differs from origin/vmmcp!  The repo's vmmcp
-branch still looks like the old one.  You need to push -f to force the repo's
+But wait, your version of `vmmcp` differs from `origin/vmmcp`!  The repo's `vmmcp`
+branch still looks like the old one.  You need to `push -f` to force the repo's
 branch to agree with yours:
 
 branch to agree with yours:
 
-$ git push -f origin vmmcp
+`$ git push -f origin vmmcp`
 
 
-This will destroy the original origin/vmmcp and replace it with your vmmcp.
-Anyone who was tracking origin/vmmcp will need to reset their branch.  Do not
-do this to origin/master.
+This will destroy the original `origin/vmmcp` and replace it with your `vmmcp`.
+Anyone who was tracking `origin/vmmcp` will need to reset their branch.  Do not
+do this to `origin/master`.
 
 
-Just remember: gitk, git rebase, and git commit --amend are your friends.
+Just remember: `gitk`, `git rebase`, and `git commit --amend` are your friends.
 
 
 ### Crap, Someone Reset a Branch I was Tracking!
 
 
 
 ### Crap, Someone Reset a Branch I was Tracking!
 
-Say you were working on origin/vmmcp while someone else did the steps from the
-previous section.  You do a git fetch and see that you differ!
+Say you were working on `origin/vmmcp` while someone else did the steps from the
+previous section.  You do a `git fetch` and see that you differ!
 
 
-If you don't have any changes from the original origin/vmmcp, then you can
+If you don't have any changes from the original `origin/vmmcp`, then you can
 simply:
 
 simply:
 
+```
 $ git checkout vmmcp
 $ git reset --hard origin/vmmcp
 $ git checkout vmmcp
 $ git reset --hard origin/vmmcp
+```
 
 
-This throws away any differences between your tree and origin/vmmcp, in essence
-making it replicate the current state of origin/vmmcp.  If you had any changes,
+This throws away any differences between your tree and `origin/vmmcp`, in essence
+making it replicate the current state of `origin/vmmcp`.  If you had any changes,
 you just lost them.  Yikes!  If in doubt, you can make a temp branch before
 doing anything dangerous with reset.
 
 you just lost them.  Yikes!  If in doubt, you can make a temp branch before
 doing anything dangerous with reset.
 
-$ git branch temp              # keeps a pointer called 'temp' to the current tip
+`$ git branch temp             # keeps a pointer called 'temp' to the current tip`
 
 Say you do have changes.  Now what?  If they are just diffs, but not commits,
 
 Say you do have changes.  Now what?  If they are just diffs, but not commits,
-you can stash them, then replay the changes on the new vmmcp branch:
+you can stash them, then replay the changes on the new `vmmcp` branch:
 
 
+```
 $ git stash
 $ git reset --hard origin/vmmcp
 $ git stash pop         # might not apply cleanly
 $ git stash
 $ git reset --hard origin/vmmcp
 $ git stash pop         # might not apply cleanly
+```
 
 If you did have commits, you'll want to rebase.  You are trying to rebase the
 
 If you did have commits, you'll want to rebase.  You are trying to rebase the
-commits from your old vmmcp branch to the new one:
+commits from your old `vmmcp` branch to the new one:
 
 
-$ git rebase --onto origin/vmmcp PREVIOUS-ORIGIN-VMMCP
+`$ git rebase --onto origin/vmmcp PREVIOUS-ORIGIN-VMMCP`
 
 
-You'll need to look at gitk, git log, git gr, or whatever to find the commit
-name (SHA1) of the original origin/vmmcp (before you fetched).  For this
+You'll need to look at `gitk`, `git log`, `git gr`, or whatever to find the commit
+name (SHA1) of the original `origin/vmmcp` (before you fetched).  For this
 reason, you could have a branch called vmmcp-mine for all of your changes, and
 reason, you could have a branch called vmmcp-mine for all of your changes, and
-keep your branch vmmcp around to just track origin/vmmcp.  This is what many
-people do with master: it only tracks origin/master, and all changes happen on
+keep your branch `vmmcp` around to just track `origin/vmmcp`.  This is what many
+people do with `master`: it only tracks `origin/master`, and all changes happen on
 separate branches.
 
 Note that you can probably just do a:
 
 separate branches.
 
 Note that you can probably just do a:
 
-$ git rebase origin/vmmcp
+`$ git rebase origin/vmmcp`
 
 and git will figure out and exclude which commits you have in common with
 
 and git will figure out and exclude which commits you have in common with
-origin/vmmcp from the rebase.  Check your results in gitk or git gr.
+`origin/vmmcp` from the rebase.  Check your results in `gitk` or `git gr`.
 
 This can be rather tricky, which is part of the reason why you shouldn't reset
 
 This can be rather tricky, which is part of the reason why you shouldn't reset
-branches that other people rely on (e.g. origin/master).  It's fine for small
+branches that other people rely on (e.g. `origin/master`).  It's fine for small
 group or individual work.
 
 group or individual work.
 
-Just remember: gitk and git rebase are your friends.
+Just remember: `gitk` and `git rebase` are your friends.
 
 
 
 
-### What Happens When Two People Push -f
+### What Happens When Two People `push -f`
 
 Whoever pushes most recently is the one to clobber the branch.  The previous
 person's commits would only exist in that person's personal repo!  Yikes!
 
 
 Whoever pushes most recently is the one to clobber the branch.  The previous
 person's commits would only exist in that person's personal repo!  Yikes!
 
-In general, don't clobber (push -f) other people's branches without
+In general, don't clobber (`push -f`) other people's branches without
 coordinating first.  I reset my origin branches all the time.  I won't usually
 reset other people's branches without checking with them.
 
 If clobbering repo branches is a problem, you can always create your own repo
 branch; branches are very cheap and easy.
 
 coordinating first.  I reset my origin branches all the time.  I won't usually
 reset other people's branches without checking with them.
 
 If clobbering repo branches is a problem, you can always create your own repo
 branch; branches are very cheap and easy.
 
-To delete a remote branch, say after it is merged into origin/master:
+To delete a remote branch, say after it is merged into `origin/master`:
 
 
-$ git push -f origin :BRANCH-NAME
+`$ git push -f origin :BRANCH-NAME`
 
 The : is part of the "refspec"; whatever is on the left is the source (in this
 
 The : is part of the "refspec"; whatever is on the left is the source (in this
-case, nothing).  Check out git help push for more info.
+case, nothing).  Check out `git help push` for more info.
 
 Again, these techinques work well with small groups, but not for big branches
 
 Again, these techinques work well with small groups, but not for big branches
-like origin/master.
+like `origin/master`.
index 0bb9f9b..17a1af5 100644 (file)
@@ -1,7 +1,25 @@
-GETTING_STARTED
+Getting Started with Akaros
+==========================
 Barret Rhoden
 
 Barret Rhoden
 
-Last thorough update: 2013-02-07
+Last thorough update: **2013-02-07**
+
+Contents
+-----------
++ Overview
++ Need Help?
++ From Download to Hello World
+  - Cross compiler (and glibc)
+  - Kernel
+  - Userspace
+  - Busybox
+  - Building and Loading a Virtual Machine Image
+  - Running Qemu
+  - Running on Hardware
+  - Hello World
+  - Other Dev Workflow Stuff
++ RISCV
++ Other Developer's Stuff
 
 
 1. Overview
 
 
 1. Overview
@@ -15,282 +33,288 @@ need to do some configuration of your environment.  Things won't magically work
 out of the box.
 
 
 out of the box.
 
 
-2. Need help?
+2. Need Help?
 ---------------------
 First off, if you get stuck, email someone.  You can join our mailing list by
 ---------------------
 First off, if you get stuck, email someone.  You can join our mailing list by
-sending an email to akaros-request@lists.eecs.berkeley.edu.  Send your messages
-to akaros@lists.eecs.berkeley.edu.  Or just email me (brho@cs), though the
-mailing list is a more scalable method in the long run.
+sending an email to <akaros-request@lists.eecs.berkeley.edu>.  Once you've
+joined, send your messages to <akaros@lists.eecs.berkeley.edu>.  Or just email
+me (<brho@cs>), though the mailing list is a more scalable method in the long
+run.
 
 
-Alternatively, you can poke your head in #akaros on irc.freenode.net.  I'm
+Alternatively, you can poke your head in #akaros on `irc.freenode.net`.  I'm
 usually idling in there (alone), and if I'm at my computer, I'll respond.
 
 
 3. From Download to Hello World
 usually idling in there (alone), and if I'm at my computer, I'll respond.
 
 
 3. From Download to Hello World
----------------------
+----------------------------
 I'll describe how to get x86 working.  RISCV is similar.
 
 I'll describe how to get x86 working.  RISCV is similar.
 
-The first step is to configure the kernel.  config, menuconfig, and some of the
-other KBuild targets work.  Defconfig gives you a default configuration.  For
-example, to config for 64-bit x86:
+The first step is to configure the kernel.  Targets like `config`,
+`menuconfig`, and some of the other KBuild targets work.  Defconfig gives you a
+default configuration.  For example, to config for 64-bit x86:
 
 
-$ make ARCH=x86 defconfig
+`$ make ARCH=x86 defconfig`
 
 Alternatively, you can run menuconfig to customize what settings you want:
 
 
 Alternatively, you can run menuconfig to customize what settings you want:
 
-$ make ARCH=x86 menuconfig
+`$ make ARCH=x86 menuconfig`
 
 
-For x86, you can choose between 32 and 64 bit when you make menuconfig.  This
-selection must match your cross compiler make command.  The default is 64 bit.
+For x86, you can choose between 32 and 64 bit when you `make menuconfig`.  This
+selection must match your cross compiler `make` command.  The default is 64
+bit.
 
 
-There are a lot of other settings when you make config, and you should browse
+There are a lot of other settings when you `make config`, and you should browse
 through to decide what you want to enable/disable.
 
 Most everyone wants KFS turned on (Filesystems --> KFS filesystem).  This is
 the in-memory filesystem that the kernel uses.  The kernel build scripts will
 look at the "KFS/Initramfs paths" string and take any of those directories and
 add them to a CPIO archive that will eventually become the root filesystem when
 through to decide what you want to enable/disable.
 
 Most everyone wants KFS turned on (Filesystems --> KFS filesystem).  This is
 the in-memory filesystem that the kernel uses.  The kernel build scripts will
 look at the "KFS/Initramfs paths" string and take any of those directories and
 add them to a CPIO archive that will eventually become the root filesystem when
-Akaros runs. These settings are set by default when you do a 'make defconfig'.
+Akaros runs. These settings are set by default when you do a `make defconfig`.
 
 
-There are also settings for ext2.  If you turn on ext2 support, you need to
-point to an img file that has been formatted with ext2 and has files in it.  If
-you aren't messing with filesystems at all, feel free to ignore this.  It's an
-in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
-gain much by using it for now.
+There are also settings for `ext2`.  If you turn on `ext2` support, you need to
+point to an `img` file that has been formatted with `ext2` and has files in it.
+If you aren't messing with filesystems at all, feel free to ignore this.  It's
+an in-memory filesystem, like KFS (linked to the end of the kernel), so you
+won't gain much by using it for now.
 
 
-3.1 Cross compiler (and glibc)
-----------
+### 3.1 Cross compiler (and glibc)
 The second step is to build the cross compiler, which lives in
 The second step is to build the cross compiler, which lives in
-tools/compilers/gcc-glibc
+`tools/compilers/gcc-glibc`
 
 
-$ cd tools/compilers/gcc-glibc
+`$ cd tools/compilers/gcc-glibc`
 
 In this directory, you first need to set up your Makelocal file.  There is a
 template to work from.
 
 
 In this directory, you first need to set up your Makelocal file.  There is a
 template to work from.
 
-$ cp Makelocal.template Makelocal
+`$ cp Makelocal.template Makelocal`
 
 
-You need to set your INSTDIRS to some place where you want the cross compiler
-installed.  I have a directory named ros-gcc-glibc for this.
+You need to set your `INSTDIRS` to some place where you want the cross compiler
+installed.  I have a directory named `akaros-gcc-glibc` for this.
 
 
-You also need to add bin directories to your PATH where the cross compiler will
-be installed.  This will vary based on your value for INSTDIRS.  For instance,
-my path contains:
+You also need to add `bin` directories to your `PATH` where the cross compiler
+will be installed.  This will vary based on your value for `INSTDIRS`.  For
+instance, my path contains:
 
 
-/home/brho/classes/ros/ros-gcc-glibc/install-x86_64-ros-gcc/bin
+`/home/brho/classes/akaros/akaros-gcc-glibc/install-x86_64-ucb-akaros-gcc/bin`
 
 
-You can also set up MAKE_JOBS, so you don't over or under load your system when
-building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
+You can also set up `MAKE_JOBS`, so you don't over or under load your system when
+building.  I have a 2 core laptop, so I use `MAKE_JOBS := 3`
 
 At this point, you can build (for example):
 
 
 At this point, you can build (for example):
 
-$ make x86_64
+`$ make x86_64`
 
 This might take a while (10-20 minutes for me on a 2007 era laptop).
 
 Just to double check everything installed correctly, you should be able to run
 
 This might take a while (10-20 minutes for me on a 2007 era laptop).
 
 Just to double check everything installed correctly, you should be able to run
-x86_64-ros-gcc from your shell.
+`x86_64-ucb-akaros-gcc` from your shell.
 
 Now, you have a cross compiler ready, and you can start to build Akaros.
 
 
 Now, you have a cross compiler ready, and you can start to build Akaros.
 
-3.2 Kernel
-----------
-cd back into the repo root.
+### 3.2 Kernel
+`cd` back into the repo root.
 
 
-Like the cross compiler, the kernel has its own Makelocal.
+Like the cross compiler, the kernel has its own `Makelocal`.
 
 
-$ cp Makelocal.template Makelocal
+`$ cp Makelocal.template Makelocal`
 
 This file is used to set up custom make targets that are not part of the
 
 This file is used to set up custom make targets that are not part of the
-default Makefile, but fit nicely into your personal workflow. This file is not
-under version control and can me made to contain just about anything.
+default `Makefile`, but fit nicely into your personal workflow. This file is
+not under version control and can me made to contain just about anything.
 
 Now you're ready to build the kernel:
 
 
 Now you're ready to build the kernel:
 
-$ make
+`$ make`
 
 So the kernel built, but you can't do much with it, and you probably have no
 programs.
 
 
 So the kernel built, but you can't do much with it, and you probably have no
 programs.
 
-Notice that we didn't have to set the ARCH variable this time.  The make system
-knows what architecture we are set up for and will always build for that
-architecture until a new ARCh is selected (i.e. via 'make ARCH=xxx defconfig'
+Notice that we didn't have to set the `ARCH` variable this time.  The make
+system knows what architecture we are set up for and will always build for that
+architecture until a new `ARCH` is selected (i.e. via `make ARCH=xxx defconfig`
 etc.)
 
 etc.)
 
-3.3 Userspace
----------
+### 3.3 Userspace
 To build userspace and test programs:
 
 To build userspace and test programs:
 
-$ make tests
+`$ make tests`
 
 You now have programs and libraries, and need to put them in KFS.  To do this,
 
 You now have programs and libraries, and need to put them in KFS.  To do this,
-we provide a 'fill-kfs' make target. 
+we provide a `fill-kfs` make target.
 
 
-$ make fill-kfs
+`$ make fill-kfs`
 
 
-The 'fill-kfs' target copies your cross compiler's shared libraries and all
+The `fill-kfs` target copies your cross compiler's shared libraries and all
 test binaries into the first "KFS/Initramfs path" you set during configuration
 test binaries into the first "KFS/Initramfs path" you set during configuration
-(or kern/kfs/lib if you just kept the default).
+(or `kern/kfs/lib` if you just kept the default).
 
 Now that you've changed the contents of KFS's source, remake the kernel.  You
 
 Now that you've changed the contents of KFS's source, remake the kernel.  You
-should see something like
+should see something like the following before the kernel links.  If you don't
+see this, then you probably didn't actually fill KFS properly.
+
+```
        Building initramfs:
                Adding kern/kfs to initramfs...
        Building initramfs:
                Adding kern/kfs to initramfs...
-before the kernel links.  If you don't see this, then you probably didn't
-actually fill KFS properly.
+```
+
 
 
-3.4 Busybox
----------
+### 3.4 Busybox
 Busybox provides our shell and some basic utilities.  You almost certainly want
 to build and install busybox.
 
 Userspace programs like busybox need to be compiled with the cross compiler and
 Busybox provides our shell and some basic utilities.  You almost certainly want
 to build and install busybox.
 
 Userspace programs like busybox need to be compiled with the cross compiler and
-then have their binaries copied to kern/kfs/bin.  Since most everyone wants
+then have their binaries copied to `kern/kfs/bin`.  Since most everyone wants
 busybox and we have a few patches of our own, we have support for automatically
 building and installing it to KFS.
 
 busybox and we have a few patches of our own, we have support for automatically
 building and installing it to KFS.
 
-For the default build (x86_64):
+For the default build (`x86_64`):
 
 
+```
 $ cd tools/apps/busybox
 $ make [x86_64|riscv]
 $ cd -
 $ cd tools/apps/busybox
 $ make [x86_64|riscv]
 $ cd -
+```
 
 
-And you should be set.  Check kfs to make sure everything installed.  You
+And you should be set.  Check `kfs` to make sure everything installed.  You
 should get sane results from:
 
 should get sane results from:
 
+```
 $ ls -l kern/kfs/bin | grep cat
 lrwxrwxrwx 1 brho brho       7 Jan 23 09:19 cat -> busybox
 $ ls -l kern/kfs/bin | grep cat
 lrwxrwxrwx 1 brho brho       7 Jan 23 09:19 cat -> busybox
+```
 
 You can customize your busybox installation, including the install prefix, the
 
 You can customize your busybox installation, including the install prefix, the
-.config file, and make jobs.  Check out the makefile in tools/apps/busybox for
-details.
+`.config` file, and `make` jobs.  Check out the makefile in
+`tools/apps/busybox` for details.
 
 Now that you've changed KFS, don't forget to remake the kernel.
 
 
 Now that you've changed KFS, don't forget to remake the kernel.
 
-3.5 Building and Loading a Virtual Machine Image
----------
+### 3.5 Building and Loading a Virtual Machine Image
 At this point, you probably have a runnable kernel with programs in KFS.  It
 At this point, you probably have a runnable kernel with programs in KFS.  It
-should be sitting at obj/kernel/akaros-kernel.  When running in a VM, you can
-either run the kernel directly from qemu, or put it in a virtual machine image
-file. 
+should be sitting at `obj/kernel/akaros-kernel`.  When running in a VM, you can
+either run the kernel directly from `qemu`, or put it in a virtual machine
+image file.
 
 If you don't want to bother with the image, skip this section.  I tend to run
 
 If you don't want to bother with the image, skip this section.  I tend to run
-my images off an image file, since qemu acts more like hardware (as far as
+my images off an image file, since `qemu` acts more like hardware (as far as
 multiboot goes).  The downside is the boot up is slower, especially if you have
 a large kernel (>100MB).  It also takes some effort to set up the VM image.
 
 If you are still reading, you'll need an image file that looks like a hard disk
 multiboot goes).  The downside is the boot up is slower, especially if you have
 a large kernel (>100MB).  It also takes some effort to set up the VM image.
 
 If you are still reading, you'll need an image file that looks like a hard disk
-to boot qemu off of.  I put one similar to mine at:
-http://akaros.cs.berkeley.edu/files/hdd268mb.img
-
-It's around 268MB (256MiB, or whatever).  If you want to make your own, check
-out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
-original document I made back when I first figured it out back in 2009, which
-has been updated again in 2013.    In between, I wrote it up online at
-http://www.omninerd.com/articles/Installing_GRUB_on_a_Hard_Disk_Image_File,
-which has some other tidbits in the comments.  Both methods still use grub1.
-
-Anyway, I put that img in AKAROS-ROOT/mnt/, and make a folder next to it:
-AKAROS-ROOT/mnt/hdd.  mnt/hdd is the mount point where I mount hdd.img (Note I
-don't call it hdd64mb.img on my dev machine).
-
-Personally, I always have hdd.img mounted.  Some of the other devs have make
+to boot `qemu` off of.  I put one similar to mine at:
+<http://akaros.cs.berkeley.edu/files/hdd268mb.img>
+
+It's around 268MB (256MiB, or whatever).  If you want to make your own, check out
+[Documentation/howtos/make-bootable-grub-hdd.txt](Documentation/howtos/make-bootable-grub-hdd.txt).
+That's actually the original document I made back when I first figured it out
+back in 2009, which was updated again in 2013.  In between, I wrote it up
+online at
+<http://www.omninerd.com/articles/Installing_GRUB_on_a_Hard_Disk_Image_File>,
+which has some other tidbits in the comments.  Both methods still use `grub1`.
+
+Anyway, I put that img in `AKAROS-ROOT/mnt/`, and make a folder next to it:
+`AKAROS-ROOT/mnt/hdd`.  `mnt/hdd` is the mount point where I mount `hdd.img`
+(Note I don't call it `hdd64mb.img` on my dev machine).
+
+Personally, I always have `hdd.img` mounted.  Some of the other devs have make
 targets that mount and umount it.  Whenever I reboot my development machine, I
 run a script (as root) that mounts the image file and sets up a few things for
 targets that mount and umount it.  Whenever I reboot my development machine, I
 run a script (as root) that mounts the image file and sets up a few things for
-networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll likely
-want to copy it to the directory *above* the akaros root directory and edit it
+networking.  I put a script I use for this in `scripts/kvm-up.sh`.  You'll likely
+want to copy it to the directory **above** the akaros root directory and edit it
 accordingly. Feel free to comment out the networking stuff.  That's for using
 accordingly. Feel free to comment out the networking stuff.  That's for using
-networking in qemu.
+networking in `qemu`.
 
 
-Now that your image file is mounted at mnt/hdd, you'll want to copy your
+Now that your image file is mounted at `mnt/hdd`, you'll want to copy your
 freshly built kernel to the root of the image.  I have a make target in my
 freshly built kernel to the root of the image.  I have a make target in my
-makelocal for this, so that whenever I do a make kvm, it builds the kernel and
-copies it to my hdd.img.
+makelocal for this, so that whenever I do a `make kvm`, it builds the kernel
+and copies it to my `hdd.img`.
 
 I added edited versions of my KVM (and USB) make targets to the
 
 I added edited versions of my KVM (and USB) make targets to the
-Makelocal.template.  Uncomment the KVM one (at least).
+`Makelocal.template`.  Uncomment the KVM one (at least).
 
 
-Incidentally, I also have the following in my Makelocal, so that make (and make
-all) also make kvm:
+Incidentally, I also have the following in my `Makelocal`, so that `make` (and
+`make all`) also make kvm:
 
 
-all: kvm
+`all: kvm`
 
 
-Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
--l and check the timestamp).
+Now, `make kvm`.  You should be able to see the new kernel in `mnt/hdd/` (do an
+`ls -l` and check the timestamp).
 
 
-3.6 Running Qemu
----------
-Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
-will vary based on your linux distribution.  Don't run it just yet:
+### 3.6 Running Qemu
+Here is the command I use to run `qemu`/`kvm`.  It's evolved over the years,
+and it will vary based on your linux distribution.  Don't run it just yet:
 
 
+```
 $ qemu-system-x86_64 -s -enable-kvm -cpu kvm64 -smp 8 -m 4096 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net user,hostfwd=tcp::5555-:23 -net dump,file=/tmp/vm.pcap -drive file=mnt/hdd.img,index=0,media=disk,format=raw
 $ qemu-system-x86_64 -s -enable-kvm -cpu kvm64 -smp 8 -m 4096 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net user,hostfwd=tcp::5555-:23 -net dump,file=/tmp/vm.pcap -drive file=mnt/hdd.img,index=0,media=disk,format=raw
+```
 
 If you skipped making a virtual machine image or want to run the kernel
 
 If you skipped making a virtual machine image or want to run the kernel
-directly without emulating a disk, replace the "-drive" parameter (all the way
-to format=raw) with "-kernel obj/kern/akaros-kernel".
+directly without emulating a disk, replace the "`-drive`" parameter (all the way
+to `format=raw`) with "`-kernel obj/kern/akaros-kernel`".
 
 
-The -monitor is the qemu monitor, which is a CLI for qemu.  Pick a
+The `-monitor` is the qemu monitor, which is a CLI for qemu.  Pick a
 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
-'tty'.  Whatever it tells you, put in place of /dev/pts/3.  I've been using the
-same tab for about 4 years now.  In that tab, enter 'sleep 999999999'.  Qemu
-will still access it, but you won't have to worry about bash trying to handle
-your inputs.
+`tty'.  Whatever it tells you, put in place of `/dev/pts/3`.  I've been using
+the same tab for about 4 years now.  In that tab, enter '`sleep 999999999`'.
+Qemu will still access it, but you won't have to worry about bash trying to
+handle your inputs.
 
 
--nographic allows qemu to work in the terminal you run qemu from, instead of
+`-nographic` allows qemu to work in the terminal you run qemu from, instead of
 spawning off a fake cpu crt/monitor.
 
 spawning off a fake cpu crt/monitor.
 
-The command as written uses QEMU's user networking.  It's emulated and a little
-slow.  The example I have alo forwards port 5555 on the host to port 23 on the
-guest.  Customize it according to your needs.
+The command as written uses qemu's user networking.  It's emulated and a little
+slow.  The example I have alo forwards port `5555` on the host to port `23` on
+the guest.  Customize it according to your needs.
 
 Another option for networking is to set up a tun/tap device.  I use this on
 some machines, and the kvm-up script has some commands to set it up.  It's
 tricky, and may vary for your distribution.  If you do use the tun/tap
 
 Another option for networking is to set up a tun/tap device.  I use this on
 some machines, and the kvm-up script has some commands to set it up.  It's
 tricky, and may vary for your distribution.  If you do use the tun/tap
-networking, replace the "-net user" section with:
+networking, replace the "`-net user`" section with:
 
 
-       -net tap,ifname=tap0,script=no
+`-net tap,ifname=tap0,script=no`
 
 
-The "-net dump" option saves a pcap trace of the network traffic.  This is very
+The "`-net dump`" option saves a pcap trace of the network traffic.  This is very
 useful for debugging, but probably not needed for most people.
 
 Feel free to pick different values for the number of cpus and RAM (8 and 4096
 in the example).
 
 useful for debugging, but probably not needed for most people.
 
 Feel free to pick different values for the number of cpus and RAM (8 and 4096
 in the example).
 
-Once you finally run it, you can stop the VM by entering 'q' to the qemu
+Once you finally run it, you can stop the VM by entering '`q`' to the qemu
 monitor (or just killing the process)..  Other help commands from the monitor
 monitor (or just killing the process)..  Other help commands from the monitor
-include 'info cpus', 'info registers', 'x', and 'help'.
+include '`info cpus`', '`info registers`', '`x`', and '`help`'.
 
 
-In more recent versions of qemu, CTRL-C will not get sent to the guest; instead
-it will kill the VM.  If this gets annoying, you can remap "interrupt" to
-something other than CTRL-C in the terminal where you run qemu:
+In more recent versions of qemu, `CTRL-C` will not get sent to the guest;
+instead it will kill the VM.  If this gets annoying, you can remap "interrupt"
+to something other than `CTRL-C` in the terminal where you run qemu:
 
 
-$ stty intr ^]
+`$ stty intr ^]`
 
 To change it back:
 
 
 To change it back:
 
-$ stty intr ^c
+`$ stty intr ^c`
+
 
 
-3.7 Running on Hardware
----------
+### 3.7 Running on Hardware
 I have a few bootable USB sticks with grub set up to run Akaros.  The make usb
 I have a few bootable USB sticks with grub set up to run Akaros.  The make usb
-target (example in Makelocal.template) will copy freshly made kernels to your
+target (example in `Makelocal.template`) will copy freshly made kernels to your
 USB device.  You'll need to adjust those paths according to your distro.  My
 USB device.  You'll need to adjust those paths according to your distro.  My
-usb sticks are usually /dev/sdc, for instance (some odd USB device in the last
-couple of years has taken over /dev/sdb.  Probably something to do with udev
-changing over the years).
+usb sticks are usually `/dev/sdc`, for instance (some odd USB device in the
+last couple of years has taken over `/dev/sdb`.  Probably something to do with
+`udev` changing over the years).
 
 
-Anyway, you'll need to mess around a bit to get that working.  Or I can dd one
+Anyway, you'll need to mess around a bit to get that working.  Or I can `dd` one
 for you (I have 4GB disks in my office that I use).  If you make your own, the
 critical part is getting grub to pick the right device (from what I remember),
 and its fairly similar to installing grub on any old hard drive (since it's
 just a bloc device).  Much easier than a hard disk image file.
 
 
 for you (I have 4GB disks in my office that I use).  If you make your own, the
 critical part is getting grub to pick the right device (from what I remember),
 and its fairly similar to installing grub on any old hard drive (since it's
 just a bloc device).  Much easier than a hard disk image file.
 
 
-3.8 Hello World
----------
+### 3.8 Hello World
 So now you can run the kernel.  It's time to edit a program (or make your own).
 In this, I'll go through my workflow for making changes.
 
 So now you can run the kernel.  It's time to edit a program (or make your own).
 In this, I'll go through my workflow for making changes.
 
+```
 $ vi tests/hello.c
 (edit, save)
 
 $ vi tests/hello.c
 (edit, save)
 
@@ -312,60 +336,60 @@ ROS(Core 0)> bb (to run busybox)
 
 / $ hello
 (Should print your message)
 
 / $ hello
 (Should print your message)
+```
 
 
-
-3.9 Other Dev Workflow stuff
----------
-One thing to note is that while we use dynamic linking for libc, parlib
-libraries are statically linked with applications.  In fact, nowadays *all*
-Akaros programs need to be linked againt parlib (used to be that single-core
+### 3.9 Other Dev Workflow Stuff
+One thing to note is that while we use dynamic linking for `libc`, `parlib`
+libraries are statically linked with applications.  In fact, nowadays **all**
+Akaros programs need to be linked againt `parlib` (used to be that single-core
 processes (SCPs) didn't need it).
 
 processes (SCPs) didn't need it).
 
-The makefiles won't notice if you change a file in parlib and then remake a
-binary.  So if you edit user/parlib/uthread.c for example, tests/pthread_test
-won't get rebuilt.  Here's what I do:
+The makefiles won't notice if you change a file in `parlib` and then remake a
+binary.  So if you edit `user/parlib/uthread.c` for example,
+`tests/pthread_test` won't get rebuilt.  Here's what I do:
 
 
+```
 $ vi user/parlib/uthread.c (make awesome change)
 
 $ touch tests/pthread_test.c ; make tests
 $ vi user/parlib/uthread.c (make awesome change)
 
 $ touch tests/pthread_test.c ; make tests
+```
 
 
-This will force the rebuild of pthread_test.  Older, untouched binaries (e.g.
-block_test), won't get rebuilt.  I actually want this in some cases (different
-versions of parlib when I'm running certain tests).  Anyway, just pay attention
-to what you're building.  There's not much output in the console, so you should
-be able to see what's going on all the time.  (unlike when building glibc...).
+This will force the rebuild of `pthread_test`.  Older, untouched binaries (e.g.
+`block_test`), won't get rebuilt.  I actually want this in some cases
+(different versions of `parlib` when I'm running certain tests).  Anyway, just
+pay attention to what you're building.  There's not much output in the console,
+so you should be able to see what's going on all the time.  (unlike when
+building `glibc`...).
 
 Oh, and don't forget to:
 
 
 Oh, and don't forget to:
 
-$ make fill-kfs
+`$ make fill-kfs`
 
 
-to make sure you run the new pthread_test. 
+to make sure you run the new `pthread_test`.
 
 
-Additionally, when switching between 32 and 64 bit x86, make objclean before
+Additionally, when switching between 32 and 64 bit x86, `make objclean` before
 filling KFS.  This is the easiest way to make sure you get the appropriate
 libraries loaded in KFS.
 
 Early on as a dev, there are lots of times where you accidentally don't run the
 right program (or kernel) and won't understand why your change isn't happening.
 filling KFS.  This is the easiest way to make sure you get the appropriate
 libraries loaded in KFS.
 
 Early on as a dev, there are lots of times where you accidentally don't run the
 right program (or kernel) and won't understand why your change isn't happening.
-A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,
-or you didn't fill KFS, or you didn't relink your binaries, or you forgot to
-save all files in vi (and not just the current buffer).  But after doing a
-couple hello worlds, you're set. 
+A few `printk("WTF\n")`'s later, you realize you didn't have the `hdd.img`
+mounted, or you didn't fill KFS, or you didn't relink your binaries, or you
+forgot to save all files in `vi1 (and not just the current buffer).  But after
+doing a couple `hello worlds`, you're set.
 
 Alternatively, you could have a make target to run qemu, which also touches all
 binaries (or otherwise enforces a rebuild), auto-fills KFS, remakes the kernel,
 
 Alternatively, you could have a make target to run qemu, which also touches all
 binaries (or otherwise enforces a rebuild), auto-fills KFS, remakes the kernel,
-and mounts/copies/unmounts your hdd.img.  Kevin's sim repo has stuff like this,
-so check it out if that's what you're into.  (I think it is at
-http://akaros.cs.berkeley.edu/ros-sim.tar.gz).  Personally, I'm not that into
-it, since I like to keep track of what is going on under the hood, esp if I
-want to do something a little differently (like with testing ext2, having
-different versions of parlib with some binaries, or being picky about my
+and mounts/copies/unmounts your `hdd.img`.
+Personally, I like to keep track of what is going on under the hood, esp if I
+want to do something a little differently (like with testing `ext2`, having
+different versions of `parlib` with some binaries, or being picky about my
 mount/umounts).
 
 
 4. RISCV
 ---------------------
 mount/umounts).
 
 
 4. RISCV
 ---------------------
-TODO.
+**TODO**.
 
 For now, you need a 64 bit distro to build the RISCV stuff, so I don't do it
 very often.  I'll eventually sync up with Andrew and we'll get this part sorted
 
 For now, you need a 64 bit distro to build the RISCV stuff, so I don't do it
 very often.  I'll eventually sync up with Andrew and we'll get this part sorted
@@ -373,4 +397,5 @@ out.
 
 
 5. Other Developer's Stuff
 
 
 5. Other Developer's Stuff
----------------------
+--------------------------
+Nothing for now...