1 /* 2 * Copyright (c) 2026, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __SFCP_HANDLER_BUFFER_H__ 9 #define __SFCP_HANDLER_BUFFER_H__ 10 11 #include <drivers/arm/sfcp.h> 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** 18 * \brief Reserve a handler buffer capable of holding an incoming packet. 19 * 20 * \details 21 * Allocates internal storage for a message of up to \p message_size bytes, 22 * returning a handle that can later be used to access or release the buffer. 23 * This is typically invoked by the interrupt handler before handing control 24 * over to a protocol-specific handler. 25 * 26 * \param[out] buffer_handle On success, updated with the allocated buffer handle. 27 * \param[in] message_size Size in bytes required to store the incoming packet. 28 * 29 * \return SFCP_ERROR_SUCCESS on success; 30 * SFCP_ERROR_ALLOCATE_BUFFER_TOO_LARGE if the request exceeds limits; 31 * SFCP_ERROR_ALLOCATE_BUFFER_FAILED on allocation failure. 32 */ 33 enum sfcp_error_t 34 sfcp_allocate_handler_buffer(sfcp_buffer_handle_t *buffer_handle, 35 size_t message_size); 36 37 /** 38 * \brief Obtain a pointer/size to a buffered packet (handler mode). 39 * 40 * \details 41 * Provides a read-only view of a packet that was previously delivered 42 * to a handler via its \ref sfcp_buffer_handle_t. This function 43 * is typically called inside a handler or by a deferred consumer to 44 * examine the full packet in-place before deciding how to process it. 45 * 46 * \param[in] buffer_handle Handle previously provided to a message or reply handler. 47 * \param[out] buf On success, set to point to the internal packet buffer. 48 * \param[out] buf_size On success, set to the size in bytes of \p buf. 49 * 50 * \return SFCP_ERROR_SUCCESS on success; 51 * SFCP_ERROR_INVALID_BUFFER_HANDLE if \p buffer_handle is not valid; 52 * other error codes as appropriate. 53 */ 54 enum sfcp_error_t sfcp_get_handler_buffer(sfcp_buffer_handle_t buffer_handle, 55 uint8_t **buf, size_t *buf_size); 56 57 /** 58 * \brief Retire (pop) a buffered packet after handling (handler mode). 59 * 60 * \details 61 * Removes the entry associated with \p buffer_handle from the internal 62 * SFCP buffer once the packet has been successfully processed. 63 * 64 * \param[in] buffer_handle Handle previously provided to a message or reply handler. 65 * 66 * \return SFCP_ERROR_SUCCESS on success; 67 * SFCP_ERROR_INVALID_BUFFER_HANDLE if \p buffer_handle is not valid; 68 * 69 * \note After a successful pop, the handle must not be reused. 70 */ 71 enum sfcp_error_t sfcp_pop_handler_buffer(sfcp_buffer_handle_t buffer_handle); 72 73 #ifdef __cplusplus 74 } 75 #endif 76 77 #endif /* __SFCP_HANDLER_BUFFER_H__ */ 78