system/ulib/libzbi/include/libzbi/zbi.h

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// ZBI Processing Library
// This library is meant to be a generic processing library for the ZBI format
// defined in system/public/zircon/boot/image.h
//
// This library has several features:
// (1) Zero allocations / Exceptions
//     Safe to use at early boot time if necessary or in other situations where
//     allocation may not be desirable.
// (2) Trivially Portable
//     This library attempts to limit the number of dependencies on the
//     environment:
//      + A C99 compliant compiler
//      + Support for sized integer types (uint8_t and uint32_t)
//      + zircon/boot/image.h
//      + Implementations of memcmp and memcpy
// (3) Tested
//     Tests for this library can be found at zircon/system/utest/zbi/*

#pragma once

#include <stddef.h>
#include <zircon/boot/image.h>
#include <zircon/compiler.h>

__BEGIN_CDECLS

typedef enum zbi_result {
    ZBI_RESULT_OK,

    ZBI_RESULT_ERROR,
    ZBI_RESULT_BAD_TYPE,
    ZBI_RESULT_BAD_MAGIC,
    ZBI_RESULT_BAD_VERSION,
    ZBI_RESULT_BAD_CRC,
    ZBI_RESULT_ERR_TRUNCATED,

    ZBI_RESULT_TOO_BIG,

    ZBI_RESULT_INCOMPLETE_KERNEL,
    ZBI_RESULT_INCOMPLETE_BOOTFS,
} zbi_result_t;

typedef zbi_result_t (*zbi_foreach_cb_t)(zbi_header_t* hdr,
                                         void* payload,
                                         void* cookie);

// Creates an empty ZBI container in buffer.
zbi_result_t zbi_init(void* buffer, size_t length);

// Checks the integrity of the underlying ZBI.
// If err is not null and an error is found, err will point to the ZBI entry
// in which a problem was found the return value will attempt to specify the
// nature of the error.
zbi_result_t zbi_check(const void* base, zbi_header_t** err);

// Same, but also diagnose ZBI_RESULT_INCOMPLETE_* result codes if the
// ZBI is not a valid complete ZBI for the host platform.
zbi_result_t zbi_check_complete(const void* base, zbi_header_t** err);

// Call `cb` with a pointer to the header and payload of each ZBI item
// excluding the root ZBI_TYPE_CONTAINER.
//
// If any of the callbacks return anything other than ZBI_RESULT_OK, iteration
// will cease and zbi_for_each will short circuit and return with the error
// result. If all items were successfully processed, ForEach will return
// ZBI_RESULT_OK.
//
// cookie will be passed transparently to each cb and is available for the
// client to pass data back from each of the callbacks.
zbi_result_t zbi_for_each(const void* base, const zbi_foreach_cb_t cb,
                          void* cookie);

// Creates a new ZBI section and appends it to the end of the ZBI pointed to by
// `base`. Assumes that the buffer at `base` has a length of `capacity` which
// is likely longer than the size of the ZBI at `base`.
//
// The new section will be aligned to the ZBI alignment boundary. Any padding
// added to achieve this alignment will be zero-filled.
//
// The caller need not set the ZBI_FLAG_VERSION field of the flags field as it
// will be set unconditionally for the new section.
//
// CRC computation is not currently supported and setting the ZBI_FLAG_CRC32
// flag will yield an error.
zbi_result_t zbi_append_section(void* base, size_t capacity,
                                uint32_t section_length, uint32_t type,
                                uint32_t extra, uint32_t flags,
                                const void* payload);

// Create a new ZBI section and returns a pointer to the payload.
zbi_result_t zbi_create_section(void* base, size_t capacity,
                                uint32_t section_length, uint32_t type,
                                uint32_t extra, uint32_t flags,
                                void** payload);

// Extend dst by appending src to the end of it.
zbi_result_t zbi_extend(void* dst, size_t capacity, const void* src);

__END_CDECLS