/*
 * Copyright 2023 Google LLC
 * Copyright lowRISC contributors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_I2S_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_I2S_H_

// #error "This file is a template, and not real code."

/**
 * @file
 * @brief <a href="/hw/ip/i2s/doc/">I2S Audio</a> Device Interface Functions
 */

#include <stdint.h>

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

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

/**
 * Runtime configuration for I2S Audio.
 *
 * This struct describes (SOFTWARE) runtime information for one-time
 * configuration of the hardware.
 */
typedef struct dif_i2s_config {
  // Fields, if necessary.
} dif_i2s_config_t;


/**
 * Parameters for a I2S Audio transaction.
 */
typedef struct dif_i2s_transaction {
  // Your fields here.
} dif_i2s_transaction_t;

/**
 * An output location for a I2S Audio transaction.
 */
typedef struct dif_i2s_output {
  // Your fields here.
} dif_i2s_output_t;

/**
 * Configures I2S Audio with runtime information.
 *
 * This function should only need to be called once for the lifetime of
 * `handle`.
 *
 * @param i2s A I2S Audio handle.
 * @param config Runtime configuration parameters.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_i2s_configure(
  const dif_i2s_t *i2s,
  dif_i2s_config_t config);

/**
 * Begins a I2S Audio transaction.
 *
 * Each call to this function should be sequenced with a call to
 * `dif_i2s_end()`.
 *
 * @param i2s A I2S Audio handle.
 * @param transaction Transaction configuration parameters.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_i2s_start(
  const dif_i2s_t *i2s,
  dif_i2s_transaction_t transaction);

/** Ends a I2S Audio transaction, writing the results to the given output.
 *
 * @param i2s A I2S Audio handle.
 * @param output Transaction output parameters.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_i2s_end(
  const dif_i2s_t *i2s,
  dif_i2s_output_t output);

/**
 * Locks out I2S Audio functionality.
 *
 * This function is reentrant: calling it while functionality is locked will
 * have no effect and return `kDifOk`.
 *
 * @param i2s A I2S Audio handle.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_i2s_lock(
  const dif_i2s_t *i2s);

/**
 * Checks whether this I2S Audio is locked.
 *
 * @param i2s A I2S Audio 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_i2s_is_locked(
  const dif_i2s_t *i2s,
  bool *is_locked);

/**
 * Checks whether the I2S RX FIFO is empty.
 *
 * @param i2s An I2S Audio handle.
 * @param[out] empty Out-param for the empty state.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_i2s_rxfifo_empty(const dif_i2s_t *i2s, bool *empty);

/**
 * Checks whether the I2S RX FIFO is empty.
 *
 * @param i2s An I2S Audio handle.
 * @param[out] full Out-param for the full state.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_i2s_txfifo_full(const dif_i2s_t *i2s, bool *full);

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

#endif  // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_I2S_H_