sdk/fidl/fuchsia.buttons/gpio_buttons.fidl

// Copyright 2025 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.buttons;

using zx;

/// Configuration for a direct gpio button where the state of the button is represented by the value
/// of a gpio.
type DirectGpioButton = table {};

/// Configuration for a matrix gpio button.
type MatrixGpioButton = table {
    /// Index of gpio B (column) used. Gpio type must be `GpioType::matrix_output` (is driven most
    /// of the time) and gpio A (row) must be `GpioType::interrupt` (triggers an interrupt most of
    /// the time). During matrix scans columns are floated and rows are read.
    1: gpio_b_index uint8;
};

/// Type of button.
type GpioButtonType = flexible union {
    1: direct DirectGpioButton;
    2: matrix MatrixGpioButton;
};

/// Maximum ordinal that GpioButtonId can be.
const MAX_GPIO_BUTTON_ID_ORD uint32 = 0x0b;

/// All possible IDs of a button.
type GpioButtonId = flexible enum {
    VOLUME_UP = 0x00;
    VOLUME_DOWN = 0x01;
    FDR = 0x02;
    MIC_MUTE = 0x03;
    PLAY_PAUSE = 0x04;
    KEY_A = 0x05;
    KEY_M = 0x06;
    CAM_MUTE = 0x07;
    MIC_AND_CAM_MUTE = 0x08;
    FUNCTION = 0x09;
    POWER = 0x0a;
};

/// Gpio pin will trigger an interrupt when its value has changed.
type InterruptGpio = table {};

/// Gpio pin's value continuously cycles through a row or column of a matrix of values that usually
/// represent a matrix of the states of buttons/components.
type MatrixOutputGpio = table {
    /// Determines the buffer mode of the gpio. A value of 0 is output-low and anything else is
    /// output-high.
    1: output_value uint8;
};

/// Gpio pin is constantly polled for its value.
type PollGpio = table {
    /// Time between each poll.
    1: period zx.Duration;
};

/// The type of gpio.
type GpioType = flexible union {
    1: interrupt InterruptGpio;
    2: matrix_output MatrixOutputGpio;
    3: poll PollGpio;
};

/// Flags for configuriung gpio pin.
type GpioFlag = flexible bits {
    /// Invert the gpio's signal.
    INVERTED = 0x80;

    /// Use the gpio as a wake vector.
    WAKE_VECTOR = 0x40;
};

/// Configuration information of a button that uses gpios to function.
type GpioButtonConfig = table {
    1: type GpioButtonType;

    /// Index of gpio A used.
    2: gpio_a_index uint8;

    /// For settling during matrix scan.
    3: gpio_delay zx.Duration;

    /// ID of the button.
    4: id GpioButtonId;
};

/// Configuration information of a gpio used by a button.
type GpioConfig = table {
    /// The type of the gpio pin.
    1: type GpioType;

    /// The flags of the gpio pin.
    2: flags GpioFlag;
};

@serializable
type GpioButtonsMetadata = table {
    /// Configuration information for buttons that require gpio to function.
    1: buttons vector<GpioButtonConfig>:MAX;

    /// Configuration information for the gpios used by |buttons|.
    2: gpios vector<GpioConfig>:MAX;
};