interface/include/tfm_ns_mailbox.h

/*
 * Copyright (c) 2019-2020, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

/* Data types and API definitions in NSPE mailbox library */

#ifndef __TFM_NS_MAILBOX_H__
#define __TFM_NS_MAILBOX_H__

#include <stdbool.h>
#include <stdint.h>
#include "tfm_mailbox.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifdef TFM_MULTI_CORE_TEST
/**
 * \brief The structure to hold the statistics result of NSPE mailbox
 */
struct ns_mailbox_stats_res_t {
    uint8_t avg_nr_slots;               /* The value before the decimal point
                                         * in the average number of NSPE
                                         * mailbox slots in use.
                                         */
    uint8_t avg_nr_slots_tenths;        /* The first digit value after the
                                         * decimal point in the average
                                         * number of NSPE mailbox slots in use.
                                         */
};
#endif

/**
 * \brief Prepare and send PSA client request to SPE via mailbox.
 *
 * \param[in] call_type         PSA client call type
 * \param[in] params            Parmaters used for PSA client call
 * \param[in] client_id         Optional client ID of non-secure caller.
 *                              It is required to identify the non-secure caller
 *                              when NSPE OS enforces non-secure task isolation.
 *
 * \retval >= 0                 The handle to the mailbox message assigned.
 * \retval < 0                  Operation failed with an error code.
 */
mailbox_msg_handle_t tfm_ns_mailbox_tx_client_req(uint32_t call_type,
                                       const struct psa_client_params_t *params,
                                       int32_t client_id);

/**
 * \brief Fetch PSA client return result.
 *
 * \param[in] handle            The handle to the mailbox message
 * \param[out] reply            The address to be written with return result.
 *
 * \retval MAILBOX_SUCCESS      Successfully get PSA client call return result.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_rx_client_reply(mailbox_msg_handle_t handle,
                                       int32_t *reply);

/**
 * \brief Check whether a specific mailbox message has been replied.
 *
 * \param[in] handle            The handle to the mailbox message
 *
 * \retval true                 The PSA client call return value is replied.
 * \retval false                The PSA client call return value is not
 *                              replied yet.
 */
bool tfm_ns_mailbox_is_msg_replied(mailbox_msg_handle_t handle);

/**
 * \brief NSPE mailbox initialization
 *
 * \param[in] queue             The base address of NSPE mailbox queue to be
 *                              initialized.
 *
 * \retval MAILBOX_SUCCESS      Operation succeeded.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue);

#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
/**
 * \brief Get the handle of the current non-secure task executing mailbox
 *        functionalities
 *
 * \note This function should be implemented according to platform, NS OS
 *       and actual use scenario.
 *       This function can be ignored or return NULL if sleep/wake-up mechanism
 *       is not required in PSA Client API implementation.
 *
 * \return Return the handle of task.
 */
const void *tfm_ns_mailbox_get_task_handle(void);
#else
static inline const void *tfm_ns_mailbox_get_task_handle(void)
{
    return NULL;
}
#endif

/**
 * \brief Fetch the handle to the first replied mailbox message in the NSPE
 *        mailbox queue.
 *        This function is intended to be called inside platform specific
 *        notification IRQ handler.
 *
 * \note The replied status of the fetched mailbox message will be cleaned after
 *       the message is fetched. When this function is called again, it fetches
 *       the next replied mailbox message from the NSPE mailbox queue.
 *
 * \return Return the handle to the first replied mailbox message in the
 *         queue.
 *         Return \ref MAILBOX_MSG_NULL_HANDLE if no mailbox message is replied.
 */
mailbox_msg_handle_t tfm_ns_mailbox_fetch_reply_msg_isr(void);

/**
 * \brief Return the handle of owner task of a mailbox message according to the
 *        \ref mailbox_msg_handle_t
 *
 * \param[in] handle            The handle of mailbox message.
 *
 * \return Return the handle value of the owner task.
 */
const void *tfm_ns_mailbox_get_msg_owner(mailbox_msg_handle_t handle);

#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
/**
 * \brief Wait for the reply returned from SPE to the mailbox message specified
 *        by handle
 *
 * \param[in] handle            The handle of mailbox message.
 *
 * \retval MAILBOX_SUCCESS      Return from waiting successfully.
 * \retval Other return code    Failed to wait with an error code.
 */
int32_t tfm_ns_mailbox_wait_reply(mailbox_msg_handle_t handle);
#endif

/**
 * \brief Platform specific NSPE mailbox initialization.
 *        Invoked by \ref tfm_ns_mailbox_init().
 *
 * \param[in] queue             The base address of NSPE mailbox queue to be
 *                              initialized.
 *
 * \retval MAILBOX_SUCCESS      Operation succeeded.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue);

/**
 * \brief Notify SPE to deal with the PSA client call sent via mailbox
 *
 * \note The implementation depends on platform specific hardware and use case.
 *
 * \retval MAILBOX_SUCCESS      Operation succeeded.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_hal_notify_peer(void);

/**
 * \brief Enter critical section of NSPE mailbox.
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_enter_critical(void);

/**
 * \brief Exit critical section of NSPE mailbox.
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_exit_critical(void);

/**
 * \brief Enter critical section of NSPE mailbox in IRQ handler.
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_enter_critical_isr(void);

/**
 * \brief Enter critical section of NSPE mailbox in IRQ handler
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_exit_critical_isr(void);

#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
/**
 * \brief Performs platform and NS OS specific waiting mechanism to wait for
 *        the reply of the specified mailbox message to be returned from SPE.
 *
 * \note This function is implemented by platform and NS OS specific waiting
 *       mechanism accroding to use scenario.
 *
 * \param[in] handle            The handle of mailbox message.
 */
void tfm_ns_mailbox_hal_wait_reply(mailbox_msg_handle_t handle);
#endif

#ifdef TFM_MULTI_CORE_TEST
/**
 * \brief Initialize the statistics module in TF-M NSPE mailbox.
 *
 * \note This function is only available when multi-core tests are enabled.
 */
void tfm_ns_mailbox_tx_stats_init(void);

/**
 * \brief Calculate the average number of used NS mailbox queue slots each time
 *        NS task requires a queue slot to submit mailbox message, which is
 *        recorded in NS mailbox statisitics module.
 *
 * \note This function is only available when multi-core tests are enabled.
 *
 * \param[in] stats_res         The buffer to be written with
 *                              \ref ns_mailbox_stats_res_t.
 *
 * \return Return the calculation result.
 */
void tfm_ns_mailbox_stats_avg_slot(struct ns_mailbox_stats_res_t *stats_res);
#endif

#ifdef __cplusplus
}
#endif

#endif /* __TFM_NS_MAILBOX_H__ */