Clean Up Documentation

Author: primis

CHANGELOG.md

@@ -4,6 +4,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Documentation for existing Code
+
+### Removed
+- Remove `make doc` functionality.
+
+### Changed
+- Rewrite of docs/ subdirectory
+
 ## [0.0.5] - 2022-09-10
 ### Added
 - Raspberry Pi 4 Support (In Progress)
@@ -87,3 +98,11 @@ This is documenting the state of the kernel before CHANGELOG was implemented
     - Implemented `printf()`, `putchar()`, and `puts()` from stdio
 - Abstract Data Types
     - Ring Buffer
+
+[Unreleased]: https://github.com/primis/apollo/compare/v0.0.5...HEAD
+[0.0.5]: https://github.com/primis/apollo/compare/0.0.4...v0.5.0
+[0.0.4]: https://github.com/primis/apollo/compare/0.0.3...0.0.4
+[0.0.3]: https://github.com/primis/apollo/compare/0.0.2...0.0.3
+[0.0.2]: https://github.com/primis/apollo/compare/0.0.1...0.0.2
+[0.0.1]: https://github.com/primis/apollo/compare/0.0.0...0.0.1
+[0.0.0]: https://github.com/primis/apollo/releases/tag/0.0.0

Makefile

@@ -6,13 +6,6 @@
 # Git revision number
 GIT_REV		!= git rev-parse --short HEAD 2>/dev/null |tr '[:lower:]' '[:upper:]'
 
-# Documentation
-MDSOURCES	!= find docs -type f -name '*.md'
-MARKDOWN 	:= markdown
-HTMLDIR		:= html
-HTMLDOCS	:= $(patsubst docs/%.md,$(HTMLDIR)/%.html,$(MDSOURCES))
-HTMLDIRS 	:= $(shell cd docs && find -type d | tr '\n' ' ')
-
 INCLUDEDIR	!= find src -type d -name "include" -printf "-I%p "
 
 include .config
@@ -40,7 +33,7 @@ endif
 OBJECTS		:= $(patsubst %.o,$(BUILD)/%.o,$(OBJECTS))
 SRCDIR		!= find src/ -type d | tr '\n' ' '
 
-all: $(BUILD)/apollo.iso doc
+all: $(BUILD)/apollo.iso
 
 # C files are compiled universally the same, assembler targets are defined in
 # The target specific makefiles
@@ -62,17 +55,6 @@ clean:
 	@find . -type d -name "build*" -exec rm -rf {} +
 	@rm -rf $(HTMLDIR)
 
-doc_setup:
-	@mkdir -p $(HTMLDIR)
-	@cd $(HTMLDIR) && mkdir -p $(HTMLDIRS)
-
-doc: $(HTMLDOCS)
-
-$(HTMLDIR)/%.html: docs/%.md
-	@mkdir -p $(@D)
-	@printf "\033[1mHTML\033[0m $<\n"
-	$(MARKDOWN) $< > $@
-
 menuconfig:
 	@kconfig-mconf Kconfig
 

docs/CONTRIBUTING.md

@@ -19,18 +19,18 @@ interactions with the project.
 ## Pull Request Process
 
 1.  Update CHANGELOG.md with details of the changes implemented. This includes
-    any tests created as well
+    any tests created as well.
 2.  Don't break any old tests or functionality when updating unless the test has
-    been determined to be wrong (requires discussion beforehand)
+    been determined to be wrong. (requires discussion beforehand)
 3.  Add tests for any new functionality in the appropriate `test` folder
     in the source tree. Tests should be comprehensive to make sure the kernel
     does not lose stability.
 4.  Any commits *must* be gpg signed with a key associated with your account.
     This keeps a chain of custody to allow proper back tracking of commits.
-5.  Pull requests should be flattened into a single commit.
+5.  Pull requests should be flattened into a single commit where relevant.
 6.  Recognize that all code will be considered under the license found in 
     LICENSE.md, any code which cannot be legally distributed under this license
-    will not be considered for pull requests
+    will not be considered for pull requests.
 
 ## Coding style
 All code should follow the standard coding style enforced herein.
@@ -41,7 +41,8 @@ All code should follow the standard coding style enforced herein.
 2.  K&R style bracing should be used consistently.
 3.  Comments should be used, but not overused for obvious content. Comments
     should use the c++ `//` style except for file descriptors at the beginning
-    of each file. Comments should not include any inappropriate or offensive
+    of each file, and function description blocks, following the doxygen 
+    standard. Comments should not include any inappropriate or offensive
     language.
 4.  Avoid monolithic functions. Indented code should never drop below 4 indents.
     Consider exposing that to a separate function or rewriting the logic at that
@@ -72,7 +73,7 @@ include:
 Examples of unacceptable behavior by participants include:
 
 * The use of sexualized language or imagery and unwelcome sexual attention or
-advances
+  advances
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or electronic
@@ -104,20 +105,20 @@ further defined and clarified by project maintainers.
 ### Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at [email protected]. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+reported by contacting the project team at [email protected]. All complaints 
+will be reviewed and investigated and will result in a response that is deemed 
+necessary and appropriate to the circumstances. The project team is obligated to
+maintain confidentiality with regard to the reporter of an incident. Further 
+details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other
 members of the project's leadership.
 
 ### Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [http://contributor-covenant.org/version/1/4][version]
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], 
+version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
 
 [homepage]: http://contributor-covenant.org
 [version]: http://contributor-covenant.org/version/1/4/

docs/arch.md

@@ -0,0 +1,31 @@
+Architectures
+=============
+
+Tier 1 Support
+--------------
+Tier 1 support architectures are platforms which active development is
+considered vital to the movement of progress of the kernel.
+
+* [x86-pc](arch/x86/pc)
+* [Raspberry Pi 4](arch/aarch64/rpi4)
+
+Tier 2 Support
+--------------
+Tier 2 support architectures are platforms which develop on their own time.
+These are not needed to be feature complete for a release of the kernel.
+
+* There are no Tier 2 Support architectures currently
+
+Tier 3 Support
+--------------
+Tier 3 support architectures are platforms which are "on life support" so to
+speak. These are architectures which aren't currently compiling and have had no
+progress in that direction in over a year.
+
+* There are no Tier 3 Support architectures currently
+
+Create a New Architecture
+-------------------------
+* If there is a platform in which you want added to the apollo kernel support list
+    please follow the [Create Your Own](arch/new-arch/Making-A-New-Arch) 
+    Architecture guide.

docs/arch/aarch64/rpi4.jpg

@@ -0,0 +1,21 @@
+Raspberry Pi 4
+==============
+
+![Raspberry Pi 4](rpi4.jpg)
+
+Introduction
+------------
+
+The Rasberry Pi 4 board is based on the BCM2711 System on a chip. It features
+a 1.5 GHz 64-bit quad core ARM Cortex-A72 processor, and 1-8 gigabytes of ram
+depending on the model. 
+There are currently two Models being produced, The model B (shown above), and
+the mode 400, which is built into a keyboard case.
+
+
+Availible Drivers
+-----------------
+
+* [16550 Compatible UART](../../../drivers/console/16550_uart/) 
+    - This is available via the GPIO header's UART0 on pins 8 and 10
+

docs/arch/aarch64/rpi4.md

@@ -3,37 +3,38 @@ Creating a Console Driver
 
 Introduction
 -------------
-
 One of the essential parts of the boot process is a console terminal driver.
 This driver allows the kernel to output early debug information before the
 system comes online. The console driver is part of the kernel. The kernel
-defines console_write(), which allows a string to be outputted to console.
-
-Inside the architecture folder itself, you must implement a function called
-void console_put(char). The Console driver will call this function to output
-a single charecter to the console device.
+defines access to logging functions but it is up to the architecture to create
+a console driver and initialize it.
 
 Initialization
 ---------------
-
-The kernel will call archInit() before it attempts to use the Console driver.
-See [Making a New Architecture](Making-A-New-Arch.html) for more information 
-about archInit().
+Calling `register_console()` is how you register a new console with the kernel.
+The only functions required to implement are `init()` and `write()`.
 
 Control Charecters
 -------------------
+The kernel internally accepts ascii data for logging, but it also uses several
+ASCII control codes which should be implemented by your console:
 
-console_put(char) accepts an ASCII charecter as input, but it should also 
-support the following basic ascii control characters:
+\t  Tab.    This should move the cursor to the next tab indent.
+            We recommend using 8 space tabs, though this is left up to 
+            the implementation.
 
-\t or 0x09 : Tab. This should move the cursor to the next tab indent.
-             We recommend using 8 space tabs, though this is left up to 
-             the implementation.
+\n  Newline. This should drop to a new line, and also perform a 
+            carriage return back to Column 0.
 
-\n or 0x0A : Newline. This should drop to a new line, and also perform a 
-             carriage return back to Column 0.
+\f  Form feed. This should either clear the screen, or on a non-screen
+            console, create some sort of page break like a horizontal rule
+            does in html.
 
-\f or 0x0C : Form feed: This should either clear the screen, or on a non-screen
-             console, create some sort of page break like a horizontal rule
-             does in html.
+\b  Backspace. This should move the cursor backwards one character but not null
+               out the character glyph at that location.
 
+Color Codes
+-----------
+Parts of the kernel use ANSI escape codes for colors. If your console supports
+color codes, try to support them. If your console does not, these codes may need
+to be stripped out of the data stream.

docs/arch/index.md

@@ -4,7 +4,7 @@ Apollo Architectures : Creating a New one
 Introduction
 ------------
 
-So You've decided to create a new archetecture support for the Apollo kernel?
+So You've decided to create a new architecture support for the Apollo kernel?
 There is a few tasks to complete on your platform before Apollo will happily
 run on top of it.
 
@@ -16,54 +16,37 @@ items availible.
 
 * Your platform has to be a 32 or 64 bit system. Apollo won't support 16 bit
     without massive core arch change.
-* A Console device of some kind for boot messages, be it serial, a screen
+* A console device of some kind for boot messages, be it serial, a screen
     buffer, or even a line printer.
 * Interrput capability. Without this, the system can't do syscalls from 
     usermode.
 * A timer. The kernel uses this for scheduling, and timekeeping. High
-    precision isn't needed, just at least 10KHz.
+    precision isn't needed, just at least 1KHz.
 
 Boot time
 ---------
-
-The Apollo kernel is a multiboot compliant kernel. The linker script tells
-multiboot to look for a symbol called 'start'. 
-
-The multiboot bootloader will be looking for a multiboot header, it's the
-job of the boot.s file (or equivilent) to provide that. The flags used in the
-Kernel should be:
-
-* MULTIBOOT_MEMORY_INFO
-* MULTIBOOT_PAGE_ALIGN
-
-You can find more about the multiboot header from the multiboot specification.
-
-It is your responsibility to write a function called start 
-
+It is a requirement that you set up your system into a well known state.
 In your start function you should set up a stack, preferably at least 4k large.
-It is also start's task to pass the multiboot header to main, stop interrupts,
-and call main.
+It is also start's task to set up the stack, stop interrupts, and call main.
 
 The stack should be aligned to a 32 byte boundary, in accordance to the SYSV
 ABI.
 
 Drivers To Implement
 --------------------
 
-When Apollo boots, it runs archInit() before doing kernel setup. archInit()
-should initialize all of the drivers listed below to a known state.
+After main has been called, Apollo enumerates all modules compiled within it and
+runs their init functions. The bare minimum a platform should support is:
 
-* A [Console Driver](Making-A-Console-Driver.html). This is a character output
-    device used to output the status of the kernel during bootup.
+* A [Console Module](Making-A-Console-Driver.html), implementing a console 
+    driver. This device used to output the status of the kernel during bootup.
 
-* An Interrupt Vector Driver. This driver should expose a function for creating
+* An interrupt vector module. This driver should expose a function for creating
     interrupt functions for syscalls. The actual syscall interface is handled
     by the kernel.
 
-* A Timer Driver. This should be a system timer that exposes functions to help
-    with scheduling such as alarm() and getTicks().
+* A time keeping module. This should be a system timer that exposes functions to
+    help with scheduling such as alarm() and getTicks().
 
-* Memory handler Driver. This driver basically should give the kernel 4k pages
+* Memory handler driver. This driver basically should give the kernel 4k pages
     when requested. This is used internally to power malloc().
-
-

docs/arch/new-arch/Making-A-Console-Driver.md

@@ -0,0 +1,24 @@
+x86 PC
+======
+
+Introduction
+------------
+
+The IBM compatible PC has been around since the 80's. In respect to the Apollo
+kernel, this architecture specifically refers to 32 bit processors. Apollo
+currently targets i686+ processors. This places a lower bound on machines to 
+around 1995 with the Pentium Pro.
+
+Standard Porting Base
+---------------------
+Due to the ubiquity of this platform, it has been determined that the Apollo
+kernel shall be developed with it as it's porting base. This makes the x86 PC
+architecture a Tier 1 supported platform.
+
+Availible Drivers
+-----------------
+
+* [VGA Console](../../../drivers/console/vga/)
+* [16550 Compatible UART](../../../drivers/console/16550_uart/)
+* [Real Time Clock](../../../drivers/clock/rtc-cmos)
+* [Intel 8254 PIC](../../../drivers/clock/i8254)