source: mainline/kernel/generic/src/cap/cap.c@ c46bfbc

/*
 * Copyright (c) 2017 Jakub Jermar
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - The name of the author may not be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/** @addtogroup generic
 * @{
 */
/** @file
 */

/*
 * HelenOS capabilities are task-local names for references to kernel objects.
 * Kernel objects are reference-counted wrappers for a select group of objects
 * allocated in and by the kernel that can be made accessible to userspace in a
 * controlled way via integer handles.
 *
 * A kernel object (kobject_t) encapsulates one of the following raw objects:
 *
 * - IPC phone
 * - IRQ object
 *
 * A capability (cap_t) is either free, allocated or published. Free
 * capabilities can be allocated, which reserves the capability handle in the
 * task-local capability space. Allocated capabilities can be published, which
 * associates them with an existing kernel object. Userspace can only access
 * published capabilities.
 *
 * A published capability may get unpublished, which disassociates it from the
 * underlying kernel object and puts it back into the allocated state. An
 * allocated capability can be freed to become available for future use.
 *
 * There is a 1:1 correspondence between a kernel object (kobject_t) and the
 * actual raw object it encapsulates. A kernel object (kobject_t) may have
 * multiple references, either implicit from one or more capabilities (cap_t),
 * even from capabilities in different tasks, or explicit as a result of
 * creating a new reference from a capability handle using kobject_get(), or
 * creating a new reference from an already existing reference by
 * kobject_add_ref() or as a result of unpublishing a capability and
 * disassociating it from its kobject_t using cap_unpublish().
 *
 * As kernel objects are reference-counted, they get automatically destroyed
 * when their last reference is dropped in kobject_put(). The idea is that
 * whenever a kernel object is inserted into some sort of a container (e.g. a
 * list or hash table), its reference count should be incremented via
 * kobject_get() or kobject_add_ref(). When the kernel object is removed from
 * the container, the reference count should go down via a call to
 * kobject_put().
 */

#include <cap/cap.h>
#include <proc/task.h>
#include <synch/mutex.h>
#include <abi/errno.h>
#include <mm/slab.h>
#include <adt/list.h>

#include <stdint.h>

#define MAX_CAPS        INT_MAX

static kobject_t *cap_unpublish_locked(task_t *, cap_handle_t, kobject_type_t);

static size_t caps_hash(const ht_link_t *item)
{
        cap_t *cap = hash_table_get_inst(item, cap_t, caps_link);
        return hash_mix(cap->handle);
}

static size_t caps_key_hash(void *key)
{
        cap_handle_t *handle = (cap_handle_t *) key;
        return hash_mix(*handle);
}

static bool caps_key_equal(void *key, const ht_link_t *item)
{
        cap_handle_t *handle = (cap_handle_t *) key;
        cap_t *cap = hash_table_get_inst(item, cap_t, caps_link);
        return *handle == cap->handle;
}

static hash_table_ops_t caps_ops = {
        .hash = caps_hash,
        .key_hash = caps_key_hash,
        .key_equal = caps_key_equal
};

/** Allocate the capability info structure
 *
 * @param task  Task for which to allocate the info structure.
 */
int caps_task_alloc(task_t *task)
{
        task->cap_info = (cap_info_t *) malloc(sizeof(cap_info_t),
            FRAME_ATOMIC);
        if (!task->cap_info)
                return ENOMEM;
        task->cap_info->handles = ra_arena_create();
        if (!task->cap_info->handles)
                goto error_handles;
        if (!ra_span_add(task->cap_info->handles, 0, MAX_CAPS))
                goto error_span;
        if (!hash_table_create(&task->cap_info->caps, 0, 0, &caps_ops))
                goto error_span;
        return EOK;

error_span:
        ra_arena_destroy(task->cap_info->handles);
error_handles:
        free(task->cap_info);
        return ENOMEM;
}

/** Initialize the capability info structure
 *
 * @param task  Task for which to initialize the info structure.
 */
void caps_task_init(task_t *task)
{
        mutex_initialize(&task->cap_info->lock, MUTEX_PASSIVE);

        for (kobject_type_t t = 0; t < KOBJECT_TYPE_MAX; t++)
                list_initialize(&task->cap_info->type_list[t]);
}

/** Deallocate the capability info structure
 *
 * @param task  Task from which to deallocate the info structure.
 */
void caps_task_free(task_t *task)
{
        hash_table_destroy(&task->cap_info->caps);
        ra_arena_destroy(task->cap_info->handles);
        free(task->cap_info);
}

/** Invoke callback function on task's capabilites of given type
 *
 * @param task  Task where the invocation should take place.
 * @param type  Kernel object type of the task's capabilities that will be
 *              subject to the callback invocation.
 * @param cb    Callback function.
 * @param arg   Argument for the callback function.
 *
 * @return True if the callback was called on all matching capabilities.
 * @return False if the callback was applied only partially.
 */
bool caps_apply_to_kobject_type(task_t *task, kobject_type_t type,
    bool (*cb)(cap_t *, void *), void *arg)
{
        bool done = true;

        mutex_lock(&task->cap_info->lock);
        list_foreach_safe(task->cap_info->type_list[type], cur, next) {
                cap_t *cap = list_get_instance(cur, cap_t, type_link);
                done = cb(cap, arg);
                if (!done)
                        break;
        }
        mutex_unlock(&task->cap_info->lock);

        return done;
}

/** Initialize capability and associate it with its handle
 *
 * @param cap     Address of the capability.
 * @param task    Backling to the owning task.
 * @param handle  Capability handle.
 */
static void cap_initialize(cap_t *cap, task_t *task, cap_handle_t handle)
{
        cap->state = CAP_STATE_FREE;
        cap->task = task;
        cap->handle = handle;
        link_initialize(&cap->type_link);
}

/** Get capability using capability handle
 *
 * @param task    Task whose capability to get.
 * @param handle  Capability handle of the desired capability.
 * @param state   State in which the capability must be.
 *
 * @return Address of the desired capability if it exists and its state matches.
 * @return NULL if no such capability exists or it's in a different state.
 */
static cap_t *cap_get(task_t *task, cap_handle_t handle, cap_state_t state)
{
        assert(mutex_locked(&task->cap_info->lock));

        if ((handle < 0) || (handle >= MAX_CAPS))
                return NULL;
        ht_link_t *link = hash_table_find(&task->cap_info->caps, &handle);
        if (!link)
                return NULL;
        cap_t *cap = hash_table_get_inst(link, cap_t, caps_link);
        if (cap->state != state)
                return NULL;
        return cap;
}

static bool cap_reclaimer(ht_link_t *link, void *arg)
{
        cap_t **result = (cap_t **) arg;
        cap_t *cap = hash_table_get_inst(link, cap_t, caps_link);

        if (cap->state == CAP_STATE_PUBLISHED && cap->kobject->ops->reclaim &&
            cap->kobject->ops->reclaim(cap->kobject)) {
                kobject_t *kobj = cap_unpublish_locked(cap->task, cap->handle,
                    cap->kobject->type);
                kobject_put(kobj);
                cap_initialize(cap, cap->task, cap->handle);
                *result = cap;
                return false;
        }

        return true;
}

/** Allocate new capability
 *
 * @param task  Task for which to allocate the new capability.
 *
 * @return New capability handle on success.
 * @return Negative error code in case of error.
 */
cap_handle_t cap_alloc(task_t *task)
{
        cap_t *cap = NULL;
        cap_handle_t handle;

        /*
         * First of all, see if we can reclaim a capability. Note that this
         * feature is only temporary and capability reclamaition will eventually
         * be phased out.
         */
        mutex_lock(&task->cap_info->lock);
        hash_table_apply(&task->cap_info->caps, cap_reclaimer, &cap);

        /*
         * If we don't have a capability by now, try to allocate a new one.
         */
        if (!cap) {
                cap = malloc(sizeof(cap_t), 0);
                if (!cap) {
                        mutex_unlock(&task->cap_info->lock);
                        return ENOMEM;
                }
                uintptr_t hbase;
                if (!ra_alloc(task->cap_info->handles, 1, 1, &hbase)) {
                        free(cap);
                        mutex_unlock(&task->cap_info->lock);
                        return ENOMEM;
                }
                cap_initialize(cap, task, (cap_handle_t) hbase);
                hash_table_insert(&task->cap_info->caps, &cap->caps_link);
        }

        cap->state = CAP_STATE_ALLOCATED;
        handle = cap->handle;
        mutex_unlock(&task->cap_info->lock);

        return handle;
}

/** Publish allocated capability
 *
 * The kernel object is moved into the capability. In other words, its reference
 * is handed over to the capability. Once published, userspace can access and
 * manipulate the capability.
 *
 * @param task    Task in which to publish the capability.
 * @param handle  Capability handle.
 * @param kobj    Kernel object.
 */
void
cap_publish(task_t *task, cap_handle_t handle, kobject_t *kobj)
{
        mutex_lock(&task->cap_info->lock);
        cap_t *cap = cap_get(task, handle, CAP_STATE_ALLOCATED);
        assert(cap);
        cap->state = CAP_STATE_PUBLISHED;
        /* Hand over kobj's reference to cap */
        cap->kobject = kobj;
        list_append(&cap->type_link, &task->cap_info->type_list[kobj->type]);
        mutex_unlock(&task->cap_info->lock);
}

static kobject_t *
cap_unpublish_locked(task_t *task, cap_handle_t handle, kobject_type_t type)
{
        kobject_t *kobj = NULL;

        cap_t *cap = cap_get(task, handle, CAP_STATE_PUBLISHED);
        if (cap) {
                if (cap->kobject->type == type) {
                        /* Hand over cap's reference to kobj */
                        kobj = cap->kobject;
                        cap->kobject = NULL;
                        list_remove(&cap->type_link);
                        cap->state = CAP_STATE_ALLOCATED;
                }
        }

        return kobj;
}

/** Unpublish published capability
 *
 * The kernel object is moved out of the capability. In other words, the
 * capability's reference to the objects is handed over to the kernel object
 * pointer returned by this function. Once unpublished, the capability does not
 * refer to any kernel object anymore.
 *
 * @param task    Task in which to unpublish the capability.
 * @param handle  Capability handle.
 * @param type    Kernel object type of the object associated with the
 *                capability.
 */
kobject_t *cap_unpublish(task_t *task, cap_handle_t handle, kobject_type_t type)
{

        mutex_lock(&task->cap_info->lock);
        kobject_t *kobj = cap_unpublish_locked(task, handle, type);
        mutex_unlock(&task->cap_info->lock);

        return kobj;
}

/** Free allocated capability
 *
 * @param task    Task in which to free the capability.
 * @param handle  Capability handle.
 */
void cap_free(task_t *task, cap_handle_t handle)
{
        assert(handle >= 0);
        assert(handle < MAX_CAPS);

        mutex_lock(&task->cap_info->lock);
        cap_t *cap = cap_get(task, handle, CAP_STATE_ALLOCATED);

        assert(cap);

        hash_table_remove_item(&task->cap_info->caps, &cap->caps_link);
        ra_free(task->cap_info->handles, handle, 1);
        free(cap);
        mutex_unlock(&task->cap_info->lock);
}

/** Initialize kernel object
 *
 * @param kobj  Kernel object to initialize.
 * @param type  Type of the kernel object.
 * @param raw   Raw pointer to the encapsulated object.
 * @param ops   Pointer to kernel object operations for the respective type.
 */
void kobject_initialize(kobject_t *kobj, kobject_type_t type, void *raw,
    kobject_ops_t *ops)
{
        atomic_set(&kobj->refcnt, 1);
        kobj->type = type;
        kobj->raw = raw;
        kobj->ops = ops;
}

/** Get new reference to kernel object from capability
 *
 * @param task    Task from which to get the reference.
 * @param handle  Capability handle.
 * @param type    Kernel object type of the object associated with the
 *                capability referenced by handle.
 *
 * @return Kernel object with incremented reference count on success.
 * @return NULL if there is no matching capability or kernel object.
 */
kobject_t *
kobject_get(struct task *task, cap_handle_t handle, kobject_type_t type)
{
        kobject_t *kobj = NULL;

        mutex_lock(&task->cap_info->lock);
        cap_t *cap = cap_get(task, handle, CAP_STATE_PUBLISHED);
        if (cap) {
                if (cap->kobject->type == type) {
                        kobj = cap->kobject;
                        atomic_inc(&kobj->refcnt);
                }
        }
        mutex_unlock(&task->cap_info->lock);

        return kobj;
}

/** Record new reference
 *
 * @param kobj  Kernel object from which the new reference is created.
 */
void kobject_add_ref(kobject_t *kobj)
{
        atomic_inc(&kobj->refcnt);
}

/** Drop reference to kernel object
 *
 * The encapsulated object and the kobject_t wrapper are both destroyed when the
 * last reference is dropped.
 *
 * @param kobj  Kernel object whose reference to drop.
 */
void kobject_put(kobject_t *kobj)
{
        if (atomic_postdec(&kobj->refcnt) == 1) {
                kobj->ops->destroy(kobj->raw);
                free(kobj);
        }
}

/** @}
 */