1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2017-2019 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without modification, 8 * are permitted provided that the following conditions are met: 9 * 10 * o Redistributions of source code must retain the above copyright notice, this list 11 * of conditions and the following disclaimer. 12 * 13 * o Redistributions in binary form must reproduce the above copyright notice, this 14 * list of conditions and the following disclaimer in the documentation and/or 15 * other materials provided with the distribution. 16 * 17 * o Neither the name of the copyright holder nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 25 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*! 34 * Header file containing the public API for the System Controller (SC) 35 * Resource Management (RM) function. This includes functions for 36 * partitioning resources, pads, and memory regions. 37 * 38 * @addtogroup RM_SVC RM: Resource Management Service 39 * 40 * Module for the Resource Management (RM) service. 41 * 42 * @includedoc rm/details.dox 43 * 44 * @{ 45 */ 46 47 #ifndef SC_RM_API_H 48 #define SC_RM_API_H 49 50 /* Includes */ 51 52 #include "main/types.h" 53 54 /* Defines */ 55 56 /*! 57 * @name Defines for type widths 58 */ 59 /*@{*/ 60 #define SC_RM_PARTITION_W 5U /*!< Width of sc_rm_pt_t */ 61 #define SC_RM_MEMREG_W 6U /*!< Width of sc_rm_mr_t */ 62 #define SC_RM_DID_W 4U /*!< Width of sc_rm_did_t */ 63 #define SC_RM_SID_W 6U /*!< Width of sc_rm_sid_t */ 64 #define SC_RM_SPA_W 2U /*!< Width of sc_rm_spa_t */ 65 #define SC_RM_PERM_W 3U /*!< Width of sc_rm_perm_t */ 66 /*@}*/ 67 68 /*! 69 * @name Defines for ALL parameters 70 */ 71 /*@{*/ 72 #define SC_RM_PT_ALL ((sc_rm_pt_t) UINT8_MAX) /*!< All partitions */ 73 #define SC_RM_MR_ALL ((sc_rm_mr_t) UINT8_MAX) /*!< All memory regions */ 74 /*@}*/ 75 76 /*! 77 * @name Defines for sc_rm_spa_t 78 */ 79 /*@{*/ 80 #define SC_RM_SPA_PASSTHRU 0U /*!< Pass through (attribute driven by master) */ 81 #define SC_RM_SPA_PASSSID 1U /*!< Pass through and output on SID */ 82 #define SC_RM_SPA_ASSERT 2U /*!< Assert (force to be secure/privileged) */ 83 #define SC_RM_SPA_NEGATE 3U /*!< Negate (force to be non-secure/user) */ 84 /*@}*/ 85 86 /*! 87 * @name Defines for sc_rm_perm_t 88 */ 89 /*@{*/ 90 #define SC_RM_PERM_NONE 0U /*!< No access */ 91 #define SC_RM_PERM_SEC_R 1U /*!< Secure RO */ 92 #define SC_RM_PERM_SECPRIV_RW 2U /*!< Secure privilege R/W */ 93 #define SC_RM_PERM_SEC_RW 3U /*!< Secure R/W */ 94 #define SC_RM_PERM_NSPRIV_R 4U /*!< Secure R/W, non-secure privilege RO */ 95 #define SC_RM_PERM_NS_R 5U /*!< Secure R/W, non-secure RO */ 96 #define SC_RM_PERM_NSPRIV_RW 6U /*!< Secure R/W, non-secure privilege R/W */ 97 #define SC_RM_PERM_FULL 7U /*!< Full access */ 98 /*@}*/ 99 100 /* Types */ 101 102 /*! 103 * This type is used to declare a resource partition. 104 */ 105 typedef uint8_t sc_rm_pt_t; 106 107 /*! 108 * This type is used to declare a memory region. 109 */ 110 typedef uint8_t sc_rm_mr_t; 111 112 /*! 113 * This type is used to declare a resource domain ID used by the 114 * isolation HW. 115 */ 116 typedef uint8_t sc_rm_did_t; 117 118 /*! 119 * This type is used to declare an SMMU StreamID. 120 */ 121 typedef uint16_t sc_rm_sid_t; 122 123 /*! 124 * This type is a used to declare master transaction attributes. 125 */ 126 typedef uint8_t sc_rm_spa_t; 127 128 /*! 129 * This type is used to declare a resource/memory region access permission. 130 * Refer to the XRDC2 Block Guide for more information. 131 */ 132 typedef uint8_t sc_rm_perm_t; 133 134 /* Functions */ 135 136 /*! 137 * @name Partition Functions 138 * @{ 139 */ 140 141 /*! 142 * This function requests that the SC create a new resource partition. 143 * 144 * @param[in] ipc IPC handle 145 * @param[out] pt return handle for partition; used for subsequent function 146 * calls associated with this partition 147 * @param[in] secure boolean indicating if this partition should be secure; only 148 * valid if caller is secure 149 * @param[in] isolated boolean indicating if this partition should be HW isolated 150 * via XRDC; set SC_TRUE if new DID is desired 151 * @param[in] restricted boolean indicating if this partition should be restricted; set 152 * SC_TRUE if masters in this partition cannot create new partitions 153 * @param[in] grant boolean indicating if this partition should always grant 154 * access and control to the parent 155 * @param[in] coherent boolean indicating if this partition is coherent; 156 * set SC_TRUE if only this partition will contain both AP clusters 157 * and they will be coherent via the CCI 158 * 159 * @return Returns an error code (SC_ERR_NONE = success). 160 * 161 * Return errors: 162 * - SC_ERR_NOACCESS if caller's partition is restricted, 163 * - SC_ERR_PARM if caller's partition is not secure but a new secure partition is requested, 164 * - SC_ERR_LOCKED if caller's partition is locked, 165 * - SC_ERR_UNAVAILABLE if partition table is full (no more allocation space) 166 * 167 * Marking as non-secure prevents subsequent functions from configuring masters in this 168 * partition to assert the secure signal. Basically, if TrustZone SW is used, the Cortex-A 169 * cores and peripherals the TZ SW will use should be in a secure partition. Almost all 170 * other partitions (for a non-secure OS or M4 cores) should be in non-secure partitions. 171 * 172 * Isolated should be true for almost all partitions. The exception is the non-secure 173 * partition for a Cortex-A core used to run a non-secure OS. This isn't isolated by 174 * domain but is instead isolated by the TZ security hardware. 175 * 176 * If restricted then the new partition is limited in what functions it can call, 177 * especially those associated with managing partitions. 178 * 179 * The grant option is usually used to isolate a bus master's traffic to specific 180 * memory without isolating the peripheral interface of the master or the API 181 * controls of that master. This is only used when creating a sub-partition with 182 * no CPU. It's useful to separate out a master and the memory it uses. 183 */ 184 sc_err_t sc_rm_partition_alloc(sc_ipc_t ipc, sc_rm_pt_t *pt, sc_bool_t secure, 185 sc_bool_t isolated, sc_bool_t restricted, sc_bool_t grant, sc_bool_t coherent); 186 187 /*! 188 * This function makes a partition confidential. 189 * 190 * @param[in] ipc IPC handle 191 * @param[in] pt handle of partition that is granting 192 * @param[in] retro retroactive 193 * 194 * @return Returns an error code (SC_ERR_NONE = success). 195 * 196 * Return errors: 197 * - SC_PARM if \a pt out of range, 198 * - SC_ERR_NOACCESS if caller's not allowed to change \a pt 199 * - SC_ERR_LOCKED if partition \a pt is locked 200 * 201 * Call to make a partition confidential. Confidential means only this 202 * partition should be able to grant access permissions to this partition. 203 * 204 * If retroactive, then all resources owned by other partitions will have 205 * access rights for this partition removed, even if locked. 206 */ 207 sc_err_t sc_rm_set_confidential(sc_ipc_t ipc, sc_rm_pt_t pt, sc_bool_t retro); 208 209 /*! 210 * This function frees a partition and assigns all resources to the caller. 211 * 212 * @param[in] ipc IPC handle 213 * @param[in] pt handle of partition to free 214 * 215 * @return Returns an error code (SC_ERR_NONE = success). 216 * 217 * Return errors: 218 * - SC_ERR_NOACCESS if caller's partition is restricted, 219 * - SC_PARM if \a pt out of range or invalid, 220 * - SC_ERR_NOACCESS if \a pt is the SC partition, 221 * - SC_ERR_NOACCESS if caller's partition is not the parent of \a pt, 222 * - SC_ERR_LOCKED if \a pt or caller's partition is locked 223 * 224 * All resources, memory regions, and pads are assigned to the caller/parent. 225 * The partition watchdog is disabled (even if locked). DID is freed. 226 */ 227 sc_err_t sc_rm_partition_free(sc_ipc_t ipc, sc_rm_pt_t pt); 228 229 /*! 230 * This function returns the DID of a partition. 231 * 232 * @param[in] ipc IPC handle 233 * 234 * @return Returns the domain ID (DID) of the caller's partition. 235 * 236 * The DID is a SoC-specific internal ID used by the HW resource 237 * protection mechanism. It is only required by clients when using the 238 * SEMA42 module as the DID is sometimes connected to the master ID. 239 */ 240 sc_rm_did_t sc_rm_get_did(sc_ipc_t ipc); 241 242 /*! 243 * This function forces a partition to use a specific static DID. 244 * 245 * @param[in] ipc IPC handle 246 * @param[in] pt handle of partition to assign \a did 247 * @param[in] did static DID to assign 248 * 249 * @return Returns an error code (SC_ERR_NONE = success). 250 * 251 * Return errors: 252 * - SC_ERR_NOACCESS if caller's partition is restricted, 253 * - SC_PARM if \a pt or \a did out of range, 254 * - SC_ERR_NOACCESS if caller's partition is not the parent of \a pt, 255 * - SC_ERR_LOCKED if \a pt is locked 256 * 257 * Assumes no assigned resources or memory regions yet! The number of static 258 * DID is fixed by the SC at boot. 259 */ 260 sc_err_t sc_rm_partition_static(sc_ipc_t ipc, sc_rm_pt_t pt, 261 sc_rm_did_t did); 262 263 /*! 264 * This function locks a partition. 265 * 266 * @param[in] ipc IPC handle 267 * @param[in] pt handle of partition to lock 268 * 269 * @return Returns an error code (SC_ERR_NONE = success). 270 * 271 * Return errors: 272 * - SC_PARM if \a pt out of range, 273 * - SC_ERR_NOACCESS if caller's partition is not the parent of \a pt 274 * 275 * If a partition is locked it cannot be freed, have resources/pads assigned 276 * to/from it, memory regions created/assigned, DID changed, or parent changed. 277 */ 278 sc_err_t sc_rm_partition_lock(sc_ipc_t ipc, sc_rm_pt_t pt); 279 280 /*! 281 * This function gets the partition handle of the caller. 282 * 283 * @param[in] ipc IPC handle 284 * @param[out] pt return handle for caller's partition 285 * 286 * @return Returns an error code (SC_ERR_NONE = success). 287 */ 288 sc_err_t sc_rm_get_partition(sc_ipc_t ipc, sc_rm_pt_t *pt); 289 290 /*! 291 * This function sets a new parent for a partition. 292 * 293 * @param[in] ipc IPC handle 294 * @param[in] pt handle of partition for which parent is to be 295 * changed 296 * @param[in] pt_parent handle of partition to set as parent 297 * 298 * @return Returns an error code (SC_ERR_NONE = success). 299 * 300 * Return errors: 301 * - SC_ERR_NOACCESS if caller's partition is restricted, 302 * - SC_PARM if arguments out of range or invalid, 303 * - SC_ERR_NOACCESS if caller's partition is not the parent of \a pt, 304 * - SC_ERR_LOCKED if either partition is locked 305 */ 306 sc_err_t sc_rm_set_parent(sc_ipc_t ipc, sc_rm_pt_t pt, 307 sc_rm_pt_t pt_parent); 308 309 /*! 310 * This function moves all movable resources/pads owned by a source partition 311 * to a destination partition. It can be used to more quickly set up a new 312 * partition if a majority of the caller's resources are to be moved to a 313 * new partition. 314 * 315 * @param[in] ipc IPC handle 316 * @param[in] pt_src handle of partition from which resources should 317 * be moved from 318 * @param[in] pt_dst handle of partition to which resources should be 319 * moved to 320 * @param[in] move_rsrc boolean to indicate if resources should be moved 321 * @param[in] move_pads boolean to indicate if pads should be moved 322 * 323 * @return Returns an error code (SC_ERR_NONE = success). 324 * 325 * By default, all resources are movable. This can be changed using the 326 * sc_rm_set_resource_movable() function. Note all masters defaulted to SMMU 327 * bypass. 328 * 329 * Return errors: 330 * - SC_ERR_NOACCESS if caller's partition is restricted, 331 * - SC_PARM if arguments out of range or invalid, 332 * - SC_ERR_NOACCESS if caller's partition is not \a pt_src or the 333 * parent of \a pt_src, 334 * - SC_ERR_LOCKED if either partition is locked 335 */ 336 sc_err_t sc_rm_move_all(sc_ipc_t ipc, sc_rm_pt_t pt_src, sc_rm_pt_t pt_dst, 337 sc_bool_t move_rsrc, sc_bool_t move_pads); 338 339 /* @} */ 340 341 /*! 342 * @name Resource Functions 343 * @{ 344 */ 345 346 /*! 347 * This function assigns ownership of a resource to a partition. 348 * 349 * @param[in] ipc IPC handle 350 * @param[in] pt handle of partition to which resource should be 351 * assigned 352 * @param[in] resource resource to assign 353 * 354 * This function assigned a resource to a partition. This partition is then 355 * the owner. All resources always have an owner (one owner). The owner 356 * has various rights to make API calls affecting the resource. Ownership 357 * does not imply access to the peripheral itself (that is based on access 358 * rights). 359 * 360 * @return Returns an error code (SC_ERR_NONE = success). 361 * 362 * This action resets the resource's master and peripheral attributes. 363 * Privilege attribute will be PASSTHRU, security attribute will be 364 * ASSERT if the partition is secure and NEGATE if it is not, and 365 * masters will defaulted to SMMU bypass. Access permissions will reset 366 * to SEC_RW for the owning partition only for secure partitions, FULL for 367 * non-secure. Default is no access by other partitions. 368 * 369 * Return errors: 370 * - SC_ERR_NOACCESS if caller's partition is restricted, 371 * - SC_PARM if arguments out of range or invalid, 372 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 373 * of the owner, 374 * - SC_ERR_LOCKED if the owning partition or \a pt is locked 375 */ 376 sc_err_t sc_rm_assign_resource(sc_ipc_t ipc, sc_rm_pt_t pt, 377 sc_rsrc_t resource); 378 379 /*! 380 * This function flags resources as movable or not. 381 * 382 * @param[in] ipc IPC handle 383 * @param[in] resource_fst first resource for which flag should be set 384 * @param[in] resource_lst last resource for which flag should be set 385 * @param[in] movable movable flag (SC_TRUE is movable) 386 * 387 * @return Returns an error code (SC_ERR_NONE = success). 388 * 389 * Return errors: 390 * - SC_PARM if resources are out of range, 391 * - SC_ERR_NOACCESS if caller's partition is not a parent of a resource owner, 392 * - SC_ERR_LOCKED if the owning partition is locked 393 * 394 * This function is used to determine the set of resources that will be 395 * moved using the sc_rm_move_all() function. All resources are movable 396 * by default so this function is normally used to prevent a set of 397 * resources from moving. 398 */ 399 sc_err_t sc_rm_set_resource_movable(sc_ipc_t ipc, sc_rsrc_t resource_fst, 400 sc_rsrc_t resource_lst, sc_bool_t movable); 401 402 /*! 403 * This function flags all of a subsystem's resources as movable 404 * or not. 405 * 406 * @param[in] ipc IPC handle 407 * @param[in] resource resource to use to identify subsystem 408 * @param[in] movable movable flag (SC_TRUE is movable) 409 * 410 * A subsystem is a physical grouping within the chip of related resources; 411 * this is SoC specific. This function is used to optimize moving resource 412 * for these groupings, for instance, an M4 core and its associated resources. 413 * The list of subsystems and associated resources can be found in the 414 * SoC-specific API document [Resources](@ref RESOURCES) chapter. 415 * 416 * @return Returns an error code (SC_ERR_NONE = success). 417 * 418 * Return errors: 419 * - SC_ERR_PARM if a function argument is out of range 420 * 421 * Note \a resource is used to find the associated subsystem. Only 422 * resources owned by the caller are set. 423 */ 424 sc_err_t sc_rm_set_subsys_rsrc_movable(sc_ipc_t ipc, sc_rsrc_t resource, 425 sc_bool_t movable); 426 427 /*! 428 * This function sets attributes for a resource which is a bus master (i.e. 429 * capable of DMA). 430 * 431 * @param[in] ipc IPC handle 432 * @param[in] resource master resource for which attributes should apply 433 * @param[in] sa security attribute 434 * @param[in] pa privilege attribute 435 * @param[in] smmu_bypass SMMU bypass mode 436 * 437 * @return Returns an error code (SC_ERR_NONE = success). 438 * 439 * Return errors: 440 * - SC_ERR_NOACCESS if caller's partition is restricted, 441 * - SC_PARM if arguments out of range or invalid, 442 * - SC_ERR_NOACCESS if caller's partition is not a parent of the resource owner, 443 * - SC_ERR_LOCKED if the owning partition is locked 444 * 445 * Masters are IP blocks that generate bus transactions. This function configures 446 * how the isolation HW will define these bus transactions from the specified master. 447 * Note the security attribute will only be changed if the caller's partition is 448 * secure. 449 * 450 * Note an IP block can be both a master and peripheral (have both a programming model 451 * and generate bus transactions). 452 */ 453 sc_err_t sc_rm_set_master_attributes(sc_ipc_t ipc, sc_rsrc_t resource, 454 sc_rm_spa_t sa, sc_rm_spa_t pa, sc_bool_t smmu_bypass); 455 456 /*! 457 * This function sets the StreamID for a resource which is a bus master (i.e. 458 * capable of DMA). 459 * 460 * @param[in] ipc IPC handle 461 * @param[in] resource master resource for which attributes should apply 462 * @param[in] sid StreamID 463 * 464 * @return Returns an error code (SC_ERR_NONE = success). 465 * 466 * Return errors: 467 * - SC_ERR_NOACCESS if caller's partition is restricted, 468 * - SC_PARM if arguments out of range or invalid, 469 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 470 * of the owner, 471 * - SC_ERR_LOCKED if the owning partition is locked 472 * 473 * This function configures the SID attribute associated with all bus transactions 474 * from this master. Note 0 is not a valid SID as it is reserved to indicate 475 * bypass. 476 */ 477 sc_err_t sc_rm_set_master_sid(sc_ipc_t ipc, sc_rsrc_t resource, 478 sc_rm_sid_t sid); 479 480 /*! 481 * This function sets access permissions for a peripheral resource. 482 * 483 * @param[in] ipc IPC handle 484 * @param[in] resource peripheral resource for which permissions should apply 485 * @param[in] pt handle of partition \a perm should by applied for 486 * @param[in] perm permissions to apply to \a resource for \a pt 487 * 488 * @return Returns an error code (SC_ERR_NONE = success). 489 * 490 * Return errors: 491 * - SC_PARM if arguments out of range or invalid, 492 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 493 * of the owner, 494 * - SC_ERR_LOCKED if the owning partition is locked 495 * - SC_ERR_LOCKED if the \a pt is confidential and the caller isn't \a pt 496 * 497 * Peripherals are IP blocks that have a programming model that can be 498 * accessed. 499 * 500 * This function configures how the isolation HW will restrict access to a 501 * peripheral based on the attributes of a transaction from bus master. It 502 * also allows the access permissions of SC_R_SYSTEM to be set. 503 * 504 * Note an IP block can be both a master and peripheral (have both a programming 505 * model and generate bus transactions). 506 */ 507 sc_err_t sc_rm_set_peripheral_permissions(sc_ipc_t ipc, sc_rsrc_t resource, 508 sc_rm_pt_t pt, sc_rm_perm_t perm); 509 510 /*! 511 * This function gets ownership status of a resource. 512 * 513 * @param[in] ipc IPC handle 514 * @param[in] resource resource to check 515 * 516 * @return Returns a boolean (SC_TRUE if caller's partition owns the resource). 517 * 518 * If \a resource is out of range then SC_FALSE is returned. 519 */ 520 sc_bool_t sc_rm_is_resource_owned(sc_ipc_t ipc, sc_rsrc_t resource); 521 522 /*! 523 * This function is used to get the owner of a resource. 524 * 525 * @param[in] ipc IPC handle 526 * @param[in] resource resource to check 527 * @param[out] pt pointer to return owning partition 528 * 529 * @return Returns a boolean (SC_TRUE if the resource is a bus master). 530 * 531 * Return errors: 532 * - SC_PARM if arguments out of range or invalid 533 * 534 * If \a resource is out of range then SC_ERR_PARM is returned. 535 */ 536 sc_err_t sc_rm_get_resource_owner(sc_ipc_t ipc, sc_rsrc_t resource, 537 sc_rm_pt_t *pt); 538 539 /*! 540 * This function is used to test if a resource is a bus master. 541 * 542 * @param[in] ipc IPC handle 543 * @param[in] resource resource to check 544 * 545 * Masters are IP blocks that generate bus transactions. Note an IP block 546 * can be both a master and peripheral (have both a programming model 547 * and generate bus transactions). 548 * 549 * @return Returns a boolean (SC_TRUE if the resource is a bus master). 550 * 551 * If \a resource is out of range then SC_FALSE is returned. 552 */ 553 sc_bool_t sc_rm_is_resource_master(sc_ipc_t ipc, sc_rsrc_t resource); 554 555 /*! 556 * This function is used to test if a resource is a peripheral. 557 * 558 * @param[in] ipc IPC handle 559 * @param[in] resource resource to check 560 * 561 * Peripherals are IP blocks that have a programming model that can be 562 * accessed. Note an IP block can be both a master and peripheral (have 563 * both a programming model and generate bus transactions) 564 * 565 * @return Returns a boolean (SC_TRUE if the resource is a peripheral). 566 * 567 * If \a resource is out of range then SC_FALSE is returned. 568 */ 569 sc_bool_t sc_rm_is_resource_peripheral(sc_ipc_t ipc, sc_rsrc_t resource); 570 571 /*! 572 * This function is used to obtain info about a resource. 573 * 574 * @param[in] ipc IPC handle 575 * @param[in] resource resource to inquire about 576 * @param[out] sid pointer to return StreamID 577 * 578 * @return Returns an error code (SC_ERR_NONE = success). 579 * 580 * Return errors: 581 * - SC_PARM if \a resource is out of range 582 */ 583 sc_err_t sc_rm_get_resource_info(sc_ipc_t ipc, sc_rsrc_t resource, 584 sc_rm_sid_t *sid); 585 586 /* @} */ 587 588 /*! 589 * @name Memory Region Functions 590 * @{ 591 */ 592 593 /*! 594 * This function requests that the SC create a new memory region. 595 * 596 * @param[in] ipc IPC handle 597 * @param[out] mr return handle for region; used for 598 * subsequent function calls 599 * associated with this region 600 * @param[in] addr_start start address of region (physical) 601 * @param[in] addr_end end address of region (physical) 602 * 603 * @return Returns an error code (SC_ERR_NONE = success). 604 * 605 * Return errors: 606 * - SC_ERR_PARM if the new memory region is misaligned, 607 * - SC_ERR_LOCKED if caller's partition is locked, 608 * - SC_ERR_PARM if the new memory region spans multiple existing regions, 609 * - SC_ERR_NOACCESS if caller's partition does not own the memory containing 610 * the new region, 611 * - SC_ERR_UNAVAILABLE if memory region table is full (no more allocation 612 * space) 613 * 614 * This function will create a new memory region. The area covered by the 615 * new region must already exist in a memory region owned by the caller. The 616 * result will be two memory regions, the new one overlapping the existing 617 * one. The new region has higher priority. See the XRDC2 MRC documentation 618 * for how it resolves access permissions in this case. By default, the new 619 * region will have access permission set to allow the caller to access. 620 */ 621 sc_err_t sc_rm_memreg_alloc(sc_ipc_t ipc, sc_rm_mr_t *mr, 622 sc_faddr_t addr_start, sc_faddr_t addr_end); 623 624 /*! 625 * This function requests that the SC split an existing memory region. 626 * 627 * @param[in] ipc IPC handle 628 * @param[in] mr handle of memory region to split 629 * @param[out] mr_ret return handle for new region; used for 630 * subsequent function calls 631 * associated with this region 632 * @param[in] addr_start start address of region (physical) 633 * @param[in] addr_end end address of region (physical) 634 * 635 * @return Returns an error code (SC_ERR_NONE = success). 636 * 637 * Return errors: 638 * - SC_ERR_PARM if the new memory region is not start/end part of mr, 639 * - SC_ERR_LOCKED if caller's partition is locked, 640 * - SC_ERR_PARM if the new memory region spans multiple existing regions, 641 * - SC_ERR_NOACCESS if caller's partition does not own the memory containing 642 * the new region, 643 * - SC_ERR_UNAVAILABLE if memory region table is full (no more allocation 644 * space) 645 * 646 * This function will take an existing region and split it into two, 647 * non-overlapping regions. Note the new region must start or end on the 648 * split region. 649 */ 650 sc_err_t sc_rm_memreg_split(sc_ipc_t ipc, sc_rm_mr_t mr, 651 sc_rm_mr_t *mr_ret, sc_faddr_t addr_start, sc_faddr_t addr_end); 652 653 /*! 654 * This function requests that the SC fragment a memory region. 655 * 656 * @param[in] ipc IPC handle 657 * @param[out] mr_ret return handle for new region; used for 658 * subsequent function calls 659 * associated with this region 660 * @param[in] addr_start start address of region (physical) 661 * @param[in] addr_end end address of region (physical) 662 * 663 * @return Returns an error code (SC_ERR_NONE = success). 664 * 665 * Return errors: 666 * - SC_ERR_LOCKED if caller's partition is locked, 667 * - SC_ERR_PARM if the new memory region spans multiple existing regions, 668 * - SC_ERR_NOACCESS if caller's partition does not own the memory containing 669 * the new region, 670 * - SC_ERR_UNAVAILABLE if memory region table is full (no more allocation 671 * space) 672 * 673 * This function finds the memory region containing the address range. 674 * It then splits it as required and returns the extracted region. The 675 * result is 2-3 non-overlapping regions, depending on how the new region 676 * aligns with existing regions. 677 */ 678 sc_err_t sc_rm_memreg_frag(sc_ipc_t ipc, sc_rm_mr_t *mr_ret, 679 sc_faddr_t addr_start, sc_faddr_t addr_end); 680 681 /*! 682 * This function frees a memory region. 683 * 684 * @param[in] ipc IPC handle 685 * @param[in] mr handle of memory region to free 686 * 687 * @return Returns an error code (SC_ERR_NONE = success). 688 * 689 * Return errors: 690 * - SC_PARM if \a mr out of range or invalid, 691 * - SC_ERR_NOACCESS if caller's partition is not a parent of \a mr, 692 * - SC_ERR_LOCKED if the owning partition of \a mr is locked 693 */ 694 sc_err_t sc_rm_memreg_free(sc_ipc_t ipc, sc_rm_mr_t mr); 695 696 /*! 697 * Internal SC function to find a memory region. 698 * 699 * @see sc_rm_find_memreg(). 700 */ 701 /*! 702 * This function finds a memory region. 703 * 704 * @param[in] ipc IPC handle 705 * @param[out] mr return handle for region; used for 706 * subsequent function calls 707 * associated with this region 708 * @param[in] addr_start start address of region to search for 709 * @param[in] addr_end end address of region to search for 710 * 711 * @return Returns an error code (SC_ERR_NONE = success). 712 * 713 * Return errors: 714 * - SC_ERR_NOTFOUND if region not found, 715 * 716 * Searches only for regions owned by the caller. Finds first 717 * region containing the range specified. 718 */ 719 sc_err_t sc_rm_find_memreg(sc_ipc_t ipc, sc_rm_mr_t *mr, 720 sc_faddr_t addr_start, sc_faddr_t addr_end); 721 722 /*! 723 * This function assigns ownership of a memory region. 724 * 725 * @param[in] ipc IPC handle 726 * @param[in] pt handle of partition to which memory region 727 * should be assigned 728 * @param[in] mr handle of memory region to assign 729 * 730 * @return Returns an error code (SC_ERR_NONE = success). 731 * 732 * This function assigns a memory region to a partition. This partition is then 733 * the owner. All regions always have an owner (one owner). The owner 734 * has various rights to make API calls affecting the region. Ownership 735 * does not imply access to the memory itself (that is based on access 736 * rights). 737 * 738 * Return errors: 739 * - SC_PARM if arguments out of range or invalid, 740 * - SC_ERR_NOACCESS if caller's partition is not the \a mr owner or parent 741 * of the owner, 742 * - SC_ERR_LOCKED if the owning partition or \a pt is locked 743 */ 744 sc_err_t sc_rm_assign_memreg(sc_ipc_t ipc, sc_rm_pt_t pt, sc_rm_mr_t mr); 745 746 /*! 747 * This function sets access permissions for a memory region. 748 * 749 * @param[in] ipc IPC handle 750 * @param[in] mr handle of memory region for which permissions 751 * should apply 752 * @param[in] pt handle of partition \a perm should by 753 * applied for 754 * @param[in] perm permissions to apply to \a mr for \a pt 755 * 756 * This operates on the memory region specified. If SC_RM_PT_ALL is specified 757 * then it operates on all the regions owned by the caller that exist at the 758 * time of the call. 759 * 760 * @return Returns an error code (SC_ERR_NONE = success). 761 * 762 * Return errors: 763 * - SC_PARM if arguments out of range or invalid, 764 * - SC_ERR_NOACCESS if caller's partition is not the region owner or parent 765 * of the owner, 766 * - SC_ERR_LOCKED if the owning partition is locked 767 * - SC_ERR_LOCKED if the \a pt is confidential and the caller isn't \a pt 768 * 769 * This function configures how the HW isolation will restrict access to a 770 * memory region based on the attributes of a transaction from bus master. 771 */ 772 sc_err_t sc_rm_set_memreg_permissions(sc_ipc_t ipc, sc_rm_mr_t mr, 773 sc_rm_pt_t pt, sc_rm_perm_t perm); 774 775 /*! 776 * This function gets ownership status of a memory region. 777 * 778 * @param[in] ipc IPC handle 779 * @param[in] mr handle of memory region to check 780 * 781 * @return Returns a boolean (SC_TRUE if caller's partition owns the 782 * memory region). 783 * 784 * If \a mr is out of range then SC_FALSE is returned. 785 */ 786 sc_bool_t sc_rm_is_memreg_owned(sc_ipc_t ipc, sc_rm_mr_t mr); 787 788 /*! 789 * This function is used to obtain info about a memory region. 790 * 791 * @param[in] ipc IPC handle 792 * @param[in] mr handle of memory region to inquire about 793 * @param[out] addr_start pointer to return start address 794 * @param[out] addr_end pointer to return end address 795 * 796 * @return Returns an error code (SC_ERR_NONE = success). 797 * 798 * Return errors: 799 * - SC_PARM if \a mr is out of range 800 */ 801 sc_err_t sc_rm_get_memreg_info(sc_ipc_t ipc, sc_rm_mr_t mr, 802 sc_faddr_t *addr_start, sc_faddr_t *addr_end); 803 804 /* @} */ 805 806 /*! 807 * @name Pad Functions 808 * @{ 809 */ 810 811 /*! 812 * This function assigns ownership of a pad to a partition. 813 * 814 * @param[in] ipc IPC handle 815 * @param[in] pt handle of partition to which pad should 816 * be assigned 817 * @param[in] pad pad to assign 818 * 819 * @return Returns an error code (SC_ERR_NONE = success). 820 * 821 * Return errors: 822 * - SC_ERR_NOACCESS if caller's partition is restricted, 823 * - SC_PARM if arguments out of range or invalid, 824 * - SC_ERR_NOACCESS if caller's partition is not the pad owner or parent 825 * of the owner, 826 * - SC_ERR_LOCKED if the owning partition or \a pt is locked 827 */ 828 sc_err_t sc_rm_assign_pad(sc_ipc_t ipc, sc_rm_pt_t pt, sc_pad_t pad); 829 830 /*! 831 * This function flags pads as movable or not. 832 * 833 * @param[in] ipc IPC handle 834 * @param[in] pad_fst first pad for which flag should be set 835 * @param[in] pad_lst last pad for which flag should be set 836 * @param[in] movable movable flag (SC_TRUE is movable) 837 * 838 * This function assigned a pad to a partition. This partition is then 839 * the owner. All pads always have an owner (one owner). The owner 840 * has various rights to make API calls affecting the pad. 841 * 842 * @return Returns an error code (SC_ERR_NONE = success). 843 * 844 * Return errors: 845 * - SC_PARM if pads are out of range, 846 * - SC_ERR_NOACCESS if caller's partition is not a parent of a pad owner, 847 * - SC_ERR_LOCKED if the owning partition is locked 848 * 849 * This function is used to determine the set of pads that will be 850 * moved using the sc_rm_move_all() function. All pads are movable 851 * by default so this function is normally used to prevent a set of 852 * pads from moving. 853 */ 854 sc_err_t sc_rm_set_pad_movable(sc_ipc_t ipc, sc_pad_t pad_fst, 855 sc_pad_t pad_lst, sc_bool_t movable); 856 857 /*! 858 * This function gets ownership status of a pad. 859 * 860 * @param[in] ipc IPC handle 861 * @param[in] pad pad to check 862 * 863 * @return Returns a boolean (SC_TRUE if caller's partition owns the pad). 864 * 865 * If \a pad is out of range then SC_FALSE is returned. 866 */ 867 sc_bool_t sc_rm_is_pad_owned(sc_ipc_t ipc, sc_pad_t pad); 868 869 /* @} */ 870 871 /*! 872 * @name Debug Functions 873 * @{ 874 */ 875 876 /*! 877 * This function dumps the RM state for debug. 878 * 879 * @param[in] ipc IPC handle 880 */ 881 void sc_rm_dump(sc_ipc_t ipc); 882 883 /* @} */ 884 885 #endif /* SC_RM_API_H */ 886 887 /**@}*/ 888 889
