// 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;

type SdhciQuirk = strict enum : 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 capabilities 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")
@banjo_layout("ddk-protocol")
closed protocol Sdhci {
    // TODO: should be replaced with a generic busdev mechanism
    strict GetInterrupt() -> (resource struct {
        s zx.Status;
        irq zx.Handle:INTERRUPT;
    });
    /// mmio size minus offset must be at least 512 bytes as per the SDHCI specification.
    strict GetMmio() -> (resource struct {
        s zx.Status;
        mmio zx.Handle:VMO;
        offset zx.Off;
    });
    /// Gets a handle to the bus transaction initiator for the device. The caller
    /// receives ownership of the handle.
    strict GetBti(struct {
        index uint32;
    }) -> (resource struct {
        s zx.Status;
        bti zx.Handle:BTI;
    });

    strict GetBaseClock() -> (struct {
        clock uint32;
    });

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