diff --git a/src/portability/index.md b/src/portability/index.md index 754ef63..1e1f03b 100644 --- a/src/portability/index.md +++ b/src/portability/index.md @@ -40,9 +40,9 @@ As said above there are three main users of the HAL: ### HAL implementation -A HAL implementation provides the interfacing between the hardware and and the users of the HAL traits. Typical implementations consist of three parts: +A HAL implementation provides the interfacing between the hardware and the users of the HAL traits. Typical implementations consist of three parts: * One or more hardware specific types -* Functions to create and intialise such a type, often providing various configuration options (speed, operation mode, use pins, etc.) +* Functions to create and initialize such a type, often providing various configuration options (speed, operation mode, use pins, etc.) * one or more `trait` `impl` of **embedded-hal** traits for that type Such a **HAL implementation** can come in various flavours: @@ -53,10 +53,10 @@ Such a **HAL implementation** can come in various flavours: ### Driver -A driver implements a set of custom functionality for an internal or external component, connected to a peripheral implementing the embedded-hal traits. Typical examples for such drivers include various sensors (temperature, magnetometer, accelerometer, light), display devices (LED arrays, LCD displays) and actors (motors, transmitters). +A driver implements a set of custom functionality for an internal or external component, connected to a peripheral implementing the embedded-hal traits. Typical examples for such drivers include various sensors (temperature, magnetometer, accelerometer, light), display devices (LED arrays, LCD displays) and actuators (motors, transmitters). -A driver has to be initialised with an instance of type that implements a certain `trait` of the embedded-hal which is ensured via trait bound and provides its own type instance with a custom set of methods allowing to interact with the driven device. +A driver has to be initialized with an instance of type that implements a certain `trait` of the embedded-hal which is ensured via trait bound and provides its own type instance with a custom set of methods allowing to interact with the driven device. ### Application -The application binds the various parts together and ensures that the desired functionality is achieved. When porting between different systems, this is the part which requires the most adaptation efforts, since the application needs to correctly intialise the real hardware via the HAL implementation and the initialisation of different hardware differs, sometimes drastically so. Also the user choice often plays a big role, since components can be physically connected to different terminals, hardware buses sometimes need external hardware to match the configuration or there are different trade-offs to be made in the use of internal peripherals (e.g. multiple timers with different capabilities are available or peripherals conflict with others). +The application binds the various parts together and ensures that the desired functionality is achieved. When porting between different systems, this is the part which requires the most adaptation efforts, since the application needs to correctly initialize the real hardware via the HAL implementation and the initialisation of different hardware differs, sometimes drastically so. Also the user choice often plays a big role, since components can be physically connected to different terminals, hardware buses sometimes need external hardware to match the configuration or there are different trade-offs to be made in the use of internal peripherals (e.g. multiple timers with different capabilities are available or peripherals conflict with others). diff --git a/src/static-guarantees/design-contracts.md b/src/static-guarantees/design-contracts.md index ea3eae6..4a243be 100644 --- a/src/static-guarantees/design-contracts.md +++ b/src/static-guarantees/design-contracts.md @@ -97,7 +97,7 @@ impl Gpio { } ``` -Because we need to enforce the restrictions on the hardware, we end up doing a lot of runtime checking whch wastes time and resources, and this code will be much less pleasant for the developer to use. +Because we need to enforce the restrictions on the hardware, we end up doing a lot of runtime checking which wastes time and resources, and this code will be much less pleasant for the developer to use. ## Type States @@ -245,7 +245,7 @@ output_pin.set_bit(false); // output_pin.into_input_pull_down(); ``` -This is defintely a convenient way to store the state of the pin, but why do it this way? Why is this better than storing the state as an `enum` inside of our `GpioConfig` structure? +This is definitely a convenient way to store the state of the pin, but why do it this way? Why is this better than storing the state as an `enum` inside of our `GpioConfig` structure? ## Compile Time Functional Safety diff --git a/src/static-guarantees/state-machines.md b/src/static-guarantees/state-machines.md index 0d5a5ba..b7c24f1 100644 --- a/src/static-guarantees/state-machines.md +++ b/src/static-guarantees/state-machines.md @@ -51,7 +51,7 @@ Typically the states listed above are set by writing values to given registers m | | | 1 | set-high | Output pin is driven high | | input_status | 5 | x | in-val | 0 if input is < 1.5v, 1 if input >= 1.5v | -We could simple expose the following structure in Rust to control this GPIO: +We _could_ expose the following structure in Rust to control this GPIO: ```rust,ignore /// GPIO interface @@ -79,7 +79,7 @@ impl Gpio { }); } - pub fn set_output_status(&mut self, is_high: bool) { + pub fn set_output_mode(&mut self, is_high: bool) { self.periph.modify(|_r, w| { w.output_mode.set_bit(is_high) }); @@ -91,8 +91,8 @@ impl Gpio { } ``` -However, this could allow us to modify certain registers that do not make sense. For example, what happens if we set the `output_mode` field when our GPIO is configured as an input? For some hardware, this may not matter, but on some hardware, it could cause unexpected or undefined behavior. +However, this would allow us to modify certain registers that do not make sense. For example, what happens if we set the `output_mode` field when our GPIO is configured as an input? -This would allow us to reach states not defined by our state machine above: An output that is pulled low, or an input that was set high! +In general, use of this structure would allow us to reach states not defined by our state machine above: e.g. an output that is pulled low, or an input that is set high. For some hardware, this may not matter. On other hardware, it could cause unexpected or undefined behavior! -Although this interface is convenient to write, it doesn't enforce the design contracts set out by our hardware implementation. \ No newline at end of file +Although this interface is convenient to write, it doesn't enforce the design contracts set out by our hardware implementation.