blob: a362682c8259a8775e21f447c43d10c503085896 [file] [log] [blame]
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_${ip_upper}_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_${ip_upper}_H_
// This file is the "DIF Library header template", which provides a base for
// building a DIF for a new peripheral, defining all of the declarations that
// would be expected of a DIF library as described in the README.md.
//
// This file should be instantiated with the `util/make_new_dif.py` script.
//
// The script also includes additional options for controlling how the tempalte
// is instantiated. After the script runs, delete this comment, the #error
// below, and any unnecessary definitions. Remember to run clang-format!
//
// Note that this file does not parse as C.
#error "This file is a template, and not real code."
/**
* @file
* @brief <a href="/hw/ip/${ip_snake}/doc/">${periph_upper}</a> Device Interface Functions
*/
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* A toggle state: enabled, or disabled.
*
* This enum may be used instead of a `bool` when describing an enabled/disabled
* state.
*/
typedef enum dif_${ip_snake}_toggle {
/*
* The "enabled" state.
*/
kDif${ip_camel}ToggleEnabled,
/**
* The "disabled" state.
*/
kDif${ip_camel}ToggleDisabled,
} dif_${ip_snake}_toggle_t;
/**
* Hardware instantiation parameters for ${periph_lower}.
*
* This struct describes information about the underlying hardware that is
* not determined until the hardware design is used as part of a top-level
* design.
*/
typedef struct dif_${ip_snake}_params {
/**
* The base address for the ${periph_lower} hardware registers.
*/
mmio_region_t base_addr;
// Other fields, if necessary.
} dif_${ip_snake}_params_t;
/**
* Runtime configuration for ${periph_lower}.
*
* This struct describes runtime information for one-time configuration of the
* hardware.
*/
typedef struct dif_${ip_snake}_config {
// Fields, if necessary.
} dif_${ip_snake}_config_t;
/**
* A handle to ${periph_lower}.
*
* This type should be treated as opaque by users.
*/
typedef struct dif_${ip_snake} {
dif_${ip_snake}_params_t params;
// Other fields, if necessary.
} dif_${ip_snake}_t;
/**
* The result of a ${periph_lower} operation.
*/
typedef enum dif_${ip_snake}_result {
/**
* Indicates that the operation succeeded.
*/
kDif${ip_camel}Ok = 0,
/**
* Indicates some unspecified failure.
*/
kDif${ip_camel}Error = 1,
/**
* Indicates that some parameter passed into a function failed a
* precondition.
*
* When this value is returned, no hardware operations occured.
*/
kDif${ip_camel}BadArg = 2,
/**
* Indicates that this operation has been locked out, and can never
* succeed until hardware reset.
*/
// Remove this variant if you don't need it.
kDif${ip_camel}Locked = 3,
} dif_${ip_snake}_result_t;
/**
* Parameters for a ${periph_lower} transaction.
*/
typedef struct dif_${ip_snake}_transaction {
// Your fields here.
} dif_${ip_snake}_transaction_t;
/**
* An output location for a ${periph_lower} transaction.
*/
typedef struct dif_${ip_snake}_output {
// Your fields here.
} dif_${ip_snake}_output_t;
/**
* A ${periph_lower} interrupt request type.
*/
typedef enum dif_${ip_snake}_irq {
// Your IRQs here!
} dif_${ip_snake}_irq_t;
/**
* A snapshot of the enablement state of the interrupts for ${periph_lower}.
*
* This is an opaque type, to be used with the `dif_${ip_snake}_irq_disable_all()` and
* `dif_${ip_snake}_irq_restore_all()` functions.
*/
typedef uint32_t dif_${ip_snake}_irq_snapshot_t;
/**
* Creates a new handle for ${periph_lower}.
*
* This function does not actuate the hardware.
*
* @param params Hardware instantiation parameters.
* @param[out] ${handle} Out param for the initialized handle.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_init(dif_${ip_snake}_params_t params,
dif_${ip_snake}_t *${handle});
/**
* Configures ${periph_lower} with runtime information.
*
* This function should need to be called once for the lifetime of `handle`.
*
* @param ${handle} A ${periph_lower} handle.
* @param config Runtime configuration parameters.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_configure(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_config_t config);
/**
* Begins a ${periph_lower} transaction.
*
* Each call to this function should be sequenced with a call to
* `dif_${ip_snake}_end()`.
*
* @param ${handle} A ${periph_lower} handle.
* @param transaction Transaction configuration parameters.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_start(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_transaction_t transaction);
/** Ends a ${periph_lower} transaction, writing the results to the given output..
*
* @param ${handle} A ${periph_lower} handle.
* @param output Transaction output parameters.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_end(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_output_t output);
/**
* Locks out ${periph_lower} functionality.
*
* This function is reentrant: calling it while functionality is locked will
* have no effect and return `kDif${ip_camel}Ok`.
*
* @param ${handle} A ${periph_lower} handle.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_lock(const dif_${ip_snake}_t *${handle});
/**
* Checks whether this ${periph_lower} is locked.
*
* @param ${handle} A ${periph_lower} handle.
* @param[out] is_locked Out-param for the locked state.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_is_locked(const dif_${ip_snake}_t *${handle},
bool *is_locked);
/**
* Returns whether a particular interrupt is currently pending.
*
* @param ${handle} A ${periph_lower} handle.
* @param irq An interrupt type.
* @param[out] is_pending Out-param for whether the interrupt is pending.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_is_pending(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_irq_t irq,
bool *is_pending);
/**
* Acknowledges a particular interrupt, indicating to the hardware that it has
* been successfully serviced.
*
* @param ${handle} A ${periph_lower} handle.
* @param irq An interrupt type.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_acknowledge(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_irq_t irq);
/**
* Checks whether a particular interrupt is currently enabled or disabled.
*
* @param ${handle} A ${periph_lower} handle.
* @param irq An interrupt type.
* @param[out] state Out-param toggle state of the interrupt.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_get_enabled(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_irq_t irq,
dif_${ip_snake}_toggle_t *state);
/**
* Sets whether a particular interrupt is currently enabled or disabled.
*
* @param ${handle} A ${periph_lower} handle.
* @param irq An interrupt type.
* @param state The new toggle state for the interrupt.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_set_enabled(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_irq_t irq,
dif_${ip_snake}_toggle_t state);
/**
* Forces a particular interrupt, causing it to be serviced as if hardware had
* asserted it.
*
* @param ${handle} A ${periph_lower} handle.
* @param irq An interrupt type.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_force(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_irq_t irq);
/**
* Disables all interrupts, optionally snapshotting all toggle state for later
* restoration.
*
* @param ${handle} A ${periph_lower} handle.
* @param[out] snapshot Out-param for the snapshot; may be `NULL`.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_disable_all(const dif_${ip_snake}_t *${handle},
dif_${ip_snake}_irq_snapshot_t *snapshot);
/**
* Restores interrupts from the given snapshot.
*
* This function can be used with `dif_${ip_snake}_irq_disable_all()` to temporary
* interrupt save-and-restore.
*
* @param ${handle} A ${periph_lower} handle.
* @param snapshot A snapshot to restore from.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
dif_${ip_snake}_result_t dif_${ip_snake}_irq_restore_all(const dif_${ip_snake}_t *${handle},
const dif_${ip_snake}_irq_snapshot_t *snapshot);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_${ip_upper}_H_