Where do I find ST-LINK/V2 host interface details

[Matt Wilson]

Posted on June 29, 2017 at 14:02

I am a Linux user (hobbyist), with ST-LINK/V2 connecting to various STM8S  devices. I can find details of the SWIM and DM interfaces on the device side (ST document UM0470), but cannot locate any details of the host side. I am not a C programmer, but I have looked at the code for STM8FLASH (on GitHib) and it shows that I need to know more about the host side interface of ST-LINK/V2. Any assistance greatly appreciated.

Background: The STM8s are running custom code. I want to use debug module to stall cpu so can inject data and change program counter before restarting cpu; lots of times. I'll probably hack something together using Python, just to see if my idea actually works at all. But I cannot find details of host side commands to ST-LINK/V2 on st.com. I figure what I want is probably there, but I am looking for the wrong thing!!

[martonmiklos]

Posted on July 05, 2017 at 08:21

It sounds like you are looking for this:

https://stm8-binutils-gdb.sourceforge.io/

 

[Matt Wilson]

Posted on July 05, 2017 at 10:23

Well that is another implementation that I haven't seen before. Thank you. There's several ST-LINK projects on GitHub (such as

https://github.com/texane/stlink

 ,

https://github.com/fpoussin/QStlink2

,

https://github.com/afaerber/stlink

 , 

https://github.com/pavelrevak/pystlink

). All these resources are implementations, so are subject to whatever scope the developer chooses. Some have good detail on SWIM, and others on DEBUG. It seems there is no ST reference at all. It just seems odd to me that a product can be produced that has a defined output interface but no defined input interface, but that seems to be the case for ST-LINK/V2. Basically, all the implementations are full of 'magic numbers' and a few examples of usages.

Just a couple of examples of unknowns are

• what does 0xF4 0x02 command actually return and what is it used for?
• What do the commands 0xF4 0x03 thru - 0xF4 0x08 actually achieve?
• Why does it take two commands to do a reset which is a single SWIM command?
• What is the magic in the long series of commands to initialise a 'session'?
• Which of the 'session' startup commands can cause a restart of the STM8 cpu? What parameter disables the restart?
• etc...etc...etc...

[martonmiklos]

Posted on July 06, 2017 at 14:34

What is your end goal? Debugging or programming?

What I know for sure that the OpenOCD developers got a header file at some point in the past from the ST:

https://sourceforge.net/p/openocd/mailman/message/35761273/

 

I do not think that full protocol description would be publicly available.

[Matt Wilson]

Posted on July 08, 2017 at 09:31

End goal is to be able to input data into memory a line at a time instead of serial byte at a time.

Background: I am running Forth on various STM8 chips - yep, the very littlest ones. The standard input to Forth is serial keyboard. I found document UM0470 describing the SWIM and DEBUG modules included in STM8 chips, and had the idea to use the SWIM pin for input instead of the normal serial using another GPIO. The Forth I am using actually has a routine to fill a line buffer with input, then evaluate that line of source code. So, it seemed an easy idea to set a breakpoint at the beginning of that routine, and use external program to dump a whole line of input in one go, then just restart CPU at the end of the routine. Also need to modify Y register with the actual length of source line before restarting. Keep doing this loop until no more source to be interpreted. Other than a bit of setting up and cleaning up, the core loop of this process is only a few lines long, if everything works.

I started with a program stm8flash available on GitHub (

https://github.com/vdudouyt/stm8flash

) which uses the SWIM commands into ST-LINK/V2. So , I started with the 0xF4 commands based on what was in that source code. All very cryptic, but just use it and hope that it all works. It didn't. As far as I can tell, so far, there are a few hiccups:

• Something I am doing is triggering a HALT interrupt.
• There's a long series of commands sent to ST-LINK/V2 for open and initialise. I know something caused an unwanted system reset, but it took me ages to stumble upon the discovery that it was a set of 2 commands! I've got no idea what the rest are for, so have no idea if their inclusion is cause of being unsuccessful.
• Attempting to use single step mode proved unsuccessful after a PC change. I have been unable to get CPU stalled at instruction immediately after the newly set PC (and yes, I flushed the decode buffer).
• Something is affecting the PC in unexpected ways when IRET and RET commands are executed in single step mode (and possibly in normal run mode, but I obviously cannot tell - except I don't get the output I expect).

Given your hint above, I got the latest copy of source code for OpenOCD. OpenOCD does not support STM8 at all, but it does have a well-structured ST-LINK interface. Interestingly, it uses DEBUG commands rather than SWIM commands. OK, so I can rework all the SWIM commands to DEBUG commands and see if STM8 can be made to work. Well, DEBUG_ENTER (F2 00) and GET_CURRENT_MODE (F5) got me into MASS mode (01) - not what was intended. So, tried DEBUG_APIV2_ENTER (F2 30 00) and ST-LINK hung. Even tried adding the SWD byte (F2 30 A3), but still hung. Here is a listing of the bytes in and out of ST-LINK/V2 for DEBUG_APIV1_ENTER and GET_CURRENT_MODE:

f2 20 00 00 00 00 00 00 00 00 00 00 00 00 00 00

 f5 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 02 00

Yoo Hoo! Got to DEBUG mode. But that is about it. Nothing else seems to work as expected.

Reading all registers (F2 04) gave back 84 bytes, but they are all rubbish. So tried just read as 8-bit (F2 0C 00 00 7F 90 00 0B), but ST-LINK/V2 refuses to reply. OK, try reading 32-bit on registers:

f2 07 00 00 7f 90 00 02 00 00 00 00 00 00 00 00

 77 77 77 77 77 77 00 00

Nope. I am running out of sticks to poke the ST-LINK/V2 into doing anything related to what I want.

It is tedious to just keep trying things, and my patience has really been tested. And it seemed such a simple idea to just push a whole source line in every time the breakpoint is reached. Any ideas about what I can try are very welcome.

P.S. <I do not think that full protocol description would be publicly available.> Well, it seems to me that using the interface into the STM8 SWIM and DEBUG hardware modules is unlikely to be directly accessed by a PC or even a custom hardware device, and that information is published by ST. But not the interface into the only ST product that does match the STM8 SWIM and DEBUG hardware modules. It is now obvious to me that it is a deliberate decision by ST to make it hard to use those hardware modules, but I cannot figure out why.

For my project, it is not worthwhile to create a replacement for the ST-LINK, but making such a replacement is a very achievable task. It is just software, after all is said and done. Whatever the input interface gets to be is simply a matter of publishing it and it will get used (well, if it is half-decent and works), at least by the open source community.

[martonmiklos]

Posted on July 10, 2017 at 08:47

I got the latest copy of source code for OpenOCD. OpenOCD does not support STM8 at all, but it does have a well-structured ST-LINK interface.

There is a pending patch for the STM8 support (thanks to Ake Rehnman):

http://openocd.zylin.com/♯/c/3953/

 

http://openocd.zylin.com/♯/c/3952/

 

https://sourceforge.net/projects/stm8-binutils-gdb/files/stm8-binutils-gdb-sources-2017-05-25.tar.gz/download

 

I have got this OpenOCD working with STM8S003, so it is indeed capable of writing memory through SWIM.

I do not think that full protocol description would be publicly available

Let me rephrase that: I do not think that the STLink USB protocol document would be publicly available.

[Matt Wilson]

Posted on July 24, 2017 at 10:28

Well, you are correct that Ake Rehnman has done a great job of implementing the SWIM interface for STM8. He has corrected and updated code from two earlier sources (by patching the OpenOCD code, which is based on code by texane on GitHub - which is the one I had seen earlier - and found to be deficient for my purposes). I just wonder how each successive author gets the necessary information to do such work. I am not so good at guessing or probing as these guys.

I haven't been through Ake's code in fine detail, but I think all the information I need is there. So, I thank you for the lead. I'll go back and try to put my little project together now. If it works, it'll be on GitHub.

[ake]

Posted on November 05, 2017 at 09:25

Let me rephrase that: I do not think that the STLink USB protocol document would be publicly available.

If someone

eventually read this thread. I have as Marton mentions been working on the stm8 back end for gdb which also required some heavy work on OpenOCD as well.

I do not know why ST keeps the st-link usb protocol secret. Not only are ST referring to OpenOCD on their

http://www.st.com/content/st_com/en/about/media-center/press-item.html/p3781.html

so basically you (ST) kind of supports the project but also benefit from people using our (open source community) hard work. Why not just release the documents for the USB protocol? That would enable us to write better software instead of spending time reverse engineering your work.

So here by I request ST to release the relevant documents for the st-link/v1 and st-link/v2 usb protocol. Do the right thing.

Thanks /Ake

[Philipp Krause]

Posted on November 05, 2017 at 10:01

A bit off-topic, since it is about the ST license situation with STM8 and STM32 in general, to just the ST-LINK/V2:

The situation in ST software licenses is radically different between STM32 and STM8.

For the STM32, a lot is available under a BSD license. For STM8, after complaints about a worse earlier license, they came up with

http://www.st.com/en/embedded-software/stsw-stm8069.html

  Version 3.0, which is non-free by clause 4, and has an explicit anti-free-software-clause 5.

For convenient software development, we need free headers with the register locations. ST provides headers in the SPL, but under a non-free license. In the

http://www.colecovision.eu/stm8/

, I did not use those headers, and instead just got the locations from the datasheets manually.

One could extract the register locations and names from the darasheets to generate headers. But would ST claim that this process results in ST holding copyright over the headers? 

Microchip Technology Inc. did so in such a case. If such claims hold might depend on the jurisdiction - in many places facts are not copyrightable. But many be the register names are? Or there are database rights to be considered?

While ST is very unlikely to sue one of their customers over such an issue, likelyhood is not enough. Also, copyrights seem to last forever¹, and no one knows where they might end up in the future.

Philipp

¹ Formally, they are finite in most jurisdictions, but historically, whenever some are about to expire, laws get changed to extend the duration of copyright.