1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// ZBI Processing Library
6// This library is meant to be a generic processing library for the ZBI format
7// defined in system/public/zircon/boot/image.h
8//
9// This library has several features:
10// (1) Zero allocations / Exceptions
11//     Safe to use at early boot time if necessary or in other situations where
12//     allocation may not be desirable.
13// (2) Trivially Portable
14//     This library attempts to limit the number of depedencies on the
15//     environment:
16//      + A C99 compliant compiler
17//      + Support for sized integer types (uint8_t and uint32_t)
18//      + zircon/boot/image.h
19//      + Implementations of memcmp and memcpy
20// (3) Tested
21//     Tests for this library can be found at zircon/system/utest/zbi/*
22
23#pragma once
24
25#include <stddef.h>
26#include <zircon/boot/image.h>
27#include <zircon/compiler.h>
28
29__BEGIN_CDECLS
30
31typedef enum zbi_result {
32    ZBI_RESULT_OK,
33
34    ZBI_RESULT_ERROR,
35    ZBI_RESULT_BAD_TYPE,
36    ZBI_RESULT_BAD_MAGIC,
37    ZBI_RESULT_BAD_VERSION,
38    ZBI_RESULT_BAD_CRC,
39    ZBI_RESULT_ERR_TRUNCATED,
40
41    ZBI_RESULT_TOO_BIG,
42
43    ZBI_RESULT_INCOMPLETE_KERNEL,
44    ZBI_RESULT_INCOMPLETE_BOOTFS,
45} zbi_result_t;
46
47typedef zbi_result_t (*zbi_foreach_cb_t)(zbi_header_t* hdr,
48                                         void* payload,
49                                         void* cookie);
50
51// Checks the integrity of the underlying ZBI.
52// If err is not null and an error is found, err will point to the ZBI entry
53// in which a problem was found the return value will attempt to specify the
54// nature of the error.
55zbi_result_t zbi_check(const void* base, zbi_header_t** err);
56
57// Same, but also diagnose ZBI_RESULT_INCOMPLETE_* result codes if the
58// ZBI is not a valid complete ZBI for the host platform.
59zbi_result_t zbi_check_complete(const void* base, zbi_header_t** err);
60
61// Call `cb` with a pointer to the header and payload of each ZBI item
62// excluding the root ZBI_TYPE_CONTAINER.
63//
64// If any of the callbacks return anything other than ZBI_RESULT_OK, iteration
65// will cease and zbi_for_each will short circuit and return with the error
66// result. If all items were successfully processed, ForEach will return
67// ZBI_RESULT_OK.
68//
69// cookie will be passed transparently to each cb and is available for the
70// client to pass data back from each of the callbacks.
71zbi_result_t zbi_for_each(const void* base, const zbi_foreach_cb_t cb,
72                          void* cookie);
73
74// Creates a new ZBI section and appends it to the end of the ZBI pointed to by
75// `base`. Assumes that the buffer at `base` has a length of `capacity` which
76// is likely longer than the size of the ZBI at `base`.
77//
78// The new section will be aligned to the ZBI alignment boundary. Any padding
79// added to achieve this alignment will be zero-filled.
80//
81// The caller need not set the ZBI_FLAG_VERSION field of the flags field as it
82// will be set unconditionally for the new section.
83//
84// CRC computation is not currently supported and setting the ZBI_FLAG_CRC32
85// flag will yield an error.
86zbi_result_t zbi_append_section(void* base, size_t capacity,
87                                uint32_t section_length, uint32_t type,
88                                uint32_t extra, uint32_t flags,
89                                const void* payload);
90
91
92// Create a new ZBI section and returns a pointer to the payload.
93zbi_result_t zbi_create_section(void* base, size_t capacity,
94                                uint32_t section_length, uint32_t type,
95                                uint32_t extra, uint32_t flags,
96                                void** payload);
97
98
99__END_CDECLS
100