Second round of changes to the MCU docs #1624

tronical · 2022-09-12T09:20:12Z

No description provided.

... because that's what it really is :-)

Usually "in order to" just becomes "to", but here it makes most sense to just name the requirement first. Also removed the bold from "nightly" as there's no other use of bold in this doc, it looks a little out of place.

… that way

Refer to the source of the features

* Fix persona (we selected the feature) * Use the blog title for the link to the blog.

…re metal

Tell what is okay, not what is not okay.

Refere to it in regular double quotes, like earlier. This could also be swapped to use a back tick, but then it should be done in both places.

First say why we select the feature, then provide background. Makes it easier to skim.

Providing the code snippet first and then the explanation makes it much easier to read.

Each tasks "receives", "reacts" or "renders.

Every operating system provides the primitives, in reality.

…e event loop It's not something that'll happen in the future :-)

by referring to crates as missing.

This emphasizes the time difference better

There's already a lot of "driving" in that section.

api/rs/slint/mcu.md

ogoffart · 2022-09-12T09:29:44Z

api/rs/slint/mcu.md

+ This feature is only available in the Rust Standard Library (std), but is not available in bare metal environments. As a fallback, the `unsafe-single-threaded`
+ feature changes Slint to use unsafe static for storage. This way, you guarantee to use Slint API only from the main thread, or from interrupt handlers.


Suggested change

This feature is only available in the Rust Standard Library (std), but is not available in bare metal environments. As a fallback, the `unsafe-single-threaded`

feature changes Slint to use unsafe static for storage. This way, you guarantee to use Slint API only from the main thread, or from interrupt handlers.

This macro is only available in the Rust Standard Library (std), not in bare metal environments. As a fallback, the `unsafe-single-threaded`

feature changes Slint to use unsafe static for storage. By selecting this feature, you must ensure that you only use

the Slint API from a single thread and not from interrupt handlers.

The sense of the sentence was changed: It is not possible to use slint from interrupt handlers

I remove the redundant "available" (well spotted).

Well spotted about the change of meaning!

api/rs/slint/mcu.md

Co-authored-by: Olivier Goffart <olivier.goffart@slint-ui.com>

hunger

Suggest rewording

…ly version They might settle on a different API, but the possibility is key here.

tronical · 2022-09-12T10:01:43Z

Suggest rewording

That's very broad :-)

hunger · 2022-09-12T09:57:48Z

api/rs/slint/mcu.md

-In order to set a global allocator, required by Slint, you will need a **nightly** version of Rust. This is due to the fact that the support for using a custom global allocator in a bare metal
-environment with `#![no_std]` has not been stabilized yet (see [#51540](https://github.com/rust-lang/rust/issues/51540) or
+Slint requires a global memory allocator. That is currently only available in the nightly version of Rust, because the support for using a custom global
+allocator in a bare metal environment with `#![no_std]` has not been stabilized yet (see [#51540](https://github.com/rust-lang/rust/issues/51540) or
 [#66741](https://github.com/rust-lang/rust/issues/66741) for tracking issues).


Maybe change this paragraph to:

Slint requires a global memory allocator, only available in the nightly version of Rust at this time. We can support stable Rust once support for using a custom global
allocator in a bare metal environment with #![no_std] has been stabilized (see #51540 or
#66741 for tracking issues).

This comments on a oudated version of the wording.
I think the current wording is good enough.
If you think it could be improved, feel free to change it.

tronical added 30 commits September 12, 2022 10:22

Refer to this as sections not document

a16f2be

Rename the toolchain/HAL section to prerequisites

28c9384

... because that's what it really is :-)

Rephrase the memory allocator paragraph

49027f7

Usually "in order to" just becomes "to", but here it makes most sense to just name the requirement first. Also removed the bold from "nightly" as there's no other use of bold in this doc, it looks a little out of place.

Take the person out of the section connecting sentence - it's simpler…

e06ea2d

… that way

create -> crate

5e56baf

bare-meta -> bare metal

9495fc6

Minor edit

354245b

Refer to the source of the features

Polish compat-0.3.0 explanation

ffb7817

* Fix persona (we selected the feature) * Use the blog title for the link to the blog.

Use but instead of which to emphasize the contrast between std and ba…

7c3a183

…re metal

Don't use future tense for what describes the present

425bfbf

Simplify the unsafe-single-threaded guarantees

2001137

Tell what is okay, not what is not okay.

Fix reference to std feature

b00011e

Refere to it in regular double quotes, like earlier. This could also be swapped to use a back tick, but then it should be done in both places.

Fix libm feature description

db4c515

First say why we select the feature, then provide background. Makes it easier to skim.

Re-introduce the HAL abbreviation

3192933

Fix the build.rs section order

7cdeb65

Providing the code snippet first and then the explanation makes it much easier to read.

Fix application structure intro

20ca2ad

Each tasks "receives", "reacts" or "renders.

Remove use of typical

cb1e761

Every operating system provides the primitives, in reality.

Use user interface consistently

1fc9eaa

In bare metal environments it is your responsibility to substitute th…

640ba85

…e event loop It's not something that'll happen in the future :-)

Shorten application structure bullet points

b0ea94e

Connect the crate selection with the need of writing drivers better

969aa30

by referring to crates as missing.

Clarify the purpose of forward input from peripherals to Slint

3122ff4

Minor sentence polish

e1a6ca0

Use contractions

1a3005d

an minimal -> a minimal

90247c5

Remove stray "in order to"

ff5855e

since -> between

f206d2f

This emphasizes the time difference better

Simplify the additional functionality the trait can be used to implement

7418994

Polish and simplify the renderer section a little bit

bbadf2f

Use "Rendering" consistently for both rendering section titles

988d8c7

Attemt to simplify the remaining sections in one go

971bdbd

tronical requested review from hunger and ogoffart September 12, 2022 09:20

tronical added 7 commits September 12, 2022 11:33

Fix typo

bff6e9f

The global memory allocator support is available *in* the rust version

4b47af5

Emphasize that only the night version has what we need

fe669bf

Fix missing plural

fe1f3ce

Consistently use 0.3.0 instead of mixing 0.3 and 0.3.0

0d55efd

Clarify that thread_local! as a macro is not available

817bade

drive -> operate

12fea26

There's already a lot of "driving" in that section.

ogoffart reviewed Sep 12, 2022

View reviewed changes

tronical and others added 3 commits September 12, 2022 11:50

Update api/rs/slint/mcu.md

6b6027a

Co-authored-by: Olivier Goffart <olivier.goffart@slint-ui.com>

Update api/rs/slint/mcu.md

434274a

Co-authored-by: Olivier Goffart <olivier.goffart@slint-ui.com>

Additional suggestions from Olivier

63b99cb

hunger reviewed Sep 12, 2022

View reviewed changes

only available in the nightly version -> only possible with the night…

94c4ad9

…ly version They might settle on a different API, but the possibility is key here.

hunger reviewed Sep 12, 2022

View reviewed changes

ogoffart merged commit f600181 into master Sep 12, 2022

ogoffart deleted the simon/mcu-docs-polish branch September 12, 2022 11:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Second round of changes to the MCU docs #1624

Second round of changes to the MCU docs #1624

tronical commented Sep 12, 2022

ogoffart Sep 12, 2022

tronical Sep 12, 2022

hunger left a comment

tronical commented Sep 12, 2022

hunger Sep 12, 2022

ogoffart Sep 12, 2022

		This feature is only available in the Rust Standard Library (std), but is not available in bare metal environments. As a fallback, the `unsafe-single-threaded`
		feature changes Slint to use unsafe static for storage. This way, you guarantee to use Slint API only from the main thread, or from interrupt handlers.

- This feature is only available in the Rust Standard Library (std), but is not available in bare metal environments. As a fallback, the `unsafe-single-threaded`
- feature changes Slint to use unsafe static for storage. This way, you guarantee to use Slint API only from the main thread, or from interrupt handlers.
+ This macro is only available in the Rust Standard Library (std), not in bare metal environments. As a fallback, the `unsafe-single-threaded`
+ feature changes Slint to use unsafe static for storage. By selecting this feature, you must ensure that you only use
+ the Slint API from a single thread and not from interrupt handlers.

Second round of changes to the MCU docs #1624

Second round of changes to the MCU docs #1624

Conversation

tronical commented Sep 12, 2022

ogoffart Sep 12, 2022

Choose a reason for hiding this comment

tronical Sep 12, 2022

Choose a reason for hiding this comment

hunger left a comment

Choose a reason for hiding this comment

tronical commented Sep 12, 2022

hunger Sep 12, 2022

Choose a reason for hiding this comment

ogoffart Sep 12, 2022

Choose a reason for hiding this comment