README: Write

1 files changed, 112 insertions, 0 deletions

diff --git a/README b/README
index e69de29..0adf1b2 100644
--- a/README
+++ b/README
@@ -0,0 +1,112 @@
+Firmware Manager
+================
+
+This is firman, the Firmware Manager.
+
+firman automatically downloads and installs boot firmware images such as
+libreboot.
+
+firman can download firmware from the following distributors:
+
+  * Libreboot project
+  * Libiquity
+
+firman supports the following systems:
+
+  * Lenovo ThinkPad X200[1]
+  * Minifree Libreboot X200
+  * Libiquity Taurinus X200
+
+[1]: If already running firmware (such as libreboot) without flash
+     region write protections enabled by the firmware or Flash
+     Descriptor and without the Intel Management Engine enabled
+
+firman will ask which distributor (if a system has multiple firmware
+distributors), download mirror, and firmware version to use.  For
+libreboot images with the GNU GRUB payload, firman will ask which
+keyboard layout to use.  For systems with the Intel ICH9, firman will
+allow the MAC address of the Intel Gigabit Ethernet controller to be
+changed.
+
+User Interfaces
+===============
+
+firman provides two user interfaces: a command-line interface (CLI) and
+a textual user interface (TUI).
+
+The TUI is based on a small custom library to manipulate ECMA-48 (ANSI
+X3.64) terminals with DEC extensions (i.e. terminals compatible with the
+DEC VT100).  This terminal manipulation library is tested to work with
+the Linux console, XTerm, and graphical terminal emulators that use the
+VTE library (such as GNOME Terminal and Xfce Terminal).
+
+There is one known bug with VTE (observed with versions 0.28.2 and
+0.34.9): the text and background colors suddenly change after any key is
+pressed while the last item of a menu dialog is selected.  Clearing the
+terminal (as is done when the next dialog is drawn) resolves the
+problem.
+
+Design Rationale
+================
+
+firman has two main goals: a user friendly interface and a small program
+size.
+
+Language Choice
+---------------
+
+firman needs to run a number of executable programs, including flashrom
+and ich9gen.  This means building argument vectors, creating pipes,
+forking child processes, duplicating file descriptors, and executing
+files.  It also needs to download (e.g. via the libcurl library or a
+wget executable) and verify (e.g. via an embedded SHA-512 implementation
+or a sha512sum executable) files.
+
+A C program can certainly do all of this reasonably well.  But working
+with child processes, pipes, and file descriptors are things that can be
+done with less code in shell command language than in C.  Additionally,
+a BusyBox system is highly likely to already have a shell interpreter,
+(small) wget executable, and sha512sum executable, so using libcurl or
+an embedded SHA-512 implementation can increase the size of a small
+embedded system.
+
+Therefore, writing firman in shell command language actually makes it
+smaller than writing it in C would.
+
+Terminal Manipulation Library
+-----------------------------
+
+A user friendly interface is one with visual elements, or widgets.
+Users are generally more familiar with dialog boxes, menus, text fields,
+and buttons than they are with command line prompts.  So firman offers a
+textual user interface (TUI) in addition to a basic command line
+interface (CLI).
+
+Most TUI applications written in C or C++ use a common terminal
+manipulation library (such as GNU Ncurses) that implements curses or a
+similar API.  Other languages often have native libraries or executables
+to allow applications to use such a terminal manipulation library.  Most
+TUI applications written in shell command language use either dialog or
+whiptail.
+
+dialog is a somewhat large executable that uses GNU Ncurses (which isn't
+very small either).  Together, dialog and Ncurses take a few hundred
+kibibytes of space.  The whiptail executable and its Newt library are
+smaller than dialog and Ncurses are, but Newt and dialog depend on the
+huge S-Lang library.  Newt, whiptail, and S-Lang combined weigh in at
+well over a mebibyte.
+
+firman's terminal manipulation library (term.sh) and TUI module, on the
+other hand, total only about 15 KiB.  Plus, shell command language
+programs compress much better than compiled binaries do; firman's
+term.sh and TUI module can be compressed down to under 4 KiB.
+
+Copyright Information
+=====================
+
+Copyright (C) 2015  Patrick "P. J." McDermott
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.