Changeset 6636fb19 in mainline

Timestamp:

2017-09-29T22:56:31Z (7 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

91b60499

Parents:

48bcf49

Message:

Add comments

Location:

kernel/generic

Files:

• include/cap/cap.h (modified) (3 diffs)
• src/cap/cap.c (modified) (14 diffs)

kernel/generic/include/cap/cap.h

@@ -67 +67 @@
 } kobject_ops_t;
 
+/*
+ * Everything in kobject_t except for the atomic reference count is imutable.
+ */
 typedef struct kobject {
         kobject_type_t type;
@@ -80 +83 @@
 } kobject_t;
 
+/*
+ * A cap_t may only be accessed under the protection of the cap_info_t lock.
+ */
 typedef struct cap {
         cap_state_t state;
@@ -115 +121 @@
     kobject_ops_t *);
 extern kobject_t *kobject_get(struct task *, cap_handle_t, kobject_type_t);
+extern void kobject_add_ref(kobject_t *);
 extern void kobject_put(kobject_t *);
 

kernel/generic/src/cap/cap.c

@@ -33 +33 @@
  */
 
+/*
+ * 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>
@@ -42 +81 @@
 static kobject_t *cap_unpublish_locked(task_t *, cap_handle_t, kobject_type_t);
 
+/** Initialize capability and associate it with its handle
+ *
+ * @param cap     Address of the capability.
+ * @param handle  Capability handle.
+ */
 void cap_initialize(cap_t *cap, cap_handle_t handle)
 {
@@ -49 +93 @@
 }
 
+/** Allocate the capability info structure
+ *
+ * @param task  Task for which to allocate the info structure.
+ */
 void caps_task_alloc(task_t *task)
 {
@@ -55 +103 @@
 }
 
+/** Initialize the capability info structure
+ *
+ * @param task  Task for which to initialize the info structure.
+ */
 void caps_task_init(task_t *task)
 {
@@ -66 +118 @@
 }
 
+/** Deallocate the capability info structure
+ *
+ * @param task  Task from which to deallocate the info structure.
+ */
 void caps_task_free(task_t *task)
 {
@@ -72 +128 @@
 }
 
+/** 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)
@@ -89 +156 @@
 }
 
+/** 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)
 {
@@ -100 +176 @@
 }
 
+/** 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)
 {
@@ -125 +208 @@
 }
 
+/** 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)
@@ -156 +249 @@
         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)
 {
@@ -166 +272 @@
 }
 
+/** 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)
 {
@@ -177 +288 @@
 }
 
+/** 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)
@@ -186 +304 @@
 }
 
+/** 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)
@@ -204 +332 @@
 }
 
+/** 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)
 {