struct mtd_info {

  char name[32];

Name of the device. Rarely used, but presented to the user via the /proc/mtd interface.

  u_char type;

Type of memory technology used in this device. Choose from: 
#define MTD_ABSENT              0
#define MTD_RAM                 1
#define MTD_ROM                 2
#define MTD_NORFLASH            3
#define MTD_NANDFLASH           4
#define MTD_PEROM               5
#define MTD_OTHER               14
#define MTD_UNKNOWN             15

  u_long flags;

Device capabilities. Bitmask. Choose from: 
#define MTD_CLEAR_BITS          1       // Bits can be cleared (flash)
#define MTD_SET_BITS            2       // Bits can be set
#define MTD_ERASEABLE           4       // Has an erase function
#define MTD_WRITEB_WRITEABLE    8       // Direct IO is possible
#define MTD_VOLATILE            16      // Set for RAMs
#define MTD_XIP                 32      // eXecute-In-Place possible
#define MTD_OOB                 64      // Out-of-band data (NAND flash)
#define MTD_ECC                 128     // Device capable of automatic ECC

  loff_t size;

Total size in bytes.

  u_long erasesize;

Size in bytes of the "erase block" of this memory device - the smallest area which can be erased in a single erase command.

  u_long oobblock;

  u_long oobsize;

Some memory technologies support out-of-band data - for example, NAND flash has 16 extra bytes per 512-byte page, for error correction or metadata. oobsize and oobblock hold the size of each out-of-band area, and the number of bytes of "real" memory with which each is associated, respectively. As an example, NAND flash, would have oobblock == 512 and oobsize == 16 to show that it has 16 bytes of OOB data per 512 bytes of flash.

  u_long ecctype;

  u_long eccsize;

Some hardware not only allows access to flash or similar devices, but also has ECC (error correction) capabilities built-in to the interface. The ecctype field is an enumeration - currently you have a choice of: 
#define MTD_ECC_NONE            0       // No automatic ECC available
#define MTD_ECC_RS_DiskOnChip   1       // Automatic ECC on DiskOnChip
The eccsize holds the size of the blocks on which the hardware can perform automatic ECC.

  struct module *module;

When a driver is a kernel loadable module, this field is a pointer to the struct module of the module. It is used to increase and decrease the module's usage count as appropriate.

The user modules are responsible for increasing and decreasing the usage count of the driver as appropriate, for example by calling __MOD_INC_USE_COUNT(mtd->module); in their open routine.

  int (*erase) (struct mtd_info *mtd, struct erase_info *instr);

This routine adds a struct erase_info to the erase queue for the device. This routine may sleep until the erase had finished, or it may simply queue the request and return immediately.

The struct erase_info contains a pointer to a callback function which will be called by the driver module when the erase has completed.

For more information, see the erase page.

  int (*point) (struct mtd_info *mtd, loff_t from, size_t len, u_char **mtdbuf);

  void (*unpoint) (struct mtd_info *mtd, u_char * addr);

For devices which are entirely memory-mapped and which can be mapped directly into user-space page tables, we may support execute-in-place (XIP) mapping of data on the flash. The precise semantics of this are yet to be defined, so it's probably best just not to either implement or attempt to use these two functions right at the moment.

  int (*read) (struct mtd_info *mtd, loff_t from, size_t len, u_char *buf);

  int (*write) (struct mtd_info *mtd, loff_t to, size_t len, const u_char *buf);

Read and write functions for the memory device. These may sleep, and should not be called from IRQ context or with locks held.

The buf argument is assumed to be in kernel-space. If you need to copy to userspace, either use a kiobuf to lock down the pages first, or use a bounce buffer.

  int (*read_ecc) (struct mtd_info *mtd, loff_t from, size_t len, u_char *buf, u_char *eccbuf);

  int (*write_ecc) (struct mtd_info *mtd, loff_t to, size_t len, const u_char *buf, u_char *eccbuf);

For devices which support automatic ECC generation or checking, these routines behave just the same at the read/write functions above, but with the addition that the write_ecc function places the generated ECC data into eccbuf, and the read_ecc function verifies the ECC data and attempts to correct any errors which it detects.

  int (*read_oob) (struct mtd_info *mtd, loff_t from, size_t len, u_char *buf);

  int (*write_oob) (struct mtd_info *mtd, loff_t to, size_t len, const u_char *buf);

For devices which have out-of-band data, these functions provide access to it.

The from/to address is the address of the start of the real page of memory with which the OOB data is associated, added to the offset within the OOB block.

Example: To specify the 5th byte of the OOB data associated with the NAND flash page at 0x1000 in the device, you would pass address 0x1005

  void (*sync) (struct mtd_info *mtd);

This routine will sleep until all pending flash operations have completed.

  void *priv;

This is used for data private to the MTD driver.

};

Notes

All the MTD driver functions may be sleep. You may not call any of them from an IRQ or timer context, or with locks held.

Nothing may modify the data in the struct mtd_info after it is registered with the MTD system.

The read, write and erase routines are mandatory. Also read_oob and write_oob if the MTD device indicates that it has such capability.

The sync routine is not mandatory, and users should check that the vector is non-NULL before attempting to use it.

David Woodhouse
$Id: mtd_info.html,v 1.1 2005/03/12 13:43:49 gleixner Exp $