#139 Special Command Proposal

[Jan Belohoubek]

Dear stm32flash community,
At UWB (https://github.com/SmartCAMPUSZCU) we currently work on a tiny bootloader with basic security features, which we decided to be protocol-compatible with STM32 bootloader protocol (and tools).

The bootloader itself will be soon open-sourced in the KETCube project framework.

We choose stm32flash as our primary/reference tool, as it allows the required customization and I already submitted a few patches to this project, so we have a little experience with the codebase in our team.

We have a public fork repository of stm32flash for rapid prototyping (currently here https://github.com/belohoub/stm32flash), but I would like to push any fixes meaningful for upstream back to this project - if you find them useful and generic enough.

Currently, we added the implementation of the STMs' "Special Command" (required for our bootloaders' security features). The specialCMD branch now contains only changes related to the introduced command and it sits on top of the main stm32flash repository (currently, it should be simple to merge).

If you want to include the proposed command in upstream, I would like to consult several topics here to limit divergent development in the early phase:

1) We proposed new cmd line switches -x and -X for special and extended special commands (extended version is not implemented yet - and we do not need it at all - but it makes sense to reserve this kind of switch for the future)
2) -x and -X switches are followed by opcode encoded as HEX string and one (special command) or two (extended special command) optional parameters encoded as HEX strings
3) We think, that it could be advantageous to allow passing parameters in binary e.g. through Unix pipe (|) - then the parameters after -x or -X switch contain opcode and parameter lengths

The proposed structure of special command with inline parameters (already implemented):

./stm32flash -x 0000:4F4B21 /dev/ttyS0

where 0000 is special command opcode (HEX), 4F4B21 is a parameter (HEX, the parameter must be up to 128B)

The proposed structure of special command taking bytes from stdin (not implemented):

echo -n -e '\x4f\x4b\x21' | ./stm32flash -x 0000:&3 /dev/ttyS0

where 0000 is special command opcode (HEX), and &3 is parameter length (3 in DEC) is bytes (parameter must be up to 128B)

Special command returns status and data (both up to 128 bytes). Currently, we only propose return as parsable HEX string to stdout, but binary in good form could be advantageous.

Extended special command controls are proposed to be analogous, but it is not implemented at al.

Our current bootloader (not open-sourced yet) currently implements a "Hello World" command (opcode 0) accepting one parameter and returning the "Hello World!" string in response data "packet" and up to 10 bytes of command parameter in the status "packet". The complete output of extended stm32flash talking to our bootloader looks as follows:

$ ./stm32flash -x 0000:4F4B21 /dev/ttyUSB0 
stm32flash 0.6

http://stm32flash.sourceforge.net/

Interface serial_posix: 57600 8E1
Version      : 0x01
Option 1     : 0x00
Option 2     : 0x00
Device ID    : 0x0447 (STM32L07xxx/08xxx)
- RAM        : Up to 20KiB  (8192b reserved by bootloader)
- Flash      : Up to 192KiB (size first sector: 32x128)
- Option RAM : 32b
- System RAM : 8KiB
Executing special command
Opcode: 0x0000
Parameter: 0x4F4B21
RxData ASCII: Hello World!
RxData HEX: 0x48656C6C6F20576F726C6421
Status ASCII: OK!
Status HEX: 0x4F4B21
Done.

It would be great to include special command (and alternatively extended special) into upstream stm32flash. We can change almost everything in our proposal to better fit the project needs, to increase the generality, or to increase consistency of new code/interface with the rest of the stm32flash tool; we only need a generic tool for sending/receiving single special commands usable by automation scripts - with parametrized input and parsable output.

If you find some time, please review our proposal and/or code proposal on GitHub. I'm ready to discuss any changes.

Thank you!

[Jan Belohoubek]

In the GitHub repository, we also added the timeout option (usable for complex special commands, e.g. tests):

-t timeout Timeout in seconds (default 5s; currently applies on special command only)

[Tormod Volden]

I think this looks interesting. I have noticed there are special commands available on some bootloaders.

I wonder about the possibility of staying with one option for this. There is already another suggestion for use of a -t timeout option (ticket #131). Generally people love adding options and it would be a mess if the maintainers wouldn't fight against it :) Would it be possible to detect two parameters and then automatically treat is as extended special command, instead of yet another option -X? E.g. -x 0007:4F4B21:CAFECAFE ? And could the timeout also be included, similar to the &length modifier, e.g. an ~timeout modifier -x 0007:4F4B21:~5

BTW, can the unquoted & cause issues in some shells or is it safe? It is not a problem though, we already use the & character in the -i option.

[Jan Belohoubek]

I'll modify as you suggests and I'll let you know.

I understand your reasons. I think, that it would be practical to have a self-holding command instead new option(s).

I would say, that ~ should not populate as USER_HOME in most shells if it is part of string, but I would rather prefer something like "+".

Is it OK if I'll push to our fork and let merging up to you? (I'll let you know here.)

PS: we were delayed for some reason, but our open-source bootloader (protocol-compatible with STM bootloader) will be released soon - I expect, that within a month. Currently we already have internal builds with almost all features :-).

[Jan Belohoubek]

Dear Tormod,
I just merged all options according my previous comment and you can find the result here: https://github.com/belohoub/stm32flash

Extended special command is still not (yet) implemented.

I used our (still in-house) bootloader tests to test for regressions - all passed, so I guess, that it things should be OK :-)