blob: b7b0ce544bc9434e70098c1582e480d7ccfc5ac4 [file] [log] [blame]
/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*
* APIs provided by firmware to vboot_reference.
*
* General notes:
*
* All verified boot functions now start with "Vb" for namespace clarity. This
* fixes the problem where uboot and vboot both defined assert().
*
* Verified boot APIs to be implemented by the calling firmware and exported to
* vboot_reference start with "VbEx".
*
* TODO: split this file into a vboot_entry_points.h file which contains the
* entry points for the firmware to call vboot_reference, and a
* vboot_firmware_exports.h which contains the APIs to be implemented by the
* calling firmware and exported to vboot_reference.
*/
#ifndef VBOOT_REFERENCE_VBOOT_API_H_
#define VBOOT_REFERENCE_VBOOT_API_H_
#include <stdint.h>
#include <stdlib.h>
#include "../2lib/include/2return_codes.h"
#include "gpt.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
struct vb2_context;
typedef struct VbSharedDataHeader VbSharedDataHeader;
/*****************************************************************************/
/* Main entry points from firmware into vboot_reference */
/*
* We use disk handles rather than indices. Using indices causes problems if
* a disk is removed/inserted in the middle of processing.
*/
typedef void *VbExDiskHandle_t;
typedef struct VbSelectAndLoadKernelParams {
/* Inputs to VbSelectAndLoadKernel() */
/* Destination buffer for kernel (normally at 0x100000 on x86) */
void *kernel_buffer;
/* Size of kernel buffer in bytes */
uint32_t kernel_buffer_size;
/*
* Outputs from VbSelectAndLoadKernel(); valid only if it returns
* success.
*/
/* Handle of disk containing loaded kernel */
VbExDiskHandle_t disk_handle;
/* Partition number on disk to boot (1...M) */
uint32_t partition_number;
/* Address of bootloader image in RAM */
uint64_t bootloader_address;
/* Size of bootloader image in bytes */
uint32_t bootloader_size;
/* UniquePartitionGuid for boot partition */
uint8_t partition_guid[16];
/* Flags set by signer */
uint32_t flags;
} VbSelectAndLoadKernelParams;
/**
* Select and loads the kernel.
*
* Returns VB2_SUCCESS if success, non-zero if error; on error, caller
* should reboot. */
vb2_error_t VbSelectAndLoadKernel(struct vb2_context *ctx,
VbSelectAndLoadKernelParams *kparams);
/**
* Attempt loading a kernel from the specified type(s) of disks.
*
* If successful, sets kparams.disk_handle to the disk for the kernel and
* returns VB2_SUCCESS.
*
* @param ctx Vboot context
* @param disk_flags Flags to pass to VbExDiskGetInfo()
* @return VB2_SUCCESS or the most specific VB2_ERROR_LK error.
*/
vb2_error_t VbTryLoadKernel(struct vb2_context *ctx, uint32_t disk_flags);
/*****************************************************************************/
/* Disk access (previously in boot_device.h) */
/* Flags for VbDisk APIs */
/*
* Disk selection in the lower 16 bits (where the disk lives), and disk
* attributes in the higher 16 bits (extra information about the disk
* needed to access it correctly).
*/
#define VB_DISK_FLAG_SELECT_MASK 0xffff
#define VB_DISK_FLAG_ATTRIBUTE_MASK (0xffff << 16)
/* Disk is removable. Example removable disks: SD cards, USB keys. */
#define VB_DISK_FLAG_REMOVABLE (1 << 0)
/*
* Disk is fixed. If this flag is present, disk is internal to the system and
* not removable. Example fixed disks: internal SATA SSD, eMMC.
*/
#define VB_DISK_FLAG_FIXED (1 << 1)
/*
* Note that VB_DISK_FLAG_REMOVABLE and VB_DISK_FLAG_FIXED are
* mutually-exclusive for a single disk. VbExDiskGetInfo() may specify both
* flags to request disks of both types in a single call.
*
* At some point we could specify additional flags, but we don't currently
* have a way to make use of these:
*
* USB Device is known to be attached to USB. Note that the SD
* card reader inside x86 systems is attached to USB so this
* isn't super useful.
* SD Device is known to be a SD card. Note that external card
* readers might not return this information, so also of
* questionable use.
* READ_ONLY Device is known to be read-only. Could be used by recovery
* when processing read-only recovery image.
*/
/*
* Disks are used in two ways:
* - As a random-access device to read and write the GPT
* - As a streaming device to read the kernel
* These are implemented differently on raw NAND vs eMMC/SATA/USB
* - On eMMC/SATA/USB, both of these refer to the same underlying
* storage, so they have the same size and LBA size. In this case,
* the GPT should not point to the same address as itself.
* - On raw NAND, the GPT is held on a portion of the SPI flash.
* Random access GPT operations refer to the SPI and streaming
* operations refer to NAND. The GPT may therefore point into
* the same offsets as itself.
* These types are distinguished by the following flag and VbDiskInfo
* has separate fields to describe the random-access ("GPT") and
* streaming aspects of the disk. If a disk is random-access (i.e.
* not raw NAND) then these fields are equal.
*/
#define VB_DISK_FLAG_EXTERNAL_GPT (1 << 16)
/* Information on a single disk */
typedef struct VbDiskInfo {
/* Disk handle */
VbExDiskHandle_t handle;
/* Size of a random-access LBA sector in bytes */
uint64_t bytes_per_lba;
/* Number of random-access LBA sectors on the device.
* If streaming_lba_count is 0, this stands in for the size of the
* randomly accessed portion as well as the streaming portion.
* Otherwise, this is only the randomly-accessed portion. */
uint64_t lba_count;
/* Number of streaming sectors on the device */
uint64_t streaming_lba_count;
/* Flags (see VB_DISK_FLAG_* constants) */
uint32_t flags;
/*
* Optional name string, for use in debugging. May be empty or null if
* not available.
*/
const char *name;
} VbDiskInfo;
/**
* Store information into [info] for all disks (storage devices) attached to
* the system which match all of the disk_flags.
*
* On output, count indicates how many disks are present, and [infos_ptr]
* points to a [count]-sized array of VbDiskInfo structs with the information
* on those disks; this pointer must be freed by calling VbExDiskFreeInfo().
* If count=0, infos_ptr may point to NULL. If [infos_ptr] points to NULL
* because count=0 or error, it is not necessary to call VbExDiskFreeInfo().
*
* A multi-function device (such as a 4-in-1 card reader) should provide
* multiple disk handles.
*
* The firmware must not alter or free the list pointed to by [infos_ptr] until
* VbExDiskFreeInfo() is called.
*/
vb2_error_t VbExDiskGetInfo(VbDiskInfo **infos_ptr, uint32_t *count,
uint32_t disk_flags);
/**
* Free a disk information list [infos] previously returned by
* VbExDiskGetInfo(). If [preserve_handle] != NULL, the firmware must ensure
* that handle remains valid after this call; all other handles from the info
* list need not remain valid after this call.
*/
vb2_error_t VbExDiskFreeInfo(VbDiskInfo *infos,
VbExDiskHandle_t preserve_handle);
/**
* Read lba_count LBA sectors, starting at sector lba_start, from the disk,
* into the buffer.
*
* This is used for random access to the GPT. It is not for the partition
* contents. The upper limit is lba_count.
*
* If the disk handle is invalid (for example, the handle refers to a disk
* which as been removed), the function must return error but must not
* crash.
*/
vb2_error_t VbExDiskRead(VbExDiskHandle_t handle, uint64_t lba_start,
uint64_t lba_count, void *buffer);
/**
* Write lba_count LBA sectors, starting at sector lba_start, to the disk, from
* the buffer.
*
* This is used for random access to the GPT. It does not (necessarily) access
* the streaming portion of the device.
*
* If the disk handle is invalid (for example, the handle refers to a disk
* which as been removed), the function must return error but must not
* crash.
*/
vb2_error_t VbExDiskWrite(VbExDiskHandle_t handle, uint64_t lba_start,
uint64_t lba_count, const void *buffer);
/* Streaming read interface */
typedef void *VbExStream_t;
/**
* Open a stream on a disk
*
* @param handle Disk to open the stream against
* @param lba_start Starting sector offset within the disk to stream from
* @param lba_count Maximum extent of the stream in sectors
* @param stream out-paramter for the generated stream
*
* @return Error code, or VB2_SUCCESS.
*
* This is used for access to the contents of the actual partitions on the
* device. It is not used to access the GPT. The size of the content addressed
* is within streaming_lba_count.
*/
vb2_error_t VbExStreamOpen(VbExDiskHandle_t handle, uint64_t lba_start,
uint64_t lba_count, VbExStream_t *stream_ptr);
/**
* Read from a stream on a disk
*
* @param stream Stream to read from
* @param bytes Number of bytes to read
* @param buffer Destination to read into
*
* @return Error code, or VB2_SUCCESS. Failure to read as much data as
* requested is an error.
*
* This is used for access to the contents of the actual partitions on the
* device. It is not used to access the GPT.
*/
vb2_error_t VbExStreamRead(VbExStream_t stream, uint32_t bytes, void *buffer);
/**
* Close a stream
*
* @param stream Stream to close
*/
void VbExStreamClose(VbExStream_t stream);
/*****************************************************************************/
/* Misc */
/**
* Check if the firmware needs to shut down the system.
*
* Returns a non-zero VB_SHUTDOWN_REQUEST mask indicating the reason(s) for
* shutdown if a shutdown is being requested (see VB_SHUTDOWN_REQUEST_*), or 0
* if a shutdown is not being requested.
*
* NOTE: When we're displaying a screen, pressing the power button should shut
* down the computer. We need a way to break out of our control loop so this
* can occur cleanly.
*/
uint32_t VbExIsShutdownRequested(void);
/*
* Shutdown requested for a reason which is not defined among other
* VB_SHUTDOWN_REQUEST_* values. This must be defined as 1 for backward
* compatibility with old versions of the API.
*/
#define VB_SHUTDOWN_REQUEST_OTHER 0x00000001
/* Shutdown requested due to a lid switch being closed. */
#define VB_SHUTDOWN_REQUEST_LID_CLOSED 0x00000002
/* Shutdown requested due to a power button being pressed. */
#define VB_SHUTDOWN_REQUEST_POWER_BUTTON 0x00000004
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* VBOOT_REFERENCE_VBOOT_API_H_ */