Skip to content

Commit 21310f9

Browse files
Sh3Rm4nSh3Rm4n
authored
Merge pull request #75 from strom-und-spiele/subvariants
Subvariants
2 parents 7c821bb + 6eb84f0 commit 21310f9

File tree

5 files changed

+162
-22
lines changed

5 files changed

+162
-22
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
77

88
## [Unreleased]
99

10+
### Changed
11+
12+
- **Breaking** The feature gate requires you to select a subvaraint if possible. ([#67](https://github.com/stm32-rs/stm32f3xx-hal/pull/67))
13+
1014
## [v0.4.3] - 2020-04-11
1115

1216
### Added

‎Cargo.toml

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -49,17 +49,23 @@ usbd-serial = "0.1"
4949
[features]
5050
default = ["unproven"]
5151
device-selected = []
52+
direct-call-deprecated = []
5253
rt = ["stm32f3/rt"]
53-
stm32f301 = ["stm32f3/stm32f301", "device-selected"]
54+
# Any Changes here should be mirrored in README.md and src/lib.rs
55+
stm32f301 = ["stm32f3/stm32f301", "direct-call-deprecated"]
56+
stm32f301xb = ["stm32f301", "device-selected"]
57+
stm32f301xc = ["stm32f301", "device-selected"]
58+
stm32f301xd = ["stm32f301", "device-selected"]
59+
stm32f301xe = ["stm32f301", "device-selected"]
5460
stm32f318 = ["stm32f3/stm32f3x8", "device-selected"]
5561
stm32f302 = ["stm32f3/stm32f302", "device-selected"]
56-
stm32f303 = ["stm32f3/stm32f303", "device-selected"]
57-
stm32f303xb = ["stm32f303", "stm32-usbd/ram_access_1x16"]
58-
stm32f303xc = ["stm32f303", "stm32-usbd/ram_access_1x16"]
59-
stm32f303xd = ["stm32f303", "stm32-usbd/ram_access_2x16"]
60-
stm32f303xe = ["stm32f303", "stm32-usbd/ram_access_2x16"]
61-
stm32f303x6 = ["stm32f303"]
62-
stm32f303x8 = ["stm32f303"]
62+
stm32f303 = ["stm32f3/stm32f303", "direct-call-deprecated"]
63+
stm32f303xb = ["stm32f303", "stm32-usbd/ram_access_1x16", "device-selected"]
64+
stm32f303xc = ["stm32f303", "stm32-usbd/ram_access_1x16", "device-selected"]
65+
stm32f303xd = ["stm32f303", "stm32-usbd/ram_access_2x16", "device-selected"]
66+
stm32f303xe = ["stm32f303", "stm32-usbd/ram_access_2x16", "device-selected"]
67+
stm32f303x6 = ["stm32f303", "device-selected"]
68+
stm32f303x8 = ["stm32f303", "device-selected"]
6369
stm32f373 = ["stm32f3/stm32f373", "device-selected"]
6470
stm32f378 = ["stm32f3/stm32f3x8", "device-selected"]
6571
stm32f334 = ["stm32f3/stm32f3x4", "device-selected"]

‎README.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,74 @@ Almost all of the implementation was shamelessly adapted from the
3838
[`stm32f30x-hal`]: https://github.com/japaric/stm32f30x-hal
3939
[`embedded-hal`]: https://github.com/japaric/embedded-hal
4040

41+
## Selecting the right chip
42+
43+
This crate requires you to specify your target chip as a feature.
44+
45+
*Example: The STM32F3Discovery board has a STM32F303VCT6 chip.
46+
So you want to expand your call to `cargo` with `--features stm32f303xc`.*
47+
48+
### Possible chips
49+
50+
[comment]: # (Any changes here should be mirrored in src/lib.rs)
51+
52+
Note: `x` denotes any character in [a-z]
53+
* stm32f301xb
54+
* stm32f301xc
55+
* stm32f301xd
56+
* stm32f301xe
57+
* stm32f318
58+
* stm32f302
59+
* stm32f303xb
60+
* stm32f303xc
61+
* stm32f303xd
62+
* stm32f303xe
63+
* stm32f303x6
64+
* stm32f303x8
65+
* stm32f373
66+
* stm32f378
67+
* stm32f334
68+
* stm32f328
69+
* stm32f358
70+
* stm32f398
71+
72+
### Background
73+
74+
For some of the stm32f3xx chips there are sub-variants that differ in
75+
functionality, peripheral use and hence 'under the hood' implementation. To
76+
allow the full use of all peripherals on certain subvariants without
77+
allowing for code that just doesn't run on other sub-vairants, they are
78+
distinct features that need to be specified.
79+
80+
As this crate is still under fundamental development, expect more
81+
sub-variants replacing the plain variants in the future as we are
82+
implementing more stuff. It is not desired to allow the plain variants to
83+
be used as this leads to confusion.
84+
*Example: the stm32f303xc has a gpio_e bank while the stm32f303x6 does
85+
not. Hence we don't want to expose the gpoio_e bank on all stm32f303 (i.e.
86+
when specifying the feature stm32f303) albeit a stm32f303xc user would
87+
expect it to do so.*
88+
89+
### Detailed steps to select the right chip
90+
91+
1. Get the full name of the chip you are using from your datasheet, user manual or other source.
92+
93+
*Example: We want to use the STM32F3Discovery kit.*
94+
*The [Usermanual][] tells us it's using a STM32F303VC chip.*
95+
96+
2. Find your chip as a feature in the list above.
97+
98+
*Example: Looking for the right feature for our STM32F303VC chip we first find
99+
`stm32f301xb`. This is the wrong chip, as we're not looking for `f301` but for `f303`.*
100+
101+
*Looking further we find `stm32f303xc`. This matches STM32F303VC (note that VC → xc).*
102+
103+
3. Add the chip name as a feature to your cargo call.
104+
105+
*Example: Using the STM32F303VC chip we run `cargo check --features stm32f303xc`.*
106+
107+
[Usermanual]: https://www.st.com/content/ccc/resource/technical/document/user_manual/8a/56/97/63/8d/56/41/73/DM00063382.pdf/files/DM00063382.pdf/jcr:content/translations/en.DM00063382.pdf
108+
41109
## License
42110

43111
[0-clause BSD license](LICENSE-0BSD.txt).

‎ci/build.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,9 @@ def main():
2828
crate_info = cargo_meta["packages"][0]
2929

3030
features = [
31-
"{},rt".format(x) for x in crate_info["features"].keys()
32-
if x not in ["device-selected", "rt", "default", "unproven"]
31+
"{},rt".format(feature)
32+
for feature, derived in crate_info["features"].items()
33+
if "device-selected" in derived
3334
]
3435

3536
cargo_build_cmd = ['cargo', 'build', '--verbose']

‎src/lib.rs

Lines changed: 73 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,80 @@
1+
/*!
2+
# Selecting the right chip
3+
4+
This crate requires you to specify your target chip as a feature.
5+
6+
Please select one of the following
7+
8+
(Note: `x` denotes any character in [a-z])
9+
* stm32f301xb
10+
* stm32f301xc
11+
* stm32f301xd
12+
* stm32f301xe
13+
* stm32f318
14+
* stm32f302
15+
* stm32f303xb
16+
* stm32f303xc
17+
* stm32f303xd
18+
* stm32f303xe
19+
* stm32f303x6
20+
* stm32f303x8
21+
* stm32f373
22+
* stm32f378
23+
* stm32f334
24+
* stm32f328
25+
* stm32f358
26+
* stm32f398
27+
28+
Example: The STM32F3Discovery board has a STM32F303VCT6 chip.
29+
So you want to expand your call to `cargo` with `--features stm32f303xc`.
30+
31+
For more information, see the [README](https://github.com/stm32-rs/stm32f3xx-hal/blob/master/README.md#selecting-the-right-chip)
32+
*/
133
#![no_std]
234
#![allow(non_camel_case_types)]
335

4-
#[cfg(not(feature = "device-selected"))]
36+
#[cfg(all(not(feature = "device-selected"), not(feature = "needs-subvariant")))]
37+
compile_error!(
38+
"This crate requires you to specify your target chip as a feature.
39+
40+
Please select one of the following
41+
42+
(Note: `x` denotes any character in [a-z])
43+
* stm32f301xb
44+
* stm32f301xc
45+
* stm32f301xd
46+
* stm32f301xe
47+
* stm32f318
48+
* stm32f302
49+
* stm32f303xb
50+
* stm32f303xc
51+
* stm32f303xd
52+
* stm32f303xe
53+
* stm32f303x6
54+
* stm32f303x8
55+
* stm32f373
56+
* stm32f378
57+
* stm32f334
58+
* stm32f328
59+
* stm32f358
60+
* stm32f398
61+
62+
Example: The STM32F3Discovery board has a STM32F303VCT6 chip.
63+
So you want to expand your call to `cargo` with `--features stm32f303xc`.
64+
65+
For more information, see README -> Selecting the right chip.
66+
"
67+
);
68+
69+
#[cfg(all(not(feature = "device-selected"), feature = "direct-call-deprecated",))]
570
compile_error!(
6-
"This crate requires one of the following device features enabled:
7-
stm32f301
8-
stm32f318
9-
stm32f302
10-
stm32f303
11-
stm32f373
12-
stm32f378
13-
stm32f334
14-
stm32f328
15-
stm32f358
16-
stm32f398"
71+
"The feature you selected is deprecated, because it was split up into sub-devices.
72+
73+
Example: The STM32F3Discovery board has a STM32F303VCT6 chip.
74+
You used to use `--features stm32f303` but now functionalities for the sub-device were added.
75+
Replace it with `--features stm32f303xc` to make your code build again.
76+
77+
Please select one of the chip features stated above."
1778
);
1879

1980
pub use embedded_hal as hal;

0 commit comments

Comments
 (0)