xref: /freebsd/sys/dev/bhnd/nvram/bhnd_nvram_data.c (revision 0957b409)
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 
30 #include <sys/cdefs.h>
31 __FBSDID("$FreeBSD$");
32 
33 
34 #ifdef _KERNEL
35 
36 #include <sys/param.h>
37 #include <sys/systm.h>
38 
39 #include <machine/_inttypes.h>
40 
41 #else /* !_KERNEL */
42 
43 #include <errno.h>
44 #include <stdint.h>
45 #include <stdlib.h>
46 #include <string.h>
47 
48 #endif /* _KERNEL */
49 
50 #include "bhnd_nvram_private.h"
51 #include "bhnd_nvram_io.h"
52 
53 #include "bhnd_nvram_datavar.h"
54 #include "bhnd_nvram_data.h"
55 
56 /**
57  * Return a human-readable description for the given NVRAM data class.
58  *
59  * @param cls The NVRAM class.
60  */
61 const char *
62 bhnd_nvram_data_class_desc(bhnd_nvram_data_class *cls)
63 {
64 	return (cls->desc);
65 }
66 
67 /**
68  * Return the class-level capability flags (@see BHND_NVRAM_DATA_CAP_*) for
69  * of @p cls.
70  *
71  * @param cls The NVRAM class.
72  */
73 uint32_t
74 bhnd_nvram_data_class_caps(bhnd_nvram_data_class *cls)
75 {
76 	return (cls->caps);
77 }
78 
79 /**
80  * Serialize all NVRAM properties in @p plist using @p cls's NVRAM data
81  * format, writing the result to @p outp.
82  *
83  * @param		cls	The NVRAM data class to be used to perform
84  *				serialization.
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.
93  *
94  * @retval 0		success
95  *
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
99  *			@p plist.
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.
106  */
107 int
108 bhnd_nvram_data_serialize(bhnd_nvram_data_class *cls,
109     bhnd_nvram_plist *props, bhnd_nvram_plist *options, void *outp,
110     size_t *olen)
111 {
112 	return (cls->op_serialize(cls, props, options, outp, olen));
113 }
114 
115 /**
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.
118  *
119  * @param cls The NVRAM class.
120  * @param io An I/O context mapping the NVRAM data.
121  *
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
125  * NVRAM parsing.
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.
129  */
130 int
131 bhnd_nvram_data_probe(bhnd_nvram_data_class *cls, struct bhnd_nvram_io *io)
132 {
133 	return (cls->op_probe(io));
134 }
135 
136 /**
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.
139  *
140  * The caller is responsible for deallocating the returned instance via
141  * bhnd_nvram_data_release().
142  *
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.
148  *
149  * @retval 0 success
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
153  * will be returned.
154  */
155 int
156 bhnd_nvram_data_probe_classes(struct bhnd_nvram_data **data,
157     struct bhnd_nvram_io *io, bhnd_nvram_data_class *classes[],
158     size_t num_classes)
159 {
160 	bhnd_nvram_data_class	*cls;
161 	int			 error, prio, result;
162 
163 	cls = NULL;
164 	prio = 0;
165 	*data = NULL;
166 
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);
171 	}
172 
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;
176 
177 		next_cls = classes[i];
178 
179 		/* Try to probe */
180 		result = bhnd_nvram_data_probe(next_cls, io);
181 
182 		/* The parser did not match if an error was returned */
183 		if (result > 0)
184 			continue;
185 
186 		/* Lower priority than previous match; keep
187 		 * searching */
188 		if (cls != NULL && result <= prio)
189 			continue;
190 
191 		/* Drop any previously parsed data */
192 		if (*data != NULL) {
193 			bhnd_nvram_data_release(*data);
194 			*data = NULL;
195 		}
196 
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);
202 			if (error)
203 				continue;
204 		}
205 
206 		/* Record best new match */
207 		prio = result;
208 		cls = next_cls;
209 
210 
211 		/* Terminate search immediately on
212 		 * BHND_NVRAM_DATA_PROBE_SPECIFIC */
213 		if (result == BHND_NVRAM_DATA_PROBE_SPECIFIC)
214 			break;
215 	}
216 
217 	/* If no match, return error */
218 	if (cls == NULL)
219 		return (ENXIO);
220 
221 	/* If the NVRAM data was not parsed above, do so now */
222 	if (*data == NULL) {
223 		if ((error = bhnd_nvram_data_new(cls, data, io)))
224 			return (error);
225 	}
226 
227 	return (0);
228 }
229 
230 /**
231  * Read a variable directly from @p io and decode as @p type.
232  *
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.
235  *
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.
247  *
248  * @retval 0		success
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.
256  */
257 int
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)
261 {
262 	return (cls->op_getvar_direct(io, name, buf, len, type));
263 }
264 
265 /**
266  * Allocate and initialize a new instance of data class @p cls, copying and
267  * parsing NVRAM data from @p io.
268  *
269  * The caller is responsible for releasing the returned parser instance
270  * reference via bhnd_nvram_data_release().
271  *
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.
276  *
277  * @retval 0 success
278  * @retval non-zero if an error occurs during allocation or initialization, a
279  * regular unix error code will be returned.
280  */
281 int
282 bhnd_nvram_data_new(bhnd_nvram_data_class *cls, struct bhnd_nvram_data **nv,
283     struct bhnd_nvram_io *io)
284 {
285 	struct bhnd_nvram_data	*data;
286 	int			 error;
287 
288 	/* If NULL, try to identify the appropriate class */
289 	if (cls == NULL)
290 		return (bhnd_nvram_data_probe_classes(nv, io, NULL, 0));
291 
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)));
296 
297 	data = bhnd_nv_calloc(1, cls->size);
298 	data->cls = cls;
299 	refcount_init(&data->refs, 1);
300 
301 	/* Let the class handle initialization */
302 	if ((error = cls->op_new(data, io))) {
303 		bhnd_nv_free(data);
304 		return (error);
305 	}
306 
307 	*nv = data;
308 	return (0);
309 }
310 
311 /**
312  * Retain and return a reference to the given data instance.
313  *
314  * @param nv The reference to be retained.
315  */
316 struct bhnd_nvram_data *
317 bhnd_nvram_data_retain(struct bhnd_nvram_data *nv)
318 {
319 	refcount_acquire(&nv->refs);
320 	return (nv);
321 }
322 
323 /**
324  * Release a reference to the given data instance.
325  *
326  * If this is the last reference, the data instance and its associated
327  * resources will be freed.
328  *
329  * @param nv The reference to be released.
330  */
331 void
332 bhnd_nvram_data_release(struct bhnd_nvram_data *nv)
333 {
334 	if (!refcount_release(&nv->refs))
335 		return;
336 
337 	/* Free any internal resources */
338 	nv->cls->op_free(nv);
339 
340 	/* Free the instance allocation */
341 	bhnd_nv_free(nv);
342 }
343 
344 /**
345  * Return a pointer to @p nv's data class.
346  *
347  * @param nv The NVRAM data instance to be queried.
348  */
349 bhnd_nvram_data_class *
350 bhnd_nvram_data_get_class(struct bhnd_nvram_data *nv)
351 {
352 	return (nv->cls);
353 }
354 
355 /**
356  * Return the number of variables in @p nv.
357  *
358  * @param nv The NVRAM data to be queried.
359  */
360 size_t
361 bhnd_nvram_data_count(struct bhnd_nvram_data *nv)
362 {
363 	return (nv->cls->op_count(nv));
364 }
365 
366 /**
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.
369  *
370  * @param nv The NVRAM data to be queried.
371  */
372 bhnd_nvram_plist *
373 bhnd_nvram_data_options(struct bhnd_nvram_data *nv)
374 {
375 	return (nv->cls->op_options(nv));
376 }
377 
378 /**
379  * Return the capability flags (@see BHND_NVRAM_DATA_CAP_*) for @p nv.
380  *
381  * @param	nv	The NVRAM data to be queried.
382  */
383 uint32_t
384 bhnd_nvram_data_caps(struct bhnd_nvram_data *nv)
385 {
386 	return (nv->cls->op_caps(nv));
387 }
388 
389 /**
390  * Iterate over @p nv, returning the names of subsequent variables.
391  *
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
395  *				begin iteration.
396  *
397  * @return Returns the next variable name, or NULL if there are no more
398  * variables defined in @p nv.
399  */
400 const char *
401 bhnd_nvram_data_next(struct bhnd_nvram_data *nv, void **cookiep)
402 {
403 	const char	*name;
404 #ifdef BHND_NV_INVARIANTS
405 	void		*prev = *cookiep;
406 #endif
407 
408 	/* Fetch next */
409 	if ((name = nv->cls->op_next(nv, cookiep)) == NULL)
410 		return (NULL);
411 
412 	/* Enforce precedence ordering invariant between bhnd_nvram_data_next()
413 	 * and bhnd_nvram_data_getvar_order() */
414 #ifdef BHND_NV_INVARIANTS
415 	if (prev != NULL &&
416 	    bhnd_nvram_data_getvar_order(nv, prev, *cookiep) > 0)
417 	{
418 		BHND_NV_PANIC("%s: returned out-of-order entry", __FUNCTION__);
419 	}
420 #endif
421 
422 	return (name);
423 }
424 
425 /**
426  * Search @p nv for a named variable, returning the variable's opaque reference
427  * if found, or NULL if unavailable.
428  *
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
431  * lookups.
432  *
433  * @param	nv	The NVRAM data to search.
434  * @param	name	The name to search for.
435  *
436  * @retval non-NULL	If @p name is found, the opaque cookie value will be
437  *			returned.
438  * @retval NULL		If @p name is not found.
439  */
440 void *
441 bhnd_nvram_data_find(struct bhnd_nvram_data *nv, const char *name)
442 {
443 	return (nv->cls->op_find(nv, name));
444 }
445 
446 /**
447  * A generic implementation of bhnd_nvram_data_find().
448  *
449  * This implementation will use bhnd_nvram_data_next() to perform a
450  * simple O(n) case-insensitve search for @p name.
451  */
452 void *
453 bhnd_nvram_data_generic_find(struct bhnd_nvram_data *nv, const char *name)
454 {
455 	const char	*next;
456 	void		*cookiep;
457 
458 	cookiep = NULL;
459 	while ((next = bhnd_nvram_data_next(nv, &cookiep))) {
460 		if (strcmp(name, next) == 0)
461 			return (cookiep);
462 	}
463 
464 	/* Not found */
465 	return (NULL);
466 }
467 
468 /**
469  * Compare the declaration order of two NVRAM variables.
470  *
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.
474  *
475  * The comparison order will match the order of variables returned via
476  * bhnd_nvstore_path_data_next().
477  *
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().
485  *
486  * @retval <= -1	If @p cookiep1 has an earlier declaration order than
487  *			@p cookiep2.
488  * @retval 0		If @p cookiep1 and @p cookiep2 are identical.
489  * @retval >= 1		If @p cookiep has a later declaration order than
490  *			@p cookiep2.
491  */
492 int
493 bhnd_nvram_data_getvar_order(struct bhnd_nvram_data *nv, void *cookiep1,
494     void *cookiep2)
495 {
496 	return (nv->cls->op_getvar_order(nv, cookiep1, cookiep2));
497 }
498 
499 /**
500  * Read a variable and decode as @p type.
501  *
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.
512  *
513  * @retval 0		success
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.
518  */
519 int
520 bhnd_nvram_data_getvar(struct bhnd_nvram_data *nv, void *cookiep, void *buf,
521     size_t *len, bhnd_nvram_type type)
522 {
523 	return (nv->cls->op_getvar(nv, cookiep, buf, len, type));
524 }
525 
526 /*
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().
530  *
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.
533  */
534 static const void *
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)
537 {
538 	const struct bhnd_nvram_vardefn	*vdefn;
539 	const char			*name;
540 	const void			*vptr;
541 
542 	BHND_NV_ASSERT(bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_READ_PTR,
543 	    ("instance does not advertise READ_PTR support"));
544 
545 	/* Fetch pointer to variable data */
546 	vptr = bhnd_nvram_data_getvar_ptr(nv, cookiep, len, type);
547 	if (vptr == NULL)
548 		return (NULL);
549 
550 	/* Select a default value format implementation */
551 
552 
553 	/* Fetch the reference variable name */
554 	name = bhnd_nvram_data_getvar_name(nv, cookiep);
555 
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);
560 
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);
564 	if (vdefn != NULL) {
565 		BHND_NV_ASSERT(vdefn->fmt != NULL,
566 		    ("NULL format for %s", name));
567 		*fmt = vdefn->fmt;
568 	} else if (*type == BHND_NVRAM_TYPE_STRING) {
569 		/* Default to Broadcom-specific string interpretation */
570 		*fmt = &bhnd_nvram_val_bcm_string_fmt;
571 	} else {
572 		/* Fall back on native formatting */
573 		*fmt = bhnd_nvram_val_default_fmt(*type);
574 	}
575 
576 	return (vptr);
577 }
578 
579 /**
580  * A generic implementation of bhnd_nvram_data_getvar().
581  *
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
584  * of the caller.
585  *
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().
589  */
590 int
591 bhnd_nvram_data_generic_rp_getvar(struct bhnd_nvram_data *nv, void *cookiep,
592     void *outp, size_t *olen, bhnd_nvram_type otype)
593 {
594 	bhnd_nvram_val			 val;
595 	const bhnd_nvram_val_fmt	*fmt;
596 	const void			*vptr;
597 	bhnd_nvram_type			 vtype;
598 	size_t				 vlen;
599 	int				 error;
600 
601 	BHND_NV_ASSERT(bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_READ_PTR,
602 	    ("instance does not advertise READ_PTR support"));
603 
604 	/* Fetch variable data and value format*/
605 	vptr = bhnd_nvram_data_getvar_ptr_info(nv, cookiep, &vlen, &vtype,
606 	    &fmt);
607 	if (vptr == NULL)
608 		return (EINVAL);
609 
610 	/* Attempt value coercion */
611 	error = bhnd_nvram_val_init(&val, fmt, vptr, vlen, vtype,
612 	    BHND_NVRAM_VAL_BORROW_DATA);
613 	if (error)
614 		return (error);
615 
616 	error = bhnd_nvram_val_encode(&val, outp, olen, otype);
617 
618 	/* Clean up */
619 	bhnd_nvram_val_release(&val);
620 	return (error);
621 }
622 
623 /**
624  * Return a caller-owned copy of an NVRAM entry's variable data.
625  *
626  * The caller is responsible for deallocating the returned value via
627  * bhnd_nvram_val_release().
628  *
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.
633  *
634  * @retval 0		success
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.
638  */
639 int
640 bhnd_nvram_data_copy_val(struct bhnd_nvram_data *nv, void *cookiep,
641     bhnd_nvram_val **value)
642 {
643 	return (nv->cls->op_copy_val(nv, cookiep, value));
644 }
645 
646 /**
647  * A generic implementation of bhnd_nvram_data_copy_val().
648  *
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
651  * of the caller.
652  *
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().
656  */
657 int
658 bhnd_nvram_data_generic_rp_copy_val(struct bhnd_nvram_data *nv,
659     void *cookiep, bhnd_nvram_val **value)
660 {
661 	const bhnd_nvram_val_fmt	*fmt;
662 	const void			*vptr;
663 	bhnd_nvram_type			 vtype;
664 	size_t				 vlen;
665 
666 	BHND_NV_ASSERT(bhnd_nvram_data_caps(nv) & BHND_NVRAM_DATA_CAP_READ_PTR,
667 	    ("instance does not advertise READ_PTR support"));
668 
669 	/* Fetch variable data and value format*/
670 	vptr = bhnd_nvram_data_getvar_ptr_info(nv, cookiep, &vlen, &vtype,
671 	    &fmt);
672 	if (vptr == NULL)
673 		return (EINVAL);
674 
675 	/* Allocate and return the new value instance */
676 	return (bhnd_nvram_val_new(value, fmt, vptr, vlen, vtype,
677 	    BHND_NVRAM_VAL_DYNAMIC));
678 }
679 
680 /**
681  * If available and supported by the NVRAM data instance, return a reference
682  * to the internal buffer containing an entry's variable data,
683  *
684  * Note that string values may not be NUL terminated.
685  *
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.
693  *
694  * @retval non-NULL	success
695  * @retval NULL		if direct data access is unsupported by @p nv, or
696  *			unavailable for @p cookiep.
697  */
698 const void *
699 bhnd_nvram_data_getvar_ptr(struct bhnd_nvram_data *nv, void *cookiep,
700     size_t *len, bhnd_nvram_type *type)
701 {
702 	return (nv->cls->op_getvar_ptr(nv, cookiep, len, type));
703 }
704 
705 
706 /**
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().
712  *
713  * @return Returns the variable's name.
714  */
715 const char *
716 bhnd_nvram_data_getvar_name(struct bhnd_nvram_data *nv, void *cookiep)
717 {
718 	return (nv->cls->op_getvar_name(nv, cookiep));
719 }
720 
721 /**
722  * Filter a request to set variable @p name with @p value.
723  *
724  * On success, the caller owns a reference to @p result, and must release
725  * any held resources via bhnd_nvram_val_release().
726  *
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
731  *			value to be set.
732  *
733  * @retval	0	success
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
737  *			type.
738  */
739 int
740 bhnd_nvram_data_filter_setvar(struct bhnd_nvram_data *nv, const char *name,
741     bhnd_nvram_val *value, bhnd_nvram_val **result)
742 {
743 	return (nv->cls->op_filter_setvar(nv, name, value, result));
744 }
745 
746 /**
747  * Filter a request to delete variable @p name.
748  *
749  * @param	nv	The NVRAM data instance.
750  * @param	name	The name of the variable to be deleted.
751  *
752  * @retval	0	success
753  * @retval	ENOENT	if @p name is unrecognized by @p nv.
754  * @retval	EINVAL	if @p name is read-only.
755  */
756 int
757 bhnd_nvram_data_filter_unsetvar(struct bhnd_nvram_data *nv, const char *name)
758 {
759 	return (nv->cls->op_filter_unsetvar(nv, name));
760 }
761