// Copyright 2018 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.hardware.sdhci;

using zx;

enum SdhciQuirk : uint64 {
    /// This is a BCM28xx specific quirk. The bottom 8 bits of the 136
    /// bit response are normally filled by 7 CRC bits and 1 reserved bit.
    /// The BCM controller checks the CRC for us and strips it off in the
    /// process.
    /// The higher level stack expects 136B responses to be packed in a
    /// certain way so we shift all the fields back to their proper offsets.
    STRIP_RESPONSE_CRC = 0x1;
    /// BCM28xx quirk: The BCM28xx appears to use its internal DMA engine to
    /// perform transfers against the SD card. Normally we would use SDMA or
    /// ADMA (if the part supported it). Since this part doesn't appear to
    /// support either, we just use PIO.
    NO_DMA = 0x2;
    /// The bottom 8 bits of the 136 bit response are normally filled by 7 CRC bits
    /// and 1 reserved bit. Some controllers strip off the CRC.
    /// The higher level stack expects 136B responses to be packed in a certain way
    /// so we shift all the fields back to their proper offsets.
    STRIP_RESPONSE_CRC_PRESERVE_ORDER = 0x4;
    /// The controller uses a tuning process that does not follow the SDHCI specification.
    NON_STANDARD_TUNING = 0x8;
    /// Don't use DDR modes even if the SDHCI capabilites register indicates it is supported.
    NO_DDR = 0x10;
    /// Prevent DMA buffers from crossing boundaries specified by dma_boundary_alignment. For
    /// example, a boundary alignment of 0x10000 will cause buffers crossing 64K boundaries to be
    /// split across multiple descriptors.
    USE_DMA_BOUNDARY_ALIGNMENT = 0x20;
};

[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
protocol Sdhci {
    // TODO: should be replaced with a generic busdev mechanism
    GetInterrupt() -> (zx.status s, zx.handle:INTERRUPT irq);
    /// mmio size minus offset must be at least 512 bytes as per the SDHCI specification.
    GetMmio() -> (zx.status s, zx.handle:VMO mmio, zx.off offset);
    /// Gets a handle to the bus transaction initiator for the device. The caller
    /// receives ownership of the handle.
    GetBti(uint32 index) -> (zx.status s, zx.handle:BTI bti);

    GetBaseClock() -> (uint32 clock);

    /// returns device quirks
    GetQuirks() -> (uint64 quirks, uint64 dma_boundary_alignment);
    /// platform specific HW reset
    HwReset() -> ();
};