1 /* 2 * Copyright (c) 2023, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef RPC_CALLER_SESSION_H 8 #define RPC_CALLER_SESSION_H 9 10 #include "rpc_caller.h" 11 #include "rpc_status.h" 12 #include "rpc_uuid.h" 13 #include <stdbool.h> 14 #include <stddef.h> 15 #include <stdint.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 typedef void *rpc_call_handle; 22 23 enum rpc_caller_memory_policy { 24 alloc_for_each_call = 0, 25 alloc_for_session, 26 }; 27 28 /** 29 * @brief RPC caller session 30 * 31 * Builds a session on top of the rpc_caller_interface. It provides high level functions for service 32 * caller implementations and for prior service discovery. 33 */ 34 struct rpc_caller_session { 35 /** Caller interface */ 36 struct rpc_caller_interface *caller; 37 38 /** Shared memory instance for the exchanging of RPC request and response parameters. */ 39 struct rpc_caller_shared_memory shared_memory; 40 41 /** Controls how and when the shared memory is allocated for the RPC calls. */ 42 enum rpc_caller_memory_policy shared_memory_policy; 43 44 /** 45 * Indicates if a call transaction has been started by the begin function but was not 46 * finished yet (i.e. end was not called). 47 */ 48 bool is_call_transaction_in_progress; 49 50 /** 51 * Stores the request length of the current transaction. Its value is set by the begin 52 * function and then used in the invoke step. 53 */ 54 size_t request_length; 55 }; 56 57 /** 58 * @brief 59 * 60 * @param session 61 * @param caller 62 * @param service_uuid 63 * @param endpoint_id 64 * @param shared_memory_size 65 * @return RPC_CALLER_EXPORTED 66 */ 67 RPC_CALLER_EXPORTED 68 rpc_status_t rpc_caller_session_open(struct rpc_caller_session *session, 69 struct rpc_caller_interface *caller, 70 const struct rpc_uuid *service_uuid, 71 uint16_t endpoint_id, 72 size_t shared_memory_size); 73 74 /** 75 * @brief 76 * 77 * @param session 78 * @param caller 79 * @param service_uuid 80 * @param shared_memory_size 81 * @return RPC_CALLER_EXPORTED 82 */ 83 RPC_CALLER_EXPORTED 84 rpc_status_t rpc_caller_session_find_and_open(struct rpc_caller_session *session, 85 struct rpc_caller_interface *caller, 86 const struct rpc_uuid *service_uuid, 87 size_t shared_memory_size); 88 89 /** 90 * @brief Closes the RPC caller session 91 * 92 * @param session Caller session instance 93 * @return RPC_CALLER_EXPORTED 94 */ 95 RPC_CALLER_EXPORTED 96 rpc_status_t rpc_caller_session_close(struct rpc_caller_session *session); 97 98 /** 99 * @brief Begins an RPC call 100 * 101 * The function returns a buffer where the service caller can build the request. 102 * 103 * @param session Caller session instance 104 * @param request_buffer Pointer of the request buffer 105 * @param request_length Request length 106 * @param response_max_length Expected maximal length of the response 107 * @return rpc_call_handle Handle of the started call 108 */ 109 RPC_CALLER_EXPORTED 110 rpc_call_handle rpc_caller_session_begin(struct rpc_caller_session *session, 111 uint8_t **request_buffer, 112 size_t request_length, 113 size_t response_max_length); 114 115 /** 116 * @brief Invoke phase of the RPC call 117 * 118 * Invokes the call on the remote side and returns the response buffer and service status. The 119 * service caller can parse the response from the response buffer. 120 * After this call the request buffer is not available for the service caller. 121 * 122 * @param handle RPC call handle 123 * @param opcode The opcode of the remote function 124 * @param response_buffer Pointer of the response buffer 125 * @param response_length Length of the response buffer 126 * @param service_status Service specific status code 127 * @return RPC_CALLER_EXPORTED 128 */ 129 RPC_CALLER_EXPORTED 130 rpc_status_t rpc_caller_session_invoke(rpc_call_handle handle, uint32_t opcode, 131 uint8_t **response_buffer, 132 size_t *response_length, 133 service_status_t *service_status); 134 135 /** 136 * @brief Ends the RPC call 137 * 138 * Indicates if the response has been parsed by the service calls and the RPC session can free the 139 * response buffer. 140 * 141 * @param handle RPC call handle 142 * @return RPC_CALLER_EXPORTED 143 */ 144 RPC_CALLER_EXPORTED 145 rpc_status_t rpc_caller_session_end(rpc_call_handle handle); 146 147 148 #ifdef __cplusplus 149 } 150 #endif 151 152 #endif /* RPC_CALLER_SESSION_H */ 153