// Copyright 2019 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.
library fuchsia.boot;

using zx;

const MAX_FILE_NAME_LENGTH uint8 = 255;

/// Protocol for retrieving boot item payloads.
@discoverable
protocol Items {
    /// Get a `payload` for a boot item of `type` and `extra`.
    /// NOTE: We return the `length` of the item, as VMOs must be page-aligned.
    ///
    /// TODO: Refactor API: fxbug.dev/34597
    ///
    /// For a list of `type`s, refer to <zircon/boot/image.h>.
    /// For a list of `extra`s, refer to <zircon/boot/driver-config.h>.
    Get(struct {
        type uint32;
        extra uint32;
    }) -> (resource struct {
        payload zx.handle:<VMO, optional>;
        length uint32;
    });

    /// Get all stored items of `type`, optionally also restricted by `extra`. Note that
    /// length is returned for each item as VMOs are page-aligned.
    ///
    /// Returns ZX_ERR_NOT_SUPPORTED if this is an untracked item which will never be stored.
    @transitional
    Get2(struct {
        type uint32;
        extra box< struct {
            n uint32;
        }>;
    }) -> (resource struct {
        retrieved_items vector< resource struct {
            payload zx.handle:VMO;
            length uint32;
            extra uint32;
        }>:MAX;
    }) error zx.status;

    /// Gets the `payload` for a `ZBI_TYPE_BOOTLOADER_FILE` boot item.
    /// Note: ZX_PROP_VMO_CONTENT_SIZE will be set to the actual file content size
    GetBootloaderFile(struct {
        filename string:MAX_FILE_NAME_LENGTH;
    }) -> (resource struct {
        payload zx.handle:<VMO, optional>;
    });
};