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