stm32-rs / stm32-usbd Goto Github PK

usb-device implementation for STM32 microcontrollers

Home Page: https://crates.io/crates/usb-device

License: MIT License

Rust 100.00%

stm32-usbd's Introduction

STM32 Peripheral Access Crates

This repository provides Rust device support crates for all STM32 microcontrollers, providing a safe API to that device's peripherals using svd2rust and a community-built collection of patches to the basic SVD files. There is one crate per device family, and each supported device is a feature-gated module in that crate. These crates are commonly known as peripheral access crates or "PACs".

To view the generated code that makes up each crate, visit the stm32-rs-nightlies repository, which is automatically rebuilt on every commit to stm32-rs master. The stm32-rs repository contains the patches to the underlying SVD files and the tooling to generate the crates.

While these crates are widely used, not every register of every device will have been tested on hardware, and so errors or omissions may remain. We can't make any guarantee of correctness. Please report any bugs you find!

You can see current coverage status for each chip here. Coverage means that individual fields are documented with possible values, but even devices with low coverage should have every register and field available in the API. That page also allows you to drill down into each field on each register on each peripheral.

Using Device Crates In Your Own Project

In your own project's Cargo.toml:

[dependencies.stm32f4]
version = "0.15.1"
features = ["stm32f405", "rt"]

The rt feature is optional but helpful. See svd2rust for details.

Then, in your code:

use stm32f4::stm32f405;

let mut peripherals = stm32f405::Peripherals::take().unwrap();

Refer to svd2rust documentation for further usage.

Replace stm32f4 and stm32f405 with your own device; see the individual crate READMEs for the complete list of supported devices. All current STM32 devices should be supported to some level.

Using Latest "Nightly" Builds

Whenever the master branch of this repository is updated, all device crates are built and deployed to the stm32-rs-nightlies repository. You can use this in your Cargo.toml:

[dependencies.stm32f4]
git = "https://github.com/stm32-rs/stm32-rs-nightlies"
features = ["stm32f405", "rt"]

The nightlies should always build and be as stable as the latest release, but contain the latest patches and updates.

Generating Device Crates / Building Locally

Install svd2rust, svdtools, and form:
- On x86-64 Linux, run make install to download pre-built binaries at the current version used by stm32-rs
- Otherwise, build using cargo (double check versions against scripts/tool_install.sh):
  - cargo install form --version 0.12.1
  - cargo install svdtools --version 0.3.18
  - cargo install svd2rust --version 0.33.4
Install rustfmt: rustup component add rustfmt
Generate patched SVD files: make patch (you probably want -j for all make invocations)
- Alternatively you could install cargo-make runner and then use it instead of make. Works on MS Windows natively:
  - cargo install cargo-make
  - cargo make patch
Generate svd2rust device crates: make svd2rust
Optional: Format device crates: make form

Motivation and Objectives

This project serves two purposes:

Create a source of high-quality STM32 SVD files, with manufacturer errors and inconsistencies fixed. These files could be used with svd2rust or other tools, or in other projects. They should hopefully be useful in their own right.
Create and publish svd2rust-generated crates covering all STM32s, using the SVD files.

When this project began, many individual crates existed for specific STM32 devices, typically maintained separately with hand-edited updates to the SVD files. This project hopes to reduce that duplication of effort and centralise the community's STM32 device support in one place.

Helping

This project is still young and there's a lot to do!

More peripheral patches need to be written, most of all. See what we've got in peripherals/ and grab a reference manual!
Also everything needs testing, and you can't so easily automate finding bugs in the SVD files...

Supported Device Families

Please see the individual crate READMEs for the full list of devices each crate supports. All SVDs released by ST for STM32 devices are covered, so probably your device is supported to some extent!

Devices that are nearly identical, like the STM32F405/F415, are supported by ST under a single SVD file STM32F405, so if you can't find your exact device check if its sibling is supported instead. The crate READMEs make this clear.

Many peripherals are not yet patched to provide the type-safe friendly-name interface (enumerated values); please consider helping out with this!

Check out the full list of supported devices here.

Adding New Devices

Update SVD zips in svd/vendor to include new SVDs.
Run make extract to extract the new zip files.
Add new YAML file in devices/ with the new SVD path and include any required SVD patches for this device, such as renaming or merging fields.
Add the new devices to stm32_part_table.yaml.
Add the new devices to scripts/makecrates.py.
You can run scripts/matchperipherals.py script to find out what existing peripherals could be cleanly applied to this new SVD. If they look sensible, you can include them in your device YAML. This requires a Python environment with the pyyaml and svdtools dependencies. Example command: python scripts/matchperipherals.py peripherals/rcc devices/stm32h562.yaml
Re-run scripts/makecrates.py devices/ to update the crates with the new devices.
Run make to rebuild, which will make a patched SVD and then run svd2rust on it to generate the final library.

If adding a new STM32 family (not just a new device to an existing family), complete these steps as well:

Add the new devices to the CRATES field in Makefile.
Update this Readme to include the new devices.
Add the devices to workflows/ci.yaml and workflows/nightlies.yaml.

Updating Existing Devices/Peripherals

Using Linux, run make extract at least once to pull the SVDs out.
Edit the device or peripheral YAML (see below for format).
Using Linux, run make to rebuild all the crates using svd patch and svd2rust.
Test your new stuff compiles: cd stm32f4; cargo build --features stm32f405

If you've added a new peripheral, consider using the matchperipherals.py script to see which devices it would cleanly apply to.

To generate a new peripheral file from scratch, consider using periphtemplate.py, which creates an empty peripheral file based on a single SVD file, with registers and fields ready to be populated. For single bit wide fields with names ending in 'E' or 'D' it additionally generates sample "Enabled"/"Disabled" entries to save time.

Device and Peripheral YAML Format

Please see the svdtools documentation for full details of the patch file format.

Style Guide

Enumerated values should be named in the past tense ("enabled", "masked", etc).
Descriptions should start with capital letters but do not end with a period

Releasing

Notes for maintainers:

Create PR preparing for new release:
- Update CHANGELOG.md with changes since last release and new contributors
- Update README.md to bump version number in example snippet
- Update scripts/makecrates.py to update version number for generated PACs
Merge PR once CI passes, pull master locally.
make clean
make -j16 form
for f in stm32f0 stm32f1 stm32f2 stm32f3 stm32f4 stm32f7 stm32h7 stm32l0 stm32l1 stm32l4 stm32l5 stm32g0 stm32g4 stm32mp1 stm32wl stm32wb; cd $f; pwd; cargo publish --allow-dirty --no-default-features; cd ..; end
git tag -a vX.X.X -m vX.X.X
git push vX.X.X

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

stm32-usbd's People

Contributors

Stargazers

Watchers

stm32-usbd's Issues

Avoid breaking changes when one hal is upgraded

An idea for solving this problem. I had this idea reading atsamd-rs/atsamd#11 (comment)

A trait (or a set of trait) is present in a dedicated crate that expose the low level stm32 usb api of the hardware. Each hal provide a simple constructor that create a struct that implement this trait. Then, the stm32-usbd provide a constructor that take a type implementing the trait and do the hard stuffs.

Breaking changes in the hal is then transparent to stm32-usbd, it's only coupled with the crate describing the trait. This trait, as a trivial proxy of the hardware, should be stable (as the -sys crates).

I have no idea of the implementation of this crate, so I may tell something not doable, but in case it's working, I share the idea.

stm32-usbd shows surprising errors just by being mentioned in the Cargo.toml

stm32-usbd throws tons of errors just by being mentioned in the Cargo.toml without target feature. This makes it somewhat hard to use in a crate which targets multiple targets where USB support may actually not available. It would be nice to have a "no-op" target which still allows the crate the be in the dependencies even without being used.

Further it would be a lot more user friendly if those non-saying error messages would actually hint at the real problem...

   Compiling stm32-usbd v0.3.1
error[E0432]: unresolved import `crate::target::UsbAccessType`
 --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/endpoint.rs:5:40
  |
5 | use crate::target::{UsbRegisters, usb, UsbAccessType};
  |                                        ^^^^^^^^^^^^^ no `UsbAccessType` in `target`

error[E0432]: unresolved imports `crate::target::UsbAccessType`, `crate::target::EP_MEM_SIZE`
 --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/endpoint_memory.rs:3:21
  |
3 | use crate::target::{UsbAccessType, EP_MEM_ADDR, EP_MEM_SIZE, NUM_ENDPOINTS};
  |                     ^^^^^^^^^^^^^               ^^^^^^^^^^^ no `EP_MEM_SIZE` in `target`
  |                     |
  |                     no `UsbAccessType` in `target`

error[E0432]: unresolved import `crate::target::USB`
 --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/bus.rs:9:21
  |
9 | use crate::target::{USB, apb_usb_enable, NUM_ENDPOINTS, UsbRegisters, UsbPins};
  |                     ^^^ no `USB` in `target`

error[E0432]: unresolved import `crate::target::usb_pins`
  --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/lib.rs:17:24
   |
17 | pub use crate::target::usb_pins::UsbPinsType;
   |                        ^^^^^^^^ could not find `usb_pins` in `target`

error[E0433]: failed to resolve: use of undeclared type or module `hal`
  --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/target.rs:58:31
   |
58 |         let rcc = unsafe { (&*hal::stm32::RCC::ptr()) };
   |                               ^^^ use of undeclared type or module `hal`

error[E0433]: failed to resolve: use of undeclared type or module `USB`
  --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/target.rs:76:19
   |
76 |         let ptr = USB::ptr() as *const Self::Target;
   |                   ^^^ use of undeclared type or module `USB`

error[E0433]: failed to resolve: use of undeclared type or module `USB`
  --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/target.rs:87:23
   |
87 |         let usb_ptr = USB::ptr() as *const usb::RegisterBlock;
   |                       ^^^ use of undeclared type or module `USB`

error[E0412]: cannot find type `USB` in this scope
  --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/target.rs:70:25
   |
70 | pub struct UsbRegisters(USB);
   |                         ^^^ not found in this scope

error[E0412]: cannot find type `USB` in this scope
  --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/stm32-usbd-0.3.1/src/target.rs:82:21
   |
82 |     pub fn new(usb: USB) -> Self {
   |                     ^^^ not found in this scope

error: aborting due to 9 previous errors

Support for simultaneous CAN operation

Allow single-threaded use without critical sections?

I have a hard-real-time firmware application that is implemented with RTIC on an STM32F303. I am using the USB interface to provide secondary (non-real-time) diagnostic capabilities. I poll the UsbDevice in my idle task (i.e. the main loop), which results in entirely adequate performance. I do not use USB interrupts and I never access the UsbDevice from an interrupt context. It looks something like this:

#[idle]
fn idle(_: idle::Context) -> ! {
    let mut usb_dev = UsbDeviceBuilder::new(...);
    loop {
        usb_dev.poll(...);
        // read & write from the endpoints
    }
}

#[task(binds = EXTI1)]
fn hard_real_time(_: hard_real_time::Context) {
    very_fast_thing();
}

Unfortunately, my hard-real-time interrupt handlers (which are only a few microseconds long) experience hundreds of microseconds of timing jitter due to the interrupts-disabled critical sections (cortex_m::interrupt::free) which are found throughout stm32-usbd.

For my project, I patched in my own version of stm32-usbd which removes all of the critical sections:
https://github.com/dlaw/stm32-usbd-no-cs
I have confirmed that it works for me and solves my problem.

I am wondering if there is a safe way to make this functionality available from the stm32-usbd crate, as an official feature which could be selected via Cargo. I could contribute a patch if given some pointers about the best way to implement this. (e.g. is it a feature to remove critical sections, or a feature to add critical sections?)

Unfortunately, the UsbBus trait bound requires Sync, which means I had to provide a bogus impl Sync for Endpoint. I would much prefer to end up with a non-Sync UsbBus when critical sections are not used, as otherwise the safety guarantees of the Rust language are violated. But it seems this would require a change to https://github.com/rust-embedded-community/usb-device as well.

STM32F070RB: Enumeration fails with CDC example

I am using a STM32F070 nucleo board and spliced-in USB cable, and the USB descriptors are not able to be read during enumeration on both Linux and Windows.

I confirmed that the hardware works by loading the ST CubeMX USB software.

I have had to patch the stm32f0xx HAL to configure the USB clock (everything is merged upstream/released now).

USB CDC is being used, based on the example in the F0xx HAL crate:
https://gist.github.com/pigrew/f3493ac8ec9c84bf1a2966c2396972b7

I'm compiling with Rust 1.41.

Based on WireShark (logging USB on Windows 10), the device descriptor is transferred, but the GET_CONFIGURATION(ix=0) request has a zero-length response packet (the response should have 9 bytes).

a single hid class didn't work

hid.rs:

use core::cmp::min;
use usb_device::Result;
use usb_device::bus::{InterfaceNumber, StringIndex, UsbBus, UsbBusAllocator};
use usb_device::class::{ControlIn, ControlOut, UsbClass};
use usb_device::control;
use usb_device::control::{Recipient, RequestType};
use usb_device::descriptor::DescriptorWriter;
use usb_device::endpoint::{EndpointAddress, EndpointIn, EndpointOut};
use usb_device::UsbError;
//use cortex_m_semihosting::hprintln;

pub const USB_CLASS_HID: u8 = 0x03;

const REPORT_DESCRIPTOR: &[u8] = &[
    0x06, 0xD0, 0xF1,  // Usage Page (Reserved 0xF1D0)
    0x09, 0x01,        // Usage (0x01)
    0xA1, 0x01,        // Collection (Application)
    0x09, 0x20,        //   Usage (0x20)
    0x15, 0x00,        //   Logical Minimum (0)
    0x26, 0xFF, 0x00,  //   Logical Maximum (255)
    0x75, 0x08,        //   Report Size (8)
    0x95, 0x40,        //   Report Count (64)
    0x81, 0x02,        //   Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
    0x09, 0x21,        //   Usage (0x21)
    0x15, 0x00,        //   Logical Minimum (0)
    0x26, 0xFF, 0x00,  //   Logical Maximum (255)
    0x75, 0x08,        //   Report Size (8)
    0x95, 0x40,        //   Report Count (64)
    0x91, 0x02,        //   Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
    0xC0,              // End Collection
];

pub struct HidClass<'a, B: UsbBus> {
    intf: InterfaceNumber,
    read_ep: EndpointOut<'a, B>,
    write_ep: EndpointIn<'a, B>,
    buf: [u8; 65],
    len: usize,
}


impl<B: UsbBus> HidClass<'_, B> {
    pub fn new(alloc: &UsbBusAllocator<B>) -> HidClass<'_, B> {
        HidClass {
            intf: alloc.interface(),
            read_ep: alloc.interrupt(8, 10),
            write_ep: alloc.interrupt(8, 10),
            buf: [0; 65],
            len: 0,
        }
    }

    pub fn write(&mut self, data: &[u8]) -> Result<usize> {
        match self.write_ep.write(data) {
            Ok(count) => Ok(count),
            Err(UsbError::WouldBlock) => Ok(0),
            e => e,
        }
    }

    pub fn read(&mut self, data: &mut [u8]) -> Result<usize> {
        // Terrible buffering implementation for brevity's sake

        if self.len == 0 {
            self.len = match self.read_ep.read(&mut self.buf) {
                Ok(0) | Err(UsbError::WouldBlock) => return Ok(0),
                Ok(count) => count,
                e => return e,
            };
        }

        let count = min(data.len(), self.len);

        &data[..count].copy_from_slice(&self.buf[0..count]);

        self.buf.rotate_left(count);
        self.len -= count;

        Ok(count)
    }
}

impl<B: UsbBus> UsbClass<B> for HidClass<'_, B> {
    fn get_configuration_descriptors(&self, writer: &mut DescriptorWriter) -> Result<()> {
        writer.interface(
            self.intf,
            3, //USB_CLASS_HID,
            0,
            0)?;

        let descriptor_len = REPORT_DESCRIPTOR.len();
        //hprintln!("report len: {}", descriptor_len).unwrap();
        let descriptor_len = (descriptor_len as u16).to_le_bytes();
        writer.write(
            0x21,
            &[0x10, 0x01, 0x21, 0x01, 0x22, descriptor_len[0], descriptor_len[1]]
        )?;

        writer.endpoint(&self.write_ep)?;
        writer.endpoint(&self.read_ep)?;
        //hprintln!("get_configuration_descriptors!").unwrap();
        Ok(())
    }

    fn endpoint_in_complete(&mut self, _addr: EndpointAddress) {
        //hprintln!("endpoint_in_complete!").unwrap();
    }

    fn control_in(&mut self, xfer: ControlIn<B>) {
        let req = xfer.request();
        match (req.request_type, req.recipient) {
            (RequestType::Standard, Recipient::Interface) => {
                //hprintln!("control_in!").unwrap();
                if req.request == control::Request::GET_DESCRIPTOR {
                    let (dtype, index) = req.descriptor_type_index();
                    if dtype == 0x22 && index == 0 {
                        let descriptor = REPORT_DESCRIPTOR;
                        xfer.accept_with(descriptor).ok();
                    }
                }
            }
            _ => {}
        }
    }
}

main.rs:

#![no_std]
#![no_main]

extern crate panic_semihosting; // logs messages to the host stderr; requires a debugger

use cortex_m::asm::delay;
use cortex_m_rt::entry;
use stm32f1xx_hal::{prelude::*, stm32};

use usb_device::prelude::*;
use stm32_usbd::UsbBus;
//use cortex_m_semihosting::hprintln;

mod hid;
mod vendor;
const VID: u16 = 0x1122;
const PID: u16 = 0x3344;

#[entry]
fn main() -> ! {
    let dp = stm32::Peripherals::take().unwrap();

    let mut flash = dp.FLASH.constrain();
    let mut rcc = dp.RCC.constrain();

    let clocks = rcc
        .cfgr
        .use_hse(8.mhz())
        .sysclk(48.mhz())
        .pclk1(24.mhz())
        .freeze(&mut flash.acr);

    assert!(clocks.usbclk_valid());

    let mut gpioa = dp.GPIOA.split(&mut rcc.apb2);

    // BluePill board has a pull-up resistor on the D+ line.
    // Pull the D+ pin down to send a RESET condition to the USB bus.
    let mut usb_dp = gpioa.pa12.into_push_pull_output(&mut gpioa.crh);
    usb_dp.set_low();
    delay(clocks.sysclk().0 / 100);

    let usb_dm = gpioa.pa11;
    let usb_dp = usb_dp.into_floating_input(&mut gpioa.crh);

    let usb_bus = UsbBus::new(dp.USB, (usb_dm, usb_dp));

    let mut hid = hid::HidClass::new(&usb_bus);
    //let mut vendor = vendor::HidClass::new(&usb_bus);

    // vid/pid: http://pid.codes/1209/CC1D/
    let mut usb_dev = UsbDeviceBuilder::new(
            &usb_bus,
            UsbVidPid(VID, PID),
        )
        .manufacturer("bitbegin")
        .product("hid")
        .serial_number("12345678")
        //.device_class(3)
        .build();
    //hprintln!("reset!").unwrap();
    //usb_dev.force_reset().expect("reset failed");

    let mut buf = [0u8; 65];
    loop {
        if !usb_dev.poll(&mut [&mut hid, &mut vendor]) {
            continue;
        }

        match hid.read(&mut buf) {
            Ok(count) if count > 0 => {
                // Echo back in upper case

                hid.write(&buf[0..count]).ok();
            },
            _ => { },
        }
    }
}

this will result in c0000011 - "xact error".

if add device_class(0xff) to UsbDeviceBuilder, it will be detected by Windows. but i want to use hidapi, so how to configure hid-class?

Device Triggered Wakeup of the Host

I am implementing the Keyberon crate that uses stm32-usbd as a dependency and am struggling to get my firmware to wake-up my computer from suspend. Looking at other libraries, I believe this is implemented with register level access in the MCU.

This could be a trait from usb_device, but I don't think it is implemented in all micro controller USB devices. The Zephyr "Trait" like implementation is here.

Zephyr STM32 HAL Implementation
ChibiOS STM32 HAL Implementation

I do not believe this is satisfied with the current suspend and resume method as those manipulate the fsusp bit of the cntr register, but I believe a device sent wakeup to the host would be manipulating the resume bit of the cntr register.

Does this seem like something that could be implemented? Should it be stm32 specific or be an implemented trait?

STM32F3Discovery fails to enumerate using 0.4 or 0.5 (works fine with 0.3)

This can be reproduced using the stm32-usbd-examples repo. If you follow the steps in the README.md file everything runs as expected since it uses stm32-usbd 0.3.

If you edit Cargo.toml to upgrade stm32-usbd to 0.4 (and upgrade stm32f3xx-hal to 0.3 as required) the code compiles without any errors (although there are a few warnings about unused Results). The device fails to enumerate correctly. This results in the "USB device not recognised" popup on Windows 10, and according to Device Manager "A request for the USB device descriptor failed". The same thing happens with 0.5.

I don't have much experience with USB stuff so I don't even know where to get started tracking this down, but I'm happy to help with a fix/PR.

Tag for version 0.5.0 is missing

This repository doesn't contain a tag for the latest released version, 0.5.0. 0cd7c1a looks like it might be the right commit.

Request release

So deps can release on Crates.io. Thx! #33

MIT license compliance w.r.t. embedded applications

:"Original" issue is at rust-embedded-community/usb-device#52, but I wanted to open an issue here as well, because this crate is also MIT-licensed.

I would love to use this in my embedded projects, but I'm not comfortable using MIT-licensed code in such applications, because of the condition:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

Granted, it does just say "included", not "displayed", so I guess I could include the license somewhere in the firmware binary and it would be okay? But I feel like being able to view the license is somewhat implied, so I'm not satisfied with this.

In many embedded applications, there's no easy way to prominently "display" license notices like this, and I think the (implied) obligation to do so is an unreasonable burden. For example, if I'm writing firmware for a simple keyboard or mouse, how would I display the license notice from the device?

So, I think MIT is not a great fit for libraries used in the embedded ecosystem. Alternatively, I would suggest dual-licensing with the Apache-2.0 license, as that is what the Rust Embedded WG (and much of the wider Rust ecosystem) does, as the Apache-2.0 license only requires a license notice for copies of the source code form.

Trigger reset upon initialization

There is the bus::UsbBus::force_reenumeration(), but strangely, UsbBus::new() does not give direct access to UsbBus.

Is there any [other] way to do this?

Thanks for this great crate.

Support for STM OTG_FS core present in STM32F4xx (and higher) series microcontrollers

Eg. the STM32F446xx family has OTG_FS and OTG_HS cores which can function both as peripheral and host (for USB OTG). I would like to be able to use this crate with the OTG_FS core in peripheral mode. I can help with the implementation, but will need some pointers on where to start.

I'm currently trying to find out more about the OTG_FS core itself.