Skip to content

Commit fa91e1f

Browse files
DirbaioDirbaio
committed
doc: use include_str!(README.md) for embedded-hal crate docs.
1 parent 2c71ed6 commit fa91e1f

File tree

2 files changed

+76
-80
lines changed

2 files changed

+76
-80
lines changed

‎embedded-hal/README.md

Lines changed: 75 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,80 @@
99
1010
This project is developed and maintained by the [HAL team](https://github.com/rust-embedded/wg#the-hal-team).
1111

12-
## [API reference]
12+
**NOTE** This HAL is still is active development. Expect the traits presented here to be
13+
tweaked, split or be replaced wholesale before being stabilized, i.e. before hitting the 1.0.0
14+
release.
1315

14-
[API reference]: https://docs.rs/embedded-hal
16+
**NOTE** If you want to use an alpha release of the 1.0.0 version, use an exact version
17+
specifier in your `Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.2"`.
18+
19+
## Companion crates
20+
21+
The main `embedded-hal` crate contains only blocking traits, where the operation is done
22+
synchronously before returning. Check out the following crates, which contain versions
23+
of the traits for other execution models:
24+
25+
- [`embedded-hal-async`](https://docs.rs/embedded-hal-async): async/await-based.
26+
- [`embedded-hal-nb`](https://docs.rs/embedded-hal-nb): polling-based, using the `nb` crate.
27+
28+
The [`embedded-hal-bus`](https://docs.rs/embedded-hal-bus) crate provides utilities for sharing
29+
SPI and I2C buses.
30+
31+
Additionally, more domain-specific traits are available in separate crates:
32+
- [`embedded-can`](https://docs.rs/embedded-can): Controller Area Network (CAN)
33+
34+
## Design goals
35+
36+
The HAL
37+
38+
- Must *erase* device specific details. Neither register, register blocks or magic values should
39+
appear in the API.
40+
41+
- Must be generic *within* a device and *across* devices. The API to use a serial interface must
42+
be the same regardless of whether the implementation uses the USART1 or UART4 peripheral of a
43+
device or the UART0 peripheral of another device.
44+
45+
- Where possible must *not* be tied to a specific asynchronous model. The API should be usable
46+
in blocking mode, with the `futures` model, with an async/await model or with a callback model.
47+
(cf. the [`nb`](https://docs.rs/nb) crate)
48+
49+
- Must be minimal, and thus easy to implement and zero cost, yet highly composable. People that
50+
want higher level abstraction should *prefer to use this HAL* rather than *re-implement*
51+
register manipulation code.
52+
53+
- Serve as a foundation for building an ecosystem of platform agnostic drivers. Here driver
54+
means a library crate that lets a target platform interface an external device like a digital
55+
sensor or a wireless transceiver. The advantage of this system is that by writing the driver as
56+
a generic library on top of `embedded-hal` driver authors can support any number of target
57+
platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux, etc.). The
58+
advantage for application developers is that by adopting `embedded-hal` they can unlock all
59+
these drivers for their platform.
60+
61+
- Trait methods must be fallible so that they can be used in any possible situation.
62+
Nevertheless, HAL implementations can additionally provide infallible versions of the same methods
63+
if they can never fail in their platform. This way, generic code can use the fallible abstractions
64+
provided here but platform-specific code can avoid fallibility-related boilerplate if possible.
65+
66+
## Out of scope
67+
68+
- Initialization and configuration stuff like "ensure this serial interface and that SPI
69+
interface are not using the same pins". The HAL will focus on *doing I/O*.
70+
71+
## Reference implementation
72+
73+
The [`stm32f1xx-hal`] crate contains a reference implementation of this HAL.
74+
75+
[`stm32f1xx-hal`]: https://crates.io/crates/stm32f1xx-hal
76+
77+
## Platform agnostic drivers
78+
79+
You can find platform agnostic drivers built on top of `embedded-hal` on crates.io by [searching
80+
for the *embedded-hal* keyword](https://crates.io/keywords/embedded-hal).
81+
82+
If you are writing a platform agnostic driver yourself you are highly encouraged to [add the
83+
embedded-hal keyword](https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata)
84+
to your crate before publishing it!
85+
//
1586

1687
## Minimum Supported Rust Version (MSRV)
1788

@@ -25,8 +96,8 @@ See [here](../docs/msrv.md) for details on how the MSRV may be upgraded.
2596
Licensed under either of
2697

2798
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
28-
http://www.apache.org/licenses/LICENSE-2.0)
29-
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
99+
<http://www.apache.org/licenses/LICENSE-2.0>)
100+
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
30101

31102
at your option.
32103

‎embedded-hal/src/lib.rs

Lines changed: 1 addition & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,4 @@
1-
//! A Hardware Abstraction Layer (HAL) for embedded systems
2-
//!
3-
//! **NOTE** This HAL is still is active development. Expect the traits presented here to be
4-
//! tweaked, split or be replaced wholesale before being stabilized, i.e. before hitting the 1.0.0
5-
//! release.
6-
//!
7-
//! **NOTE** If you want to use an alpha release of the 1.0.0 version, use an exact version
8-
//! specifier in your `Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.2"`.
9-
//!
10-
//! # Companion crates
11-
//!
12-
//! The main `embedded-hal` crate contains only blocking traits, where the operation is done
13-
//! synchronously before returning. Check out the following crates, which contain versions
14-
//! of the traits for other execution models:
15-
//!
16-
//! - [`embedded-hal-async`](https://docs.rs/embedded-hal-async): async/await-based.
17-
//! - [`embedded-hal-nb`](https://docs.rs/embedded-hal-nb): polling-based, using the `nb` crate.
18-
//!
19-
//! The [`embedded-hal-bus`](https://docs.rs/embedded-hal-bus) crate provides utilities for sharing
20-
//! SPI and I2C buses.
21-
//!
22-
//! Additionally, more domain-specific traits are available in separate crates:
23-
//! - [`embedded-can`](https://docs.rs/embedded-can): Controller Area Network (CAN)
24-
//!
25-
//! # Design goals
26-
//!
27-
//! The HAL
28-
//!
29-
//! - Must *erase* device specific details. Neither register, register blocks or magic values should
30-
//! appear in the API.
31-
//!
32-
//! - Must be generic *within* a device and *across* devices. The API to use a serial interface must
33-
//! be the same regardless of whether the implementation uses the USART1 or UART4 peripheral of a
34-
//! device or the UART0 peripheral of another device.
35-
//!
36-
//! - Where possible must *not* be tied to a specific asynchronous model. The API should be usable
37-
//! in blocking mode, with the `futures` model, with an async/await model or with a callback model.
38-
//! (cf. the [`nb`](https://docs.rs/nb) crate)
39-
//!
40-
//! - Must be minimal, and thus easy to implement and zero cost, yet highly composable. People that
41-
//! want higher level abstraction should *prefer to use this HAL* rather than *re-implement*
42-
//! register manipulation code.
43-
//!
44-
//! - Serve as a foundation for building an ecosystem of platform agnostic drivers. Here driver
45-
//! means a library crate that lets a target platform interface an external device like a digital
46-
//! sensor or a wireless transceiver. The advantage of this system is that by writing the driver as
47-
//! a generic library on top of `embedded-hal` driver authors can support any number of target
48-
//! platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux, etc.). The
49-
//! advantage for application developers is that by adopting `embedded-hal` they can unlock all
50-
//! these drivers for their platform.
51-
//!
52-
//! - Trait methods must be fallible so that they can be used in any possible situation.
53-
//! Nevertheless, HAL implementations can additionally provide infallible versions of the same methods
54-
//! if they can never fail in their platform. This way, generic code can use the fallible abstractions
55-
//! provided here but platform-specific code can avoid fallibility-related boilerplate if possible.
56-
//!
57-
//! # Out of scope
58-
//!
59-
//! - Initialization and configuration stuff like "ensure this serial interface and that SPI
60-
//! interface are not using the same pins". The HAL will focus on *doing I/O*.
61-
//!
62-
//! # Reference implementation
63-
//!
64-
//! The [`stm32f1xx-hal`] crate contains a reference implementation of this HAL.
65-
//!
66-
//! [`stm32f1xx-hal`]: https://crates.io/crates/stm32f1xx-hal
67-
//!
68-
//! # Platform agnostic drivers
69-
//!
70-
//! You can find platform agnostic drivers built on top of `embedded-hal` on crates.io by [searching
71-
//! for the *embedded-hal* keyword](https://crates.io/keywords/embedded-hal).
72-
//!
73-
//! If you are writing a platform agnostic driver yourself you are highly encouraged to [add the
74-
//! embedded-hal keyword](https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata)
75-
//! to your crate before publishing it!
76-
1+
#![doc = include_str!("../README.md")]
772
#![warn(missing_docs)]
783
#![no_std]
794

0 commit comments

Comments
 (0)