added protocol description

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

1 files changed, 166 insertions, 0 deletions

diff --git a/downloader/proto.txt b/downloader/proto.txt
new file mode 100644
index 0000000..295cec7
--- /dev/null
+++ b/downloader/proto.txt
@@ -0,0 +1,166 @@
+Command List:
+=============
+
+'i'  ... identify
+'b'  ... boot
+'r'  ... reset
+'f'  ... read flash
+'F'  ... write flash
+'e'  ... read eeprom
+'E'  ... write eeprom
+'c'  ... read config
+'C'  ... write config
+
+
+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 '??'
+
+identify:
+~~~~~~~~~
+  command:
+    'i' | <csum> (in this case <csum> will always be 'i')
+
+  answer:
+    'i' | version | name | fss | supported | <csum>
+
+      version:
+         2bytes, protocol version
+         It is an error if the major version (MSB) is different (hence any
+         protocol update must change the major version of the bootloader).
+
+      name:
+         10bytes, a descriptive name of the device.
+         The downloader has to compare this name with the device name supplied
+         via commandline and stop in case they don't match
+
+      fss:
+         1byte, flash segment size
+         The number of words of one flash segment which has to be written at once.
+         The downloader can fill up holes by supplying the illegal code word 0xFFFF
+         for some addresses. The bootloader will skip those areas.
+
+      supported:
+         1byte, a bitmap showing supported commands
+         The commands 'identify' and 'boot' are always supported by the bootloader,
+         others may not (i.e.: not all PICs allow to update the configurtion words)
+
+           bit | command
+          -----+----------
+            0  | reset
+            1  | read flash
+            2  | write flash
+            3  | read eeprom
+            4  | write eeprom
+            5  | read config
+            6  | write config
+
+
+boot:
+~~~~~
+
+  command:
+    'b' | <csum> (in this case <csum> will always be 'b')
+
+  answer:
+    'b' | <csum>
+
+
+  This instucts the bootloader to boot to the user application directly (no reset)
+
+
+reset:
+~~~~~~
+
+  command:
+    'r' | <csum> (in this case <csum> will always be 'r')
+
+  answer:
+    'r' | <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.
+
+
+read flash:
+~~~~~~~~~~~
+
+  command:
+    f | addr | <csum>
+
+  answer:
+    f | data | <csum>
+
+  The bootloader reads <fss> words from flash address <addr> and returns it as
+  <data>.
+
+
+write flash:
+~~~~~~~~~~~~
+
+  command:
+    F | addr | data | <csum>
+
+  answer:
+    F | (0|1) | <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'.
+
+
+read eeprom:
+~~~~~~~~~~~~
+
+  command:
+    e | addr | len | <csum>
+
+  answer:
+    e | data | <csum>
+
+  The bootloader reads <len> bytes from eeprom at address <addr> and returns it as
+  <data>.
+
+
+write eeprom:
+~~~~~~~~~~~~~
+
+  command:
+    E | addr | len | data | <csum>
+
+  answer:
+    E | (0|1) | <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'.
+
+
+read config:
+~~~~~~~~~~~~
+
+   command:
+      c | nr | <csum>
+
+   answer:
+      c | word | <csum>
+
+   The bootloader reads and returns the configuration word number <nr>.
+
+
+write config:
+~~~~~~~~~~~~~
+
+   command:
+      C | nr | word | <csum>
+
+   answer:
+      C | (0|1) | <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'.