From dd574db57a20e6821cb27175ab0a663a73dbf1af Mon Sep 17 00:00:00 2001 From: Bill Richardson Date: Thu, 9 Dec 2010 13:28:56 -0800 Subject: [PATCH] Updated documentation to describe config file format. This it what we finally agreed upon. Change-Id: I9dd859d5932328a2174b76331178a7c61ed01b5d BUG=chromium-os:781 TEST=none (documenation only) Review URL: http://codereview.chromium.org/5743001 --- user_tools/README_recovery.txt | 80 ++++++++++++++++++++++------------ 1 file changed, 53 insertions(+), 27 deletions(-) diff --git a/user_tools/README_recovery.txt b/user_tools/README_recovery.txt index 4360256103..97f413f846 100644 --- a/user_tools/README_recovery.txt +++ b/user_tools/README_recovery.txt @@ -12,47 +12,73 @@ steps. 3. Ask the user to select a USB drive, and write the recovery image to it. + + Here's the format of the config file: -The config file is a text file containing at least two paragraphs or -stanzas, which are separated by at least one blank line. Lines beginning -with '#' are completely ignored and do not count as blank lines. Non-blank -lines must consist of a non-blank key and non-blank value separated by a '=' -with no spaces on either side. The key may not contain whitespace. The value -may contain spaces, but all trailing whitespace is discarded. +The config file is a machine-generated, human-readable text file containing +at least two paragraphs or stanzas, which are separated by at least one +blank line. + +* Each line in the file ends with "\n" (LF), not "\r\n" (CRLF). + +* The file shall not contain any tab characters. + +* Lines beginning with '#' are completely ignored and do not count as blank + lines. + +* Non-blank lines must consist of a non-blank key and non-blank value + separated by a '=' with no spaces on either side. The key may not contain + whitespace. The value may contain spaces, but all trailing whitespace is + discarded. + +* The first stanza must contain a key named "recovery_tool_version'. Its + value must match the version of the recovery tool. If the value does not + match, then the key 'recovery_tool_update', if it exists in the first + stanza, should contain a string to display to the user. Regardless, if the + version doesn't match, the recovery tool should exit. + +* The first stanza MAY have platform-specific keys such as + 'recovery_tool_linux_version'. If present, this key is used instead of the + 'recovery_tool_version' key to determine the required recovery tool + version. + +* The current recovery_tool_version value is 0.9.1 + +* The archive shall be in ZIP format. -The first stanza must contain a key named "recovery_tool_version'. Its value -must match the version of the recovery tool. If the value does not match, -then the key 'recovery_tool_update', if it exists in the first stanza, -should contain a string to display to the user. Regardless, if the version -doesn't match, the recovery tool should exit. The second and remaining stanzas describe recovery images to put on the USB -drive. +drive. Each image stanza must contain, in this order: -For recovery_tool_version=1.0, each image stanza must contain: +* One and only one of each of these keys: -* One and only one of these keys: + name - string to show to the user + zipfilesize - size in bytes of the zipfile + file - the name of the file to extract from the zipfile + filesize - size in bytes of the extracted, uncompressed file + channel - the channel for this image ("beta-channel", + "dev-channel", "pilot-channel", etc.) - display_name - string to show to the user - file - the name of the file to extract from the tarball - size - size in bytes of the tarball +* Zero or more of these keys: -* One or more of these keys: - - url - where to find the tarball to download + hwid - the HWID of the device which can use this image (no + entry means "any device") * One or both of these keys: - md5 - md5sum of the tarball - sha1 - sha1sum of the tarball + md5 - md5sum of the zipfile + sha1 - sha1sum of the zipfile -* Any other keys are informational only and are not used by the recovery tool. +* One or more of these keys: + + url - where to find the zipfile to download +Any other keys are informational only and are not used by the recovery tool. -NOTE: This is still in flux. Possible additional keys are +If more than one url is provided, then they should be tried, in turn, until +one succeeds. - hwid - name - channel +At a minimum, the user shall be shown the name, channel, and all hwid values +for each image.