trezor-firmware/common/protob/messages-debug.proto

syntax = "proto2";
package hw.trezor.messages.debug;

// Sugar for easier handling in Java
option java_package = "com.satoshilabs.trezor.lib.protobuf";
option java_outer_classname = "TrezorMessageDebug";

option (include_in_bitcoin_only) = true;

import "messages.proto";
import "messages-common.proto";
import "messages-management.proto";

/**
 * Request: "Press" the button on the device
 * @start
 * @next DebugLinkLayout
 */
message DebugLinkDecision {
    optional DebugButton button = 1;  // button press
    optional DebugSwipeDirection swipe = 2;  // swipe direction
    optional string input = 3;  // keyboard input
    /**
    * Structure representing swipe direction
    */
    enum DebugSwipeDirection {
        UP = 0;
        DOWN = 1;
        LEFT = 2;
        RIGHT = 3;
    }

    /**
    * Structure representing button presses
    */
    enum DebugButton {
        NO = 0;
        YES = 1;
        INFO = 2;
    }

    /**
    * Structure representing model R button presses
    */
    // TODO: probably delete the middle_btn as it is not a physical one
    enum DebugPhysicalButton {
        LEFT_BTN = 0;
        MIDDLE_BTN = 1;
        RIGHT_BTN = 2;
    }

    optional uint32 x = 4;                             // touch X coordinate
    optional uint32 y = 5;                             // touch Y coordinate
    optional bool wait = 6;                            // wait for layout change
    optional uint32 hold_ms = 7;                       // touch hold duration
    optional DebugPhysicalButton physical_button = 8;  // physical button press
}

/**
 * Response: Device text layout as a list of tokens as returned by Rust
 * @end
 */
message DebugLinkLayout {
    repeated string tokens = 1;
}

/**
 * Request: Re-seed RNG with given value
 * @start
 * @next Success
 */
message DebugLinkReseedRandom {
    optional uint32 value = 1;
}

/**
 * Request: Start or stop recording screen changes into given target directory
 * @start
 * @next Success
 */
message DebugLinkRecordScreen {
    optional string target_directory = 1;           // empty or missing to stop recording
    optional uint32 refresh_index = 2 [default=0];  // which index to give the screenshots (after emulator restarts)
}

/**
 * Request: Computer asks for device state
 * @start
 * @next DebugLinkState
 */
message DebugLinkGetState {
    optional bool wait_word_list = 1;  // Trezor T only - wait until mnemonic words are shown
    optional bool wait_word_pos = 2;   // Trezor T only - wait until reset word position is requested
    optional bool wait_layout = 3;     // wait until current layout changes
}

/**
 * Response: Device current state
 * @end
 */
message DebugLinkState {
    optional bytes layout = 1;                              // raw buffer of display
    optional string pin = 2;                                // current PIN, blank if PIN is not set/enabled
    optional string matrix = 3;                             // current PIN matrix
    optional bytes mnemonic_secret = 4;                     // current mnemonic secret
    optional common.HDNodeType node = 5; // current BIP-32 node
    optional bool passphrase_protection = 6;                // is node/mnemonic encrypted using passphrase?
    optional string reset_word = 7;                         // word on device display during ResetDevice workflow
    optional bytes reset_entropy = 8;                       // current entropy during ResetDevice workflow
    optional string recovery_fake_word = 9;                 // (fake) word on display during RecoveryDevice workflow
    optional uint32 recovery_word_pos = 10;                 // index of mnemonic word the device is expecting during RecoveryDevice workflow
    optional uint32 reset_word_pos = 11;                    // index of mnemonic word the device is expecting during ResetDevice workflow
    optional management.BackupType mnemonic_type = 12;      // current mnemonic type (BIP-39/SLIP-39)
    repeated string tokens = 13;                            // current layout represented as a list of string tokens
}

/**
 * Request: Ask device to restart
 * @start
 */
message DebugLinkStop {
}

/**
 * Response: Device wants host to log event
 * @ignore
 */
message DebugLinkLog {
    optional uint32 level = 1;
    optional string bucket = 2;
    optional string text = 3;
}

/**
 * Location in the flash memory.enum
 * @embed
 */
message FlashMemoryLocation {
    /// Selector of the area
    required FlashArea area = 1;
    /// Offset from area start
    required uint32 offset = 2;

    enum FlashArea {
        Boardloader = 0;
        Bootloader = 1;
        StorageA = 2;
        StorageB = 3;
        Firmware = 4;
        Translations = 5;
    }
}

/**
 * Request: Read memory from device (legacy)
 * @start
 * @next DebugLinkMemory
 */
message DebugLinkMemoryRead {
    option deprecated = true;

    optional uint32 address = 1;
    optional uint32 length = 2;
}

/**
 * Request: Read flash contents from device (trezor-core)
 * @start
 * @next DebugLinkMemory
 */
 message DebugLinkFlashRead {
    /// Flash memory location
    required FlashMemoryLocation location = 1;
    /// Length of the memory to read. If unspecified, the whole area is read.
    optional uint32 length = 2;
    /// If true, only the hash of the memory contents will be returned.
    /// Useful if the memory is large and the hash is enough to verify the contents.
    optional bool hashed = 3 [default = false];
}

/**
 * Response: Device sends memory back
 * @end
 */
message DebugLinkMemory {
    optional bytes memory = 1;
    optional bytes hash = 2;
}

/**
 * Request: Write memory to device (legacy).
 * WARNING: Writing to the wrong location can irreparably break the device.
 * @start
 * @next Success
 * @next Failure
 */
message DebugLinkMemoryWrite {
    option deprecated = true;

    optional uint32 address = 1;
    optional bytes memory = 2;
    optional bool flash = 3;
}

/**
 * Request: Write to device flash memory (trezor-core).
 * WARNING: Writing to the wrong location can irreparably break the device.
 * @start
 * @next Success
 * @next Failure
 */
 message DebugLinkFlashWrite {
    /// Flash memory location
    required FlashMemoryLocation location = 1;
    /// Contents of the memory to flash.
    required bytes memory = 2;
}

/**
 * Request: Erase block of flash on device (legacy)
 * WARNING: Writing to the wrong location can irreparably break the device.
 * @start
 * @next Success
 * @next Failure
 */
message DebugLinkFlashEraseLegacy {
    option deprecated = true;

    optional uint32 sector = 1;
}

/**
 * Request: Erase block of flash on device (trezor-core)
 * WARNING: Writing to the wrong location can irreparably break the device.
 * @start
 * @next Success
 * @next Failure
 */
 message DebugLinkFlashErase {
    /// Flash memory location
    required FlashMemoryLocation location = 1;
    /// Erase whole area or just the sector at the given offset.
    /// If the offset is not a start of a sector, error is returned.
    optional bool whole_area = 2 [default = false];
}


/**
 * Request: Erase the SD card
 * @start
 * @next Success
 * @next Failure
 */
message DebugLinkEraseSdCard {
    optional bool format = 1;  // if true, the card will be formatted to FAT32.
                               // if false, it will be all 0xFF bytes.
}


/**
 * Request: Start or stop tracking layout changes
 * @start
 * @next Success
 */
message DebugLinkWatchLayout {
    optional bool watch = 1;  // if true, start watching layout.
                              // if false, stop.
}


/**
 * Request: Remove all the previous debug event state
 * @start
 * @next Success
 */
message DebugLinkResetDebugEvents {
}