docs: document public apis for cyw43 driver

This commit is contained in:
Ulf Lilleengen 2023-12-19 16:08:06 +01:00 committed by Dario Nieuwenhuis
parent e65d6fa698
commit 1df1f8e742
7 changed files with 67 additions and 2 deletions

17
cyw43-pio/README.md Normal file
View File

@ -0,0 +1,17 @@
# cyw43-pio
RP2040 PIO driver for the nonstandard half-duplex SPI used in the Pico W. The PIO driver offloads SPI communication with the WiFi chip and improves throughput.
## Minimum supported Rust version (MSRV)
Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
## License
This work is licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
<http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.

View File

@ -1,5 +1,7 @@
#![no_std]
#![allow(async_fn_in_trait)]
#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
use core::slice;
@ -11,6 +13,7 @@ use embassy_rp::{Peripheral, PeripheralRef};
use fixed::FixedU32;
use pio_proc::pio_asm;
/// SPI comms driven by PIO.
pub struct PioSpi<'d, CS: Pin, PIO: Instance, const SM: usize, DMA> {
cs: Output<'d, CS>,
sm: StateMachine<'d, PIO, SM>,
@ -25,6 +28,7 @@ where
CS: Pin,
PIO: Instance,
{
/// Create a new instance of PioSpi.
pub fn new<DIO, CLK>(
common: &mut Common<'d, PIO>,
mut sm: StateMachine<'d, PIO, SM>,
@ -143,6 +147,7 @@ where
}
}
/// Write data to peripheral and return status.
pub async fn write(&mut self, write: &[u32]) -> u32 {
self.sm.set_enable(false);
let write_bits = write.len() * 32 - 1;
@ -170,6 +175,7 @@ where
status
}
/// Send command and read response into buffer.
pub async fn cmd_read(&mut self, cmd: u32, read: &mut [u32]) -> u32 {
self.sm.set_enable(false);
let write_bits = 31;

View File

@ -45,6 +45,10 @@ nc 192.168.0.250 1234
```
Send it some data, you should see it echoed back and printed in the firmware's logs.
## Minimum supported Rust version (MSRV)
Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
## License
This work is licensed under either of

View File

@ -12,17 +12,23 @@ use crate::ioctl::{IoctlState, IoctlType};
use crate::structs::*;
use crate::{countries, events, PowerManagementMode};
/// Control errors.
#[derive(Debug)]
pub struct Error {
/// Status code.
pub status: u32,
}
/// Multicast errors.
#[derive(Debug)]
pub enum AddMulticastAddressError {
/// Not a multicast address.
NotMulticast,
/// No free address slots.
NoFreeSlots,
}
/// Control driver.
pub struct Control<'a> {
state_ch: ch::StateRunner<'a>,
events: &'a Events,
@ -38,6 +44,7 @@ impl<'a> Control<'a> {
}
}
/// Initialize WiFi controller.
pub async fn init(&mut self, clm: &[u8]) {
const CHUNK_SIZE: usize = 1024;
@ -154,6 +161,7 @@ impl<'a> Control<'a> {
self.ioctl(IoctlType::Set, IOCTL_CMD_DOWN, 0, &mut []).await;
}
/// Set power management mode.
pub async fn set_power_management(&mut self, mode: PowerManagementMode) {
// power save mode
let mode_num = mode.mode();
@ -166,6 +174,7 @@ impl<'a> Control<'a> {
self.ioctl_set_u32(86, 0, mode_num).await;
}
/// Join an unprotected network with the provided ssid.
pub async fn join_open(&mut self, ssid: &str) -> Result<(), Error> {
self.set_iovar_u32("ampdu_ba_wsize", 8).await;
@ -183,6 +192,7 @@ impl<'a> Control<'a> {
self.wait_for_join(i).await
}
/// Join an protected network with the provided ssid and passphrase.
pub async fn join_wpa2(&mut self, ssid: &str, passphrase: &str) -> Result<(), Error> {
self.set_iovar_u32("ampdu_ba_wsize", 8).await;
@ -250,16 +260,19 @@ impl<'a> Control<'a> {
}
}
/// Set GPIO pin on WiFi chip.
pub async fn gpio_set(&mut self, gpio_n: u8, gpio_en: bool) {
assert!(gpio_n < 3);
self.set_iovar_u32x2("gpioout", 1 << gpio_n, if gpio_en { 1 << gpio_n } else { 0 })
.await
}
/// Start open access point.
pub async fn start_ap_open(&mut self, ssid: &str, channel: u8) {
self.start_ap(ssid, "", Security::OPEN, channel).await;
}
/// Start WPA2 protected access point.
pub async fn start_ap_wpa2(&mut self, ssid: &str, passphrase: &str, channel: u8) {
self.start_ap(ssid, passphrase, Security::WPA2_AES_PSK, channel).await;
}
@ -494,13 +507,14 @@ impl<'a> Control<'a> {
}
}
/// WiFi network scanner.
pub struct Scanner<'a> {
subscriber: EventSubscriber<'a>,
events: &'a Events,
}
impl Scanner<'_> {
/// wait for the next found network
/// Wait for the next found network.
pub async fn next(&mut self) -> Option<BssInfo> {
let event = self.subscriber.next_message_pure().await;
if event.header.status != EStatus::PARTIAL {

View File

@ -2,6 +2,8 @@
#![no_main]
#![allow(async_fn_in_trait)]
#![deny(unused_must_use)]
#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
// This mod MUST go first, so that the others see its macros.
pub(crate) mod fmt;
@ -102,6 +104,7 @@ const CHIP: Chip = Chip {
chanspec_ctl_sb_mask: 0x0700,
};
/// Driver state.
pub struct State {
ioctl_state: IoctlState,
ch: ch::State<MTU, 4, 4>,
@ -109,6 +112,7 @@ pub struct State {
}
impl State {
/// Create new driver state holder.
pub fn new() -> Self {
Self {
ioctl_state: IoctlState::new(),
@ -118,6 +122,7 @@ impl State {
}
}
/// Power management modes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PowerManagementMode {
/// Custom, officially unsupported mode. Use at your own risk.
@ -203,8 +208,13 @@ impl PowerManagementMode {
}
}
/// Embassy-net driver.
pub type NetDriver<'a> = ch::Device<'a, MTU>;
/// Create a new instance of the CYW43 driver.
///
/// Returns a handle to the network device, control handle and a runner for driving the low level
/// stack.
pub async fn new<'a, PWR, SPI>(
state: &'a mut State,
pwr: PWR,

View File

@ -34,6 +34,7 @@ impl Default for LogState {
}
}
/// Driver communicating with the WiFi chip.
pub struct Runner<'a, PWR, SPI> {
ch: ch::Runner<'a, MTU>,
bus: Bus<PWR, SPI>,
@ -222,6 +223,7 @@ where
}
}
/// Run the
pub async fn run(mut self) -> ! {
let mut buf = [0; 512];
loop {

View File

@ -4,13 +4,16 @@ use crate::fmt::Bytes;
macro_rules! impl_bytes {
($t:ident) => {
impl $t {
/// Bytes consumed by this type.
pub const SIZE: usize = core::mem::size_of::<Self>();
/// Convert to byte array.
#[allow(unused)]
pub fn to_bytes(&self) -> [u8; Self::SIZE] {
unsafe { core::mem::transmute(*self) }
}
/// Create from byte array.
#[allow(unused)]
pub fn from_bytes(bytes: &[u8; Self::SIZE]) -> &Self {
let alignment = core::mem::align_of::<Self>();
@ -23,6 +26,7 @@ macro_rules! impl_bytes {
unsafe { core::mem::transmute(bytes) }
}
/// Create from mutable byte array.
#[allow(unused)]
pub fn from_bytes_mut(bytes: &mut [u8; Self::SIZE]) -> &mut Self {
let alignment = core::mem::align_of::<Self>();
@ -204,6 +208,7 @@ pub struct EthernetHeader {
}
impl EthernetHeader {
/// Swap endianness.
pub fn byteswap(&mut self) {
self.ether_type = self.ether_type.to_be();
}
@ -472,19 +477,26 @@ impl ScanResults {
#[repr(C, packed(2))]
#[non_exhaustive]
pub struct BssInfo {
/// Version.
pub version: u32,
/// Length.
pub length: u32,
/// BSSID.
pub bssid: [u8; 6],
/// Beacon period.
pub beacon_period: u16,
/// Capability.
pub capability: u16,
/// SSID length.
pub ssid_len: u8,
/// SSID.
pub ssid: [u8; 32],
// there will be more stuff here
}
impl_bytes!(BssInfo);
impl BssInfo {
pub fn parse(packet: &mut [u8]) -> Option<&mut Self> {
pub(crate) fn parse(packet: &mut [u8]) -> Option<&mut Self> {
if packet.len() < BssInfo::SIZE {
return None;
}