1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2019-2020 Broadcom
15 * The Resource Manager (RM) module provides basic DB handling for
16 * internal resources. These resources exists within the actual device
17 * and are controlled by the HCAPI Resource Manager running on the
20 * The RM DBs are all intended to be indexed using TF types there for
21 * a lookup requires no additional conversion. The DB configuration
22 * specifies the TF Type to HCAPI Type mapping and it becomes the
23 * responsibility of the DB initialization to handle this static
26 * Accessor functions are providing access to the DB, thus hiding the
29 * The RM DB will work on its initial allocated sizes so the
30 * capability of dynamically growing a particular resource is not
31 * possible. If this capability later becomes a requirement then the
32 * MAX pool size of the Chip Å“needs to be added to the tf_rm_elem_info
33 * structure and several new APIs would need to be added to allow for
34 * growth of a single TF resource type.
38 * Resource reservation single entry result. Used when accessing HCAPI
42 /** Starting index of the allocated resource */
44 /** Number of allocated elements */
49 * RM Element configuration enumeration. Used by the Device to
50 * indicate how the RM elements the DB consists off, are to be
51 * configured at time of DB creation. The TF may present types to the
52 * ULP layer that is not controlled by HCAPI within the Firmware.
54 enum tf_rm_elem_cfg_type {
55 TF_RM_ELEM_CFG_NULL, /**< No configuration */
56 TF_RM_ELEM_CFG_HCAPI, /**< HCAPI 'controlled' */
57 TF_RM_ELEM_CFG_PRIVATE, /**< Private thus not HCAPI 'controlled' */
62 * RM Element configuration structure, used by the Device to configure
63 * how an individual TF type is configured in regard to the HCAPI RM
66 struct tf_rm_element_cfg {
68 * RM Element config controls how the DB for that element is
71 enum tf_rm_elem_cfg_type cfg;
73 /* If a HCAPI to TF type conversion is required then TF type
78 * HCAPI RM Type for the element. Used for TF to HCAPI type
85 * Allocation information for a single element.
87 struct tf_rm_alloc_info {
89 * HCAPI RM allocated range information.
92 * In case of dynamic allocation support this would have
93 * to be changed to linked list of tf_rm_entry instead.
95 struct tf_rm_entry entry;
99 * Create RM DB parameters
101 struct tf_rm_create_db_parms {
103 * [in] Receive or transmit direction
107 * [in] Number of elements in the parameter structure
109 uint16_t num_elements;
111 * [in] Parameter structure
113 struct tf_rm_element_cfg *parms;
121 * Free RM DB parameters
123 struct tf_rm_free_db_parms {
125 * [in] Receive or transmit direction
135 * Allocate RM parameters for a single element
137 struct tf_rm_allocate_parms {
143 * [in] DB Index, indicates which DB entry to perform the
148 * [in] Pointer to the allocated index in normalized
149 * form. Normalized means the index has been adjusted,
150 * i.e. Full Action Record offsets.
156 * Free RM parameters for a single element
158 struct tf_rm_free_parms {
164 * [in] DB Index, indicates which DB entry to perform the
175 * Is Allocated parameters for a single element
177 struct tf_rm_is_allocated_parms {
183 * [in] DB Index, indicates which DB entry to perform the
192 * [in] Pointer to flag that indicates the state of the query
198 * Get Allocation information for a single element
200 struct tf_rm_get_alloc_info_parms {
206 * [in] DB Index, indicates which DB entry to perform the
211 * [out] Pointer to the requested allocation information for
212 * the specified db_index
214 struct tf_rm_alloc_info *info;
218 * Get HCAPI type parameters for a single element
220 struct tf_rm_get_hcapi_parms {
226 * [in] DB Index, indicates which DB entry to perform the
231 * [out] Pointer to the hcapi type for the specified db_index
233 uint16_t *hcapi_type;
237 * @page rm Resource Manager
239 * @ref tf_rm_create_db
243 * @ref tf_rm_allocate
247 * @ref tf_rm_is_allocated
249 * @ref tf_rm_get_info
251 * @ref tf_rm_get_hcapi_type
255 * Creates and fills a Resource Manager (RM) DB with requested
256 * elements. The DB is indexed per the parms structure.
259 * Pointer to TF handle, used for HCAPI communication
262 * Pointer to create parameters
265 * - (0) if successful.
266 * - (-EINVAL) on failure.
270 * - Fail on parameter check
271 * - Fail on DB creation, i.e. alloc amount is not possible or validation fails
272 * - Fail on DB creation if DB already exist
276 * - Does hcapi reservation
277 * - Populates the pool with allocated elements
278 * - Returns handle to the created DB
280 int tf_rm_create_db(struct tf *tfp,
281 struct tf_rm_create_db_parms *parms);
284 * Closes the Resource Manager (RM) DB and frees all allocated
285 * resources per the associated database.
288 * Pointer to TF handle, used for HCAPI communication
291 * Pointer to free parameters
294 * - (0) if successful.
295 * - (-EINVAL) on failure.
297 int tf_rm_free_db(struct tf *tfp,
298 struct tf_rm_free_db_parms *parms);
301 * Allocates a single element for the type specified, within the DB.
304 * Pointer to allocate parameters
307 * - (0) if successful.
308 * - (-EINVAL) on failure.
310 int tf_rm_allocate(struct tf_rm_allocate_parms *parms);
313 * Free's a single element for the type specified, within the DB.
316 * Pointer to free parameters
319 * - (0) if successful.
320 * - (-EpINVAL) on failure.
322 int tf_rm_free(struct tf_rm_free_parms *parms);
325 * Performs an allocation verification check on a specified element.
328 * Pointer to is allocated parameters
331 * - (0) if successful.
332 * - (-EINVAL) on failure.
336 * - If pool is set to Chip MAX, then the query index must be checked
337 * against the allocated range and query index must be allocated as well.
338 * - If pool is allocated size only, then check if query index is allocated.
340 int tf_rm_is_allocated(struct tf_rm_is_allocated_parms *parms);
343 * Retrieves an elements allocation information from the Resource
347 * Pointer to get info parameters
350 * - (0) if successful.
351 * - (-EINVAL) on failure.
353 int tf_rm_get_info(struct tf_rm_get_alloc_info_parms *parms);
356 * Performs a lookup in the Resource Manager DB and retrieves the
357 * requested HCAPI type.
360 * Pointer to get hcapi parameters
363 * - (0) if successful.
364 * - (-EINVAL) on failure.
366 int tf_rm_get_hcapi_type(struct tf_rm_get_hcapi_parms *parms);
368 #endif /* TF_RM_H_ */