// Copyright 2021 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.tpm.cr50;

using zx;
using fuchsia.tpm;

const CCD_CAPABILITY_COUNT_MAX uint32 = 32;
const CCD_PASSWORD_MAX uint32 = 512;

/// Vendor-specific TPM response codes.
type Cr50Status = flexible enum : uint8 {
    /// Command succeeded.
    SUCCESS = 0;
    /// Incorrect parameters.
    BOGUS_ARGS = 1;
    /// Failed while reading from flash.
    READ_FLASH_FAIL = 2;
    /// Failed while writing to flash.
    WRITE_FLASH_FAIL = 3;
    /// Request or part of request too big.
    REQUEST_TOO_BIG = 4;
    /// Response too big for the response buffer allocated by the TPM.
    RESPONSE_TOO_BIG = 5;
    /// Unspecified internal error.
    INTERNAL_ERROR = 6;
    /// Command not allowed in current state.
    NOT_ALLOWED = 7;
    /// Command was given an unknown subcommand.
    NO_SUCH_SUBCOMMAND = 8;
    /// Command is in progress.
    IN_PROGRESS = 9;
    /// Password is required for this command.
    PASSWORD_REQUIRED = 10;
    /// Non-volatile memory was locked.
    NVMEM_LOCKED = 11;
    /// Unsupported command.
    NO_SUCH_COMMAND = 127;
};

/// State of case-closed debugging features on this device.
type CcdState = flexible enum : uint8 {
    /// Locked. CCD configuration is read-only. ALWAYS capabilities are
    /// available.
    LOCKED = 0;
    /// Unlocked:
    /// * Requires a short physical presence check.
    /// * CCD password can be changed (unless it was set with CCD open).
    /// * Limited access to CCD configuration (can toggle capabilities between
    /// ALWAYS and UNLESS_LOCKED, but cannot set flags or change OPEN
    /// capabilities).
    UNLOCKED = 1;
    /// Opened. Full access to all CCD capabilities and configuration.
    /// Requires a long physical presence check.
    OPEN = 2;
};

/// Case-closed debugging capabilities.
type CcdCapability = flexible enum {
    /// UART from AP.
    GSC_RX_AP_TX = 0;
    /// UART to AP.
    GSC_TX_AP_RX = 1;
    /// UART from EC.
    GSC_RX_EC_TX = 2;
    /// UART to EC.
    GSC_TX_EC_RX = 3;
    /// Access to AP SPI flash.
    AP_FLASH = 4;
    /// Access to EC flash.
    EC_FLASH = 5;
    /// Override WP (temporarily or at boot).
    OVERRIDE_WP = 6;
    /// Reboot EC/AP.
    REBOOT_EC_AP = 7;
    /// Allow access to full console.
    GSC_FULL_CONSOLE = 8;
    /// Unlock/open CCD without AP reboot.
    UNLOCK_NO_REBOOT = 9;
    /// Unlock/open CCD without short physical presence check.
    UNLOCK_NO_SHORT_PP = 10;
    /// Open CCD without TPM wipe.
    OPEN_NO_TPM_WIPE = 11;
    /// Open TPM without long physical presence check.
    OPEN_NO_LONG_PP = 12;
    /// Allow disconnecting the battery to bypass the physical presence check.
    BATTERY_BYPASS_PP = 13;
    /// Unused.
    UNUSED = 14;
    /// Access I2C via USB.
    I2C = 15;
    /// Read-only access to hash or dump EC/AP flash.
    FLASH_READ = 16;
    /// Open CCD without developer mode enabled.
    OPEN_NO_DEV_MODE = 17;
    /// Open CCD from USB.
    OPEN_FROM_USB = 18;
    /// Override battery presence temporarily or at boot.
    OVERRIDE_BATTERY_STATE = 19;
};

/// Represents the state of a CCD capability.
type CcdCapabilityState = flexible enum {
    /// Default value.
    DEFAULT = 0;
    /// Always available, even if locked.
    ALWAYS = 1;
    /// Available unless locked. (i.e. in UNLOCKED or OPEN states).
    UNLESS_LOCKED = 2;
    /// Only available if opened.
    IF_OPENED = 3;
};

type CcdCapabilitySetting = struct {
    capability CcdCapability;
    current_state CcdCapabilityState;
    default_state CcdCapabilityState;
};

type CcdFlags = flexible bits {
    /// Test lab mode enabled. Read only.
    TEST_LAB = 0x1;
    /// State when password was set (0 = open, 1 = unlocked). Read only.
    PASSWORD_SET_WHEN_UNLOCKED = 0x2;
    /// Factory mode state. Read only.
    FACTORY_MODE_ENABLED = 0x4;

    /// Enable Rddkeepalive at boot.
    RDDKEEPALIVE_AT_BOOT = 0x8000;
    /// Override battery presence at boot.
    OVERRIDE_BATT_AT_BOOT = 0x10000;
    /// If overriding battery presence, what state? (0 = disconnected, 1 =
    /// connected).
    OVERRIDE_BATT_STATE_CONNECT = 0x20000;
    /// Override write protect at boot.
    OVERRIDE_WP_AT_BOOT = 0x40000;
    /// If override WP, what value should it have? (0 = disabled, 1 = enabled).
    OVERRIDE_WP_STATE_ENABLED = 0x80000;
};

type CcdIndicator = flexible bits : uint8 {
    /// 1 if CCD has a password.
    HAS_PASSWORD = 0x1;
    /// 1 if all capabilities are default.
    ALL_CAPS_DEFAULT = 0x2;
};

type CcdInfo = struct {
    /// CCD capability settings.
    capabilities vector<CcdCapabilitySetting>:CCD_CAPABILITY_COUNT_MAX;
    /// CCD flags.
    flags CcdFlags;
    /// Current CCD state, some bits configurable.
    state CcdState;
    /// Indicates internal CCD state.
    indicator CcdIndicator;
    /// True if CCD is forcibly disabled.
    force_disabled bool;
};

/// Response code type for cr50 commands.
type Cr50Rc = flexible union {
    /// TPM standard response code.
    1: tpm fuchsia.tpm.TpmRc;
    /// Cr50 vendor response code.
    2: cr50 Cr50Status;
};

/// Write protect status field.
type WpState = flexible bits : uint8 {
    /// Appears to be unused.
    UPDATE = 0x1;
    /// If set, then WP is enabled.
    ENABLE = 0x2;
    /// If set, then the current WP state is forced.
    FORCE = 0x4;
    /// If set, then WP state is overriden at boot.
    /// Otherwise WP is enabled if battery is present, disabled otherwise.
    AT_BOOT_SET = 0x8;
    /// Determines state of WP at boot if AT_BOOT_SET is set.
    AT_BOOT_ENABLE = 0x10;
};

@discoverable
closed protocol Cr50 {
    /// Get information about the current state of case-closed debugging.
    strict CcdGetInfo() -> (struct {
        rc Cr50Rc;
        info box<CcdInfo>;
    }) error zx.Status;

    /// Lock case-closed debugging.
    strict CcdLock() -> (struct {
        rc Cr50Rc;
    }) error zx.Status;

    /// Put case-closed debugging into the OPEN state.
    /// See |CcdState| for a description of what each state means.
    strict CcdOpen(struct {
        password string:<CCD_PASSWORD_MAX, optional>;
    }) -> (resource struct {
        rc Cr50Rc;
        presence_checker client_end:<PhysicalPresenceNotifier, optional>;
    }) error zx.Status;

    /// Put case-closed debugging into the UNLOCKED state.
    /// See |CcdState| for a description of what each state means.
    strict CcdUnlock(struct {
        password string:<CCD_PASSWORD_MAX, optional>;
    }) -> (resource struct {
        rc Cr50Rc;
        presence_checker client_end:<PhysicalPresenceNotifier, optional>;
    }) error zx.Status;

    /// Get the current state of the AP BIOS flash write protect.
    strict WpGetState() -> (struct {
        rc Cr50Rc;
        state WpState;
    }) error zx.Status;
};

type PhysicalPresenceState = flexible enum {
    /// Physical presence check timed out, or there isn't one currently running.
    CLOSED = 0;
    /// TPM is ready to receive next press.
    AWAITING_PRESS = 1;
    /// TPM is waiting - not ready to receive a press yet.
    BETWEEN_PRESSES = 2;
    /// Physical presence check succeeded and CCD is unlocked/open.
    DONE = 3;
};

/// Union passed to OnChange() event handler of |PhysicalPresenceNotifier|.
type PhysicalPresenceEvent = flexible union {
    /// An error occurred while polling the TPM.
    1: err zx.Status;
    /// Physical presence status.
    2: state PhysicalPresenceState;
};

/// Protocol used to notify client of a pending physical presence event.
/// This protocol has no form of backpressure because it is not expected to
/// generate a large number of messages. An unlock or open will usually result in less
/// than 20 messages.
closed protocol PhysicalPresenceNotifier {
    /// Called when the PP check has changed state.
    /// If CLOSED is the first event sent, it means that no PP check was necessary
    /// (i.e. CCD is already open). However, if CLOSED isn't the first event
    /// sent, then CLOSED indicates that the PP check timed out.
    strict -> OnChange(struct {
        event PhysicalPresenceEvent;
    });
};