2 * Copyright (c) 2017 Jakub Jermar
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 /** @addtogroup kernel_generic
36 * HelenOS capabilities are task-local names for references to kernel objects.
37 * Kernel objects are reference-counted wrappers for a select group of objects
38 * allocated in and by the kernel that can be made accessible to userspace in a
39 * controlled way via integer handles.
41 * A kernel object (kobject_t) encapsulates one of the following raw objects:
47 * A capability (cap_t) is either free, allocated or published. Free
48 * capabilities can be allocated, which reserves the capability handle in the
49 * task-local capability space. Allocated capabilities can be published, which
50 * associates them with an existing kernel object. Userspace can only access
51 * published capabilities.
53 * A published capability may get unpublished, which disassociates it from the
54 * underlying kernel object and puts it back into the allocated state. An
55 * allocated capability can be freed to become available for future use.
57 * There is a 1:1 correspondence between a kernel object (kobject_t) and the
58 * actual raw object it encapsulates. A kernel object (kobject_t) may have
59 * multiple references, either implicit from one or more capabilities (cap_t),
60 * even from capabilities in different tasks, or explicit as a result of
61 * creating a new reference from a capability handle using kobject_get(), or
62 * creating a new reference from an already existing reference by
63 * kobject_add_ref() or as a result of unpublishing a capability and
64 * disassociating it from its kobject_t using cap_unpublish().
66 * A holder of an explicit reference to a kernel object may revoke access to it
67 * from all capabilities that point to it by calling cap_revoke().
69 * As kernel objects are reference-counted, they get automatically destroyed
70 * when their last reference is dropped in kobject_put(). The idea is that
71 * whenever a kernel object is inserted into some sort of a container (e.g. a
72 * list or hash table), its reference count should be incremented via
73 * kobject_get() or kobject_add_ref(). When the kernel object is removed from
74 * the container, the reference count should go down via a call to
80 #include <proc/task.h>
81 #include <synch/mutex.h>
82 #include <abi/errno.h>
90 #define CAPS_START (CAP_NIL + 1)
91 #define CAPS_SIZE (INT_MAX - CAPS_START)
92 #define CAPS_LAST (CAPS_SIZE - 1)
94 static slab_cache_t
*cap_cache
;
95 static slab_cache_t
*kobject_cache
;
97 static size_t caps_hash(const ht_link_t
*item
)
99 cap_t
*cap
= hash_table_get_inst(item
, cap_t
, caps_link
);
100 return hash_mix(CAP_HANDLE_RAW(cap
->handle
));
103 static size_t caps_key_hash(void *key
)
105 cap_handle_t
*handle
= (cap_handle_t
*) key
;
106 return hash_mix(CAP_HANDLE_RAW(*handle
));
109 static bool caps_key_equal(void *key
, const ht_link_t
*item
)
111 cap_handle_t
*handle
= (cap_handle_t
*) key
;
112 cap_t
*cap
= hash_table_get_inst(item
, cap_t
, caps_link
);
113 return *handle
== cap
->handle
;
116 static hash_table_ops_t caps_ops
= {
118 .key_hash
= caps_key_hash
,
119 .key_equal
= caps_key_equal
124 cap_cache
= slab_cache_create("cap_t", sizeof(cap_t
), 0, NULL
,
126 kobject_cache
= slab_cache_create("kobject_t", sizeof(kobject_t
), 0,
130 /** Allocate the capability info structure
132 * @param task Task for which to allocate the info structure.
134 errno_t
caps_task_alloc(task_t
*task
)
136 task
->cap_info
= (cap_info_t
*) malloc(sizeof(cap_info_t
));
139 task
->cap_info
->handles
= ra_arena_create();
140 if (!task
->cap_info
->handles
)
142 if (!ra_span_add(task
->cap_info
->handles
, CAPS_START
, CAPS_SIZE
))
144 if (!hash_table_create(&task
->cap_info
->caps
, 0, 0, &caps_ops
))
149 ra_arena_destroy(task
->cap_info
->handles
);
151 free(task
->cap_info
);
155 /** Initialize the capability info structure
157 * @param task Task for which to initialize the info structure.
159 void caps_task_init(task_t
*task
)
161 mutex_initialize(&task
->cap_info
->lock
, MUTEX_RECURSIVE
);
163 for (kobject_type_t t
= 0; t
< KOBJECT_TYPE_MAX
; t
++)
164 list_initialize(&task
->cap_info
->type_list
[t
]);
167 /** Deallocate the capability info structure
169 * @param task Task from which to deallocate the info structure.
171 void caps_task_free(task_t
*task
)
173 hash_table_destroy(&task
->cap_info
->caps
);
174 ra_arena_destroy(task
->cap_info
->handles
);
175 free(task
->cap_info
);
178 /** Invoke callback function on task's capabilites of given type
180 * @param task Task where the invocation should take place.
181 * @param type Kernel object type of the task's capabilities that will be
182 * subject to the callback invocation.
183 * @param cb Callback function.
184 * @param arg Argument for the callback function.
186 * @return True if the callback was called on all matching capabilities.
187 * @return False if the callback was applied only partially.
189 bool caps_apply_to_kobject_type(task_t
*task
, kobject_type_t type
,
190 bool (*cb
)(cap_t
*, void *), void *arg
)
194 mutex_lock(&task
->cap_info
->lock
);
195 list_foreach_safe(task
->cap_info
->type_list
[type
], cur
, next
) {
196 cap_t
*cap
= list_get_instance(cur
, cap_t
, type_link
);
201 mutex_unlock(&task
->cap_info
->lock
);
206 /** Initialize capability and associate it with its handle
208 * @param cap Address of the capability.
209 * @param task Backling to the owning task.
210 * @param handle Capability handle.
212 static void cap_initialize(cap_t
*cap
, task_t
*task
, cap_handle_t handle
)
214 cap
->state
= CAP_STATE_FREE
;
216 cap
->handle
= handle
;
217 link_initialize(&cap
->kobj_link
);
218 link_initialize(&cap
->type_link
);
221 /** Get capability using capability handle
223 * @param task Task whose capability to get.
224 * @param handle Capability handle of the desired capability.
225 * @param state State in which the capability must be.
227 * @return Address of the desired capability if it exists and its state matches.
228 * @return NULL if no such capability exists or it's in a different state.
230 static cap_t
*cap_get(task_t
*task
, cap_handle_t handle
, cap_state_t state
)
232 assert(mutex_locked(&task
->cap_info
->lock
));
234 if ((CAP_HANDLE_RAW(handle
) < CAPS_START
) ||
235 (CAP_HANDLE_RAW(handle
) > CAPS_LAST
))
237 ht_link_t
*link
= hash_table_find(&task
->cap_info
->caps
, &handle
);
240 cap_t
*cap
= hash_table_get_inst(link
, cap_t
, caps_link
);
241 if (cap
->state
!= state
)
246 /** Allocate new capability
248 * @param task Task for which to allocate the new capability.
250 * @param[out] handle New capability handle on success.
252 * @return An error code in case of error.
254 errno_t
cap_alloc(task_t
*task
, cap_handle_t
*handle
)
256 mutex_lock(&task
->cap_info
->lock
);
257 cap_t
*cap
= slab_alloc(cap_cache
, FRAME_ATOMIC
);
259 mutex_unlock(&task
->cap_info
->lock
);
263 if (!ra_alloc(task
->cap_info
->handles
, 1, 1, &hbase
)) {
264 slab_free(cap_cache
, cap
);
265 mutex_unlock(&task
->cap_info
->lock
);
268 cap_initialize(cap
, task
, (cap_handle_t
) hbase
);
269 hash_table_insert(&task
->cap_info
->caps
, &cap
->caps_link
);
271 cap
->state
= CAP_STATE_ALLOCATED
;
272 *handle
= cap
->handle
;
273 mutex_unlock(&task
->cap_info
->lock
);
278 /** Publish allocated capability
280 * The kernel object is moved into the capability. In other words, its reference
281 * is handed over to the capability. Once published, userspace can access and
282 * manipulate the capability.
284 * @param task Task in which to publish the capability.
285 * @param handle Capability handle.
286 * @param kobj Kernel object.
289 cap_publish(task_t
*task
, cap_handle_t handle
, kobject_t
*kobj
)
291 mutex_lock(&kobj
->caps_list_lock
);
292 mutex_lock(&task
->cap_info
->lock
);
293 cap_t
*cap
= cap_get(task
, handle
, CAP_STATE_ALLOCATED
);
295 cap
->state
= CAP_STATE_PUBLISHED
;
296 /* Hand over kobj's reference to cap */
298 list_append(&cap
->kobj_link
, &kobj
->caps_list
);
299 list_append(&cap
->type_link
, &task
->cap_info
->type_list
[kobj
->type
]);
300 mutex_unlock(&task
->cap_info
->lock
);
301 mutex_unlock(&kobj
->caps_list_lock
);
304 static void cap_unpublish_unsafe(cap_t
*cap
)
307 list_remove(&cap
->kobj_link
);
308 list_remove(&cap
->type_link
);
309 cap
->state
= CAP_STATE_ALLOCATED
;
312 /** Unpublish published capability
314 * The kernel object is moved out of the capability. In other words, the
315 * capability's reference to the objects is handed over to the kernel object
316 * pointer returned by this function. Once unpublished, the capability does not
317 * refer to any kernel object anymore.
319 * @param task Task in which to unpublish the capability.
320 * @param handle Capability handle.
321 * @param type Kernel object type of the object associated with the
324 * @return Pointer and explicit reference to the kobject that was associated
325 * with the capability.
327 kobject_t
*cap_unpublish(task_t
*task
, cap_handle_t handle
, kobject_type_t type
)
329 kobject_t
*kobj
= NULL
;
332 mutex_lock(&task
->cap_info
->lock
);
333 cap_t
*cap
= cap_get(task
, handle
, CAP_STATE_PUBLISHED
);
335 if (cap
->kobject
->type
== type
) {
336 /* Hand over cap's reference to kobj */
338 if (!mutex_trylock(&kobj
->caps_list_lock
)) {
339 mutex_unlock(&task
->cap_info
->lock
);
343 cap_unpublish_unsafe(cap
);
344 mutex_unlock(&kobj
->caps_list_lock
);
347 mutex_unlock(&task
->cap_info
->lock
);
352 /** Revoke access to kobject from all existing capabilities
354 * All published capabilities associated with the kobject are unpublished (i.e.
355 * their new state is set to CAP_STATE_ALLOCATED) and no longer point to the
356 * kobject. Kobject's reference count is decreased accordingly.
358 * Note that the caller is supposed to hold an explicit reference to the kobject
359 * so that the kobject is guaranteed to exist when this function returns.
361 * @param kobj Pointer and explicit reference to the kobject capabilities of
362 * which are about to be unpublished.
364 void cap_revoke(kobject_t
*kobj
)
366 mutex_lock(&kobj
->caps_list_lock
);
367 list_foreach_safe(kobj
->caps_list
, cur
, hlp
) {
368 cap_t
*cap
= list_get_instance(cur
, cap_t
, kobj_link
);
369 mutex_lock(&cap
->task
->cap_info
->lock
);
370 cap_unpublish_unsafe(cap
);
371 /* Drop the reference for the unpublished capability */
373 mutex_unlock(&cap
->task
->cap_info
->lock
);
375 mutex_unlock(&kobj
->caps_list_lock
);
378 /** Free allocated capability
380 * @param task Task in which to free the capability.
381 * @param handle Capability handle.
383 void cap_free(task_t
*task
, cap_handle_t handle
)
385 assert(CAP_HANDLE_RAW(handle
) >= CAPS_START
);
386 assert(CAP_HANDLE_RAW(handle
) <= CAPS_LAST
);
388 mutex_lock(&task
->cap_info
->lock
);
389 cap_t
*cap
= cap_get(task
, handle
, CAP_STATE_ALLOCATED
);
393 hash_table_remove_item(&task
->cap_info
->caps
, &cap
->caps_link
);
394 ra_free(task
->cap_info
->handles
, CAP_HANDLE_RAW(handle
), 1);
395 slab_free(cap_cache
, cap
);
396 mutex_unlock(&task
->cap_info
->lock
);
399 kobject_t
*kobject_alloc(unsigned int flags
)
401 return slab_alloc(kobject_cache
, flags
);
404 void kobject_free(kobject_t
*kobj
)
406 slab_free(kobject_cache
, kobj
);
409 /** Initialize kernel object
411 * @param kobj Kernel object to initialize.
412 * @param type Type of the kernel object.
413 * @param raw Raw pointer to the encapsulated object.
414 * @param ops Pointer to kernel object operations for the respective type.
416 void kobject_initialize(kobject_t
*kobj
, kobject_type_t type
, void *raw
,
419 atomic_store(&kobj
->refcnt
, 1);
421 mutex_initialize(&kobj
->caps_list_lock
, MUTEX_PASSIVE
);
422 list_initialize(&kobj
->caps_list
);
429 /** Get new reference to kernel object from capability
431 * @param task Task from which to get the reference.
432 * @param handle Capability handle.
433 * @param type Kernel object type of the object associated with the
434 * capability referenced by handle.
436 * @return Kernel object with incremented reference count on success.
437 * @return NULL if there is no matching capability or kernel object.
440 kobject_get(struct task
*task
, cap_handle_t handle
, kobject_type_t type
)
442 kobject_t
*kobj
= NULL
;
444 mutex_lock(&task
->cap_info
->lock
);
445 cap_t
*cap
= cap_get(task
, handle
, CAP_STATE_PUBLISHED
);
447 if (cap
->kobject
->type
== type
) {
449 atomic_inc(&kobj
->refcnt
);
452 mutex_unlock(&task
->cap_info
->lock
);
457 /** Record new reference
459 * @param kobj Kernel object from which the new reference is created.
461 void kobject_add_ref(kobject_t
*kobj
)
463 atomic_inc(&kobj
->refcnt
);
466 /** Drop reference to kernel object
468 * The encapsulated object and the kobject_t wrapper are both destroyed when the
469 * last reference is dropped.
471 * @param kobj Kernel object whose reference to drop.
473 void kobject_put(kobject_t
*kobj
)
475 if (atomic_postdec(&kobj
->refcnt
) == 1) {
476 kobj
->ops
->destroy(kobj
->raw
);