Compatibility of firmware upgrade with any Teensy board

[image-et-son]

The firmware upgrade currently only works for original PJRC Teensy boards. There are copycat versions of the Teensy++ 2.0 board on the market but the firmware code is not compatible. This discussion is about putting the knowledge together to understand the incompatibility and ideally to make changes / variants of the firmware or to develop changes to Teensy++ 2.0 boards so the firmware can be used with any board.

Some basic information from the firmware code and the Teensy++ 2.0 features:

• The compatibility question is likely to be related to the bootloader software and the so-called self-programming mode (SPM)
• The development by GliGli uses only the original PJRC boards which come with a bespoke bootloader software called HalfKay
• Typically a bootloader (and the SPM) is used to re-program, e.g. having a software which starts in an update mode and which can (using SPM) send program code to the memory. However, in the GliGli firmware the SPM is also used to "abuse" the memory as a permanent storage place, e.g. for patch data, settings and sequencer data. To do so, a so-called bootloader hack is employed. NB: the firmware update via SysEx also uses this function.
• The GilGi firmware upgrade uses the normal PJRC bootloader
• The memory of the processor is divided into two sections: RWW (read-while-write) and a NRWW (non-read-while-write). The basic idea is that any self-programming functions reside inside the NRWW where it is prevented that code is read while is it written. The details of bootloader and memory sections are described in the ATMEL AT90USB64/128 documentation in chapter 28, here: https://www.pjrc.com/teensy/at90usb1286.pdf
• The relevant firmware code is located in the code files p600firmware.c and teensy_bootloader_hack.h.
• The NRWW section itself is divided into the actual bootloader section and a second section which can be used by app code. The split of the NRWW section can be customized. In Teensy++ 2.0 the NRWW starts at address 0x1e000
• Apparently SPM can be activated by the bootloader only. The firmware therefore calls a routine inside the bootloader directly which invokes SPM before reading/writing pages is done. Apparently the routine call to the bootloader can be only be done from NRWW. Ghis is why critical functions of the firmware are configured to reside in the NRWW, concretely: program_page() and functions used for firmware upgrade via SysEx. program_page() is then not only used for firmware updates but also for storage.
• It is essential that the program_page() function resides in the NRWW. The Makefile specifies the section .bootloader at 0x1f000 for the memory location of the function. The bootloader on the board must support this.
• program_page() itself uses overwrites of the page_fill, page_erase and page_write functions provided in avr/boot.h in which the normal call "rcall Do_spm" (which apparently would not be allowed outside the boot section) is replaced by the hack: a direct call of a routine inside the bootloader, concretely: rcall .bootloader+0xe4a. This address has a "rcall Do_spm" followed by unknown (but apparently harmless) code before the next return command. The address offset 0xe4a was found by trial and error.

[image-et-son]

Further info:

• in the Teensy++ 2.0 setup the bootloader code jump address (byte address) is 0x1FC00 (see https://www.pjrc.com/teensy/jump_to_bootloader.html) - apparently, the split of the NRWW (which starts at 0x1E000) is such that the bootloader section has 4 pages (=4 x 256 bytes) only (this is not the ATMEL shipping default) and starts at byte address 0x1FC00
• Since the page handling code of the firmware is placed at 0x1FC00 this gives 0x1FC00 - 0x1F000 = 3072 bytes (or 12 pages) for that code (because it must not overwrite the bootloader)
• The jump address of the bootloader hack is 0x1F000 + 0xe4a = 0x1FE4A. Which is 586 bytes into the bootloader code.
• GliGli tried different jump addresses in a probing code that wrote a single page and then checked if anything was written to flash in order to find the offset 0x1FE4A. Note that it is only required that this address contained an SPM call, so there is likely to be more than one choice since SPM is liekly to be used multiple times inside the bootloader code.
• Questions from here: since we don't know which bootloader copycat boards use, it is even no clear if they also use the setup with 4 pages for the BLS. However, if they'd use a BLS of 8 pages it might still work. If they use 16 or the full NRWW size of 32 pages, then the firmware would overwrite the bootloader. Still 4 or 8 pages are possible.

[image-et-son]

Current working plan:

1. Get basic code for USB logging working on Teensy++ 2.0 (https://www.pjrc.com/teensy/usb_debug_only.html)
2. Copy bootloader hack into that code (erase, fill, write page)
3. Write a main() which cycles through bootloader addresses, uses that to hack-write a page and the checks if that page was really written
4. Log success address to USB out

Currently I am stuck on 1) because the USB logging code doesn't compile to a working hex using my avr-gcc 11.1. I am working on creating a virtual platform which supports a lower version of avr-gcc. M12x proved that it works for avr-gcc 9.3.

[GrantMTG]

Hi. I don't have experience with GitHub so apologies if I do this wrong. The following is probably well known, but I wanted to understand the .SYX file format currently in use. It appears to be a variation on the Mutable Instruments format. This is a good choice. MI have a great repository of work that is well regarded in the community.

Regarding the current Teensy2pp PJRC HalfKay USB bootloader (that's a mouthful), I suspect that he (Paul/PJRC) is ignoring the CRC (in the interest of making a very small bootloader). Considering the connection is hardwired during upload I think this is an acceptable choice. Do we need to increase the size of the bootloader? Hard to say so far, and there may be limited boundaries that can be assigned to bootloader space as defined by Atmel. Clearly I don't know much about AVR at this point either.

One thing I noticed when comparing the .HEX versus the .SYX is that the .HEX carries content in the second 64K of the Atmel MCU. Am I mistaken? What are the elements that the .HEX firmware transfer that the .SYX does not?

Here are further Mutable Instruments links regarding their AVR MIDI bootloader (MI has since moved on to STM32 parts as far as I know). I think the MI AVR toolchain is similar to what you guys are using for the P600.

https://github.com/pichenettes/avr-midi-bootloader/blob/master/bootloader/bootloader.c

https://github.com/pichenettes/shruthi-1/blob/master/bootloader/bootloader.cc

I have been looking at solutions for physically replacing the Teensy2pp HalfKay USB Bootloader (using an ICSP/ICE) and have pondered whether or not we could write an interim application that can be downloaded using HalfKay (USB) or MIDI (SYX) and this interim application would rewrite the bootloader with the new one.

[image-et-son]

Hi, yes the firmware syx structure is correct. I am working on a technical documentation and it is explained there too. It just isn't finished yet. This graphical representation is very intuitive though.

I think there is some misunderstanding: the bootloader knows nothing of MIDI and SysEx. Instead it is part of the firmware which converts MIDI input into hex and copies it page by page to the flash. It is application code which has nothing to do with the HalfKay bootloader. And: it is exactly that code (and all functions needed for this incl. the said bootloader hack) that is placed beyond 64K of the MCU! The reason is that this is the so called NRWW. The code for the bootloader hack needs to be in the NRWW and this section can replace itself in the process.

I'll look into the MI stuff. Sounds interesting.

[GrantMTG]

OK, thanks for the info. Feel free to correct my errors in understanding. Sorry for trouble. Looking forward to the technical document. :-)

Out of curiosity, do we know who, if anyone, owns the MIDI ID that is being used? 00h 61h (Micros 'N MIDI ??)

It is my understanding that the Teensy loader program (Teensy.exe) can be used to transfter a .HEX file to the Teensy2pp board via communications over USB HID using the HalfKay bootloader resident in the MCU on the Teensy2pp board. The hex file in our case being the P600fw. (Of course this requires having the P600 open or else a USB extension cable must be used.) I don't know yet what is involved in order for the P600fw itself to download a new .SYX P600fw application (but if we write a new bootloader, maybe we can eliminate that).

As you mentioned before the application (P600) lives at 0x00000 and the bootloader lives at 0x1FC00 if memory serves. Hopefully your technical document maps out the other storage elements "up there". It looks like there is lots of empty space between P600fw end at about 0x0C4BD and the bootloader begin at 0x1FC00, but I don't know how much space is devoted to P600fw variable/parameter storage. The HEX file has content at 0x1E000-0x1E5E7, 0x1Ec00-0x1ED38 and 0x1F000-0x1F093.

Also, I don't think there is any magic line at 64k. The MCU naturally accesses 128k since the Program Counter addresses 64k 16-bit words, not bytes. There are user definable lines for the end-of-application/start-of-bootloader and end-of-RWW/start-of-NRWW.

[GrantMTG]

I think there is some misunderstanding: the bootloader knows nothing of MIDI and SysEx. 

To clarify, the bootloader does not have to be USB and even if it was, there is no reason it has to be USB HID. If the bootloader were to support USB-MIDI then even a browser could be used to do the update (web midi). If the bootloader used the 6850 then it could be 5-pin DIN MIDI. In this case once the bootloader is replaced, then no one ever needs to open the P600 up. PRJC simply chose chose USB HID because it served his wide client base of non-music people. Just food for thought, USB HID is OK too.

Finally, the AT90USB has a built-in UART but it's probably not practical to replace the 6850 with this (two more wires need to be adapted/jumpered).

[image-et-son]

Ah, OK, true, it is possible to write a bootloader that uses MIDI as input. In the case of the P600 this would have to be specific for the hardware (I don't think there's anything generic or canonical about it). If I take the experience from failures to upgrade the firmware via MIDI SysEx (1 out 10, maybe) I very much value the far more robust USB hex to flash "fallback" which HalfKay provides. Unless, of course, an equally robust bootloader via the DIN MIDI and UART can be programmed. Sounds like quite a challenge, though. I haven't done anything like it before.

[GrantMTG]

Yeah, the P600 bootloader would have to use the same 6850 UART code as the P600 keyboard fw. It's only a few lines of code though. I assume there some kind of UART/MIDI buffer or queue in the existing p600fw code as well. The code would be smaller than the USB "stack". A MIDI UART bootloader only really needs to deal with Sys Ex too, so I don't know that it would merit that whole xnormidi thing. It's just a small state machine. So theoretically one could delete the USB stack and xnormidi. Or not, depending on the comfort level. :-)

Compared to what you have been doing I don't think this is more difficult. Just different. The advantage of the existing PJRC method is that the software (protocol) has some built-in considerations for speed/connection and the PC host side software is supplied by the board vendor so Paul knows what the best behaviour for the Teensy Loader should be.

The flash update process is something like: send a block of data, erase that block, burn that block. I think the AT90USB flash blocks are 256 bytes, but that's from memory. It may be better to do one bulk erase rather than several, but this affects MCU busy time (one long erase wait versus many shorter ones). It takes a fairly long time to erase or burn a block so the protocol either calls out "Delay after F7" and/or must wait for an ACK/NAK sys ex response from the P600 after each block. The former is implemented by MIDI-OX as seen here:

Delay after F7 example: http://www.moogmusic.de/midiox.jpg

An ACK sys ex response could just be something like:
F0 MANUFACT_ID DEVICE_ID CMD# 'A' F7

If people are just doing blind dumps with existing software then specifying "Delay after F7" is important and pretty common. If someone is writing a PC application from scratch then it would be better to wait for the ACK. Bidirectional communication means you know if the device is attached and you know when each transaction is done.

Another thing that would be a great idea is to brick-proof the bootloader. The easiest way to do this is, assuming the hardware can support it, "if a-certain-p600-panel-button is pressed at startup, then run the bootloader". You guys have had excitement with the membranes, so that might need to be considered.

I think a "ping" command/response should be added to the current P600fw as soon as possible. Some kind of version info can be returned if the P600 receives a MIDI Universal Device Inquiry request (for example). It doesn't have to be that, but some incoming MIDI command triggers a MIDI response (preferably with version info).

Finally, a nice feature would be to have a sys ex or other command that can launch the bootloader. That way a new PC application can request the bootloader, check to see if it's active, send the firmware update and reboot without the user touching the P600. This requires the bootloader also respond to the MIDI Universal Device Inquiry. Hopefully the AT90USB supports this (launch bootloader from app), but I don't know.

Now having said all that, there's nothing stopping us from doing the same basic thing over USB HID or whatever. Once the existing bootloader is replaced then also the Teensy Loader needs to be replaced. I've done raw USB HID stuff on Ubuntu linux using libusb and it's my understanding that one can do the same thing on Windows. My Windows code came first so I just used Win32 for that. I was not aware of libusb until years later. Does Mac have libusb? I'm guessing it must. Anyway, Paul shows some techniques for USB HID here:

https://github.com/PaulStoffregen/teensy_loader_cli/blob/master/teensy_loader_cli.c

[GrantMTG]

Instant Gratification:

Well here is one path that seems easy, at the beginning at least:

• Install Atmel Studio 7
• Install LUFA
• Select a LUFA example such as DFU Bootloader.
• Build ... done!

There are a LOT of example projects included with LUFA so it will take some digging to see if there is anything suitable. This thing covers just about every possible angle though (MIDI, USB, UART, bootloaders, devices, ...). It's not a small bootloader though. I think 4k is the best one could hope for.

Software:
https://gallery.microchip.com/packages/FourWalledCubicle.LUFA.0e160d5c-e331-48d9-850b-e0387912171b/17.4.18.170418

Documentation:
https://w0.dk/~chlor/lufa/Bootloaders/DFU/Documentation/html/index.html

I have used the CLI "dfu-programmer" on Windows before so I can see if anything is usable for the AT90USB162 I have at the moment. I'm not sure that part is supported.

The API seems decent enough, but there will be a learning curve:
https://w0.dk/~chlor/lufa/Bootloaders/DFU/Documentation/html/index.html#Sec_API

Example:

    void BootloaderAPI_WritePage(const uint32_t Address)
    {
    boot_page_write_safe(Address);
    boot_spm_busy_wait();
    boot_rww_enable();
    }

[GrantMTG]

Update on minor tests. This is all stuff that AVR fans have been doing for 10 years I imagine, but it's all Greek to me.

I was able to use the Waveshare ICE that I got on Amazon (and I'm very impressed with the whole kit) to wipe the fake Teensy loader off of the Teensy Clone I got and instead install the Atmel factory "DFU" (at90usb1287-dfu-1_0_1.hex). I used Atmel Studio 7 to do the procedure, but probably AVRDude might be more interesting to you guys. I put DFU in quotes because from what I read, Atmel kind of bastardized the industry standard DFU protocol, but that's not terribly important to us.

This loader would also accept the files "blink_fast_Teensy2pp.hex" and "blink_slow_Teensy2pp.hex". For this I used the command line Windows DFU application dfu-programmer.exe. (https://github.com/dfu-programmer/dfu-programmer) As an aside, there is also a command line Teensy Loader from PJRC if anyone wants to play with that. It's on the PJRC site. I'm not sure how the Atmel DFU got it's driver associated on Windows. I've installed a lot of AVR things in the last few days and for me it was plug-n-play.

Next steps will be to evaluate if I can build a LUFA HID and/or DFU bootloader in the Atmel Studio 7 environment and see if it boots. Then to figure out if there is already some software for the actual application loading. Recall that LUFA already has a documented method for a running application to program flash. Then of course, what are the effects of that on P600fw. Curiously, LUFA has some MIDI support but I'm guessing that's for over USB.

[GrantMTG]

Using the files found here ( http://blog.lincomatic.com/?p=548 ), I was able to load the (LUFA) DFU_Bootloader into the Teensy clone, and again it in turn loaded the demo blink programs using dfu_programmer.exe. One notable difference between this LUFA DFU file and the alleged factory one (at90usb1287-dfu-1_0_1.hex) was the size for the fuses. This one required "4K bytes (2K words) of space".

I don't know what vintage this DFU firmware version is compared to latest and I have yet to investigate the jump tables for hooking into flash programming (versus Teensy).

[GrantMTG]

Oh, one important thing, you can't actually debug with an Atmel AVRISP mkii. You need the "ICE" level debuggers for that. This bugs me to no end. You can get professional debugging from other chip vendors for quite cheap compared the Atmel/Microchip. I'm not a fan of "printf" style debugging.