mkimage Reference

Name

mkimage -- make new CapROS volume

Synopsis

Description

The mkimage utility creates a new CapROS image file based on the description specified in description_file. It converts files into CapROS segments, and defines the initial contents of a set of CapROS objects.

In a system with persistent objects, there will be two description files and two image files. One describes the initial state of the non-persistent objects, and the other describes the initial state of the persistent objects.

Most of the input to mkimage comes from the description_file file, which describes the image be created. The description_file is preprocessed using the C Preprocessor (cpp); in consequence, C-style comments are supported in the input description file. Of the options listed, -I directory, -D name[=definition], and -A predicate[{value}] are simply passed to cpp. The input to cpp is a preinclude file followed by description_file. The preinclude file is located at EROS_ROOT/host/include/mkimage.preinclude if the environment variable EROS_ROOT is defined, otherwise HOME/eros/host/include/mkimage.preinclude. The mkimage utility takes its commands from the output of cpp.

The -a architecture option defines the architecture in the same way as the arch statement (see below).

The -o image option specifies the output file.

The -v option ("verbose") prints the symbol table after every statement is processed.

The -d option prints parse information for each statement.

The -nostddef option is passed to cpp. It would also disable the automatic definition of symbols by mkimage, if there were any.

The -nostdinc option disables the use of standard includes by cpp.

Statements in the description file are semicolon-terminated, and consist of directives, assignments, or diagnostics.

The balance of this page describes each statement in greater detail. mkimage grew in an ad-hoc fashion. While its facilities for capability manipulation are fairly well regularized, its commands for register manipulation and expression processing could be significantly enhanced.

Directives

A mkimage description file always begins with a declaration of the processor architecture. This tells mkimage how processes are to be formed and what the register names are for the active architecture.

arch keyword

Declares the active processor architecture. This tells mkimage how processes are to be formed and what the register names are for the active architecture. The arch declaration should be the first declaration of the file, and should appear prior to the inclusion of process image map files.

Keyword is one of:

Keyword	Architecture
i486	Intel 486 and later architectures
arm	ARMv4 and later architectures

hide name

Removes name from the symbol table. Used to minimize the number of symbols that are exported from an image map file or result from a macro expansion that required temporary names.

ipl process

Defines the IPL process. This is the only process that will be started at boot time. Only one IPL process can be defined.

run name

If name is a process key, it indicates that the process should be started by the IPL process. If name is a start key, it must be a constructor and will be called by the IPL process.

Key Expressions

Key expressions include both basic key specification and transformations on existing keys.

clone node

Returns a copy (in a new node) of node, which can be either a name or a slot. The returned key to the new node has exactly the same type, subtype, l2v, and so forth as the original.

empty GPT with number pages

Creates a GPT containing slots for number pages (but no actual pages) at consecutive addresses.

This fabrication is useful for processes that will automatically populate a memory tree but need to know that all required GPTs for the tree are preallocated -- most notably, the space bank.

new GPT with lss lss

Creates a GPT with an l2v value of (lss-1)*EROS_NODE_LGSIZE + EROS_PAGE_ADDR_BITS.

key as opaque GPT key

Returns an opaque copy of key. key must be a GPT key.

key with guard offset

Returns a copy of key with the specified guard. This sets both the l2g and guard fields of the key. key must be a GPT or page key.

key as qualifier opaque forwarder key

Returns an opaque copy of key with the specified qualifiers, which may include sendCap and/or sendWord (or neither). key must be a forwarder key.

key as qualifier node key

Returns a copy of the node key with the specified access restrictions, which may include ro and/or nc and/or weak.

key with qualifier page at offset
key with qualifier subseg segkey at offset

Inserts a new page (subsegment) with the specified access restrictions at offset within the segment tree named by key.

The qualifier may include ro and/or nc and/or weak, or may be sense which means all three restrictions.

physpage ( physaddr )
physpage ro ( physaddr )

A page key to the page at physical address physaddr, which is any arithmetic expression. The ro form produces a read-only key.

misc misckeyname
misc misckeyname value

A miscellaneous key. The valid miscellaneous key names are listed in eros/src/sys/KEYDEFS. value can be supplied if the miscellaneous key uses it.

name

Returns the key previously created by a name assignment to name

new process

Fabricates a new process according to the rules for the current architecture and returns a process key to it.

process with constituents

Adds a constituents node to a pre-existing process. The result of this expression is the process key.

new forwarder

Fabricates a new forwarder and returns a key to it.

Setting the Blocked flag is not implemented.

new node
new qualifier node

Fabricates a new node and returns a key to it. The qualifiers nc (no-call), ro (read-only), and weak (weak) may be used to restrict the authority of the returned key. Any, all, or none of these qualifiers may be used in any order.

Note, there is currently no way to set the l2v field of the node.

new page
new qualifier page

Fabricates a new page and returns a key to it. The qualifiers nc (no-call), ro (read-only), and weak (weak) may be used to restrict the authority of the returned key. Any, all, or none of these qualifiers may be used in any order.

null

The zero number key. If you are using this to convey no authority, you should switch to the void key (below).

number ( value )

A number key with the designated value. The value is a 32-bit unsigned integer.

A number key actually holds three integers. The second and third integers are zero.

number ( value1, value2, value3 )

A number key with the three designated values. The values are 32-bit unsigned integers.

number ( "string" )

A number key with three integers containing the string in little-endian form. In other words, the first character is in the low 8 bits of the first word; the second character is in the next higher 8 bits, the fifth character is in the low 8 bits of the second word, etc. Any characters beyond 12 are ignored. The string is padded with zero bytes if necessary.

program segment "filename"
program segtree "filename"
program ro segtree "filename"
program rw segtree "filename"
program data segtree "filename"

Fabricates a new memory tree containing the load image of the executable file. If the load image fits in a single page, a page key is returned and it makes no difference whether segment or segtree is used. Otherwise, if the segment form is used, an opaque GPT key is returned. Otherwise a non-opaque GPT key is returned.

The first two forms load the entire program image. If ro is specified, the memory tree will have only the read-only sections (.text, .rodata, and .eh_frame if present). If rw is specified, the memory tree will have only the read-write sections (.data and .bss). If data is specified, the memory tree will have only the initialized data section (.data).

small program "filename"

Fabricates a new memory tree containing the load image of the executable file. The returned key is a GPT key suitable for use with the small program runtime.

range ( lo_oid : hi_oid )

A range key granting authority over the range [lo_oid,hi_oid).

segtree "filename"

Fabricates a new segment tree containing the content of the named file. A non-opaque GPT key is returned.

start process keydata

Fabricates a start key to the designated process with the designated keydata value.

symbol "filename" name

Extracts the load address of the symbol name from the binary filename, and returns it as a number key suitable for assignment to a process program counter. While the most commonly used name is _start, other names can be used to provide multiple entry points into a single binary file.

threadlist

A node key designating the reserved threadlist node. This is for the IPL process. All but the last key in this node is a process key to a process to be started by the IPL process. [Or a constructor...] The last key is a node key to the next node in the list, or void if none.

void

The void key (a key conveying no authority).

volsize

A node key designating the reserved volsize node. The mkimage utility populates the volsize node with information concerning the total number of nodes and pages that are used in the image. This information is used by the spacebank at initialization time to avoid reallocating these objects.

zero segtree with number pages

Creates a segment containing number pages at consecutive addresses. Note that the newly created segment uses dedicated pages, which is not the same as using the primordial zero segment of the same size. A non-opaque GPT key is returned.

Assignments

Assignments take the form:

name = qualified_key;
slot = qualified_key;

The first form creates a new directory (symbol table) entry, and binds it to the value of qualified_key. The second traverses existing objects to find the designated slot, and replaces the current key in the slot with qualified_key.

Simple Slot Designation

In its simplest form, a slot is designated by starting from any key that designates a node and supplying slot indexes using C-style array syntax:

nodekey[5] = qualified_key

Sets the fifth slot of the node named by nodekey to key.

Array syntax can be applied recursively, as in:

nodekey[5][10] = qualified_key

Except for the last, all slots traversed in this fasion must contain keys that designate a node.

qualified_key is any key expression, optionally prepended with access restrictions, which may include ro and/or nc and/or weak, or may be sense which means all three restrictions.

Process Slot Designation

Certain slots in the process root are commonly set in image description files, and it is useful to be able to check that the assigned key is of an appropriate type. For this reason, mkimage provides a special syntax for setting such slots.

In all of the examples below, Node may be either a symbol name designating the process root node or a slot expression (as described above) designating a process root node.

Forwarder Slot Designation

GPT Slot Designation

Diagnostics

To support debugging, mkimage supports a number of diagnostic commands that can be used to print various structures.

print "your string here"

Prints the supplied string to stdout, followed by a newline. Most commonly used to provide a reminder description of the subsequent print output.

print directory

Prints the list of all currently assigned names and their associated keys (i.e. the symbol table). Note that the directory does not include names which have been hidden by a hide directive prior to the print statement.

print key

Prints the specified key. See below for a description of key syntax.

print segment segkey

Recursively prints the segment tree whose root is segkey. Segkey must be a memory key (GPT or page). For brevity, slots in the segment tree containing void keys are omitted.

print page pagekey

Prints the content of the page named by pagekey, which must be a page key.

print node key

Prints the content of the node named by key, which must designate a node or GPT.

print process key

Prints the process designated by key, which must be a process or gate key.