sys/dev/bhnd/nvram/bhnd_nvram_value.h

   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_ */