Software APIs
dif_mbx.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_MBX_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_MBX_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/mbx/doc/">DOE Mailbox</a> Device Interface
11 * Functions
12 */
13#include <stdint.h>
14
15#include "sw/device/lib/dif/autogen/dif_mbx_autogen.h"
16
17#ifdef __cplusplus
18extern "C" {
19#endif // __cplusplus
20
21/**
22 * Inbound and outbound range for DOE Mailbox.
23 */
24typedef struct dif_mbx_range_config {
25 uint32_t imbx_base_addr;
26 uint32_t imbx_limit_addr;
27 uint32_t ombx_base_addr;
28 uint32_t ombx_limit_addr;
29} dif_mbx_range_config_t;
30
31/**
32 * A DOE transaction is allowed to have at maximum 1024 double words (32-bit
33 * each).
34 */
35#define DOE_MAILBOX_MAX_OBJECT_SIZE 1024
36
37/**
38 * DOE object transferred on the inbound or outbound mailbox.
39 */
40typedef struct dif_mbx_transaction {
41 uint32_t *data_dwords;
42 uint32_t nr_dwords;
43} dif_mbx_transaction_t;
44
45/**
46 * Configures the mailbox inbound and outbound ranges and validates them.
47 *
48 * @param mbx A DOE Mailbox handle.
49 * @param config Mailbox inbound and outbound range configuration.
50 * @return The result of the operation.
51 */
52OT_WARN_UNUSED_RESULT
53dif_result_t dif_mbx_range_set(const dif_mbx_t *mbx,
54 dif_mbx_range_config_t config);
55
56/**
57 * Returns whether the mailbox is busy or not.
58 *
59 * @param mbx A DOE Mailbox handle.
60 * @param[out] is_busy True if the mailbox is busy, false if not.
61 * @return The result of the operation.
62 */
63OT_WARN_UNUSED_RESULT
64dif_result_t dif_mbx_is_busy(const dif_mbx_t *mbx, bool *is_busy);
65
66/**
67 * Reads the mailbox range configuration.
68 *
69 * @param mbx A DOE Mailbox handle.
70 * @param[out] config Mailbox inbound and outbound range configuration.
71 * @return The result of the operation.
72 */
73OT_WARN_UNUSED_RESULT
74dif_result_t dif_mbx_range_get(const dif_mbx_t *mbx,
75 dif_mbx_range_config_t *config);
76
77/**
78 * Reads the DOE interrupt configuration for inter-processor interrupts (IPI).
79 *
80 * @param mbx A DOE Mailbox handle.
81 * @param[out] doe_intr_addr Mailbox interrupt address.
82 * @param[out] doe_intr_data Mailbox interrupt value.
83 * @return The result of the operation.
84 */
85OT_WARN_UNUSED_RESULT
86dif_result_t dif_mbx_ipi_configuration_get(const dif_mbx_t *mbx,
87 uint32_t *doe_intr_addr,
88 uint32_t *doe_intr_data);
89
90/**
91 * Reads the DoE Mailbox request from internal SRAM.
92 * The `request->nr_words` field specifies the maximum number of words
93 * that can be stored in the internal request array. After reading,
94 * this function updates `request->nr_words` to indicate the actual
95 * number of words read.
96 *
97 * @param mbx A handle to the DoE Mailbox.
98 * @param[out] request A pointer to the DoE object where the request data
99 * from internal SRAM will be stored.
100 * @return The result of the operation:
101 * - kDifBadArg: One or more input arguments are invalid.
102 * - kDifOutOfRange: The response exceeds the buffer size.
103 * - kDifOk: The operation was successful.
104 */
105OT_WARN_UNUSED_RESULT
106dif_result_t dif_mbx_process_request(const dif_mbx_t *mbx,
107 dif_mbx_transaction_t *request);
108
109/**
110 * Host writes the DoE Mailbox response to the internal SRAM.
111 *
112 * @param mbx A DOE Mailbox handle.
113 * @param response DOE object written to the the internal SRAM.
114 * @return The result of the operation.
115 */
116OT_WARN_UNUSED_RESULT
117dif_result_t dif_mbx_generate_response(const dif_mbx_t *mbx,
118 const dif_mbx_transaction_t response);
119
120#ifdef __cplusplus
121} // extern "C"
122#endif // __cplusplus
123
124#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_MBX_H_