interface/include/psa/service.h

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

#ifndef __PSA_SERVICE_H__
#define __PSA_SERVICE_H__

#include <stddef.h>
#include <stdint.h>

#include "psa/client.h"
#include "psa_config.h"
#include "psa/error.h"
#include "psa/framework_feature.h"

#ifdef __cplusplus
extern "C" {
#endif

/********************** PSA Secure Partition Macros and Types ****************/

/**
 * A timeout value that requests a polling wait operation.
 */
#define PSA_POLL                (0x00000000u)

/**
 * A timeout value that requests a blocking wait operation.
 */
#define PSA_BLOCK               (0x80000000u)

/**
 * A mask value that includes all Secure Partition signals.
 */
#define PSA_WAIT_ANY            (0xFFFFFFFFu)

/**
 * The signal number for the Secure Partition doorbell.
 */
#define PSA_DOORBELL            (0x00000008u)

/* PSA message types */
/* An IPC message type that indicates a new connection. */
#define PSA_IPC_CONNECT         (-1)
/* An IPC message type that indicates the end of a connection. */
#define PSA_IPC_DISCONNECT      (-2)

/* FLIH return types */
#define PSA_FLIH_NO_SIGNAL      ((psa_flih_result_t) 0)
#define PSA_FLIH_SIGNAL         ((psa_flih_result_t) 1)

/* Store a set of one or more Secure Partition signals */
typedef uint32_t psa_signal_t;

/* A type used to temporarily store a previous interrupt state. */
typedef uint32_t psa_irq_status_t;

/* The type of the return value from an FLIH function */
typedef uint32_t psa_flih_result_t;

/**
 * Describe a message received by an RoT Service after calling \ref psa_get().
 */
typedef struct psa_msg_t {
    int32_t type;              /* One of the following values:
                                 * \ref PSA_IPC_CONNECT
                                 * >= 0
                                 * \ref PSA_IPC_DISCONNECT
                                 */
    psa_handle_t handle;        /* A reference generated by the SPM to the
                                 * message returned by psa_get().
                                 */
    int32_t client_id;          /*
                                 * Partition ID of the sender of the
                                 * message:
                                 *  - secure partition id;
                                 *  - non secure client endpoint id.
                                 */
    void *rhandle;              /* Be useful for binding a connection to some
                                 * application-specific data or function
                                 * pointer within the RoT Service
                                 * implementation.
                                 */
    size_t in_size[PSA_MAX_IOVEC]; /* Provide the size of each client input
                                    * vector in bytes.
                                    */
    size_t out_size[PSA_MAX_IOVEC];/* Provide the size of each client output
                                    * vector in bytes.
                                    */
} psa_msg_t;

/************************* PSA Secure Partition API **************************/

/**
 * \brief Return the Secure Partition interrupt signals that have been asserted
 *        from a subset of signals provided by the caller.
 *
 * \param[in] signal_mask       A set of signals to query. Signals that are not
 *                              in this set will be ignored.
 * \param[in] timeout           Specify either blocking \ref PSA_BLOCK or
 *                              polling \ref PSA_POLL operation.
 *
 * \retval >0                   At least one signal is asserted.
 * \retval 0                    No signals are asserted. This is only seen when
 *                              a polling timeout is used.
 */
psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);

/**
 * \brief Retrieve the message which corresponds to a given RoT Service signal
 *        and remove the message from the RoT Service queue.
 *
 * \param[in] signal            The signal value for an asserted RoT Service.
 * \param[out] msg              Pointer to \ref psa_msg_t object for receiving
 *                              the message.
 *
 * \retval PSA_SUCCESS          Success, *msg will contain the delivered
 *                              message.
 * \retval PSA_ERROR_DOES_NOT_EXIST Message could not be delivered.
 * \retval "PROGRAMMER ERROR"   The call is invalid because one or more of the
 *                              following are true:
 * \arg                           signal has more than a single bit set.
 * \arg                           signal does not correspond to an RoT Service.
 * \arg                           The RoT Service signal is not currently
 *                                asserted.
 * \arg                           The msg pointer provided is not a valid memory
 *                                reference.
 */
psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg);

/**
 * \brief Associate some RoT Service private data with a client connection.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] rhandle           Reverse handle allocated by the RoT Service.
 *
 * \retval void                 Success, rhandle will be provided with all
 *                              subsequent messages delivered on this
 *                              connection.
 * \retval "PROGRAMMER ERROR"   msg_handle is invalid.
 */
void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);

/**
 * \brief Read a message parameter or part of a message parameter from a client
 *        input vector.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] invec_idx         Index of the input vector to read from. Must be
 *                              less than \ref PSA_MAX_IOVEC.
 * \param[out] buffer           Buffer in the Secure Partition to copy the
 *                              requested data to.
 * \param[in] num_bytes         Maximum number of bytes to be read from the
 *                              client input vector.
 *
 * \retval >0                   Number of bytes copied.
 * \retval 0                    There was no remaining data in this input
 *                              vector.
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a
 *                                \ref PSA_IPC_CALL message.
 * \arg                           invec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 * \arg                           the memory reference for buffer is invalid or
 *                                not writable.
 */
size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
                void *buffer, size_t num_bytes);

/**
 * \brief Skip over part of a client input vector.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] invec_idx         Index of input vector to skip from. Must be
 *                              less than \ref PSA_MAX_IOVEC.
 * \param[in] num_bytes         Maximum number of bytes to skip in the client
 *                              input vector.
 *
 * \retval >0                   Number of bytes skipped.
 * \retval 0                    There was no remaining data in this input
 *                              vector.
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a request
 *                                message.
 * \arg                           invec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 */
size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx, size_t num_bytes);

/**
 * \brief Write a message response to a client output vector.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[out] outvec_idx       Index of output vector in message to write to.
 *                              Must be less than \ref PSA_MAX_IOVEC.
 * \param[in] buffer            Buffer with the data to write.
 * \param[in] num_bytes         Number of bytes to write to the client output
 *                              vector.
 *
 * \retval void                 Success
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a request
 *                                message.
 * \arg                           outvec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 * \arg                           The memory reference for buffer is invalid.
 * \arg                           The call attempts to write data past the end
 *                                of the client output vector.
 */
void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
               const void *buffer, size_t num_bytes);

/**
 * \brief Complete handling of a specific message and unblock the client.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] status            Message result value to be reported to the
 *                              client.
 *
 * \retval void                 Success.
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                         msg_handle is invalid.
 * \arg                         An invalid status code is specified for the
 *                              type of message.
 */
void psa_reply(psa_handle_t msg_handle, psa_status_t status);

/**
 * \brief Send a PSA_DOORBELL signal to a specific Secure Partition.
 *
 * \param[in] partition_id      Secure Partition ID of the target partition.
 *
 * \retval void                 Success.
 * \retval "PROGRAMMER ERROR"   partition_id does not correspond to a Secure
 *                              Partition.
 */
void psa_notify(int32_t partition_id);

/**
 * \brief Clear the PSA_DOORBELL signal.
 *
 * \retval void                 Success.
 * \retval "PROGRAMMER ERROR"   The Secure Partition's doorbell signal is not
 *                              currently asserted.
 */
void psa_clear(void);

/**
 * \brief Inform the SPM that an interrupt has been handled (end of interrupt).
 *
 * \param[in] irq_signal        The interrupt signal that has been processed.
 *
 * \retval void                 Success.
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           irq_signal is not an interrupt signal.
 * \arg                           irq_signal indicates more than one signal.
 * \arg                           irq_signal is not currently asserted.
 * \arg                           The interrupt is not using SLIH.
 */
void psa_eoi(psa_signal_t irq_signal);

/**
 * \brief Terminate execution within the calling Secure Partition and will not
 *        return.
 *
 * \retval "Does not return"
 */
void psa_panic(void);

/**
 * \brief Enable an interrupt.
 *
 * \param[in] irq_signal The signal for the interrupt to be enabled.
 *                       This must have a single bit set, which must be the
 *                       signal value for an interrupt in the calling Secure
 *                       Partition.
 *
 * \retval void
 * \retval "PROGRAMMER ERROR" If one or more of the following are true:
 * \arg                       \a irq_signal is not an interrupt signal.
 * \arg                       \a irq_signal indicates more than one signal.
 */
void psa_irq_enable(psa_signal_t irq_signal);

/**
 * \brief Disable an interrupt and return the status of the interrupt prior to
 *        being disabled by this call.
 *
 * \param[in] irq_signal The signal for the interrupt to be disabled.
 *                       This must have a single bit set, which must be the
 *                       signal value for an interrupt in the calling Secure
 *                       Partition.
 *
 * \retval 0                  The interrupt was disabled prior to this call.
 *         1                  The interrupt was enabled prior to this call.
 * \retval "PROGRAMMER ERROR" If one or more of the following are true:
 * \arg                       \a irq_signal is not an interrupt signal.
 * \arg                       \a irq_signal indicates more than one signal.
 *
 * \note The current implementation always return 1. Do not use the return.
 */
psa_irq_status_t psa_irq_disable(psa_signal_t irq_signal);

/**
 * \brief Reset the signal for an interrupt that is using FLIH handling.
 *
 * \param[in] irq_signal    The interrupt signal to be reset.
 *                          This must have a single bit set, corresponding to a
 *                          currently asserted signal for an interrupt that is
 *                          defined to use FLIH handling.
 *
 * \retval void
 * \retval "Programmer Error" if one or more of the following are true:
 * \arg                       \a irq_signal is not a signal for an interrupt
 *                            that is specified with FLIH handling in the Secure
 *                            Partition manifest.
 * \arg                       \a irq_signal indicates more than one signal.
 * \arg                       \a irq_signal is not currently asserted.
 */
void psa_reset_signal(psa_signal_t irq_signal);

#if PSA_FRAMEWORK_HAS_MM_IOVEC

/**
 * \brief Map a client input vector for direct access by a Secure Partition RoT
 *        Service.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] invec_idx         Index of input vector to map. Must be
 *                              less than \ref PSA_MAX_IOVEC.
 *
 * \retval                      A pointer to the input vector data.
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           MM-IOVEC has not been enabled for the RoT
 *                                Service that received the message.
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a request
 *                                message.
 * \arg                           invec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 * \arg                           The input vector has length zero.
 * \arg                           The input vector has already been mapped using
 *                                psa_map_invec().
 * \arg                           The input vector has already been accessed
 *                                using psa_read() or psa_skip().
 */
const void *psa_map_invec(psa_handle_t msg_handle, uint32_t invec_idx);

/**
 * \brief Unmap a previously mapped client input vector from a Secure Partition
 *        RoT Service.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] invec_idx         Index of input vector to map. Must be
 *                              less than \ref PSA_MAX_IOVEC.
 *
 * \retval void
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a request
 *                                message.
 * \arg                           invec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 * \arg                           The input vector has not been mapped by a call
 *                                to psa_map_invec().
 * \arg                           The input vector has already been unmapped by
 *                                a call to psa_unmap_invec().
 */
void psa_unmap_invec(psa_handle_t msg_handle, uint32_t invec_idx);

/**
 * \brief Map a client output vector for direct access by a Secure Partition RoT
 *        Service.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] outvec_idx        Index of output vector to map. Must be
 *                              less than \ref PSA_MAX_IOVEC.
 *
 * \retval                      A pointer to the output vector data.
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           MM-IOVEC has not been enabled for the RoT
 *                                Service that received the message.
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a request
 *                                message.
 * \arg                           outvec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 * \arg                           The output vector has length zero.
 * \arg                           The output vector has already been mapped
 *                                using psa_map_outvec().
 * \arg                           The output vector has already been accessed
 *                                using psa_write().
 */
void *psa_map_outvec(psa_handle_t msg_handle, uint32_t outvec_idx);

/**
 * \brief Unmap a previously mapped client output vector from a Secure Partition
 *        RoT Service.
 *
 * \param[in] msg_handle        Handle for the client's message.
 * \param[in] outvec_idx        Index of output vector to map. Must be
 *                              less than \ref PSA_MAX_IOVEC.
 * \param[in] len               The number of bytes written to the output
 *                              vector. This must be less than or equal to the
 *                              size of the output vector.
 *
 * \retval void
 * \retval "PROGRAMMER ERROR"   The call is invalid, one or more of the
 *                              following are true:
 * \arg                           msg_handle is invalid.
 * \arg                           msg_handle does not refer to a request
 *                                message.
 * \arg                           outvec_idx is equal to or greater than
 *                                \ref PSA_MAX_IOVEC.
 * \arg                           The output vector has not been mapped by a
 *                                call to psa_map_outvec().
 * \arg                           The output vector has already been unmapped by
 *                                a call to psa_unmap_outvec().
 */
void psa_unmap_outvec(psa_handle_t msg_handle, uint32_t outvec_idx, size_t len);

#endif /* PSA_FRAMEWORK_HAS_MM_IOVEC */

#ifdef __cplusplus
}
#endif

#endif /* __PSA_SERVICE_H__ */