MIOS SysEx Implementation

=========================





Following Commands are available

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



   a) Command X1 

      read from internal Flash, internal EEPROM, external BankStick

      (X = 0...7 - address extension)



   b) Command X2

      write to internal Flash, internal EEPROM, external BankStick

      (X = 0...7 - address extension)



   c) Command 03

      select BankStick before read/write



   d) Command 08

      print a message on LCD



   e) Command 0D

      debug interface





Important Notes

~~~~~~~~~~~~~~~



   o the maximum number of bytes which can be written at once is 1024 (1k)

     If more data has to be written, use multiple SysEx blocks and insert

     a delay of 750 mS between every block

     The hex2syx.pl script takes this already into account

     See also http://www.ucapps.de, Concepts->MIOS->Bootstrap Loader



   o if more than 1024 bytes are requested by the read command, MIOS

     will send multiple blocks and insert a delay between every block



   o internal flash and external BankStick addresses must be aligned

     to 64 bytes (0x40)



   o if data should be written into or read from a BankStick, use 

     the "03" command first to select the bankstick, thereafter the

     read/write command

     The hex2syx.pl script takes this already into account



   o every command except for 08 returns a acknowledge or disacknowledge

     code which is documented below



   o with command 01, 02 and 03 all user tasks will be suspended by

     MIOS to avoid interferences with the user program.

     MIOS will reset the core when no additional command has been

     received after 2 seconds



   o the first level bootstrap loader only supports command 02



   o the first level bootstrap loader doesn't allow to overwrite

     the bootstrap loader range (0x7c00-0x7fff)



   o the second level bootstrap loader supports all commands, but

     doesn't allow to overwrite the MIOS address range (0x0000-0x2fff)

     and the bootstrap loader range (0x7c00-0x7fff)





The Read command (X1)

~~~~~~~~~~~~~~~~~~~~~



   Structure:

      F0 00 00 7E 40 <device-id> <au>1 <ah> <al> <ch> <cl> F7



      <device-id>: the MIOS device ID from 00 to 7F

      <au>: 3-bit address extension

      <ah>: 14-bit address, high byte

      <al>: 14-bit address, low byte

      <ch>: 14-bit counter, high byte

      <cl>: 14-bit counter, low byte



      The resulting PIC address is derived from the 14-bit address

      with following formula:



         ah = (address >> 10) & 0x7f

         al = (address >>  3) & 0x7f

         address = (ah << 10) | (al << 3)

         ch = (counter >> 10) & 0x7f

         cl = (counter >>  3) & 0x7f

         counter = (ch << 10) | (cl << 3)



      when address >= 0x00000 and address <= 0x07fff:

         -> Internal Flash selected, offset 0x0000-0x7fff

      when address >= 0x08000 and address <= 0x0ffff:

         -> Internal EEPROM selected, offset 0x0000-0x00ff

            (64k devices: 0x0000-0x03ff)

      when address >= 0x08100 and address <= 0x0ffff:

         -> Invalid address range (reserved)

      when address >= 0x10000 and address <= 0x1ffff:

         -> External BankStick selected, offset 0x0000-0xffff

      when address >= 0x28000 and address <= 0x2ffff:

         -> Internal Flash selected, offset 0x8000-0xffff

            (64k devices only!)



      The address extension <au> selects the BankStick number



   Examples:



      o read the whole internal flash

        F0 00 00 7E 40 00 01 00 00 10 00 F7

      o read the whole internal EEPROM

        F0 00 00 7E 40 00 01 20 00 00 20 F7

      o select BankStick #0, read the whole 32k BankStick memory (24LC256)

        F0 00 00 7E 40 00 01 40 00 20 00 F7

      o select BankStick #0, read the whole 64k BankStick memory (24LC512)

        F0 00 00 7E 40 00 01 40 00 40 00 F7



   The returned SysEx blocks can be written back into the core/BankStick.

   In this way it is possible to create backups or to clone the content

   from one to another MIOS core.



   It's also possible to edit the returned content by using the

   syx2asm.pl script (see the bs_xfer example which contains a

   step-by-step guide)





The Write command (X2)

~~~~~~~~~~~~~~~~~~~~~~



   Structure:

      F0 00 00 7E 40 <device-id> <au>2 <ah> <al> <ch> <cl> <dump> <checksum> F7



      <device-id>: the MIOS device ID from 00 to 7F

      <au>: 3-bit address extension

      <ah>: 14-bit address, high byte

      <al>: 14-bit address, low byte

      <ch>: 14-bit counter, high byte

      <cl>: 14-bit counter, low byte

      <dump>: the data which will be uploaded, scrambled in 7-bit format

              see the hex2syx.pl and syx2asm.pl scripts for further details

      <checksum>: inverted checksum from <ah> to the last byte of <dump>



      The resulting PIC address is derived from the 14-bit address

      with following formula:



         ah = (address >> 10) & 0x7f

         al = (address >>  3) & 0x7f

         address = (ah << 10) | (al << 3)

         ch = (counter >> 10) & 0x7f

         cl = (counter >>  3) & 0x7f

         counter = (ch << 10) | (cl << 3)



      when address >= 0x00000 and address <= 0x07fff:

         -> Internal Flash selected, offset 0x0000-0x7fff

      when address >= 0x08000 and address <= 0x0ffff:

         -> Internal EEPROM selected, offset 0x0000-0x00ff

            (64k devices: 0x0000-0x03ff)

      when address >= 0x08100 and address <= 0x0ffff:

         -> Invalid address range (reserved)

      when address >= 0x10000 and address <= 0x1ffff:

         -> External BankStick selected, offset 0x0000-0xffff

      when address >= 0x28000 and address <= 0x2ffff:

         -> Internal Flash selected, offset 0x8000-0xffff

            (64k devices only!)



      The address extension <au> selects the BankStick number



   Examples: use hex2syx.pl or MIOS Studio!!!





The Select BankStick command (03)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



   Structure:

      F0 00 00 7E 40 <device-id> 03 <bs-number> F7



      <device-id>: the MIOS device ID from 00 to 7F

      <bs-number>: the BankStick number from 0 to 7



   This command was used in previous MIOS versions (<V1.8) to

   select the BankStick before writing or reading.



   !!! THIS COMMAND IS OBSOLETE !!!



   The BankStick is now selected with the address extension

   of the Read/Write command.





The LCD message command (08)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~



   Structure:

      F0 00 00 7E 40 <device-id> 08 <lcd-command> <data> F7



      <device-id>:   the MIOS device ID from 00 to 7F

      <lcd-command>: see below

      <data>:        depends on the command, see below





   <lcd-command> == 00:

      Clears the LCD, starts a message (display will not be

      updated for the next 2 seconds). 

      The <data> field is optional, it contains additional

      characters which are print immediately from position 0/0



   <lcd-command> == 01:

      Sets the cursor and starts a message (display will not be

      updated for the next 2 seconds). 

      <data>:

         - first byte: cursor X position (0x00-0x7f)

         - second byte: cursor Y position (0x00-0x7f)

         - following bytes: optional, contains additional 

           characters which will be print immediately from

           the new cursor position



   <lcd-command> == 02:

      Starts a message (display will not be updated for the 

      next 2 seconds).

      <data>: contains characters which will be print immediately

      from the current cursor position



   <lcd-command> == 03:

      Stops a message immediately, the USER_DISPLAY_Init routine will be

      invoked which reinitializes the LCD screen



   Note: every command will cause that the USER_DISPLAY_Init routine

   will be invoked within 2 seconds after the last LCD command

   has been received



   Note2: these commands are also used by MIOS itself when

   display type #06 has been selected



   Note3: these commands are also received by MBHP_TV



   Examples:



      o clear screen and print "123" for 2 seconds

        F0 00 00 7E 40 08 00 31 32 33 F7

      o print "456" at second line

        F0 00 00 7E 40 08 01 00 01 34 35 36 F7

      o add "7"

        F0 00 00 7E 40 08 02 37 F7





The Debug command (0D)

~~~~~~~~~~~~~~~~~~~~~~



   Structure:

      F0 00 00 7E 40 <device-id> 0D <debug-command> <au> <ah> <al> <wh> <wl> <mp1h> <mp1l> <mp2h> <mp2l> <mp3h> <mp3l> F7



      <device-id>:     the MIOS device ID from 00 to 7F

      <debug-command>: see below

      <au>:   (address >> 14) & 0x7f

      <ah>:   (address >>  7) & 0x7f

      <al>:   (address >>  0) & 0x7f

      <wh>:   (WREG >> 4) & 0x0f

      <wl>:   (WREG     ) & 0x0f

      <mp1h>: (MIOS_PARAMETER1 >> 4) & 0x0f

      <mp1l>: (MIOS_PARAMETER1     ) & 0x0f

      <mp2h>: (MIOS_PARAMETER2 >> 4) & 0x0f

      <mp2l>: (MIOS_PARAMETER2     ) & 0x0f

      <mp3h>: (MIOS_PARAMETER3 >> 4) & 0x0f

      <mp3l>: (MIOS_PARAMETER3     ) & 0x0f





   <debug-command> == 01:

      call a function 

      Address of function in <au>-<al>; 

      WREG and MIOS_PARAMETERx in the following bytes

      Returns the (changed) parameters:

         F0 00 00 7E 40 <device-id> 0F <wh> <wl> <mp1h> <mp1l> <mp2h> <mp2l> <mp3h> <mp3l> F7



   <debug-command> == 02:

      read from SRAM

      SRAM address in <ah>-<al> (0x000-0x5ff)

      counter in <wh><wl> (high-byte) and <mp1h><mp1l> (low-byte)

      Returns the SRAM dump:

         F0 00 00 7E 40 <device-id> 0F <byte0_h> <byte0_l>, ... <byten_h> <byte0_l> F7



   <debug-command> == 03:

      write to SRAM

      SRAM address in <ah>-<al> (0x000-0x5ff)

      write value in <wh><wl> (only one value can be written)

      Returns an empty acknowledge:

         F0 00 00 7E 40 <device-id> 0F F7





   Examples: use mkdbg.pl !!!





The Error Codes (0E)

~~~~~~~~~~~~~~~~~~~~



   Structure:

      F0 00 00 7E 40 <device-id> 0E <error code> <additional information> F7



      <device-id>:  the MIOS device ID from 00 to 7F

      <error code>: see below

      <additional information>: for internal use, ignore it





   Error Code | Description

   -----------+---------------------------------------------------------------

    0x01      | Less bytes than expected have been received

    0x02      | More bytes than expected have been received

    0x03      | Checksum mismatch

    0x04      | Write failed (verify error or invalid address)

    0x05      | Write access failed (invalid address range) - 

              | used by 1st level bsl

    0x06      | MIDI Time Out

    0x07      | Wrong Debug Command

    0x08      | 2nd level bsl: Read/Write command tried to access an invalid 

              | address range

    0x09      | 2nd level bsl: Read/Write address not correctly aligned

    0x0a      | BankStick not available





Thorsten.Klose@midibox.org