Added capability types to capability man page.

README

@@ -1,5 +1,5 @@
 
-		Codezero Microkernel v0.1 Release
+		Codezero Microkernel v0.2 Release
 
 		Copyright (C) 2007-2009 Bahadir Bilgehan Balban
 

docs/man/man7/capability.7

@@ -58,13 +58,53 @@ denotes the unique ID of the one and only capability owner. This is always a thr
 .TP
 .fi
 .I type
-field contains the capability type or targeted resource type. The capability type determines the generic operations that the capability describes. For example a capability describing a system call would likely have a type name that resembles the name of that system call. See below for the list of valid capability types. The resource type denotes the type of targeted resources. In case this is a thread or a collection of threads, the type may be one of thread, address space, or container. Quantitative resources also have different types, describing the resource. Since quantitative resources such as memory pools, or memory regions are not associated with a target id, the types have no meaning for the resid field for these capabilities. See below for the full list of valid resource types.
+field contains the capability type or targeted resource type. The capability type determines the generic operations that the capability describes. For example a capability describing a system call would likely have a type name that resembles the name of that system call. See the
+.B CAPABILITY TYPES
+section below, for a list of valid capability types. The resource type denotes the type of targeted resources. In case this is a thread or a collection of threads, the type may be one of thread, address space, or container. Quantitative resources also have different types, describing the resource. Since quantitative resources such as memory pools, or memory regions are not associated with a target id, the resource types have no meaning for the resid field for these capabilities. See the CAPABILITY RESOURCE TYPES section below for the full list of valid resource types.
 
 .TP
 .fi
 .I access
 field denotes the fine-grain operations available on a particular resource. The meaning of each bitfield differs according to the type of the capability. For example, for a capability type thread_control, the bitfields may mean suspend, resume, create, delete etc. See below for the full list of capability bits.
 
+.SH CAPABILITY TYPES
+.TP
+.B CAP_TYPE_TCTRL
+.RB "Defines the capability to make the " "l4_thread_control " "system call. It is usually owned by the pager and targets the container so that the pager can issue the call on all threads in the container. "
+.TP
+.B CAP_TYPE_EXREGS
+.RB "Defines the capability to make the " "l4_exchange_registers " "system call. "
+.I rtype
+.RB "field is usually expected to target the complete container, similar to " "CAP_TYPE_TCTRL " "capabilities."
+.TP
+.B CAP_TYPE_MAP_PHYSMEM
+.RB "Defines a physical memory region. A thread who owns this capability would be always expected to use the " "l4_map " "system call, to map the physical area to its address space. As an optimisation there is no separate mapping capability defined for the " "l4_map " "system call. As a physical memory capability, it may also define fields for devices such as device types, numbers and irqs."
+.TP
+.B CAP_TYPE_MAP_VIRTMEM
+.RB "Similar to the " " CAP_TYPE_MAP_PHYSMEM " "capability, it defines a virtual memory range that can be mapped using the " "l4_map " "system call."
+
+.TP
+.B CAP_TYPE_IPC
+.RB "This is the most fundamentally used capability in the system. " "CAP_TYPE_IPC " "defines the ability to make ipc calls to threads in the system. By its "
+.I rtype
+.RB " field, it may be defined such that it enables inter-container ipc, i.e. the ability to send messages to a thread or all threads in another container. Ipc operations always have a valid target if it is a " " send " "operation. By this fact, ipc capability checks are done only during the send phase."
+.TP
+.B CAP_TYPE_IRQCTRL
+.RB "Defines a thread's privilege to set up and handle irqs. A separate " "CAP_TYPE_MAP_PHYSMEM " "capability would also be necessary on each individual device, to gain access to its irqs."
+.TP
+.B CAP_TYPE_UMUTEX
+.RB "Defines a thread's privilege to use kernel-supported userspace mutexes. A thread who has access to a " "mutexpool " "would have to have this capability to use it. In future versions, this capability may be removed, assuming the " "mutexpool " "capability is in itself sufficient for having access to mutexes."
+.TP
+.B CAP_TYPE_QUANTITY
+.RB "There are various typed, fixed-size memory pools that have this capability type. Fixed-size memory pools such as " "mappool" ", " "cappool" ", " "threadpool" ", and similar capabilities are some of the examples. A quantitative capability has no valid target resource id type, because they are themselves resources to be consumed by their owner. Since they already have a unique capability ID, the target resource id does not provide any better identification. As a result normally the
+.I resid
+.RB "field is set to " "CAP_RESID_NONE" " on quantitative capabilities."
+
+Quantitative capabilities have been introduced for allocation of structures that are fundamentally and minimally needed in the system. Any further abstraction of memory resources would make the design too generic, requiring much effort from userspace. The choice of which mechanisms need to be kept inside and out of the kernel is a subtle one. In this particular case, it was decided that a minimal set of typed resources would be always useful to keep in the kernel.
+
+.TP
+.B CAP_TYPE_CAP
+.RB "Defines the capability to manipulate existing capabilities. Any thread who attempts to share, grant, modify, or replicate its capabilities must make a call to the " "l4_capability_control " "system call. This capability defines the operations available making this call. A caller must own this capability, and also own all other capabilities that are going to be modified."
 
 .SH SEE ALSO
 .BR "l4_capability_control"(7)