296 lines
7.5 KiB
C
296 lines
7.5 KiB
C
/*
|
|
* Copyright (c) 2008-2012 Apple Inc. All rights reserved.
|
|
*
|
|
* This document is the property of Apple Inc.
|
|
* It is considered confidential and proprietary.
|
|
*
|
|
* This document may not be reproduced or transmitted in any form,
|
|
* in whole or in part, without the express written permission of
|
|
* Apple Inc.
|
|
*/
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@header nand_nvram_impl
|
|
|
|
@abstract portable header info for nand nvram implementation use only
|
|
|
|
@discussion These declarations have been pulled out into an
|
|
independent file so that diagnostic utilities and white box unit
|
|
tests might take advantage of knowing implementation-specific
|
|
details. Nevertheless, no client of the nand nvram driver nor its
|
|
system-specific wrapper should ever need to reference this header.
|
|
Any declarations that need that level of visibility are intended to
|
|
be placed in "nand_nvram_core.h".
|
|
|
|
@copyright Apple Inc.
|
|
|
|
@updated 2012-02-21
|
|
*/
|
|
|
|
/* ========================================================================== */
|
|
|
|
#ifndef _NAND_NVRAM_IMPL_H
|
|
#define _NAND_NVRAM_IMPL_H
|
|
|
|
__BEGIN_DECLS
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@group public platform-independent type declarations
|
|
*/
|
|
|
|
/*!
|
|
@typedef nand_nvram_t
|
|
|
|
@abstract Opaque reference to structure needed by nand nvram implementation.
|
|
*/
|
|
typedef struct nand_nvram nand_nvram_t;
|
|
|
|
/*!
|
|
@typedef nand_nvram_geometry_t
|
|
|
|
@abstract
|
|
*/
|
|
typedef struct nand_nvram_geometry nand_nvram_geometry_t;
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@group private platform-independent type declarations
|
|
*/
|
|
|
|
typedef struct _meta meta_t;
|
|
typedef struct _blob blob_t;
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@group public platform-independent constant definitions
|
|
*/
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_SIZE
|
|
|
|
@abstract Standard size of nvram presented by the driver. Note
|
|
that, if this ends up changing in the future, this value should
|
|
start being defined on a platform/product specific basis.
|
|
*/
|
|
#define kNAND_NVRAM_SIZE 8192
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_META_SIZE
|
|
|
|
@abstract Amount of bytes required by meta data for each nvram
|
|
backing store page.
|
|
*/
|
|
#define kNAND_NVRAM_META_SIZE 10
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_PAGE_RESERVED_IN_BLOCK
|
|
|
|
@abstract Number of pages reserved for partition table in each
|
|
NAND block.
|
|
*/
|
|
#define kNAND_NVRAM_PAGE_RESERVED_IN_BLOCK 2
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@group private platform-independent constant definitions
|
|
*/
|
|
|
|
/*!
|
|
@const NULL
|
|
|
|
@abstract It really sucks that some of our systems don't define NULL.
|
|
*/
|
|
#ifndef NULL
|
|
#define NULL ((void *)0)
|
|
#endif
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_MAX_SIZE
|
|
|
|
@abstract Maximum amount of storage; should fit into a standard 2K page.
|
|
*/
|
|
#define kNAND_NVRAM_MAX_SIZE (128 * 2048)
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_SIGNATURE
|
|
|
|
@abstract Constant value used to identify nand nvram meta data.
|
|
*/
|
|
#define kNAND_NVRAM_SIGNATURE ((uint16_t) 0xBEAD)
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_VERSION_MAJOR
|
|
|
|
@abstract Major version of the driver that wrote the nvram content.
|
|
Major version differences are considered to be incompatible. Even
|
|
major version numbers are reserved for development purposes; odd
|
|
version numbers should be used for when development is frozen,
|
|
stabilized, and therefore only accepting minor revision level changes.
|
|
*/
|
|
#define kNAND_NVRAM_FEATURE_EXTRA_AREA_VERSION_MAJOR ((uint8_t) 0x0)
|
|
#define kNAND_NVRAM_VERSION_MAJOR kNAND_NVRAM_FEATURE_EXTRA_AREA_VERSION_MAJOR
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_VERSION_MINOR
|
|
|
|
@abstract Minor version of the driver that wrote the nvram content.
|
|
Minor versions should be fully compatible within a major version and
|
|
are intended to be incremented when the driver has changed between
|
|
public releases.
|
|
*/
|
|
#define kNAND_NVRAM_FEATURE_EXTRA_AREA_VERSION_MINOR ((uint8_t) 0x3)
|
|
#define kNAND_NVRAM_VERSION_MINOR kNAND_NVRAM_FEATURE_EXTRA_AREA_VERSION_MINOR
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_GENERATION_ERASED
|
|
|
|
@abstract A generation number of all ones is reserved since it also
|
|
corresponds to the erased state of nand bits.
|
|
*/
|
|
#define kNAND_NVRAM_GENERATION_ERASED ((uint32_t) 0xFFFFFFFF)
|
|
|
|
/*!
|
|
@const kNAND_NVRAM_GENERATION_UNKNOWN
|
|
|
|
@abstract A generation number of all zeros is reserved since it
|
|
corresponds to the state of an uninitialized meta struct.
|
|
*/
|
|
#define kNAND_NVRAM_GENERATION_UNKNOWN ((uint32_t) 0x00000000)
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@group public platform-independent structure declarations
|
|
*/
|
|
|
|
/*!
|
|
@struct nand_nvram_geometry
|
|
|
|
@abstract Geometry of nand device array slice.
|
|
|
|
@field number_of_banks Number of logical banks.
|
|
|
|
@field blocks_per_bank Number of blocks in each bank.
|
|
|
|
@field pages_per_block Number of pages per block.
|
|
|
|
@field data_pages_per_block Number of pages per block available for data storage.
|
|
|
|
@field bytes_per_page Size in bytes of page.
|
|
|
|
@field bytes_per_meta_buffer Size in bytes of buffer for in-memory per-page meta info.
|
|
|
|
@field bytes_per_meta_actual Size in bytes of in-storage per-page meta info (i.e. actual size).
|
|
*/
|
|
struct nand_nvram_geometry {
|
|
|
|
uint32_t number_of_banks;
|
|
uint32_t blocks_per_bank;
|
|
uint32_t pages_per_block;
|
|
uint32_t data_pages_per_block;
|
|
uint32_t bytes_per_page;
|
|
uint32_t bytes_per_meta_buffer;
|
|
uint32_t bytes_per_meta_actual;
|
|
};
|
|
|
|
/* ========================================================================== */
|
|
|
|
/*!
|
|
@group private platform-independent structure declarations
|
|
*/
|
|
|
|
/*!
|
|
@struct _meta
|
|
|
|
@abstract Structure defining per-page meta layout.
|
|
|
|
@field generation Monotonically increasing generation of blob;
|
|
kNAND_NVRAM_GENERATION_UNKNOWN and kNAND_NVRAM_GENERATION_ERASED are
|
|
reserved values that should never appear on a nand device.
|
|
|
|
@field page_max Maximum page index for blob (i.e. page count - 1).
|
|
|
|
@field page_idx Page index of this meta within blob.
|
|
|
|
@field version_major Major version number of nand nvram driver.
|
|
|
|
@field version_minor Minor version number of nand nvram driver.
|
|
|
|
@field signature Constant value of kNAND_NVRAM_SIGNATURE marks valid
|
|
nvram meta.
|
|
*/
|
|
struct _meta {
|
|
|
|
uint32_t generation;
|
|
uint8_t page_max;
|
|
uint8_t page_idx;
|
|
uint8_t version_major;
|
|
uint8_t version_minor;
|
|
uint16_t signature;
|
|
|
|
} __attribute__((__packed__));
|
|
|
|
/*!
|
|
@struct _blob
|
|
|
|
@abstract Container for N pages of data and meta information
|
|
for convenience of writing to/from nand devices.
|
|
|
|
@field pageCount Number of pages currently allocated to
|
|
shadow the blob.
|
|
|
|
@field metaBufs Buffer containing pages' meta structs.
|
|
|
|
@field dataBufs Buffer containing pages' data.
|
|
*/
|
|
struct _blob {
|
|
|
|
void * meta_bufs;
|
|
void * data_bufs;
|
|
};
|
|
|
|
/*!
|
|
@struct nand_nvram
|
|
|
|
@abstract NAND-based nvram driver context information.
|
|
|
|
@field geometry Geometry of nand device array slice used for
|
|
backing store.
|
|
|
|
@field is_dirty Flag indicating whether shadow has been
|
|
modified since last restore or sync.
|
|
|
|
@field shadow Blob used as container for pages of data and meta
|
|
information being shadowed from nand.
|
|
|
|
@field cursors Array of page numbers of next page in each
|
|
bank available for commit.
|
|
*/
|
|
struct nand_nvram {
|
|
|
|
nand_nvram_geometry_t geo;
|
|
void * context;
|
|
uint32_t size;
|
|
bool is_born;
|
|
bool is_dirty;
|
|
uint32_t * watermarks;
|
|
uint32_t * cursors;
|
|
bool * copies;
|
|
blob_t * shadow;
|
|
};
|
|
|
|
/* ========================================================================== */
|
|
|
|
__END_DECLS
|
|
|
|
#endif /* ! _NAND_NVRAM_IMPL_H */
|
|
|
|
/* ========================================================================== */
|