Line data Source code
1 0 : /* 2 : * Copyright (c) 2020 Intel Corporation 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : #ifndef ZEPHYR_INCLUDE_SYS_KOBJECT_H 7 : #define ZEPHYR_INCLUDE_SYS_KOBJECT_H 8 : 9 : #include <stdint.h> 10 : #include <stddef.h> 11 : 12 : #include <zephyr/sys/iterable_sections.h> 13 : #include <zephyr/sys/internal/kobject_internal.h> 14 : 15 : #ifdef __cplusplus 16 : extern "C" { 17 : #endif 18 : 19 : struct k_thread; 20 : struct k_mutex; 21 : struct z_futex_data; 22 : 23 : /** 24 : * @brief Kernel Object Types 25 : * 26 : * This enumeration needs to be kept in sync with the lists of kernel objects 27 : * and subsystems in scripts/build/gen_kobject_list.py, as well as the otype_to_str() 28 : * function in kernel/userspace.c 29 : */ 30 0 : enum k_objects { 31 : K_OBJ_ANY, 32 : 33 : /** @cond 34 : * Doxygen should ignore this build-time generated include file 35 : * when generating API documentation. Enumeration values are 36 : * generated during build by gen_kobject_list.py. It includes 37 : * basic kernel objects (e.g. pipes and mutexes) and driver types. 38 : */ 39 : #include <zephyr/kobj-types-enum.h> 40 : /** @endcond 41 : */ 42 : 43 : K_OBJ_LAST 44 : }; 45 : /** 46 : * @defgroup usermode_apis User Mode APIs 47 : * @ingroup kernel_apis 48 : * @{ 49 : */ 50 : 51 : #ifdef CONFIG_USERSPACE 52 : 53 : /** 54 : * @brief Grant a static thread access to a list of kernel objects 55 : * 56 : * For threads declared with K_THREAD_DEFINE(), grant the thread access to 57 : * a set of kernel objects. These objects do not need to be in an initialized 58 : * state. The permissions will be granted when the threads are initialized 59 : * in the early boot sequence. 60 : * 61 : * All arguments beyond the first must be pointers to kernel objects. 62 : * 63 : * @param name_ Name of the thread, as passed to K_THREAD_DEFINE() 64 : */ 65 1 : #define K_THREAD_ACCESS_GRANT(name_, ...) \ 66 : static void * const _CONCAT(_object_list_, name_)[] = \ 67 : { __VA_ARGS__, NULL }; \ 68 : static const STRUCT_SECTION_ITERABLE(k_object_assignment, \ 69 : _CONCAT(_object_access_, name_)) = \ 70 : { (&_k_thread_obj_ ## name_), \ 71 : (_CONCAT(_object_list_, name_)) } 72 : 73 : /** Object initialized */ 74 1 : #define K_OBJ_FLAG_INITIALIZED BIT(0) 75 : /** Object is Public */ 76 1 : #define K_OBJ_FLAG_PUBLIC BIT(1) 77 : /** Object allocated */ 78 1 : #define K_OBJ_FLAG_ALLOC BIT(2) 79 : /** Driver Object */ 80 1 : #define K_OBJ_FLAG_DRIVER BIT(3) 81 : 82 : /** 83 : * Grant a thread access to a kernel object 84 : * 85 : * The thread will be granted access to the object if the caller is from 86 : * supervisor mode, or the caller is from user mode AND has permissions 87 : * on both the object and the thread whose access is being granted. 88 : * 89 : * @param object Address of kernel object 90 : * @param thread Thread to grant access to the object 91 : */ 92 1 : __syscall void k_object_access_grant(const void *object, 93 : struct k_thread *thread); 94 : 95 : /** 96 : * Revoke a thread's access to a kernel object 97 : * 98 : * The thread will lose access to the object if the caller is from 99 : * supervisor mode, or the caller is from user mode AND has permissions 100 : * on both the object and the thread whose access is being revoked. 101 : * 102 : * @param object Address of kernel object 103 : * @param thread Thread to remove access to the object 104 : */ 105 1 : void k_object_access_revoke(const void *object, struct k_thread *thread); 106 : 107 : /** 108 : * @brief Release an object 109 : * 110 : * Allows user threads to drop their own permission on an object 111 : * Their permissions are automatically cleared when a thread terminates. 112 : * 113 : * @param object The object to be released 114 : * 115 : */ 116 1 : __syscall void k_object_release(const void *object); 117 : 118 : /** 119 : * Grant all present and future threads access to an object 120 : * 121 : * If the caller is from supervisor mode, or the caller is from user mode and 122 : * have sufficient permissions on the object, then that object will have 123 : * permissions granted to it for *all* current and future threads running in 124 : * the system, effectively becoming a public kernel object. 125 : * 126 : * Use of this API should be avoided on systems that are running untrusted code 127 : * as it is possible for such code to derive the addresses of kernel objects 128 : * and perform unwanted operations on them. 129 : * 130 : * It is not possible to revoke permissions on public objects; once public, 131 : * any thread may use it. 132 : * 133 : * @param object Address of kernel object 134 : */ 135 1 : void k_object_access_all_grant(const void *object); 136 : 137 : /** 138 : * Check if a kernel object is of certain type and is valid. 139 : * 140 : * This checks if the kernel object exists, of certain type, 141 : * and has been initialized. 142 : * 143 : * @param obj Address of the kernel object 144 : * @param otype Object type (use K_OBJ_ANY for ignoring type checking) 145 : * @return True if kernel object (@a obj) exists, of certain type, and 146 : * has been initialized. False otherwise. 147 : */ 148 1 : bool k_object_is_valid(const void *obj, enum k_objects otype); 149 : 150 : #else 151 : /* LCOV_EXCL_START */ 152 : #define K_THREAD_ACCESS_GRANT(thread, ...) 153 : 154 : /** 155 : * @internal 156 : */ 157 : static inline void z_impl_k_object_access_grant(const void *object, 158 : struct k_thread *thread) 159 : { 160 : ARG_UNUSED(object); 161 : ARG_UNUSED(thread); 162 : } 163 : 164 : /** 165 : * @internal 166 : */ 167 : static inline void k_object_access_revoke(const void *object, 168 : struct k_thread *thread) 169 : { 170 : ARG_UNUSED(object); 171 : ARG_UNUSED(thread); 172 : } 173 : 174 : /** 175 : * @internal 176 : */ 177 : static inline void z_impl_k_object_release(const void *object) 178 : { 179 : ARG_UNUSED(object); 180 : } 181 : 182 : static inline void k_object_access_all_grant(const void *object) 183 : { 184 : ARG_UNUSED(object); 185 : } 186 : 187 : static inline bool k_object_is_valid(const void *obj, enum k_objects otype) 188 : { 189 : ARG_UNUSED(obj); 190 : ARG_UNUSED(otype); 191 : 192 : return true; 193 : } 194 : 195 : /* LCOV_EXCL_STOP */ 196 : #endif /* !CONFIG_USERSPACE */ 197 : 198 : #if defined(CONFIG_DYNAMIC_OBJECTS) || defined(__DOXYGEN__) 199 : /** 200 : * Allocate a kernel object of a designated type 201 : * 202 : * This will instantiate at runtime a kernel object of the specified type, 203 : * returning a pointer to it. The object will be returned in an uninitialized 204 : * state, with the calling thread being granted permission on it. The memory 205 : * for the object will be allocated out of the calling thread's resource pool. 206 : * 207 : * @note This function is available only if @kconfig{CONFIG_DYNAMIC_OBJECTS} 208 : * is selected. 209 : * 210 : * @note Thread stack object has to use k_object_alloc_size() since stacks may 211 : * have different sizes. 212 : * 213 : * @param otype Requested kernel object type 214 : * @return A pointer to the allocated kernel object, or NULL if memory wasn't 215 : * available 216 : */ 217 1 : __syscall void *k_object_alloc(enum k_objects otype); 218 : 219 : /** 220 : * Allocate a kernel object of a designated type and a given size 221 : * 222 : * This will instantiate at runtime a kernel object of the specified type, 223 : * returning a pointer to it. The object will be returned in an uninitialized 224 : * state, with the calling thread being granted permission on it. The memory 225 : * for the object will be allocated out of the calling thread's resource pool. 226 : * 227 : * This function is specially helpful for thread stack objects because 228 : * their sizes can vary. Other objects should probably look k_object_alloc(). 229 : * 230 : * @note This function is available only if @kconfig{CONFIG_DYNAMIC_OBJECTS} 231 : * is selected. 232 : * 233 : * @param otype Requested kernel object type 234 : * @param size Requested kernel object size 235 : * @return A pointer to the allocated kernel object, or NULL if memory wasn't 236 : * available 237 : */ 238 1 : __syscall void *k_object_alloc_size(enum k_objects otype, size_t size); 239 : 240 : /** 241 : * Free a kernel object previously allocated with k_object_alloc() 242 : * 243 : * This will return memory for a kernel object back to resource pool it was 244 : * allocated from. Care must be exercised that the object will not be used 245 : * during or after when this call is made. 246 : * 247 : * @note This function is available only if @kconfig{CONFIG_DYNAMIC_OBJECTS} 248 : * is selected. 249 : * 250 : * @param obj Pointer to the kernel object memory address. 251 : */ 252 1 : void k_object_free(void *obj); 253 : #else 254 : 255 : /* LCOV_EXCL_START */ 256 : static inline void *z_impl_k_object_alloc(enum k_objects otype) 257 : { 258 : ARG_UNUSED(otype); 259 : 260 : return NULL; 261 : } 262 : 263 : static inline void *z_impl_k_object_alloc_size(enum k_objects otype, 264 : size_t size) 265 : { 266 : ARG_UNUSED(otype); 267 : ARG_UNUSED(size); 268 : 269 : return NULL; 270 : } 271 : 272 : /** 273 : * @brief Free an object 274 : * 275 : * @param obj 276 : */ 277 : static inline void k_object_free(void *obj) 278 : { 279 : ARG_UNUSED(obj); 280 : } 281 : /* LCOV_EXCL_STOP */ 282 : #endif /* CONFIG_DYNAMIC_OBJECTS */ 283 : 284 : /** @} */ 285 : 286 : #include <zephyr/syscalls/kobject.h> 287 : #ifdef __cplusplus 288 : } 289 : #endif 290 : 291 : #endif
