Memory Technology Device

Low level Memory Technology Device interface. More...

Detailed Description

Low level Memory Technology Device interface.

Generic memory technology device interface

Unlike the Flash page driver, this is device driver based (i.e. all functions take a mtd_dev_t as a first argument), so that SPI based EEPROMs (e.g. AT25xxx) can be accessed the same way as internal flash or SD cards), all inside the same application.

MTD devices expose a block based erase and write interface. In that, they are the distinct from block devices (like hard disks) on which individual bytes can be overwritten. The Linux MTD FAQ has a convenient comparison (beware though of terminology differences outlined below). They can be erased (with some granularity, often wearing out the erased area a bit), and erased areas can be written to (sometimes multiple times).

MTD devices are described in terms of sectors, pages and feature flags:

Unless a flag (such as MTD_DRIVER_FLAG_DIRECT_WRITE or MTD_DRIVER_FLAG_CLEARING_OVERWRITE) allows it, this MTD API does not allow memory areas to be written to twice between erase operations. Drivers are not expected to count write accesses, and neither do this module's functions: The performance impact would be too great. It is up to the application to only write to erased memory once. Failure to do so may damage hardware.

This MTD API currently does not specify which value will be read from an erased sector.

Modules

 Native MTD
 mtd flash emulation for native
 

Files

file  mtd.h
 

Data Structures

struct  mtd_dev_t
 MTD device descriptor. More...
 
struct  mtd_desc
 MTD driver interface. More...
 

Macros

#define MTD_DRIVER_FLAG_DIRECT_WRITE   (1 << 0)
 MTD driver can write any data to the storage without erasing it first. More...
 
#define MTD_DRIVER_FLAG_CLEARING_OVERWRITE   (1 << 1)
 MTD driver supports arbitrary clearing overwrites. More...
 

Typedefs

typedef struct mtd_desc mtd_desc_t
 MTD driver interface. More...
 

Enumerations

enum  mtd_power_state { MTD_POWER_UP , MTD_POWER_DOWN }
 MTD power states. More...
 

Functions

int mtd_init (mtd_dev_t *mtd)
 mtd_init Initialize a MTD device More...
 
int mtd_read (mtd_dev_t *mtd, void *dest, uint32_t addr, uint32_t count)
 Read data from a MTD device. More...
 
int mtd_read_page (mtd_dev_t *mtd, void *dest, uint32_t page, uint32_t offset, uint32_t size)
 Read data from a MTD device with pagewise addressing. More...
 
int mtd_write (mtd_dev_t *mtd, const void *src, uint32_t addr, uint32_t count)
 Write data to a MTD device. More...
 
int mtd_write_page_raw (mtd_dev_t *mtd, const void *src, uint32_t page, uint32_t offset, uint32_t size)
 Write data to a MTD device with pagewise addressing. More...
 
int mtd_write_page (mtd_dev_t *mtd, const void *src, uint32_t page, uint32_t offset, uint32_t size)
 Write data to a MTD device with pagewise addressing. More...
 
int mtd_erase (mtd_dev_t *mtd, uint32_t addr, uint32_t count)
 Erase sectors of a MTD device. More...
 
int mtd_erase_sector (mtd_dev_t *mtd, uint32_t sector, uint32_t num)
 Erase sectors of a MTD device. More...
 
int mtd_power (mtd_dev_t *mtd, enum mtd_power_state power)
 Set power mode on a MTD device. More...
 

Macro Definition Documentation

◆ MTD_DRIVER_FLAG_CLEARING_OVERWRITE

#define MTD_DRIVER_FLAG_CLEARING_OVERWRITE   (1 << 1)

MTD driver supports arbitrary clearing overwrites.

If this is set, (arbitrarily) many writes are permitted per write size, and the result is the old value bitwise-AND the written value.

This property is common for managed flash memories. (By comparison, the raw flash often used internally by MCUs may not allow overwrites, or may allow them with the same semantics, but only for a limited number of writes between erasures; there is currently no flag describing these any further).

Definition at line 137 of file mtd.h.

◆ MTD_DRIVER_FLAG_DIRECT_WRITE

#define MTD_DRIVER_FLAG_DIRECT_WRITE   (1 << 0)

MTD driver can write any data to the storage without erasing it first.

If this is set, a write completely overrides the previous values.

Definition at line 124 of file mtd.h.

Typedef Documentation

◆ mtd_desc_t

typedef struct mtd_desc mtd_desc_t

MTD driver interface.

This define the functions to access a MTD.

A MTD is composed of pages combined into sectors. A sector is the smallest erasable unit. The number of pages in a sector must be constant for the whole MTD.

The erase operation is available only for entire sectors.

Definition at line 1 of file mtd.h.

Enumeration Type Documentation

◆ mtd_power_state

MTD power states.

Enumerator
MTD_POWER_UP 

Power up.

MTD_POWER_DOWN 

Power down.

Definition at line 85 of file mtd.h.

Function Documentation

◆ mtd_erase()

int mtd_erase ( mtd_dev_t mtd,
uint32_t  addr,
uint32_t  count 
)

Erase sectors of a MTD device.

addr must be aligned on a sector boundary. count must be a multiple of a sector size.

Parameters
mtdthe device to erase
[in]addrthe address of the first sector to erase
[in]countthe number of bytes to erase
Returns
0 if erase successful
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or count are not valid, i.e. outside memory
-EIO if I/O error occurred

◆ mtd_erase_sector()

int mtd_erase_sector ( mtd_dev_t mtd,
uint32_t  sector,
uint32_t  num 
)

Erase sectors of a MTD device.

Parameters
mtdthe device to erase
[in]sectorthe first sector number to erase
[in]numthe number of sectors to erase
Returns
0 if erase successful
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or sector are not valid, i.e. outside memory
-EIO if I/O error occurred

◆ mtd_init()

int mtd_init ( mtd_dev_t mtd)

mtd_init Initialize a MTD device

Parameters
mtdthe device to initialize
Returns

◆ mtd_power()

int mtd_power ( mtd_dev_t mtd,
enum mtd_power_state  power 
)

Set power mode on a MTD device.

Parameters
mtdthe device to access
[in]powerthe power mode to set
Returns
0 if power mode successfully set
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation or power state is not supported on mtd
-EIO if I/O error occurred

◆ mtd_read()

int mtd_read ( mtd_dev_t mtd,
void *  dest,
uint32_t  addr,
uint32_t  count 
)

Read data from a MTD device.

No alignment is required on addr and count.

Parameters
mtdthe device to read from
[out]destthe buffer to fill in
[in]addrthe start address to read from
[in]countthe number of bytes to read
Returns
0 on success
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or count are not valid, i.e. outside memory
-EIO if I/O error occurred

◆ mtd_read_page()

int mtd_read_page ( mtd_dev_t mtd,
void *  dest,
uint32_t  page,
uint32_t  offset,
uint32_t  size 
)

Read data from a MTD device with pagewise addressing.

The MTD layer will take care of splitting up the transaction into multiple reads if it is required by the underlying storage media.

Parameters
mtdthe device to read from
[out]destthe buffer to fill in
[in]pagePage number to start reading from
[in]offsetoffset from the start of the page (in bytes)
[in]sizethe number of bytes to read
Returns
0 on success
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or count are not valid, i.e. outside memory
-EIO if I/O error occurred

◆ mtd_write()

int mtd_write ( mtd_dev_t mtd,
const void *  src,
uint32_t  addr,
uint32_t  count 
)

Write data to a MTD device.

addr + count must be inside a page boundary. addr can be anywhere but the buffer cannot overlap two pages.

Both parameters must be multiples of the device's write size.

Parameters
mtdthe device to write to
[in]srcthe buffer to write
[in]addrthe start address to write to
[in]countthe number of bytes to write
Returns
0 on success
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or count are not valid, i.e. outside memory, or overlapping two pages
-EIO if I/O error occurred
-EINVAL if parameters are invalid (invalid alignment for instance)

◆ mtd_write_page()

int mtd_write_page ( mtd_dev_t mtd,
const void *  src,
uint32_t  page,
uint32_t  offset,
uint32_t  size 
)

Write data to a MTD device with pagewise addressing.

The MTD layer will take care of splitting up the transaction into multiple writes if it is required by the underlying storage media.

If the underlying sector needs to be erased before it can be written, the MTD layer will take care of the read-modify-write operation.

offset must be smaller than the page size

Note
this requires the mtd_write_page module
Parameters
mtdthe device to write to
[in]srcthe buffer to write
[in]pagePage number to start writing to
[in]offsetbyte offset from the start of the page
[in]sizethe number of bytes to write
Returns
0 on success
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or count are not valid, i.e. outside memory,
-EIO if I/O error occurred
-EINVAL if parameters are invalid

◆ mtd_write_page_raw()

int mtd_write_page_raw ( mtd_dev_t mtd,
const void *  src,
uint32_t  page,
uint32_t  offset,
uint32_t  size 
)

Write data to a MTD device with pagewise addressing.

The MTD layer will take care of splitting up the transaction into multiple writes if it is required by the underlying storage media.

This performs a raw write, no automatic read-modify-write cycle is performed.

Both offset and size must be multiples of the device's write size.

Parameters
mtdthe device to write to
[in]srcthe buffer to write
[in]pagePage number to start writing to
[in]offsetbyte offset from the start of the page
[in]sizethe number of bytes to write
Returns
0 on success
< 0 if an error occurred
-ENODEV if mtd is not a valid device
-ENOTSUP if operation is not supported on mtd
-EOVERFLOW if addr or count are not valid, i.e. outside memory,
-EIO if I/O error occurred
-EINVAL if parameters are invalid