Skip to content

Commit

Permalink
first commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@nwolovick
nwolovick committed Mar 14, 2011
0 parents commit db32473
Show file tree
Hide file tree
Showing 918 changed files with 115,909 additions and 0 deletions.
1 change: 1 addition & 0 deletions README.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
See doc/index.html or doc/hacking.pdf for information about GeekOS
119 changes: 119 additions & 0 deletions doc/FAQ.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
<html>
<head>
<title>GeekOS FAQ</title>
</head>

<body>
<h1>GeekOS FAQ</h1>

<p> Maintained by David Hovemeyer &lt;<a href="mailto:[email protected]">[email protected]</a>&gt;

<p> This document attempts to answer frequently asked questions
about <a href="http://geekos.sourceforge.net/">GeekOS</a>.

<p> Last modified on $Date: 2004/02/07 19:31:45 $.

<h2>Contents</h2>

<ol>
<li> <a href="#q1">What is GeekOS?</a>
<li> <a href="#q2">What do I need to run GeekOS?</a>
<li> <a href="#q3">Why did you write another instructional operating system?</a>
<li> <a href="#q4">Why does GeekOS suck so much?</a>
<li> <a href="#q5">Will GeekOS run program <i>X</i>?</a>
</ol>

<h2><a name="q1">1. What is GeekOS?</a></h2>

<p> GeekOS is an instructional operating system.&nbsp; It is intended to
be used in undergraduate operation system courses, or for self-study.&nbsp;
It implements a very minimal set of features on top of bare x86 PC
hardware.&nbsp; In a series of projects included in the GeekOS distribution,
students add important operation system features such as processes,
virtual memory, a filesystem, and interprocess communication.&nbsp; Once
all of the projects have been completed, GeekOS resembles a very simple
version of Unix.

<h2><a name="q2">2. What do I need to run GeekOS?</a></h2>

<p> GeekOS runs mainly on the <a href="http://bochs.sourceforge.net/">Bochs</a>
PC emulator.&nbsp; Running GeekOS on an emulator has several important
advantages over running it on a real computer:

<ol>
<li> The emulator boots very quickly (around 1 second), allowing
a much quicker compile/edit/debug cycle
<li> The logfile produced by bochs (bochs.out) contains very useful
information for diagnosing crashes
<li> Recent versions of Bochs (2.0 and later) can be build with
stubs for the gdb debugger, allowing easy debugging of the kernel
</ol>

<p> Please note that although GeekOS is
<a href="http://geekos.sourceforge.net/hardware.html">tested on real hardware</a>
from time to time, you will probably need to do some hacking to get
it working on <em>your</em> PC.&nbsp; Submissions of bug fixes
that make GeekOS work on more hardware are
<a href="mailto:[email protected]">gladly accepted</a>.

<p> To compile GeekOS from source, you will need the following software:

<ul>
<li> <a href="http://gcc.gnu.org/">gcc</a> targeting i386/ELF; the default
compiler on Linux and FreeBSD systems will work, and cross compilers
targeting i386-elf should also work
<li> A host platform C compiler supporting ANSI C
<li> <a href="http://nasm.sourceforge.net/">The Netwide Assembler (NASM)</a>
<li> <a href="http://www.gnu.org/software/make/">GNU Make</a>
<li> <a href="http://www.perl.com/">Perl</a>, version 5.0 or later
<li> AWK, egrep
</ul>

<h2><a name="q3">3. Why did you write another instructional operating system?</a></h2>

<p> Good question.&nbsp; There are a lot of other good instructional
operating systems out there: <a href="http://www.cs.vu.nl/~ast/minix.html">Minix</a>,
<a href="http://www.tik.ee.ethz.ch/~topsy/">Topsy</a>,
<a href="http://www.eecs.harvard.edu/~syrah/os161/">OS/161</a>,
and <a href="http://www.cs.washington.edu/homes/tom/nachos/">Nachos</a>,
to name a few.

<p> GeekOS pursues slightly different design goals than any of the above.&nbsp;
I wanted to combine <em>simplicity</em> with <em>realism</em>.&nbsp; Simplicity
means that GeekOS tries to use the simplest algorithm or data structure
that will work; for example, you will find lots of linked lists and arrays in GeekOS,
but no hash tables or balanced trees.&nbsp; Realism means that GeekOS
resembles a real operating system.&nbsp; When the projects are completed,
GeekOS has processes, paged virtual memory, and a hierarchical filesystem.&nbsp;
Adventurous hackers can boot GeekOS on a real PC.

<h2><a name="q4">4. Why does GeekOS suck so much?</a></h2>

<p> Many of the implementation decisions made in GeekOS would be unacceptable
in a real operating system.&nbsp; For example:

<ul>
<li> No support for PCI devices
<li> IDE disk driver uses CHS addressing and programmed I/O
<li> IDE requests proceed synchronously with busy waiting
<li> Page stealing does a complete walk of every page of memory
with interrupts disabled
<li> Executable loading copies entire program image into
memory twice before process starts
<li> And so on...
</ul>

<p> Keep in mind that the main goal of GeekOS is <em>simplicity</em>.&nbsp;
If you want to fix some of the more egregious limitations in GeekOS,
<em>in a way that maintains or improves the simplicity of the system</em>,
please <a href="mailto:[email protected]">submit a patch</a>.

<h2><a name="q5">5. Will GeekOS run program <i>X</i>?</a></h2>

<p> GeekOS does not conform to any existing API standard, and has only a
very minimal C library.&nbsp; Therefore, any program written for another
operating system will require considerable porting effort.

</body>

</html>
46 changes: 46 additions & 0 deletions doc/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# The manual is written in DocBook
# (see http://www.docbook.org/tdg/en/html/docbook.html)
# It uses xsltproc to convert the SGML using two style sheets:
# conversion to HTML
# conversion to latex for constructing PDF
# These are available, respectively, at
# http://docbook.sourceforge.net/projects/xsl/
# http://db2latex.sourceforge.net/
# You can create a Makefile.local to override the locations of
# these stylesheets defined in the variables below (the _BASE
# variables don't matter, only the _XSL_* ones).

DOCBOOK_BASE := /export/home/daveho/linux/docbook/docbook-xsl-1.64.1
DOCBOOK_XSL_HTML := $(DOCBOOK_BASE)/html/chunk.xsl

DB2LATEX_HOME := /export/home/daveho/linux/docbook/db2latex-xsl-0.8pre1
DB2LATEX_XSL := $(DB2LATEX_HOME)/xsl/docbook.xsl

-include Makefile.local

CLASSPATH := $(SAXON_HOME)/saxon.jar:$$CLASSPATH

all : index.html hacking.pdf

index.html : hacking.xml hacking-html.xsl
xsltproc -o $@ hacking-html.xsl hacking.xml

hacking-html.xsl : hacking-html.xsl.in
perl -n -e 's,\@HTML_XSL_STYLESHEET\@,$(DOCBOOK_XSL_HTML),g;print' hacking-html.xsl.in > $@

hacking.pdf : hacking.tex
pdflatex hacking.tex
pdflatex hacking.tex

hacking.tex : hacking.xml hacking-db2latex.xsl
xsltproc -o $@ hacking-db2latex.xsl hacking.xml

hacking-db2latex.xsl : hacking-db2latex.xsl.in
perl -n -e 's,\@DB2LATEX_XSL_STYLESHEET\@,$(DB2LATEX_XSL),g;print' hacking-db2latex.xsl.in > $@

clean :
rm -f hacking.{aux,glo,idx,log,out,pdf,tex} *.xsl
rm -f apiref.html hacking101.html introproject.html projectoverview.html vmproject.html \
index.html ipcproject.html schedulingproject.html \
fsproject.html intro.html overview.html usermodeproject.html elfparsingproject.html

57 changes: 57 additions & 0 deletions doc/apiref.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 12. GeekOS API Reference</title><meta name="generator" content="DocBook XSL Stylesheets V1.64.1"><link rel="home" href="index.html" title="Hacking GeekOS"><link rel="up" href="index.html" title="Hacking GeekOS"><link rel="previous" href="ipcproject.html" title="Chapter 11. Project 6: ACLs and Inter-process Communication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. GeekOS API Reference</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ipcproject.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="apiref"></a>Chapter 12. GeekOS API Reference</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="apiref.html#threadfns">1. Thread functions</a></span></dt><dd><dl><dt><span class="sect2"><a href="apiref.html#Start_Kernel_Thread">1.1. Start_Kernel_Thread()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Exit">1.2. Exit()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Join">1.3. Join()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Wait">1.4. Wait()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Wake_Up">1.5. Wake_Up()</a></span></dt><dt><span class="sect2"><a href="apiref.html#Wake_Up_One">1.6. Wake_Up_One()</a></span></dt></dl></dd></dl></div><p>
This chapter documents commonly used functions in the GeekOS kernel.
Note that this chapter is likely to be incomplete. You can always refer
directly to the GeekOS source code if you need more information on
a particular function.
</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="threadfns"></a>1. Thread functions</h2></div></div><div></div></div>
This section describes functions used to manage threads.

<div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Start_Kernel_Thread"></a>1.1. Start_Kernel_Thread()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">struct Kernel_Thread *<b class="fsfunc">Start_Kernel_Thread</b>(</code></td><td><var class="pdparam">startFunc</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">arg</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">priority</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">detached</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td>Thread_Start_Func  </td><td><var class="pdparam">startFunc</var>;</td></tr><tr><td>ulong_t  </td><td><var class="pdparam">arg</var>;</td></tr><tr><td>int  </td><td><var class="pdparam">priority</var>;</td></tr><tr><td>bool  </td><td><var class="pdparam">detached</var>;</td></tr></table></div><p>
</p><p>
Starts a new kernel thread. <i class="parameter"><tt>startFunc</tt></i> is a function
which will be called as the body of the new thread.
The start function will execute with interrupts enabled.
It should return void and take an unsigned long parameter.
<i class="parameter"><tt>arg</tt></i> is an arbitrary value passed to the thread's start function.
It can be used to convey extra information, or a pointer to a data
structure to be used by the thread. <i class="parameter"><tt>priority</tt></i>
is the priority of the new thread. <tt class="literal">PRIORITY_NORMAL</tt>
should be used for ordinary kernel threads. <tt class="literal">PRIORITY_USER</tt>
should be used for user processes. <i class="parameter"><tt>detached</tt></i>
indicates whether the parent thread will wait for the child thread
to exit. If true, then the parent must call the <tt class="literal">Join()</tt>
function to wait for the child. If false, then the parent must not
call <tt class="literal">Join()</tt>.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Exit"></a>1.2. Exit()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><p><code class="funcdef">void <b class="fsfunc">Exit</b>(</code><var class="pdparam">exitCode</var><code>)</code>;<br>int <code>exitCode</code>;</p></div><p>
</p><p>
Causes the current thread to exit with the exit code given by <i class="parameter"><tt>exitCode</tt></i>.
If the current thread has a parent and is not a detached thread, the
exit code will be returned by the <tt class="literal">Join()</tt> call made by
the parent. Interrupts must be enabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Join"></a>1.3. Join()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><p><code class="funcdef">int <b class="fsfunc">Join</b>(</code><var class="pdparam">kthread</var><code>)</code>;<br>struct Kernel_Thread *<code>kthread</code>;</p></div><p>
</p><p>
Wait for a child thread <i class="parameter"><tt>kthread</tt></i> to exit. The
child must have been created with its <i class="parameter"><tt>detached</tt></i>
parameter set to true. Once the child has exited, returns the exit code
of the child thread. Interrupts must be enabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Wait"></a>1.4. Wait()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><p><code class="funcdef">void <b class="fsfunc">Wait</b>(</code><var class="pdparam">waitQueue</var><code>)</code>;<br>struct Thread_Queue *<code>waitQueue</code>;</p></div><p>
</p><p>
Puts the current thread on given wait queue. The thread will resume executing
at a later point when another thread or interrupt handler calls
<tt class="literal">Wake_Up()</tt> or <tt class="literal">Wake_Up_One()</tt> on the
same wait queue. Interrupts must be disabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Wake_Up"></a>1.5. Wake_Up()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">void <b class="fsfunc">Wake_Up</b>(</code></td><td><var class="pdparam">waitQueue</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td>struct Thread_Queue * </td><td><var class="pdparam">waitQueue</var>;</td></tr></table></div><p>
</p><p>
Wakes up all threads on given wait queue by moving them to the
run queue. Interrupts must be disabled.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Wake_Up_One"></a>1.6. Wake_Up_One()</h3></div></div><div></div></div><p>
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">void <b class="fsfunc">Wake_Up_One</b>(</code></td><td><var class="pdparam">waitQueue</var><code>)</code>;</td><td> </td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td>struct Thread_Queue * </td><td><var class="pdparam">waitQueue</var>;</td></tr></table></div><p>
</p><p>
Wakes up the highest priority thread in given wait queue by
moving it to the run queue. Interrupts must be disabled.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ipcproject.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Chapter 11. Project 6: ACLs and Inter-process Communication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
Loading

0 comments on commit db32473

Please sign in to comment.