added return codes for proto definition

git-svn-id: https://svn.spreadspace.org/pic/trunk@20 a09c6847-51d9-44de-8ef2-e725cf50f3c7

1 files changed, 36 insertions, 24 deletions

diff --git a/downloader/proto.txt b/downloader/proto.txt
index 295cec7..1228811 100644
--- a/downloader/proto.txt
+++ b/downloader/proto.txt
@@ -18,7 +18,20 @@ Description:
 Every command consits of one byte command code, a fixed number of bytes as
 arguments and ends with a XOR checksum over all bytes sent. All data is
 transferred LSB first.
-If the command code is unkown the bootloaders retunrns '??'
+Every answer to a command starts with the command code. One byte return value,
+optionally some data and a checksum (XOR over all bytes received)
+The return codes have the following meaning:
+
+  code | Error
+ ------+-------------
+    0  | OK
+    1  | invalid command
+    2  | bad checksum
+    3  | not implemented
+    4  | flash write error
+    5  | address invalid
+    6  | address prohibited
+
 
 identify:
 ~~~~~~~~~
@@ -26,7 +39,7 @@ identify:
     'i' | <csum> (in this case <csum> will always be 'i')
 
   answer:
-    'i' | version | name | fss | supported | <csum>
+    'i' | <ret> | version | name | devid | fss | supported | <csum>
 
       version:
          2bytes, protocol version
@@ -38,6 +51,10 @@ identify:
          The downloader has to compare this name with the device name supplied
          via commandline and stop in case they don't match
 
+      devid:
+         2bytes, device id of the PIC
+	 The downlaoder may use this id to check if it talks to the right bootloader
+
       fss:
          1byte, flash segment size
          The number of words of one flash segment which has to be written at once.
@@ -67,8 +84,7 @@ boot:
     'b' | <csum> (in this case <csum> will always be 'b')
 
   answer:
-    'b' | <csum>
-
+    'b' | <ret> | <csum>
 
   This instucts the bootloader to boot to the user application directly (no reset)
 
@@ -80,8 +96,7 @@ reset:
     'r' | <csum> (in this case <csum> will always be 'r')
 
   answer:
-    'r' | <csum>
-
+    'r' | <ret> | <csum>
 
   The device performs a reboot. If the boot condition (i.e.: port pin) is not met
   this instructs the device to boot to the user application.
@@ -91,10 +106,10 @@ read flash:
 ~~~~~~~~~~~
 
   command:
-    f | addr | <csum>
+    'f' | addr | <csum>
 
   answer:
-    f | data | <csum>
+    'f' | <ret> | data | <csum>
 
   The bootloader reads <fss> words from flash address <addr> and returns it as
   <data>.
@@ -104,24 +119,23 @@ write flash:
 ~~~~~~~~~~~~
 
   command:
-    F | addr | data | <csum>
+    'F' | addr | data | <csum>
 
   answer:
-    F | (0|1) | <csum>
+    'F' | <ret> | <csum>
 
   The bootloader writes <data> (which has to contain exactly <fss> words) to address
-  <addr> inside the flash. In case of Error '0' is returned, on success the return
-  code contains '1'.
+  <addr> inside the flash.
 
 
 read eeprom:
 ~~~~~~~~~~~~
 
   command:
-    e | addr | len | <csum>
+    'e' | addr | len | <csum>
 
   answer:
-    e | data | <csum>
+    'e' | <ret> | data | <csum>
 
   The bootloader reads <len> bytes from eeprom at address <addr> and returns it as
   <data>.
@@ -131,24 +145,23 @@ write eeprom:
 ~~~~~~~~~~~~~
 
   command:
-    E | addr | len | data | <csum>
+    'E' | addr | len | data | <csum>
 
   answer:
-    E | (0|1) | <csum>
+    'E' | <ret> | <csum>
 
   The bootloader writes <data> (which has to contain exactly <len> bytes) to address
-  <addr> inside the eeprom. In case of Error '0' is returned, on success the return
-  code contains '1'.
+  <addr> inside the eeprom.
 
 
 read config:
 ~~~~~~~~~~~~
 
    command:
-      c | nr | <csum>
+     'c' | nr | <csum>
 
    answer:
-      c | word | <csum>
+     'c' | <ret> | word | <csum>
 
    The bootloader reads and returns the configuration word number <nr>.
 
@@ -157,10 +170,9 @@ write config:
 ~~~~~~~~~~~~~
 
    command:
-      C | nr | word | <csum>
+     'C' | nr | word | <csum>
 
    answer:
-      C | (0|1) | <csum>
+     'C' | <ret> | <csum>
 
-   The bootloader writes <word> onto configuration word number <nr>. In case
-   of an error '0' is returned, on success the return code contains '1'.
+   The bootloader writes <word> onto configuration word number <nr>.