genode manual

[Norman Feske]

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.pdf

> 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


-- 
Dr.-Ing. Norman Feske
Genode Labs

http://www.genode-labs.com · http://genode.org

Genode Labs GmbH · Amtsgericht Dresden · HRB 28424 · Sitz Dresden
Geschäftsführer: Dr.-Ing. Norman Feske, Christian Helmuth