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 #include <sys/refcount.h> 36 37 #ifdef _KERNEL 38 #include <machine/stdarg.h> 39 #else /* !_KERNEL */ 40 #include <stdarg.h> 41 #endif /* _KERNEL */ 42 43 #include "bhnd_nvram.h" 44 45 typedef struct bhnd_nvram_val_fmt bhnd_nvram_val_fmt; 46 typedef struct bhnd_nvram_val bhnd_nvram_val; 47 48 const char *bhnd_nvram_val_fmt_name( 49 const bhnd_nvram_val_fmt *fmt); 50 51 const bhnd_nvram_val_fmt *bhnd_nvram_val_default_fmt( 52 bhnd_nvram_type type); 53 54 int bhnd_nvram_val_init(bhnd_nvram_val *value, 55 const bhnd_nvram_val_fmt *fmt, 56 const void *inp, size_t ilen, 57 bhnd_nvram_type itype, uint32_t flags); 58 59 int bhnd_nvram_val_convert_init( 60 bhnd_nvram_val *value, 61 const bhnd_nvram_val_fmt *fmt, 62 bhnd_nvram_val *src, uint32_t flags); 63 64 int bhnd_nvram_val_new(bhnd_nvram_val **value, 65 const bhnd_nvram_val_fmt *fmt, 66 const void *inp, size_t ilen, 67 bhnd_nvram_type itype, uint32_t flags); 68 69 int bhnd_nvram_val_convert_new( 70 bhnd_nvram_val **value, 71 const bhnd_nvram_val_fmt *fmt, 72 bhnd_nvram_val *src, uint32_t flags); 73 74 bhnd_nvram_val *bhnd_nvram_val_copy(bhnd_nvram_val *value); 75 76 void bhnd_nvram_val_release( 77 bhnd_nvram_val *value); 78 79 int bhnd_nvram_val_encode(bhnd_nvram_val *value, 80 void *outp, size_t *olen, 81 bhnd_nvram_type otype); 82 83 int bhnd_nvram_val_encode_elem( 84 bhnd_nvram_val *value, const void *inp, 85 size_t ilen, void *outp, size_t *olen, 86 bhnd_nvram_type otype); 87 88 int bhnd_nvram_val_printf(bhnd_nvram_val *value, 89 const char *fmt, char *outp, size_t *olen, 90 ...); 91 int bhnd_nvram_val_vprintf(bhnd_nvram_val *value, 92 const char *fmt, char *outp, size_t *olen, 93 va_list ap); 94 95 const void *bhnd_nvram_val_bytes(bhnd_nvram_val *value, 96 size_t *olen, bhnd_nvram_type *otype); 97 98 bhnd_nvram_type bhnd_nvram_val_type(bhnd_nvram_val *value); 99 bhnd_nvram_type bhnd_nvram_val_elem_type( 100 bhnd_nvram_val *value); 101 102 const void *bhnd_nvram_val_next(bhnd_nvram_val *value, 103 const void *prev, size_t *olen); 104 105 size_t bhnd_nvram_val_nelem(bhnd_nvram_val *value); 106 107 /** 108 * NVRAM value flags 109 */ 110 enum { 111 /** 112 * Do not allocate additional space for value data; all data must be 113 * represented inline within the value structure (default). 114 */ 115 BHND_NVRAM_VAL_FIXED = (0<<0), 116 117 /** 118 * Automatically allocate additional space for value data if it cannot 119 * be represented within the value structure. 120 */ 121 BHND_NVRAM_VAL_DYNAMIC = (1<<0), 122 123 /** 124 * Copy the value data upon initialization. (default). 125 */ 126 BHND_NVRAM_VAL_COPY_DATA = (0<<1), 127 128 /** 129 * Do not perform an initial copy of the value data; the data must 130 * remain valid for the lifetime of the NVRAM value. 131 * 132 * Value data will still be copied if the value itself is copied to the 133 * heap. 134 */ 135 BHND_NVRAM_VAL_BORROW_DATA = (1<<1), 136 137 /** 138 * Do not copy the value data when copying the value to the heap; the 139 * vlaue data is assumed to be statically allocated and must remain 140 * valid for the lifetime of the process. 141 * 142 * Implies BHND_NVRAM_VAL_BORROW_DATA. 143 */ 144 BHND_NVRAM_VAL_STATIC_DATA = (1<<2), 145 }; 146 147 /** 148 * @internal 149 * 150 * NVRAM value storage types. 151 */ 152 typedef enum { 153 /** 154 * The value structure has an automatic storage duration 155 * (e.g. it is stack allocated, or is otherwise externally managed), 156 * and no destructors will be run prior to deallocation of the value. 157 * 158 * When performing copy/retain, the existing structure must be copied 159 * to a new heap allocation. 160 */ 161 BHND_NVRAM_VAL_STORAGE_AUTO = 0, 162 163 /** 164 * The value structure was heap allocated and is fully managed by the 165 * the NVRAM value API. 166 * 167 * When performing copy/retain, the existing structure may be retained 168 * as-is. 169 */ 170 BHND_NVRAM_VAL_STORAGE_DYNAMIC = 2, 171 172 /** 173 * The value structure has a static storage duration, and will never 174 * be deallocated. 175 * 176 * When performing copy/retain, the existing structure may be referenced 177 * without modification. 178 */ 179 BHND_NVRAM_VAL_STORAGE_STATIC = 3, 180 } bhnd_nvram_val_storage; 181 182 /** 183 * @internal 184 * 185 * NVRAM data storage types. 186 */ 187 typedef enum { 188 /** Value has no active representation. This is the default for 189 * zero-initialized value structures. */ 190 BHND_NVRAM_VAL_DATA_NONE = 0, 191 192 /** Value data is represented inline */ 193 BHND_NVRAM_VAL_DATA_INLINE = 1, 194 195 /** 196 * Value represented by an external reference to data with a static 197 * storage location. The data need not be copied if copying the value. 198 */ 199 BHND_NVRAM_VAL_DATA_EXT_STATIC = 2, 200 201 /** 202 * Value represented by weak external reference, which must be copied 203 * if copying the value. 204 */ 205 BHND_NVRAM_VAL_DATA_EXT_WEAK = 3, 206 207 /** 208 * Value represented by an external reference that must be deallocated 209 * when deallocating the value. 210 */ 211 BHND_NVRAM_VAL_DATA_EXT_ALLOC = 4, 212 } bhnd_nvram_val_data_storage; 213 214 /** 215 * NVRAM value 216 */ 217 struct bhnd_nvram_val { 218 volatile u_int refs; /**< reference count */ 219 bhnd_nvram_val_storage val_storage; /**< value structure storage */ 220 const bhnd_nvram_val_fmt *fmt; /**< value format */ 221 bhnd_nvram_val_data_storage data_storage; /**< data storage */ 222 bhnd_nvram_type data_type; /**< data type */ 223 size_t data_len; /**< data size */ 224 225 /** data representation */ 226 union { 227 uint8_t u8[8]; /**< 8-bit unsigned data */ 228 uint16_t u16[4]; /**< 16-bit unsigned data */ 229 uint32_t u32[2]; /**< 32-bit unsigned data */ 230 uint32_t u64[1]; /**< 64-bit unsigned data */ 231 int8_t i8[8]; /**< 8-bit signed data */ 232 int16_t i16[4]; /**< 16-bit signed data */ 233 int32_t i32[2]; /**< 32-bit signed data */ 234 int64_t i64[1]; /**< 64-bit signed data */ 235 unsigned char ch[8]; /**< 8-bit character data */ 236 bhnd_nvram_bool_t b[8]; /**< 8-bit boolean data */ 237 const void *ptr; /**< external data */ 238 } data; 239 }; 240 241 /** Declare a bhnd_nvram_val_fmt with name @p _n */ 242 #define BHND_NVRAM_VAL_FMT_DECL(_n) \ 243 extern const bhnd_nvram_val_fmt bhnd_nvram_val_ ## _n ## _fmt; 244 245 BHND_NVRAM_VAL_FMT_DECL(bcm_decimal); 246 BHND_NVRAM_VAL_FMT_DECL(bcm_hex); 247 BHND_NVRAM_VAL_FMT_DECL(bcm_leddc); 248 BHND_NVRAM_VAL_FMT_DECL(bcm_macaddr); 249 BHND_NVRAM_VAL_FMT_DECL(bcm_string); 250 251 BHND_NVRAM_VAL_FMT_DECL(uint8); 252 BHND_NVRAM_VAL_FMT_DECL(uint16); 253 BHND_NVRAM_VAL_FMT_DECL(uint32); 254 BHND_NVRAM_VAL_FMT_DECL(uint64); 255 BHND_NVRAM_VAL_FMT_DECL(int8); 256 BHND_NVRAM_VAL_FMT_DECL(int16); 257 BHND_NVRAM_VAL_FMT_DECL(int32); 258 BHND_NVRAM_VAL_FMT_DECL(int64); 259 BHND_NVRAM_VAL_FMT_DECL(char); 260 BHND_NVRAM_VAL_FMT_DECL(bool); 261 BHND_NVRAM_VAL_FMT_DECL(string); 262 BHND_NVRAM_VAL_FMT_DECL(data); 263 BHND_NVRAM_VAL_FMT_DECL(null); 264 265 BHND_NVRAM_VAL_FMT_DECL(uint8_array); 266 BHND_NVRAM_VAL_FMT_DECL(uint16_array); 267 BHND_NVRAM_VAL_FMT_DECL(uint32_array); 268 BHND_NVRAM_VAL_FMT_DECL(uint64_array); 269 BHND_NVRAM_VAL_FMT_DECL(int8_array); 270 BHND_NVRAM_VAL_FMT_DECL(int16_array); 271 BHND_NVRAM_VAL_FMT_DECL(int32_array); 272 BHND_NVRAM_VAL_FMT_DECL(int64_array); 273 BHND_NVRAM_VAL_FMT_DECL(char_array); 274 BHND_NVRAM_VAL_FMT_DECL(bool_array); 275 BHND_NVRAM_VAL_FMT_DECL(string_array); 276 277 /** Shared NULL value instance */ 278 #define BHND_NVRAM_VAL_NULL (&bhnd_nvram_val_null) 279 extern bhnd_nvram_val bhnd_nvram_val_null; 280 281 #endif /* _BHND_NVRAM_BHND_NVRAM_VALUE_H_ */ 282