diff --git a/README b/README index 2179ce8..5a4e9a0 100644 --- a/README +++ b/README @@ -1,3 +1,5 @@ +-*- mode: org; -*- +* Copyright header ## Copyright (C) 2016 Jeremiah Orians ## This file is part of stage0. ## @@ -17,6 +19,12 @@ The master repository for this work is located at: https://savannah.nongnu.org/projects/stage0/ +* If you wish to contribute: +pull requests can be made at https://github.com/oriansj/stage0 +or patches/diffs can be sent via email to Jeremiah (at) pdp10 [dot] guru +or join us on freenode's #bootstrappable + +* Goal This is a set of manually created hex programs in a Cthulhu Path to madness fashion. Which only have the goal of creating a bootstrapping path to a C compiler capable of Compiling GCC, with only the explicit requirement of a single 1 KByte binary or less. @@ -24,10 +32,12 @@ Compiling GCC, with only the explicit requirement of a single 1 KByte binary or Additionally, all code must be able to be understood by 70% of the population of programmers. If the code can not be understood by that volume, it needs to be altered until it satifies the above requirement. +* Also found within This repo contains a few of my false start pieces that may be of interest to people who want to independently create the root binary, I welcome all bug fixes and code that aids in the above stated goal. +* FYI I'll be adding more code and documentation as I build pieces. ALL code in this REPO is under the GPLv3 or Later. @@ -35,3 +45,130 @@ In order to build stage0 and all the pieces, one only needs to run make all. Each individual piece can be built by simply running make $piece with $piece being replaced by the actual part you want to make. The only pieces that have any external dependencies are the Web IDE (Python3+CherryPy), libvm (GCC) and vm (GCC+GNU getopt) + +* Future +** Software + +** Hardware + +* Need to know information +** stage0 +The stage0 is the ultimate lowest level of bootstrap that is useful for systems +without firmware, operating systems nor any other provided software functionality +Those with such capabilities can skip this stage as it requires human input + +*** Hex0_monitor +The Hex0_monitor provides dual functionality: +1) It assembles hex0 programs manually typed in +2) It writes the characters, providing minimal text input functionality. + +The first is essential for creating of the root binaries. +The second is essential for creating source files before you have an editor. +The distinction is important because only the Hex0 assembler in stage1 is built +by the Hex0_monitor and from that point onwards it is used as a minimal text +editor until a more advanced text editor can be bootstrapped. + +** stage1 +The stage1 is dependent on the availablity of text source files and atleast a +hex0 monitor or assembler. The steps in this stage can be fully automated should +one trust their automation or performed manually on any hardware they trust. + +Regardless of which method selected, the resulting binaries MUST be identical. + +*** Hex0 +The Hex0 assembler or stage1_assembler-0 is the head node of the stage1 bootstrap. +Its functionality is reduced compared to the stage0 monitor simply because it +only performs half of the required functions; that of generating binaries from +hex0 source files. + +It most important features of note are: +; line comments and +# line comments +As careful notes are essential for this stage + +*** Hex1 +The Hex1 assembler or stage1_assembler-1 is the next logical extension of the +Hex0 assembler, single character labels and relative displacement using a prefix. +In this case labels start with : thus the label a must be written :a and the +prefix for relative offsets is @ thus the pointer must be written @a +Further because of the mescc-tools standardization of syntax @label indicates a +16bit relative displacement. + +Alternate architectures porting this need not limit themselves to 16bit +displacements should they so choose, rather they must provide atleast 1 size +of displacement or if they so desire, they may skip and write their Hex2 +assembler in Hex0 but as it is a much larger program, I recommend against it. + +*** Hex2 +The Hex2 assembler or stage1_assembler-2 or hex2_linker is as complex of a hex +language that is both meaningful and worth the effort + +Hex2's important advances over Hex1 are as follows: +Support for long labels (Minimal 42 chars, ideally unlimited) +Support for Absolute addressing ($label for 16bit absolute addresses) +Support for Alternate pointer sizes (%label for 32bit relative and &label for +32bit absolute addresses) + +Optionally support for !label (8bit relative addressing) and ?label +(Architecture specific size/properties) and/or @label1>label2 %label1>label2 +displacements may be implemented should the specific architecture require it +for human readable hex2 source files (such as ELF headers) + +*** M0 +M0 or M0-macro or M1-macro is the minimal string replacement program with string +processing functionality required to convert an Assembly like syntax into Hex2 +programs that can be compiled. Its rules are merely an extension of Hex2 with +the goal of reducing the amount of hex that one would need to write. + +The 3 essential pieces are: +1) DEFINE STRING1 HEX_CHARACTERS (No extra whitespace nor \t or \n inside +definition) +2) "Raw strings" allow every character except " as there is no support for +string escapes, including NULL; which are converted to Hex chars for Hex2 +To convert back to the chars inside of the "quotes" with the addition of a +trailing NULL character or the number desired (Must be atleast 1, no upper +bound) and restrictions such as padding to word boundries are accetpable. +3) 'Raw char strings' will passing anything inside of them (except ' which +termininates the string). + +Thus by combining :label, @label, DEFINE SYSCALL 0F05, Raw strings and chars; +one has created a rather flexiable and powerful Assembler capable of building +far more ambitious pieces in "Macro Assembly" + +** stage2 +The stage2 is dependent on the availabilty of text sources files and atleast a +functional macro assembler and can be used to build operating systems or other +"Bootstrap" functionality that might be required to enable functional binaries; +such as programs that set execute bits or generate dwarf stubs. + +*** FORTH +Because a great many people stated FORTH would be an ideal bootstrapping language +the time and effort was put forth by Caleb and Jeremiah to provide a framework +for those people to contribute immediately; thus the FORTH was born. + +Several efforts were taken to make the FORTH more standard but ultimately it was +determined, Assembly was preferable as the underlaying architecture wasn't total +garbage. + +It now sits waiting for any FORTH programmer who wishes to prove FORTH is a real +bootstrapping language. + +*** Lisp +The next recommendation in bootstrapping was Lisp, so efforts were taken to +design the most minimal Lisp with all of the functionality described in the +original Lisp papers. The task was completed relatively quickly compared to the +FORTH and even had enhancements such as a compacting garbage collector. + +Ultimately it was found, the lisp that many rave about isn't entirely compatable +with modern lisps or schemes; thus was shelved for any Lisper who wishes to pick +it up. + +*** C +After being told for months there is no way to write a proper C compiler in +assembly and months of research without any human written C compilers in +assembly found. To prove the point Jeremiah decided the First C compiler on the +bootstrap would actually be a cross-compiler for x86, such that everyone would +be able to verify it did exactly what it was supposed to and see it self-host +its C version. + +** stage3