stm32f0xx-hal
stm32f0xx-hal copied to clipboard
stm32-rs
Move pin af definitions to a universal pin_mappings file
This makes the peripheral files really peripheral specific and moves the glue into a separate file. I'd like to compare it to all the datasheets to make sure there is no typo in there.
I'm not sure if we should keep the analog mappings in the adc.rs file.
hmm, I have a potential thought for this. Would it be preferable to just have a single definition of all the pins for each micro variant? It will result in some duplication, but it will also make it much clearer what the total mapping for any given micro is.
hmm, I have a potential thought for this. Would it be preferable to just have a single definition of all the pins for each micro variant? It will result in some duplication, but it will also make it much clearer what the total mapping for any given micro is.
I was thinking the same as this would make things much easier to change and verify.
Just my $0.02, I like @HarkonenBade 's idea of splitting out the pin definitions by variant; as mentioned by @therealprof it would simplify adding/modifying/verifying things, IMO. In regards to potential duplication, we may be able to refactor out some common configuration as we find it, but I see the pros of this change outweighing the cons.
Would it be preferable to just have a single definition of all the pins for each micro variant? I split it up so its (everything) -> (family) -> (specific micro). I think it's the best way.
Yeah, I'm just wondering if a flat single macro for each supported chip feature would be easier to keep track of. Also I'd be down to make a python script that takes the pin mapping table from a datasheet in a sane way and outputs the macro def.
f. Also I'd be down to make a python script that takes the pin mapping table from a datasheet in a sane way and outputs the macro def.
Pdf parsing sounds somewhat broken and insane, but you could maybe see what stm32cubemx uses internally. It's probably something xml-y.
f. Also I'd be down to make a python script that takes the pin mapping table from a datasheet in a sane way and outputs the macro def.
Pdf parsing sounds somewhat broken and insane, but you could maybe see what stm32cubemx uses internally. It's probably something xml-y.
That is fair, currently pulling some of their MCU defs to take a look at what the file format is like.
@HarkonenBade PDF parsing is indeed tricky. Most likely you'll only find all the fancy tipos and minor changes in typography in all the different data sheets.
Well, I've managed to hack together something that can read the cubemx database files and spit out a pins! macro definition for a particular mcu.
@HarkonenBade Cool stuff, potentially even more accurate than the SVD files or datasheets/documentation.
https://github.com/HarkonenBade/cube-parse There is the current state, the code is super messy and potentially fragile, but it seems to function. I'll try and grind some of the rough edges off if it seems useful.
Looks good. Does anyone know what the license of these files is? I liked having a guaranteed subset, but it's way better and less error prone this way.
Looks good. Does anyone know what the license of these files is? I liked having a guaranteed subset, but it's way better and less error prone this way.
I believe that it is under the same licence applied to all of cubeMX which is this: https://www.st.com/resource/en/license_agreement/dm00218346.pdf . I'm not 100% certain if derivative use would be permitted, but I also am not an expert at reading licence agreements.
use, reproduction or redistribution of this software package partially or totally may be done in any manner that would subject this software package to any Open Source Terms (as defined below) is software package or any part thereof, including modifications and/or derivative works of this software package, must be used and execute solely and exclusively on or in combination with a microcontroller or a microprocessor devices manufactured by or for STMicroelectronics.
Doesn't seem very compatible. We should probably store them in a separate repo akin to stm32-rs and just use the end result. I wouldn't depend on them not completely changing under us. Having a separate crate doesn't seem possible/easy, so i think we just need to copy-paste.
hmm, I'm not sure that would be directly a terrible restriction, as is the stm32f0xx-hal really going to be used on anything other than ST devices? Also if we were copy pasting then we would still fall foul of the licence I suspect.
Nah, we're only using the technical data, that's not copyright, while the original files may be. According to Wikipedia
Copyright does not cover ideas and information themselves, only the form or manner in which they are expressed
So we're probably safe, but I'm no lawyer
@david-sawatzke
Doesn't seem very compatible.
What do you mean by that? Using the result should be no problem. Redistributing parts of CubeMX is of course a bad idea but it's likely they're part of the family packs and in that case it might be even possible to retrieve them on the fly.
I wouldn't depend on them not completely changing under us.
I would not change anything from how we're working today: if we need the pins, get the files, run the tool put the output into this crate and done. We'll not notice if they change anyway but unless they're buggy I'm also not expecting any major changes.
@david-sawatzke
Doesn't seem very compatible.
What do you mean by that? Using the result should be no problem. Redistributing parts of CubeMX is of course a bad idea but it's likely they're part of the family packs and in that case it might be even possible to retrieve them on the fly.
They are sadly only distributed as part of the actual cubemx application. The family packs just contain hal sources and templates/examples. The issue is if the pin defs count as 'derived works' from the cubemx software package.
Using the result seems to be no problem
Yes, but i personally like the way stm32-rs does it, generating final files as needed and using original files as the source of truth. But we can't do it this way in the repo
Yes, but i personally like the way stm32-rs does it, generating final files as needed and using original files as the source of truth. But we can't do it this way in the repo
There're two obvious ways how to achieve the same (and a few more non-obvious ones):
- Ask for permission to include the source files in the GH repo
- Download them on the fly
Yes, but i personally like the way stm32-rs does it, generating final files as needed and using original files as the source of truth. But we can't do it this way in the repo
There're two obvious ways how to achieve the same (and a few more non-obvious ones):
- Ask for permission to include the source files in the GH repo
- Download them on the fly
The latter will require working out how to extract them from the STM32CubeMX installer without running it however.
Getting permission would be great, but i wouldn't download them on the fly, since we could experience random breakage with newer versions and stm32cubemx is pretty large.
EDIT: And st wants people to give their email to download it, although the aur also has a direct link.
Slow progress on autogeneration still being made in https://github.com/HarkonenBade/cube-parse, the latest output looks something like https://gist.github.com/HarkonenBade/5ae17d4f85e5f83faeb05407fd5a653c
Rebased this on master, but haven't added the new pinbindings, because I hope we'll use generated mappings
I'll try taking a bit more of a look at that soon. A profitable route may be using the features of the F0-hal crate to narrow the feature gate declarations. (and I could then flag if there are any conflicts between the current feature gates and the ones that the pin def would require)
I'm currently working on generating STM32 symbols/components for the LibrePCB base library. For that we also needed the pinout information. I found an alternative to parsing the XML files directly: STM32CubeMX can be scripted to export pinout mappings in CSV format. The result can be found here: https://github.com/LibrePCB/stm32-pinout
That functionality is also available directly through the GUI. You can export the pinout CSV files manually through a menu, both with and without AF mappings. You can find an example file here, it basically matches the table in the datasheet.
Unfortunately the CSV files exported through scripting do not contain AF mappings. However, the AF mappings are printed to the terminal during export, so the information is there.
I reverse-engineered the CubeMX JAR a bit and found the function that handles the command line CSV export:
CommandLineManager.addCommand("csv pinout", "csv pinout <file>", 0, new CommandLineListener() {
public boolean onCommandEntered(String[] args) {
return MxSystem.getMxMcu().csvDump(args[0], false);
}
});
The false parameter to csvDump specifies whether AF mappings are exported as well or not. Unfortunately it's hardcoded to false.
I opened a support ticket with ST to ask whether that functionality could be added or not. I don't have high hopes that this will happen though, usually requests like that end up in /dev/null.
Another option would be to try patching the JAR so we could export pinout files with AF mappings using the official software. From those CSV files we could generate grouped AF pin mappings for various STM32 HALs. I'm not sure how easy patching JARs is, IIRC they have some kind of checksum. All we'd need to do is changing that false to true though.
Regarding licensing, I think that those exported CSV files only contain technical information from the datasheet and probably do not fall under copyright. IANAL though.
By patching a single byte in the JAR bytecode, the exported CSV files now include the AF mapping information :tada:
https://github.com/LibrePCB/stm32-pinout/
See the data directory for the current export.
@david-sawatzke @HarkonenBade is this useful to you, or does the database parser already handle all information you need? The reason why I think using the CSV export functionality might be useful, is that ST appears to do some post-processing in their code on top of the data available in the database files. For example:
if (paramName.equals("GPIO_Speed") && currentIp != null && currentIp.getIPGroup().equalsIgnoreCase("Connectivity")) {
String MxDBVersion = this.mcu.getProject().getMxDataBaseVersion();
if (CodeGenerator.isDBversionOlderThan("DB.4.0.140"))
return "GPIO_SPEED_HIGH";
if (getMcu().getFamily().equals("STM32L1") || getMcu().getFamily().equals("STM32L0") ||
getMcu().getFamily().equals("STM32L4") ||
getMcu().getFamily().equals("STM32F2") ||
getMcu().getFamily().equals("STM32F4") ||
getMcu().getFamily().equals("STM32F7"))
return "GPIO_SPEED_FREQ_VERY_HIGH";
if (getMcu().getFamily().equals("STM32F0") || getMcu().getFamily().equals("STM32F3") ||
getMcu().getFamily().equals("STM32F1"))
return "GPIO_SPEED_FREQ_HIGH";
}
However, I don't know whether this affects AFs as well.
Quick update, after checking @HarkonenBade's approach with cube-parse again a bit in more depth, this definitely looks like the cleaner approach than the hack I did above. We had a lengthy discussion tonight in the rust-embedded Matrix channel with @adamgreig and @therealprof about grouping of features and ended up with the conclusion that using the "GPIO IP Versions" as features is probably the best approach.
I've forked cube-parse for now and added a lot of documentation on how the STM32CubeMX database is structured, and why grouping features by "GPIO IP Version" probably makes sense.
In the case of the STM32F0, the following five GPIO versions...
STM32F031_gpio_v1_0_Modes.xml
STM32F042_gpio_v1_0_Modes.xml
STM32F051_gpio_v1_0_Modes.xml
STM32F052_gpio_v1_0_Modes.xml
STM32F091_gpio_v1_0_Modes.xml
...would result in the following features:
- io-STM32F031
- io-STM32F042
- io-STM32F051
- io-STM32F052
- io-STM32F091
The feature names could still be bikeshedded. A possible alternative would be removing the STM32 prefix so that the feature name is io-F031. I think some kind of prefix (like io) makes sense though, to indicate that these are not necessarily prefixes of your MCU (see below).
Note that sometimes those GPIO peripheral versions don't match the name. For example the STM32F091_gpio_v1_0 version is shared among the following MCUs:
#[cfg(feature = "io-STM32F091")]
// STM32F030CCTx
// STM32F030RCTx
// STM32F091C(B-C)Tx
// STM32F091C(B-C)Tx
// STM32F091C(B-C)Ux
// STM32F091C(B-C)Ux
// STM32F091R(B-C)Tx
// STM32F091R(B-C)Tx
// STM32F091RCHx
// STM32F091RCYx
// STM32F091V(B-C)Tx
// STM32F091V(B-C)Tx
// STM32F091VCHx
// STM32F098CCTx
// STM32F098CCUx
// STM32F098RCHx
// STM32F098RCTx
// STM32F098RCYx
// STM32F098VCHx
// STM32F098VCTx
This includes some F098xxxx MCUs as well as some STM32F030xxxx. However, other STM32F030xxxx MCUs are using other GPIO versions (e.g. STM32F030C6Tx -> io-STM32F031).
We'll probably have to solve this issue with documentation (and maybe a lookup table from MCU to feature).
The alternative would be adding a feature per MCU and then adding a dependency on the proper GPIO version, but @therealprof objected to having many features :slightly_smiling_face: I'm still unsure whether having a feature per MCU would be a good idea or not.
(The MCU feature dependencies could look something like this: STM32F098CCUx = ["io-STM32F091"].)