Introduction to LEVELX

1. Introduction

Azure® RTOS LevelX is a library offering wear-levelling and bad-block management features for Flash memories. LevelX is not intended to provide FileSytem APIs, but only low-level APIs to read, write, and erase sectors in Flash memories. Combined with FileX, it allows seamless use of NAND and NOR Flash memories as media storage devices.

LevelX Overview

LevelX is designed in a modular way that facilitates the support of any Flash memory. In fact, LevelX requires a low-level driver interacting with the Flash memory to support the basic raw API, read blocks, write blocks, erase blocks, and check errors. These raw APIs are then logically combined to offer more user-friendly high-level APIs. The main features offered by LevelX are:

  • Data read/write
  • Flash erase
  • Flash defragmentation
  • Wear levelling
  • Error checks

Further details are available in the LevelX official documentation

2. STM32 Integration

LevelX mainly targets the following memory types:

  • NOR Flash memories (SPI/Quad-SPI/Octo-SPI), making use of wear-levelling and bad-block management features
  • NAND Flash memories, also making use of wear-levelling and bad-block management features
  • SRAMs: covering any MCU internal volatile memory (such as DTCM and AXI SRAM). This is useful specifically for fast prototyping and testing.

2.1. Known limitations

3. How to use

LevelX must be used alongside with FileX. Please refer to the FileX page "How To Use" section for more details about how to use LevelX

LevelX requires low-level interfaces to support the above-mentioned hardware devices:

  • lx_stm32_xxx_driver_template.c/stm32_lx_xxx_driver_template.h: An empty interface, provided as skeleton that can be modified by the user to support a custom Flash memory.
  • lx_stm32_*_driver.c: LevelX driver patterns that are ready to use by the application. They are delivered as part of the LevelX source code. The drivers may differ between STM32 Series depending on the supported features.
  • lx_stm32_*_driver_template.h: A template configuration header file to tune the corresponding driver for specific STM32 MCU/board. This file should be copied to the application source tree and renamed to “lx_stm32_*_driver.h”, then customized according to the driver needs.
LevelX LowLayer

Configuration flags can be defined by the user in the “xxx_driver_template.h” file. The LevelX driver Octo-SPI header template file below is an example:


#ifdef __cplusplus
extern "C" {

/* Includes ------------------------------------------------------------------*/
#include "lx_api.h"
#include "stm32h747i_discovery_qspi.h"

/* Exported types ------------------------------------------------------------*/
/* Exported constants --------------------------------------------------------*/
/* the Quad-SPI instance ,default value set to 0 */
#define QSPI_INSTANCE   0
#define DEFAULT_BLOCK_SIZE (4 * 1024)

/* when set to 1, the Quad-SPI init is done by the driver, otherwise it is up to the application to intialize it */


/* allow the driver to fully erase the Quad-SPI chip. This should be used carefully.
 * the call is blocking and takes a while. by default it is set to 0.
 * When creating a fresh file system on the NOR Flash this flag should be enabled.

/* Exported macro ------------------------------------------------------------*/
/* Exported functions prototypes ---------------------------------------------*/
UINT  lx_stm32_qspi_initialize(LX_NOR_FLASH *nor_flash);

/* Private defines -----------------------------------------------------------*/

#ifdef __cplusplus
#endif /* LX_STM32_QSPI_DRIVER_H */

4. STM32 LevelX applications

To be Updated.

STM32 Packages provide the following set of applications (the supported applications list may differ between products and boards):

Application Short description
Fx_NAND_Write_Read_File Demonstrates how to create a Fat File system on NAND Flash using FileX alongside LevelX. The application is designed to execute file operations on the Micron MT29F2G16ABAEAWP NAND Flash device, the code provides all the required software code to properly manage it. [readme]