Subversion Repositories svn.mios

Rev

Rev 53 | View as "text/plain" | Blame | Compare with Previous | Last modification | View Log | RSS feed

$Id: mios_sysex_implementation.txt 984 2011-04-17 20:23:22Z tk $

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 bootloader only supports command 02

   o the first level bootloader doesn't allow to overwrite
     the bootloader range (0x0000-0x03ff)

   o the second level bootstrap loader supports all commands, but
     doesn't allow to overwrite the MIOS and Bootloader
     address range (0x0000-0x2fff)


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
    0x0b      | MIDI IN Overrun (CPU load too high)
    0x0c      | MIDI IN Frame Error (Bad signal/Optocoupler)


Thorsten.Klose@midibox.org