summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorP. J. McDermott <pj@pehjota.net>2015-10-31 14:39:56 (EDT)
committer P. J. McDermott <pj@pehjota.net>2015-10-31 14:39:56 (EDT)
commit1bcbaaca746b4784a48eedc70cc3fbad00242eaa (patch)
tree28ecf3bbaf128aaa65a4458d8b228403962337e5 /README
parentc030425eabae128a6a3756bd60495df7f16a81a9 (diff)
downloadfirman.sh-1bcbaaca746b4784a48eedc70cc3fbad00242eaa.zip
firman.sh-1bcbaaca746b4784a48eedc70cc3fbad00242eaa.tar.gz
firman.sh-1bcbaaca746b4784a48eedc70cc3fbad00242eaa.tar.bz2
README: Write
Diffstat (limited to 'README')
-rw-r--r--README112
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.