1 /***************************************************************************//** 2 * \file cyhal_hwmgr.h 3 * 4 * \brief 5 * Provides a high level interface for managing hardware resources. This is 6 * used to track what hardware blocks are already being used so they are not over 7 * allocated. 8 * 9 ******************************************************************************** 10 * \copyright 11 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 12 * an affiliate of Cypress Semiconductor Corporation 13 * 14 * SPDX-License-Identifier: Apache-2.0 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); 17 * you may not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, 24 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 *******************************************************************************/ 28 29 /** 30 * \addtogroup group_hal_hwmgr HWMGR (Hardware Manager) 31 * \ingroup group_hal 32 * \{ 33 * High level interface to the Hardware Manager. 34 * 35 * \section section_hwmgr_features Features 36 * * Allows HAL drivers or application firmware to mark specific hardware resources 37 * as reserved. When this is done, other reservation requests for the same resource will be denied. 38 * * For resources which are interchangeable such as clock dividers, provides allocation 39 * and reservation of an available instance. 40 * 41 * \section section_hwmgr_quickstart Quick Start 42 * * \ref cyhal_hwmgr_init is used to initialize the hardware manager to keep 43 * track of resources being used. 44 * * \ref cyhal_hwmgr_reserve reserves a specified resource if available. 45 * * \ref cyhal_hwmgr_free frees the specified resource. 46 * * \ref cyhal_hwmgr_allocate can be used to allocate a free block of specified 47 * resource, if available. 48 * 49 * 50 * \section section_hwmgr_snippets Code snippets 51 * \subsection subsection_hwmgr_snippet_1 Snippet 1: Freeing a block used by PDL or configurators 52 * The following snippet shows how a specific resource used directly in PDL or the 53 * configurators can be freed so that it can be used by HAL.<br> 54 * 55 * \snippet hal_hwmgr.c snippet_cyhal_hwmgr_reserve 56 */ 57 58 #pragma once 59 60 #include <stdint.h> 61 #include <stdbool.h> 62 #include "cy_result.h" 63 #include "cyhal_hw_types.h" 64 65 #if defined(__cplusplus) 66 extern "C" { 67 #endif 68 69 /** \addtogroup group_hal_results_hwmgr HWMGR HAL Results 70 * HWMGR specific return codes 71 * \ingroup group_hal_results 72 * \{ *//** 73 */ 74 75 /** The requested resource type is invalid */ 76 #define CYHAL_HWMGR_RSLT_ERR_INVALID \ 77 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_HWMGR, 0)) 78 /** The requested resource is already in use */ 79 #define CYHAL_HWMGR_RSLT_ERR_INUSE \ 80 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_HWMGR, 1)) 81 /** No resources of the requested type are available */ 82 #define CYHAL_HWMGR_RSLT_ERR_NONE_FREE \ 83 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_HWMGR, 2)) 84 /** No hardware connection available */ 85 #define CYHAL_HWMGR_RSLT_ERR_NO_CONNECTION \ 86 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_HWMGR, 3)) 87 /** Attempt to free a resource that was not used */ 88 #define CYHAL_HWMGR_RSLT_WARN_UNUSED \ 89 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_WARNING, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_HWMGR, 50)) 90 91 /** 92 * \} 93 */ 94 95 96 97 98 /** Initializes the hardware manager to keep track of what resources are being used. 99 * 100 * @return The status of the init request 101 * 102 */ 103 cy_rslt_t cyhal_hwmgr_init(void); 104 105 /** Reserve the specified resource. The exact block number and 106 * channel number must be specified. If this is not know, use 107 * \ref cyhal_hwmgr_allocate. 108 * 109 * \note This function is called by the init function of hardware blocks. 110 * Calling this again for the same block will result in error since the hardware 111 * block is already marked as consumed. 112 * 113 * @param[in] obj The resource object that should be reserved 114 * @return The status of the reserve request 115 * 116 * See \ref subsection_hwmgr_snippet_1 117 */ 118 cy_rslt_t cyhal_hwmgr_reserve(const cyhal_resource_inst_t* obj); 119 120 /** Free the specified resource to allow it to be reused. 121 * 122 * @param[in,out] obj The resource object to free 123 * 124 * See \ref subsection_hwmgr_snippet_1 125 */ 126 void cyhal_hwmgr_free(const cyhal_resource_inst_t* obj); 127 128 /** Allocates a free block of the specified type if available 129 * This function is used when the exact block number and channel number of the 130 * resource is not known. This function loops through all available resource 131 * of the specified type and assigns the resource if available. 132 * This function internally calls \ref cyhal_hwmgr_reserve function and hence, 133 * it should not be called again. 134 * 135 * @param[in] type The type of resource to allocate. 136 * @param[out] obj The resource object. 137 * @return The status of the allocate request. 138 * 139 */ 140 cy_rslt_t cyhal_hwmgr_allocate(cyhal_resource_t type, cyhal_resource_inst_t* obj); 141 142 #if defined(__cplusplus) 143 } 144 #endif 145 146 #ifdef CYHAL_HWMGR_IMPL_HEADER 147 #include CYHAL_HWMGR_IMPL_HEADER 148 #endif /* CYHAL_HWMGR_IMPL_HEADER */ 149 150 /** \} group_hal_hwmgr */ 151
