From ba7e43c6653ac3a4b464caf7384260eaef5bf4fd Mon Sep 17 00:00:00 2001
From: Christian Pointner <equinox@spreadspace.org>
Date: Tue, 9 Jul 2013 22:47:06 +0000
Subject: moved downloader to bootloader dir

git-svn-id: https://svn.spreadspace.org/pic/trunk@63 a09c6847-51d9-44de-8ef2-e725cf50f3c7
---
 bootloader/proto.txt | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 bootloader/proto.txt

(limited to 'bootloader/proto.txt')

diff --git a/bootloader/proto.txt b/bootloader/proto.txt
new file mode 100644
index 0000000..0e35e1e
--- /dev/null
+++ b/bootloader/proto.txt
@@ -0,0 +1,200 @@
+Command List:
+=============
+
+  code | command
+ ------+------------
+    1  | identify
+    2  | boot
+    3  | reset
+    4  | read flash
+    5  | write flash
+    6  | read eeprom
+    7  | write eeprom
+    8  | read config
+    9  | write config
+
+
+Description:
+------------
+
+Every command consits of one byte command code, one byte length which counts all
+bytes of the command including the command code and checksum. The length is followed
+by zero or more data and a XOR checksum over all bytes sent. All data is
+transferred LSB first (aka little endian). All addresses and words are 2bytes long.
+Every answer to a command starts with the command code a length field which counts all
+bytes of the answer, 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
+    5  | value out of bounds
+
+identify:
+~~~~~~~~~
+  command:
+    1 | len=3 | <csum>
+
+  answer:
+    1 | len=19 | <ret> | version | name | devid | fs | fss | es | mess | 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:
+         3bytes, 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
+
+      devid:
+         2bytes, device id of the PIC
+         The downlaoder may use this id to check if it talks to the right bootloader
+
+      fs:
+         2bytes, flash size
+         The size of the flash in code words.
+
+      fss:
+         1byte, flash segment size
+         The number of words of one flash segment which has to be written at once.
+         If less than <fss> should be updated the downloader has to perform a read
+         operation first.
+
+      es:
+         2bytes, eeprom size
+         The size of the eeprom in bytes.
+
+      mess:
+         1byte, maximum eeprom segment size
+         This represents the maximum number of eeprom bytes which may be written or
+         read at once. Unlike <fss> value it is ok to write or read less than <mess>
+         bytes.
+
+      supported:
+         2bytes, 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:
+    2 | len=3 | <csum>
+
+  answer:
+    2 | len=4 | <ret> | <csum>
+
+  This instucts the bootloader to boot to the user application directly (no reset)
+
+
+reset:
+~~~~~~
+
+  command:
+    3 | len=3 | <csum>
+
+  answer:
+    3 | len=4 | <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.
+
+
+read flash:
+~~~~~~~~~~~
+
+  command:
+    4 | len=5 | addr | <csum>
+
+  answer:
+    4 | len=4+2*<fss> | <ret> | data | <csum>
+
+  The bootloader reads <fss> words from flash address <addr> and returns it as
+  <data>.
+
+
+write flash:
+~~~~~~~~~~~~
+
+  command:
+    5 | len=5+2*<fss> | addr | data | <csum>
+
+  answer:
+    5 | len=4 | <ret> | <csum>
+
+  The bootloader writes <data> (which has to contain exactly <fss> words) to address
+  <addr> inside the flash. The start address has to be aligned to <fss> boundaries.
+  Before writing the memory region will be erased. If there are words which shouldn't
+  be altered the downloader has to read these words first and reprogram the whole segment.
+
+
+read eeprom:
+~~~~~~~~~~~~
+
+  command:
+    6 | len=5 | addr | len | <csum>
+
+  answer:
+    6 | len=4+<len> | <ret> | data | <csum>
+
+  The bootloader reads <len> bytes from eeprom at address <addr> and returns it as
+  <data>. len is 1byte long.
+
+
+write eeprom:
+~~~~~~~~~~~~~
+
+  command:
+    7 | len=4+len(data) | addr | data | <csum>
+
+  answer:
+    7 | len=4 | <ret> | <csum>
+
+  The bootloader writes <data> (which has to contain exactly <len>-4 bytes) to address
+  <addr> inside the eeprom. len is 1byte long and the value must not exceed <mess> bytes.
+
+
+read config:
+~~~~~~~~~~~~
+
+  command:
+    8 | len=3 | nr | <csum>
+
+  answer:
+    8 | len=6 | <ret> | word | <csum>
+
+  The bootloader reads and returns the configuration word number <nr>. <nr> is one
+  byte long.
+
+
+write config:
+~~~~~~~~~~~~~
+
+  command:
+    9 | len=5 | nr | word | <csum>
+
+  answer:
+    9 | len=4 | <ret> | <csum>
+
+  The bootloader writes <word> onto configuration word number <nr>. <nr> is one
+  byte long.
-- 
cgit v1.2.3