sw/device/lib/dif/dif_dma.h

// Copyright 2023 Google LLC.
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0

#ifndef MATCHA_SW_DEVICE_LIB_DIF_DIF_DMA_H_
#define MATCHA_SW_DEVICE_LIB_DIF_DIF_DMA_H_

/**
 * @file
 * @brief <a href="/hw/ip/dma/doc/">System DMA</a> Device Interface Functions
 */

#include <stdint.h>

#include "sw/device/lib/dif/autogen/dif_dma_autogen.h"

#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus

dif_result_t dif_dma_read_config(const dif_dma_t *dma, uint32_t *config);
dif_result_t dif_dma_enable_loop(const dif_dma_t *dma);
dif_result_t dif_dma_begin(const dif_dma_t *dma);
dif_result_t dif_dma_configure_reader(const dif_dma_t *dma, uint32_t start_addr,
                                      uint32_t line_length, uint32_t line_count,
                                      uint32_t line_stride);
dif_result_t dif_dma_configure_writer(const dif_dma_t *dma, uint32_t start_addr,
                                      uint32_t line_length, uint32_t line_count,
                                      uint32_t line_stride);

/**
 * Runtime configuration for System DMA.
 *
 * This struct describes (SOFTWARE) runtime information for one-time
 * configuration of the hardware.
 */
typedef struct dif_dma_config {
  // Fields, if necessary.
} dif_dma_config_t;

/**
 * Parameters for a System DMA transaction.
 */
typedef struct dif_dma_transaction {
  // Your fields here.
} dif_dma_transaction_t;

/**
 * An output location for a System DMA transaction.
 */
typedef struct dif_dma_output {
  // Your fields here.
} dif_dma_output_t;

/**
 * Configures System DMA with runtime information.
 *
 * This function should only need to be called once for the lifetime of
 * `handle`.
 *
 * @param dma A System DMA handle.
 * @param config Runtime configuration parameters.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_dma_configure(const dif_dma_t *dma, dif_dma_config_t config);

/**
 * Begins a System DMA transaction.
 *
 * Each call to this function should be sequenced with a call to
 * `dif_dma_end()`.
 *
 * @param dma A System DMA handle.
 * @param transaction Transaction configuration parameters.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_dma_start(const dif_dma_t *dma,
                           dif_dma_transaction_t transaction);

/** Ends a System DMA transaction, writing the results to the given output.
 *
 * @param dma A System DMA handle.
 * @param output Transaction output parameters.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_dma_end(const dif_dma_t *dma, dif_dma_output_t output);

/**
 * Locks out System DMA functionality.
 *
 * This function is reentrant: calling it while functionality is locked will
 * have no effect and return `kDifOk`.
 *
 * @param dma A System DMA handle.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_dma_lock(const dif_dma_t *dma);

/**
 * Checks whether this System DMA is locked.
 *
 * @param dma A System DMA handle.
 * @param[out] is_locked Out-param for the locked state.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_dma_is_locked(const dif_dma_t *dma, bool *is_locked);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  // MATCHA_SW_DEVICE_LIB_DIF_DIF_DMA_H_