ubi-media.h

Go to the documentation of this file.

/*
 * Copyright (c) International Business Machines Corp., 2006
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
 * the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * Authors: Artem Bityutskiy (Битюцкий Артём)
 *          Thomas Gleixner
 *          Frank Haverkamp
 *          Oliver Lohmann
 *          Andreas Arnez
 */

/*
 * This file defines the layout of UBI headers and all the other UBI on-flash
 * data structures.
 */

#ifndef __UBI_MEDIA_H__
#define __UBI_MEDIA_H__

#include <asm/byteorder.h>

/* The version of UBI images supported by this implementation */
#define UBI_VERSION 1

/* The highest erase counter value supported by this implementation */
#define UBI_MAX_ERASECOUNTER 0x7FFFFFFF

/* The initial CRC32 value used when calculating CRC checksums */
#define UBI_CRC32_INIT 0xFFFFFFFFU

/* Erase counter header magic number (ASCII "UBI#") */
#define UBI_EC_HDR_MAGIC  0x55424923
/* Volume identifier header magic number (ASCII "UBI!") */
#define UBI_VID_HDR_MAGIC 0x55424921

/*
 * Volume type constants used in the volume identifier header.
 *
 * @UBI_VID_DYNAMIC: dynamic volume
 * @UBI_VID_STATIC: static volume
 */
enum {
    UBI_VID_DYNAMIC = 1,
    UBI_VID_STATIC  = 2
};

/*
 * Volume flags used in the volume table record.
 *
 * @UBI_VTBL_AUTORESIZE_FLG: auto-resize this volume
 *
 * %UBI_VTBL_AUTORESIZE_FLG flag can be set only for one volume in the volume
 * table. UBI automatically re-sizes the volume which has this flag and makes
 * the volume to be of largest possible size. This means that if after the
 * initialization UBI finds out that there are available physical eraseblocks
 * present on the device, it automatically appends all of them to the volume
 * (the physical eraseblocks reserved for bad eraseblocks handling and other
 * reserved physical eraseblocks are not taken). So, if there is a volume with
 * the %UBI_VTBL_AUTORESIZE_FLG flag set, the amount of available logical
 * eraseblocks will be zero after UBI is loaded, because all of them will be
 * reserved for this volume. Note, the %UBI_VTBL_AUTORESIZE_FLG bit is cleared
 * after the volume had been initialized.
 *
 * The auto-resize feature is useful for device production purposes. For
 * example, different NAND flash chips may have different amount of initial bad
 * eraseblocks, depending of particular chip instance. Manufacturers of NAND
 * chips usually guarantee that the amount of initial bad eraseblocks does not
 * exceed certain percent, e.g. 2%. When one creates an UBI image which will be
 * flashed to the end devices in production, he does not know the exact amount
 * of good physical eraseblocks the NAND chip on the device will have, but this
 * number is required to calculate the volume sized and put them to the volume
 * table of the UBI image. In this case, one of the volumes (e.g., the one
 * which will store the root file system) is marked as "auto-resizable", and
 * UBI will adjust its size on the first boot if needed.
 *
 * Note, first UBI reserves some amount of physical eraseblocks for bad
 * eraseblock handling, and then re-sizes the volume, not vice-versa. This
 * means that the pool of reserved physical eraseblocks will always be present.
 */
enum {
    UBI_VTBL_AUTORESIZE_FLG = 0x01,
};

/*
 * Compatibility constants used by internal volumes.
 *
 * @UBI_COMPAT_DELETE: delete this internal volume before anything is written
 *                     to the flash
 * @UBI_COMPAT_RO: attach this device in read-only mode
 * @UBI_COMPAT_PRESERVE: preserve this internal volume - do not touch its
 *                       physical eraseblocks, don't allow the wear-leveling
 *                       sub-system to move them
 * @UBI_COMPAT_REJECT: reject this UBI image
 */
enum {
    UBI_COMPAT_DELETE   = 1,
    UBI_COMPAT_RO       = 2,
    UBI_COMPAT_PRESERVE = 4,
    UBI_COMPAT_REJECT   = 5
};

/* Sizes of UBI headers */
#define UBI_EC_HDR_SIZE  sizeof(struct ubi_ec_hdr)
#define UBI_VID_HDR_SIZE sizeof(struct ubi_vid_hdr)

/* Sizes of UBI headers without the ending CRC */
#define UBI_EC_HDR_SIZE_CRC  (UBI_EC_HDR_SIZE  - sizeof(__be32))
#define UBI_VID_HDR_SIZE_CRC (UBI_VID_HDR_SIZE - sizeof(__be32))

struct ubi_ec_hdr {
    __be32  magic;
    __u8    version;
    __u8    padding1[3];
    __be64  ec; /* Warning: the current limit is 31-bit anyway! */
    __be32  vid_hdr_offset;
    __be32  data_offset;
    __be32  image_seq;
    __u8    padding2[32];
    __be32  hdr_crc;
} __packed;

struct ubi_vid_hdr {
    __be32  magic;
    __u8    version;
    __u8    vol_type;
    __u8    copy_flag;
    __u8    compat;
    __be32  vol_id;
    __be32  lnum;
    __u8    padding1[4];
    __be32  data_size;
    __be32  used_ebs;
    __be32  data_pad;
    __be32  data_crc;
    __u8    padding2[4];
    __be64  sqnum;
    __u8    padding3[12];
    __be32  hdr_crc;
} __packed;

/* Internal UBI volumes count */
#define UBI_INT_VOL_COUNT 1

/*
 * Starting ID of internal volumes: 0x7fffefff.
 * There is reserved room for 4096 internal volumes.
 */
#define UBI_INTERNAL_VOL_START (0x7FFFFFFF - 4096)

/* The layout volume contains the volume table */

#define UBI_LAYOUT_VOLUME_ID     UBI_INTERNAL_VOL_START
#define UBI_LAYOUT_VOLUME_TYPE   UBI_VID_DYNAMIC
#define UBI_LAYOUT_VOLUME_ALIGN  1
#define UBI_LAYOUT_VOLUME_EBS    2
#define UBI_LAYOUT_VOLUME_NAME   "layout volume"
#define UBI_LAYOUT_VOLUME_COMPAT UBI_COMPAT_REJECT

/* The maximum number of volumes per one UBI device */
#define UBI_MAX_VOLUMES 128

/* The maximum volume name length */
#define UBI_VOL_NAME_MAX 127

/* Size of the volume table record */
#define UBI_VTBL_RECORD_SIZE sizeof(struct ubi_vtbl_record)

/* Size of the volume table record without the ending CRC */
#define UBI_VTBL_RECORD_SIZE_CRC (UBI_VTBL_RECORD_SIZE - sizeof(__be32))

struct ubi_vtbl_record {
    __be32  reserved_pebs;
    __be32  alignment;
    __be32  data_pad;
    __u8    vol_type;
    __u8    upd_marker;
    __be16  name_len;
    __u8    name[UBI_VOL_NAME_MAX+1];
    __u8    flags;
    __u8    padding[23];
    __be32  crc;
} __packed;

/* UBI fastmap on-flash data structures */

#define UBI_FM_SB_VOLUME_ID (UBI_LAYOUT_VOLUME_ID + 1)
#define UBI_FM_DATA_VOLUME_ID   (UBI_LAYOUT_VOLUME_ID + 2)

/* fastmap on-flash data structure format version */
#define UBI_FM_FMT_VERSION  1

#define UBI_FM_SB_MAGIC     0x7B11D69F
#define UBI_FM_HDR_MAGIC    0xD4B82EF7
#define UBI_FM_VHDR_MAGIC   0xFA370ED1
#define UBI_FM_POOL_MAGIC   0x67AF4D08
#define UBI_FM_EBA_MAGIC    0xf0c040a8

/* A fastmap supber block can be located between PEB 0 and
 * UBI_FM_MAX_START */
#define UBI_FM_MAX_START    64

/* A fastmap can use up to UBI_FM_MAX_BLOCKS PEBs */
#define UBI_FM_MAX_BLOCKS   32

/* 5% of the total number of PEBs have to be scanned while attaching
 * from a fastmap.
 * But the size of this pool is limited to be between UBI_FM_MIN_POOL_SIZE and
 * UBI_FM_MAX_POOL_SIZE */
#define UBI_FM_MIN_POOL_SIZE    8
#define UBI_FM_MAX_POOL_SIZE    256

#define UBI_FM_WL_POOL_SIZE 25

struct ubi_fm_sb {
    __be32 magic;
    __u8 version;
    __u8 padding1[3];
    __be32 data_crc;
    __be32 used_blocks;
    __be32 block_loc[UBI_FM_MAX_BLOCKS];
    __be32 block_ec[UBI_FM_MAX_BLOCKS];
    __be64 sqnum;
    __u8 padding2[32];
} __packed;

struct ubi_fm_hdr {
    __be32 magic;
    __be32 free_peb_count;
    __be32 used_peb_count;
    __be32 scrub_peb_count;
    __be32 bad_peb_count;
    __be32 erase_peb_count;
    __be32 vol_count;
    __u8 padding[4];
} __packed;

/* struct ubi_fm_hdr is followed by two struct ubi_fm_scan_pool */

struct ubi_fm_scan_pool {
    __be32 magic;
    __be16 size;
    __be16 max_size;
    __be32 pebs[UBI_FM_MAX_POOL_SIZE];
    __be32 padding[4];
} __packed;

/* ubi_fm_scan_pool is followed by nfree+nused struct ubi_fm_ec records */

struct ubi_fm_ec {
    __be32 pnum;
    __be32 ec;
} __packed;

struct ubi_fm_volhdr {
    __be32 magic;
    __be32 vol_id;
    __u8 vol_type;
    __u8 padding1[3];
    __be32 data_pad;
    __be32 used_ebs;
    __be32 last_eb_bytes;
    __u8 padding2[8];
} __packed;

/* struct ubi_fm_volhdr is followed by one struct ubi_fm_eba records */

struct ubi_fm_eba {
    __be32 magic;
    __be32 reserved_pebs;
    __be32 pnum[0];
} __packed;
#endif /* !__UBI_MEDIA_H__ */