fastboot: update getvar documentation.
The protocol doc states that calling `fastboot getvar` for an unknown
variable should return an empty OKAY message, but in reality modern
devices return a FAIL response in this case (tested with marlin and
shamu).
Additionally, some A/B logic in fastboot expects a FAIL response for
unknown variables in order to function properly.
This CL changes the documentation to match reality.
Bug: http://b/33756193
Test: none
Change-Id: I41f7c80585be73e60ca0ac216787596c4d60a1d5
diff --git a/fastboot/fastboot_protocol.txt b/fastboot/fastboot_protocol.txt
index 2801703..b12e420 100644
--- a/fastboot/fastboot_protocol.txt
+++ b/fastboot/fastboot_protocol.txt
@@ -78,7 +78,7 @@
Host: "getvar:nonexistant" request some undefined variable
-Client: "OKAY" return value ""
+Client: "FAILUnknown variable" getvar failure; see getvar details below
Host: "download:00001234" request to send 0x1234 bytes of data
@@ -113,7 +113,14 @@
"getvar:%s" Read a config/version variable from the bootloader.
The variable contents will be returned after the
- OKAY response.
+ OKAY response. If the variable is unknown, the bootloader
+ should return a FAIL response, optionally with an error
+ message.
+
+ Previous versions of this document indicated that getvar
+ should return an empty OKAY response for unknown
+ variables, so older devices might exhibit this behavior,
+ but new implementations should return FAIL instead.
"download:%08x" Write data to memory which will be later used
by "boot", "ramdisk", "flash", etc. The client
@@ -215,7 +222,7 @@
Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0E]getvar:version
Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x07]OKAY0.4
Host [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x0B]getvar:none
-Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x04]OKAY
+Device [0x00][0x00][0x00][0x00][0x00][0x00][0x00][0x14]FAILUnknown variable
Host <disconnect>
@@ -364,10 +371,10 @@
0x03 0x00 0x00 0x01
0x03 0x00 0x00 0x02
0x03 0x00 0x00 0x02 OKAY0.4
-0x03 0x00 0x00 0x03 getvar:foo
+0x03 0x00 0x00 0x03 getvar:none
0x03 0x00 0x00 0x03
0x03 0x00 0x00 0x04
- 0x03 0x00 0x00 0x04 OKAY
+ 0x03 0x00 0x00 0x04 FAILUnknown var
----------------------------------------------------------------------
[fastboot "INFO" responses, S = 0x0000]