1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2019-2021 Broadcom 3 * All rights reserved. 4 */ 5 6 #ifndef TF_RM_NEW_H_ 7 #define TF_RM_NEW_H_ 8 9 #include "tf_core.h" 10 #include "bitalloc.h" 11 #include "tf_device.h" 12 13 struct tf; 14 15 /** RM return codes */ 16 #define TF_RM_ALLOCATED_ENTRY_FREE 0 17 #define TF_RM_ALLOCATED_ENTRY_IN_USE 1 18 #define TF_RM_ALLOCATED_NO_ENTRY_FOUND -1 19 20 /** 21 * The Resource Manager (RM) module provides basic DB handling for 22 * internal resources. These resources exists within the actual device 23 * and are controlled by the HCAPI Resource Manager running on the 24 * firmware. 25 * 26 * The RM DBs are all intended to be indexed using TF types there for 27 * a lookup requires no additional conversion. The DB configuration 28 * specifies the TF Type to HCAPI Type mapping and it becomes the 29 * responsibility of the DB initialization to handle this static 30 * mapping. 31 * 32 * Accessor functions are providing access to the DB, thus hiding the 33 * implementation. 34 * 35 * The RM DB will work on its initial allocated sizes so the 36 * capability of dynamically growing a particular resource is not 37 * possible. If this capability later becomes a requirement then the 38 * MAX pool size of the Chip œneeds to be added to the tf_rm_elem_info 39 * structure and several new APIs would need to be added to allow for 40 * growth of a single TF resource type. 41 * 42 * The access functions does not check for NULL pointers as it's a 43 * support module, not called directly. 44 */ 45 46 /** 47 * Resource reservation single entry result. Used when accessing HCAPI 48 * RM on the firmware. 49 */ 50 struct tf_rm_new_entry { 51 /** Starting index of the allocated resource */ 52 uint16_t start; 53 /** Number of allocated elements */ 54 uint16_t stride; 55 }; 56 57 /** 58 * RM Element configuration enumeration. Used by the Device to 59 * indicate how the RM elements the DB consists off, are to be 60 * configured at time of DB creation. The TF may present types to the 61 * ULP layer that is not controlled by HCAPI within the Firmware. 62 */ 63 enum tf_rm_elem_cfg_type { 64 /** 65 * No configuration 66 */ 67 TF_RM_ELEM_CFG_NULL, 68 /** HCAPI 'controlled', no RM storage thus the Device Module 69 * using the RM can chose to handle storage locally. 70 */ 71 TF_RM_ELEM_CFG_HCAPI, 72 /** HCAPI 'controlled', uses a Bit Allocator Pool for internal 73 * storage in the RM. 74 */ 75 TF_RM_ELEM_CFG_HCAPI_BA, 76 /** 77 * Shared element thus it belongs to a shared FW Session and 78 * is not controlled by the Host. 79 */ 80 TF_RM_ELEM_CFG_SHARED, 81 TF_RM_TYPE_MAX 82 }; 83 84 /** 85 * RM Reservation strategy enumeration. Type of strategy comes from 86 * the HCAPI RM QCAPS handshake. 87 */ 88 enum tf_rm_resc_resv_strategy { 89 TF_RM_RESC_RESV_STATIC_PARTITION, 90 TF_RM_RESC_RESV_STRATEGY_1, 91 TF_RM_RESC_RESV_STRATEGY_2, 92 TF_RM_RESC_RESV_STRATEGY_3, 93 TF_RM_RESC_RESV_MAX 94 }; 95 96 /** 97 * RM Element configuration structure, used by the Device to configure 98 * how an individual TF type is configured in regard to the HCAPI RM 99 * of same type. 100 */ 101 struct tf_rm_element_cfg { 102 /** 103 * RM Element config controls how the DB for that element is 104 * processed. 105 */ 106 enum tf_rm_elem_cfg_type cfg_type; 107 108 /* If a HCAPI to TF type conversion is required then TF type 109 * can be added here. 110 */ 111 112 /** 113 * HCAPI RM Type for the element. Used for TF to HCAPI type 114 * conversion. 115 */ 116 uint16_t hcapi_type; 117 }; 118 119 /** 120 * Allocation information for a single element. 121 */ 122 struct tf_rm_alloc_info { 123 /** 124 * HCAPI RM allocated range information. 125 * 126 * NOTE: 127 * In case of dynamic allocation support this would have 128 * to be changed to linked list of tf_rm_entry instead. 129 */ 130 struct tf_rm_new_entry entry; 131 }; 132 133 /** 134 * Create RM DB parameters 135 */ 136 struct tf_rm_create_db_parms { 137 /** 138 * [in] Device module type. Used for logging purposes. 139 */ 140 enum tf_device_module_type type; 141 /** 142 * [in] Receive or transmit direction. 143 */ 144 enum tf_dir dir; 145 /** 146 * [in] Number of elements. 147 */ 148 uint16_t num_elements; 149 /** 150 * [in] Parameter structure array. Array size is num_elements. 151 */ 152 struct tf_rm_element_cfg *cfg; 153 /** 154 * Resource allocation count array. This array content 155 * originates from the tf_session_resources that is passed in 156 * on session open. 157 * Array size is num_elements. 158 */ 159 uint16_t *alloc_cnt; 160 /** 161 * [out] RM DB Handle 162 */ 163 void **rm_db; 164 }; 165 166 /** 167 * Free RM DB parameters 168 */ 169 struct tf_rm_free_db_parms { 170 /** 171 * [in] Receive or transmit direction 172 */ 173 enum tf_dir dir; 174 /** 175 * [in] RM DB Handle 176 */ 177 void *rm_db; 178 }; 179 180 /** 181 * Allocate RM parameters for a single element 182 */ 183 struct tf_rm_allocate_parms { 184 /** 185 * [in] RM DB Handle 186 */ 187 void *rm_db; 188 /** 189 * [in] DB Index, indicates which DB entry to perform the 190 * action on. 191 */ 192 uint16_t db_index; 193 /** 194 * [in] Pointer to the allocated index in normalized 195 * form. Normalized means the index has been adjusted, 196 * i.e. Full Action Record offsets. 197 */ 198 uint32_t *index; 199 /** 200 * [in] Priority, indicates the priority of the entry 201 * priority 0: allocate from top of the tcam (from index 0 202 * or lowest available index) 203 * priority !0: allocate from bottom of the tcam (from highest 204 * available index) 205 */ 206 uint32_t priority; 207 /** 208 * [in] Pointer to the allocated index before adjusted. 209 */ 210 uint32_t *base_index; 211 }; 212 213 /** 214 * Free RM parameters for a single element 215 */ 216 struct tf_rm_free_parms { 217 /** 218 * [in] RM DB Handle 219 */ 220 void *rm_db; 221 /** 222 * [in] DB Index, indicates which DB entry to perform the 223 * action on. 224 */ 225 uint16_t db_index; 226 /** 227 * [in] Index to free 228 */ 229 uint16_t index; 230 }; 231 232 /** 233 * Is Allocated parameters for a single element 234 */ 235 struct tf_rm_is_allocated_parms { 236 /** 237 * [in] RM DB Handle 238 */ 239 void *rm_db; 240 /** 241 * [in] DB Index, indicates which DB entry to perform the 242 * action on. 243 */ 244 uint16_t db_index; 245 /** 246 * [in] Index to free 247 */ 248 uint32_t index; 249 /** 250 * [in] Pointer to flag that indicates the state of the query 251 */ 252 int *allocated; 253 /** 254 * [in] Pointer to the allocated index before adjusted. 255 */ 256 uint32_t *base_index; 257 }; 258 259 /** 260 * Get Allocation information for a single element 261 */ 262 struct tf_rm_get_alloc_info_parms { 263 /** 264 * [in] RM DB Handle 265 */ 266 void *rm_db; 267 /** 268 * [in] DB Index, indicates which DB entry to perform the 269 * action on. 270 */ 271 uint16_t db_index; 272 /** 273 * [out] Pointer to the requested allocation information for 274 * the specified db_index 275 */ 276 struct tf_rm_alloc_info *info; 277 }; 278 279 /** 280 * Get HCAPI type parameters for a single element 281 */ 282 struct tf_rm_get_hcapi_parms { 283 /** 284 * [in] RM DB Handle 285 */ 286 void *rm_db; 287 /** 288 * [in] DB Index, indicates which DB entry to perform the 289 * action on. 290 */ 291 uint16_t db_index; 292 /** 293 * [out] Pointer to the hcapi type for the specified db_index 294 */ 295 uint16_t *hcapi_type; 296 }; 297 298 /** 299 * Get InUse count parameters for single element 300 */ 301 struct tf_rm_get_inuse_count_parms { 302 /** 303 * [in] RM DB Handle 304 */ 305 void *rm_db; 306 /** 307 * [in] DB Index, indicates which DB entry to perform the 308 * action on. 309 */ 310 uint16_t db_index; 311 /** 312 * [out] Pointer to the inuse count for the specified db_index 313 */ 314 uint16_t *count; 315 }; 316 317 /** 318 * Check if the indexes are in the range of reserved resource 319 */ 320 struct tf_rm_check_indexes_in_range_parms { 321 /** 322 * [in] RM DB Handle 323 */ 324 void *rm_db; 325 /** 326 * [in] DB Index, indicates which DB entry to perform the 327 * action on. 328 */ 329 uint16_t db_index; 330 /** 331 * [in] Starting index 332 */ 333 uint16_t starting_index; 334 /** 335 * [in] number of entries 336 */ 337 uint16_t num_entries; 338 }; 339 340 /** 341 * @page rm Resource Manager 342 * 343 * @ref tf_rm_create_db 344 * 345 * @ref tf_rm_free_db 346 * 347 * @ref tf_rm_allocate 348 * 349 * @ref tf_rm_free 350 * 351 * @ref tf_rm_is_allocated 352 * 353 * @ref tf_rm_get_info 354 * 355 * @ref tf_rm_get_hcapi_type 356 * 357 * @ref tf_rm_get_inuse_count 358 */ 359 360 /** 361 * Creates and fills a Resource Manager (RM) DB with requested 362 * elements. The DB is indexed per the parms structure. 363 * 364 * [in] tfp 365 * Pointer to TF handle, used for HCAPI communication 366 * 367 * [in] parms 368 * Pointer to create parameters 369 * 370 * Returns 371 * - (0) if successful. 372 * - (-EINVAL) on failure. 373 */ 374 /* 375 * NOTE: 376 * - Fail on parameter check 377 * - Fail on DB creation, i.e. alloc amount is not possible or validation fails 378 * - Fail on DB creation if DB already exist 379 * 380 * - Allocs local DB 381 * - Does hcapi qcaps 382 * - Does hcapi reservation 383 * - Populates the pool with allocated elements 384 * - Returns handle to the created DB 385 */ 386 int tf_rm_create_db(struct tf *tfp, 387 struct tf_rm_create_db_parms *parms); 388 389 /** 390 * Closes the Resource Manager (RM) DB and frees all allocated 391 * resources per the associated database. 392 * 393 * [in] tfp 394 * Pointer to TF handle, used for HCAPI communication 395 * 396 * [in] parms 397 * Pointer to free parameters 398 * 399 * Returns 400 * - (0) if successful. 401 * - (-EINVAL) on failure. 402 */ 403 int tf_rm_free_db(struct tf *tfp, 404 struct tf_rm_free_db_parms *parms); 405 406 /** 407 * Allocates a single element for the type specified, within the DB. 408 * 409 * [in] parms 410 * Pointer to allocate parameters 411 * 412 * Returns 413 * - (0) if successful. 414 * - (-EINVAL) on failure. 415 * - (-ENOMEM) if pool is empty 416 */ 417 int tf_rm_allocate(struct tf_rm_allocate_parms *parms); 418 419 /** 420 * Free's a single element for the type specified, within the DB. 421 * 422 * [in] parms 423 * Pointer to free parameters 424 * 425 * Returns 426 * - (0) if successful. 427 * - (-EINVAL) on failure. 428 */ 429 int tf_rm_free(struct tf_rm_free_parms *parms); 430 431 /** 432 * Performs an allocation verification check on a specified element. 433 * 434 * [in] parms 435 * Pointer to is allocated parameters 436 * 437 * Returns 438 * - (0) if successful. 439 * - (-EINVAL) on failure. 440 */ 441 /* 442 * NOTE: 443 * - If pool is set to Chip MAX, then the query index must be checked 444 * against the allocated range and query index must be allocated as well. 445 * - If pool is allocated size only, then check if query index is allocated. 446 */ 447 int tf_rm_is_allocated(struct tf_rm_is_allocated_parms *parms); 448 449 /** 450 * Retrieves an elements allocation information from the Resource 451 * Manager (RM) DB. 452 * 453 * [in] parms 454 * Pointer to get info parameters 455 * 456 * Returns 457 * - (0) if successful. 458 * - (-EINVAL) on failure. 459 */ 460 int tf_rm_get_info(struct tf_rm_get_alloc_info_parms *parms); 461 462 /** 463 * Performs a lookup in the Resource Manager DB and retrieves the 464 * requested HCAPI RM type. 465 * 466 * [in] parms 467 * Pointer to get hcapi parameters 468 * 469 * Returns 470 * - (0) if successful. 471 * - (-EINVAL) on failure. 472 */ 473 int tf_rm_get_hcapi_type(struct tf_rm_get_hcapi_parms *parms); 474 475 /** 476 * Performs a lookup in the Resource Manager DB and retrieves the 477 * requested HCAPI RM type inuse count. 478 * 479 * [in] parms 480 * Pointer to get inuse parameters 481 * 482 * Returns 483 * - (0) if successful. 484 * - (-EINVAL) on failure. 485 */ 486 int tf_rm_get_inuse_count(struct tf_rm_get_inuse_count_parms *parms); 487 488 /** 489 * Check if the requested indexes are in the range of reserved resource. 490 * 491 * [in] parms 492 * Pointer to get inuse parameters 493 * 494 * Returns 495 * - (0) if successful. 496 * - (-EINVAL) on failure. 497 */ 498 int 499 tf_rm_check_indexes_in_range(struct tf_rm_check_indexes_in_range_parms *parms); 500 501 502 #endif /* TF_RM_NEW_H_ */ 503