2 * Copyright (c) 2015-2016 Landon Fuller <landonf@FreeBSD.org>
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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.
30 #include <sys/cdefs.h>
31 __FBSDID("$FreeBSD$");
36 #include <sys/param.h>
37 #include <sys/systm.h>
39 #include <machine/_inttypes.h>
50 #include "bhnd_nvram_private.h"
51 #include "bhnd_nvram_io.h"
53 #include "bhnd_nvram_datavar.h"
54 #include "bhnd_nvram_data.h"
57 * Return a human-readable description for the given NVRAM data class.
59 * @param cls The NVRAM class.
62 bhnd_nvram_data_class_desc(bhnd_nvram_data_class *cls)
68 * Return the class-level capability flags (@see BHND_NVRAM_DATA_CAP_*) for
71 * @param cls The NVRAM class.
74 bhnd_nvram_data_class_caps(bhnd_nvram_data_class *cls)
80 * Serialize all NVRAM properties in @p plist using @p cls's NVRAM data
81 * format, writing the result to @p outp.
83 * @param cls The NVRAM data class to be used to perform
85 * @param props The raw property values to be serialized to
86 * @p outp, in serialization order.
87 * @param options Serialization options for @p cls, or NULL.
88 * @param[out] outp On success, the serialed NVRAM data will be
89 * written to this buffer. This argment may be
90 * NULL if the value is not desired.
91 * @param[in,out] olen The capacity of @p buf. On success, will be set
92 * to the actual length of the serialized data.
96 * @retval ENOMEM If @p outp is non-NULL and a buffer of @p olen is too
97 * small to hold the serialized data.
98 * @retval EINVAL If a property value required by @p cls is not found in
100 * @retval EFTYPE If a property value in @p plist cannot be represented
101 * as the data type required by @p cls.
102 * @retval ERANGE If a property value in @p plist would would overflow
103 * (or underflow) the data type required by @p cls.
104 * @retval non-zero If serialization otherwise fails, a regular unix error
105 * code will be returned.
108 bhnd_nvram_data_serialize(bhnd_nvram_data_class *cls,
109 bhnd_nvram_plist *props, bhnd_nvram_plist *options, void *outp,
112 return (cls->op_serialize(cls, props, options, outp, olen));
116 * Probe to see if this NVRAM data class class supports the data mapped by the
117 * given I/O context, returning a BHND_NVRAM_DATA_PROBE probe result.
119 * @param cls The NVRAM class.
120 * @param io An I/O context mapping the NVRAM data.
122 * @retval 0 if this is the only possible NVRAM data class for @p io.
123 * @retval negative if the probe succeeds, a negative value should be returned;
124 * the class returning the highest negative value should be selected to handle
126 * @retval ENXIO If the NVRAM format is not handled by @p cls.
127 * @retval positive if an error occurs during probing, a regular unix error
128 * code should be returned.
131 bhnd_nvram_data_probe(bhnd_nvram_data_class *cls, struct bhnd_nvram_io *io)
133 return (cls->op_probe(io));
137 * Probe to see if an NVRAM data class in @p classes supports parsing
138 * of the data mapped by @p io, returning the parsed data in @p data.
140 * The caller is responsible for deallocating the returned instance via
141 * bhnd_nvram_data_release().
143 * @param[out] data On success, the parsed NVRAM data instance.
144 * @param io An I/O context mapping the NVRAM data to be copied and parsed.
145 * @param classes An array of NVRAM data classes to be probed, or NULL to
146 * probe the default supported set.
147 * @param num_classes The number of NVRAM data classes in @p classes.
150 * @retval ENXIO if no class is found capable of parsing @p io.
151 * @retval non-zero if an error otherwise occurs during allocation,
152 * initialization, or parsing of the NVRAM data, a regular unix error code
156 bhnd_nvram_data_probe_classes(struct bhnd_nvram_data **data,
157 struct bhnd_nvram_io *io, bhnd_nvram_data_class *classes[],
160 bhnd_nvram_data_class *cls;
161 int error, prio, result;
167 /* If class array is NULL, default to our linker set */
168 if (classes == NULL) {
169 classes = SET_BEGIN(bhnd_nvram_data_class_set);
170 num_classes = SET_COUNT(bhnd_nvram_data_class_set);
173 /* Try to find the best data class capable of parsing io */
174 for (size_t i = 0; i < num_classes; i++) {
175 bhnd_nvram_data_class *next_cls;
177 next_cls = classes[i];
180 result = bhnd_nvram_data_probe(next_cls, io);
182 /* The parser did not match if an error was returned */
186 /* Lower priority than previous match; keep
188 if (cls != NULL && result <= prio)
191 /* Drop any previously parsed data */
193 bhnd_nvram_data_release(*data);
197 /* If this is a 'maybe' match, attempt actual parsing to
198 * verify that this does in fact match */
199 if (result <= BHND_NVRAM_DATA_PROBE_MAYBE) {
200 /* If parsing fails, keep searching */
201 error = bhnd_nvram_data_new(next_cls, data, io);
206 /* Record best new match */
211 /* Terminate search immediately on
212 * BHND_NVRAM_DATA_PROBE_SPECIFIC */
213 if (result == BHND_NVRAM_DATA_PROBE_SPECIFIC)
217 /* If no match, return error */
221 /* If the NVRAM data was not parsed above, do so now */
223 if ((error = bhnd_nvram_data_new(cls, data, io)))
231 * Read a variable directly from @p io and decode as @p type.
233 * This may be used to perform reading of NVRAM variables during the very
234 * early boot process, prior to the availability of the kernel allocator.
236 * @param cls An NVRAM class capable of parsing @p io.
237 * @param io NVRAM data to be parsed.
238 * @param name The raw name of the variable to be fetched,
239 * including any device path (/pci/1/1/varname) or
240 * alias prefix (0:varname).
241 * @param[out] buf On success, the requested value will be written
242 * to this buffer. This argment may be NULL if
243 * the value is not desired.
244 * @param[in,out] len The capacity of @p buf. On success, will be set
245 * to the actual size of the requested value.
246 * @param type The data type to be written to @p buf.
249 * @retval ENOMEM If @p buf is non-NULL and a buffer of @p len is too
250 * small to hold the requested value.
251 * @retval ENOENT If @p name is not found in @p io.
252 * @retval EFTYPE If the variable data cannot be coerced to @p type.
253 * @retval ERANGE If value coercion would overflow @p type.
254 * @retval non-zero If parsing @p io otherwise fails, a regular unix error
255 * code will be returned.
258 bhnd_nvram_data_getvar_direct(bhnd_nvram_data_class *cls,
259 struct bhnd_nvram_io *io, const char *name, void *buf, size_t *len,
260 bhnd_nvram_type type)
262 return (cls->op_getvar_direct(io, name, buf, len, type));
266 * Allocate and initialize a new instance of data class @p cls, copying and
267 * parsing NVRAM data from @p io.
269 * The caller is responsible for releasing the returned parser instance
270 * reference via bhnd_nvram_data_release().
272 * @param cls If non-NULL, the data class to be allocated. If NULL,
273 * bhnd_nvram_data_probe_classes() will be used to determine the data format.
274 * @param[out] nv On success, a pointer to the newly allocated NVRAM data instance.
275 * @param io An I/O context mapping the NVRAM data to be copied and parsed.
278 * @retval non-zero if an error occurs during allocation or initialization, a
279 * regular unix error code will be returned.
282 bhnd_nvram_data_new(bhnd_nvram_data_class *cls, struct bhnd_nvram_data **nv,
283 struct bhnd_nvram_io *io)
285 struct bhnd_nvram_data *data;
288 /* If NULL, try to identify the appropriate class */
290 return (bhnd_nvram_data_probe_classes(nv, io, NULL, 0));
292 /* Allocate new instance */
293 BHND_NV_ASSERT(sizeof(struct bhnd_nvram_data) <= cls->size,
294 ("instance size %zu less than minimum %zu", cls->size,
295 sizeof(struct bhnd_nvram_data)));
297 data = bhnd_nv_calloc(1, cls->size);
299 refcount_init(&data->refs, 1);
301 /* Let the class handle initialization */
302 if ((error = cls->op_new(data, io))) {
312 * Retain and return a reference to the given data instance.
314 * @param nv The reference to be retained.
316 struct bhnd_nvram_data *
317 bhnd_nvram_data_retain(struct bhnd_nvram_data *nv)
319 refcount_acquire(&nv->refs);
324 * Release a reference to the given data instance.
326 * If this is the last reference, the data instance and its associated
327 * resources will be freed.
329 * @param nv The reference to be released.
332 bhnd_nvram_data_release(struct bhnd_nvram_data *nv)
334 if (!refcount_release(&nv->refs))
337 /* Free any internal resources */
338 nv->cls->op_free(nv);
340 /* Free the instance allocation */
345 * Return a pointer to @p nv's data class.
347 * @param nv The NVRAM data instance to be queried.
349 bhnd_nvram_data_class *
350 bhnd_nvram_data_get_class(struct bhnd_nvram_data *nv)
356 * Return the number of variables in @p nv.
358 * @param nv The NVRAM data to be queried.
361 bhnd_nvram_data_count(struct bhnd_nvram_data *nv)
363 return (nv->cls->op_count(nv));
367 * Return a borrowed reference to the serialization options for @p nv,
368 * suitable for use with bhnd_nvram_data_serialize(), or NULL if none.
370 * @param nv The NVRAM data to be queried.
373 bhnd_nvram_data_options(struct bhnd_nvram_data *nv)
375 return (nv->cls->op_options(nv));
379 * Return the capability flags (@see BHND_NVRAM_DATA_CAP_*) for @p nv.
381 * @param nv The NVRAM data to be queried.
384 bhnd_nvram_data_caps(struct bhnd_nvram_data *nv)
386 return (nv->cls->op_caps(nv));
390 * Iterate over @p nv, returning the names of subsequent variables.
392 * @param nv The NVRAM data to be iterated.
393 * @param[in,out] cookiep A pointer to a cookiep value previously returned
394 * by bhnd_nvram_data_next(), or a NULL value to
397 * @return Returns the next variable name, or NULL if there are no more
398 * variables defined in @p nv.
401 bhnd_nvram_data_next(struct bhnd_nvram_data *nv, void **cookiep)
404 #ifdef BHND_NV_INVARIANTS
405 void *prev = *cookiep;
409 if ((name = nv->cls->op_next(nv, cookiep)) == NULL)
412 /* Enforce precedence ordering invariant between bhnd_nvram_data_next()
413 * and bhnd_nvram_data_getvar_order() */
414 #ifdef BHND_NV_INVARIANTS
416 bhnd_nvram_data_getvar_order(nv, prev, *cookiep) > 0)
418 BHND_NV_PANIC("%s: returned out-of-order entry", __FUNCTION__);
426 * Search @p nv for a named variable, returning the variable's opaque reference
427 * if found, or NULL if unavailable.
429 * The BHND_NVRAM_DATA_CAP_INDEXED capability flag will be returned by
430 * bhnd_nvram_data_caps() if @p nv supports effecient name-based
433 * @param nv The NVRAM data to search.
434 * @param name The name to search for.
436 * @retval non-NULL If @p name is found, the opaque cookie value will be
438 * @retval NULL If @p name is not found.
441 bhnd_nvram_data_find(struct bhnd_nvram_data *nv, const char *name)
443 return (nv->cls->op_find(nv, name));
447 * A generic implementation of bhnd_nvram_data_find().
449 * This implementation will use bhnd_nvram_data_next() to perform a
450 * simple O(n) case-insensitve search for @p name.
453 bhnd_nvram_data_generic_find(struct bhnd_nvram_data *nv, const char *name)
459 while ((next = bhnd_nvram_data_next(nv, &cookiep))) {
460 if (strcmp(name, next) == 0)
469 * Compare the declaration order of two NVRAM variables.
471 * Variable declaration order is used to determine the current order of
472 * the variables in the source data, as well as to determine the precedence
473 * of variable declarations in data sources that define duplicate names.
475 * The comparison order will match the order of variables returned via
476 * bhnd_nvstore_path_data_next().
478 * @param nv The NVRAM data.
479 * @param cookiep1 An NVRAM variable cookie previously
480 * returned via bhnd_nvram_data_next() or
481 * bhnd_nvram_data_find().
482 * @param cookiep2 An NVRAM variable cookie previously
483 * returned via bhnd_nvram_data_next() or
484 * bhnd_nvram_data_find().
486 * @retval <= -1 If @p cookiep1 has an earlier declaration order than
488 * @retval 0 If @p cookiep1 and @p cookiep2 are identical.
489 * @retval >= 1 If @p cookiep has a later declaration order than
493 bhnd_nvram_data_getvar_order(struct bhnd_nvram_data *nv, void *cookiep1,
496 return (nv->cls->op_getvar_order(nv, cookiep1, cookiep2));
500 * Read a variable and decode as @p type.
502 * @param nv The NVRAM data.
503 * @param cookiep An NVRAM variable cookie previously returned
504 * via bhnd_nvram_data_next() or
505 * bhnd_nvram_data_find().
506 * @param[out] buf On success, the requested value will be written
507 * to this buffer. This argment may be NULL if
508 * the value is not desired.
509 * @param[in,out] len The capacity of @p buf. On success, will be set
510 * to the actual size of the requested value.
511 * @param type The data type to be written to @p buf.
514 * @retval ENOMEM If @p buf is non-NULL and a buffer of @p len is too
515 * small to hold the requested value.
516 * @retval EFTYPE If the variable data cannot be coerced to @p type.
517 * @retval ERANGE If value coercion would overflow @p type.
520 bhnd_nvram_data_getvar(struct bhnd_nvram_data *nv, void *cookiep, void *buf,
521 size_t *len, bhnd_nvram_type type)
523 return (nv->cls->op_getvar(nv, cookiep, buf, len, type));
527 * Common bhnd_nvram_data_getvar_ptr() wrapper used by
528 * bhnd_nvram_data_generic_rp_getvar() and
529 * bhnd_nvram_data_generic_rp_copy_val().
531 * If a variable definition for the requested variable is found via
532 * bhnd_nvram_find_vardefn(), the definition will be used to populate fmt.
535 bhnd_nvram_data_getvar_ptr_info(struct bhnd_nvram_data *nv, void *cookiep,
536 size_t *len, bhnd_nvram_type *type, const bhnd_nvram_val_fmt **fmt)
538 const struct bhnd_nvram_vardefn *vdefn;
542 BHND_NV_ASSERT(bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_READ_PTR,
543 ("instance does not advertise READ_PTR support"));
545 /* Fetch pointer to variable data */
546 vptr = bhnd_nvram_data_getvar_ptr(nv, cookiep, len, type);
550 /* Select a default value format implementation */
553 /* Fetch the reference variable name */
554 name = bhnd_nvram_data_getvar_name(nv, cookiep);
556 /* Trim path prefix, if any; the Broadcom NVRAM format assumes a global
557 * namespace for all variable definitions */
558 if (bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_DEVPATHS)
559 name = bhnd_nvram_trim_path_name(name);
561 /* Check the variable definition table for a matching entry; if
562 * it exists, use it to populate the value format. */
563 vdefn = bhnd_nvram_find_vardefn(name);
565 BHND_NV_ASSERT(vdefn->fmt != NULL,
566 ("NULL format for %s", name));
568 } else if (*type == BHND_NVRAM_TYPE_STRING) {
569 /* Default to Broadcom-specific string interpretation */
570 *fmt = &bhnd_nvram_val_bcm_string_fmt;
572 /* Fall back on native formatting */
573 *fmt = bhnd_nvram_val_default_fmt(*type);
580 * A generic implementation of bhnd_nvram_data_getvar().
582 * This implementation will call bhnd_nvram_data_getvar_ptr() to fetch
583 * a pointer to the variable data and perform data coercion on behalf
586 * If a variable definition for the requested variable is available via
587 * bhnd_nvram_find_vardefn(), the definition will be used to provide a
588 * formatting instance to bhnd_nvram_val_init().
591 bhnd_nvram_data_generic_rp_getvar(struct bhnd_nvram_data *nv, void *cookiep,
592 void *outp, size_t *olen, bhnd_nvram_type otype)
595 const bhnd_nvram_val_fmt *fmt;
597 bhnd_nvram_type vtype;
601 BHND_NV_ASSERT(bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_READ_PTR,
602 ("instance does not advertise READ_PTR support"));
604 /* Fetch variable data and value format*/
605 vptr = bhnd_nvram_data_getvar_ptr_info(nv, cookiep, &vlen, &vtype,
610 /* Attempt value coercion */
611 error = bhnd_nvram_val_init(&val, fmt, vptr, vlen, vtype,
612 BHND_NVRAM_VAL_BORROW_DATA);
616 error = bhnd_nvram_val_encode(&val, outp, olen, otype);
619 bhnd_nvram_val_release(&val);
624 * Return a caller-owned copy of an NVRAM entry's variable data.
626 * The caller is responsible for deallocating the returned value via
627 * bhnd_nvram_val_release().
629 * @param nv The NVRAM data.
630 * @param cookiep An NVRAM variable cookie previously returned
631 * via bhnd_nvram_data_next() or bhnd_nvram_data_find().
632 * @param[out] value On success, the caller-owned value instance.
635 * @retval ENOMEM If allocation fails.
636 * @retval non-zero If initialization of the value otherwise fails, a
637 * regular unix error code will be returned.
640 bhnd_nvram_data_copy_val(struct bhnd_nvram_data *nv, void *cookiep,
641 bhnd_nvram_val **value)
643 return (nv->cls->op_copy_val(nv, cookiep, value));
647 * A generic implementation of bhnd_nvram_data_copy_val().
649 * This implementation will call bhnd_nvram_data_getvar_ptr() to fetch
650 * a pointer to the variable data and perform data coercion on behalf
653 * If a variable definition for the requested variable is available via
654 * bhnd_nvram_find_vardefn(), the definition will be used to provide a
655 * formatting instance to bhnd_nvram_val_init().
658 bhnd_nvram_data_generic_rp_copy_val(struct bhnd_nvram_data *nv,
659 void *cookiep, bhnd_nvram_val **value)
661 const bhnd_nvram_val_fmt *fmt;
663 bhnd_nvram_type vtype;
666 BHND_NV_ASSERT(bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_READ_PTR,
667 ("instance does not advertise READ_PTR support"));
669 /* Fetch variable data and value format*/
670 vptr = bhnd_nvram_data_getvar_ptr_info(nv, cookiep, &vlen, &vtype,
675 /* Allocate and return the new value instance */
676 return (bhnd_nvram_val_new(value, fmt, vptr, vlen, vtype,
677 BHND_NVRAM_VAL_DYNAMIC));
681 * If available and supported by the NVRAM data instance, return a reference
682 * to the internal buffer containing an entry's variable data,
684 * Note that string values may not be NUL terminated.
686 * @param nv The NVRAM data.
687 * @param cookiep An NVRAM variable cookie previously returned
688 * via bhnd_nvram_data_next() or
689 * bhnd_nvram_data_find().
690 * @param[out] len On success, will be set to the actual size of
691 * the requested value.
692 * @param[out] type The data type of the entry data.
694 * @retval non-NULL success
695 * @retval NULL if direct data access is unsupported by @p nv, or
696 * unavailable for @p cookiep.
699 bhnd_nvram_data_getvar_ptr(struct bhnd_nvram_data *nv, void *cookiep,
700 size_t *len, bhnd_nvram_type *type)
702 return (nv->cls->op_getvar_ptr(nv, cookiep, len, type));
707 * Return the variable name associated with a given @p cookiep.
708 * @param nv The NVRAM data to be iterated.
709 * @param[in,out] cookiep A pointer to a cookiep value previously returned
710 * via bhnd_nvram_data_next() or
711 * bhnd_nvram_data_find().
713 * @return Returns the variable's name.
716 bhnd_nvram_data_getvar_name(struct bhnd_nvram_data *nv, void *cookiep)
718 return (nv->cls->op_getvar_name(nv, cookiep));
722 * Filter a request to set variable @p name with @p value.
724 * On success, the caller owns a reference to @p result, and must release
725 * any held resources via bhnd_nvram_val_release().
727 * @param nv The NVRAM data instance.
728 * @param name The name of the variable to be set.
729 * @param value The proposed value to be set.
730 * @param[out] result On success, a caller-owned reference to the filtered
734 * @retval ENOENT if @p name is unrecognized by @p nv.
735 * @retval EINVAL if @p name is read-only.
736 * @retval EINVAL if @p value cannot be converted to the required value
740 bhnd_nvram_data_filter_setvar(struct bhnd_nvram_data *nv, const char *name,
741 bhnd_nvram_val *value, bhnd_nvram_val **result)
743 return (nv->cls->op_filter_setvar(nv, name, value, result));
747 * Filter a request to delete variable @p name.
749 * @param nv The NVRAM data instance.
750 * @param name The name of the variable to be deleted.
753 * @retval ENOENT if @p name is unrecognized by @p nv.
754 * @retval EINVAL if @p name is read-only.
757 bhnd_nvram_data_filter_unsetvar(struct bhnd_nvram_data *nv, const char *name)
759 return (nv->cls->op_filter_unsetvar(nv, name));