Linux Kernel  3.7.1
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Enumerations
ubi.h File Reference
#include <linux/ioctl.h>
#include <linux/types.h>
#include <mtd/ubi-user.h>

Go to the source code of this file.

Data Structures

struct  ubi_volume_info
 
struct  ubi_device_info
 
struct  ubi_notification
 

Macros

#define UBI_ALL   -1
 

Enumerations

enum  { UBI_READONLY = 1, UBI_READWRITE, UBI_EXCLUSIVE }
 

: volume name

struct ubi_volume_info - UBI volume description data structure. : volume ID : UBI device number this volume belongs to : how many physical eraseblocks are reserved for this volume : how many bytes of data this volume contains : how many physical eraseblocks of this volume actually contain any data : volume type (UBI_DYNAMIC_VOLUME or UBI_STATIC_VOLUME) : non-zero if the volume is corrupted (static volumes only) : non-zero if the volume has update marker set : volume alignment : how many bytes are available in logical eraseblocks of this volume : volume name length

: UBI volume character device major and minor numbers

The flag is only relevant to static volumes and is always zero for dynamic ones. This is because UBI does not care about dynamic volume data protection and only cares about protecting static volume data.

The flag is set if the volume update operation was interrupted. Before touching the volume data during the update operation, UBI first sets the update marker flag for this volume. If the volume update operation was further interrupted, the update marker indicates this. If the update marker is set, the contents of the volume is certainly damaged and a new volume update operation has to be started.

To put it differently, and fields have different semantics: o the flag means that this static volume is corrupted for some reasons, but not because an interrupted volume update o the field means that the volume is damaged because of an interrupted update operation.

I.e., the flag is never set if the flag is set.

The and fields are only really needed for static volumes and contain the number of bytes stored in this static volume and how many eraseblock this data occupies. In case of dynamic volumes, the field is equivalent to *, and the field is equivalent to .

In general, logical eraseblock size is a property of the UBI device, not of the UBI volume. Indeed, the logical eraseblock size depends on the physical eraseblock size and on how much bytes UBI headers consume. But because of the volume alignment (), the usable size of logical eraseblocks if a volume may be less. The following equation is true: = LEB size - (LEB size mod ), where LEB size is the logical eraseblock size defined by the UBI device.

The alignment is multiple to the minimal flash input/output unit size or %1 if all the available space is used.

To put this differently, alignment may be considered is a way to change volume logical eraseblock sizes.

enum  {
  UBI_VOLUME_ADDED, UBI_VOLUME_REMOVED, UBI_VOLUME_RESIZED, UBI_VOLUME_RENAMED,
  UBI_VOLUME_UPDATED
}
 
int ubi_get_device_info (int ubi_num, struct ubi_device_info *di)
 
void ubi_get_volume_info (struct ubi_volume_desc *desc, struct ubi_volume_info *vi)
 
struct ubi_volume_descubi_open_volume (int ubi_num, int vol_id, int mode)
 
struct ubi_volume_descubi_open_volume_nm (int ubi_num, const char *name, int mode)
 
struct ubi_volume_descubi_open_volume_path (const char *pathname, int mode)
 
int ubi_register_volume_notifier (struct notifier_block *nb, int ignore_existing)
 
int ubi_unregister_volume_notifier (struct notifier_block *nb)
 
void ubi_close_volume (struct ubi_volume_desc *desc)
 
int ubi_leb_read (struct ubi_volume_desc *desc, int lnum, char *buf, int offset, int len, int check)
 
int ubi_leb_write (struct ubi_volume_desc *desc, int lnum, const void *buf, int offset, int len)
 
int ubi_leb_change (struct ubi_volume_desc *desc, int lnum, const void *buf, int len)
 
int ubi_leb_erase (struct ubi_volume_desc *desc, int lnum)
 
int ubi_leb_unmap (struct ubi_volume_desc *desc, int lnum)
 
int ubi_leb_map (struct ubi_volume_desc *desc, int lnum)
 
int ubi_is_mapped (struct ubi_volume_desc *desc, int lnum)
 
int ubi_sync (int ubi_num)
 
int ubi_flush (int ubi_num, int vol_id, int lnum)
 

Macro Definition Documentation

#define UBI_ALL   -1

Definition at line 29 of file ubi.h.

Enumeration Type Documentation

anonymous enum
Enumerator:
UBI_READONLY 
UBI_READWRITE 
UBI_EXCLUSIVE 

Definition at line 38 of file ubi.h.

anonymous enum
Enumerator:
UBI_VOLUME_ADDED 
UBI_VOLUME_REMOVED 
UBI_VOLUME_RESIZED 
UBI_VOLUME_RENAMED 
UBI_VOLUME_UPDATED 

Definition at line 173 of file ubi.h.

Function Documentation

void ubi_close_volume ( struct ubi_volume_desc desc)

ubi_close_volume - close UBI volume. : volume descriptor

Definition at line 328 of file kapi.c.

int ubi_flush ( int  ubi_num,
int  vol_id,
int  lnum 
)

ubi_flush - flush UBI work queue. : UBI device to flush work queue : volume id to flush for : logical eraseblock number to flush for

This function executes all pending works for a particular volume id / logical eraseblock number pair. If either value is set to UBI_ALL, then it acts as a wildcard for all of the corresponding volume numbers or logical eraseblock numbers. It returns zero in case of success and a negative error code in case of failure.

Definition at line 719 of file kapi.c.

int ubi_get_device_info ( int  ubi_num,
struct ubi_device_info di 
)

ubi_get_device_info - get information about UBI device. : UBI device number : the information is stored here

This function returns %0 in case of success, %-EINVAL if the UBI device number is invalid, and %-ENODEV if there is no such UBI device.

Definition at line 59 of file kapi.c.

void ubi_get_volume_info ( struct ubi_volume_desc desc,
struct ubi_volume_info vi 
)

ubi_get_volume_info - get information about UBI volume. : volume descriptor : the information is stored here

Definition at line 102 of file kapi.c.

int ubi_is_mapped ( struct ubi_volume_desc desc,
int  lnum 
)

ubi_is_mapped - check if logical eraseblock is mapped. : volume descriptor : logical eraseblock number

This function checks if logical eraseblock is mapped to a physical eraseblock. If a logical eraseblock is un-mapped, this does not necessarily mean it will still be un-mapped after the UBI device is re-attached. The logical eraseblock may become mapped to the physical eraseblock it was last mapped to.

This function returns %1 if the LEB is mapped, %0 if not, and a negative error code in case of failure. If the volume is damaged because of an interrupted update this function just returns immediately with %-EBADF error code.

Definition at line 669 of file kapi.c.

int ubi_leb_change ( struct ubi_volume_desc desc,
int  lnum,
const void buf,
int  len 
)

Definition at line 492 of file kapi.c.

int ubi_leb_erase ( struct ubi_volume_desc desc,
int  lnum 
)

ubi_leb_erase - erase logical eraseblock. : volume descriptor : logical eraseblock number

This function un-maps logical eraseblock and synchronously erases the correspondent physical eraseblock. Returns zero in case of success and a negative error code in case of failure.

If the volume is damaged because of an interrupted update this function just returns immediately with %-EBADF code.

Definition at line 533 of file kapi.c.

int ubi_leb_map ( struct ubi_volume_desc desc,
int  lnum 
)

ubi_leb_map - map logical eraseblock to a physical eraseblock. : volume descriptor : logical eraseblock number

This function maps an un-mapped logical eraseblock to a physical eraseblock. This means, that after a successful invocation of this function the logical eraseblock will be empty (contain only %0xFF bytes) and be mapped to a physical eraseblock, even if an unclean reboot happens.

This function returns zero in case of success, %-EBADF if the volume is damaged because of an interrupted update, %-EBADMSG if the logical eraseblock is already mapped, and other negative error codes in case of other failures.

Definition at line 630 of file kapi.c.

int ubi_leb_read ( struct ubi_volume_desc desc,
int  lnum,
char buf,
int  offset,
int  len,
int  check 
)

ubi_leb_read - read data. : volume descriptor : logical eraseblock number to read from : buffer where to store the read data : offset within the logical eraseblock to read from : how many bytes to read : whether UBI has to check the read data's CRC or not.

This function reads data from offset of logical eraseblock and stores the data at . When reading from static volumes, specifies whether the data has to be checked or not. If yes, the whole logical eraseblock will be read and its CRC checksum will be checked (i.e., the CRC checksum is per-eraseblock). So checking may substantially slow down the read speed. The argument is ignored for dynamic volumes.

In case of success, this function returns zero. In case of failure, this function returns a negative error code.

%-EBADMSG error code is returned: o for both static and dynamic volumes if MTD driver has detected a data integrity problem (unrecoverable ECC checksum mismatch in case of NAND); o for static volumes in case of data CRC mismatch.

If the volume is damaged because of an interrupted update this function just returns immediately with %-EBADF error code.

Definition at line 384 of file kapi.c.

int ubi_leb_unmap ( struct ubi_volume_desc desc,
int  lnum 
)

ubi_leb_unmap - un-map logical eraseblock. : volume descriptor : logical eraseblock number

This function un-maps logical eraseblock and schedules the corresponding physical eraseblock for erasure, so that it will eventually be physically erased in background. This operation is much faster than the erase operation.

Unlike erase, the un-map operation does not guarantee that the logical eraseblock will contain all 0xFF bytes when UBI is initialized again. For example, if several logical eraseblocks are un-mapped, and an unclean reboot happens after this, the logical eraseblocks will not necessarily be un-mapped again when this MTD device is attached. They may actually be mapped to the same physical eraseblocks again. So, this function has to be used with care.

In other words, when un-mapping a logical eraseblock, UBI does not store any information about this on the flash media, it just marks the logical eraseblock as "un-mapped" in RAM. If UBI is detached before the physical eraseblock is physically erased, it will be mapped again to the same logical eraseblock when the MTD device is attached again.

The main and obvious use-case of this function is when the contents of a logical eraseblock has to be re-written. Then it is much more efficient to first un-map it, then write new data, rather than first erase it, then write new data. Note, once new data has been written to the logical eraseblock, UBI guarantees that the old contents has gone forever. In other words, if an unclean reboot happens after the logical eraseblock has been un-mapped and then written to, it will contain the last written data.

This function returns zero in case of success and a negative error code in case of failure. If the volume is damaged because of an interrupted update this function just returns immediately with %-EBADF code.

Definition at line 594 of file kapi.c.

int ubi_leb_write ( struct ubi_volume_desc desc,
int  lnum,
const void buf,
int  offset,
int  len 
)

ubi_leb_write - write data. : volume descriptor : logical eraseblock number to write to : data to write : offset within the logical eraseblock where to write : how many bytes to write

This function writes bytes of data from to offset of logical eraseblock .

This function takes care of physical eraseblock write failures. If write to the physical eraseblock write operation fails, the logical eraseblock is re-mapped to another physical eraseblock, the data is recovered, and the write finishes. UBI has a pool of reserved physical eraseblocks for this.

If all the data were successfully written, zero is returned. If an error occurred and UBI has not been able to recover from it, this function returns a negative error code. Note, in case of an error, it is possible that something was still written to the flash media, but that may be some garbage.

If the volume is damaged because of an interrupted update this function just returns immediately with %-EBADF code.

Definition at line 447 of file kapi.c.

struct ubi_volume_desc* ubi_open_volume ( int  ubi_num,
int  vol_id,
int  mode 
)
read

ubi_open_volume - open UBI volume. : UBI device number : volume ID : open mode

The parameter specifies if the volume should be opened in read-only mode, read-write mode, or exclusive mode. The exclusive mode guarantees that nobody else will be able to open this volume. UBI allows to have many volume readers and one writer at a time.

If a static volume is being opened for the first time since boot, it will be checked by this function, which means it will be fully read and the CRC checksum of each logical eraseblock will be checked.

This function returns volume descriptor in case of success and a negative error code in case of failure.

Definition at line 127 of file kapi.c.

struct ubi_volume_desc* ubi_open_volume_nm ( int  ubi_num,
const char name,
int  mode 
)
read

Definition at line 238 of file kapi.c.

struct ubi_volume_desc* ubi_open_volume_path ( const char pathname,
int  mode 
)
read

ubi_open_volume_path - open UBI volume by its character device node path. : volume character device node path : open mode

This function is similar to 'ubi_open_volume()', but opens a volume the path to its character device node.

Definition at line 295 of file kapi.c.

int ubi_register_volume_notifier ( struct notifier_block nb,
int  ignore_existing 
)

ubi_register_volume_notifier - register a volume notifier. : the notifier description object : if non-zero, do not send "added" notification for all already existing volumes

This function registers a volume notifier, which means that 'nb->notifier_call()' will be invoked when an UBI volume is created, removed, re-sized, re-named, or updated. The first argument of the function is the notification type. The second argument is pointer to a &struct ubi_notification object which describes the notification event. Using UBI API from the volume notifier is prohibited.

This function returns zero in case of success and a negative error code in case of failure.

Definition at line 752 of file kapi.c.

int ubi_sync ( int  ubi_num)

ubi_sync - synchronize UBI device buffers. : UBI device to synchronize

The underlying MTD device may cache data in hardware or in software. This function ensures the caches are flushed. Returns zero in case of success and a negative error code in case of failure.

Definition at line 693 of file kapi.c.

int ubi_unregister_volume_notifier ( struct notifier_block nb)

ubi_unregister_volume_notifier - unregister the volume notifier. : the notifier description object

This function unregisters volume notifier and returns zero in case of success and a negative error code in case of failure.

Definition at line 784 of file kapi.c.