diff options
Diffstat (limited to 'bootloader/proto.txt')
| -rw-r--r-- | bootloader/proto.txt | 200 |
1 files changed, 200 insertions, 0 deletions
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. |