1 /*
2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6 
7 /*******************************************************************************************************************//**
8  * @ingroup RENESAS_INTERFACES
9  * @defgroup MHU_API MHU Interface (for secure and non secure channels)
10  * @brief Interface for Message Handling Unit
11  *
12  * @section MHU_API_SUMMARY Summary
13  * The Message Handling Unit interface provides a common API for MHU HAL drivers.
14  * The Message Handling Unit interface supports:
15  *        - Message communication between Cortex-A55 and Cortex-M33.
16  *        - 32-bit data can be communicated between CPUs via shared memory.
17  *
18  * Implemented by:
19  * - @ref MHU_S
20  * - @ref MHU_NS
21  *
22  * @{
23  **********************************************************************************************************************/
24 
25 /***********************************************************************************************************************
26  * Includes
27  **********************************************************************************************************************/
28 
29 /* Register definitions, common services and error codes. */
30 #include "bsp_api.h"
31 
32 #ifndef R_MHU_API_H
33  #define R_MHU_API_H
34 
35 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */
36 FSP_HEADER
37 
38 /**********************************************************************************************************************
39  * Macro definitions
40  **********************************************************************************************************************/
41 
42 /**********************************************************************************************************************
43  * Typedef definitions
44  **********************************************************************************************************************/
45 
46 typedef enum e_mhu_send_type
47 {
48     MHU_SEND_TYPE_MSG = 0,             ///< Channel for sending "message" and receiving "response".
49     MHU_SEND_TYPE_RSP,                 ///< Channel for sending "response" and receiving "message".
50 } mhu_send_type_t;
51 
52 /** MHU callback parameter definition */
53 typedef struct st_mhu_callback_args
54 {
55     /** Placeholder for user data.  Set in @ref mhu_api_t::open function in @ref mhu_cfg_t. */
56     void const * p_context;
57     uint32_t     channel;              ///< Channel where the receive interrupt occurred.
58     uint32_t     msg;                  ///< 32-bit received data.
59 } mhu_callback_args_t;
60 
61 /** MHU configuration block */
62 typedef struct st_mhu_cfg
63 {
64     /** Generic configuration */
65     uint32_t  channel;                                 ///< Identifier recognizable by implementation
66     uint8_t   rx_ipl;                                  ///< Receive interrupt priority
67     IRQn_Type rx_irq;                                  ///< Receive interrupt ID
68 
69     /** Parameters to control software behavior */
70     void (* p_callback)(mhu_callback_args_t * p_args); ///< Pointer to callback function
71 
72     void const * p_shared_memory;                      ///< Pointer to 64-bit send/receive data buffer.
73 
74     /** Placeholder for user data.  Passed to the user callback in @ref mhu_callback_args_t. */
75     void const * p_context;
76 } mhu_cfg_t;
77 
78 /** MHU control block.  Allocate an instance specific control block to pass into the MHU API calls.
79  * @par Implemented as
80  * - mhu_instance_ctrl_t
81  */
82 typedef void mhu_ctrl_t;
83 
84 /** Interface definition for MHU */
85 typedef struct st_mhu_api
86 {
87     /** Opens the MHU driver and initializes the hardware.
88      * @par Implemented as
89      * - @ref R_MHU_S_Open()
90      * - @ref R_MHU_NS_Open()
91      *
92      * @param[in] p_ctrl    Pointer to control block. Must be declared by user. Elements are set here.
93      * @param[in] p_cfg     Pointer to configuration structure.
94      */
95     fsp_err_t (* open)(mhu_ctrl_t * const p_ctrl, mhu_cfg_t const * const p_cfg);
96 
97     /** Performs a send operation on an MHU device.
98      * @par Implemented as
99      * - @ref R_MHU_S_MsgSend()
100      * - @ref R_MHU_NS_MsgSend()
101      *
102      * @param[in] p_ctrl    Pointer to control block set in mhu_api_t::open call.
103      * @param[in] msg       32bit send data.
104      */
105     fsp_err_t (* msgSend)(mhu_ctrl_t * const p_ctrl, uint32_t const msg);
106 
107     /**
108      * Specify callback function and optional context pointer and working memory pointer.
109      * @par Implemented as
110      * - @ref R_MHU_S_CallbackSet()
111      * - @ref R_MHU_NS_CallbackSet()
112      *
113      * @param[in]   p_ctrl                   Control block set in @ref mhu_api_t::open call for this channel.
114      * @param[in]   p_callback               Callback function to register
115      * @param[in]   p_context                Pointer to send to callback function
116      * @param[in]   p_callback_memory        Pointer to volatile memory where callback structure can be allocated.
117      *                                       Callback arguments allocated here are only valid during the callback.
118      */
119     fsp_err_t (* callbackSet)(mhu_ctrl_t * const p_api_ctrl, void (* p_callback) (mhu_callback_args_t *),
120                               void const * const p_context, mhu_callback_args_t * const p_callback_memory);
121 
122     /** Closes the driver and releases the MHU device.
123      * @par Implemented as
124      * - @ref R_MHU_S_Close()
125      * - @ref R_MHU_NS_Close()
126      *
127      * @param[in] p_ctrl    Pointer to control block set in mhu_api_t::open call.
128      */
129     fsp_err_t (* close)(mhu_ctrl_t * const p_ctrl);
130 } mhu_api_t;
131 
132 /** This structure encompasses everything that is needed to use an instance of this interface. */
133 typedef struct st_mhu_instance
134 {
135     mhu_ctrl_t      * p_ctrl;          ///< Pointer to the control structure for this instance
136     mhu_cfg_t const * p_cfg;           ///< Pointer to the configuration structure for this instance
137     mhu_api_t const * p_api;           ///< Pointer to the API structure for this instance
138 } mhu_instance_t;
139 
140 /******************************************************************************************************************//**
141  * @} (end addtogroup MHU_API)
142  *********************************************************************************************************************/
143 
144 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */
145 FSP_FOOTER
146 
147 #endif                                 /* R_MHU_API_H */
148