1 /* 2 * Copyright (c) 2026, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __SFCP_LINK_HAL_H__ 9 #define __SFCP_LINK_HAL_H__ 10 11 #include <stdbool.h> 12 #include <stddef.h> 13 #include <stdint.h> 14 15 #include <drivers/arm/sfcp_link_defs.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 enum sfcp_hal_error_t { 22 SFCP_HAL_ERROR_SUCCESS = 0, 23 SFCP_HAL_ERROR_UNSUPPORTED_DEVICE, 24 SFCP_HAL_ERROR_CANNOT_GET_ID, 25 SFCP_HAL_ERROR_CANNOT_GET_ROUTING_TABLES, 26 SFCP_HAL_ERROR_DEVICE_UNSUPPORTED, 27 SFCP_HAL_ERROR_INVALID_MESSAGE_ARGUMENT, 28 SFCP_HAL_ERROR_INVALID_MESSAGE_SIZE, 29 SFCP_HAL_ERROR_INVALID_RECEIVE_SIZE, 30 SFCP_HAL_ERROR_SEND_MESSAGE_BUS_BUSY, 31 SFCP_HAL_ERROR_MESSAGE_NOT_AVAILABLE, 32 SFCP_HAL_ERROR_MAX, 33 SFCP_HAL_ERROR_FORCE_UINT32 = UINT32_MAX, 34 }; 35 36 /** 37 * \brief Retrieves the route (link ID) to the specified node. 38 * 39 * This function determines the appropriate communication link (route) 40 * to send a message to the node. 41 * 42 * \param node_id The identifier of the target node. 43 * \return The link ID corresponding to the link to send the message on. 44 */ 45 sfcp_link_id_t sfcp_hal_get_route(sfcp_node_id_t node_id); 46 47 /** 48 * \brief Retrieves the current node's identifier. 49 * 50 * This function obtains the node ID for the current device. 51 * 52 * \param[out] node_id Pointer to a variable where the node ID will be stored. 53 * \return SFCP_HAL_ERROR_SUCCESS on success, or an appropriate error code. 54 */ 55 enum sfcp_hal_error_t sfcp_hal_get_my_node_id(sfcp_node_id_t *node_id); 56 57 /** 58 * \brief Sends a message over the specified communication link. 59 * 60 * This function sends a message to a remote node using the provided link ID. 61 * 62 * \param link_id The link identifier to use for transmission. 63 * \param message Pointer to the message data to send. 64 * \param message_size The size of the message in bytes. 65 * \return SFCP_HAL_ERROR_SUCCESS on success, or an appropriate error code. 66 */ 67 enum sfcp_hal_error_t sfcp_hal_send_message(sfcp_link_id_t link_id, 68 const uint8_t *message, 69 size_t message_size); 70 71 /** 72 * \brief Waits for a message on the specified communication link. 73 * 74 * This function blocks until a message is received on the specified link. 75 * 76 * \note This is a blocking call. Consider updating to a non-blocking variant if needed. 77 * 78 * \param link_id The link identifier to wait on. 79 * \param is_available Whether or not the message is available 80 * \return SFCP_HAL_ERROR_SUCCESS on success, or an appropriate error code. 81 */ 82 enum sfcp_hal_error_t sfcp_hal_is_message_available(sfcp_link_id_t link_id, 83 bool *is_available); 84 85 /** 86 * \brief Retrieves the size of the next message to be received on the specified communication 87 * link. 88 * 89 * This function queries the communication link identified by @p link_id to determine the size 90 * of the next available message. The size is returned via the @p message_size pointer. 91 * 92 * \param[in] link_id The link identifier to query. 93 * \param[out] message_size Pointer to a variable where the size of 94 * the message (in bytes) will be stored. 95 * 96 * \return SFCP_HAL_ERROR_SUCCESS on success, or an appropriate error code. 97 */ 98 enum sfcp_hal_error_t sfcp_hal_get_receive_message_size(sfcp_link_id_t link_id, 99 size_t *message_size); 100 101 /** 102 * \brief Receives (a chunk of) a message from the specified communication link. 103 * 104 * The caller is responsible for providing the buffer that holds the entire message and for 105 * tracking how many bytes have already been retrieved. The function may be invoked multiple 106 * times to drain a single message in aligned chunks. The implementation guarantees that any 107 * remaining data is acknowledged so the sender can provide the next chunk. 108 * 109 * \param link_id Identifier of the link to read from. 110 * \param message Destination buffer (offset by @p already_received bytes). 111 * \param total_message_size Total size, in bytes, of the current message being received. 112 * \param already_received Number of bytes from the message that the caller has already copied. 113 * \param size_to_receive Number of bytes to read into @p message during this call. The 114 * buffer must be at least this size. 115 * 116 * \return SFCP_HAL_ERROR_SUCCESS on success, or an appropriate error code. 117 */ 118 enum sfcp_hal_error_t sfcp_hal_receive_message(sfcp_link_id_t link_id, 119 uint8_t *message, 120 size_t total_message_size, 121 size_t already_received, 122 size_t size_to_receive); 123 124 /** 125 * \brief Initializes the communication HAL layer. 126 * 127 * This function initializes internal data structures and hardware resources required 128 * for communication. 129 * 130 * \return SFCP_HAL_ERROR_SUCCESS on successful initialization, or an appropriate error code. 131 */ 132 enum sfcp_hal_error_t sfcp_hal_init(void); 133 134 #ifdef __cplusplus 135 } 136 #endif 137 138 #endif /* __SFCP_LINK_HAL_H__ */ 139