[RFC] Bouffalolab Vendor Support

[VynDragon]

Introduction

There is community interest to add support for Bouffalolab SoCs in Zephyr. This RFC was opened to serve as an umbrella to help community and Zephyr members know the initiatives.

Problem description

There is a pull request for the initial support: #78795
Work is ongoing for more.

Proposed changes

Give an overview about all pieces required to add Bouffalolab SoCs in Zephyr.

Detailed RFC

In this section of the document the target audience is the dev team. Upon reading this section each engineer should have a rather clear picture of what needs to be done in order to implement the described feature.

Vendor Documentation and SDK

Bouffalolab provides a open source SDK which can be used for reference, especially for peripherals for which the documentation is incomplete or absent. There is some significant amount of documentation available in https://github.com/bouffalolab/bl_docs .

HAL

There is no specific HAL per se for Bouffalolab devices in the public SDK. The materials from the vendor that will be directly used here are the headers, which provide peripheral register details.

CPUs

Bouffalolab SoCs use various CPU designs:

• SiFive (SiFive E24 on BL60x, BL70x and BL70xL)
• Xuantie T-HEAD (E907 on BL61x, and C906, E907, E902 on BL808 and BL606P).

For both SiFive and Xuantie CPUs the reference manuals are public available.

Caches

Xuantie CPUs provide instruction caches and branch prediction. It can be configured via the XTHeadCMO RISCV extension and various CSR. The SiFive E24 do not provide a direct cache instead a peripheral called L1C (Level 1 Cache) is used. It is part of the ITCM from E24 to enable fast instruction fetch. The Bouffalo MCUs should use caching mechanisms to compensate the slow flash page load. When using it can be from 16KB up to 48KB dedicated I-Cache and should be handled with care.

The port will provide the mechanisms and their pitfalls within zephyr will be addressed on:

• the initialization code
• in the flash driver and
• in the BL61x USB driver.

The management is critical in some drivers that interact with Flash and/or DMA.

Availability for developers

• Devboards and modules for BL60x and BL61x are easily available from AI-Thinker, Pine64, and Sipeed via typical channels (Amazon, Aliexpress, LCSC...).
• Devboards and modules for BL70x are sometimes available from XT/DOIT. Some noname boards are also available. It is also embbeded in some Sipeed products, such as the RV-debugger.
• Devboards and modules for BL808 are available from Sipeed and Pine64.
• BL606P is so far only available in the Pine64 PineVox.
• TG7100C is a alternative packaging of BL602, available from AI-Thinker via typical channels.
• Xiaomi offers modules for BL616 and BL602 at https://iot.mi.com/moduleBrowser.html
• Qualcomm offers BL61x as QCC74x.
• Some Cozylife Temperature sensors are supposed to feature BL602L, see https://www.elektroda.com/rtvforum/topic4081863.html for images. This item has been confirmed to feature BL602L10: https://aliexpress.com/item/1005006788062582.html
• BL704L10 is available in this product: https://3reality.com/product/temperature-and-humidity-sensor-lite/, with JTAG and UART already broken out to headers, see FCC ID 2BAGQ-3RTHS0224Z

Peripherals Drivers

Most peripherals are either the same or very similar between SoCs. Due to this, the drivers will be implemented in a way that make them usable on all variants.

Task List

Milestone 0 :

Introduce the vendor.

• HAL repository HAL module request: hal_bouffalolab #84174
• BL60x CPU support Introduce Bouffalo Lab SoC's [patch 1] #84173
  The riscv-privileged arch in CLIC vectored mode will be used
• USART driver Introduce Bouffalo Lab SoC's [patch 1] #84173
• USART interrupts Make BFLB not use the SDK code #91977
• PinCtrl driver Introduce Bouffalo Lab SoC's [patch 1] #84173

Milestone 1:

Migration from SDK v1.4.5 headers to peripheral headers.

• Add new registers files in HAL. The current v1.4.5 will be there in the migration phase. After migration, they will be removed
• Migrate from v1.4.5 headers to new headers Make BFLB not use the SDK code #91977
• BL60x e-fuse driver drivers: syscon: bflb efuses #89108
• BL60x clock driver drivers: clock_control: introduce bl60x clock control #90183
• GPIO driver

Milestone 2:

Finish clean-up

• Update BL60x SoC initialization Make BFLB not use the SDK code #91977
• Drop v1.4.5 headers bflb: Remove SDK files hal_bouffalolab#2

Milestone 3:

• Introduce BL70x SoC
• Add BL70x clock driver

Milestone 4:

• Introduce BL61x SoC
• Add BL61x clock driver

Dependencies

• M0 -> M1 -> [M2 | M3 | M4]
• After M0 new BL60x can be added
• After M2/3/4 new drivers will be welcome for that specific series including:
  • WIFI
  • BLE
  • IEEE 802.15.4

References

SoCs

• BL60x: BL602, BL604 Introduce Bouffalo Lab SoC's [patch 1] #84173
• BL70x: BL702, BL706
  Complete: https://github.com/VynDragon/zephyr/tree/bflb_upstreaming_efuse
• BL61x: BL616, BL618
  Mostly Complete (no AUPLL init): https://github.com/VynDragon/zephyr/tree/bflb/bl61x
  https://github.com/VynDragon/zephyr/tree/bflb/bl61x_usb
• BL70xL: BL702L, BL704L
  Work Started at: https://github.com/VynDragon/zephyr/tree/bflb/bl702l
• BL808
• BL606P
• LF68x: LF686 (BL602), LF688 (BL604)
• TG7100C (BL602): Confirmed working fine with BL60x code.

Boards

• bl604e_iot_dvk (BL604) Introduce Bouffalo Lab SoC's [patch 1] #84173
• dt_bl10_devkit (BL602) boards: doiting: Introduce dt_bl10_devkit #90622
• dt_XT-ZB1-DevKit (BL702)
• ai_WB2-12F-Kit (BL602) boards: Introduce AI-WB2-12F #89049
• ai_WB2-32S-Kit (BL602)
• ai_M62-12F-Kit (BL616)
• ai_M62-32S-Kit (BL616)
• ai_M61-32S-Kit (BL618)
• ai_TG-12F-Kit (TG7100C)
• sipeed_M0P-Dock (BL618)
• sipeed_M0s-Dock (BL616)
• sipeed_M0sense (BL702)
• sipeed_M1s-Dock (BL808)
• pine64_PineVox (BL606P)
• pine64_Ox64 (BL808)
• pine64_PineCone (BL602)
• others_BL702S-Blue (BL702) https://aliexpress.com/item/1005005927910587.html keyword 'BL702S'
• others_BL616-Blue (BL616) https://aliexpress.com/item/1005006916672346.html keyword 'BL616'
• EVK-QCC744M (BL618)
• EVK-QCC743M (BL616)
• X-NUCLEO-67W61M1 (QCC74x -> bl61x)

Drivers

Drivers are 'complete' if they support all currently complete SoCs.

• ADC
  Complete in: https://github.com/VynDragon/zephyr/tree/bflb/bl61x
• Audio ADC
• CAM (DVP)
• Audio DAC
• CANbus Driver BL61x
• DAC
  https://github.com/VynDragon/zephyr/tree/bflb/bl61x but for BL61x
• DBI
• DMA
• Ethernet EMAC
• Efuses (dependency)
  Complete in: https://github.com/VynDragon/zephyr/tree/bflb/bl61x
• Flash Single Bank
  Complete in: https://github.com/VynDragon/zephyr/tree/bflb/bl61x
• Flash Multi Banks
• GPIO FIFO Mode
• I2C
  Complete in: https://github.com/VynDragon/zephyr/tree/bflb/bl61x
• I2S
• IR
• JDEC
• KeyScan
• LINbus
• LPM (Low Power Modes)
  Work Started in: https://github.com/VynDragon/zephyr/tree/bflb/work_bflb
• MJPEG
• PIR Sensor Controller
• PMP
• PSRAM
• PWM
• QDEC (rotary encoders)
• Security Engine/Accelerator
• SDH
• SDIO
• SPI
  Complete in: https://github.com/VynDragon/zephyr/tree/bflb/bl61x
• Timers (!= riscv system timer)
• USB Device BL61x
  Complete in: https://github.com/VynDragon/zephyr/tree/bflb/bl61x_usb
• USB Host BL61x
• USB Device/Host BL808/606P
• USB Device BL70x
• VENC
• BLE BL60x
• BLE BL70x
• BLE BL70xL
• Bluetooth/BLE BL61x
• Bluetooth/BLE BL808/606P
• Wifi Bl60x
• Wifi BL61x
• Wifi BL808/BL606P
• 802.15.4 BL61x
• 802.15.4 BL70x
• 802.15.4 BL70xL
• 802.15.4 BL808/BL606P

Tools

• bflb_mcu_tool scripts: runners: Introduce bflb_mcu_tool runner  #89035

[github-actions]

Hi @VynDragon! We appreciate you submitting your first issue for our open-source project. 🌟

Even though I'm a bot, I can assure you that the whole community is genuinely grateful for your time and effort. 🤖💙

[kristoftjonck]

Great to see this moving forward! I noticed that the Iso11898 (CAN) driver is missing from the peripheral list. I’m not sure which Bouffalolab modules support CAN, but I know the BL61x does. I also spotted a clock initialization for CAN in the Bouffalo SDK for the BL808. It would be great to see support for this added!

[gamelaster]

@kristoftjonck BL61X for sure supports CAN (but as far as I remember, external transceiver is required). I think @VynDragon will add it into the list.

[VynDragon]

Great to see this moving forward! I noticed that the Iso11898 (CAN) driver is missing from the peripheral list. I’m not sure which Bouffalolab modules support CAN, but I know the BL61x does. I also spotted a clock initialization for CAN in the Bouffalo SDK for the BL808. It would be great to see support for this added!

Hi, the thing with the CAN peripheral is that it's been removed from the docs intentionally, and so has the code. It is still available from alternative sources or Qualcomm. It was a subject of discussion recently but I haven't re-added it to the list, which I will do now.
Regardless, I can say now already it is unlikely I will produce a driver for it, due to lack of test hardware and personal interest, but someone else might do it. There is also the option of contracting my company (or someone else familiar with bflb hardware like gamelaster who is an expert) and providing test hardware if you are very interested in this feature.

[kristoftjonck]

@VynDragon @gamelaster Thanks for the insight! Do you have any additional details on the intentional removal of the CAN peripheral in the documentation? Were there any specific issues, and do you have direct contact with Buffalo Labs? We'd love to gain more detailed insights. Can I reach out using the email address listed on your website?

[VynDragon]

intentional removal of the CAN peripheral in the documentation

Not much, we suspect a patent or copyright issue.

direct contact with Buffalo Labs

Not me personally, but we (the 'working group' I guess?) hope to strengthen communications once initial support is merged.

Can I reach out using the email address listed on your website?

Idk if you mean me or gamelaster but mine is also used for commits and on my website so you are fully free to contact me for any relevant reasons.

[gamelaster]

@kristoftjonck as VynDragon said 😁

 Can I reach out using the email address listed on your website?

If that was targeted to me, then yeah, for sure, feel free to use my email from my personal website, or the one used in git commits.