1 /*- 2 * Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org> 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer, 10 * without modification. 11 * 2. Redistributions in binary form must reproduce at minimum a disclaimer 12 * similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any 13 * redistribution must be conditioned upon including a substantially 14 * similar Disclaimer requirement for further binary redistribution. 15 * 16 * NO WARRANTY 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 * LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY 20 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21 * THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, 22 * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 25 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 27 * THE POSSIBILITY OF SUCH DAMAGES. 28 * 29 * $FreeBSD$ 30 */ 31 32 #ifndef _BHND_NVRAM_BHND_NVRAM_VALUE_H_ 33 #define _BHND_NVRAM_BHND_NVRAM_VALUE_H_ 34 35 36 #include <sys/refcount.h> 37 38 #ifdef _KERNEL 39 #include <machine/stdarg.h> 40 #else /* !_KERNEL */ 41 #include <stdarg.h> 42 #endif /* _KERNEL */ 43 44 #include "bhnd_nvram.h" 45 46 typedef struct bhnd_nvram_val_fmt bhnd_nvram_val_fmt; 47 typedef struct bhnd_nvram_val bhnd_nvram_val; 48 49 const char *bhnd_nvram_val_fmt_name( 50 const bhnd_nvram_val_fmt *fmt); 51 52 const bhnd_nvram_val_fmt *bhnd_nvram_val_default_fmt( 53 bhnd_nvram_type type); 54 55 int bhnd_nvram_val_init(bhnd_nvram_val *value, 56 const bhnd_nvram_val_fmt *fmt, 57 const void *inp, size_t ilen, 58 bhnd_nvram_type itype, uint32_t flags); 59 60 int bhnd_nvram_val_convert_init( 61 bhnd_nvram_val *value, 62 const bhnd_nvram_val_fmt *fmt, 63 bhnd_nvram_val *src, uint32_t flags); 64 65 int bhnd_nvram_val_new(bhnd_nvram_val **value, 66 const bhnd_nvram_val_fmt *fmt, 67 const void *inp, size_t ilen, 68 bhnd_nvram_type itype, uint32_t flags); 69 70 int bhnd_nvram_val_convert_new( 71 bhnd_nvram_val **value, 72 const bhnd_nvram_val_fmt *fmt, 73 bhnd_nvram_val *src, uint32_t flags); 74 75 bhnd_nvram_val *bhnd_nvram_val_copy(bhnd_nvram_val *value); 76 77 void bhnd_nvram_val_release( 78 bhnd_nvram_val *value); 79 80 int bhnd_nvram_val_encode(bhnd_nvram_val *value, 81 void *outp, size_t *olen, 82 bhnd_nvram_type otype); 83 84 int bhnd_nvram_val_encode_elem( 85 bhnd_nvram_val *value, const void *inp, 86 size_t ilen, void *outp, size_t *olen, 87 bhnd_nvram_type otype); 88 89 int bhnd_nvram_val_printf(bhnd_nvram_val *value, 90 const char *fmt, char *outp, size_t *olen, 91 ...); 92 int bhnd_nvram_val_vprintf(bhnd_nvram_val *value, 93 const char *fmt, char *outp, size_t *olen, 94 va_list ap); 95 96 97 const void *bhnd_nvram_val_bytes(bhnd_nvram_val *value, 98 size_t *olen, bhnd_nvram_type *otype); 99 100 bhnd_nvram_type bhnd_nvram_val_type(bhnd_nvram_val *value); 101 bhnd_nvram_type bhnd_nvram_val_elem_type( 102 bhnd_nvram_val *value); 103 104 const void *bhnd_nvram_val_next(bhnd_nvram_val *value, 105 const void *prev, size_t *olen); 106 107 size_t bhnd_nvram_val_nelem(bhnd_nvram_val *value); 108 109 /** 110 * NVRAM value flags 111 */ 112 enum { 113 /** 114 * Do not allocate additional space for value data; all data must be 115 * represented inline within the value structure (default). 116 */ 117 BHND_NVRAM_VAL_FIXED = (0<<0), 118 119 /** 120 * Automatically allocate additional space for value data if it cannot 121 * be represented within the value structure. 122 */ 123 BHND_NVRAM_VAL_DYNAMIC = (1<<0), 124 125 /** 126 * Copy the value data upon initialization. (default). 127 */ 128 BHND_NVRAM_VAL_COPY_DATA = (0<<1), 129 130 /** 131 * Do not perform an initial copy of the value data; the data must 132 * remain valid for the lifetime of the NVRAM value. 133 * 134 * Value data will still be copied if the value itself is copied to the 135 * heap. 136 */ 137 BHND_NVRAM_VAL_BORROW_DATA = (1<<1), 138 139 /** 140 * Do not copy the value data when copying the value to the heap; the 141 * vlaue data is assumed to be statically allocated and must remain 142 * valid for the lifetime of the process. 143 * 144 * Implies BHND_NVRAM_VAL_BORROW_DATA. 145 */ 146 BHND_NVRAM_VAL_STATIC_DATA = (1<<2), 147 }; 148 149 /** 150 * @internal 151 * 152 * NVRAM value storage types. 153 */ 154 typedef enum { 155 /** 156 * The value structure has an automatic storage duration 157 * (e.g. it is stack allocated, or is otherwise externally managed), 158 * and no destructors will be run prior to deallocation of the value. 159 * 160 * When performing copy/retain, the existing structure must be copied 161 * to a new heap allocation. 162 */ 163 BHND_NVRAM_VAL_STORAGE_AUTO = 0, 164 165 /** 166 * The value structure was heap allocated and is fully managed by the 167 * the NVRAM value API. 168 * 169 * When performing copy/retain, the existing structure may be retained 170 * as-is. 171 */ 172 BHND_NVRAM_VAL_STORAGE_DYNAMIC = 2, 173 174 /** 175 * The value structure has a static storage duration, and will never 176 * be deallocated. 177 * 178 * When performing copy/retain, the existing structure may be referenced 179 * without modification. 180 */ 181 BHND_NVRAM_VAL_STORAGE_STATIC = 3, 182 } bhnd_nvram_val_storage; 183 184 /** 185 * @internal 186 * 187 * NVRAM data storage types. 188 */ 189 typedef enum { 190 /** Value has no active representation. This is the default for 191 * zero-initialized value structures. */ 192 BHND_NVRAM_VAL_DATA_NONE = 0, 193 194 /** Value data is represented inline */ 195 BHND_NVRAM_VAL_DATA_INLINE = 1, 196 197 /** 198 * Value represented by an external reference to data with a static 199 * storage location. The data need not be copied if copying the value. 200 */ 201 BHND_NVRAM_VAL_DATA_EXT_STATIC = 2, 202 203 /** 204 * Value represented by weak external reference, which must be copied 205 * if copying the value. 206 */ 207 BHND_NVRAM_VAL_DATA_EXT_WEAK = 3, 208 209 /** 210 * Value represented by an external reference that must be deallocated 211 * when deallocating the value. 212 */ 213 BHND_NVRAM_VAL_DATA_EXT_ALLOC = 4, 214 } bhnd_nvram_val_data_storage; 215 216 /** 217 * NVRAM value 218 */ 219 struct bhnd_nvram_val { 220 volatile u_int refs; /**< reference count */ 221 bhnd_nvram_val_storage val_storage; /**< value structure storage */ 222 const bhnd_nvram_val_fmt *fmt; /**< value format */ 223 bhnd_nvram_val_data_storage data_storage; /**< data storage */ 224 bhnd_nvram_type data_type; /**< data type */ 225 size_t data_len; /**< data size */ 226 227 /** data representation */ 228 union { 229 uint8_t u8[8]; /**< 8-bit unsigned data */ 230 uint16_t u16[4]; /**< 16-bit unsigned data */ 231 uint32_t u32[2]; /**< 32-bit unsigned data */ 232 uint32_t u64[1]; /**< 64-bit unsigned data */ 233 int8_t i8[8]; /**< 8-bit signed data */ 234 int16_t i16[4]; /**< 16-bit signed data */ 235 int32_t i32[2]; /**< 32-bit signed data */ 236 int64_t i64[1]; /**< 64-bit signed data */ 237 unsigned char ch[8]; /**< 8-bit character data */ 238 bhnd_nvram_bool_t b[8]; /**< 8-bit boolean data */ 239 const void *ptr; /**< external data */ 240 } data; 241 }; 242 243 /** Declare a bhnd_nvram_val_fmt with name @p _n */ 244 #define BHND_NVRAM_VAL_FMT_DECL(_n) \ 245 extern const bhnd_nvram_val_fmt bhnd_nvram_val_ ## _n ## _fmt; 246 247 BHND_NVRAM_VAL_FMT_DECL(bcm_decimal); 248 BHND_NVRAM_VAL_FMT_DECL(bcm_hex); 249 BHND_NVRAM_VAL_FMT_DECL(bcm_leddc); 250 BHND_NVRAM_VAL_FMT_DECL(bcm_macaddr); 251 BHND_NVRAM_VAL_FMT_DECL(bcm_string); 252 253 BHND_NVRAM_VAL_FMT_DECL(uint8); 254 BHND_NVRAM_VAL_FMT_DECL(uint16); 255 BHND_NVRAM_VAL_FMT_DECL(uint32); 256 BHND_NVRAM_VAL_FMT_DECL(uint64); 257 BHND_NVRAM_VAL_FMT_DECL(int8); 258 BHND_NVRAM_VAL_FMT_DECL(int16); 259 BHND_NVRAM_VAL_FMT_DECL(int32); 260 BHND_NVRAM_VAL_FMT_DECL(int64); 261 BHND_NVRAM_VAL_FMT_DECL(char); 262 BHND_NVRAM_VAL_FMT_DECL(bool); 263 BHND_NVRAM_VAL_FMT_DECL(string); 264 BHND_NVRAM_VAL_FMT_DECL(data); 265 BHND_NVRAM_VAL_FMT_DECL(null); 266 267 BHND_NVRAM_VAL_FMT_DECL(uint8_array); 268 BHND_NVRAM_VAL_FMT_DECL(uint16_array); 269 BHND_NVRAM_VAL_FMT_DECL(uint32_array); 270 BHND_NVRAM_VAL_FMT_DECL(uint64_array); 271 BHND_NVRAM_VAL_FMT_DECL(int8_array); 272 BHND_NVRAM_VAL_FMT_DECL(int16_array); 273 BHND_NVRAM_VAL_FMT_DECL(int32_array); 274 BHND_NVRAM_VAL_FMT_DECL(int64_array); 275 BHND_NVRAM_VAL_FMT_DECL(char_array); 276 BHND_NVRAM_VAL_FMT_DECL(bool_array); 277 BHND_NVRAM_VAL_FMT_DECL(string_array); 278 279 /** Shared NULL value instance */ 280 #define BHND_NVRAM_VAL_NULL (&bhnd_nvram_val_null) 281 extern bhnd_nvram_val bhnd_nvram_val_null; 282 283 #endif /* _BHND_NVRAM_BHND_NVRAM_VALUE_H_ */ 284