Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merge the next branch (finally!) #190

Merged
merged 104 commits into from
Jul 11, 2021
Merged

Merge the next branch (finally!) #190

merged 104 commits into from
Jul 11, 2021

Conversation

Rahix
Copy link
Owner

@Rahix Rahix commented Jul 9, 2021

Technically we haven't yet finished all the work from #130 but ending this doesn't seem to be happening anytime soon either. In the meantime we've gotten a few pull-requests against the main/master branch which is sad because it means the work has to be duplicated for the refactored version.

So I think it is in everyones best interest to merge next now and take care of the rest later. The work has matured enough that it should replace the old codebase for most usecases, and if anything is missing, maybe this will speed up the addition to the new crates ;)

Anyway, thanks a lot to the people who contributed to the refactoring effort, especially @explicite who did a lot of the board and MCU ports and @drmorr0 who chipped in with the SPI controller driver.

I've taken some time to start working on documentation of the new stuff, I think there's now enough that we can replace the main/master branch. But there are lots of items where documentation could still be improved so if you see anything, please feel free to send PRs :)

Also, there's now an avr-hal-template for jumpstarting AVR Rust projects.


From an operational point of view, I plan to merge next into main with

git switch -C tmp next
git merge -s ours main
git switch -C main

which means that the current tree of next will replace everything on main (but with a continuous history). The "old" version of avr-hal thus will still exist in git history and will also be available in a dedicated old branch (which already exists).

The next branch will not be deleted just yet, so we don't break anyone referencing it for the next weeks. Additionaly I will edit all currently open PRs at the time of merge to then refer to the main branch if they currently refer to next. So any work that is still in progress will be preserved without additional effort from the authors.

Rahix and others added 30 commits February 7, 2021 17:02
To make some traits unimplementable, add a sealed trait to
avr-hal-generic.
Replace the existing port implementation with a new design.  With the
new design, there is a single `Pin` type for representing pins and
specific pins can be discerned via one of its generic parameters.

One one hand, this eases visibility of the public API as it is no longer
hidden inside a magic macro and on the other hand it allows to easily
support the different IO cells of old and new AVR MCUs.

Please refer to the included documentation in this commit for more
details.

Ref: #114
Adjust the `impl_usart_traditional!()` macro to support the new design
of pin types.

This leads to an interesting issue: Because with the new design, neither
the type (e.g. `USART0`) nor the trait (`UsartOps`) nor the pin type are
from the HAL crate, we run into the orphan rule.

Mitigate this by expecting a newtype wrapper around the peripheral, and
as such do the register accesses through a `.0` accessor.  In the future
we might want to make this accessor configurable.
Start with the new unified HAL crate for all ATmega MCUs.  Start with
support for ATmega328P's GPIO pins and USART peripheral.

Instead of, like the previous HAL, exposing `pac::Peripherals`, the HAL
now defines its own `Peripherals` struct.  This allows us to more
cleanly implement more complex peripheral support.  For example, instead
of individual fields for each port (PORTB, PORTC, PORTD, ...), the
`hal::Peripherals` only has a single field `pins`, wrapping all of the
above.

Ref: #94
Create a unified crate for all arduino boards, to combat code
duplication in the current design.  As a start, add very basic support
for Arduino Uno.  This includes GPIO pins and USART communication for
now.

Additionally, include a `prelude` for reexporting commonly needed traits
again.

This crate, similarly to atmega-hal, exposes its own `Peripherals`
struct.  This struct uses fields and types more fitting for the selected
board.  For example, the `pins` field has subfields for each of the
boards external pins, named appropriately instead of relying on the MCU
pin names.

Ref: #117
With a unified `arduino-hal`, we cannot keep examples in the crate in
a convenient way.  Instead, let's add dedicated examples crate for each
board which demonstrate usage of `arduino-hal`.

Start with a blinky and usart communication example.
Add basic (ports & usart) support for ATmega32U4 to atmega-hal.
Add basic support for Arduino Leonardo.
Add the `cfg(feature = "board-selected")` guard to the prelude module as
well to prevent spurious error messages when no board was selected (we
only want the "no board selected" error to show up).
Test-compile the HAL crates for MCUs which do not have a board to build
tests for.
It seems the approach of defining a custom `Peripherals` struct does not
scale well: We'd need to replicate all the fields from the respective
MCUs `Peripherals` struct to provide a usable API.  But doing so would
be a huge effort.

Instead, look for a design where the custom `Peripherals` is not needed.

As a first step, convert the `Pins` initialization to a macro-based
approach.  A `pins!()` macro is provided which moves the relevant fields
out of the `Peripherals` struct.  This must be a macro because it must
happen as part of the `main()` function where the `Peripherals` instance
can linger in its partially moved state.
Also drop the custom `Peripherals` struct which is found in the
`arduino-hal`.  Provide the same `pins!()` macro here as well, just with
board pins instead of MCU pins.
Use the new pins initialization which is based on a macro in all blink
examples.
Because HAL crates neither own the `UsartOps` trait nor the `USARTn`
instance, they are not allowed to implement it for the type.  However,
the orphan rules allow us to deal with this by adding a generic
parameter to `UsartOps` which is local to the HAL crate.

The new `H` parameter serves exactly this purpose and nothing more.
A HAL should define a type and use it for `H` in all HAL
implementations.  Ideally, it should also export type-aliases for all
types from `avr-hal-generic` with the `H` parameter already substituted.
`UsartOps` is no longer meant to be implemented on newtype-wrappers and
as such the .0 field accessor is now superfluous.

This partially reverts commit 9c33514 ("generic: usart: Introduce
a type-parameter for orphan circumvention").
Drop the RawPeripheral() wrapper type and instead use a marker called
`Atmega` to deal with the orphan rule.  Update macro invocations to fit
with the new design in avr-hal-generic.
Use the new `pins!()` macro.
Merge the two separates jobs into a single matrix.  This means the
`fail-fast` will abort all pending jobs instead of just the ones in the
respective category.
Having the input mode encoded in the type is useful for static
guarantees but cumbersome in situations where one does not care.

Provide a way to "erase" the type-information about input mode, by way
of a `.forget_imode()` method.  The resulting type behaves just like
a normal input pin except that pull-up and floating pins have the same
type.
drmorr0 and others added 19 commits May 1, 2021 10:54
Make the receiving code more similar to the sending code.
On boards where a reset is needed (currently `leonardo` and `promicro`),
show descriptive instructions on how to reset the board.
Update pin names to really match what's on the board.
Once more than one HAL crates is included, it would be impossible to
have a single `rt` feature for the runtime (see [1]).  Fortunately this
can be sidestepped by importing the runtime directly from avr-device
instead of catching the reexport from the HAL.

[1]: #179 (comment)
Add proper information that reflects the new state of affairs.  Instead
of the step-by-step, link to a full template to ease the process of
creating new projects.

Also include an overview of the new crate structure.
We want our own error to be shown instead, so disable the one from
avr-device, similar to what we do with the HAL crate.
Build documentation for relevant crates in the new, refactored
architecture.
gauteh and others added 8 commits July 10, 2021 10:11
…es without serial port)

ravedude: trinketpro -> trinket-pro
We don't want people using the nightly override from the repository root
for ravedude - the tool is meant to be compiled with stable rust.  To
prevent accidental use of the nightly toolchain, add a second override
file in `ravedude/` to make use of the stable compiler.
Show how to write a custom panic handler.  Update the implementation to
be more device-agnostic to make it easier to reuse the code with other
boards.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants