summaryrefslogtreecommitdiff
path: root/software/pic.bootloader/proto.txt
blob: 0e35e1e3e5681856ad68a5d80521d9384ed47e2f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
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.