1 /*
2  * Copyright (c) 2022 Google Inc. All rights reserved
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining
5  * a copy of this software and associated documentation files
6  * (the "Software"), to deal in the Software without restriction,
7  * including without limitation the rights to use, copy, modify, merge,
8  * publish, distribute, sublicense, and/or sell copies of the Software,
9  * and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be
13  * included in all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22  */
23 
24 #pragma once
25 #include <assert.h>
26 #include <lk/compiler.h>
27 #include <stdint.h>
28 
29 __BEGIN_CDECLS
30 
31 struct dtb_embedded_iterator;
32 
33 /**
34  * dtb_embedded_iterator_new() - Create an iterator for the embedded dtbs
35  * @piter:     Pointer to a pointer to store the allocated iterator.
36  *
37  * Return:    %NO_ERROR in case of success, %ERR_NO_MEMORY or another error code
38  *            otherwise. It's the caller's responsibility to free the iterator
39  *            with dtb_embedded_iterator_free.
40  */
41 int dtb_embedded_iterator_new(struct dtb_embedded_iterator** piter);
42 
43 /**
44  * dtb_embedded_iterator_free() - Free an embedded dtb iterator
45  *
46  * @piter:    Pointer to the iterator to free.
47  *
48  * The function will set @piter to %NULL to prevent double frees.
49  */
50 void dtb_embedded_iterator_free(struct dtb_embedded_iterator** piter);
51 
52 /**
53  * dtb_embedded_iterator_reset() - Reset an iterator to the first embedded dtb
54  *
55  * @iter:    The pointer to the iterator to reset
56  */
57 void dtb_embedded_iterator_reset(struct dtb_embedded_iterator* iter);
58 
59 /**
60  * dtb_embedded_iterator_next() - Advance an iterator to the next embedded dtb
61  *
62  * @iter:         The pointer to the iterator to advance
63  * @dtb:          Out parameter for the next dtb. This pointer's lifetime is
64  *                unrelated to the iterator's and is always valid.
65  * @dtb_size:     Out parameter for the next dtb's size
66  *
67  * Return:        NO_ERROR if the iterator is advanced to the next dtb.
68  *                ERR_OUT_OF_RANGE if the iterator initially points to the last
69  *                dtb. All other errors indicate invalid embedded dtbs or
70  *                arguments.
71  */
72 int dtb_embedded_iterator_next(struct dtb_embedded_iterator* iter,
73                                const void** dtb,
74                                size_t* dtb_size);
75 
76 __END_CDECLS
77