// Copyright 2023 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.

// This file is a copy of sdk/banjo/fuchsia.hardware.sdmmc/sdmmc.fidl.
// The protocol itself has NOT gone through an up-to-date API review.

library fuchsia.hardware.sdmmc;

using zx;

/// The max value of client_id fields below. There is no known need for more than eight clients at
/// the moment, however if that changes later this value will be increased.
const SDMMC_MAX_CLIENT_ID uint8 = 7;

type SdmmcVoltage = strict enum : uint8 {
    V330 = 0;
    V180 = 1;
    MAX = 2;
};

type SdmmcBusWidth = strict enum : uint8 {
    ONE = 0;
    FOUR = 1;
    EIGHT = 2;
    MAX = 3;
};

type SdmmcTiming = strict enum : uint8 {
    LEGACY = 0;
    HS = 1;
    HSDDR = 2;
    HS200 = 3;
    HS400 = 4;
    SDR12 = 5;
    SDR25 = 6;
    SDR50 = 7;
    SDR104 = 8;
    DDR50 = 9;
    MAX = 10;
};

type SdmmcBuffer = strict resource union {
    /// The ID of a VMO that was previously registered.
    1: vmo_id uint32;
    /// An unregistered VMO of which the protocol implementation does not take ownership. The VMO is
    /// pinned upon entering Request and is unpinned before returning.
    2: vmo zx.Handle:VMO;
};

type SdmmcBufferRegion = resource struct {
    buffer SdmmcBuffer;
    /// Offset into the VMO to start reading or writing. This is relative to the offset passed to
    /// RegisterVmo if type is VMO_ID.
    offset uint64;
    /// Number of bytes to read from or write to this buffer region.
    size uint64;
};

type SdmmcReq = resource struct {
    cmd_idx uint32;
    cmd_flags uint32;
    arg uint32;

    blocksize uint32;

    /// If true, the SDMMC driver should reduce the log level of any error
    /// messages that this request produces. This will be set on requests for
    /// which errors are expected or not fatal.
    suppress_error_messages bool;

    /// The client ID for this request. Only VMOs registered with this client may be present in
    /// buffers below.
    client_id uint8;
    buffers vector<SdmmcBufferRegion>:MAX;
};

/// number of pages per request - 2M per request
/// matches DMA_DESC_COUNT in dev/block/sdhci
/// (PAGE_SIZE / sizeof(zx_paddr_t))
const SDMMC_PAGES_COUNT uint64 = 512;

type SdmmcHostCap = strict bits : uint64 {
    BUS_WIDTH_8 = 0x1;
    DMA = 0x2;
    VOLTAGE_330 = 0x4;
    AUTO_CMD12 = 0x8;
    SDR104 = 0x10;
    SDR50 = 0x20;
    DDR50 = 0x40;
    /// The host does not require tuning for SDR50.
    NO_TUNING_SDR50 = 0x80;
};

type SdmmcHostPrefs = strict bits : uint64 {
    DISABLE_HS400 = 0x1;
    DISABLE_HS200 = 0x2;
    DISABLE_HSDDR = 0x4;
};

type SdmmcHostInfo = struct {
    /// Controller capabilities
    caps uint64;
    /// Maximum data request size
    max_transfer_size uint64;
    max_transfer_size_non_dma uint64;
    /// The number of buffer regions that may be used in a single request.
    max_buffer_regions uint64;
};

type SdmmcVmoRight = strict bits : uint32 {
    READ = 0x1; // The protocol implementation can read from this VMO (used for write requests).
    WRITE = 0x2; // The protocol implementation can write to this VMO (used for read requests).
};

@discoverable
@transport("Driver")
closed protocol InBandInterrupt {
    strict Callback() -> ();
};

@discoverable
@transport("Driver")
closed protocol Sdmmc {
    /// Get host info.
    strict HostInfo() -> (struct {
        info SdmmcHostInfo;
    }) error zx.Status;
    /// Set signal voltage.
    strict SetSignalVoltage(struct {
        voltage SdmmcVoltage;
    }) -> () error zx.Status;
    /// Set bus width.
    strict SetBusWidth(struct {
        bus_width SdmmcBusWidth;
    }) -> () error zx.Status;
    /// Set bus frequency, zero means disable the clock to the card.
    strict SetBusFreq(struct {
        bus_freq uint32;
    }) -> () error zx.Status;
    /// Set mmc timing.
    strict SetTiming(struct {
        timing SdmmcTiming;
    }) -> () error zx.Status;
    /// Issue a hw reset.
    strict HwReset() -> () error zx.Status;
    /// Perform tuning.
    strict PerformTuning(struct {
        cmd_idx uint32;
    }) -> () error zx.Status;
    /// Register the given callback to be called when an in-band interrupt is received from the
    /// card. Before calling the callback the protocol implementation will disable the in-band
    /// interrupt in the controller. In-band interrupts can be re-enabled by calling
    /// `AckInBandInterrupt()` once the previous interrupt has been handled by the client.
    strict RegisterInBandInterrupt(resource struct {
        @in_out
        interrupt_cb client_end:InBandInterrupt;
    }) -> () error zx.Status;
    strict AckInBandInterrupt();

    /// In the methods below, vmo_id is used to uniquely identify a VMO that will be passed to
    /// Request in an SdmmcBufferRegion. VMO IDs are chosen by the caller, and may be any uint32
    /// value.
    /// Registers a VMO and transfers ownership to the protocol implementation. vmo_rights is a bit
    /// field containing SdmmcVmoRight values, and determines the read/write permissions used by
    /// the implementation when pinning or mapping the VMO. The implementation may pin vmo during
    /// this call or any time it is used in a request, and may keep it pinned until the VMO is
    /// unregistered. client_id may be in [0, SDMMC_MAX_CLIENT_ID] and identifies the ID space for
    /// this VMO to be registered in (that is, two different VMOs may use the same ID if they are
    /// registered for different clients).
    strict RegisterVmo(resource struct {
        vmo_id uint32;
        client_id uint8;
        vmo zx.Handle:VMO;
        offset uint64;
        size uint64;
        vmo_rights uint32;
    }) -> () error zx.Status;
    /// The callee unmaps/unpins the VMO and returns ownership to the caller.
    strict UnregisterVmo(struct {
        vmo_id uint32;
        client_id uint8;
    }) -> (resource struct {
        vmo zx.Handle:VMO;
    }) error zx.Status;

    /// Perform the requests in order, atomically (i.e., no intervening requests). Furthermore,
    /// calls are replied to in the order they are received. If an error occurs, abort any remaining
    /// requests. Else, return the response of the last request.
    ///
    /// The protocol implementation chooses whether or not to use DMA
    /// depending on the properties of the request and the capabilities of the controller.
    ///
    /// Clients are responsible for performing the following cache operations:
    ///
    /// After read requests:
    /// - Call zx_cache_flush with ZX_CACHE_FLUSH_DATA | ZX_CACHE_FLUSH_INVALIDATE on buffers that
    ///   have been mapped by the client.
    /// - Call zx_vmo_op_range with ZX_VMO_OP_CACHE_CLEAN_INVALIDATE on all other buffers.
    ///
    /// Note that writing to any portion of a buffer before Request has returned can corrupt the
    /// received data.
    ///
    /// Before write requests:
    /// - Call zx_cache_flush with ZX_CACHE_FLUSH_DATA on buffers that have been mapped by the
    ///   client.
    /// - Call zx_vmo_op_range with ZX_VMO_OP_CACHE_CLEAN on all other buffers.
    strict Request(resource struct {
        reqs vector<SdmmcReq>:MAX;
    }) -> (struct {
        response array<uint32, 4>;
    }) error zx.Status;
};

service SdmmcService {
    sdmmc client_end:Sdmmc;
};