Porting Guide

This guide explains how to add support for new chips using MUSB.

Known chips using MUSB IP

Manufacturer	Chips (not fully listed)	IP
Texas Instruments	am335x,am1802, F2837xD, LM3S6911	musb**
Allwinner(全志)	F1C100S, F133	musb phy ip
SiFli (思澈)	SF32LB52x	musb std*
beken (北科微 or 小博通)	beken725x	musb std*
essemi (东软载波微)	ES32F027x	musb std*
jieli (杰理)		musb**
SPRD	sp7862	musb**
MediaTek	MT6735	musb**
Puya (普冉)	py32f071, py32f403	musb mini*
STC (姚永平)	stc8, stc32, ai8051u	musb mini*

*: Not sure about the IP name

**: Further identification is needed

Overview

MUSB uses YAML files to describe register layouts and chip-specific configurations.

Creating a New Profile

Identify Your Chip
- Registers start with POWER, FADDR (though not always at the beginning)
- Most registers are 8-bit (some manufacturers group them into 32-bit, but it's usually clear they're composed of 8-bit registers)
- An INDEX register exists, requiring setting before endpoint operations. EP0 registers are separate, other endpoints use TXCSRH, TXCSRL, RXCSRH, RXCSRL (or IN_CSR1, IN_CSR2, OUT_CSR1, OUT_CSR2)
- Compare with block-peri-std to confirm register similarity

Create Profile YAML

To write a profile, please refer to existing profiles and serialization-related data types

Example: the PY32F07x profile example.

# Example profile structure
name: my_chip
block: peri_std
base_address: 0x40005c00
base_address: 0x40005c00
fifo:
  type: fixed
  shared: false
reg_bit_size:
  fifo: 8
  intr: 8
endpoints:
  - type: rxtx
    max_packet_size_dword: 8
  - type: rxtx
    max_packet_size_dword: 8

Register Definitions

Each manufacturer's SVD or manual exhibits significant register name variations, despite functional consistency. This crate uses standard MUSB register names.

The crate describes registers using YAML, with these register description files manually maintained. It then leverages chiptool and yaml2pac to generate register operation functions. These operations can be found in the build.rs file.

These replacements are automatically generated from profile contents and can be used in register description YAML files.
- ENDPOINTS_NUM
  
  profile.endpoints.len()
- FIFO_REG_BIT_SIZE
  
  profile.reg_bit_size.fifo
  
  Note: This does not change the offset.
- INTR_REG_BIT_SIZE
  
  profile.reg_bit_size.intr
  
  Note: This does not change the offset.

Integrate this crate into a HAL crate

Examples

py32-hal/src/usb.rs · py32-rs/py32-hal

Instance

Every struct in this crate has a generic parameter T: MusbInstance:

pub trait MusbInstance: 'static {
    fn regs() -> regs::Usb;
}

If the profile contains a base_address field, you can directly use:

let musb_driver = musb::Driver::<musb::UsbInstance>(new);

musb::UsbInstance is a struct that has already implemented the MusbInstance trait based on base_address.

If not, you need to create this type:

pub struct UsbInstance;
impl musb::MusbInstance for UsbInstance {
    fn regs() -> musb::regs::Usb {
        unsafe { musb::regs::Usb::from_ptr((0x40005c00) as _ ) }
    }
}

Driver

This crate includes a MusbDriver that has methods from embassy_usb_driver::Driver but doesn't implement it. The intention is for HAL libraries to create a Driver that wraps MusbDriver to handle platform-specific peripheral initialization. Please refer to the Examples section.

Then

Contribution back is welcome!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!