mkimage Reference

Name

mkimage -- make new EROS volume

Synopsis

Description

The mkimage utility creates a new EROS image file based on the description specified in description_file.

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, only the -v, -d, -nostddef, and -o options are processed by mkimage. All other options are passed unmodified to cpp, and description_file is passed as input to cpp. The mkimage utility takes its commands from the output of cpp.

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.

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 domain image map files.

Keyword is one of:

Keyword	Architecture
i486	Intel 486 and later architectures

Other architectures are planned, and will be added to this list as they are implemented.

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.

run name

Indicates that name, which must be a domain or start key, should be an initially running domain.

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, lss, and so forth as the original.

empty segment with number pages
empty segtree with number pages

Creates a segment containing slots for number pages (but no actual pages) at consecutive addresses. If the segment form is used a segment key is returned. Otherwise a node key is returned.

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

key as qualifier segment key
key as qualifier node key

Returns a copy of key with the specified type and access restrictions.

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.

key with blss blss

Returns a copy of key with the specified blss.

misc name

name

Returns the key previously created by a name assignment to name

A miscellaneous key. The valid miscellaneous key names are listed in eros/src/base/sys/disk/MiscKey.def.

new process

Fabricates a new procss according to the rules for the current architecture and returns a 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 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.

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"
small program "filename"

Fabricates a new segment tree containing the load image of the executable file. If the segment form is used a segment key is returned. Otherwise a node key is returned. If the small variant is used, the returned key is a node 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).

wrapper with blss blss

Fabricates a new wrapper with the given blss.

segment "filename"
segtree "filename"

Fabricates a new segment tree containing the content of the named file. If the segment form is used a segment key is returned. Otherwise a node key is returned.

start domain keydata

Fabricates a start key to the designated domain 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 domain 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.

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 segment with number pages
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.

If the segment form is used a segment key is returned. Otherwise a node 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] = key

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

Array syntax can be applied recursively, as in:

nodekey[5][10] = key

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

Domain Slot Designation

Certain slots in the domain 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 domain root node or a slot expression (as described above) designating a domain root node.

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 (node, segment, or page). For brevity, slots in the segment tree containing zero number keys are elided from the output.

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. Segment, process, and gate keys are deemed to designate a node.

print domain key

Prints the domain rooted at key, which must designate a node. Segment, process, and gate keys are deemed to designate a node.

Note that this command makes no attempt to verify that key names a domain. Using print domain on other structures may generate confusing output.