mketfs

Syntax:

Runs on:

Linux, Microsoft Windows

Options:

-D

Treat undeclared intermediate directories as errors.
If there's a target filesystem entry of /x/y, and /x has never
occurred explicitly in the buildfile,
the input directory, or as a child of a
recursively included directory, then /x is considered an undeclared intermediate directory.

-d

Display warnings for undeclared intermediate directories.

-linputline

("el") Process inputline before interpretation of
the buildfile begins.
Input lines given to mketfs should be quoted to prevent interpretation by the shell (as
mketfs input lines often contain spaces).
Multiple -l options are processed in the order specified.
No default.

-n[n...]

Don't use timestamps in the files.
Using the -n option permits identical images in binary format.
Specifying additional -n options strips all time information from files.

Description:

The mketfs utility reads a text buildfile describing an
embedded transaction filesystem (ETFS) and produces a binary image file containing the
ETFS as a sequence of transactions.
You can copy this file to flash at a later stage, using
etfsctl.

Note:
Don't confuse this command with
mkifs,
which builds an OS image filesystem, or
mkefs,
which builds an embedded filesystem.

You specify the input and output on the command line:

buildfile

The filename of the buildfile that describes the contents of the embedded filesystem;
use "-" to specify standard input (the default).

directory

The root of a directory hierarchy to be appended to the file list
specified in buildfile (if any).
The default is no directory.

outputfile

The filename of the image file containing the ETFS;
use "-" to specify standard output (the default).
Note that you can specify the outputfile only if you
specified a buildfile.

If you don't specify either a buildfile or a directory, a buildfile is expected
as input from standard input.
The output is always an image file; if you don't specify outputfile,
image-file data will be produced on standard output.

The mketfs utility generates a list of clusters, which are sized
to match the hardware (1024, 2048, or 4096 bytes).
Each cluster has a header of type struct etfs_trans, which is a fixed 16 bytes.
So the actual size of the image file is the size of the input data (rounded
up to a multiple of the cluster size) plus 16 bytes times the number of clusters.
When
etfsctl
writes to the filesystem, it removes the etfs_trans structure.
As the devio layer is putting the cluster
into hardware, it generates a new, BSP-specific structure to hold the
same information as was in the etfs_trans.

Buildfiles

The buildfile uses the same grammar as the mkifs command,
but supports different attributes.

The buildfile is basically just a list of files that you want to be included in the ETFS image file when it's
built by mketfs. As well as the files to be included, you can
specify various attributes that are used to set parameters of the filesystem and the files in it.
For example, you can specify the maximum size of the filesystem, or the user and group IDs of the individual files.

Note:
You can't use a backslash (\) to break long lines into smaller pieces.

In a buildfile, a pound sign (#) indicates a comment; anything
between it and the end of the line is ignored.
There must be a space between a buildfile command and the pound sign.

Each line is in the form:

[attributes] file_specification

where the attributes (with the enclosing square brackets) and the
file specification are both optional.

You can use an attribute:

on the same line as a filename, in which case the attribute modifies only that file.
In this example, the attribute modifies only file A:

[attribute] A
B
C

on a line by itself, in which case the attribute modifies all subsequent files.
In this example, the attribute modifies files A, B, and
C:

[attribute]
A
B
C

Attributes provide information about the file following the attribute.
They're enclosed in square brackets;
when combining attributes (e.g., to specify both the user ID
and the group ID), enclose both attribute tokens
in the same pair of square brackets.
For example:

Those ending with an equals sign ("=") followed by a value.
Don't put any spaces around the equals sign.

A question mark (?) before an attribute makes the setting
conditional. The attribute is set only if it hasn't already been set.
For example, ?+bigendian sets the +bigendian attribute
only if +bigendian or -bigendian hasn't already been set.

The file_specification takes one of the following forms:

path

The file is copied from the host to the location in the image defined by the
prefix
attribute.
If path isn't absolute, mketfs looks for it in the locations identified by the
search
attribute.

target_path=host_path

The specified file or contents of the specified directory are fetched from
the host filesystem and placed into the image.

target_path={contents}

An inline definition.
The contents of the file are listed within the buildfile itself,
enclosed in braces ({ }); the file doesn't exist on the host system anywhere.
The contents of the inline file can't be on the same line as the opening or closing brace.

Note:
The mketfs utility doesn't parse the contents of an inline file for
anything but the closing brace.
For example, mketfs doesn't interpret
a pound sign (#) in an inline file as the beginning of a comment.
The syntax of the inline file depends on what it's used for on the target system.

Closing braces (}) and backslashes (\) in an
inline file must be escaped with a backslash.

You can enclose a filename in double quotes ("") if it
includes spaces or unusual characters.

Note:
You should explicitly specify the cluster_size,
block_size and num_blocks attributes as appropriate
for your flash device to ensure that the image produced is fully compatible with your specific device.

Note:
An OR-bar indicates that either the first
element or the second element must be present, but not both (e.g.
+|-bigendian means either +bigendian
or -bigendian, but not +-bigendian).

bigendian attribute (boolean)

+|-bigendian

Set the byte order for the embedded filesystem to either
big (via +bigendian) or little (via -bigendian)
endian. The default is little endian.

block_size attribute

block_size=bsize

Set the block size for the ETFS.
The block size depends on what memory device you have in your target hardware.
The default block size is 16 KB.

cd attribute

cd=filename

Set the current working directory to the specified pathname before attempting to open the host file.
Default is the directory from which mketfs was invoked.

cluster_size attribute

cluster_size=csize

Set the cluster size for the ETFS. The cluster size depends
on what memory device you have in your target hardware. The default cluster size is 1 KB.

dperms attribute

dperms=dperms_spec

Set the access permissions of the directory.
If specified as a number, the permissions are set to that
number (just like the chmod command).
If specified as an asterisk (*), the
host directory's permissions are used; for an inline directory, the permissions are
obtained from the umask of the user running mketfs.
Otherwise, a symbolic mode string (which is a subset of chmod's)
is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a

one of -, =, or +

a combination of r, w, x,
s, g, and t

You can include more than one symbolic mode string, separating them with a comma (,).

The default dperms_spec is *.

Note:
When running on a Windows host, mketfs might guess at the permissions, so you should
use the dperms attribute to specify them explicitly.
You might also have to use the uid and gid attributes to set the
ownership correctly.

filter attribute

filter=filter_spec

Run the host file through the filter program specified, presenting the host
file data as standard input to the program and using the standard output from
the program as the data to be placed into the embedded filesystem.
Default is no filter.

You can specify a filter_spec of none.
This is useful if you need to override a global filter specification.

followlink attribute (boolean)

[+|-followlink]target_path=host_path

If you specify +followlink or omit it, then whenever an item x is taken
from the host filesystem and x is a symbolic link, mketfs
resolves the symbolic link and includes its target file or directory.

If you specify -followlink, then:

If the symbolic link is named explicitly in the buildfile and is a link to a directory,
mketfs follows the link and recurses into the directory.

Otherwise mketfs includes the symbolic link itself in the image filesystem.
It's up to you to include in the image whatever the link points to.

gid attribute

gid=id_spec

Set the group ID number for the file.
The value of this attribute may be either a number or an asterisk
(*). If it's an asterisk, the group ID is taken from the host file;
for an inline file, the group ID is the group of the user running mketfs.
The default value for this attribute is *.

mountperms attribute

mountperms=perms_spec

Set the access permissions for mountpoints.
If specified as a number, the permissions are set to that
number (just like the chmod command).
Otherwise, a symbolic mode string (which is a subset of chmod's)
is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a

one of -, =, or +

a combination of r, w, x,
s, g, and t

You can include more than one symbolic mode string, separating them with a comma (,).

The default perms_spec is "0775".

mtime attribute

mtime=time_spec

Set the timestamps of the files or directories to the specified time.
The time_spec must be either:

a single asterisk (*), meaning that the host file's timestamp should be used (the default behavior)

or:

in a format based on ISO8601:

YYYY-MM-DD-HH:MM:SS

You must provide all six elements.
The time is always interpreted as UTC.

Timestamps specified with the mtime attribute aren't affected by the -n option.

num_blocks attribute

num_blocks=num_blocks[,num_pad]

You must use this attribute to specify the number of blocks in the flash device (num_blocks).
You can also use it to specify the minimum number of blocks in the image file (num_pad).
If you specify num_pad, then the image file is padded out to that number of blocks;
otherwise the image file is padded to num_blocks blocks.

To keep the image as small as possible (for faster programming of the
NAND part), set num_blocks to the appropriate number and set num_pad to 0.
Doing this will correctly set the size of the .counts file
(an array of the blocks showing the read and erase counts), so that wear-leveling will be done.

optional attribute (boolean)

+|-optional

If true, and the host file can't be found, output a warning and
continue building the embedded filesystem.
If false, and the host file can't be found, output an error
message and exit mketfs.
The default is true.

perms attribute

perms=perms_spec

Set the access permissions of the file.
If specified as a number, the permissions are set to that number (just like the chmod command).
If specified as an asterisk ("*"), the host file's permissions are used; for an inline file,
permissions of 0666 are used.
Otherwise, a symbolic mode string (which is a subset of chmod's)
is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a

one of -, =, or +

a combination of r, w, x,
s, g, and t

You can include more than one symbolic mode string, separating them with a comma (,).

The default perms_spec is *.

Note:
When running on a Windows host, mketfs can't get the
setuid ("set user ID") or setgid ("set group ID") permissions from the file, and
it might guess at the read, write, and execute permissions, so you should
use the perms attribute to specify the permissions explicitly.
You might also have to use the
uid
and
gid
attributes to set the ownership correctly.
To determine whether or not a utility needs to have the setuid or setgid
permission set, see its entry in the Utilities Reference.

prefix attribute

prefix=prefix_spec

Set the prefix on the target file names.
The default is the empty string.

search attribute

search=path:path:…

This attribute specifies that mketfs should search for the file
in the named locations on the host system.
The search directory portion of the host file name isn't included in the name that's stored in the ETFS.

Note:
Colon separators and forward slashes in the paths are the standard Unix
conventions, but for Windows searches, you must use the standard Windows
conventions, such as semicolon separators and backslashes in the paths.

type attribute

type=file_type

Sets the type of the files being created in the ETFS.
Allowable types are:

link — a symbolic link

file — a regular, everyday file (the default)

dir — a directory

Note:
Specifying [type=dir] tells mketfs to make the named file
a directory; you don't need to specify the type when you're copying the
contents of a directory.
For example, this command:

[type=dir]/usr/bin=/usr/nto/x86/bin

creates an empty directory named /usr/bin, with the same owner and permissions
as for the host directory.
To recursively copy /usr/nto/x86/bin to /usr/bin, you
just need to specify:

/usr/bin=/usr/nto/x86/bin

uid attribute

uid=id_spec

Set the user ID number for the file.
The value of this attribute may be either a number or an asterisk
(*). If it's an asterisk, the user ID is taken from the host file;
for an inline file, the user ID is the user running mketfs.
The default value for this attribute is *.

Patch files

Patch files let you override the user ID, group ID, and permissions of certain files,
depending on their location and filename pattern. Patches are applied after
all files have been collected (from the buildfile and/or the specified
directory). Consequently, patch files can override settings specified in
the buildfile.

Patch files must contain only lines of the form:

#comment

or:

type:path:pattern:uid:gid:perms

In comment lines, # must be the very first character.
The entire line is regarded as a comment and is ignored.

The type is either d or f, optionally followed by r.
Type d patches are applied only to directories, and type f patches are applied only to files.
An r indicates that the patch should be applied recursively within path;
without r, the patch is applied to path only.

The pattern is a filename pattern that specifies which files to apply the patch to.
The uid and gid must be decimal numbers, while perms must be
an octal number (see
chmod).
Note that it isn't possible to set only the user ID, group ID, or permissions;
for each match, all three are affected.

Examples:

In this example, we've specified a cluster_size of 1 KB, a
block_size of 64 KB and a total device size of 240 blocks
(which is the default configuration of fs-etfs-ram).
The files and subdirectories from the /home/jgarvey/nto_flash directory on the host
system are to be recursively copied into the root directory of the ETFS.

To create an ETFS image file using the above buildfile, invoke mketfs as follows:

mketfs my_etfs.bld my_image.etfs

This creates the my_image.etfs file containing the ETFS filesystem, which can then
be copied to the target sstem as follows: