Subversion Repositories svn.mios

Rev

Rev 53 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
47 tk 1
$Id: mios_sysex_implementation.txt 984 2011-04-17 20:23:22Z tk $
2
 
3
MIOS SysEx Implementation
4
=========================
5
 
6
 
7
Following Commands are available
8
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9
 
10
   a) Command X1
11
      read from internal Flash, internal EEPROM, external BankStick
12
      (X = 0...7 - address extension)
13
 
14
   b) Command X2
15
      write to internal Flash, internal EEPROM, external BankStick
16
      (X = 0...7 - address extension)
17
 
18
   c) Command 03
19
      select BankStick before read/write
20
 
21
   d) Command 08
22
      print a message on LCD
23
 
24
   e) Command 0D
25
      debug interface
26
 
27
 
28
Important Notes
29
~~~~~~~~~~~~~~~
30
 
31
   o the maximum number of bytes which can be written at once is 1024 (1k)
32
     If more data has to be written, use multiple SysEx blocks and insert
33
     a delay of 750 mS between every block
34
     The hex2syx.pl script takes this already into account
35
     See also http://www.ucapps.de, Concepts->MIOS->Bootstrap Loader
36
 
37
   o if more than 1024 bytes are requested by the read command, MIOS
38
     will send multiple blocks and insert a delay between every block
39
 
40
   o internal flash and external BankStick addresses must be aligned
41
     to 64 bytes (0x40)
42
 
43
   o if data should be written into or read from a BankStick, use
44
     the "03" command first to select the bankstick, thereafter the
45
     read/write command
46
     The hex2syx.pl script takes this already into account
47
 
48
   o every command except for 08 returns a acknowledge or disacknowledge
49
     code which is documented below
50
 
51
   o with command 01, 02 and 03 all user tasks will be suspended by
52
     MIOS to avoid interferences with the user program.
53
     MIOS will reset the core when no additional command has been
54
     received after 2 seconds
55
 
56
   o the first level bootloader only supports command 02
57
 
58
   o the first level bootloader doesn't allow to overwrite
59
     the bootloader range (0x0000-0x03ff)
60
 
61
   o the second level bootstrap loader supports all commands, but
62
     doesn't allow to overwrite the MIOS and Bootloader
63
     address range (0x0000-0x2fff)
64
 
65
 
66
The Read command (X1)
67
~~~~~~~~~~~~~~~~~~~~~
68
 
69
   Structure:
70
      F0 00 00 7E 40 <device-id> <au>1 <ah> <al> <ch> <cl> F7
71
 
72
      <device-id>: the MIOS device ID from 00 to 7F
73
      <au>: 3-bit address extension
74
      <ah>: 14-bit address, high byte
75
      <al>: 14-bit address, low byte
76
      <ch>: 14-bit counter, high byte
77
      <cl>: 14-bit counter, low byte
78
 
79
      The resulting PIC address is derived from the 14-bit address
80
      with following formula:
81
 
82
         ah = (address >> 10) & 0x7f
83
         al = (address >>  3) & 0x7f
84
         address = (ah << 10) | (al << 3)
85
         ch = (counter >> 10) & 0x7f
86
         cl = (counter >>  3) & 0x7f
87
         counter = (ch << 10) | (cl << 3)
88
 
89
      when address >= 0x00000 and address <= 0x07fff:
90
         -> Internal Flash selected, offset 0x0000-0x7fff
91
      when address >= 0x08000 and address <= 0x0ffff:
92
         -> Internal EEPROM selected, offset 0x0000-0x00ff
93
            (64k devices: 0x0000-0x03ff)
94
      when address >= 0x08100 and address <= 0x0ffff:
95
         -> Invalid address range (reserved)
96
      when address >= 0x10000 and address <= 0x1ffff:
97
         -> External BankStick selected, offset 0x0000-0xffff
98
      when address >= 0x28000 and address <= 0x2ffff:
99
         -> Internal Flash selected, offset 0x8000-0xffff
100
            (64k devices only!)
101
 
102
      The address extension <au> selects the BankStick number
103
 
104
   Examples:
105
 
106
      o read the whole internal flash
107
        F0 00 00 7E 40 00 01 00 00 10 00 F7
108
      o read the whole internal EEPROM
109
        F0 00 00 7E 40 00 01 20 00 00 20 F7
110
      o select BankStick #0, read the whole 32k BankStick memory (24LC256)
111
        F0 00 00 7E 40 00 01 40 00 20 00 F7
112
      o select BankStick #0, read the whole 64k BankStick memory (24LC512)
113
        F0 00 00 7E 40 00 01 40 00 40 00 F7
114
 
115
   The returned SysEx blocks can be written back into the core/BankStick.
116
   In this way it is possible to create backups or to clone the content
117
   from one to another MIOS core.
118
 
119
   It's also possible to edit the returned content by using the
120
   syx2asm.pl script (see the bs_xfer example which contains a
121
   step-by-step guide)
122
 
123
 
124
The Write command (X2)
125
~~~~~~~~~~~~~~~~~~~~~~
126
 
127
   Structure:
128
      F0 00 00 7E 40 <device-id> <au>2 <ah> <al> <ch> <cl> <dump> <checksum> F7
129
 
130
      <device-id>: the MIOS device ID from 00 to 7F
131
      <au>: 3-bit address extension
132
      <ah>: 14-bit address, high byte
133
      <al>: 14-bit address, low byte
134
      <ch>: 14-bit counter, high byte
135
      <cl>: 14-bit counter, low byte
136
      <dump>: the data which will be uploaded, scrambled in 7-bit format
137
              see the hex2syx.pl and syx2asm.pl scripts for further details
138
      <checksum>: inverted checksum from <ah> to the last byte of <dump>
139
 
140
      The resulting PIC address is derived from the 14-bit address
141
      with following formula:
142
 
143
         ah = (address >> 10) & 0x7f
144
         al = (address >>  3) & 0x7f
145
         address = (ah << 10) | (al << 3)
146
         ch = (counter >> 10) & 0x7f
147
         cl = (counter >>  3) & 0x7f
148
         counter = (ch << 10) | (cl << 3)
149
 
150
      when address >= 0x00000 and address <= 0x07fff:
151
         -> Internal Flash selected, offset 0x0000-0x7fff
152
      when address >= 0x08000 and address <= 0x0ffff:
153
         -> Internal EEPROM selected, offset 0x0000-0x00ff
154
            (64k devices: 0x0000-0x03ff)
155
      when address >= 0x08100 and address <= 0x0ffff:
156
         -> Invalid address range (reserved)
157
      when address >= 0x10000 and address <= 0x1ffff:
158
         -> External BankStick selected, offset 0x0000-0xffff
159
      when address >= 0x28000 and address <= 0x2ffff:
160
         -> Internal Flash selected, offset 0x8000-0xffff
161
            (64k devices only!)
162
 
163
      The address extension <au> selects the BankStick number
164
 
165
   Examples: use hex2syx.pl or MIOS Studio!!!
166
 
167
 
168
The Select BankStick command (03)
169
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170
 
171
   Structure:
172
      F0 00 00 7E 40 <device-id> 03 <bs-number> F7
173
 
174
      <device-id>: the MIOS device ID from 00 to 7F
175
      <bs-number>: the BankStick number from 0 to 7
176
 
177
   This command was used in previous MIOS versions (<V1.8) to
178
   select the BankStick before writing or reading.
179
 
180
   !!! THIS COMMAND IS OBSOLETE !!!
181
 
182
   The BankStick is now selected with the address extension
183
   of the Read/Write command.
184
 
185
 
186
The LCD message command (08)
187
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
 
189
   Structure:
190
      F0 00 00 7E 40 <device-id> 08 <lcd-command> <data> F7
191
 
192
      <device-id>:   the MIOS device ID from 00 to 7F
193
      <lcd-command>: see below
194
      <data>:        depends on the command, see below
195
 
196
 
197
   <lcd-command> == 00:
198
      Clears the LCD, starts a message (display will not be
199
      updated for the next 2 seconds).
200
      The <data> field is optional, it contains additional
201
      characters which are print immediately from position 0/0
202
 
203
   <lcd-command> == 01:
204
      Sets the cursor and starts a message (display will not be
205
      updated for the next 2 seconds).
206
      <data>:
207
         - first byte: cursor X position (0x00-0x7f)
208
         - second byte: cursor Y position (0x00-0x7f)
209
         - following bytes: optional, contains additional
210
           characters which will be print immediately from
211
           the new cursor position
212
 
213
   <lcd-command> == 02:
214
      Starts a message (display will not be updated for the
215
      next 2 seconds).
216
      <data>: contains characters which will be print immediately
217
      from the current cursor position
218
 
219
   <lcd-command> == 03:
220
      Stops a message immediately, the USER_DISPLAY_Init routine will be
221
      invoked which reinitializes the LCD screen
222
 
223
   Note: every command will cause that the USER_DISPLAY_Init routine
224
   will be invoked within 2 seconds after the last LCD command
225
   has been received
226
 
227
   Note2: these commands are also used by MIOS itself when
228
   display type #06 has been selected
229
 
230
   Note3: these commands are also received by MBHP_TV
231
 
232
   Examples:
233
 
234
      o clear screen and print "123" for 2 seconds
235
        F0 00 00 7E 40 08 00 31 32 33 F7
236
      o print "456" at second line
237
        F0 00 00 7E 40 08 01 00 01 34 35 36 F7
238
      o add "7"
239
        F0 00 00 7E 40 08 02 37 F7
240
 
241
 
242
The Debug command (0D)
243
~~~~~~~~~~~~~~~~~~~~~~
244
 
245
   Structure:
246
      F0 00 00 7E 40 <device-id> 0D <debug-command> <au> <ah> <al> <wh> <wl> <mp1h> <mp1l> <mp2h> <mp2l> <mp3h> <mp3l> F7
247
 
248
      <device-id>:     the MIOS device ID from 00 to 7F
249
      <debug-command>: see below
250
      <au>:   (address >> 14) & 0x7f
251
      <ah>:   (address >>  7) & 0x7f
252
      <al>:   (address >>  0) & 0x7f
253
      <wh>:   (WREG >> 4) & 0x0f
254
      <wl>:   (WREG     ) & 0x0f
255
      <mp1h>: (MIOS_PARAMETER1 >> 4) & 0x0f
256
      <mp1l>: (MIOS_PARAMETER1     ) & 0x0f
257
      <mp2h>: (MIOS_PARAMETER2 >> 4) & 0x0f
258
      <mp2l>: (MIOS_PARAMETER2     ) & 0x0f
259
      <mp3h>: (MIOS_PARAMETER3 >> 4) & 0x0f
260
      <mp3l>: (MIOS_PARAMETER3     ) & 0x0f
261
 
262
 
263
   <debug-command> == 01:
264
      call a function
265
      Address of function in <au>-<al>;
266
      WREG and MIOS_PARAMETERx in the following bytes
267
      Returns the (changed) parameters:
268
         F0 00 00 7E 40 <device-id> 0F <wh> <wl> <mp1h> <mp1l> <mp2h> <mp2l> <mp3h> <mp3l> F7
269
 
270
   <debug-command> == 02:
271
      read from SRAM
272
      SRAM address in <ah>-<al> (0x000-0x5ff)
273
      counter in <wh><wl> (high-byte) and <mp1h><mp1l> (low-byte)
274
      Returns the SRAM dump:
275
         F0 00 00 7E 40 <device-id> 0F <byte0_h> <byte0_l>, ... <byten_h> <byte0_l> F7
276
 
277
   <debug-command> == 03:
278
      write to SRAM
279
      SRAM address in <ah>-<al> (0x000-0x5ff)
280
      write value in <wh><wl> (only one value can be written)
281
      Returns an empty acknowledge:
282
         F0 00 00 7E 40 <device-id> 0F F7
283
 
284
 
285
   Examples: use mkdbg.pl !!!
286
 
287
 
288
The Error Codes (0E)
289
~~~~~~~~~~~~~~~~~~~~
290
 
291
   Structure:
292
      F0 00 00 7E 40 <device-id> 0E <error code> <additional information> F7
293
 
294
      <device-id>:  the MIOS device ID from 00 to 7F
295
      <error code>: see below
296
      <additional information>: for internal use, ignore it
297
 
298
 
299
   Error Code | Description
300
   -----------+---------------------------------------------------------------
301
    0x01      | Less bytes than expected have been received
302
    0x02      | More bytes than expected have been received
303
    0x03      | Checksum mismatch
304
    0x04      | Write failed (verify error or invalid address)
305
    0x05      | Write access failed (invalid address range) -
306
              | used by 1st level bsl
307
    0x06      | MIDI Time Out
308
    0x07      | Wrong Debug Command
309
    0x08      | 2nd level bsl: Read/Write command tried to access an invalid
310
              | address range
311
    0x09      | 2nd level bsl: Read/Write address not correctly aligned
312
    0x0a      | BankStick not available
984 tk 313
    0x0b      | MIDI IN Overrun (CPU load too high)
314
    0x0c      | MIDI IN Frame Error (Bad signal/Optocoupler)
47 tk 315
 
316
 
317
Thorsten.Klose@midibox.org