Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
handles_manager.h
1 /* Copyright (c) 2017-2018 ARM Limited
2  *
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef __MBED_HANDLE_MANAGER_H__
19 #define __MBED_HANDLE_MANAGER_H__
20 
21 /* -------------------------------------- Includes ----------------------------------- */
22 
23 #include "psa_defs.h"
24 
25 #include <stdint.h>
26 
27 /* -------------------------------- Handle Manager Module ---------------------------- */
28 
29 /*
30  * The Handle Manager module generates and exposes a unique
31  * identifier (handle) per handle memory (handle_mem) it receives.
32  * You can use the exposed handle identifier to relate to the "registered"
33  * handle memory.
34  *
35  * You can:
36  * - Ask for a unique handle identifier for a given handle memory [`handle_create`].
37  * - Ask for a pointer to the handle memory corresponding to a
38  * handle identifier [`handle_get_mem`].
39  * - Remove a handle from the handle manager module [`handle_destroy`].
40  *
41  * Note:
42  * Handle generation is done exclusively.
43  * Once you have a handle, you can remove or get its memory non-exclusively.
44  * The assumption is that only one context is dealing with a handle after it is
45  * generated.
46  */
47 
48 /* --------------------------------- extern "C" wrapper ------------------------------ */
49 
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53 
54 
55 
56 /* ------------------------------------ Definitions ---------------------------------- */
57 
58 #define PSA_HANDLE_MGR_INVALID_HANDLE ((uint16_t)PSA_NULL_HANDLE)
59 
60 #define PSA_HANDLE_MGR_INVALID_FRIEND_OWNER 0 // Denoting invalid friend or invalid owner
61 
62 // Handle manager pool indexes must be in range 0 - 0x7FFF.
63 // This is because the index is stored in the upper 16 bits of a handle,
64 // and the most significant bit must be zero to keep handles non-negative.
65 #define PSA_HANDLE_MGR_MAX_HANDLES_NUM 0x8000
66 
67 
68 
69 /* -------------------------------------- Structs ------------------------------------ */
70 
71 typedef struct psa_handle_item_t {
72 
73  psa_handle_t handle; /* The user-exposed handle [unique identifier]. */
74  int32_t handle_owner; /* The partition ID of the handle creator. Allowed to get_mem() / destroy(). */
75  int32_t handle_friend; /* The partition ID of a "friend" partition. Allowed to get_mem(). */
76  void *handle_mem; /* Points to memory allocated by the use.r */
77 
78 } psa_handle_item_t;
79 
80 
81 typedef struct psa_handle_manager_t {
82 
83  // Handle generator uses only 16 bits, and wraps.
84  // The reason for this is that we use the 16 upper bits to store the handle's index in the handles pool (for performance reasons)
85  uint16_t handle_generator; /* A counter supplying handle numbers. */
86  uint16_t pool_size; /* The maximum number of handles that pool can contain. */
87  psa_handle_item_t *handles_pool; /* Holds couples of handles and their memory "blocks". */
88 
89 } psa_handle_manager_t;
90 
91 
92 /*
93 handles_pool
94  |
95  |
96  |
97  --> *--------------------------------------------------------------------------*
98  | handle | handle | handle | | | ... |
99  *--------------------------------------------------------------------------*
100  | handle_owner | handle_owner | handle_owner | | | ... |
101  *--------------------------------------------------------------------------*
102  | handle_friend | handle_friend | handle_friend | | | ... |
103  *--------------------------------------------------------------------------*
104  | handle_mem | handle_mem | handle_mem | | | ... |
105  *--------------------------------------------------------------------------*
106 */
107 
108 
109 
110 /* ------------------------------------- Functions ----------------------------------- */
111 
112 
113 /*
114  * @brief Create unique handle identifier
115  *
116  * This function generates a unique handle identifier, and **couples** it with the received handle memory.
117  * If there is no vacant space for the new handle, the function fails.
118  *
119  * @note This function is expected to pass since it is always coupled with memory pool allocation of the same size.
120  * In case memory pool allocation fails, this function should not be called.
121  * This function will panic in the case of non-vacant space use.
122  *
123  * @param[in] handle_mgr A pointer to the handle manager object.
124  * @param[in] handle_mem A pointer to a pre-allocated handle memory for which to get a handle identifier.
125  * @param[in] friend_pid The partition ID allowed to `get_mem()` and `destroy()` in addition to the handle owner.
126  * Use `PSA_HANDLE_MGR_INVALID_FRIEND_OWNER` to denote that there is no friend partition.
127  * @return The created handle identifier
128  */
129 psa_handle_t psa_hndl_mgr_handle_create(psa_handle_manager_t *handle_mgr, void *handle_mem, int32_t friend_pid);
130 
131 
132 /*
133  * @brief Remove a handle from the handle manager.
134  *
135  * @param handle_mgr A pointer to the handle manager object.
136  * @param handle The handle to be removed.
137  */
138 void psa_hndl_mgr_handle_destroy(psa_handle_manager_t *handle_mgr, psa_handle_t handle);
139 
140 
141 /*
142  * @brief De-reference handle
143  *
144  * This function retrieves the pointer associated with the input <handle>.
145  *
146  * @note This function will panic if caller is not allowed to de-reference the memory,
147  * or handler does not correspond to a valid existing handle.
148  *
149  * @param handle_mgr A pointer to the handle manager object.
150  * @param handle The handle for which you request the corresponding memory handle.
151  * @return void* A pointer to the memory corresponding to the handle.
152  */
153 void *psa_hndl_mgr_handle_get_mem(psa_handle_manager_t *handle_mgr, psa_handle_t handle);
154 
155 
156 #ifdef __cplusplus
157 }
158 #endif
159 
160 #endif /* __MBED_HANDLE_MANAGER_H__ */
psa_handle_manager_t
Definition: handles_manager.h:81
psa_handle_item_t
Definition: handles_manager.h:71
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.