max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge #537

Browse Source 
537: Documents the nRF BufferedUarte problem r=Dirbaio a=huntc

Please see https://github.com/embassy-rs/embassy/issues/536 for the rationale.

Co-authored-by: huntc <huntchr@gmail.com>
This commit is contained in:
bors[bot] 2021-12-12 20:35:43 +00:00 committed by GitHub
commit 052abc918a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 18 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
embassy-nrf/src/buffered_uarte.rs
View File

@ -1,6 +1,17 @@
//! Async buffered UART //! Async buffered UART
//! //!
//! Please ee [uarte] to understand when [BufferedUarte] should be used. //! WARNING!!! The functionality provided here is intended to be used only
//! in situations where hardware flow control are available i.e. CTS and RTS.
//! This is a problem that should be addressed at a later stage and can be
//! fully explained at https://github.com/embassy-rs/embassy/issues/536.
//!
//! Note that discarding a future from a read or write operation may lead to losing
//! data. For example, when using `futures_util::future::select` and completion occurs
//! on the "other" future, you should capture the incomplete future and continue to use
//! it for the next read or write. This pattern is a consideration for all IO, and not
//! just serial communications.
//!
//! Please also see [crate::uarte] to understand when [BufferedUarte] should be used.
use core::cmp::min; use core::cmp::min;
use core::marker::PhantomData; use core::marker::PhantomData;

6
embassy-nrf/src/uarte.rs
View File

@ -2,14 +2,14 @@
//! Async UART //! Async UART
//! //!
//! Async UART is provided in two flavors - this one and also [buffered_uarte::BufferedUarte]. //! Async UART is provided in two flavors - this one and also [crate::buffered_uarte::BufferedUarte].
//! The [Uarte] here is useful for those use-cases where reading the UARTE peripheral is //! The [Uarte] here is useful for those use-cases where reading the UARTE peripheral is
//! exclusively awaited on. If the [Uarte] is required to be awaited on with some other future, //! exclusively awaited on. If the [Uarte] is required to be awaited on with some other future,
//! for example when using `futures_util::future::select`, then you should consider //! for example when using `futures_util::future::select`, then you should consider
//! [buffered_uarte::BufferedUarte] so that reads may continue while processing these //! [crate::buffered_uarte::BufferedUarte] so that reads may continue while processing these
//! other futures. If you do not then you may lose data between reads. //! other futures. If you do not then you may lose data between reads.
//! //!
//! An advantage of the [Uarte] has over [buffered_uarte::BufferedUarte] is that less //! An advantage of the [Uarte] has over [crate::buffered_uarte::BufferedUarte] is that less
//! memory may be used given that buffers are passed in directly to its read and write //! memory may be used given that buffers are passed in directly to its read and write
//! methods. //! methods.

6
examples/nrf/src/bin/buffered_uart.rs
View File

@ -8,7 +8,6 @@ mod example_common;
use embassy::executor::Spawner; use embassy::executor::Spawner;
use embassy::io::{AsyncBufReadExt, AsyncWriteExt}; use embassy::io::{AsyncBufReadExt, AsyncWriteExt};
use embassy_nrf::buffered_uarte::State; use embassy_nrf::buffered_uarte::State;
use embassy_nrf::gpio::NoPin;
use embassy_nrf::{buffered_uarte::BufferedUarte, interrupt, uarte, Peripherals}; use embassy_nrf::{buffered_uarte::BufferedUarte, interrupt, uarte, Peripherals};
use example_common::*; use example_common::*;
use futures::pin_mut; use futures::pin_mut;
@ -24,6 +23,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
let irq = interrupt::take!(UARTE0_UART0); let irq = interrupt::take!(UARTE0_UART0);
let mut state = State::new(); let mut state = State::new();
// Please note - important to have hardware flow control (https://github.com/embassy-rs/embassy/issues/536)
let u = BufferedUarte::new( let u = BufferedUarte::new(
&mut state, &mut state,
p.UARTE0, p.UARTE0,
@ -33,8 +33,8 @@ async fn main(_spawner: Spawner, p: Peripherals) {
irq, irq,
p.P0_08, p.P0_08,
p.P0_06, p.P0_06,
NoPin, p.P0_07,
NoPin, p.P0_05,
config, config,
&mut rx_buffer, &mut rx_buffer,
&mut tx_buffer, &mut tx_buffer,