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:

A sector is the device's erase unit. Calls to mtd_erase need to work in alignment with this number (commonly somewhere around 1kiB).

(Note that this corresponds to the term "page" as used in the flashpage API, and the term "eraseblock" in Linux's MTD).
A page is the largest a device can write in one transfer.

Applications rarely need to deal with this; it offers no guarantees on atomicity, but writing within a page is generally faster than across page boundaries.

Pages are a subdivision of sectors.
The write size is the minimum size of writes to the device, and also the required alignment of writes.

The write size is a divider of the page. It is often between 1 to 4 bytes long, but may be up to the full page size.
The device's flags indicate features, eg. whether a memory location can be overwritten without erasing it first.

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...

static mtd_dev_t *	mtd_default_get_dev (unsigned idx)
	Default MTD device configuration. More...

#define	MTD_EMULATED_DEV(n, sc, pps, ps)
	MTD device that is emulated in RAM for test purposes. More...

#define	MTD_EMULATED_DEV_FS(n, m, fs) VFS_AUTO_MOUNT(fs, VFS_MTD(mtd_emulated_dev ## n), "/mtde" # n, m)
	Macro to define an automatic VFS mount point for an emulated MTD. More...

const mtd_desc_t	_mtd_emulated_driver
	Emulated MTD device operations table for mtd.

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.

◆ MTD_EMULATED_DEV

#define MTD_EMULATED_DEV	(	n,
		sc,
		pps,
		ps
	)

Value:

    uint8_t _mtd_emulated_memory ## n[sc * pps * ps];   \
                                                        \
    mtd_emulated_t mtd_emulated_dev ## n = {            \
        .base = {                                       \
            .driver = &_mtd_emulated_driver,            \
            .sector_count = sc,                         \
            .pages_per_sector = pps,                    \
            .page_size = ps,                            \
            .write_size = 1,                            \
        },                                              \
        .size = sc * pps * ps,                          \
        .memory = _mtd_emulated_memory ## n,            \
        .init_done = false,                             \
    }                                                   \

MTD device that is emulated in RAM for test purposes.

Helpers for using emulated MTDs.

Author: Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Macro to define an emulated MTD

This macro creates a MTD device that is emulated in RAM. For example, using

MTD_EMULATED_DEV(0, 16, 4, 64)

MTD_EMULATED_DEV

#define MTD_EMULATED_DEV(n, sc, pps, ps)

MTD device that is emulated in RAM for test purposes.

Definition: mtd_emulated.h:46

creates the emulated MTD device mtd_emulated_dev0 with 16 sectors, 4 pages per sector and a page size of 64 bytes. The write size is always 1 byte.

Parameters

n	index of the emulated MTD (results into symbol `mtd_emulated_devn`)
sc	sectors of the emulated MTD
pps	pages per sector of the emulated MTD
ps	page size in bytes

Definition at line 46 of file mtd_emulated.h.

◆ MTD_EMULATED_DEV_FS

#define MTD_EMULATED_DEV_FS	(	n,
		m,
		fs
	)	VFS_AUTO_MOUNT(fs, VFS_MTD(mtd_emulated_dev ## n), "/mtde" # n, m)

Macro to define an automatic VFS mount point for an emulated MTD.

For example, using

MTD_EMULATED_DEV_FS(0, 2, fatfs);

MTD_EMULATED_DEV_FS

#define MTD_EMULATED_DEV_FS(n, m, fs)

Macro to define an automatic VFS mount point for an emulated MTD.

Definition: mtd_emulated.h:77

automatically mounts the emulated MTD mtd_emulated_dev0 with FAT file system under mount point /mtde0 with unique index 2.

Parameters

n	index of the emulated MTD (symbol `mtd_emulated_devn`, mount point `/mtde0`)
m	unique overall index of VFS mount point
fs	filesystem type used

Definition at line 77 of file mtd_emulated.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

enum 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_default_get_dev()

static mtd_dev_t* mtd_default_get_dev ( unsigned idx )

inlinestatic

Default MTD device configuration.

Helpers for generic MTD use.

Author: Benjamin Valentin benja.nosp@m.min..nosp@m.valen.nosp@m.tin@.nosp@m.ml-pa.nosp@m..com

Get the default MTD device by index

Parameters

[in] idx Index of the MTD device

Returns: MTD_0 for idx 0 and so on NULL if no MTD device exists for the given index

Definition at line 101 of file mtd_default.h.

◆ 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

	mtd	the device to erase
[in]	addr	the address of the first sector to erase
[in]	count	the 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

	mtd	the device to erase
[in]	sector	the first sector number to erase
[in]	num	the 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

mtd	the 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

	mtd	the device to access
[in]	power	the 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

	mtd	the device to read from
[out]	dest	the buffer to fill in
[in]	addr	the start address to read from
[in]	count	the 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

	mtd	the device to read from
[out]	dest	the buffer to fill in
[in]	page	Page number to start reading from
[in]	offset	offset from the start of the page (in bytes)
[in]	size	the number of bytes to read

Returns: number of bytes read on success; < 0 value on error; -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

	mtd	the device to write to
[in]	src	the buffer to write
[in]	addr	the start address to write to
[in]	count	the 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

	mtd	the device to write to
[in]	src	the buffer to write
[in]	page	Page number to start writing to
[in]	offset	byte offset from the start of the page
[in]	size	the number of bytes to write

Returns: number of bytes written on success; < 0 value on error; -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

	mtd	the device to write to
[in]	src	the buffer to write
[in]	page	Page number to start writing to
[in]	offset	byte offset from the start of the page
[in]	size	the number of bytes to write

Returns: number of bytes written on success; < 0 value on error; -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

Detailed Description

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ MTD_DRIVER_FLAG_CLEARING_OVERWRITE

◆ MTD_DRIVER_FLAG_DIRECT_WRITE

◆ MTD_EMULATED_DEV

◆ MTD_EMULATED_DEV_FS

Typedef Documentation

◆ mtd_desc_t

Enumeration Type Documentation

◆ mtd_power_state

Function Documentation

◆ mtd_default_get_dev()

◆ mtd_erase()

◆ mtd_erase_sector()

◆ mtd_init()

◆ mtd_power()

◆ mtd_read()

◆ mtd_read_page()

◆ mtd_write()

◆ mtd_write_page()

◆ mtd_write_page_raw()