1/*  *********************************************************************
2    *  Broadcom Common Firmware Environment (CFE)
3    *
4    *  nvram environment manipulation		File: bcmnvram.h
5    *
6    *  Definitions and prototypes for nvram variable subroutines.
7    *
8    *  The functionality is roughly parallel to env_subr.h but the
9    *  inteface is designed to match the HND "nvram" functions.  This
10    *  file replaces their nvram.h and defines a subset of the same
11    *  interface.
12    *
13    *********************************************************************
14    *
15    *  Copyright 2003,2004
16    *  Broadcom Corporation. All rights reserved.
17    *
18    *  This software is furnished under license and may be used and
19    *  copied only in accordance with the following terms and
20    *  conditions.  Subject to these conditions, you may download,
21    *  copy, install, use, modify and distribute modified or unmodified
22    *  copies of this software in source and/or binary form.  No title
23    *  or ownership is transferred hereby.
24    *
25    *  1) Any source code used, modified or distributed must reproduce
26    *     and retain this copyright notice and list of conditions
27    *     as they appear in the source file.
28    *
29    *  2) No right is granted to use any trade name, trademark, or
30    *     logo of Broadcom Corporation.  The "Broadcom Corporation"
31    *     name may not be used to endorse or promote products derived
32    *     from this software without the prior written permission of
33    *     Broadcom Corporation.
34    *
35    *  3) THIS SOFTWARE IS PROVIDED "AS-IS" AND ANY EXPRESS OR
36    *     IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO, ANY IMPLIED
37    *     WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
38    *     PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT
39    *     SHALL BROADCOM BE LIABLE FOR ANY DAMAGES WHATSOEVER, AND IN
40    *     PARTICULAR, BROADCOM SHALL NOT BE LIABLE FOR DIRECT, INDIRECT,
41    *     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
42    *     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
43    *     GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
44    *     BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
45    *     OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
46    *     TORT (INCLUDING NEGLIGENCE OR OTHERWISE), EVEN IF ADVISED OF
47    *     THE POSSIBILITY OF SUCH DAMAGE.
48    ********************************************************************* */
49
50
51#ifndef _BCMNVRAM_H
52#define _BCMNVRAM_H
53
54/*  *********************************************************************
55    *  Conventions
56    ********************************************************************* */
57
58/*
59 * The representation of nvram variable bindings is effectively a
60 * public interface, since other versions of the firmware and various
61 * operating systems interpret the same data structures.
62 *
63 * There is a binary header of type nvram_header_t (see below).
64 * The flash/nvram region following the header stores a sequence
65 * of <name,value> tuples.  The binding of each environment variable
66 * is stored as a null-terminated ASCII string with the format:
67 *                   <name>=<value>
68 * The strings are contiguous in memory; the end of the sequence is marked
69 * by an empty string (two consecutive null characeters).
70 *
71 * The header is word oriented, in match-bits order.  The characters
72 * of the tuple strings are stored in little-endian byte order when
73 * in non-volatile memory and must be converted to/from host byte
74 * order internally.
75 */
76
77/*  *********************************************************************
78    *  Data structures.
79    ********************************************************************* */
80
81typedef struct nvram_header_s {
82    uint32_t  magic;
83    uint32_t  len;
84    uint32_t  crc_ver_init;
85    uint32_t  config_refresh;
86    uint32_t  config_ncdl;
87} nvram_header_t;
88
89typedef struct {
90    const char *envname;
91    const char *nvname;
92    const char *def;
93} nvram_import_t;
94
95
96#define NVRAM_CRC_SHIFT        0
97#define NVRAM_CRC_MASK         (0xFF << NVRAM_CRC_SHIFT)
98#define NVRAM_VER_SHIFT        8
99#define NVRAM_VER_MASK         (0xFF << NVRAM_VER_SHIFT)
100#define NVRAM_INIT_SHIFT       16
101#define NVRAM_INIT_MASK        (0xFFF << NVRAM_INIT_SHIFT)
102#define NVRAM_MEMTEST_MASK     (0x1 << 28)
103
104#define NVRAM_CONFIG_SHIFT     0
105#define NVRAM_CONFIG_MASK      (0xFFFF << NVRAM_CONFIG_SHIFT)
106#define NVRAM_REFRESH_SHIFT    16
107#define NVRAM_REFRESH_MASK     (0xFFFF << NVRAM_REFRESH_MASK)
108
109/*  *********************************************************************
110    *  Constants
111    ********************************************************************* */
112
113#define NVRAM_MAGIC            0x48534C46     /* 'FLSH' (little-endian) */
114#define NVRAM_VERSION          1
115
116#define NVRAM_SPACE            0x8000         /* Header plus tuples */
117
118/*  *********************************************************************
119    *  Globals
120    ********************************************************************* */
121
122extern nvram_import_t *nvram_import_data;
123
124/*  *********************************************************************
125    *  Prototypes
126    ********************************************************************* */
127
128/* Initialize from non-volatile storage. */
129int         nvram_init (uint8_t *base, size_t size);
130
131/* Enumerate all tuples in arbitrary order.  Calls of set and unset
132   have unpredictable effect. */
133int         nvram_enum (int (*proc)(const char *tuple));
134
135/* Lookup, add, delete variables. */
136const char *nvram_get(const char *name);
137int         nvram_set(const char *name, const char *value);
138int         nvram_unset(const char *name);
139
140/* Commit to non-volatile storage. */
141int         nvram_commit(int device);
142
143#endif /* _BCMNVRAM_H */
144