Rename Contributing and GETTING_STARTED files
authorKevin Klues <klueska@cs.berkeley.edu>
Thu, 3 Sep 2015 04:01:01 +0000 (21:01 -0700)
committerBarret Rhoden <brho@cs.berkeley.edu>
Tue, 8 Sep 2015 14:24:58 +0000 (10:24 -0400)
Add *.md extensions in preparation fo a subsequent commit where I make
these files markdown compliant.

Documentation/Contributing [deleted file]
Documentation/Contributing.md [new file with mode: 0644]
GETTING_STARTED [deleted file]
GETTING_STARTED.md [new file with mode: 0644]

diff --git a/Documentation/Contributing b/Documentation/Contributing
deleted file mode 100644 (file)
index 0f4d40a..0000000
+++ /dev/null
@@ -1,515 +0,0 @@
-Akaros Contribution Policies
-===========================
-2015-04-27 Barret Rhoden (brho)
-
-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
----------------------------
-By contributing to Akaros, you are agreeing with the Developer Certificate of
-Origin (found in Documentation/ and at http://developercertificate.org/).
-
-All contributions of any sort, including code from other projects, must be
-compatible with the GPLv2.
-
-All new code should be licensed "GPLv2 or later".
-
-You (or your employer) may retain the copyright to your contributions, if
-applicable.  We do not require copyright assignment.
-
-
-Contribution Philosophy
----------------------------
-"Do the right thing."  If you've discovered a problem, figure out how to fix it
-and fix it right.  You do not need to solve every problem, but think a little
-and don't be short-sighted.  (Grep the codebase for TODO.)  For example, if you
-want to disable the legacy USB devices, then go ahead.  You do not need to
-write an entire USB stack, but you should expect that stack to be written in
-the future.
-
-You 'own' your patches and changes, meaning both that they are your
-responsibility and you are free to pursue a solution in your own way.  You must
-be happy with your commits; I must be ok with them.  If you're happy with
-something half-assed, then you're in the wrong line of work.
-
-Expect push-back on various things and plan on reworking your commits.  We
-should be able to reach a good solution through discussion and, on occasion,
-arguments.
-
-Discussion and arguments about patches and technical content is fine.
-Attacking people is not.
-
-
-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
-
-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.
-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
-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
-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
-central repo works fine.
-
-Thanks to git's fast and simple branching, we can work and rework on branches
-that are not master.  Reworking branches includes rewriting commits and git's
-history.  (See below for some git commands).  The general rule is that there is
-no expectation of stability in any branch other than master.  Those branches
-may be rebased without warning by people working on the branch.  You 'own'
-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
-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.
-
-For minor changes and bug fixes, just push them or email a patch.  Use your
-better judgement.
-
-When adding new patches to a branch, you should rebase your commits on top of
-the branch's latest commit, then do a fast-forward merge.
-
-Your commits should be of a reasonable size.  Try to isolate your commits to
-logically consistent, easily verifiable changes.  Each commit should compile,
-but you don't want to change everything in one commit.
-
-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
-commits.
-
-
-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.
-
-- 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.
-
-- 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.
-
-- 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().
-
-- 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 keywords "if", "for", "while", "switch".  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
-  with a brace.
-
-- Beginning-of-line indentation via tabs, not spaces.  Use spaces for
-  additional formatting (such as lining up text when word wrapping).
-
-- Preprocessor macros are usually upper-case.  Try to avoid using macros
-  unless necessary (I prefer static inlines).
-
-- Pointer declarations have the * on the variable.  void *x, not void* x.
-
-- Multi-word names are lower_case_with_underscores.  Keep your names short,
-  especially for local variables.
-
-- 'Permanent' comments in are C /* ... */ comments.  Only use C++ style (//)
-  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
-
-- In a function definition, the function name shoud NOT start a new line.  Old
-  code incorrectly does this, and should be changed over time.
-- Feel free to use gotos, especially in functions that have cleanup before
-  they exit, or in other places that enhance readability.
-
-- 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.
-
-- 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.
-
-- 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).
-
-
-Git Workflow
-------------------------------------
-Git allows us to do a lot of cool things.  One of its primary purposes is to
-provide a means for us to review each others code.  In this section, I'll
-describe how I use git to make changes to Akaros.
-
-### Setup
-
-First off, visualizing the git tree is extremely useful.  I use:
-
-$ gitk --all &
-
-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"
-
-That's pretty crazy, so I have the following in my ~/.gitconfig
-
-[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" 
-        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`.
-
-
-### A Basic Commit
-
-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
-
-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':
-
-$ git checkout -b monitor-change
-
-Edit, compile, and test a change, say in 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
-very useful for committing only what you want from a set of changes in your
-working directory.
-
-$ git status
-
-Take a look at things before you commit; see if you missed any files or added
-anything you don't want.
-
-$ git commit
-
-Write a descriptive message, with a short, one-line summary first.  e.g.
-
-```
-commit 52cc9b19c6edfc183276b1ebf24af9baea4d20d2
-Author: Barret Rhoden <brho@cs.berkeley.edu>
-Date:   Mon Jan 19 18:36:07 2015 -0500
-
-    Fixes kernel argument checking in "m"
-    
-    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.
-
-$ 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.
-
-$ git push origin monitor-change
-
-Email the mailing list or your nearest shepherd, and we'll take a look!
-
-
-### A Bigger Change: Several Commits!
-
-Say you are working on the monitor, and you realize your change is quite large
-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):
-
-$ git reset HEAD
-
-Now, your changes are unstaged.  Confirm with:
-
-$ git status
-
-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
-
-Select only the changes you want, then commit:
-
-$ git commit  # write message
-
-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
-
-
-### 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
-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.
-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
-
-Master is now up to date.  git pull --rebase does this too, though I prefer to
-always fetch first.
-
-$ 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:
-
-$ 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.
-
-$ git push -f origin monitor-change
-
-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
-it down to a few steps (assuming you are on SOMEBRANCH):
-
-$ git fetch
-$ git rebase origin/master
-$ git push -f origin/SOMEBRANCH
-
-
-### Oh No, I Committed and Pushed Something I Want to Change
-
-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)
-
-* 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!
-* 08e42d6        VMM: Call EPT ops for every KPT op
-* 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.
-
-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
-leaving the bugs and printks in old code you only increase the load on your
-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.
-
-First up, make sure you are on vmmcp and do a rebase -i.
-
-$ 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:
-
-$ git rebase -i --onto master master vmmcp
-
-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,
-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.
-
-$ 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
-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.
-
-$ 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:
-
-* 13a95cc        (HEAD, vmmcp) WIP-fixes-vmm-bug
-* 876d5b0        (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!
-* 08e42d6        VMM: Call EPT ops for every KPT op
-* 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!
-
-$ git rebase -i master
-
-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
-easier than the rebase with amend.  I use it when a change applies to both the
-current tip as well as the faulty commit.
-
-You can even use git rebase to logically reorder commits so that together, the
-'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
-branch to agree with yours:
-
-$ 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.
-
-Just remember: gitk, git rebase, and git commit --amend are your friends.
-
-
-### 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!
-
-If you don't have any changes from the original origin/vmmcp, then you can
-simply:
-
-$ 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,
-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
-
-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:
-
-$ 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
-commits from your old vmmcp branch to the new one:
-
-$ 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
-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
-separate branches.
-
-Note that you can probably just do a:
-
-$ git rebase origin/vmmcp
-
-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.
-
-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
-group or individual work.
-
-Just remember: gitk and git rebase are your friends.
-
-
-### 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!
-
-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.
-
-To delete a remote branch, say after it is merged into origin/master:
-
-$ git push -f origin :BRANCH-NAME
-
-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.
-
-Again, these techinques work well with small groups, but not for big branches
-like origin/master.
diff --git a/Documentation/Contributing.md b/Documentation/Contributing.md
new file mode 100644 (file)
index 0000000..0f4d40a
--- /dev/null
@@ -0,0 +1,515 @@
+Akaros Contribution Policies
+===========================
+2015-04-27 Barret Rhoden (brho)
+
+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
+---------------------------
+By contributing to Akaros, you are agreeing with the Developer Certificate of
+Origin (found in Documentation/ and at http://developercertificate.org/).
+
+All contributions of any sort, including code from other projects, must be
+compatible with the GPLv2.
+
+All new code should be licensed "GPLv2 or later".
+
+You (or your employer) may retain the copyright to your contributions, if
+applicable.  We do not require copyright assignment.
+
+
+Contribution Philosophy
+---------------------------
+"Do the right thing."  If you've discovered a problem, figure out how to fix it
+and fix it right.  You do not need to solve every problem, but think a little
+and don't be short-sighted.  (Grep the codebase for TODO.)  For example, if you
+want to disable the legacy USB devices, then go ahead.  You do not need to
+write an entire USB stack, but you should expect that stack to be written in
+the future.
+
+You 'own' your patches and changes, meaning both that they are your
+responsibility and you are free to pursue a solution in your own way.  You must
+be happy with your commits; I must be ok with them.  If you're happy with
+something half-assed, then you're in the wrong line of work.
+
+Expect push-back on various things and plan on reworking your commits.  We
+should be able to reach a good solution through discussion and, on occasion,
+arguments.
+
+Discussion and arguments about patches and technical content is fine.
+Attacking people is not.
+
+
+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
+
+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.
+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
+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
+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
+central repo works fine.
+
+Thanks to git's fast and simple branching, we can work and rework on branches
+that are not master.  Reworking branches includes rewriting commits and git's
+history.  (See below for some git commands).  The general rule is that there is
+no expectation of stability in any branch other than master.  Those branches
+may be rebased without warning by people working on the branch.  You 'own'
+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
+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.
+
+For minor changes and bug fixes, just push them or email a patch.  Use your
+better judgement.
+
+When adding new patches to a branch, you should rebase your commits on top of
+the branch's latest commit, then do a fast-forward merge.
+
+Your commits should be of a reasonable size.  Try to isolate your commits to
+logically consistent, easily verifiable changes.  Each commit should compile,
+but you don't want to change everything in one commit.
+
+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
+commits.
+
+
+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.
+
+- 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.
+
+- 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.
+
+- 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().
+
+- 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 keywords "if", "for", "while", "switch".  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
+  with a brace.
+
+- Beginning-of-line indentation via tabs, not spaces.  Use spaces for
+  additional formatting (such as lining up text when word wrapping).
+
+- Preprocessor macros are usually upper-case.  Try to avoid using macros
+  unless necessary (I prefer static inlines).
+
+- Pointer declarations have the * on the variable.  void *x, not void* x.
+
+- Multi-word names are lower_case_with_underscores.  Keep your names short,
+  especially for local variables.
+
+- 'Permanent' comments in are C /* ... */ comments.  Only use C++ style (//)
+  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
+
+- In a function definition, the function name shoud NOT start a new line.  Old
+  code incorrectly does this, and should be changed over time.
+- Feel free to use gotos, especially in functions that have cleanup before
+  they exit, or in other places that enhance readability.
+
+- 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.
+
+- 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.
+
+- 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).
+
+
+Git Workflow
+------------------------------------
+Git allows us to do a lot of cool things.  One of its primary purposes is to
+provide a means for us to review each others code.  In this section, I'll
+describe how I use git to make changes to Akaros.
+
+### Setup
+
+First off, visualizing the git tree is extremely useful.  I use:
+
+$ gitk --all &
+
+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"
+
+That's pretty crazy, so I have the following in my ~/.gitconfig
+
+[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" 
+        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`.
+
+
+### A Basic Commit
+
+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
+
+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':
+
+$ git checkout -b monitor-change
+
+Edit, compile, and test a change, say in 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
+very useful for committing only what you want from a set of changes in your
+working directory.
+
+$ git status
+
+Take a look at things before you commit; see if you missed any files or added
+anything you don't want.
+
+$ git commit
+
+Write a descriptive message, with a short, one-line summary first.  e.g.
+
+```
+commit 52cc9b19c6edfc183276b1ebf24af9baea4d20d2
+Author: Barret Rhoden <brho@cs.berkeley.edu>
+Date:   Mon Jan 19 18:36:07 2015 -0500
+
+    Fixes kernel argument checking in "m"
+    
+    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.
+
+$ 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.
+
+$ git push origin monitor-change
+
+Email the mailing list or your nearest shepherd, and we'll take a look!
+
+
+### A Bigger Change: Several Commits!
+
+Say you are working on the monitor, and you realize your change is quite large
+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):
+
+$ git reset HEAD
+
+Now, your changes are unstaged.  Confirm with:
+
+$ git status
+
+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
+
+Select only the changes you want, then commit:
+
+$ git commit  # write message
+
+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
+
+
+### 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
+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.
+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
+
+Master is now up to date.  git pull --rebase does this too, though I prefer to
+always fetch first.
+
+$ 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:
+
+$ 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.
+
+$ git push -f origin monitor-change
+
+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
+it down to a few steps (assuming you are on SOMEBRANCH):
+
+$ git fetch
+$ git rebase origin/master
+$ git push -f origin/SOMEBRANCH
+
+
+### Oh No, I Committed and Pushed Something I Want to Change
+
+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)
+
+* 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!
+* 08e42d6        VMM: Call EPT ops for every KPT op
+* 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.
+
+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
+leaving the bugs and printks in old code you only increase the load on your
+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.
+
+First up, make sure you are on vmmcp and do a rebase -i.
+
+$ 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:
+
+$ git rebase -i --onto master master vmmcp
+
+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,
+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.
+
+$ 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
+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.
+
+$ 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:
+
+* 13a95cc        (HEAD, vmmcp) WIP-fixes-vmm-bug
+* 876d5b0        (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!
+* 08e42d6        VMM: Call EPT ops for every KPT op
+* 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!
+
+$ git rebase -i master
+
+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
+easier than the rebase with amend.  I use it when a change applies to both the
+current tip as well as the faulty commit.
+
+You can even use git rebase to logically reorder commits so that together, the
+'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
+branch to agree with yours:
+
+$ 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.
+
+Just remember: gitk, git rebase, and git commit --amend are your friends.
+
+
+### 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!
+
+If you don't have any changes from the original origin/vmmcp, then you can
+simply:
+
+$ 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,
+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
+
+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:
+
+$ 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
+commits from your old vmmcp branch to the new one:
+
+$ 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
+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
+separate branches.
+
+Note that you can probably just do a:
+
+$ git rebase origin/vmmcp
+
+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.
+
+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
+group or individual work.
+
+Just remember: gitk and git rebase are your friends.
+
+
+### 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!
+
+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.
+
+To delete a remote branch, say after it is merged into origin/master:
+
+$ git push -f origin :BRANCH-NAME
+
+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.
+
+Again, these techinques work well with small groups, but not for big branches
+like origin/master.
diff --git a/GETTING_STARTED b/GETTING_STARTED
deleted file mode 100644 (file)
index 0bb9f9b..0000000
+++ /dev/null
@@ -1,376 +0,0 @@
-GETTING_STARTED
-Barret Rhoden
-
-Last thorough update: 2013-02-07
-
-
-1. Overview
----------------------
-In this document, I outline what steps I go through to set up my development
-environment.  Some devs use other setups, and they can put sections farther
-down in this document describing their steps.
-
-Due to the nature of different workflows and different Linux distros, you'll
-need to do some configuration of your environment.  Things won't magically work
-out of the box.
-
-
-2. Need help?
----------------------
-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.
-
-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
----------------------
-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:
-
-$ make ARCH=x86 defconfig
-
-Alternatively, you can run menuconfig to customize what settings you want:
-
-$ 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.
-
-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
-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.
-
-3.1 Cross compiler (and glibc)
-----------
-The second step is to build the cross compiler, which lives in
-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.
-
-$ 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 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
-
-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):
-
-$ 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
-x86_64-ros-gcc from your shell.
-
-Now, you have a cross compiler ready, and you can start to build Akaros.
-
-3.2 Kernel
-----------
-cd back into the repo root.
-
-Like the cross compiler, the kernel has its own Makelocal.
-
-$ cp Makelocal.template Makelocal
-
-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.
-
-Now you're ready to build the kernel:
-
-$ make
-
-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'
-etc.)
-
-3.3 Userspace
----------
-To build userspace and test programs:
-
-$ make tests
-
-You now have programs and libraries, and need to put them in KFS.  To do this,
-we provide a 'fill-kfs' make target. 
-
-$ make fill-kfs
-
-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
-(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
-should see something like
-       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
----------
-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
-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):
-
-$ cd tools/apps/busybox
-$ make [x86_64|riscv]
-$ cd -
-
-And you should be set.  Check kfs to make sure everything installed.  You
-should get sane results from:
-
-$ 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
-.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.
-
-3.5 Building and Loading a Virtual Machine Image
----------
-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. 
-
-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
-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
-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
-accordingly. Feel free to comment out the networking stuff.  That's for using
-networking in qemu.
-
-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
-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
-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:
-
-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).
-
-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
-
-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".
-
-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
-'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
-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.
-
-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:
-
-       -net tap,ifname=tap0,script=no
-
-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).
-
-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
-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:
-
-$ stty intr ^]
-
-To change it back:
-
-$ stty intr ^c
-
-3.7 Running on Hardware
----------
-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
-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).
-
-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.
-
-
-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.
-
-$ vi tests/hello.c
-(edit, save)
-
-$ make tests
-(new version in obj/tests/hello)
-
-$ make fill-kfs
-(updates kfs)
-
-$ make
-(rebuilds kernel with the new KFS)
-
-$ qemu...
-
-(following commands are in Akaros)
-Shift-G (to get to the kernel monitor)
-
-ROS(Core 0)> bb (to run busybox)
-
-/ $ 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
-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:
-
-$ 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...).
-
-Oh, and don't forget to:
-
-$ make fill-kfs
-
-to make sure you run the new pthread_test. 
-
-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.
-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. 
-
-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
-mount/umounts).
-
-
-4. RISCV
----------------------
-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
-out.
-
-
-5. Other Developer's Stuff
----------------------
diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
new file mode 100644 (file)
index 0000000..0bb9f9b
--- /dev/null
@@ -0,0 +1,376 @@
+GETTING_STARTED
+Barret Rhoden
+
+Last thorough update: 2013-02-07
+
+
+1. Overview
+---------------------
+In this document, I outline what steps I go through to set up my development
+environment.  Some devs use other setups, and they can put sections farther
+down in this document describing their steps.
+
+Due to the nature of different workflows and different Linux distros, you'll
+need to do some configuration of your environment.  Things won't magically work
+out of the box.
+
+
+2. Need help?
+---------------------
+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.
+
+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
+---------------------
+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:
+
+$ make ARCH=x86 defconfig
+
+Alternatively, you can run menuconfig to customize what settings you want:
+
+$ 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.
+
+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
+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.
+
+3.1 Cross compiler (and glibc)
+----------
+The second step is to build the cross compiler, which lives in
+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.
+
+$ 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 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
+
+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):
+
+$ 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
+x86_64-ros-gcc from your shell.
+
+Now, you have a cross compiler ready, and you can start to build Akaros.
+
+3.2 Kernel
+----------
+cd back into the repo root.
+
+Like the cross compiler, the kernel has its own Makelocal.
+
+$ cp Makelocal.template Makelocal
+
+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.
+
+Now you're ready to build the kernel:
+
+$ make
+
+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'
+etc.)
+
+3.3 Userspace
+---------
+To build userspace and test programs:
+
+$ make tests
+
+You now have programs and libraries, and need to put them in KFS.  To do this,
+we provide a 'fill-kfs' make target. 
+
+$ make fill-kfs
+
+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
+(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
+should see something like
+       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
+---------
+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
+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):
+
+$ cd tools/apps/busybox
+$ make [x86_64|riscv]
+$ cd -
+
+And you should be set.  Check kfs to make sure everything installed.  You
+should get sane results from:
+
+$ 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
+.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.
+
+3.5 Building and Loading a Virtual Machine Image
+---------
+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. 
+
+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
+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
+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
+accordingly. Feel free to comment out the networking stuff.  That's for using
+networking in qemu.
+
+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
+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
+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:
+
+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).
+
+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
+
+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".
+
+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
+'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
+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.
+
+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:
+
+       -net tap,ifname=tap0,script=no
+
+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).
+
+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
+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:
+
+$ stty intr ^]
+
+To change it back:
+
+$ stty intr ^c
+
+3.7 Running on Hardware
+---------
+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
+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).
+
+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.
+
+
+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.
+
+$ vi tests/hello.c
+(edit, save)
+
+$ make tests
+(new version in obj/tests/hello)
+
+$ make fill-kfs
+(updates kfs)
+
+$ make
+(rebuilds kernel with the new KFS)
+
+$ qemu...
+
+(following commands are in Akaros)
+Shift-G (to get to the kernel monitor)
+
+ROS(Core 0)> bb (to run busybox)
+
+/ $ 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
+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:
+
+$ 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...).
+
+Oh, and don't forget to:
+
+$ make fill-kfs
+
+to make sure you run the new pthread_test. 
+
+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.
+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. 
+
+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
+mount/umounts).
+
+
+4. RISCV
+---------------------
+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
+out.
+
+
+5. Other Developer's Stuff
+---------------------