STM32N6: improvements to XSPI driver, add support for userspace storage driver

[jmaksymowicz]

Description

This PR contains some commits from #417 - I wanted to separate the ones required for the userspace storage driver (needed ASAP) from the ones required for secure boot and encryption (can wait longer for approval). This includes infrastructure for writing to Flash in memory-mapped mode.

In order to support the userspace XSPI storage driver, the PLO driver now exports its configuration to a blob in syspage which can then be read by the userspace driver. The userspace driver then doesn't need to reset or re-initialize the chip and can issue read/write/erase operations right away. After considering multiple options I decided this is the best way.

Alternatives would be:

1. The userspace driver could reset and re-initialize the chip from scratch.
   This would be problematic, especially on nucleo board which doesn't have a GPIO pin tied to Flash reset.
   We cannot reset Flash as we exit PLO, as this would prevent kernel from accessing it during boot.
   In order to issue a soft-reset command in userspace driver, the PLO driver would need to pass information how to do it - causing the same problem again.
   It would also require more copy-pasting of code between the PLO driver and userspace driver (which I wanted to avoid). The userspace code would need to contain chip identification and SFDP parser code which would need to be kept in sync with the PLO version, which would be a huge pain.

2. The PLO driver could pass data through hal_syspage_t
   This would be the more conventional method. It would require changes that would need to be kept in sync between PLO, kernel and userspace, as well as creation of dedicated platformctl operation - I wanted to avoid this.
   The method of passing the blob has another advantage - the blob can be overridden by one supplied by user script. This means that potentially support of a chip could be upgraded without having to upgrade PLO.

Comments on what could be added to the xspi_chipSetup_v1 structure are welcome. The data it includes is sufficient for now, but it would be nice to make it more future-proof.

Depends-On: phoenix-rtos-kernel:jmaksymowicz/stm32-flashcs

Motivation and Context

Allow userspace Flash storage driver to be implemented.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Chore (refactoring, style fixes, git/CI config, submodule management, no code logic changes)

How Has This Been Tested?

• Already covered by automatic testing.
• New test added: (add PR link here).
• Tested by hand on: armv8m55-stm32n6-nucleo

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing linter checks and tests passed.
• My changes generate no new compilation warnings for any of the targets.

Special treatment

• This PR needs additional PRs to work (list the PRs, preferably in merge-order).
• I will merge this PR by myself when appropriate.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the STM32N6 XSPI driver by laying the groundwork for userspace Flash storage driver implementation. It achieves this by introducing a mechanism to export detailed XSPI chip configuration into a syspage blob, allowing userspace applications to seamlessly interact with the Flash memory. This approach bypasses the complexities of re-initialization and synchronization between kernel and userspace. Additionally, the changes incorporate DMA-driven memory copy capabilities for more efficient Flash write operations and refine D-Cache management for better performance and control.

Highlights

• Userspace Storage Driver Support: The XSPI driver now exports its configuration parameters to a syspage blob, enabling userspace drivers to access Flash memory without needing to re-initialize or reset the chip. This simplifies the implementation of userspace Flash storage drivers.
• DMA-driven Memory Operations: Implemented xspi_dmaMemcpy to perform efficient, DMA-driven memory copy operations for Flash writes, improving performance and handling alignment requirements for DTR modes.
• Memory-Mapped Write Mode for Flash: The XSPI driver now supports writing to Flash in memory-mapped mode, which is crucial for the new DMA-based write operations.
• D-Cache Management Refactoring: Refactored D-Cache management functions in hal/armv8m/cpu.c for improved modularity and added hal_cleanInvalDCacheAddr for more granular cache control during DMA transfers.
• XSPI Chip Configuration Structure: Introduced a new header chip_setup.h defining xspi_chipSetup_v1 and xspi_commandRegs_v1 structures to standardize and serialize XSPI chip parameters.

Changelog

• devices/flash-stm32xspi/chip_setup.h
  • Added new header file defining xspi_commandRegs_v1 and xspi_chipSetup_v1 structures for XSPI chip configuration.
• devices/flash-stm32xspi/xspi_common.c
  • Added DMA-related definitions and constants for GPDMA1 and channel offsets.
  • Extended xspi_ctrlParams to include DMA controller base address, device, and channel.
  • Implemented xspi_dmaMemcpy for DMA-driven memory copy operations.
  • Modified xspidrv_init to configure DMA and set default prefetch and timeout values.
  • Updated xspidrv_done to disable the DMA clock.
• devices/flash-stm32xspi/xspi_common.h
  • Defined new macros XSPI_DEFAULT_PREFETCH and XSPI_DEFAULT_TIMEOUT for XSPI control register settings.
  • Extended xspi_ctrlParams_t structure to include dmaCtrl, dmaDev, and dmaChannel fields.
  • Declared new functions xspi_dmaMemcpy, xspi_regcom_done, and xspi_hb_done.
• devices/flash-stm32xspi/xspi_hyperbus.c
  • Renamed psramdrv_changeXspiMode to xspi_hb_changeXspiMode for consistency.
  • Updated internal calls to the renamed mode change function.
  • Added xspi_hb_done function, which currently performs no action.
• devices/flash-stm32xspi/xspi_regcom.c
  • Included chip_setup.h and syspage.h for new functionalities.
  • Added paramsStored flag to flash_memParams to track syspage serialization status.
  • Modified flashdrv_changeCtrlMode to accept a doMemWriting parameter and handle prefetch/timeout bits for memory-mapped writes.
  • Updated calls to flashdrv_changeCtrlMode across various functions.
  • Replaced the original flashdrv_write_internal with a new DMA-based implementation using xspi_endAlignedMemcpy and xspi_write_page.
  • Implemented xspi_regcom_serializeCommand and xspi_regcom_serializeConfig to prepare chip parameters for syspage.
  • Added xspi_regcom_done to serialize and allocate XSPI chip configuration into a syspage blob for userspace access.
• hal/armv8m/cpu.c
  • Refactored D-Cache management functions by introducing static helper functions (hal_cache_getCCSIDR, hal_cache_getLogLine, hal_cache_loopSetWay, hal_cache_loopMemory).
  • Rewrote hal_enableDCache, hal_disableDCache, hal_cleanDCache, hal_invalDCacheAddr, and hal_invalDCacheAll to utilize the new helper functions.
  • Added hal_cleanInvalDCacheAddr for cleaning and invalidating specific memory regions in the D-Cache.
• hal/armv8m/cpu.h
  • Declared the new hal_cleanInvalDCacheAddr function.
• hal/armv8m/stm32/n6/stm32n6.c
  • Corrected the register offset used in _stm32_rccGetDevClock from rcc_ahb1enr to rcc_busenr.
• syspage.c
  • Implemented syspage_progAllocateAndAdd to dynamically allocate memory and add program entries or blobs to syspage, with an option to prevent overwriting existing entries.
• syspage.h
  • Declared the new syspage_progAllocateAndAdd function.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces several valuable improvements to the STM32N6 XSPI driver, including DMA support for memory-mapped writes, exporting flash configuration to userspace via syspage, and refactoring cache management functions. A medium-severity vulnerability was identified in the cache maintenance code, which could lead to undefined behavior, data corruption, or denial of service. Furthermore, a potential issue in the new DMA functionality could also lead to undefined behavior, and it is suggested to replace a hardcoded device-specific timeout with a configurable value for improved robustness, aligning with repository guidelines for device-specific parameters.

[github-actions]

Unit Test Results

9 525 tests  ±0   8 933 ✅ ±0   53m 4s ⏱️ +38s
  583 suites ±0     592 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 690f5ae. ± Comparison against base commit 0747a54.

♻️ This comment has been updated with latest results.