VirtualBox

source: vbox/trunk/src/VBox/VMM/VMMR3/CFGM.cpp@ 62596

Last change on this file since 62596 was 62478, checked in by vboxsync, 8 years ago

(C) 2016
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 96.7 KB
Line 
1/* $Id: CFGM.cpp 62478 2016-07-22 18:29:06Z vboxsync $ */
2/** @file
3 * CFGM - Configuration Manager.
4 */
5
6/*
7 * Copyright (C) 2006-2016 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18/** @page pg_cfgm CFGM - The Configuration Manager
19 *
20 * The configuration manager is a directory containing the VM configuration at
21 * run time. It works in a manner similar to the windows registry - it's like a
22 * file system hierarchy, but the files (values) live in a separate name space
23 * and can include the path separators.
24 *
25 * The configuration is normally created via a callback passed to VMR3Create()
26 * via the pfnCFGMConstructor parameter. To make testcase writing a bit simpler,
27 * we allow the callback to be NULL, in which case a simple default
28 * configuration will be created by CFGMR3ConstructDefaultTree(). The
29 * Console::configConstructor() method in Main/ConsoleImpl2.cpp creates the
30 * configuration from the XML.
31 *
32 * Devices, drivers, services and other PDM stuff are given their own subtree
33 * where they are protected from accessing information of any parents. This is
34 * is implemented via the CFGMR3SetRestrictedRoot() API.
35 *
36 * Data validation beyond the basic primitives is left to the caller. The caller
37 * is in a better position to know the proper validation rules of the individual
38 * properties.
39 *
40 * @see grp_cfgm
41 *
42 *
43 * @section sec_cfgm_primitives Data Primitives
44 *
45 * CFGM supports the following data primitives:
46 * - Integers. Representation is unsigned 64-bit. Boolean, unsigned and
47 * small integers, and pointers are all represented using this primitive.
48 * - Zero terminated character strings. These are of course UTF-8.
49 * - Variable length byte strings. This can be used to get/put binary
50 * objects like for instance RTMAC.
51 *
52 */
53
54
55/*********************************************************************************************************************************
56* Header Files *
57*********************************************************************************************************************************/
58#define LOG_GROUP LOG_GROUP_CFGM
59#include <VBox/vmm/cfgm.h>
60#include <VBox/vmm/dbgf.h>
61#include <VBox/vmm/mm.h>
62#include "CFGMInternal.h"
63#include <VBox/vmm/vm.h>
64#include <VBox/vmm/uvm.h>
65#include <VBox/err.h>
66
67#include <VBox/log.h>
68#include <iprt/assert.h>
69#include <iprt/mem.h>
70#include <iprt/param.h>
71#include <iprt/string.h>
72#include <iprt/uuid.h>
73
74
75/*********************************************************************************************************************************
76* Internal Functions *
77*********************************************************************************************************************************/
78static void cfgmR3DumpPath(PCFGMNODE pNode, PCDBGFINFOHLP pHlp);
79static void cfgmR3Dump(PCFGMNODE pRoot, unsigned iLevel, PCDBGFINFOHLP pHlp);
80static DECLCALLBACK(void) cfgmR3Info(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs);
81static int cfgmR3ResolveNode(PCFGMNODE pNode, const char *pszPath, PCFGMNODE *ppChild);
82static int cfgmR3ResolveLeaf(PCFGMNODE pNode, const char *pszName, PCFGMLEAF *ppLeaf);
83static int cfgmR3InsertLeaf(PCFGMNODE pNode, const char *pszName, PCFGMLEAF *ppLeaf);
84static void cfgmR3RemoveLeaf(PCFGMNODE pNode, PCFGMLEAF pLeaf);
85static void cfgmR3FreeValue(PVM pVM, PCFGMLEAF pLeaf);
86
87
88/** @todo replace pVM for pUVM !*/
89
90/**
91 * Allocator wrapper.
92 *
93 * @returns Pointer to the allocated memory, NULL on failure.
94 * @param pVM The cross context VM structure, if the tree
95 * is associated with one.
96 * @param enmTag The allocation tag.
97 * @param cb The size of the allocation.
98 */
99static void *cfgmR3MemAlloc(PVM pVM, MMTAG enmTag, size_t cb)
100{
101 if (pVM)
102 return MMR3HeapAlloc(pVM, enmTag, cb);
103 return RTMemAlloc(cb);
104}
105
106
107/**
108 * Free wrapper.
109 *
110 * @returns Pointer to the allocated memory, NULL on failure.
111 * @param pVM The cross context VM structure, if the tree
112 * is associated with one.
113 * @param pv The memory block to free.
114 */
115static void cfgmR3MemFree(PVM pVM, void *pv)
116{
117 if (pVM)
118 MMR3HeapFree(pv);
119 else
120 RTMemFree(pv);
121}
122
123
124/**
125 * String allocator wrapper.
126 *
127 * @returns Pointer to the allocated memory, NULL on failure.
128 * @param pVM The cross context VM structure, if the tree
129 * is associated with one.
130 * @param enmTag The allocation tag.
131 * @param cbString The size of the allocation, terminator included.
132 */
133static char *cfgmR3StrAlloc(PVM pVM, MMTAG enmTag, size_t cbString)
134{
135 if (pVM)
136 return (char *)MMR3HeapAlloc(pVM, enmTag, cbString);
137 return (char *)RTStrAlloc(cbString);
138}
139
140
141/**
142 * String free wrapper.
143 *
144 * @returns Pointer to the allocated memory, NULL on failure.
145 * @param pVM The cross context VM structure, if the tree
146 * is associated with one.
147 * @param pszString The memory block to free.
148 */
149static void cfgmR3StrFree(PVM pVM, char *pszString)
150{
151 if (pVM)
152 MMR3HeapFree(pszString);
153 else
154 RTStrFree(pszString);
155}
156
157
158/**
159 * Frees one node, leaving any children or leaves to the caller.
160 *
161 * @param pNode The node structure to free.
162 */
163static void cfgmR3FreeNodeOnly(PCFGMNODE pNode)
164{
165 pNode->pFirstLeaf = NULL;
166 pNode->pFirstChild = NULL;
167 pNode->pNext = NULL;
168 pNode->pPrev = NULL;
169 if (!pNode->pVM)
170 RTMemFree(pNode);
171 else
172 {
173 pNode->pVM = NULL;
174 MMR3HeapFree(pNode);
175 }
176}
177
178
179
180
181/**
182 * Constructs the configuration for the VM.
183 *
184 * This should only be called used once.
185 *
186 * @returns VBox status code.
187 * @param pVM The cross context VM structure.
188 * @param pfnCFGMConstructor Pointer to callback function for constructing
189 * the VM configuration tree. This is called on
190 * the EMT.
191 * @param pvUser The user argument passed to pfnCFGMConstructor.
192 * @thread EMT.
193 * @internal
194 */
195VMMR3DECL(int) CFGMR3Init(PVM pVM, PFNCFGMCONSTRUCTOR pfnCFGMConstructor, void *pvUser)
196{
197 LogFlow(("CFGMR3Init: pfnCFGMConstructor=%p pvUser=%p\n", pfnCFGMConstructor, pvUser));
198
199 /*
200 * Init data members.
201 */
202 pVM->cfgm.s.pRoot = NULL;
203
204 /*
205 * Register DBGF into item.
206 */
207 int rc = DBGFR3InfoRegisterInternal(pVM, "cfgm", "Dumps a part of the CFGM tree. The argument indicates where to start.",
208 cfgmR3Info);
209 AssertRCReturn(rc,rc);
210
211 /*
212 * Root Node.
213 */
214 PCFGMNODE pRoot = (PCFGMNODE)MMR3HeapAllocZ(pVM, MM_TAG_CFGM, sizeof(*pRoot));
215 if (!pRoot)
216 return VERR_NO_MEMORY;
217 pRoot->pVM = pVM;
218 pRoot->cchName = 0;
219 pVM->cfgm.s.pRoot = pRoot;
220
221 /*
222 * Call the constructor if specified, if not use the default one.
223 */
224 if (pfnCFGMConstructor)
225 rc = pfnCFGMConstructor(pVM->pUVM, pVM, pvUser);
226 else
227 rc = CFGMR3ConstructDefaultTree(pVM);
228 if (RT_SUCCESS(rc))
229 {
230 Log(("CFGMR3Init: Successfully constructed the configuration\n"));
231 CFGMR3Dump(CFGMR3GetRoot(pVM));
232 }
233 else
234 AssertMsgFailed(("Constructor failed with rc=%Rrc pfnCFGMConstructor=%p\n", rc, pfnCFGMConstructor));
235
236 return rc;
237}
238
239
240/**
241 * Terminates the configuration manager.
242 *
243 * @returns VBox status code.
244 * @param pVM The cross context VM structure.
245 * @internal
246 */
247VMMR3DECL(int) CFGMR3Term(PVM pVM)
248{
249 CFGMR3RemoveNode(pVM->cfgm.s.pRoot);
250 pVM->cfgm.s.pRoot = NULL;
251 return 0;
252}
253
254
255/**
256 * Gets the root node for the VM.
257 *
258 * @returns Pointer to root node.
259 * @param pVM The cross context VM structure.
260 */
261VMMR3DECL(PCFGMNODE) CFGMR3GetRoot(PVM pVM)
262{
263 return pVM->cfgm.s.pRoot;
264}
265
266
267/**
268 * Gets the root node for the VM.
269 *
270 * @returns Pointer to root node.
271 * @param pUVM The user mode VM structure.
272 */
273VMMR3DECL(PCFGMNODE) CFGMR3GetRootU(PUVM pUVM)
274{
275 UVM_ASSERT_VALID_EXT_RETURN(pUVM, NULL);
276 PVM pVM = pUVM->pVM;
277 AssertReturn(pVM, NULL);
278 return pVM->cfgm.s.pRoot;
279}
280
281
282/**
283 * Gets the parent of a CFGM node.
284 *
285 * @returns Pointer to the parent node.
286 * @returns NULL if pNode is Root or pNode is the start of a
287 * restricted subtree (use CFGMr3GetParentEx() for that).
288 *
289 * @param pNode The node which parent we query.
290 */
291VMMR3DECL(PCFGMNODE) CFGMR3GetParent(PCFGMNODE pNode)
292{
293 if (pNode && !pNode->fRestrictedRoot)
294 return pNode->pParent;
295 return NULL;
296}
297
298
299/**
300 * Gets the parent of a CFGM node.
301 *
302 * @returns Pointer to the parent node.
303 * @returns NULL if pNode is Root or pVM is not correct.
304 *
305 * @param pVM The cross context VM structure. Used as token that
306 * the caller is trusted.
307 * @param pNode The node which parent we query.
308 */
309VMMR3DECL(PCFGMNODE) CFGMR3GetParentEx(PVM pVM, PCFGMNODE pNode)
310{
311 if (pNode && pNode->pVM == pVM)
312 return pNode->pParent;
313 return NULL;
314}
315
316
317/**
318 * Query a child node.
319 *
320 * @returns Pointer to the specified node.
321 * @returns NULL if node was not found or pNode is NULL.
322 * @param pNode Node pszPath is relative to.
323 * @param pszPath Path to the child node or pNode.
324 * It's good style to end this with '/'.
325 */
326VMMR3DECL(PCFGMNODE) CFGMR3GetChild(PCFGMNODE pNode, const char *pszPath)
327{
328 PCFGMNODE pChild;
329 int rc = cfgmR3ResolveNode(pNode, pszPath, &pChild);
330 if (RT_SUCCESS(rc))
331 return pChild;
332 return NULL;
333}
334
335
336/**
337 * Query a child node by a format string.
338 *
339 * @returns Pointer to the specified node.
340 * @returns NULL if node was not found or pNode is NULL.
341 * @param pNode Node pszPath is relative to.
342 * @param pszPathFormat Path to the child node or pNode.
343 * It's good style to end this with '/'.
344 * @param ... Arguments to pszPathFormat.
345 */
346VMMR3DECL(PCFGMNODE) CFGMR3GetChildF(PCFGMNODE pNode, const char *pszPathFormat, ...)
347{
348 va_list Args;
349 va_start(Args, pszPathFormat);
350 PCFGMNODE pRet = CFGMR3GetChildFV(pNode, pszPathFormat, Args);
351 va_end(Args);
352 return pRet;
353}
354
355
356/**
357 * Query a child node by a format string.
358 *
359 * @returns Pointer to the specified node.
360 * @returns NULL if node was not found or pNode is NULL.
361 * @param pNode Node pszPath is relative to.
362 * @param pszPathFormat Path to the child node or pNode.
363 * It's good style to end this with '/'.
364 * @param Args Arguments to pszPathFormat.
365 */
366VMMR3DECL(PCFGMNODE) CFGMR3GetChildFV(PCFGMNODE pNode, const char *pszPathFormat, va_list Args)
367{
368 char *pszPath;
369 RTStrAPrintfV(&pszPath, pszPathFormat, Args);
370 if (pszPath)
371 {
372 PCFGMNODE pChild;
373 int rc = cfgmR3ResolveNode(pNode, pszPath, &pChild);
374 RTStrFree(pszPath);
375 if (RT_SUCCESS(rc))
376 return pChild;
377 }
378 return NULL;
379}
380
381
382/**
383 * Gets the first child node.
384 * Use this to start an enumeration of child nodes.
385 *
386 * @returns Pointer to the first child.
387 * @returns NULL if no children.
388 * @param pNode Node to enumerate children for.
389 */
390VMMR3DECL(PCFGMNODE) CFGMR3GetFirstChild(PCFGMNODE pNode)
391{
392 return pNode ? pNode->pFirstChild : NULL;
393}
394
395
396/**
397 * Gets the next sibling node.
398 * Use this to continue an enumeration.
399 *
400 * @returns Pointer to the first child.
401 * @returns NULL if no children.
402 * @param pCur Node to returned by a call to CFGMR3GetFirstChild()
403 * or successive calls to this function.
404 */
405VMMR3DECL(PCFGMNODE) CFGMR3GetNextChild(PCFGMNODE pCur)
406{
407 return pCur ? pCur->pNext : NULL;
408}
409
410
411/**
412 * Gets the name of the current node.
413 * (Needed for enumeration.)
414 *
415 * @returns VBox status code.
416 * @param pCur Node to returned by a call to CFGMR3GetFirstChild()
417 * or successive calls to CFGMR3GetNextChild().
418 * @param pszName Where to store the node name.
419 * @param cchName Size of the buffer pointed to by pszName (with terminator).
420 */
421VMMR3DECL(int) CFGMR3GetName(PCFGMNODE pCur, char *pszName, size_t cchName)
422{
423 int rc;
424 if (pCur)
425 {
426 if (cchName > pCur->cchName)
427 {
428 rc = VINF_SUCCESS;
429 memcpy(pszName, pCur->szName, pCur->cchName + 1);
430 }
431 else
432 rc = VERR_CFGM_NOT_ENOUGH_SPACE;
433 }
434 else
435 rc = VERR_CFGM_NO_NODE;
436 return rc;
437}
438
439
440/**
441 * Gets the length of the current node's name.
442 * (Needed for enumeration.)
443 *
444 * @returns Node name length in bytes including the terminating null char.
445 * @returns 0 if pCur is NULL.
446 * @param pCur Node to returned by a call to CFGMR3GetFirstChild()
447 * or successive calls to CFGMR3GetNextChild().
448 */
449VMMR3DECL(size_t) CFGMR3GetNameLen(PCFGMNODE pCur)
450{
451 return pCur ? pCur->cchName + 1 : 0;
452}
453
454
455/**
456 * Validates that the child nodes are within a set of valid names.
457 *
458 * @returns true if all names are found in pszzAllowed.
459 * @returns false if not.
460 * @param pNode The node which children should be examined.
461 * @param pszzValid List of valid names separated by '\\0' and ending with
462 * a double '\\0'.
463 *
464 * @deprecated Use CFGMR3ValidateConfig.
465 */
466VMMR3DECL(bool) CFGMR3AreChildrenValid(PCFGMNODE pNode, const char *pszzValid)
467{
468 if (pNode)
469 {
470 for (PCFGMNODE pChild = pNode->pFirstChild; pChild; pChild = pChild->pNext)
471 {
472 /* search pszzValid for the name */
473 const char *psz = pszzValid;
474 while (*psz)
475 {
476 size_t cch = strlen(psz);
477 if ( cch == pChild->cchName
478 && !memcmp(psz, pChild->szName, cch))
479 break;
480
481 /* next */
482 psz += cch + 1;
483 }
484
485 /* if at end of pszzValid we didn't find it => failure */
486 if (!*psz)
487 {
488 AssertMsgFailed(("Couldn't find '%s' in the valid values\n", pChild->szName));
489 return false;
490 }
491 }
492 }
493
494 /* all ok. */
495 return true;
496}
497
498
499/**
500 * Gets the first value of a node.
501 * Use this to start an enumeration of values.
502 *
503 * @returns Pointer to the first value.
504 * @param pCur The node (Key) which values to enumerate.
505 */
506VMMR3DECL(PCFGMLEAF) CFGMR3GetFirstValue(PCFGMNODE pCur)
507{
508 return pCur ? pCur->pFirstLeaf : NULL;
509}
510
511/**
512 * Gets the next value in enumeration.
513 *
514 * @returns Pointer to the next value.
515 * @param pCur The current value as returned by this function or CFGMR3GetFirstValue().
516 */
517VMMR3DECL(PCFGMLEAF) CFGMR3GetNextValue(PCFGMLEAF pCur)
518{
519 return pCur ? pCur->pNext : NULL;
520}
521
522/**
523 * Get the value name.
524 * (Needed for enumeration.)
525 *
526 * @returns VBox status code.
527 * @param pCur Value returned by a call to CFGMR3GetFirstValue()
528 * or successive calls to CFGMR3GetNextValue().
529 * @param pszName Where to store the value name.
530 * @param cchName Size of the buffer pointed to by pszName (with terminator).
531 */
532VMMR3DECL(int) CFGMR3GetValueName(PCFGMLEAF pCur, char *pszName, size_t cchName)
533{
534 int rc;
535 if (pCur)
536 {
537 if (cchName > pCur->cchName)
538 {
539 rc = VINF_SUCCESS;
540 memcpy(pszName, pCur->szName, pCur->cchName + 1);
541 }
542 else
543 rc = VERR_CFGM_NOT_ENOUGH_SPACE;
544 }
545 else
546 rc = VERR_CFGM_NO_NODE;
547 return rc;
548}
549
550
551/**
552 * Gets the length of the current node's name.
553 * (Needed for enumeration.)
554 *
555 * @returns Value name length in bytes including the terminating null char.
556 * @returns 0 if pCur is NULL.
557 * @param pCur Value returned by a call to CFGMR3GetFirstValue()
558 * or successive calls to CFGMR3GetNextValue().
559 */
560VMMR3DECL(size_t) CFGMR3GetValueNameLen(PCFGMLEAF pCur)
561{
562 return pCur ? pCur->cchName + 1 : 0;
563}
564
565
566/**
567 * Gets the value type.
568 * (For enumeration.)
569 *
570 * @returns VBox status code.
571 * @param pCur Value returned by a call to CFGMR3GetFirstValue()
572 * or successive calls to CFGMR3GetNextValue().
573 */
574VMMR3DECL(CFGMVALUETYPE) CFGMR3GetValueType(PCFGMLEAF pCur)
575{
576 Assert(pCur);
577 return pCur->enmType;
578}
579
580
581/**
582 * Validates that the values are within a set of valid names.
583 *
584 * @returns true if all names are found in pszzAllowed.
585 * @returns false if not.
586 * @param pNode The node which values should be examined.
587 * @param pszzValid List of valid names separated by '\\0' and ending with
588 * a double '\\0'.
589 * @deprecated Use CFGMR3ValidateConfig.
590 */
591VMMR3DECL(bool) CFGMR3AreValuesValid(PCFGMNODE pNode, const char *pszzValid)
592{
593 if (pNode)
594 {
595 for (PCFGMLEAF pLeaf = pNode->pFirstLeaf; pLeaf; pLeaf = pLeaf->pNext)
596 {
597 /* search pszzValid for the name */
598 const char *psz = pszzValid;
599 while (*psz)
600 {
601 size_t cch = strlen(psz);
602 if ( cch == pLeaf->cchName
603 && !memcmp(psz, pLeaf->szName, cch))
604 break;
605
606 /* next */
607 psz += cch + 1;
608 }
609
610 /* if at end of pszzValid we didn't find it => failure */
611 if (!*psz)
612 {
613 AssertMsgFailed(("Couldn't find '%s' in the valid values\n", pLeaf->szName));
614 return false;
615 }
616 }
617 }
618
619 /* all ok. */
620 return true;
621}
622
623
624/**
625 * Checks if the given value exists.
626 *
627 * @returns true if it exists, false if not.
628 * @param pNode Which node to search for pszName in.
629 * @param pszName The name of the value we seek.
630 */
631VMMR3DECL(bool) CFGMR3Exists(PCFGMNODE pNode, const char *pszName)
632{
633 PCFGMLEAF pLeaf;
634 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
635 return RT_SUCCESS_NP(rc);
636}
637
638
639/**
640 * Query value type.
641 *
642 * @returns VBox status code.
643 * @param pNode Which node to search for pszName in.
644 * @param pszName Name of an integer value.
645 * @param penmType Where to store the type.
646 */
647VMMR3DECL(int) CFGMR3QueryType(PCFGMNODE pNode, const char *pszName, PCFGMVALUETYPE penmType)
648{
649 PCFGMLEAF pLeaf;
650 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
651 if (RT_SUCCESS(rc))
652 {
653 if (penmType)
654 *penmType = pLeaf->enmType;
655 }
656 return rc;
657}
658
659
660/**
661 * Query value size.
662 * This works on all types of values.
663 *
664 * @returns VBox status code.
665 * @param pNode Which node to search for pszName in.
666 * @param pszName Name of an integer value.
667 * @param pcb Where to store the value size.
668 */
669VMMR3DECL(int) CFGMR3QuerySize(PCFGMNODE pNode, const char *pszName, size_t *pcb)
670{
671 PCFGMLEAF pLeaf;
672 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
673 if (RT_SUCCESS(rc))
674 {
675 switch (pLeaf->enmType)
676 {
677 case CFGMVALUETYPE_INTEGER:
678 *pcb = sizeof(pLeaf->Value.Integer.u64);
679 break;
680
681 case CFGMVALUETYPE_STRING:
682 *pcb = pLeaf->Value.String.cb;
683 break;
684
685 case CFGMVALUETYPE_BYTES:
686 *pcb = pLeaf->Value.Bytes.cb;
687 break;
688
689 default:
690 rc = VERR_CFGM_IPE_1;
691 AssertMsgFailed(("Invalid value type %d\n", pLeaf->enmType));
692 break;
693 }
694 }
695 return rc;
696}
697
698
699/**
700 * Query integer value.
701 *
702 * @returns VBox status code.
703 * @param pNode Which node to search for pszName in.
704 * @param pszName Name of an integer value.
705 * @param pu64 Where to store the integer value.
706 */
707VMMR3DECL(int) CFGMR3QueryInteger(PCFGMNODE pNode, const char *pszName, uint64_t *pu64)
708{
709 PCFGMLEAF pLeaf;
710 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
711 if (RT_SUCCESS(rc))
712 {
713 if (pLeaf->enmType == CFGMVALUETYPE_INTEGER)
714 *pu64 = pLeaf->Value.Integer.u64;
715 else
716 rc = VERR_CFGM_NOT_INTEGER;
717 }
718 return rc;
719}
720
721
722/**
723 * Query integer value with default.
724 *
725 * @returns VBox status code.
726 * @param pNode Which node to search for pszName in.
727 * @param pszName Name of an integer value.
728 * @param pu64 Where to store the integer value. This is set to the default on failure.
729 * @param u64Def The default value. This is always set.
730 */
731VMMR3DECL(int) CFGMR3QueryIntegerDef(PCFGMNODE pNode, const char *pszName, uint64_t *pu64, uint64_t u64Def)
732{
733 PCFGMLEAF pLeaf;
734 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
735 if (RT_SUCCESS(rc))
736 {
737 if (pLeaf->enmType == CFGMVALUETYPE_INTEGER)
738 *pu64 = pLeaf->Value.Integer.u64;
739 else
740 rc = VERR_CFGM_NOT_INTEGER;
741 }
742
743 if (RT_FAILURE(rc))
744 {
745 *pu64 = u64Def;
746 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
747 rc = VINF_SUCCESS;
748 }
749
750 return rc;
751}
752
753
754/**
755 * Query zero terminated character value.
756 *
757 * @returns VBox status code.
758 * @param pNode Which node to search for pszName in.
759 * @param pszName Name of a zero terminate character value.
760 * @param pszString Where to store the string.
761 * @param cchString Size of the string buffer. (Includes terminator.)
762 */
763VMMR3DECL(int) CFGMR3QueryString(PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString)
764{
765 PCFGMLEAF pLeaf;
766 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
767 if (RT_SUCCESS(rc))
768 {
769 if (pLeaf->enmType == CFGMVALUETYPE_STRING)
770 {
771 size_t cbSrc = pLeaf->Value.String.cb;
772 if (cchString >= cbSrc)
773 {
774 memcpy(pszString, pLeaf->Value.String.psz, cbSrc);
775 memset(pszString + cbSrc, 0, cchString - cbSrc);
776 }
777 else
778 rc = VERR_CFGM_NOT_ENOUGH_SPACE;
779 }
780 else
781 rc = VERR_CFGM_NOT_STRING;
782 }
783 return rc;
784}
785
786
787/**
788 * Query zero terminated character value with default.
789 *
790 * @returns VBox status code.
791 * @param pNode Which node to search for pszName in.
792 * @param pszName Name of a zero terminate character value.
793 * @param pszString Where to store the string. This will not be set on overflow error.
794 * @param cchString Size of the string buffer. (Includes terminator.)
795 * @param pszDef The default value.
796 */
797VMMR3DECL(int) CFGMR3QueryStringDef(PCFGMNODE pNode, const char *pszName, char *pszString, size_t cchString, const char *pszDef)
798{
799 PCFGMLEAF pLeaf;
800 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
801 if (RT_SUCCESS(rc))
802 {
803 if (pLeaf->enmType == CFGMVALUETYPE_STRING)
804 {
805 size_t cbSrc = pLeaf->Value.String.cb;
806 if (cchString >= cbSrc)
807 {
808 memcpy(pszString, pLeaf->Value.String.psz, cbSrc);
809 memset(pszString + cbSrc, 0, cchString - cbSrc);
810 }
811 else
812 rc = VERR_CFGM_NOT_ENOUGH_SPACE;
813 }
814 else
815 rc = VERR_CFGM_NOT_STRING;
816 }
817
818 if (RT_FAILURE(rc) && rc != VERR_CFGM_NOT_ENOUGH_SPACE)
819 {
820 size_t cchDef = strlen(pszDef);
821 if (cchString > cchDef)
822 {
823 memcpy(pszString, pszDef, cchDef);
824 memset(pszString + cchDef, 0, cchString - cchDef);
825 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
826 rc = VINF_SUCCESS;
827 }
828 else if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
829 rc = VERR_CFGM_NOT_ENOUGH_SPACE;
830 }
831
832 return rc;
833}
834
835
836/**
837 * Query byte string value.
838 *
839 * @returns VBox status code.
840 * @param pNode Which node to search for pszName in.
841 * @param pszName Name of a byte string value.
842 * @param pvData Where to store the binary data.
843 * @param cbData Size of buffer pvData points too.
844 */
845VMMR3DECL(int) CFGMR3QueryBytes(PCFGMNODE pNode, const char *pszName, void *pvData, size_t cbData)
846{
847 PCFGMLEAF pLeaf;
848 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
849 if (RT_SUCCESS(rc))
850 {
851 if (pLeaf->enmType == CFGMVALUETYPE_BYTES)
852 {
853 if (cbData >= pLeaf->Value.Bytes.cb)
854 {
855 memcpy(pvData, pLeaf->Value.Bytes.pau8, pLeaf->Value.Bytes.cb);
856 memset((char *)pvData + pLeaf->Value.Bytes.cb, 0, cbData - pLeaf->Value.Bytes.cb);
857 }
858 else
859 rc = VERR_CFGM_NOT_ENOUGH_SPACE;
860 }
861 else
862 rc = VERR_CFGM_NOT_BYTES;
863 }
864 return rc;
865}
866
867
868/**
869 * Validate one level of a configuration node.
870 *
871 * This replaces the CFGMR3AreChildrenValid and CFGMR3AreValuesValid APIs.
872 *
873 * @returns VBox status code.
874 *
875 * When an error is returned, both VMSetError and AssertLogRelMsgFailed
876 * have been called. So, all the caller needs to do is to propagate
877 * the error status up to PDM.
878 *
879 * @param pNode The node to validate.
880 * @param pszNode The node path, always ends with a slash. Use
881 * "/" for the root config node.
882 * @param pszValidValues Patterns describing the valid value names. See
883 * RTStrSimplePatternMultiMatch for details on the
884 * pattern syntax.
885 * @param pszValidNodes Patterns describing the valid node (key) names.
886 * See RTStrSimplePatternMultiMatch for details on
887 * the pattern syntax.
888 * @param pszWho Who is calling.
889 * @param uInstance The instance number of the caller.
890 */
891VMMR3DECL(int) CFGMR3ValidateConfig(PCFGMNODE pNode, const char *pszNode,
892 const char *pszValidValues, const char *pszValidNodes,
893 const char *pszWho, uint32_t uInstance)
894{
895 /* Input validation. */
896 AssertPtrNullReturn(pNode, VERR_INVALID_POINTER);
897 AssertPtrReturn(pszNode, VERR_INVALID_POINTER);
898 Assert(*pszNode && pszNode[strlen(pszNode) - 1] == '/');
899 AssertPtrReturn(pszValidValues, VERR_INVALID_POINTER);
900 AssertPtrReturn(pszValidNodes, VERR_INVALID_POINTER);
901 AssertPtrReturn(pszWho, VERR_INVALID_POINTER);
902
903 if (pNode)
904 {
905 /*
906 * Enumerate the leaves and check them against pszValidValues.
907 */
908 for (PCFGMLEAF pLeaf = pNode->pFirstLeaf; pLeaf; pLeaf = pLeaf->pNext)
909 {
910 if (!RTStrSimplePatternMultiMatch(pszValidValues, RTSTR_MAX,
911 pLeaf->szName, pLeaf->cchName,
912 NULL))
913 {
914 AssertLogRelMsgFailed(("%s/%u: Value '%s%s' didn't match '%s'\n",
915 pszWho, uInstance, pszNode, pLeaf->szName, pszValidValues));
916 return VMSetError(pNode->pVM, VERR_CFGM_CONFIG_UNKNOWN_VALUE, RT_SRC_POS,
917 N_("Unknown configuration value '%s%s' found in the configuration of %s instance #%u"),
918 pszNode, pLeaf->szName, pszWho, uInstance);
919 }
920
921 }
922
923 /*
924 * Enumerate the child nodes and check them against pszValidNodes.
925 */
926 for (PCFGMNODE pChild = pNode->pFirstChild; pChild; pChild = pChild->pNext)
927 {
928 if (!RTStrSimplePatternMultiMatch(pszValidNodes, RTSTR_MAX,
929 pChild->szName, pChild->cchName,
930 NULL))
931 {
932 AssertLogRelMsgFailed(("%s/%u: Node '%s%s' didn't match '%s'\n",
933 pszWho, uInstance, pszNode, pChild->szName, pszValidNodes));
934 return VMSetError(pNode->pVM, VERR_CFGM_CONFIG_UNKNOWN_NODE, RT_SRC_POS,
935 N_("Unknown configuration node '%s%s' found in the configuration of %s instance #%u"),
936 pszNode, pChild->szName, pszWho, uInstance);
937 }
938 }
939 }
940
941 /* All is well. */
942 return VINF_SUCCESS;
943}
944
945
946
947/**
948 * Populates the CFGM tree with the default configuration.
949 *
950 * This assumes an empty tree and is intended for testcases and such that only
951 * need to do very small adjustments to the config.
952 *
953 * @returns VBox status code.
954 * @param pVM The cross context VM structure.
955 * @internal
956 */
957VMMR3DECL(int) CFGMR3ConstructDefaultTree(PVM pVM)
958{
959 int rc;
960 int rcAll = VINF_SUCCESS;
961#define UPDATERC() do { if (RT_FAILURE(rc) && RT_SUCCESS(rcAll)) rcAll = rc; } while (0)
962
963 PCFGMNODE pRoot = CFGMR3GetRoot(pVM);
964 AssertReturn(pRoot, VERR_WRONG_ORDER);
965
966 /*
967 * Create VM default values.
968 */
969 rc = CFGMR3InsertString(pRoot, "Name", "Default VM");
970 UPDATERC();
971 rc = CFGMR3InsertInteger(pRoot, "RamSize", 128U * _1M);
972 UPDATERC();
973 rc = CFGMR3InsertInteger(pRoot, "RamHoleSize", 512U * _1M);
974 UPDATERC();
975 rc = CFGMR3InsertInteger(pRoot, "TimerMillies", 10);
976 UPDATERC();
977 rc = CFGMR3InsertInteger(pRoot, "RawR3Enabled", 1);
978 UPDATERC();
979 /** @todo CFGM Defaults: RawR0, PATMEnabled and CASMEnabled needs attention later. */
980 rc = CFGMR3InsertInteger(pRoot, "RawR0Enabled", 1);
981 UPDATERC();
982 rc = CFGMR3InsertInteger(pRoot, "PATMEnabled", 1);
983 UPDATERC();
984 rc = CFGMR3InsertInteger(pRoot, "CSAMEnabled", 1);
985 UPDATERC();
986
987 /*
988 * PDM.
989 */
990 PCFGMNODE pPdm;
991 rc = CFGMR3InsertNode(pRoot, "PDM", &pPdm);
992 UPDATERC();
993 PCFGMNODE pDevices = NULL;
994 rc = CFGMR3InsertNode(pPdm, "Devices", &pDevices);
995 UPDATERC();
996 rc = CFGMR3InsertInteger(pDevices, "LoadBuiltin", 1); /* boolean */
997 UPDATERC();
998 PCFGMNODE pDrivers = NULL;
999 rc = CFGMR3InsertNode(pPdm, "Drivers", &pDrivers);
1000 UPDATERC();
1001 rc = CFGMR3InsertInteger(pDrivers, "LoadBuiltin", 1); /* boolean */
1002 UPDATERC();
1003
1004
1005 /*
1006 * Devices
1007 */
1008 pDevices = NULL;
1009 rc = CFGMR3InsertNode(pRoot, "Devices", &pDevices);
1010 UPDATERC();
1011 /* device */
1012 PCFGMNODE pDev = NULL;
1013 PCFGMNODE pInst = NULL;
1014 PCFGMNODE pCfg = NULL;
1015#if 0
1016 PCFGMNODE pLunL0 = NULL;
1017 PCFGMNODE pLunL1 = NULL;
1018#endif
1019
1020 /*
1021 * PC Arch.
1022 */
1023 rc = CFGMR3InsertNode(pDevices, "pcarch", &pDev);
1024 UPDATERC();
1025 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1026 UPDATERC();
1027 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1028 UPDATERC();
1029 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1030 UPDATERC();
1031
1032 /*
1033 * PC Bios.
1034 */
1035 rc = CFGMR3InsertNode(pDevices, "pcbios", &pDev);
1036 UPDATERC();
1037 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1038 UPDATERC();
1039 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1040 UPDATERC();
1041 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1042 UPDATERC();
1043 rc = CFGMR3InsertInteger(pCfg, "RamSize", 128U * _1M);
1044 UPDATERC();
1045 rc = CFGMR3InsertInteger(pCfg, "RamHoleSize", 512U * _1M);
1046 UPDATERC();
1047 rc = CFGMR3InsertString(pCfg, "BootDevice0", "IDE");
1048 UPDATERC();
1049 rc = CFGMR3InsertString(pCfg, "BootDevice1", "NONE");
1050 UPDATERC();
1051 rc = CFGMR3InsertString(pCfg, "BootDevice2", "NONE");
1052 UPDATERC();
1053 rc = CFGMR3InsertString(pCfg, "BootDevice3", "NONE");
1054 UPDATERC();
1055 rc = CFGMR3InsertString(pCfg, "HardDiskDevice", "piix3ide");
1056 UPDATERC();
1057 rc = CFGMR3InsertString(pCfg, "FloppyDevice", "");
1058 UPDATERC();
1059 RTUUID Uuid;
1060 RTUuidClear(&Uuid);
1061 rc = CFGMR3InsertBytes(pCfg, "UUID", &Uuid, sizeof(Uuid));
1062 UPDATERC();
1063
1064 /*
1065 * PCI bus.
1066 */
1067 rc = CFGMR3InsertNode(pDevices, "pci", &pDev); /* piix3 */
1068 UPDATERC();
1069 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1070 UPDATERC();
1071 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1072 UPDATERC();
1073 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1074 UPDATERC();
1075
1076 /*
1077 * PS/2 keyboard & mouse
1078 */
1079 rc = CFGMR3InsertNode(pDevices, "pckbd", &pDev);
1080 UPDATERC();
1081 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1082 UPDATERC();
1083 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1084 UPDATERC();
1085#if 0
1086 rc = CFGMR3InsertNode(pInst, "LUN#0", &pLunL0);
1087 UPDATERC();
1088 rc = CFGMR3InsertString(pLunL0, "Driver", "KeyboardQueue");
1089 UPDATERC();
1090 rc = CFGMR3InsertNode(pLunL0, "Config", &pCfg);
1091 UPDATERC();
1092 rc = CFGMR3InsertInteger(pCfg, "QueueSize", 64);
1093 UPDATERC();
1094 rc = CFGMR3InsertNode(pLunL0, "AttachedDriver", &pLunL1);
1095 UPDATERC();
1096 rc = CFGMR3InsertString(pLunL1, "Driver", "MainKeyboard");
1097 UPDATERC();
1098 rc = CFGMR3InsertNode(pLunL1, "Config", &pCfg);
1099 UPDATERC();
1100#endif
1101#if 0
1102 rc = CFGMR3InsertNode(pInst, "LUN#1", &pLunL0);
1103 UPDATERC();
1104 rc = CFGMR3InsertString(pLunL0, "Driver", "MouseQueue");
1105 UPDATERC();
1106 rc = CFGMR3InsertNode(pLunL0, "Config", &pCfg);
1107 UPDATERC();
1108 rc = CFGMR3InsertInteger(pCfg, "QueueSize", 128);
1109 UPDATERC();
1110 rc = CFGMR3InsertNode(pLunL0, "AttachedDriver", &pLunL1);
1111 UPDATERC();
1112 rc = CFGMR3InsertString(pLunL1, "Driver", "MainMouse");
1113 UPDATERC();
1114 rc = CFGMR3InsertNode(pLunL1, "Config", &pCfg);
1115 UPDATERC();
1116#endif
1117
1118 /*
1119 * i8254 Programmable Interval Timer And Dummy Speaker
1120 */
1121 rc = CFGMR3InsertNode(pDevices, "i8254", &pDev);
1122 UPDATERC();
1123 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1124 UPDATERC();
1125#ifdef DEBUG
1126 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1127 UPDATERC();
1128#endif
1129 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1130 UPDATERC();
1131
1132 /*
1133 * i8259 Programmable Interrupt Controller.
1134 */
1135 rc = CFGMR3InsertNode(pDevices, "i8259", &pDev);
1136 UPDATERC();
1137 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1138 UPDATERC();
1139 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1140 UPDATERC();
1141 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1142 UPDATERC();
1143
1144 /*
1145 * RTC MC146818.
1146 */
1147 rc = CFGMR3InsertNode(pDevices, "mc146818", &pDev);
1148 UPDATERC();
1149 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1150 UPDATERC();
1151 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1152 UPDATERC();
1153
1154 /*
1155 * VGA.
1156 */
1157 rc = CFGMR3InsertNode(pDevices, "vga", &pDev);
1158 UPDATERC();
1159 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1160 UPDATERC();
1161 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1162 UPDATERC();
1163 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1164 UPDATERC();
1165 rc = CFGMR3InsertInteger(pCfg, "VRamSize", 4 * _1M);
1166 UPDATERC();
1167
1168 /* Bios logo. */
1169 rc = CFGMR3InsertInteger(pCfg, "FadeIn", 1);
1170 UPDATERC();
1171 rc = CFGMR3InsertInteger(pCfg, "FadeOut", 1);
1172 UPDATERC();
1173 rc = CFGMR3InsertInteger(pCfg, "LogoTime", 0);
1174 UPDATERC();
1175 rc = CFGMR3InsertString(pCfg, "LogoFile", "");
1176 UPDATERC();
1177
1178#if 0
1179 rc = CFGMR3InsertNode(pInst, "LUN#0", &pLunL0);
1180 UPDATERC();
1181 rc = CFGMR3InsertString(pLunL0, "Driver", "MainDisplay");
1182 UPDATERC();
1183#endif
1184
1185 /*
1186 * IDE controller.
1187 */
1188 rc = CFGMR3InsertNode(pDevices, "piix3ide", &pDev); /* piix3 */
1189 UPDATERC();
1190 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1191 UPDATERC();
1192 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1193 UPDATERC();
1194 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1195 UPDATERC();
1196
1197 /*
1198 * VMMDev.
1199 */
1200 rc = CFGMR3InsertNode(pDevices, "VMMDev", &pDev);
1201 UPDATERC();
1202 rc = CFGMR3InsertNode(pDev, "0", &pInst);
1203 UPDATERC();
1204 rc = CFGMR3InsertNode(pInst, "Config", &pCfg);
1205 UPDATERC();
1206 rc = CFGMR3InsertInteger(pInst, "Trusted", 1); /* boolean */
1207 UPDATERC();
1208 rc = CFGMR3InsertInteger(pCfg, "RamSize", 128U * _1M);
1209 UPDATERC();
1210
1211
1212 /*
1213 * ...
1214 */
1215
1216#undef UPDATERC
1217 return rcAll;
1218}
1219
1220
1221
1222
1223/**
1224 * Resolves a path reference to a child node.
1225 *
1226 * @returns VBox status code.
1227 * @param pNode Which node to search for pszName in.
1228 * @param pszPath Path to the child node.
1229 * @param ppChild Where to store the pointer to the child node.
1230 */
1231static int cfgmR3ResolveNode(PCFGMNODE pNode, const char *pszPath, PCFGMNODE *ppChild)
1232{
1233 *ppChild = NULL;
1234 if (!pNode)
1235 return VERR_CFGM_NO_PARENT;
1236 PCFGMNODE pChild = NULL;
1237 for (;;)
1238 {
1239 /* skip leading slashes. */
1240 while (*pszPath == '/')
1241 pszPath++;
1242
1243 /* End of path? */
1244 if (!*pszPath)
1245 {
1246 if (!pChild)
1247 return VERR_CFGM_INVALID_CHILD_PATH;
1248 *ppChild = pChild;
1249 return VINF_SUCCESS;
1250 }
1251
1252 /* find end of component. */
1253 const char *pszNext = strchr(pszPath, '/');
1254 if (!pszNext)
1255 pszNext = strchr(pszPath, '\0');
1256 RTUINT cchName = pszNext - pszPath;
1257
1258 /* search child list. */
1259 pChild = pNode->pFirstChild;
1260 for ( ; pChild; pChild = pChild->pNext)
1261 if (pChild->cchName == cchName)
1262 {
1263 int iDiff = memcmp(pszPath, pChild->szName, cchName);
1264 if (iDiff <= 0)
1265 {
1266 if (iDiff != 0)
1267 pChild = NULL;
1268 break;
1269 }
1270 }
1271 if (!pChild)
1272 return VERR_CFGM_CHILD_NOT_FOUND;
1273
1274 /* next iteration */
1275 pNode = pChild;
1276 pszPath = pszNext;
1277 }
1278
1279 /* won't get here */
1280}
1281
1282
1283/**
1284 * Resolves a path reference to a child node.
1285 *
1286 * @returns VBox status code.
1287 * @param pNode Which node to search for pszName in.
1288 * @param pszName Name of a byte string value.
1289 * @param ppLeaf Where to store the pointer to the leaf node.
1290 */
1291static int cfgmR3ResolveLeaf(PCFGMNODE pNode, const char *pszName, PCFGMLEAF *ppLeaf)
1292{
1293 *ppLeaf = NULL;
1294 if (!pNode)
1295 return VERR_CFGM_NO_PARENT;
1296
1297 size_t cchName = strlen(pszName);
1298 PCFGMLEAF pLeaf = pNode->pFirstLeaf;
1299 while (pLeaf)
1300 {
1301 if (cchName == pLeaf->cchName)
1302 {
1303 int iDiff = memcmp(pszName, pLeaf->szName, cchName);
1304 if (iDiff <= 0)
1305 {
1306 if (iDiff != 0)
1307 break;
1308 *ppLeaf = pLeaf;
1309 return VINF_SUCCESS;
1310 }
1311 }
1312
1313 /* next */
1314 pLeaf = pLeaf->pNext;
1315 }
1316 return VERR_CFGM_VALUE_NOT_FOUND;
1317}
1318
1319
1320
1321/**
1322 * Creates a CFGM tree.
1323 *
1324 * This is intended for creating device/driver configs can be
1325 * passed around and later attached to the main tree in the
1326 * correct location.
1327 *
1328 * @returns Pointer to the root node, NULL on error (out of memory or invalid
1329 * VM handle).
1330 * @param pUVM The user mode VM handle. For testcase (and other
1331 * purposes, NULL can be used. However, the resulting
1332 * tree cannot be inserted into a tree that has a
1333 * non-NULL value. Using NULL can be usedful for
1334 * testcases and similar, non VMM uses.
1335 */
1336VMMR3DECL(PCFGMNODE) CFGMR3CreateTree(PUVM pUVM)
1337{
1338 if (pUVM)
1339 {
1340 UVM_ASSERT_VALID_EXT_RETURN(pUVM, NULL);
1341 VM_ASSERT_VALID_EXT_RETURN(pUVM->pVM, NULL);
1342 }
1343
1344 PCFGMNODE pNew;
1345 if (pUVM)
1346 pNew = (PCFGMNODE)MMR3HeapAllocU(pUVM, MM_TAG_CFGM, sizeof(*pNew));
1347 else
1348 pNew = (PCFGMNODE)RTMemAlloc(sizeof(*pNew));
1349 if (pNew)
1350 {
1351 pNew->pPrev = NULL;
1352 pNew->pNext = NULL;
1353 pNew->pParent = NULL;
1354 pNew->pFirstChild = NULL;
1355 pNew->pFirstLeaf = NULL;
1356 pNew->pVM = pUVM ? pUVM->pVM : NULL;
1357 pNew->fRestrictedRoot = false;
1358 pNew->cchName = 0;
1359 pNew->szName[0] = 0;
1360 }
1361 return pNew;
1362}
1363
1364
1365/**
1366 * Duplicates a CFGM sub-tree or a full tree.
1367 *
1368 * @returns Pointer to the root node. NULL if we run out of memory or the
1369 * input parameter is NULL.
1370 * @param pRoot The root of the tree to duplicate.
1371 * @param ppCopy Where to return the root of the duplicate.
1372 */
1373VMMR3DECL(int) CFGMR3DuplicateSubTree(PCFGMNODE pRoot, PCFGMNODE *ppCopy)
1374{
1375 AssertPtrReturn(pRoot, VERR_INVALID_POINTER);
1376
1377 /*
1378 * Create a new tree.
1379 */
1380 PCFGMNODE pNewRoot = CFGMR3CreateTree(pRoot->pVM ? pRoot->pVM->pUVM : NULL);
1381 if (!pNewRoot)
1382 return VERR_NO_MEMORY;
1383
1384 /*
1385 * Duplicate the content.
1386 */
1387 int rc = VINF_SUCCESS;
1388 PCFGMNODE pSrcCur = pRoot;
1389 PCFGMNODE pDstCur = pNewRoot;
1390 for (;;)
1391 {
1392 if ( !pDstCur->pFirstChild
1393 && !pDstCur->pFirstLeaf)
1394 {
1395 /*
1396 * Values first.
1397 */
1398 /** @todo this isn't the most efficient way to do it. */
1399 for (PCFGMLEAF pLeaf = pSrcCur->pFirstLeaf; pLeaf && RT_SUCCESS(rc); pLeaf = pLeaf->pNext)
1400 rc = CFGMR3InsertValue(pDstCur, pLeaf);
1401
1402 /*
1403 * Insert immediate child nodes.
1404 */
1405 /** @todo this isn't the most efficient way to do it. */
1406 for (PCFGMNODE pChild = pSrcCur->pFirstChild; pChild && RT_SUCCESS(rc); pChild = pChild->pNext)
1407 rc = CFGMR3InsertNode(pDstCur, pChild->szName, NULL);
1408
1409 AssertLogRelRCBreak(rc);
1410 }
1411
1412 /*
1413 * Deep copy of the children.
1414 */
1415 if (pSrcCur->pFirstChild)
1416 {
1417 Assert(pDstCur->pFirstChild && !strcmp(pDstCur->pFirstChild->szName, pSrcCur->pFirstChild->szName));
1418 pSrcCur = pSrcCur->pFirstChild;
1419 pDstCur = pDstCur->pFirstChild;
1420 }
1421 /*
1422 * If it's the root node, we're done.
1423 */
1424 else if (pSrcCur == pRoot)
1425 break;
1426 else
1427 {
1428 /*
1429 * Upon reaching the end of a sibling list, we must ascend and
1430 * resume the sibiling walk on an previous level.
1431 */
1432 if (!pSrcCur->pNext)
1433 {
1434 do
1435 {
1436 pSrcCur = pSrcCur->pParent;
1437 pDstCur = pDstCur->pParent;
1438 } while (!pSrcCur->pNext && pSrcCur != pRoot);
1439 if (pSrcCur == pRoot)
1440 break;
1441 }
1442
1443 /*
1444 * Next sibling.
1445 */
1446 Assert(pDstCur->pNext && !strcmp(pDstCur->pNext->szName, pSrcCur->pNext->szName));
1447 pSrcCur = pSrcCur->pNext;
1448 pDstCur = pDstCur->pNext;
1449 }
1450 }
1451
1452 if (RT_FAILURE(rc))
1453 {
1454 CFGMR3RemoveNode(pNewRoot);
1455 return rc;
1456 }
1457
1458 *ppCopy = pNewRoot;
1459 return VINF_SUCCESS;
1460}
1461
1462
1463/**
1464 * Insert subtree.
1465 *
1466 * This function inserts (no duplication) a tree created by CFGMR3CreateTree()
1467 * into the main tree.
1468 *
1469 * The root node of the inserted subtree will need to be reallocated, which
1470 * effectually means that the passed in pSubTree handle becomes invalid
1471 * upon successful return. Use the value returned in ppChild instead
1472 * of pSubTree.
1473 *
1474 * @returns VBox status code.
1475 * @returns VERR_CFGM_NODE_EXISTS if the final child node name component exists.
1476 * @param pNode Parent node.
1477 * @param pszName Name or path of the new child node.
1478 * @param pSubTree The subtree to insert. Must be returned by CFGMR3CreateTree().
1479 * @param ppChild Where to store the address of the new child node. (optional)
1480 */
1481VMMR3DECL(int) CFGMR3InsertSubTree(PCFGMNODE pNode, const char *pszName, PCFGMNODE pSubTree, PCFGMNODE *ppChild)
1482{
1483 /*
1484 * Validate input.
1485 */
1486 AssertPtrReturn(pNode, VERR_INVALID_POINTER);
1487 AssertPtrReturn(pSubTree, VERR_INVALID_POINTER);
1488 AssertReturn(pNode != pSubTree, VERR_INVALID_PARAMETER);
1489 AssertReturn(!pSubTree->pParent, VERR_INVALID_PARAMETER);
1490 AssertReturn(pNode->pVM == pSubTree->pVM, VERR_INVALID_PARAMETER);
1491 Assert(!pSubTree->pNext);
1492 Assert(!pSubTree->pPrev);
1493
1494 /*
1495 * Use CFGMR3InsertNode to create a new node and then
1496 * re-attach the children and leaves of the subtree to it.
1497 */
1498 PCFGMNODE pNewChild;
1499 int rc = CFGMR3InsertNode(pNode, pszName, &pNewChild);
1500 if (RT_SUCCESS(rc))
1501 {
1502 Assert(!pNewChild->pFirstChild);
1503 Assert(!pNewChild->pFirstLeaf);
1504
1505 pNewChild->pFirstChild = pSubTree->pFirstChild;
1506 pNewChild->pFirstLeaf = pSubTree->pFirstLeaf;
1507 for (PCFGMNODE pChild = pNewChild->pFirstChild; pChild; pChild = pChild->pNext)
1508 pChild->pParent = pNewChild;
1509
1510 if (ppChild)
1511 *ppChild = pNewChild;
1512
1513 /* free the old subtree root */
1514 cfgmR3FreeNodeOnly(pSubTree);
1515 }
1516 return rc;
1517}
1518
1519
1520/**
1521 * Replaces a (sub-)tree with new one.
1522 *
1523 * This function removes the exiting (sub-)tree, completely freeing it in the
1524 * process, and inserts (no duplication) the specified tree. The tree can
1525 * either be created by CFGMR3CreateTree or CFGMR3DuplicateSubTree.
1526 *
1527 * @returns VBox status code.
1528 * @param pRoot The sub-tree to replace. This node will remain valid
1529 * after the call.
1530 * @param pNewRoot The tree to replace @a pRoot with. This not will
1531 * become invalid after a successful call.
1532 */
1533VMMR3DECL(int) CFGMR3ReplaceSubTree(PCFGMNODE pRoot, PCFGMNODE pNewRoot)
1534{
1535 /*
1536 * Validate input.
1537 */
1538 AssertPtrReturn(pRoot, VERR_INVALID_POINTER);
1539 AssertPtrReturn(pNewRoot, VERR_INVALID_POINTER);
1540 AssertReturn(pRoot != pNewRoot, VERR_INVALID_PARAMETER);
1541 AssertReturn(!pNewRoot->pParent, VERR_INVALID_PARAMETER);
1542 AssertReturn(pNewRoot->pVM == pRoot->pVM, VERR_INVALID_PARAMETER);
1543 AssertReturn(!pNewRoot->pNext, VERR_INVALID_PARAMETER);
1544 AssertReturn(!pNewRoot->pPrev, VERR_INVALID_PARAMETER);
1545
1546 /*
1547 * Free the current properties fo pRoot.
1548 */
1549 while (pRoot->pFirstChild)
1550 CFGMR3RemoveNode(pRoot->pFirstChild);
1551
1552 while (pRoot->pFirstLeaf)
1553 cfgmR3RemoveLeaf(pRoot, pRoot->pFirstLeaf);
1554
1555 /*
1556 * Copy all the properties from the new root to the current one.
1557 */
1558 pRoot->pFirstLeaf = pNewRoot->pFirstLeaf;
1559 pRoot->pFirstChild = pNewRoot->pFirstChild;
1560 for (PCFGMNODE pChild = pRoot->pFirstChild; pChild; pChild = pChild->pNext)
1561 pChild->pParent = pRoot;
1562
1563 cfgmR3FreeNodeOnly(pNewRoot);
1564
1565 return VINF_SUCCESS;
1566}
1567
1568
1569/**
1570 * Copies all values and keys from one tree onto another.
1571 *
1572 * The flags control what happens to keys and values with the same name
1573 * existing in both source and destination.
1574 *
1575 * @returns VBox status code.
1576 * @param pDstTree The destination tree.
1577 * @param pSrcTree The source tree.
1578 * @param fFlags Copy flags, see CFGM_COPY_FLAGS_XXX.
1579 */
1580VMMR3DECL(int) CFGMR3CopyTree(PCFGMNODE pDstTree, PCFGMNODE pSrcTree, uint32_t fFlags)
1581{
1582 /*
1583 * Input validation.
1584 */
1585 AssertPtrReturn(pSrcTree, VERR_INVALID_POINTER);
1586 AssertPtrReturn(pDstTree, VERR_INVALID_POINTER);
1587 AssertReturn(pDstTree != pSrcTree, VERR_INVALID_PARAMETER);
1588 AssertReturn(!(fFlags & ~(CFGM_COPY_FLAGS_VALUE_DISP_MASK | CFGM_COPY_FLAGS_KEY_DISP_MASK)), VERR_INVALID_PARAMETER);
1589 AssertReturn( (fFlags & CFGM_COPY_FLAGS_VALUE_DISP_MASK) != CFGM_COPY_FLAGS_RESERVED_VALUE_DISP_0
1590 && (fFlags & CFGM_COPY_FLAGS_VALUE_DISP_MASK) != CFGM_COPY_FLAGS_RESERVED_VALUE_DISP_1,
1591 VERR_INVALID_PARAMETER);
1592 AssertReturn((fFlags & CFGM_COPY_FLAGS_KEY_DISP_MASK) != CFGM_COPY_FLAGS_RESERVED_KEY_DISP,
1593 VERR_INVALID_PARAMETER);
1594
1595 /*
1596 * Copy the values.
1597 */
1598 int rc;
1599 for (PCFGMLEAF pValue = CFGMR3GetFirstValue(pSrcTree); pValue; pValue = CFGMR3GetNextValue(pValue))
1600 {
1601 rc = CFGMR3InsertValue(pDstTree, pValue);
1602 if (rc == VERR_CFGM_LEAF_EXISTS)
1603 {
1604 if ((fFlags & CFGM_COPY_FLAGS_VALUE_DISP_MASK) == CFGM_COPY_FLAGS_REPLACE_VALUES)
1605 {
1606 rc = CFGMR3RemoveValue(pDstTree, pValue->szName);
1607 if (RT_FAILURE(rc))
1608 break;
1609 rc = CFGMR3InsertValue(pDstTree, pValue);
1610 }
1611 else
1612 rc = VINF_SUCCESS;
1613 }
1614 AssertRCReturn(rc, rc);
1615 }
1616
1617 /*
1618 * Copy/merge the keys - merging results in recursion.
1619 */
1620 for (PCFGMNODE pSrcChild = CFGMR3GetFirstChild(pSrcTree); pSrcChild; pSrcChild = CFGMR3GetNextChild(pSrcChild))
1621 {
1622 PCFGMNODE pDstChild = CFGMR3GetChild(pDstTree, pSrcChild->szName);
1623 if ( pDstChild
1624 && (fFlags & CFGM_COPY_FLAGS_KEY_DISP_MASK) == CFGM_COPY_FLAGS_REPLACE_KEYS)
1625 {
1626 CFGMR3RemoveNode(pDstChild);
1627 pDstChild = NULL;
1628 }
1629 if (!pDstChild)
1630 {
1631 PCFGMNODE pChildCopy;
1632 rc = CFGMR3DuplicateSubTree(pSrcChild, &pChildCopy);
1633 AssertRCReturn(rc, rc);
1634 rc = CFGMR3InsertSubTree(pDstTree, pSrcChild->szName, pChildCopy, NULL);
1635 AssertRCReturnStmt(rc, CFGMR3RemoveNode(pChildCopy), rc);
1636 }
1637 else if ((fFlags & CFGM_COPY_FLAGS_KEY_DISP_MASK) == CFGM_COPY_FLAGS_MERGE_KEYS)
1638 {
1639 rc = CFGMR3CopyTree(pDstChild, pSrcChild, fFlags);
1640 AssertRCReturn(rc, rc);
1641 }
1642 }
1643
1644 return VINF_SUCCESS;
1645}
1646
1647
1648
1649/**
1650 * Compares two names.
1651 *
1652 * @returns Similar to memcpy.
1653 * @param pszName1 The first name.
1654 * @param cchName1 The length of the first name.
1655 * @param pszName2 The second name.
1656 * @param cchName2 The length of the second name.
1657 */
1658DECLINLINE(int) cfgmR3CompareNames(const char *pszName1, size_t cchName1, const char *pszName2, size_t cchName2)
1659{
1660 int iDiff;
1661 if (cchName1 <= cchName2)
1662 {
1663 iDiff = memcmp(pszName1, pszName2, cchName1);
1664 if (!iDiff && cchName1 < cchName2)
1665 iDiff = -1;
1666 }
1667 else
1668 {
1669 iDiff = memcmp(pszName1, pszName2, cchName2);
1670 if (!iDiff)
1671 iDiff = 1;
1672 }
1673 return iDiff;
1674}
1675
1676
1677/**
1678 * Insert a node.
1679 *
1680 * @returns VBox status code.
1681 * @returns VERR_CFGM_NODE_EXISTS if the final child node name component exists.
1682 * @param pNode Parent node.
1683 * @param pszName Name or path of the new child node.
1684 * @param ppChild Where to store the address of the new child node. (optional)
1685 */
1686VMMR3DECL(int) CFGMR3InsertNode(PCFGMNODE pNode, const char *pszName, PCFGMNODE *ppChild)
1687{
1688 int rc;
1689 if (pNode)
1690 {
1691 /*
1692 * If given a path we have to deal with it component by component.
1693 */
1694 while (*pszName == '/')
1695 pszName++;
1696 if (strchr(pszName, '/'))
1697 {
1698 char *pszDup = RTStrDup(pszName);
1699 if (pszDup)
1700 {
1701 char *psz = pszDup;
1702 for (;;)
1703 {
1704 /* Terminate at '/' and find the next component. */
1705 char *pszNext = strchr(psz, '/');
1706 if (pszNext)
1707 {
1708 *pszNext++ = '\0';
1709 while (*pszNext == '/')
1710 pszNext++;
1711 if (*pszNext == '\0')
1712 pszNext = NULL;
1713 }
1714
1715 /* does it exist? */
1716 PCFGMNODE pChild = CFGMR3GetChild(pNode, psz);
1717 if (!pChild)
1718 {
1719 /* no, insert it */
1720 rc = CFGMR3InsertNode(pNode, psz, &pChild);
1721 if (RT_FAILURE(rc))
1722 break;
1723 if (!pszNext)
1724 {
1725 if (ppChild)
1726 *ppChild = pChild;
1727 break;
1728 }
1729
1730 }
1731 /* if last component fail */
1732 else if (!pszNext)
1733 {
1734 rc = VERR_CFGM_NODE_EXISTS;
1735 break;
1736 }
1737
1738 /* next */
1739 pNode = pChild;
1740 psz = pszNext;
1741 }
1742 RTStrFree(pszDup);
1743 }
1744 else
1745 rc = VERR_NO_TMP_MEMORY;
1746 }
1747 /*
1748 * Not multicomponent, just make sure it's a non-zero name.
1749 */
1750 else if (*pszName)
1751 {
1752 /*
1753 * Check if already exists and find last node in chain.
1754 */
1755 size_t cchName = strlen(pszName);
1756 PCFGMNODE pPrev = NULL;
1757 PCFGMNODE pNext = pNode->pFirstChild;
1758 if (pNext)
1759 {
1760 for ( ; pNext; pPrev = pNext, pNext = pNext->pNext)
1761 {
1762 int iDiff = cfgmR3CompareNames(pszName, cchName, pNext->szName, pNext->cchName);
1763 if (iDiff <= 0)
1764 {
1765 if (!iDiff)
1766 return VERR_CFGM_NODE_EXISTS;
1767 break;
1768 }
1769 }
1770 }
1771
1772 /*
1773 * Allocate and init node.
1774 */
1775 PCFGMNODE pNew = (PCFGMNODE)cfgmR3MemAlloc(pNode->pVM, MM_TAG_CFGM, sizeof(*pNew) + cchName);
1776 if (pNew)
1777 {
1778 pNew->pParent = pNode;
1779 pNew->pFirstChild = NULL;
1780 pNew->pFirstLeaf = NULL;
1781 pNew->pVM = pNode->pVM;
1782 pNew->fRestrictedRoot = false;
1783 pNew->cchName = cchName;
1784 memcpy(pNew->szName, pszName, cchName + 1);
1785
1786 /*
1787 * Insert into child list.
1788 */
1789 pNew->pPrev = pPrev;
1790 if (pPrev)
1791 pPrev->pNext = pNew;
1792 else
1793 pNode->pFirstChild = pNew;
1794 pNew->pNext = pNext;
1795 if (pNext)
1796 pNext->pPrev = pNew;
1797
1798 if (ppChild)
1799 *ppChild = pNew;
1800 rc = VINF_SUCCESS;
1801 }
1802 else
1803 rc = VERR_NO_MEMORY;
1804 }
1805 else
1806 {
1807 rc = VERR_CFGM_INVALID_NODE_PATH;
1808 AssertMsgFailed(("Invalid path %s\n", pszName));
1809 }
1810 }
1811 else
1812 {
1813 rc = VERR_CFGM_NO_PARENT;
1814 AssertMsgFailed(("No parent! path %s\n", pszName));
1815 }
1816
1817 return rc;
1818}
1819
1820
1821/**
1822 * Insert a node, format string name.
1823 *
1824 * @returns VBox status code.
1825 * @param pNode Parent node.
1826 * @param ppChild Where to store the address of the new child node. (optional)
1827 * @param pszNameFormat Name of or path the new child node.
1828 * @param ... Name format arguments.
1829 */
1830VMMR3DECL(int) CFGMR3InsertNodeF(PCFGMNODE pNode, PCFGMNODE *ppChild, const char *pszNameFormat, ...)
1831{
1832 va_list Args;
1833 va_start(Args, pszNameFormat);
1834 int rc = CFGMR3InsertNodeFV(pNode, ppChild, pszNameFormat, Args);
1835 va_end(Args);
1836 return rc;
1837}
1838
1839
1840/**
1841 * Insert a node, format string name.
1842 *
1843 * @returns VBox status code.
1844 * @param pNode Parent node.
1845 * @param ppChild Where to store the address of the new child node. (optional)
1846 * @param pszNameFormat Name or path of the new child node.
1847 * @param Args Name format arguments.
1848 */
1849VMMR3DECL(int) CFGMR3InsertNodeFV(PCFGMNODE pNode, PCFGMNODE *ppChild, const char *pszNameFormat, va_list Args)
1850{
1851 int rc;
1852 char *pszName;
1853 RTStrAPrintfV(&pszName, pszNameFormat, Args);
1854 if (pszName)
1855 {
1856 rc = CFGMR3InsertNode(pNode, pszName, ppChild);
1857 RTStrFree(pszName);
1858 }
1859 else
1860 rc = VERR_NO_MEMORY;
1861 return rc;
1862}
1863
1864
1865/**
1866 * Marks the node as the root of a restricted subtree, i.e. the end of
1867 * a CFGMR3GetParent() journey.
1868 *
1869 * @param pNode The node to mark.
1870 */
1871VMMR3DECL(void) CFGMR3SetRestrictedRoot(PCFGMNODE pNode)
1872{
1873 if (pNode)
1874 pNode->fRestrictedRoot = true;
1875}
1876
1877
1878/**
1879 * Insert a node.
1880 *
1881 * @returns VBox status code.
1882 * @param pNode Parent node.
1883 * @param pszName Name of the new child node.
1884 * @param ppLeaf Where to store the new leaf.
1885 * The caller must fill in the enmType and Value fields!
1886 */
1887static int cfgmR3InsertLeaf(PCFGMNODE pNode, const char *pszName, PCFGMLEAF *ppLeaf)
1888{
1889 int rc;
1890 if (*pszName)
1891 {
1892 if (pNode)
1893 {
1894 /*
1895 * Check if already exists and find last node in chain.
1896 */
1897 size_t cchName = strlen(pszName);
1898 PCFGMLEAF pPrev = NULL;
1899 PCFGMLEAF pNext = pNode->pFirstLeaf;
1900 if (pNext)
1901 {
1902 for ( ; pNext; pPrev = pNext, pNext = pNext->pNext)
1903 {
1904 int iDiff = cfgmR3CompareNames(pszName, cchName, pNext->szName, pNext->cchName);
1905 if (iDiff <= 0)
1906 {
1907 if (!iDiff)
1908 return VERR_CFGM_LEAF_EXISTS;
1909 break;
1910 }
1911 }
1912 }
1913
1914 /*
1915 * Allocate and init node.
1916 */
1917 PCFGMLEAF pNew = (PCFGMLEAF)cfgmR3MemAlloc(pNode->pVM, MM_TAG_CFGM, sizeof(*pNew) + cchName);
1918 if (pNew)
1919 {
1920 pNew->cchName = cchName;
1921 memcpy(pNew->szName, pszName, cchName + 1);
1922
1923 /*
1924 * Insert into child list.
1925 */
1926 pNew->pPrev = pPrev;
1927 if (pPrev)
1928 pPrev->pNext = pNew;
1929 else
1930 pNode->pFirstLeaf = pNew;
1931 pNew->pNext = pNext;
1932 if (pNext)
1933 pNext->pPrev = pNew;
1934
1935 *ppLeaf = pNew;
1936 rc = VINF_SUCCESS;
1937 }
1938 else
1939 rc = VERR_NO_MEMORY;
1940 }
1941 else
1942 rc = VERR_CFGM_NO_PARENT;
1943 }
1944 else
1945 rc = VERR_CFGM_INVALID_CHILD_PATH;
1946 return rc;
1947}
1948
1949
1950/**
1951 * Removes a node.
1952 *
1953 * @param pNode The node to remove.
1954 */
1955VMMR3DECL(void) CFGMR3RemoveNode(PCFGMNODE pNode)
1956{
1957 if (pNode)
1958 {
1959 /*
1960 * Free children.
1961 */
1962 while (pNode->pFirstChild)
1963 CFGMR3RemoveNode(pNode->pFirstChild);
1964
1965 /*
1966 * Free leaves.
1967 */
1968 while (pNode->pFirstLeaf)
1969 cfgmR3RemoveLeaf(pNode, pNode->pFirstLeaf);
1970
1971 /*
1972 * Unlink ourselves.
1973 */
1974 if (pNode->pPrev)
1975 pNode->pPrev->pNext = pNode->pNext;
1976 else
1977 {
1978 if (pNode->pParent)
1979 pNode->pParent->pFirstChild = pNode->pNext;
1980 else if ( pNode->pVM /* might be a different tree */
1981 && pNode == pNode->pVM->cfgm.s.pRoot)
1982 pNode->pVM->cfgm.s.pRoot = NULL;
1983 }
1984 if (pNode->pNext)
1985 pNode->pNext->pPrev = pNode->pPrev;
1986
1987 /*
1988 * Free ourselves.
1989 */
1990 cfgmR3FreeNodeOnly(pNode);
1991 }
1992}
1993
1994
1995/**
1996 * Removes a leaf.
1997 *
1998 * @param pNode Parent node.
1999 * @param pLeaf Leaf to remove.
2000 */
2001static void cfgmR3RemoveLeaf(PCFGMNODE pNode, PCFGMLEAF pLeaf)
2002{
2003 if (pNode && pLeaf)
2004 {
2005 /*
2006 * Unlink.
2007 */
2008 if (pLeaf->pPrev)
2009 pLeaf->pPrev->pNext = pLeaf->pNext;
2010 else
2011 pNode->pFirstLeaf = pLeaf->pNext;
2012 if (pLeaf->pNext)
2013 pLeaf->pNext->pPrev = pLeaf->pPrev;
2014
2015 /*
2016 * Free value and node.
2017 */
2018 cfgmR3FreeValue(pNode->pVM, pLeaf);
2019 pLeaf->pNext = NULL;
2020 pLeaf->pPrev = NULL;
2021 cfgmR3MemFree(pNode->pVM, pLeaf);
2022 }
2023}
2024
2025
2026/**
2027 * Frees whatever resources the leaf value is owning.
2028 *
2029 * Use this before assigning a new value to a leaf.
2030 * The caller must either free the leaf or assign a new value to it.
2031 *
2032 * @param pVM The cross context VM structure, if the tree
2033 * is associated with one.
2034 * @param pLeaf Pointer to the leaf which value should be free.
2035 */
2036static void cfgmR3FreeValue(PVM pVM, PCFGMLEAF pLeaf)
2037{
2038 if (pLeaf)
2039 {
2040 switch (pLeaf->enmType)
2041 {
2042 case CFGMVALUETYPE_BYTES:
2043 cfgmR3MemFree(pVM, pLeaf->Value.Bytes.pau8);
2044 pLeaf->Value.Bytes.pau8 = NULL;
2045 pLeaf->Value.Bytes.cb = 0;
2046 break;
2047
2048 case CFGMVALUETYPE_STRING:
2049 cfgmR3StrFree(pVM, pLeaf->Value.String.psz);
2050 pLeaf->Value.String.psz = NULL;
2051 pLeaf->Value.String.cb = 0;
2052 break;
2053
2054 case CFGMVALUETYPE_INTEGER:
2055 break;
2056 }
2057 pLeaf->enmType = (CFGMVALUETYPE)0;
2058 }
2059}
2060
2061/**
2062 * Destroys a tree created with CFGMR3CreateTree or CFGMR3DuplicateSubTree.
2063 *
2064 * @returns VBox status code.
2065 * @param pRoot The root node of the tree.
2066 */
2067VMMR3DECL(int) CFGMR3DestroyTree(PCFGMNODE pRoot)
2068{
2069 if (!pRoot)
2070 return VINF_SUCCESS;
2071 AssertReturn(!pRoot->pParent, VERR_INVALID_PARAMETER);
2072 AssertReturn(!pRoot->pVM || pRoot != pRoot->pVM->cfgm.s.pRoot, VERR_ACCESS_DENIED);
2073
2074 CFGMR3RemoveNode(pRoot);
2075 return VINF_SUCCESS;
2076}
2077
2078
2079/**
2080 * Inserts a new integer value.
2081 *
2082 * @returns VBox status code.
2083 * @param pNode Parent node.
2084 * @param pszName Value name.
2085 * @param u64Integer The value.
2086 */
2087VMMR3DECL(int) CFGMR3InsertInteger(PCFGMNODE pNode, const char *pszName, uint64_t u64Integer)
2088{
2089 PCFGMLEAF pLeaf;
2090 int rc = cfgmR3InsertLeaf(pNode, pszName, &pLeaf);
2091 if (RT_SUCCESS(rc))
2092 {
2093 pLeaf->enmType = CFGMVALUETYPE_INTEGER;
2094 pLeaf->Value.Integer.u64 = u64Integer;
2095 }
2096 return rc;
2097}
2098
2099
2100/**
2101 * Inserts a new string value. This variant expects that the caller know the length
2102 * of the string already so we can avoid calling strlen() here.
2103 *
2104 * @returns VBox status code.
2105 * @param pNode Parent node.
2106 * @param pszName Value name.
2107 * @param pszString The value. Must not be NULL.
2108 * @param cchString The length of the string excluding the
2109 * terminator.
2110 */
2111VMMR3DECL(int) CFGMR3InsertStringN(PCFGMNODE pNode, const char *pszName, const char *pszString, size_t cchString)
2112{
2113 Assert(RTStrNLen(pszString, cchString) == cchString);
2114
2115 int rc;
2116 if (pNode)
2117 {
2118 /*
2119 * Allocate string object first.
2120 */
2121 char *pszStringCopy = (char *)cfgmR3StrAlloc(pNode->pVM, MM_TAG_CFGM_STRING, cchString + 1);
2122 if (pszStringCopy)
2123 {
2124 memcpy(pszStringCopy, pszString, cchString);
2125 pszStringCopy[cchString] = '\0';
2126
2127 /*
2128 * Create value leaf and set it to string type.
2129 */
2130 PCFGMLEAF pLeaf;
2131 rc = cfgmR3InsertLeaf(pNode, pszName, &pLeaf);
2132 if (RT_SUCCESS(rc))
2133 {
2134 pLeaf->enmType = CFGMVALUETYPE_STRING;
2135 pLeaf->Value.String.psz = pszStringCopy;
2136 pLeaf->Value.String.cb = cchString + 1;
2137 }
2138 else
2139 cfgmR3StrFree(pNode->pVM, pszStringCopy);
2140 }
2141 else
2142 rc = VERR_NO_MEMORY;
2143 }
2144 else
2145 rc = VERR_CFGM_NO_PARENT;
2146
2147 return rc;
2148}
2149
2150
2151/**
2152 * Inserts a new string value. Calls strlen(pszString) internally; if you know the
2153 * length of the string, CFGMR3InsertStringLengthKnown() is faster.
2154 *
2155 * @returns VBox status code.
2156 * @param pNode Parent node.
2157 * @param pszName Value name.
2158 * @param pszString The value.
2159 */
2160VMMR3DECL(int) CFGMR3InsertString(PCFGMNODE pNode, const char *pszName, const char *pszString)
2161{
2162 return CFGMR3InsertStringN(pNode, pszName, pszString, strlen(pszString));
2163}
2164
2165
2166/**
2167 * Same as CFGMR3InsertString except the string value given in RTStrPrintfV
2168 * fashion.
2169 *
2170 * @returns VBox status code.
2171 * @param pNode Parent node.
2172 * @param pszName Value name.
2173 * @param pszFormat The value given as a format string.
2174 * @param va Argument to pszFormat.
2175 */
2176VMMR3DECL(int) CFGMR3InsertStringFV(PCFGMNODE pNode, const char *pszName, const char *pszFormat, va_list va)
2177{
2178 int rc;
2179 if (pNode)
2180 {
2181 /*
2182 * Allocate string object first.
2183 */
2184 char *pszString;
2185 if (!pNode->pVM)
2186 pszString = RTStrAPrintf2(pszFormat, va);
2187 else
2188 pszString = MMR3HeapAPrintfVU(pNode->pVM->pUVM, MM_TAG_CFGM_STRING, pszFormat, va);
2189 if (pszString)
2190 {
2191 /*
2192 * Create value leaf and set it to string type.
2193 */
2194 PCFGMLEAF pLeaf;
2195 rc = cfgmR3InsertLeaf(pNode, pszName, &pLeaf);
2196 if (RT_SUCCESS(rc))
2197 {
2198 pLeaf->enmType = CFGMVALUETYPE_STRING;
2199 pLeaf->Value.String.psz = pszString;
2200 pLeaf->Value.String.cb = strlen(pszString) + 1;
2201 }
2202 else
2203 cfgmR3StrFree(pNode->pVM, pszString);
2204 }
2205 else
2206 rc = VERR_NO_MEMORY;
2207 }
2208 else
2209 rc = VERR_CFGM_NO_PARENT;
2210
2211 return rc;
2212}
2213
2214
2215/**
2216 * Same as CFGMR3InsertString except the string value given in RTStrPrintf
2217 * fashion.
2218 *
2219 * @returns VBox status code.
2220 * @param pNode Parent node.
2221 * @param pszName Value name.
2222 * @param pszFormat The value given as a format string.
2223 * @param ... Argument to pszFormat.
2224 */
2225VMMR3DECL(int) CFGMR3InsertStringF(PCFGMNODE pNode, const char *pszName, const char *pszFormat, ...)
2226{
2227 va_list va;
2228 va_start(va, pszFormat);
2229 int rc = CFGMR3InsertStringFV(pNode, pszName, pszFormat, va);
2230 va_end(va);
2231 return rc;
2232}
2233
2234
2235/**
2236 * Same as CFGMR3InsertString except the string value given as a UTF-16 string.
2237 *
2238 * @returns VBox status code.
2239 * @param pNode Parent node.
2240 * @param pszName Value name.
2241 * @param pwszValue The string value (UTF-16).
2242 */
2243VMMR3DECL(int) CFGMR3InsertStringW(PCFGMNODE pNode, const char *pszName, PCRTUTF16 pwszValue)
2244{
2245 char *pszValue;
2246 int rc = RTUtf16ToUtf8(pwszValue, &pszValue);
2247 if (RT_SUCCESS(rc))
2248 {
2249 rc = CFGMR3InsertString(pNode, pszName, pszValue);
2250 RTStrFree(pszValue);
2251 }
2252 return rc;
2253}
2254
2255
2256/**
2257 * Inserts a new integer value.
2258 *
2259 * @returns VBox status code.
2260 * @param pNode Parent node.
2261 * @param pszName Value name.
2262 * @param pvBytes The value.
2263 * @param cbBytes The value size.
2264 */
2265VMMR3DECL(int) CFGMR3InsertBytes(PCFGMNODE pNode, const char *pszName, const void *pvBytes, size_t cbBytes)
2266{
2267 int rc;
2268 if (pNode)
2269 {
2270 if (cbBytes == (RTUINT)cbBytes)
2271 {
2272 /*
2273 * Allocate string object first.
2274 */
2275 void *pvCopy = cfgmR3MemAlloc(pNode->pVM, MM_TAG_CFGM_STRING, cbBytes);
2276 if (pvCopy || !cbBytes)
2277 {
2278 memcpy(pvCopy, pvBytes, cbBytes);
2279
2280 /*
2281 * Create value leaf and set it to string type.
2282 */
2283 PCFGMLEAF pLeaf;
2284 rc = cfgmR3InsertLeaf(pNode, pszName, &pLeaf);
2285 if (RT_SUCCESS(rc))
2286 {
2287 pLeaf->enmType = CFGMVALUETYPE_BYTES;
2288 pLeaf->Value.Bytes.cb = cbBytes;
2289 pLeaf->Value.Bytes.pau8 = (uint8_t *)pvCopy;
2290 }
2291 else
2292 cfgmR3MemFree(pNode->pVM, pvCopy);
2293 }
2294 else
2295 rc = VERR_NO_MEMORY;
2296 }
2297 else
2298 rc = VERR_OUT_OF_RANGE;
2299 }
2300 else
2301 rc = VERR_CFGM_NO_PARENT;
2302
2303 return rc;
2304}
2305
2306
2307/**
2308 * Make a copy of the specified value under the given node.
2309 *
2310 * @returns VBox status code.
2311 * @param pNode Parent node.
2312 * @param pValue The value to copy and insert.
2313 */
2314VMMR3DECL(int) CFGMR3InsertValue(PCFGMNODE pNode, PCFGMLEAF pValue)
2315{
2316 int rc;
2317 switch (pValue->enmType)
2318 {
2319 case CFGMVALUETYPE_INTEGER:
2320 rc = CFGMR3InsertInteger(pNode, pValue->szName, pValue->Value.Integer.u64);
2321 break;
2322
2323 case CFGMVALUETYPE_BYTES:
2324 rc = CFGMR3InsertBytes(pNode, pValue->szName, pValue->Value.Bytes.pau8, pValue->Value.Bytes.cb);
2325 break;
2326
2327 case CFGMVALUETYPE_STRING:
2328 rc = CFGMR3InsertStringN(pNode, pValue->szName, pValue->Value.String.psz, pValue->Value.String.cb - 1);
2329 break;
2330
2331 default:
2332 rc = VERR_CFGM_IPE_1;
2333 AssertMsgFailed(("Invalid value type %d\n", pValue->enmType));
2334 break;
2335 }
2336 return rc;
2337}
2338
2339
2340/**
2341 * Remove a value.
2342 *
2343 * @returns VBox status code.
2344 * @param pNode Parent node.
2345 * @param pszName Name of the new child node.
2346 */
2347VMMR3DECL(int) CFGMR3RemoveValue(PCFGMNODE pNode, const char *pszName)
2348{
2349 PCFGMLEAF pLeaf;
2350 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
2351 if (RT_SUCCESS(rc))
2352 cfgmR3RemoveLeaf(pNode, pLeaf);
2353 return rc;
2354}
2355
2356
2357
2358/*
2359 * -+- helper apis -+-
2360 */
2361
2362
2363/**
2364 * Query unsigned 64-bit integer value.
2365 *
2366 * @returns VBox status code.
2367 * @param pNode Which node to search for pszName in.
2368 * @param pszName Name of an integer value.
2369 * @param pu64 Where to store the integer value.
2370 */
2371VMMR3DECL(int) CFGMR3QueryU64(PCFGMNODE pNode, const char *pszName, uint64_t *pu64)
2372{
2373 return CFGMR3QueryInteger(pNode, pszName, pu64);
2374}
2375
2376
2377/**
2378 * Query unsigned 64-bit integer value with default.
2379 *
2380 * @returns VBox status code.
2381 * @param pNode Which node to search for pszName in.
2382 * @param pszName Name of an integer value.
2383 * @param pu64 Where to store the integer value. Set to default on failure.
2384 * @param u64Def The default value.
2385 */
2386VMMR3DECL(int) CFGMR3QueryU64Def(PCFGMNODE pNode, const char *pszName, uint64_t *pu64, uint64_t u64Def)
2387{
2388 return CFGMR3QueryIntegerDef(pNode, pszName, pu64, u64Def);
2389}
2390
2391
2392/**
2393 * Query signed 64-bit integer value.
2394 *
2395 * @returns VBox status code.
2396 * @param pNode Which node to search for pszName in.
2397 * @param pszName Name of an integer value.
2398 * @param pi64 Where to store the value.
2399 */
2400VMMR3DECL(int) CFGMR3QueryS64(PCFGMNODE pNode, const char *pszName, int64_t *pi64)
2401{
2402 uint64_t u64;
2403 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2404 if (RT_SUCCESS(rc))
2405 *pi64 = (int64_t)u64;
2406 return rc;
2407}
2408
2409
2410/**
2411 * Query signed 64-bit integer value with default.
2412 *
2413 * @returns VBox status code.
2414 * @param pNode Which node to search for pszName in.
2415 * @param pszName Name of an integer value.
2416 * @param pi64 Where to store the value. Set to default on failure.
2417 * @param i64Def The default value.
2418 */
2419VMMR3DECL(int) CFGMR3QueryS64Def(PCFGMNODE pNode, const char *pszName, int64_t *pi64, int64_t i64Def)
2420{
2421 uint64_t u64;
2422 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, i64Def);
2423 *pi64 = (int64_t)u64;
2424 return rc;
2425}
2426
2427
2428/**
2429 * Query unsigned 32-bit integer value.
2430 *
2431 * @returns VBox status code.
2432 * @param pNode Which node to search for pszName in.
2433 * @param pszName Name of an integer value.
2434 * @param pu32 Where to store the value.
2435 */
2436VMMR3DECL(int) CFGMR3QueryU32(PCFGMNODE pNode, const char *pszName, uint32_t *pu32)
2437{
2438 uint64_t u64;
2439 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2440 if (RT_SUCCESS(rc))
2441 {
2442 if (!(u64 & UINT64_C(0xffffffff00000000)))
2443 *pu32 = (uint32_t)u64;
2444 else
2445 rc = VERR_CFGM_INTEGER_TOO_BIG;
2446 }
2447 return rc;
2448}
2449
2450
2451/**
2452 * Query unsigned 32-bit integer value with default.
2453 *
2454 * @returns VBox status code.
2455 * @param pNode Which node to search for pszName in.
2456 * @param pszName Name of an integer value.
2457 * @param pu32 Where to store the value. Set to default on failure.
2458 * @param u32Def The default value.
2459 */
2460VMMR3DECL(int) CFGMR3QueryU32Def(PCFGMNODE pNode, const char *pszName, uint32_t *pu32, uint32_t u32Def)
2461{
2462 uint64_t u64;
2463 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, u32Def);
2464 if (RT_SUCCESS(rc))
2465 {
2466 if (!(u64 & UINT64_C(0xffffffff00000000)))
2467 *pu32 = (uint32_t)u64;
2468 else
2469 rc = VERR_CFGM_INTEGER_TOO_BIG;
2470 }
2471 if (RT_FAILURE(rc))
2472 *pu32 = u32Def;
2473 return rc;
2474}
2475
2476
2477/**
2478 * Query signed 32-bit integer value.
2479 *
2480 * @returns VBox status code.
2481 * @param pNode Which node to search for pszName in.
2482 * @param pszName Name of an integer value.
2483 * @param pi32 Where to store the value.
2484 */
2485VMMR3DECL(int) CFGMR3QueryS32(PCFGMNODE pNode, const char *pszName, int32_t *pi32)
2486{
2487 uint64_t u64;
2488 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2489 if (RT_SUCCESS(rc))
2490 {
2491 if ( !(u64 & UINT64_C(0xffffffff80000000))
2492 || (u64 & UINT64_C(0xffffffff80000000)) == UINT64_C(0xffffffff80000000))
2493 *pi32 = (int32_t)u64;
2494 else
2495 rc = VERR_CFGM_INTEGER_TOO_BIG;
2496 }
2497 return rc;
2498}
2499
2500
2501/**
2502 * Query signed 32-bit integer value with default.
2503 *
2504 * @returns VBox status code.
2505 * @param pNode Which node to search for pszName in.
2506 * @param pszName Name of an integer value.
2507 * @param pi32 Where to store the value. Set to default on failure.
2508 * @param i32Def The default value.
2509 */
2510VMMR3DECL(int) CFGMR3QueryS32Def(PCFGMNODE pNode, const char *pszName, int32_t *pi32, int32_t i32Def)
2511{
2512 uint64_t u64;
2513 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, i32Def);
2514 if (RT_SUCCESS(rc))
2515 {
2516 if ( !(u64 & UINT64_C(0xffffffff80000000))
2517 || (u64 & UINT64_C(0xffffffff80000000)) == UINT64_C(0xffffffff80000000))
2518 *pi32 = (int32_t)u64;
2519 else
2520 rc = VERR_CFGM_INTEGER_TOO_BIG;
2521 }
2522 if (RT_FAILURE(rc))
2523 *pi32 = i32Def;
2524 return rc;
2525}
2526
2527
2528/**
2529 * Query unsigned 16-bit integer value.
2530 *
2531 * @returns VBox status code.
2532 * @param pNode Which node to search for pszName in.
2533 * @param pszName Name of an integer value.
2534 * @param pu16 Where to store the value.
2535 */
2536VMMR3DECL(int) CFGMR3QueryU16(PCFGMNODE pNode, const char *pszName, uint16_t *pu16)
2537{
2538 uint64_t u64;
2539 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2540 if (RT_SUCCESS(rc))
2541 {
2542 if (!(u64 & UINT64_C(0xffffffffffff0000)))
2543 *pu16 = (int16_t)u64;
2544 else
2545 rc = VERR_CFGM_INTEGER_TOO_BIG;
2546 }
2547 return rc;
2548}
2549
2550
2551/**
2552 * Query unsigned 16-bit integer value with default.
2553 *
2554 * @returns VBox status code.
2555 * @param pNode Which node to search for pszName in.
2556 * @param pszName Name of an integer value.
2557 * @param pu16 Where to store the value. Set to default on failure.
2558 * @param u16Def The default value.
2559 */
2560VMMR3DECL(int) CFGMR3QueryU16Def(PCFGMNODE pNode, const char *pszName, uint16_t *pu16, uint16_t u16Def)
2561{
2562 uint64_t u64;
2563 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, u16Def);
2564 if (RT_SUCCESS(rc))
2565 {
2566 if (!(u64 & UINT64_C(0xffffffffffff0000)))
2567 *pu16 = (int16_t)u64;
2568 else
2569 rc = VERR_CFGM_INTEGER_TOO_BIG;
2570 }
2571 if (RT_FAILURE(rc))
2572 *pu16 = u16Def;
2573 return rc;
2574}
2575
2576
2577/**
2578 * Query signed 16-bit integer value.
2579 *
2580 * @returns VBox status code.
2581 * @param pNode Which node to search for pszName in.
2582 * @param pszName Name of an integer value.
2583 * @param pi16 Where to store the value.
2584 */
2585VMMR3DECL(int) CFGMR3QueryS16(PCFGMNODE pNode, const char *pszName, int16_t *pi16)
2586{
2587 uint64_t u64;
2588 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2589 if (RT_SUCCESS(rc))
2590 {
2591 if ( !(u64 & UINT64_C(0xffffffffffff8000))
2592 || (u64 & UINT64_C(0xffffffffffff8000)) == UINT64_C(0xffffffffffff8000))
2593 *pi16 = (int16_t)u64;
2594 else
2595 rc = VERR_CFGM_INTEGER_TOO_BIG;
2596 }
2597 return rc;
2598}
2599
2600
2601/**
2602 * Query signed 16-bit integer value with default.
2603 *
2604 * @returns VBox status code.
2605 * @param pNode Which node to search for pszName in.
2606 * @param pszName Name of an integer value.
2607 * @param pi16 Where to store the value. Set to default on failure.
2608 * @param i16Def The default value.
2609 */
2610VMMR3DECL(int) CFGMR3QueryS16Def(PCFGMNODE pNode, const char *pszName, int16_t *pi16, int16_t i16Def)
2611{
2612 uint64_t u64;
2613 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, i16Def);
2614 if (RT_SUCCESS(rc))
2615 {
2616 if ( !(u64 & UINT64_C(0xffffffffffff8000))
2617 || (u64 & UINT64_C(0xffffffffffff8000)) == UINT64_C(0xffffffffffff8000))
2618 *pi16 = (int16_t)u64;
2619 else
2620 rc = VERR_CFGM_INTEGER_TOO_BIG;
2621 }
2622 if (RT_FAILURE(rc))
2623 *pi16 = i16Def;
2624 return rc;
2625}
2626
2627
2628/**
2629 * Query unsigned 8-bit integer value.
2630 *
2631 * @returns VBox status code.
2632 * @param pNode Which node to search for pszName in.
2633 * @param pszName Name of an integer value.
2634 * @param pu8 Where to store the value.
2635 */
2636VMMR3DECL(int) CFGMR3QueryU8(PCFGMNODE pNode, const char *pszName, uint8_t *pu8)
2637{
2638 uint64_t u64;
2639 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2640 if (RT_SUCCESS(rc))
2641 {
2642 if (!(u64 & UINT64_C(0xffffffffffffff00)))
2643 *pu8 = (uint8_t)u64;
2644 else
2645 rc = VERR_CFGM_INTEGER_TOO_BIG;
2646 }
2647 return rc;
2648}
2649
2650
2651/**
2652 * Query unsigned 8-bit integer value with default.
2653 *
2654 * @returns VBox status code.
2655 * @param pNode Which node to search for pszName in.
2656 * @param pszName Name of an integer value.
2657 * @param pu8 Where to store the value. Set to default on failure.
2658 * @param u8Def The default value.
2659 */
2660VMMR3DECL(int) CFGMR3QueryU8Def(PCFGMNODE pNode, const char *pszName, uint8_t *pu8, uint8_t u8Def)
2661{
2662 uint64_t u64;
2663 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, u8Def);
2664 if (RT_SUCCESS(rc))
2665 {
2666 if (!(u64 & UINT64_C(0xffffffffffffff00)))
2667 *pu8 = (uint8_t)u64;
2668 else
2669 rc = VERR_CFGM_INTEGER_TOO_BIG;
2670 }
2671 if (RT_FAILURE(rc))
2672 *pu8 = u8Def;
2673 return rc;
2674}
2675
2676
2677/**
2678 * Query signed 8-bit integer value.
2679 *
2680 * @returns VBox status code.
2681 * @param pNode Which node to search for pszName in.
2682 * @param pszName Name of an integer value.
2683 * @param pi8 Where to store the value.
2684 */
2685VMMR3DECL(int) CFGMR3QueryS8(PCFGMNODE pNode, const char *pszName, int8_t *pi8)
2686{
2687 uint64_t u64;
2688 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2689 if (RT_SUCCESS(rc))
2690 {
2691 if ( !(u64 & UINT64_C(0xffffffffffffff80))
2692 || (u64 & UINT64_C(0xffffffffffffff80)) == UINT64_C(0xffffffffffffff80))
2693 *pi8 = (int8_t)u64;
2694 else
2695 rc = VERR_CFGM_INTEGER_TOO_BIG;
2696 }
2697 return rc;
2698}
2699
2700
2701/**
2702 * Query signed 8-bit integer value with default.
2703 *
2704 * @returns VBox status code.
2705 * @param pNode Which node to search for pszName in.
2706 * @param pszName Name of an integer value.
2707 * @param pi8 Where to store the value. Set to default on failure.
2708 * @param i8Def The default value.
2709 */
2710VMMR3DECL(int) CFGMR3QueryS8Def(PCFGMNODE pNode, const char *pszName, int8_t *pi8, int8_t i8Def)
2711{
2712 uint64_t u64;
2713 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, i8Def);
2714 if (RT_SUCCESS(rc))
2715 {
2716 if ( !(u64 & UINT64_C(0xffffffffffffff80))
2717 || (u64 & UINT64_C(0xffffffffffffff80)) == UINT64_C(0xffffffffffffff80))
2718 *pi8 = (int8_t)u64;
2719 else
2720 rc = VERR_CFGM_INTEGER_TOO_BIG;
2721 }
2722 if (RT_FAILURE(rc))
2723 *pi8 = i8Def;
2724 return rc;
2725}
2726
2727
2728/**
2729 * Query boolean integer value.
2730 *
2731 * @returns VBox status code.
2732 * @param pNode Which node to search for pszName in.
2733 * @param pszName Name of an integer value.
2734 * @param pf Where to store the value.
2735 * @remark This function will interpret any non-zero value as true.
2736 */
2737VMMR3DECL(int) CFGMR3QueryBool(PCFGMNODE pNode, const char *pszName, bool *pf)
2738{
2739 uint64_t u64;
2740 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2741 if (RT_SUCCESS(rc))
2742 *pf = u64 ? true : false;
2743 return rc;
2744}
2745
2746
2747/**
2748 * Query boolean integer value with default.
2749 *
2750 * @returns VBox status code.
2751 * @param pNode Which node to search for pszName in.
2752 * @param pszName Name of an integer value.
2753 * @param pf Where to store the value. Set to default on failure.
2754 * @param fDef The default value.
2755 * @remark This function will interpret any non-zero value as true.
2756 */
2757VMMR3DECL(int) CFGMR3QueryBoolDef(PCFGMNODE pNode, const char *pszName, bool *pf, bool fDef)
2758{
2759 uint64_t u64;
2760 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, fDef);
2761 *pf = u64 ? true : false;
2762 return rc;
2763}
2764
2765
2766/**
2767 * Query I/O port address value.
2768 *
2769 * @returns VBox status code.
2770 * @param pNode Which node to search for pszName in.
2771 * @param pszName Name of an integer value.
2772 * @param pPort Where to store the value.
2773 */
2774VMMR3DECL(int) CFGMR3QueryPort(PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort)
2775{
2776 AssertCompileSize(RTIOPORT, 2);
2777 return CFGMR3QueryU16(pNode, pszName, pPort);
2778}
2779
2780
2781/**
2782 * Query I/O port address value with default.
2783 *
2784 * @returns VBox status code.
2785 * @param pNode Which node to search for pszName in.
2786 * @param pszName Name of an integer value.
2787 * @param pPort Where to store the value. Set to default on failure.
2788 * @param PortDef The default value.
2789 */
2790VMMR3DECL(int) CFGMR3QueryPortDef(PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort, RTIOPORT PortDef)
2791{
2792 AssertCompileSize(RTIOPORT, 2);
2793 return CFGMR3QueryU16Def(pNode, pszName, pPort, PortDef);
2794}
2795
2796
2797/**
2798 * Query unsigned int address value.
2799 *
2800 * @returns VBox status code.
2801 * @param pNode Which node to search for pszName in.
2802 * @param pszName Name of an integer value.
2803 * @param pu Where to store the value.
2804 */
2805VMMR3DECL(int) CFGMR3QueryUInt(PCFGMNODE pNode, const char *pszName, unsigned int *pu)
2806{
2807 AssertCompileSize(unsigned int, 4);
2808 return CFGMR3QueryU32(pNode, pszName, (uint32_t *)pu);
2809}
2810
2811
2812/**
2813 * Query unsigned int address value with default.
2814 *
2815 * @returns VBox status code.
2816 * @param pNode Which node to search for pszName in.
2817 * @param pszName Name of an integer value.
2818 * @param pu Where to store the value. Set to default on failure.
2819 * @param uDef The default value.
2820 */
2821VMMR3DECL(int) CFGMR3QueryUIntDef(PCFGMNODE pNode, const char *pszName, unsigned int *pu, unsigned int uDef)
2822{
2823 AssertCompileSize(unsigned int, 4);
2824 return CFGMR3QueryU32Def(pNode, pszName, (uint32_t *)pu, uDef);
2825}
2826
2827
2828/**
2829 * Query signed int address value.
2830 *
2831 * @returns VBox status code.
2832 * @param pNode Which node to search for pszName in.
2833 * @param pszName Name of an integer value.
2834 * @param pi Where to store the value.
2835 */
2836VMMR3DECL(int) CFGMR3QuerySInt(PCFGMNODE pNode, const char *pszName, signed int *pi)
2837{
2838 AssertCompileSize(signed int, 4);
2839 return CFGMR3QueryS32(pNode, pszName, (int32_t *)pi);
2840}
2841
2842
2843/**
2844 * Query unsigned int address value with default.
2845 *
2846 * @returns VBox status code.
2847 * @param pNode Which node to search for pszName in.
2848 * @param pszName Name of an integer value.
2849 * @param pi Where to store the value. Set to default on failure.
2850 * @param iDef The default value.
2851 */
2852VMMR3DECL(int) CFGMR3QuerySIntDef(PCFGMNODE pNode, const char *pszName, signed int *pi, signed int iDef)
2853{
2854 AssertCompileSize(signed int, 4);
2855 return CFGMR3QueryS32Def(pNode, pszName, (int32_t *)pi, iDef);
2856}
2857
2858
2859/**
2860 * Query pointer integer value.
2861 *
2862 * @returns VBox status code.
2863 * @param pNode Which node to search for pszName in.
2864 * @param pszName Name of an integer value.
2865 * @param ppv Where to store the value.
2866 */
2867VMMR3DECL(int) CFGMR3QueryPtr(PCFGMNODE pNode, const char *pszName, void **ppv)
2868{
2869 uint64_t u64;
2870 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2871 if (RT_SUCCESS(rc))
2872 {
2873 uintptr_t u = (uintptr_t)u64;
2874 if (u64 == u)
2875 *ppv = (void *)u;
2876 else
2877 rc = VERR_CFGM_INTEGER_TOO_BIG;
2878 }
2879 return rc;
2880}
2881
2882
2883/**
2884 * Query pointer integer value with default.
2885 *
2886 * @returns VBox status code.
2887 * @param pNode Which node to search for pszName in.
2888 * @param pszName Name of an integer value.
2889 * @param ppv Where to store the value. Set to default on failure.
2890 * @param pvDef The default value.
2891 */
2892VMMR3DECL(int) CFGMR3QueryPtrDef(PCFGMNODE pNode, const char *pszName, void **ppv, void *pvDef)
2893{
2894 uint64_t u64;
2895 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, (uintptr_t)pvDef);
2896 if (RT_SUCCESS(rc))
2897 {
2898 uintptr_t u = (uintptr_t)u64;
2899 if (u64 == u)
2900 *ppv = (void *)u;
2901 else
2902 rc = VERR_CFGM_INTEGER_TOO_BIG;
2903 }
2904 if (RT_FAILURE(rc))
2905 *ppv = pvDef;
2906 return rc;
2907}
2908
2909
2910/**
2911 * Query Guest Context pointer integer value.
2912 *
2913 * @returns VBox status code.
2914 * @param pNode Which node to search for pszName in.
2915 * @param pszName Name of an integer value.
2916 * @param pGCPtr Where to store the value.
2917 */
2918VMMR3DECL(int) CFGMR3QueryGCPtr(PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr)
2919{
2920 uint64_t u64;
2921 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2922 if (RT_SUCCESS(rc))
2923 {
2924 RTGCPTR u = (RTGCPTR)u64;
2925 if (u64 == u)
2926 *pGCPtr = u;
2927 else
2928 rc = VERR_CFGM_INTEGER_TOO_BIG;
2929 }
2930 return rc;
2931}
2932
2933
2934/**
2935 * Query Guest Context pointer integer value with default.
2936 *
2937 * @returns VBox status code.
2938 * @param pNode Which node to search for pszName in.
2939 * @param pszName Name of an integer value.
2940 * @param pGCPtr Where to store the value. Set to default on failure.
2941 * @param GCPtrDef The default value.
2942 */
2943VMMR3DECL(int) CFGMR3QueryGCPtrDef(PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr, RTGCPTR GCPtrDef)
2944{
2945 uint64_t u64;
2946 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, GCPtrDef);
2947 if (RT_SUCCESS(rc))
2948 {
2949 RTGCPTR u = (RTGCPTR)u64;
2950 if (u64 == u)
2951 *pGCPtr = u;
2952 else
2953 rc = VERR_CFGM_INTEGER_TOO_BIG;
2954 }
2955 if (RT_FAILURE(rc))
2956 *pGCPtr = GCPtrDef;
2957 return rc;
2958}
2959
2960
2961/**
2962 * Query Guest Context unsigned pointer value.
2963 *
2964 * @returns VBox status code.
2965 * @param pNode Which node to search for pszName in.
2966 * @param pszName Name of an integer value.
2967 * @param pGCPtr Where to store the value.
2968 */
2969VMMR3DECL(int) CFGMR3QueryGCPtrU(PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr)
2970{
2971 uint64_t u64;
2972 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
2973 if (RT_SUCCESS(rc))
2974 {
2975 RTGCUINTPTR u = (RTGCUINTPTR)u64;
2976 if (u64 == u)
2977 *pGCPtr = u;
2978 else
2979 rc = VERR_CFGM_INTEGER_TOO_BIG;
2980 }
2981 return rc;
2982}
2983
2984
2985/**
2986 * Query Guest Context unsigned pointer value with default.
2987 *
2988 * @returns VBox status code.
2989 * @param pNode Which node to search for pszName in.
2990 * @param pszName Name of an integer value.
2991 * @param pGCPtr Where to store the value. Set to default on failure.
2992 * @param GCPtrDef The default value.
2993 */
2994VMMR3DECL(int) CFGMR3QueryGCPtrUDef(PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr, RTGCUINTPTR GCPtrDef)
2995{
2996 uint64_t u64;
2997 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, GCPtrDef);
2998 if (RT_SUCCESS(rc))
2999 {
3000 RTGCUINTPTR u = (RTGCUINTPTR)u64;
3001 if (u64 == u)
3002 *pGCPtr = u;
3003 else
3004 rc = VERR_CFGM_INTEGER_TOO_BIG;
3005 }
3006 if (RT_FAILURE(rc))
3007 *pGCPtr = GCPtrDef;
3008 return rc;
3009}
3010
3011
3012/**
3013 * Query Guest Context signed pointer value.
3014 *
3015 * @returns VBox status code.
3016 * @param pNode Which node to search for pszName in.
3017 * @param pszName Name of an integer value.
3018 * @param pGCPtr Where to store the value.
3019 */
3020VMMR3DECL(int) CFGMR3QueryGCPtrS(PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr)
3021{
3022 uint64_t u64;
3023 int rc = CFGMR3QueryInteger(pNode, pszName, &u64);
3024 if (RT_SUCCESS(rc))
3025 {
3026 RTGCINTPTR u = (RTGCINTPTR)u64;
3027 if (u64 == (uint64_t)u)
3028 *pGCPtr = u;
3029 else
3030 rc = VERR_CFGM_INTEGER_TOO_BIG;
3031 }
3032 return rc;
3033}
3034
3035
3036/**
3037 * Query Guest Context signed pointer value with default.
3038 *
3039 * @returns VBox status code.
3040 * @param pNode Which node to search for pszName in.
3041 * @param pszName Name of an integer value.
3042 * @param pGCPtr Where to store the value. Set to default on failure.
3043 * @param GCPtrDef The default value.
3044 */
3045VMMR3DECL(int) CFGMR3QueryGCPtrSDef(PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr, RTGCINTPTR GCPtrDef)
3046{
3047 uint64_t u64;
3048 int rc = CFGMR3QueryIntegerDef(pNode, pszName, &u64, GCPtrDef);
3049 if (RT_SUCCESS(rc))
3050 {
3051 RTGCINTPTR u = (RTGCINTPTR)u64;
3052 if (u64 == (uint64_t)u)
3053 *pGCPtr = u;
3054 else
3055 rc = VERR_CFGM_INTEGER_TOO_BIG;
3056 }
3057 if (RT_FAILURE(rc))
3058 *pGCPtr = GCPtrDef;
3059 return rc;
3060}
3061
3062
3063/**
3064 * Query zero terminated character value storing it in a
3065 * buffer allocated from the MM heap.
3066 *
3067 * @returns VBox status code.
3068 * @param pNode Which node to search for pszName in.
3069 * @param pszName Value name. This value must be of zero terminated character string type.
3070 * @param ppszString Where to store the string pointer.
3071 * Free this using MMR3HeapFree() (or RTStrFree if not
3072 * associated with a pUVM - see CFGMR3CreateTree).
3073 */
3074VMMR3DECL(int) CFGMR3QueryStringAlloc(PCFGMNODE pNode, const char *pszName, char **ppszString)
3075{
3076 size_t cbString;
3077 int rc = CFGMR3QuerySize(pNode, pszName, &cbString);
3078 if (RT_SUCCESS(rc))
3079 {
3080 char *pszString = cfgmR3StrAlloc(pNode->pVM, MM_TAG_CFGM_USER, cbString);
3081 if (pszString)
3082 {
3083 rc = CFGMR3QueryString(pNode, pszName, pszString, cbString);
3084 if (RT_SUCCESS(rc))
3085 *ppszString = pszString;
3086 else
3087 cfgmR3StrFree(pNode->pVM, pszString);
3088 }
3089 else
3090 rc = VERR_NO_MEMORY;
3091 }
3092 return rc;
3093}
3094
3095
3096/**
3097 * Query zero terminated character value storing it in a
3098 * buffer allocated from the MM heap.
3099 *
3100 * @returns VBox status code.
3101 * @param pNode Which node to search for pszName in. This cannot be
3102 * NULL if @a pszDef is not NULL, because we need
3103 * somewhere way to get to the VM in order to call
3104 * MMR3HeapStrDup.
3105 * @param pszName Value name. This value must be of zero terminated character string type.
3106 * @param ppszString Where to store the string pointer. Not set on failure.
3107 * Free this using MMR3HeapFree() (or RTStrFree if not
3108 * associated with a pUVM - see CFGMR3CreateTree).
3109 * @param pszDef The default return value. This can be NULL.
3110 */
3111VMMR3DECL(int) CFGMR3QueryStringAllocDef(PCFGMNODE pNode, const char *pszName, char **ppszString, const char *pszDef)
3112{
3113 Assert(pNode || !pszDef); /* We need pVM if we need to duplicate the string later. */
3114
3115 /*
3116 * (Don't call CFGMR3QuerySize and CFGMR3QueryStringDef here as the latter
3117 * cannot handle pszDef being NULL.)
3118 */
3119 PCFGMLEAF pLeaf;
3120 int rc = cfgmR3ResolveLeaf(pNode, pszName, &pLeaf);
3121 if (RT_SUCCESS(rc))
3122 {
3123 if (pLeaf->enmType == CFGMVALUETYPE_STRING)
3124 {
3125 size_t const cbSrc = pLeaf->Value.String.cb;
3126 char *pszString = cfgmR3StrAlloc(pNode->pVM, MM_TAG_CFGM_USER, cbSrc);
3127 if (pszString)
3128 {
3129 memcpy(pszString, pLeaf->Value.String.psz, cbSrc);
3130 *ppszString = pszString;
3131 }
3132 else
3133 rc = VERR_NO_MEMORY;
3134 }
3135 else
3136 rc = VERR_CFGM_NOT_STRING;
3137 }
3138 if (RT_FAILURE(rc))
3139 {
3140 if (!pszDef)
3141 *ppszString = NULL;
3142 else
3143 {
3144 size_t const cbDef = strlen(pszDef) + 1;
3145 *ppszString = cfgmR3StrAlloc(pNode->pVM, MM_TAG_CFGM_USER, cbDef);
3146 memcpy(*ppszString, pszDef, cbDef);
3147 }
3148 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
3149 rc = VINF_SUCCESS;
3150 }
3151
3152 return rc;
3153}
3154
3155
3156/**
3157 * Dumps the configuration (sub)tree to the release log.
3158 *
3159 * @param pRoot The root node of the dump.
3160 */
3161VMMR3DECL(void) CFGMR3Dump(PCFGMNODE pRoot)
3162{
3163 bool fOldBuffered = RTLogRelSetBuffering(true /*fBuffered*/);
3164 LogRel(("************************* CFGM dump *************************\n"));
3165 cfgmR3Dump(pRoot, 0, DBGFR3InfoLogRelHlp());
3166 LogRel(("********************* End of CFGM dump **********************\n"));
3167 RTLogRelSetBuffering(fOldBuffered);
3168}
3169
3170
3171/**
3172 * Info handler, internal version.
3173 *
3174 * @param pVM The cross context VM structure.
3175 * @param pHlp Callback functions for doing output.
3176 * @param pszArgs Argument string. Optional and specific to the handler.
3177 */
3178static DECLCALLBACK(void) cfgmR3Info(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs)
3179{
3180 /*
3181 * Figure where to start.
3182 */
3183 PCFGMNODE pRoot = pVM->cfgm.s.pRoot;
3184 if (pszArgs && *pszArgs)
3185 {
3186 int rc = cfgmR3ResolveNode(pRoot, pszArgs, &pRoot);
3187 if (RT_FAILURE(rc))
3188 {
3189 pHlp->pfnPrintf(pHlp, "Failed to resolve CFGM path '%s', %Rrc", pszArgs, rc);
3190 return;
3191 }
3192 }
3193
3194 /*
3195 * Dump the specified tree.
3196 */
3197 pHlp->pfnPrintf(pHlp, "pRoot=%p:{", pRoot);
3198 cfgmR3DumpPath(pRoot, pHlp);
3199 pHlp->pfnPrintf(pHlp, "}\n");
3200 cfgmR3Dump(pRoot, 0, pHlp);
3201}
3202
3203
3204/**
3205 * Recursively prints a path name.
3206 */
3207static void cfgmR3DumpPath(PCFGMNODE pNode, PCDBGFINFOHLP pHlp)
3208{
3209 if (pNode->pParent)
3210 cfgmR3DumpPath(pNode->pParent, pHlp);
3211 pHlp->pfnPrintf(pHlp, "%s/", pNode->szName);
3212}
3213
3214
3215/**
3216 * Dumps a branch of a tree.
3217 */
3218static void cfgmR3Dump(PCFGMNODE pRoot, unsigned iLevel, PCDBGFINFOHLP pHlp)
3219{
3220 /*
3221 * Path.
3222 */
3223 pHlp->pfnPrintf(pHlp, "[");
3224 cfgmR3DumpPath(pRoot, pHlp);
3225 pHlp->pfnPrintf(pHlp, "] (level %d)%s\n", iLevel, pRoot->fRestrictedRoot ? " (restricted root)" : "");
3226
3227 /*
3228 * Values.
3229 */
3230 PCFGMLEAF pLeaf;
3231 size_t cchMax = 0;
3232 for (pLeaf = CFGMR3GetFirstValue(pRoot); pLeaf; pLeaf = CFGMR3GetNextValue(pLeaf))
3233 cchMax = RT_MAX(cchMax, pLeaf->cchName);
3234 for (pLeaf = CFGMR3GetFirstValue(pRoot); pLeaf; pLeaf = CFGMR3GetNextValue(pLeaf))
3235 {
3236 switch (CFGMR3GetValueType(pLeaf))
3237 {
3238 case CFGMVALUETYPE_INTEGER:
3239 {
3240 pHlp->pfnPrintf(pHlp, " %-*s <integer> = %#018llx (%'lld", (int)cchMax, pLeaf->szName, pLeaf->Value.Integer.u64, pLeaf->Value.Integer.u64);
3241 if ( ( pLeaf->cchName >= 4
3242 && !RTStrCmp(&pLeaf->szName[pLeaf->cchName - 4], "Size"))
3243 || ( pLeaf->cchName >= 2
3244 && !RTStrNCmp(pLeaf->szName, "cb", 2)) )
3245 {
3246 if (pLeaf->Value.Integer.u64 > _2G)
3247 pHlp->pfnPrintf(pHlp, ", %'lld GB", pLeaf->Value.Integer.u64 / _1G);
3248 else if (pLeaf->Value.Integer.u64 > _2M)
3249 pHlp->pfnPrintf(pHlp, ", %'lld MB", pLeaf->Value.Integer.u64 / _1M);
3250 else if (pLeaf->Value.Integer.u64 > _2K)
3251 pHlp->pfnPrintf(pHlp, ", %'lld KB", pLeaf->Value.Integer.u64 / _1K);
3252 }
3253 pHlp->pfnPrintf(pHlp, ")\n");
3254 break;
3255 }
3256
3257 case CFGMVALUETYPE_STRING:
3258 pHlp->pfnPrintf(pHlp, " %-*s <string> = \"%s\" (cb=%zu)\n", (int)cchMax, pLeaf->szName, pLeaf->Value.String.psz, pLeaf->Value.String.cb);
3259 break;
3260
3261 case CFGMVALUETYPE_BYTES:
3262 pHlp->pfnPrintf(pHlp, " %-*s <bytes> = \"%.*Rhxs\" (cb=%zu)\n", (int)cchMax, pLeaf->szName, pLeaf->Value.Bytes.cb, pLeaf->Value.Bytes.pau8, pLeaf->Value.Bytes.cb);
3263 break;
3264
3265 default:
3266 AssertMsgFailed(("bad leaf!\n"));
3267 break;
3268 }
3269 }
3270 pHlp->pfnPrintf(pHlp, "\n");
3271
3272 /*
3273 * Children.
3274 */
3275 for (PCFGMNODE pChild = CFGMR3GetFirstChild(pRoot); pChild; pChild = CFGMR3GetNextChild(pChild))
3276 {
3277 Assert(pChild->pNext != pChild);
3278 Assert(pChild->pPrev != pChild);
3279 Assert(pChild->pPrev != pChild->pNext || !pChild->pPrev);
3280 Assert(pChild->pFirstChild != pChild);
3281 Assert(pChild->pParent == pRoot);
3282 cfgmR3Dump(pChild, iLevel + 1, pHlp);
3283 }
3284}
3285
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette