Hello Prashanth,
I'm having trouble building the manual from the latest genode-manual master:
<use img/genode_labs.pdf> [150] <use img/genode_labs.pdf> [151] <use img/genode_labs.pdf> [152]
! LaTeX Error: File `spec/classes/genode/capability/description.tex' not found.
this error was introduced when I added the functional specification, which incorporates many textual snippets that are generated from the source code. Until now, I had not streamlined the extraction procedure with the normal work flow. Instead, I had to perform a number of manual steps using the Makefile in manual/spec/. Your email prompted me to fix that. The current version automatically obtains the Genode source code and extracts all the documentation snippets needed.
Btw, I updated the PDF today:
http://genode.org/files/53bcb8e33fe6602fed25edc3c7b922c5/manual-2015-04-27.p...
Being unable to build, I instead read the March 9th version of the really excellent manual, and have the following feedback:
section 3.1.4: Capability delegation through capability invocation
Is there a notion of access rights on capabilities, e.g. read/write/grant as in sel4? If not, it might be good to comment on the design choice.
There are no access rights associated with a Genode capability other than the rights to use it and to delegate it. As both rights are always there, I don't think that we should introduce the term "access right" at all. Basically, a Genode capability is an access right.
Since you are not the first one asking this question, I will have to find a way to make this point more clear in the documentation.
3.2.4: Client-server relationship
Not sure if this is the best place for it, but related to the lifetime of a session, can capabilities be revoked or deleted, and who can perform this action (child/parent/delegatee)? It would be good to have an explanation that is as clear as the one on capability creation and delegation, explaining how a capability is removed from a protection domain.
The revocation of capabilities is briefly covered at the end of Section 3.1.2. I agree that it would be useful to elaborate it a bit more in Section 3.2.4. Would the following description be of help?
The object identity of a session RPC object (and further RPC objects that may have been created using the session) is owned by the server. So the server is in control over the lifetime of those RPC objects. When the server is instructed by its parent to close a given session, the object identity of the session vanishes. Since capabilities become invalid (aka revoked) once their associated RPC object is destroyed, the revocation of capabilities is a side effect of the closing of sessions. The closing of a session can naturally be initiated by all nodes of the component tree that were involved in the session creation.
In practice, the partial revocation of authority is rare. Revocation of authority is usually performed by destroying the sub system, from which authority must be revoked.
3.4.5: Address-space management
One issue that was not referred to was handling page-faults, which I found is indeed covered in the 'Under the hood' chapter. It would be good to have a forward reference.
So far, I have not considered the fact that (and way how) page faults are handled as important for Chapter 3. For example, from the architecture's point of view, it does not matter whether page faults are handled in a lazy fashion (as for most current base platforms) or by eagerly populating page tables. It remains a peculiarity of the underlying kernel. Still, I like you idea to add a forward reference to the under-to-hood chapter.
I found the sub-section on managed dataspaces a bit unclear, especially the relationship between 'the RM client' and 'the component' in the first case, and 'client', 'RM client' and 'server' in the second case. One (or two) of your excellent diagrams would be really helpful here.
I agree.
3.6.1: Synchronous RPC
This is not clear: "Each IPC server has a corresponding untyped capability that can be used to perform calls to the server using an IPC client object." Perhaps server/client got swapped somewhere?
This is indeed a bit confusing. Does it become more clear if I reword it as follows? "For each IPC server, there exists an associated untyped capability that is created with the IPC server object. This capability and can be combined with an IPC client object to perform calls to the IPC server."
3.6.2: Asynchronous notifications
Even when the server is signalling events to a single trusted client, isn't there a possibility of deadlock that motivates the need for asynchronous notifications?
You are right that deadlocks would happen if we had circular client-server relationships. But I do not remember to have ever tried to build a notification mechanism in this way.
6.2.6: Assigning subsystems to CPUs
At the end of the section, I thought the upper-left CPU would be at position (0,8) instead of (4,0). Perhaps a diagram could help, or the existing diagram showing affinity for nested inits could be reused for this example.
Good idea. An illustration would certainly help here.
Thank you for the valuable suggestions! I will do my best to incorporate them.
Cheers Norman