Specifying a Protocol Graph

A new instance of the x-kernel is configured by specifying the collection of protocols that are to be included in the kernel in a file called graph.comp. Example graph.comp files can be found in xkernel/build/Template.

The graph.comp file is divided into three sections: device drivers, protocols, and miscellaneous configuration parameters. The sections are separated by lines beginning with @; and each section may be empty.

The first two sections, device drivers and protocols, describe the protocol graph to be configured into your kernel. The only difference between the two sections is that drivers in the first section are initialized directly from the x-kernel boot thread, whereas protocols in the protocol section are initialized from a distinct protocol initialization thread. For the device drivers and platforms in this distribution, this distinction is of no consequence and device drivers may be configured in either the first or the second section.

Device drivers and protocols are described by the same types of entries, as in the example:

name=yap files=yap,yap_clnt,yap_srvr dir=yap protocols=ip,eth trace=TR_MAJOR_EVENTS;

The protocols field indicates the protocols below the current protocol in the graph. When this field contains multiple protocols, order is significant (the lower protocols will be loaded into the upper protocol's down vector in the order in which they are listed.) A protocol which expects multiple protocols below it will describe the expected semantics of the lower protocols in its manual page in appendix A.

The trace field defines the debugging level used in trace statements depending on the protocol variable traceyapp. See section 8 for the symbolic names associated with trace levels.

Multiple instantiations of protocols are supported by using a ``/'' character after the protocol name to add an extension. In the following example, two instantiations of ``yap'' are indicated, one over ``ip'' and one over ``eth,'' and both are used by the ``prt'' protocol. In this example, the instance suffixes for the ``yap'' protocol are the names of the protocol below the instance, but this is just a convention - they could have any distinct string as an instance suffix.

name=yap/ip files=yap,yap_clnt,yap_srvr dir=yap protocols=ip trace=TR_MAJOR_EVENTS;
name=yap/eth protocols=eth;
name=prt files=prt dir=prt protocols=yap/ip,yap/eth trace=TR_ERRORS;

Only the first of multiple instantiations should have dir, files, or trace fields.

The third section of graph.comp contains the names of files with protocol number tables that are to be loaded during initialization. It also contains the names of subsystems and their configuration parameters. Currently trace variables are the only parameters that can be set here. The following illustrates a typical use of the third section:

@;
#
# You can also specify protocol tables to be read in at boot time.
#
prottbl=/usr/xkernel/etc/prottbl;
prottbl=./prottbl.local;
#
#subsystem tracing for messages and protocol operations
#see the include file xk_debug.h for a list of subsystem trace variables
#
name=msg        trace=TR_GROSS_EVENTS;
name=protocol   trace=TR_MAJOR_EVENTS;
#
# You can specify the name of the romfile to be used; 
# the data will be read during "make compose" and incorporated
# into the xkernel runtime image
#
romfile=romfile.yap;
#
# You can specify romfile contents (see section "ROM options")
#
romopt shepherd threads 8;

The graph.comp file is read by an x-kernel utility program called compose which generates startup code to build the protocol graph and set up the described configuration. The protocol graph is built bottom-up; when a protocol's initialization function is called, the lower level-protocols have already been initialized.