From 1bcbaaca746b4784a48eedc70cc3fbad00242eaa Mon Sep 17 00:00:00 2001 From: P. J. McDermott Date: Sat, 31 Oct 2015 14:39:56 -0400 Subject: README: Write --- 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. -- cgit v0.9.1