sdk/banjo/fuchsia.hardware.shareddma/shareddma.fidl

// Copyright 2019 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.shareddma;
using zx;

type DmaType = strict enum : uint32 {
    REGULAR = 0x1;
    CYCLIC = 0x2;
};

type DmaState = strict enum : uint32 {
    COMPLETED = 0x1;
    FAILED = 0x2;
};

@transport("Banjo")
@banjo_layout("ddk-callback")
closed protocol DmaNotifyCallback {
    strict Callback(struct {
        state DmaState;
    }) -> ();
};

@transport("Banjo")
@banjo_layout("ddk-protocol")
closed protocol SharedDma {

    /// Initializes and provides a VMO for memory source or destination.
    /// Only supports device to memory and memory to device DMAs.
    /// The provided id is opaque and HW specific.  The id implicitly defines the direction of the
    /// DMA (biderectional DMAs are not supported yet).  Transfer sizes and alignment are
    /// managed within the shared DMA driver.
    strict InitializeAndGetBuffer(struct {
        channel_id uint32;
        type DmaType;
        size uint32;
    }) -> (resource struct {
        s zx.Status;
        vmo zx.Handle:VMO;
    });

    /// Start DMA
    strict Start(struct {
        channel_id uint32;
    });

    /// Stop DMA
    strict Stop(struct {
        channel_id uint32;
    });

    /// Returns the current position within memory where is the DMA has written to or read from.
    strict GetBufferPosition(struct {
        channel_id uint32;
    }) -> (struct {
        position uint32;
    });

    /// It must always be assumed that the DMA is in the process of transfering this amount
    /// of data (accounting for warp around) into or from memory, hence for:
    /// Device to memory DMAs, it is not safe to read this amount past the buffer position.
    /// Memory to device DMAs, it is not safe to write this amount before the buffer position.
    strict GetTransferSize(struct {
        channel_id uint32;
    }) -> (struct {
        size_per_transfer uint32;
    });

    /// Specifies a callback for notifications of state change.
    /// Notification for DmaType CYCLIC with DmaState COMPLETE are expected periodically;
    /// size_per_notification indicates how often (in bytes) the notifications are delivered.
    strict SetNotifyCallback(resource struct {
        channel_id uint32;
        cb client_end:DmaNotifyCallback;
    }) -> (struct {
        s zx.Status;
        size_per_notification uint32;
    });
};