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
18 extern "C" {
19 #endif // __cplusplus
20 
21 /**
22  * Inbound and outbound range for DOE Mailbox.
23  */
24 typedef 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  */
40 typedef 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  */
52 OT_WARN_UNUSED_RESULT
53 dif_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  */
63 OT_WARN_UNUSED_RESULT
64 dif_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  */
73 OT_WARN_UNUSED_RESULT
74 dif_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  */
85 OT_WARN_UNUSED_RESULT
86 dif_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  */
105 OT_WARN_UNUSED_RESULT
106 dif_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  */
116 OT_WARN_UNUSED_RESULT
117 dif_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_
Return to OpenTitan Documentation