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

Hi Prashanth,

On 04/27/2015 09:45 PM, Prashanth Mundkur wrote:

Yes, this is a bit clearer. Please correct me if I'm wrong, but I gather that:

Since the server is in control over the lifetime of the RPC objects, it can destroy its RPC object (and hence invalidate the underlying capability) _at any time_ regardless of a request to close the RPC session. In normal usage, however, the capabilities (or object identities) are destroyed as a result of closing the session, at the request of the client, server parent, or any node in the component tree that was involved in the creation of the session creation.

This leads to the following question: can the server refuse to close a session?

yes, a server may ignore the session-close request. Servers that are used by clients of different security levels (e.g., the nitpicker GUI server that serves both untrusted clients and security-critical clients at the same time) must be designed and implemented with special care. Besides the correct response to session-close requests, another consideration is the adherence to the security policy as configured by the parent. The mere fact that a server is a child of its parent does not imply that the parent won't need to trust it in some respects.

In cases where is not viable to trust the server (e.g., because the server is based on ported software that is too complex for thorough evaluation), certain security properties such as the effectiveness of closing sessions could be enforced by a small (and thereby trustworthy) intermediate server that sits in-between the real server and the client. This intermediate server would then effectively wrap the server's session interface.

One minor typo I forgot to mention is

<any-service">

in three places in the system_configuration.txt chapter.

Thank you!

Cheers Norman