obmc-phosphor-initfs: Create README.md
Create a README.md documenting features, optional configuration, invocation, and operation of the `init`, `shutdown`, and `update` scripts supporting storage in MTD partitions (SPI attached NOR devices).
diff --git a/meta-phosphor/recipes-phosphor/initrdscripts/files/README.md b/meta-phosphor/recipes-phosphor/initrdscripts/files/README.md
new file mode 100644
index 0000000..5d383e7
--- /dev/null
+++ b/meta-phosphor/recipes-phosphor/initrdscripts/files/README.md
@@ -0,0 +1,253 @@
+# Phosphor initfs
+The obmc-phosphor-initfs package contains a collection of scripts that combine to maintain a filesystem using the default static images in flash. When ombined with supporting utilities, they implement the [Systemd Init Interface]() using images stored in mapped memory technology devices (MTD) such as nor flash attached over a SPI bus and provide support to replace the images.
+
+### Usage
+`init`
+
+`shutdown [_verb_ [ _systemd-options_ ]]`
+
+ `_verb_` can be `shutdown`, `reboot`, `poweroff`, or `kexec`.
+ All are invoked with `-f` and `kexec` is also invoked with `-e`.
+
+`update [_options_]`
+
+### Features
+#### Filesystem content delivered in Read-only images
+- Delivered as an integrated unit
+ - Take a known amount of space
+ - Image size verified before delivery
+ - Compressed during image creation
+ - Reduces valuable space in flash
+ - Components tested together
+- Local modifications written into one filesystem
+ - Can be cleaned and recreated for maintence
+ - Stored in flash optimized filesystem
+ - Understands erase blocks and interrupted writes
+ - Shares overhead for erase blocks and logging
+ - Can be filtered to known file paths
+ - As recovery method when file system full
+ - Upon code update or entry into development sandbox
+ - Prevents unintentional overlay base image including point in time
+ - Supports peristent writes in multple directories
+ - `etc` requires some content to be overridden
+ - `var` requires write access but no base content
+ - `/home` desirable when login allowed
+ - Currently overlays full filesystem
+ - Provides easy development environment to replace any file that fits in rwfs or RAM
+ - Future plans to limit to required directories
+#### Configurable and Extensible
+- Configuration from sources available at OS, bootloader prompt, or image creation
+ - See security considerations for methods to limit options
+- Images stored in labeled MTD partitions
+ - The label reflects their content: `rwfs`, `rofs`, `u-boot-env`
+ - Image name matches MTD label
+ - Additional partitions can be created and update images supplied
+ - Full device labels are supported and contained partitions are scanned for delaying mounts
+- Support to
+ - apply remaining images at shutdown
+ - prune or erase writable filesystem
+ - download or inject rofs
+ - inject additional updates supporting automated recovery
+ - copy content into RAM allowing image application during runtime
+ - perfor manual intervention and debug via shell on console device
+
+##### Runtime configuration selecting additional or alterative `init`
+- Selected by long option names to avoid conflicts
+- Controlled by initrd content for deployment conotrol
+ - Signed initrd or initramfs images allows owner control
+ - Options can be built initrd image
+ - Providing a set of always selected options
+ - Optionally ignoring other sources below
+- Can be read from kernel command line
+ - typically `bootargs` variable at execution of `boot` command
+- Can be read from Das U-Boot compatiable environment
+ - Contained in two variables
+ - Avoids undesired configuration from other macros
+ - Allows one to always be cleared during os boot
+ - Requires `setenv` then `saveenv` at bootloader
+ - Alternatively can be set via `fw_setenv` from operating system
+- Supports tweaks to execution and storage
+ - Erase writable filesystem
+ - optionally preserving selected content
+ - Invoke a shell on detected error or demand
+ - One or both layers of overlay copied into RAM supporting
+ - Code update during system runtime (as flash is not mounted)
+ - Support developer test and debug
+ - Allow replacment of any content for one boot
+ - Content obtained from initrd, MTD, or network
+ - Initial overlay can be primed from writable overlay
+ - Selected iles can be written back to writable overlay
+#### systemd
+- Implments the [Systemd Initrd Interface]()
+ - `init` locates and mounts the filesystem stack
+ - `shutdown` is copied into `/run/initramfs` by `init` and
+ - Unmounts overlay allowing `rwfs` to unmount
+ - Calls `update` after filesystems are unmounted
+ - with watchdogd pinging watchdog device
+- Both `init` and `shutdown` integrate with `update` for code update and development environment support
+- All three share knowlege of expected filesystem mountpoinits and update image storage locations
+#### Provides an enviornment and method to update content
+- Images staged in `/run/initramfs` (a `tmpfs`)
+- Images written to MTD partition with `flash_copy`
+- Flash written when images are unmounted (eg at system reboot or shutdown)
+- Special hooks allow reboot into online volatile environment
+ - Supports image update while main operation continues
+ - Provides temporary environemnt to download, test, and debug
+- Can flash image
+#### Troubleshooting and Recovery environment
+- Init configuration tweaks were developed incrementally during the debug of
+ - the `init` script
+ - the code `update` script
+- Debug shell
+ - Can Replace default of inducing kernel panic expecting watchdog or panic timer to cause reboot
+ - Allows interactive troubleshooting and recovery
+ - Allows multiple transitions between code update and full filesystem
+ - Note job control is not available on `/dev/console`
+ - execute `getty -l /bin/sh _console-device_` to obtain job control
+ - to find console device try `cons=$(tr ' ' '\n' < /sys/class/tty/console/active | tail -n 1)`
+- Will call shell repeatedly until
+ - The shell exists cleanly (`exit 0`)
+ - The file `/takeover` is found, in which case
+ - The shell will be invoked via `exec(2)`
+ - Allowing edit of `init` script
+ - to be restarted via `exec init`
+
+##### Security Considerations
+- By default `init` exits on error inducing kernel panic
+ - It's expected the kernel `panic=` or watchdog will result in a new attempt
+- Initrd signing can be combined with secure boot to prevent options parsing
+ - images or signed injections and selection mechanisms would need to be created to support
+ - factory reset
+ - clean rwfs filesystem
+ - runtime, online code update
+ - Content copied into memory
+- File injection can can be used
+ - Files injected into initrd can select some options
+ - Files injected into initrd can skip other sources
+- All network download or indivual url schemes can be disabled by patching configuration variable settings in the init script
+##### Security Considerations
+- Scripts can be modified before execution as desribed in [Developer notes](README.md#Deceloper)
+ - `shutdown` and `update` execute from `/run/initramfs`
+ - they can be edited altering their content before invocation
+ - `init` can exit to a shell and then be replaced or restarted
+ - `init` can be invoked after `shutdown` commpletes instead of calling the `_verb_`
+- Features can be selected at bootloader via
+ - Can be configured by injecting files into initramfs
+ - Can be configured to automatically download read only image from network
+ - Files injected into the initrd
+ - Concatinating cpio.gz use for iniramfs
+ - Building an image with additional file(s)
+ - The kernel command line
+ - In `Das U-Boot` when `boot` command is issued the contents of `bootargs` are passed to the payload
+ - From named bootloader environment variables
+ - `openbmcinit` for persistent options
+ - `openbmconce` for options expected to be cleared each boot
+ - the variable is expected to be cleared by a systemd unit
+
+##### patchable or editable configuration
+`# Set to y for yes, anything else for no.`
+option and default | description
+-|-
+`force_rwfst_jffs2=y` | If rwfs is recognized as containing a block based filesystem save files and erase the partition to select replacement jffs filesystem
+`flash_images_before_init=n` | apply injected images before mounting filesystem
+`consider_download_files=y` | look for option to download image-rofs from network
+`consider_download_tftp=y` | recognise `tftp:` scheme
+`consider_download_http=y` | recognise `http:` scheme
+`consider_download_ftp=y` | recognise `ftp:` scheme
+
+#### `init` options
+option | description
+-|-
+`enable-initrd-debug-sh` | invoke debug shell loop instead of exiting expecting a kernel panic
+`debug-init-sh` | invoke shell after establishing `shutdown` evironment
+`clean-rwfs-filesystem` | remove paths not designated for preservation across code updates from rwfs filesystem
+`factory-reset` | erase rwfs filesystem without preserving any writable content
+`overlay-filesystem-in-ram` | store overlay in ram (starting with no content)
+`copy-files-to-ram` | copy files to be preserved into ram overlay
+`copy-base-filesystem-to-ram` | copy content of rofs into ram (allowing partition to be written during runtime)
+
+# init operation
+- Changes current directory to `/`
+- Establishes special filesystem mounts supporting utilities
+ - `/dev`
+ - `/proc`
+ - `/sys`
+- Creates `shutdown` execution environment under `/run/initramfs`
+ - Mount a `tmpfs` at `/run` and make directory as needed
+ - Recursively copy package and supporting utility content into directory
+- Assemble options into `/run/initramfs/init-options` by copying from `/init-options` or combining `/init-options-base` with the `openbmcinit` and `openbmconce` variables from `u-boot-env` partition and the kernel command line content in `/proc/cmdline` into `/run/initramfs/init-options`
+- Locates and prints MTD partitions labeled `rofs` and `rwfs` by number
+- Invoke Debug Shell if selected by `debug-init-sh`
+- Downloads `/run/image-rofs` if selected by `openbmc-init-download-files`
+ - Presumes use of the [nfsroot kernel command line]() option `ip=`
+ - Copies `/proc/net/pnp` to `/run/systemd/resolve/resolv.conf` and establishes symlink from `/etc/resolv.conf`
+ - Obtains the download url from first location found among
+ - `/init-download-url`
+ - `/run/initramfs/init-download-url`
+ - `openbmcinitdownloadurl` bootloader environment variable
+ - Chooses command from the URL
+ | scheme | command |
+ |-|-|
+ | `http` | `wget` |
+ | `ftp` | `wget` |
+ | `tftp` | `tftp -g` |
+- Moves any injected code update images
+ - from `/image-*` to `/run/image-` for immediate use
+ - from `/image-*` to `/run/initramfs/image-*` for immediate update (selected by script config variable ``)
+- Considers `rwfs` image maintence
+ - If selected by `clean-rwfs-filesystem`
+ - If the content of `rwfs` recognised as another filesystem but configuration forces `jffs` (force migration from inferior interm choices)
+ - If selected by `factory-reset`
+ - also suppresses preservation of any content via `--no-save-files`
+ - By creating empty `/run/initramfs/image-rwfs` update
+- Invokes `update` to apply images preserving content
+ - Calls `flasherase` on `rwfs` if triggered by empty update
+- Copies files in preserve list into ram if selected by `copy-files-files-to-ram`
+- Copys `rofs` partition into ram (unless image downloaded) for loopback mount
+- Mounts `rofs` on `/run/ro`
+- If it exists, runs `fsck._rwfst_` from `rofs` using a `chroot` environment
+- Mounts `rwfs` on `/run/rw` (except when runninig with overlay in ram)
+- Establishs directories for work (empty) and overlay content in rw mount space
+- Fast forwards date to the latest of
+ - the current kernel time (supporting working RTC)
+ - `/etc/os-release` from mounted `rofs` image
+ - `/var/lib/systemd/random-seed` from possibly mounted `rwfs` filesystem
+- Creates overlay combining `rwfs` and `rofs` and mounts on `/root`
+- Confirms non-empty executable exists at `/sbin/init`
+- Moves basic filesystems onto `/root`
+- Invokes `switchroot` to
+ - Unlink content from initramfs
+ - Perform magic needed for `pivot_root`
+ - Invoke `/sbin/init`
+
+- mounts including
+ - `/usr` content
+ - `/etc` with writable overlay over the base image
+ - `/run/` including
+ - `/run/initramfs` execution environment
+ - `/run/initramfs/shutdown`
+ - Several other filesystems
+ - `/var` mounted writable space over empty base directory
+ - `/sys`
+ - `/proc`
+ - `/dev`
+## Possible Future Enhancements
+- Restrict overlay directories to those required
+ - Match writability of other [filesystem layouts]()
+ - Only overlay `etc` from filesystem
+ - Bind mount `/var` and `/home`
+ - Provide option for full development overlay in ram
+- Split paths in filesystem to be preserved
+ - Allow selective factory reset by removing inidividual files
+ - Adopt inclusive naming standards
+- Allow support other image downloads
+- Parse config variables from file
+ - Disable / Enable configuration
+ - Name of image files
+ - Storage beyond MTD partitions
+ - Share between `init` `update` and `shutdown`
+- Option to automatically apply update images during boot
+## Reference
+- [filesystem layouts](https://github.com/openbmc/docs/blob/master/architecture/code-update/flash-layout.md#writable-filesystem-options)
+- [Systemd Initrd Interface](https://systemd.io/INITRD_INTERFACE/)
+- [nfsroot kernel command line](https://docs.kernel.org/admin-guide/nfs/nfsroot.html#kernel-command-line)