title: smokeping_examples(5)

summary: Examples of Smokeping configuration

text:
# smokeping_examples(5)

## NAME
smokeping_examples - Examples of Smokeping configuration

## OVERVIEW
This document provides some examples of Smokeping configuration files. All the examples can be found in the "examples" directory in the Smokeping documentation. Note that the DNS names in the examples are non-functional.

Details of the syntax and all the variables are found in smokeping_config and in the documentation of the corresponding probe, if applicable.

This manual is automatically generated from the Smokeping source code, specifically the Smokeping::Examples module.

## DESCRIPTION
Currently the examples differ only in the "Probes" and "Targets" sections. The other sections are taken from the "etc/config.dist" configuration template in the Smokeping distribution so that the example files are complete.

If you would like to provide more examples, document the other sections or enhance the existing examples, please do so, preferably by sending the proposed changes to the smokeping-users mailing list.

### Example 1: config.simple
Probe configuration

```
 *** Probes ***
 +FPing
 binary = /usr/bin/fping

```

Probe explanation

Here we have just one probe, fping, pinging four hosts. The fping probe is using the default parameters, some of them supplied from the Database section ("step" and "pings"), and some of them by the probe module.

Target configuration

```
 *** Targets ***
 probe = FPing

 menu = Top
 title = Network Latency Grapher
 remark = Welcome to this SmokePing website.

 + mysite1
 menu = Site 1
 title = Hosts in Site 1

 ++ myhost1
 host = myhost1.mysite1.example
 ++ myhost2
 host = myhost2.mysite1.example

 + mysite2
 menu = Site 2
 title = Hosts in Site 2

 ++ myhost3
 host = myhost3.mysite2.example
 ++ myhost4
 host = myhost4.mysite2.example

```

Target explanation

The hosts are located in two sites of two hosts each, and the configuration has been divided to site sections ('+') and host subsections ('++') accordingly.

### Example 2: config.multiple-probes
Probe configuration

```
 *** Probes ***
 + FPing
 binary = /usr/bin/fping
 packetsize = 1000

 + DNS
 binary = /usr/bin/dig
 lookup = name.example
 pings = 5
 step = 180

 + EchoPingHttp
 pings = 5
 url = /test-url

```

Probe explanation

Here we have three probes: FPing for the regular ICMP pings, DNS for name server latency measurement and EchoPingHttp for web servers. The FPing probe runs with the default parameters, except that the ICMP packet size is 1000 bytes instead of the default 56 bytes.

The DNS and EchoPingHttp probes have been configured to be a bit more gentle with the servers, as they only do 5 queries (pings) instead of the default 20 (or whatever is specified in the Database section). However, DNS queries are made more often: 5 queries every 3 minutes instead of every 5 minutes.

Target configuration

```
 *** Targets ***
 probe = FPing
 menu = Top
 title = Network Latency Grapher
 remark = Welcome to this SmokePing website.

 + network
 menu = Net latency
 title = Network latency (ICMP pings)

 ++ myhost1
 host = myhost1.example
 ++ myhost2
 host = myhost2.example

 + services
 menu = Service latency
 title = Service latency (DNS, HTTP)

 ++ DNS
 probe = DNS
 menu = DNS latency
 title = Service latency (DNS)

 +++ dns1
 host = dns1.example

 +++ dns2
 host = dns2.example

 ++ HTTP
 menu = HTTP latency
 title = Service latency (HTTP)

 +++ www1
 host = www1.example

 +++ www2
 host = www2.example

```

Target explanation

The target tree has been divided by the probe used. This does not have to be the case: every target (sub)section can use a different probe, and the same probe can be used in different parts of the config tree.

### Example 3: config.fping-instances
Probe configuration

```
 *** Probes ***
 + FPing
 binary = /usr/bin/fping

 ++ FPingNormal
 offset = 0%

 ++ FPingLarge
 packetsize = 5000
 offset = 50%

```

Probe explanation

This example demonstrates the concept of probe instances. The FPingLarge and FPingNormal probes are independent of each other, they just use the same module, FPing. FPingNormal uses the default parameters, and so does FPingLarge except for the 5 kilobyte packetsize. Both use the same fping binary, and its path is configured FPing top section. The 'offset' parameters make sure the probes don't run at the same time - FPingNormal is run every 'full' 5 minutes (eg. 8:00, 8:05, 8:10 and so on, in wallclock time) while FPingLarge is run halfway through these intervals (eg. 8:02:30, 8:07:30 etc.)

The top FPing section does not define a probe in itself because it has subsections. If we really wanted to have one probe named "FPing", we could do so by making a subsection by that name.

Target configuration

```
 *** Targets ***
 probe = FPingNormal
 menu = Top
 title = Network Latency Grapher
 remark = Welcome to this SmokePing website.

 + network
 menu = Net latency
 title = Network latency (ICMP pings)

 ++ myhost1
 menu = myhost1
 title = ICMP latency for myhost1

 +++ normal
 title = Normal packetsize (56 bytes)
 probe = FPingNormal
 host = myhost1.example

 +++ large
 title = Large packetsize (5000 bytes)
 probe = FPingLarge
 host = myhost1.example

 ++ myhost2
 menu = myhost2
 title = ICMP latency for myhost2

 +++ normal
 title = Normal packetsize (56 bytes)
 probe = FPingNormal
 host = myhost2.example

 +++ large
 title = Large packetsize (5000 bytes)
 probe = FPingLarge
 host = myhost2.example

```

Target explanation

The target section shows two host, myhost1.example and myhost2.example, being pinged with two differently sized ICMP packets. This time the tree is divided by the target host rather than the probe.

### Example 4: config.targetvars-with-Curl
Probe configuration

```
 *** Probes ***
 + Curl
 # probe-specific variables
 binary = /usr/bin/curl
 step = 60

 # a default for this target-specific variable
 urlformat = http://%host%/

```

Probe explanation

This example explains the difference between probe- and target-specific variables. We use the Curl probe for this. Every probe supports at least some probe-specific variables. The values of these variables are common to all the targets of the probe, and they can only be configured in the Probes section. In this case, the probe-specific variables are "binary" and "step".

Target-specific variables are supported by most probes, the most notable exception being the FPing probe and its derivatives. Target-specific variables can have different values for different targets. They can be configured in both Probes and Targets sections. The values assigned in the Probes section function become default values that can be overridden in the Targets section.

The documentation of each probe states which of its variables are probe-specific and which are target-specific.

In this case the "urlformat" variable is a target-specific one. It is also quite uncommon, because it can contain a placeholder for the "host" variable in the Targets section. This is not a general feature, its usage is only limited to the "urlformat" variable and the "%host%" escape.

(The reason why the FPing probe does not support target-specific variables is simply the fact that the fping program measures all its targets in one go, so they all have the same parameters. The other probes ping their targets one at a time.)

Target configuration

```
 *** Targets ***
 probe = Curl
 menu = Top
 title = Network Latency Grapher
 remark = Welcome to this SmokePing website.

 + HTTP
 menu = http
 title = HTTP latency

 ++ myhost1
 menu = myhost1
 title = HTTP latency for myhost1
 host = myhost1.example

 ++ myhost2
 menu = myhost2
 title = HTTP latency for myhost2
 host = myhost2.example

 ++ myhost3
 menu = myhost3
 title = HTTP latency for myhost3 (port 8080!)
 host = myhost3.example
 urlformat = http://%host%:8080/

 + FTP
 menu = ftp
 title = FTP latency
 urlformat = ftp://%host%/

 ++ myhost1
 menu = myhost1
 title = FTP latency for myhost1
 host = myhost1.example

 ++ myhost2
 menu = myhost2
 title = FTP latency for myhost2
 host = myhost2.example

```

Target explanation

The target tree is divided into an HTTP branch and an FTP one. The servers "myhost1.example" and "myhost2.example" are probed in both. The third server, "myhost3.example", only has an HTTP server, and it's in a non-standard port (8080). The "urlformat" variable is specified for the whole FTP branch as "ftp://%host%/". For the HTTP branch, the default from the Probes section is used, except for myhost3, which overrides it to tag the port number into the URL.

The myhost3 assignment could just as well have included the hostname verbatim (ie. urlformat = http://myhost3.example:8080/) instead of using the %host% placeholder, but the host variable would still have been required (even though it wouldn't have been used for anything).

### Example 5: config.echoping
Probe configuration

```
 *** Probes ***
 + FPing
 binary = /usr/bin/fping

 # these expect to find echoping in /usr/bin
 # if not, you'll have to specify the location separately for each probe
 # + EchoPing         # uses TCP or UDP echo (port 7)
 # + EchoPingDiscard  # uses TCP or UDP discard (port 9)
 # + EchoPingChargen  # uses TCP chargen (port 19)
 + EchoPingSmtp       # SMTP (25/tcp) for mail servers
 + EchoPingHttps      # HTTPS (443/tcp) for web servers
 + EchoPingHttp       # HTTP (80/tcp) for web servers and caches
 + EchoPingIcp        # ICP (3130/udp) for caches
 # these need at least echoping 6 with the corresponding plugins
 + EchoPingDNS        # DNS (53/udp or tcp) servers
 + EchoPingLDAP       # LDAP (389/tcp) servers
 + EchoPingWhois      # Whois (43/tcp) servers

```

Probe explanation

This example shows most of the echoping-derived probes in action.

Target configuration

```
 *** Targets ***
 # default probe
 probe = FPing

 menu = Top
 title = Network Latency Grapher
 remark = Welcome to this SmokePing website.

 + MyServers

 menu = My Servers
 title = My Servers

 ++ www-server
 menu = www-server
 title = Web Server (www-server) / ICMP
 # probe = FPing propagated from top
 host = www-server.example

 +++ http
 menu = http
 title = Web Server (www-server) / HTTP
 probe = EchoPingHttp
 host = www-server.example
 # default url is /

 +++ https
 menu = https
 title = Web Server (www-server) / HTTPS
 probe = EchoPingHttps
 host = www-server.example

 ++ cache
 menu = www-cache
 title = Web Cache (www-cache) / ICMP
 host = www-cache.example

 +++ http
 menu = http
 title = www-cache / HTTP
 probe = EchoPingHttp
 host = www-cache.example
 port = 8080 # use the squid port
 url = http://www.somehost.example/

 +++ icp
 menu = icp
 title = www-cache / ICP
 probe = EchoPingIcp
 host = www-cache.example
 url = http://www.somehost.example/

 ++ mail
 menu = mail-server
 title = Mail Server (mail-server) / ICMP
 host = mail-server.example

 +++ smtp
 menu = mail-server / SMTP
 title = Mail Server (mail-server) / SMTP
 probe = EchoPingSmtp
 host = mail-server.example

 ++ ldap-server
 menu = ldap-server
 title = ldap-server / ICMP
 host = ldap-server.example

 +++ ldap
 menu = ldap-server / LDAP
 title = LDAP Server (ldap-server) / LDAP
 probe = EchoPingLDAP
 ldap_request = (objectclass=*)
 host = ldap-server.example

 ++ name-server
 menu = name-server
 title = name-server / ICMP
 host = name-server.example

 +++ DNS
 menu = name-server / DNS
 title = DNS Server (name-server) / DNS
 probe = EchoPingDNS
 dns_request = name.example
 host = name-server.example

 ++ whois-server
 menu = whois-server
 title = whois-server / ICMP
 host = whois-server.example

 +++ Whois
 menu = whois-server / Whois
 title = Whois Server (whois-server) / Whois
 probe = EchoPingWhois
 whois_request = domain.example
 host = whois-server.example

```

Target explanation

All the servers are pinged both with ICMP (the FPing probe) and their respective echoping probe. The proxy server, www-cache, is probed with both HTTP requests and ICP requests for the same URL.

### Example 6: config.template
Probe configuration

```
 *** Probes ***

 + FPing

 binary = /usr/sbin/fping

 *** Slaves ***
 secrets=/usr/etc/smokeping_secrets.dist
 +boomer
 display_name=boomer
 color=0000ff

 +slave2
 display_name=another
 color=00ff00

```

Probe explanation

This is the template configuration file distributed with Smokeping. It is included in the examples as well for the sake of completeness.

Target configuration

```
 *** Targets ***

 probe = FPing

 menu = Top
 title = Network Latency Grapher
 remark = Welcome to the SmokePing website of xxx Company. \
          Here you will learn all about the latency of our network.

 + Test
 menu= Targets
 #parents = owner:/Test/James location:/

 ++ James

 menu = James
 title =James
 alerts = someloss
 slaves = boomer slave2
 host = james.address

 ++ MultiHost

 menu = Multihost
 title = James and James as seen from Boomer
 host = /Test/James /Test/James~boomer

```

Target explanation

This is the template configuration file distributed with Smokeping. It is included in the examples as well for the sake of completeness.

## COPYRIGHT
Copyright 2005 by Niko Tyni.

## LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

## AUTHOR
Niko Tyni <ntyni@iki.fi>

## SEE ALSO
The other Smokeping documents, especially smokeping_config.

branch: sisyphus


snapper-configs

package: snapper

title: snapper-configs(5)

summary: Configuration files for snapper configs

text:
# snapper-configs(5)

## NAME
snapper-configs - Configuration files for snapper configs

## DESCRIPTION
Each file /etc/snapper/configs/* describes a snapper config.

## VARIABLES
The following is a list of variables that can be present in the configuration file. Boolean values must be "yes" or "no".

SUBVOLUME=path

Path of the subvolume or mount point. There is no default value. The value must always be specified.

FSTYPE=value

Filesystem type for the subvolume. Default value is "btrfs" but it's recommended to always specify the filesystem type.

QGROUP=qgroup

The btrfs quota group used for space aware cleanup algorithms. Only supported for btrfs.

SPACE_LIMIT=float or size

Threshold for the maximum space snapshots should use on the filesystem. When snapshots exceed this limit (either as a fraction of the whole filesystem or an absolute value), snapper will remove older snapshots during cleanup operations. An absolute value must use the C locale. Only supported for btrfs.

Default value is "0.5" (50% of the filesystem).

New in version 0.3.0, absolute value new in version 0.9.0.

FREE_LIMIT=float or size

Threshold for the minimum free space that should remain on the filesystem. When free space falls below this limit (either as a fraction of the whole filesystem or an absolute value), snapper will remove older snapshots during cleanup operations to reclaim space. An absolute value must use the C locale. Only supported for btrfs.

Default value is "0.2" (20% of the filesystem).

New in version 0.8.0, absolute value new in version 0.9.0.

ALLOW_USERS=users

List of users allowed to operate with the config. The user-names must be separated by spaces. Spaces in usernames can be escaped with a "\". Also see the PERMISSIONS section in snapper(8).

Using network users should be avoided since it can break most commands including rollback when the network does not work.

Default value is "" but "root" is always implicitly included.

ALLOW_GROUPS=groups

List of groups allowed to operate with the config. The group-names must be separated by spaces. Spaces in group-names can be escaped with a "\". Also see the PERMISSIONS section in snapper(8).

Using network groups should be avoided since it can break most commands including rollback when the network does not work.

Default value is "".

SYNC_ACL=boolean

Defines whether snapper will sync the users and groups from ALLOW_USERS and ALLOW_GROUPS to the ACL of the .snapshots directory. Also see the PERMISSIONS section in snapper(8).

Default value is "no".

New in version 0.2.0.

BACKGROUND_COMPARISON=boolean

Defines whether pre and post snapshots should be compared in the background after creation. Default value is "yes".

COMPRESSION=algorithm

Defines the compression algorithm used for saving file list. Allowed values are "none" and "gzip". Depending on the installed libraries, some compression algorithms might not be available. Default value is "gzip".

New in version 0.10.1.

NUMBER_CLEANUP=boolean

Defines whether the number cleanup algorithm should be run for the config. Default value is "no".

NUMBER_MIN_AGE=seconds

Minimal age for snapshots to be deleted by the number cleanup algorithm. Default value is "3600".

NUMBER_LIMIT=number or range

Defines how many snapshots the number cleanup algorithm should keep. The youngest snapshots will be kept. Default value is "50".

NUMBER_LIMIT_IMPORTANT=number or range

Defines how many important snapshots the number cleanup algorithm should keep. Important snapshots have important=yes in the userdata. The youngest important snapshots will be kept. The number of normal and important snapshots are counted independently.

Default value is "10".

New in version 0.1.8.

TIMELINE_CREATE=boolean

Defines whether hourly snapshots should be created. Together with the timeline cleanup algorithm this will create a collection of snapshots with more snapshots in the recent past and fewer snapshots in the far past.

Default value is "no".

TIMELINE_CLEANUP=boolean

Defines whether the timeline cleanup algorithm should be run for the config. Default value is "no".

TIMELINE_MIN_AGE=seconds

Minimal age for snapshots to be deleted by the timeline cleanup algorithm. Default value is "3600".

TIMELINE_LIMIT_HOURLY=number or range

Defines how many hourly snapshots the timeline cleanup algorithm should keep. An hourly snapshot is the first snapshot in an hour. The youngest hourly snapshots will be kept. Default value is "10".

TIMELINE_LIMIT_DAILY=number or range

Defines how many daily snapshots the timeline cleanup algorithm should keep. A daily snapshot is the first snapshot in a day. The youngest daily snapshots will be kept. Default value is "10".

TIMELINE_LIMIT_WEEKLY=number or range

Defines how many weekly snapshots the timeline cleanup algorithm should keep. A weekly snapshot is the first snapshot in a week. The youngest weekly snapshots will be kept. In compliance with ISO 8601 weeks start on Monday. Default value is "0".

TIMELINE_LIMIT_MONTHLY=number or range

Defines how many monthly snapshots the timeline cleanup algorithm should keep. A monthly snapshot is the first snapshot in a month. The youngest monthly snapshots will be kept. Default value is "10".

TIMELINE_LIMIT_QUARTERLY=number or range

Defines how many quarterly snapshots the timeline cleanup algorithm should keep. A quarterly snapshot is the first snapshot in a quarter. The youngest quarterly snapshots will be kept. Default value is "0".

TIMELINE_LIMIT_YEARLY=number or range

Defines how many yearly snapshots the timeline cleanup algorithm should keep. A yearly snapshot is the first snapshot in a year. The youngest yearly snapshots will be kept. Default value is "10".

EMPTY_PRE_POST_CLEANUP=boolean

Defines whether the empty-pre-post cleanup algorithm should be run for the config. Default value is "no".

EMPTY_PRE_POST_MIN_AGE=seconds

Minimal age for snapshots to be deleted by the empty-pre-post cleanup algorithm. Default value is "3600".

## TYPES
Some of the types used for the variables deserve an explanation.

range

A range of numbers given as min-value-max-value, e.g. "10-20".

qgroup

A btrfs qgroup in the standard form level-id, e.g. "1/0".

## NOTES
The default values stated here are the values snapper uses when the entry is missing in the configuration file. Some are not identical to the values from the configuration file template.

## HOMEPAGE
http://snapper.io/

## AUTHORS
Arvin Schnell <aschnell@suse.com>

## SEE ALSO
snapper(8), snapperd(8)


snapper-backup-configs

package: snapper-backup

title: snapper-backup-configs(5)

text:
# snapper-backup-configs(5)

## NAME
snapper-backup-configs - Configuration files for snapper backup configs

## DESCRIPTION
Each file /etc/snapper/backup-configs/*.json describes a snapper backup config.

The file uses JSON syntax containing a single object with key-value pairs.

## KEY VALUE PAIRS
The following is a list of keys that can be present in the configuration file.

config

Name of the snapper config.

target-mode

Either local or ssh-push.

source-path

Path of the source subvolume. This must match the subvolume of the corresponding snapper config.

target-path

Path of the target subvolume or mount point.

automatic

Boolean for enabling automatic transfer and delete for the backup config using a systemd timer service.

ssh-host

Name of the target host. Required for target mode ssh-push.

ssh-port

Port of the target host. Optional for target mode ssh-push.

ssh-user

User on the target host. Optional for target mode ssh-push.

ssh-identity

An ssh-identity to access the host without requiring a password or passphrase. Optional for target mode ssh-push.

send-compressed-data

Per default snbk will add the option --compressed-data iff supported by the source and target system. This can be disable by setting this value to false.

send-options

Extra options for the btrfs send command as an array of strings. Optional. Per default snbk automatically adds --proto and --compressed-data iff supported by both the source and target.

receive-options

Extra options for the btrfs receive command as an array of strings. Optional.

target-btrfs-bin

Location of the btrfs binary on the target. Can also be used to install wrapper scripts. Optional.

target-ls-bin

Location of the ls binary on the target. Can also be used to install wrapper scripts. Optional.

target-mkdir-bin

Location of the mkdir binary on the target. Can also be used to install wrapper scripts. Optional.

target-rm-bin

Location of the rm binary on the target. Can also be used to install wrapper scripts. Optional.

target-rmdir-bin

Location of the rmdir binary on the target. Can also be used to install wrapper scripts. Optional.

## EXAMPLES
An example backup config for local backups:

```
{

    "config": "root",

    "target-mode": "local",

    "automatic": true,

    "source-path": "/",

    "target-path": "/backups/root"
}

```

An example backup config for remote backups via ssh-push:

```
{

    "config": "root",

    "target-mode": "ssh-push",

    "automatic": false,

    "source-path": "/",

    "target-path": "/backups/eberich/root",

    "ssh-host": "backups.example.com",

    "ssh-identity": "/etc/snapper/certs/id_ecdsa"
}

```

## HOMEPAGE
http://snapper.io/

## AUTHORS
Arvin Schnell <aschnell@suse.com>

## SEE ALSO
snbk(8), snapper(8)


sos.conf

package: sos

title: sos.conf(5)

summary: sosreport configuration

text:
# sos.conf(5)

## NAME
sos.conf - sosreport configuration

## DESCRIPTION
sosreport uses a configuration file at /etc/sos/sos.conf, and there are subdirectories under /etc/sos that are used for specific purposes.

Note that non-root users may override options set in /etc/sos/sos.conf by creating their own sos.conf under $HOME/.config/sos.

The order in which options are loaded is as follows:

1. System configuration file at /etc/sos/sos.conf

2. User-specific configuration file at $HOME/.config/sos/sos.conf (for sos

components that support non-root)

3. In the case of running sos report, presets either automatically loaded

due to system configuration, or specified via --preset

4. Command line values

In other words, config files will override defaults, presets override config files, and command line values override presets and config files.

## SUBDIRECTORIES
The following subdirectories exist under /etc/sos and are used as noted below

extras.d

This directory is used to store configuration files used by the sos_extras plugin. The plugin traverses this directory and for each file there it executes commands or collects files optionally with sizelimit.

Expected content of an extras file is as follows:

- empty lines or those starting with '#' are ignored

- add_copy_spec called to lines starting by ':', optionally followed by

sizelimit

- otherwise, whole line will be executed as a command.

Example:

command1 --arg1 val1

command2

:/path/to/file

:/path/to/files* sizelimit

WARNING: be careful what files to collect or what commands to execute:

- avoid calling potentially dangerous or system altering commands, like:

- using multiple commands on a line (via shlex, semicolon etc.)

- executing commands on background

- setting env.variables (as those will be ignored)

- altering a system (not only by "rm -rf")

- be aware, no secret obfuscation is made

groups.d

This directory is used to store host group configuration files for sos collect. These files can specify any/all of the primary, nodes, and cluster-type options.

Users may create their own private host groups in $HOME/.config/sos/groups.d/. If a host group of the same name is saved in both the user's homedir and this directory, the homedir configuration file will have precedence. When run as non-root, sos collect will save host groups to the user's home dir, and create the necessary directory structure if required.

Note that non-root users may load host groups defined under /etc/sos/groups.d/, but they may not write new groups or update existing groups saved there.

presets.d

This directory is used to store preset configuration files for sos report. Presets may be used to save standard sets of options. See man sos-report for more information.

## PARAMETERS
There are sections for each sos component, as well as global values and those for plugin options. Options are set using 'ini'-style name = value pairs. Disabling/enabling a boolean option is done the same way like on command line (e.g. process.lsof=off).

Some options accept a comma separated list of values.

Using options that don't expect a value (like all-logs or no-report) will result in enabling those options, regardless of value set.

Sections are parsed in the ordering:

- [global]

- [component]

- [plugin_options]

[global]

<option> Sets (long) option value. Short options (i.e. z=auto)

are not supported.

[component]

Each component will have a separate section, and it will support the options that particular component provides. These are readily identifiable in the --help output for each component, E.G. sos report --help.

[plugin_options]

Alter available options for defined (and loaded) plugins. Takes the form plugin.option = value, for example rpm.rpmva = true.

## EXAMPLES
To use quiet and batch mode with 10 threads:

[global]

batch=yes

build=true

threads=10

To disable the 'host' and 'filesys' plugins:

[report]

skip-plugins = host,filesys

To disable rpm package verification in the RPM plugin:

[plugin_options]

rpm.rpmva = off

## FILES
/etc/sos/sos.conf

$HOME/.config/sos/sos.conf (optional)

## SEE ALSO
sos-report(1) sos-collect(1) sos-clean(1)


package: srecord

title: srec_aomf(5)

summary: Intel Absolute Object Module Format

text:
# srec_aomf(5)

## NAME
srec_aomf - Intel Absolute Object Module Format

## DESCRIPTION
The Absolute Object Module Format (AOMF) is a subset of the 8051 OMF. The structure of an absolute object file (the order of the records in it) is similar to that of a relocatable object file. There are three main differences: the first is that an absolute object file contains one module only, the second is that not all the records can appear in the absolute file and the third is that the records can contain only absolute information.

### Generic Record Format
Each record starts with a record type which indicates the type of the record, and record length which contain the number of bytes in the record exclusive of the first two fields. The record ends with a checksum byte which contains the 2s complement of the sum (modulo 256) of all other bytes in the record. Therefore the sum (modulo 256) of all bytes in the record is zero.

The record length includes the payload and checksum fields, but excludes the type and length fields.

All 16‐bit fields are little‐endian.

REC TYP 8 bits

Record Length 16 bits

Payload

CHK SUM 8 bits

Here are some of the relevant record types:

0x01

Scope Definition Record

0x02

Module Start Record

0x04

Module End Record

0x06

Content Record

0x0E

Segment Definition Record

0x12

Debug Items Record

0x16

Public Definition Record

0x18

External Definition Record

Names are not stored as C strings. Names are stored as a length byte followed by the contents.

### Structure
An AOMF file consists of a module header record (0x02), followed by one or more content (0x06), scope (0x01) or debug (0x12) records, and ends in a module end record (0x04).

The records with the following types are extraneous (they may appear in the file but are ignored): 0x0E, 0x16 and 0x18 (definition records). All records which are not part of the AOMF and are not extraneous are considered erroneous.

### Module Header Record
REC TYP 0x02

Record Length 16 bits

Module Name

TRN ID 8 bits

zero 8 bits

CHK SUM 8 bits

Each module must starts with a module header record. It is used to identify the module for the RL51 and other future processors of 8051 object files. In addition to the Module Name the record contains:

TRN ID

The byte identifies the program which has generated this module: 0xFD

ASM51

0xFE

PL/M-51

0xFF

RL51.

### Module End Record
REC TYP 0x04

Record Length 16 bits

Module Name

zero 16 bits

REG MSK 8 bits

zero 8 bits

CHK SUM 8 bits

The record ends the module sequence and contains the following information: characteristics

MODULE NAME

The name of the module is given here for a consistency check. It must match the name given in the Module Header Record.

REGISTER MASK (REG MSK)

The field contains a bit for each of the four register banks. Each bit, when set specifies that the corresponding bank is used by the module: Bit 0 (the least significant bit)

bank #0.

Bit 1

bank #1.

Bit 2

bank #2.

Bit 3

bank #3.

### Content Record
REC TYP 0x06

Record Length 16 bits

SEG ID 8 bits

Offset 16 bits

DATA

CHK SUM 8 bits

This record provides one or more bytes of contiguous data, from which a portion of a memory image may be constructed.

SEG ID

This field must be zero.

OFFSET

Gives the absolute address of the first byte of data in the record, within the CODE address space.

DATA

A sequence of data bytes to be loaded from OFFSET to OFFSET+RECORDLENGTH−5.

### Size Multiplier
In general, raw binary data will expand in sized by approximately 1.02 times when represented with this format.

## SOURCE

```
http://www.intel.com/design/mcs96/swsup/omf96_pi.pdf
ftp://download.intel.com/design/mcs51/SWSUP/omf51.exe (zip archive)
http://www.elsist.net/WebSite/ftp/various/OMF51EPS.pdf
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_ascii_hex(5)

summary: Ascii\[hy]Hex file format

text:
# srec_ascii_hex(5)

## NAME
srec_ascii_hex - Ascii‐Hex file format

## DESCRIPTION
This format is also known as the Ascii‐Space‐Hex or Ascii‐Hex‐Space format. If you know who invented this format, please let me know. If you have a better or more complete description, I'd like to know that, too.

The file starts with a start‐of‐text (STX or Control‐B) character (0x02). Everything before the STX is ignored.

Each data byte is represented as 2 hexadecimal characters, followed by an "execution character". The default execution character is a space, although many programs which write this format omit the space character immediately preceding end‐of‐line.

The address for data bytes is set by using a sequence of $Annnn, characters, where nnnn is the 4‐character ascii representation of the address. The comma is required. There is no need for an address record unless there are gaps. Implicitly, the file starts a address 0 if no address is set before the first data byte.

The file ends with an end‐of‐text (ETX or Control‐C) character (0x03). Everything following the ETX is ignored.

It is also possible to specify a running 16‐bit checksum using a sequence of $Snnnn, characters, although this usually appears after the ETX character and is thus often ignored.

### Variant Forms
In addition to a space character, the execution character can also be percent (%) called "ascii‐hex‐percent" format, apostrophe (') or comma (,) called "ascii‐hex‐comma" format. The file must use the same execution character throughout.

If the execution character is a comma, the address and checksum commands are terminated by a dot (.) rather than a comma (,).

### Size Multiplier
In general, binary data will expand in sized by approximately 3.0 times when represented with this format.

## EXAMPLE
Here is an example ascii‐hex file. It contains the data “Hello, World[rq] to be loaded at address 0x1000.

```
^B $A1000,
48 65 6C 6C 6F 2C 20 57 6F 72 6C 64 0A ^C
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_atmel_generic(5)

summary: Atmel Generic file format

text:
# srec_atmel_generic(5)

## NAME
srec_atmel_generic - Atmel Generic file format

## DESCRIPTION
This format is the output of the Atmel AVR assembler. The file contains two columns of hexadecimal coded values. The first column is the 24‐bit word address, the second column is the 16‐bit word data. The columns are separated by a colon (`:') character.

By default, SRecord treats this is little‐endian data (the least significant byte first). If you want big endian order, use the -atmel‐generic‐be argument instead.

### Size Multiplier
In general, binary data will expand in sized by approximately 6.0 times when represented with this format (6.5 times in Windows).

## EXAMPLE
Here is an example Atmel Generic file. It contains the data “Hello, World[rq] to be loaded at bytes address 0x0100 (but remember, the file contents are word addressed).

```
000080:4865
000081:6C6C
000082:6F2C
000083:2057
000084:6F72
000085:6C64
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_binary(5)

summary: binary file format

text:
# srec_binary(5)

## NAME
srec_binary - binary file format

## DESCRIPTION
It is possible to read and write binary files using srec_cat(1).

### File Holes
A file hole is a portion of a regular file that contains NUL characters and is not stored in any data block on disk. Holes are a long‐standing feature of Unix files. For instance, the following Unix command creates a file in which the first bytes are a hole:

```
$ echo -n "X" | dd of=/tmp/hole bs=1024 seek=6
$
```

Now /tmp/hole has 6,145 characters (6,144 NUL characters plus an X character), yet the file occupies just one data block on disk.

File holes were introduced to avoid wasting disk space. They are used extensively by database applications and, more generally, by all applications that perform hashing on files.

See http://www.oreilly.com/catalog/linuxkernel2/chapter/ch17.pdf for more information.

### Reading
The size of binary files is taken from the size of the file on the file system. If the file has holes these will read as blocks of NUL (zero) data, as there is no elegant way to detect Unix file holes. In general, you probably want to use the -unfill filter to find and remove large swathes of zero bytes.

### Writing
In producing a binary file, srec_cat(1) honours the address information and places the data into the binary file at the addresses specified in the hex file. This usually results on holes in the file. Sometimes alarmingly large file sizes are reported as a result.

If you are on a brain‐dead operating system without file holes then there are going to be real data blocks containing real zero bytes, and consuming real amounts of disk space. Upgrade - I suggest Linux.

To make a file of the size you expect, use

srec_info foo.s19

to find the lowest address, then use

srec_cat foo.s19 -intel -offset -n -o foo.bin -binary

where n is the lowest address present in the foo.s19 file, as reported by srec_info(1). The negative offset serves to move the data down to have an origin of zero.

## SEE ALSO
srec_input(1)

for a description of the -unfill filter

srec_examples(1)

has a section about binary files, and ways of automagically offseting the data back to zero in a single command.

## COPYRIGHT
SRrecord version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The SRrecord program comes with ABSOLUTELY NO WARRANTY; for details use the 'SRrecord -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'SRrecord -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_brecord(5)

text:
# srec_brecord(5)

## NAME
srec_brecord - Freescale MC68EZ328 Dragonball bootstrap record format

## DESCRIPTION
This data format is understood by Freescale MC68EZ328 Dragonball series processors on their internal UART.

### Lines
Each line contains hexadecimal data, each byte represented by two hexadecimal nybbles in upper case. Characters not in this set, but larger than 0x30 (e.g. lower case) will be ignored, less than 0x30 (e.g. CR or LF) are considered record terminators. Comments are problematic; don't try this at home.

### Fields
Each line contains a 4‐byte address (big endian), a 1‐byte length‐and‐mode, and then data bytes as dictated by the length. There is no checksum. A zero length record is an execution start address record, non‐zero length records are data.

1

2

3

4

5

6

7

8

9

10

...

n

Address

Length

Data

The length‐and‐mode byte is formatted as follows:

7

6

5

4

3

2

1

0

Mode

R

Length

Mode

These bits are ignored by SRecord in input (00 = bytes, 01 = half words, 10 is reserved, 11 = long words). These bits are always zero on output by SRecord.

R

This bit indicates a data read rather than a data write; SRecord does not accept input files with this bit set, and will not set it on output.

Length

The length of the records data bytes. It does not include the address or length bytes. The maximum payload of a record is 31 bytes of data.

### Size Multiplier
In general, binary data will expand in sized by at least 2.35 times when represented with this format.

## EXAMPLE
Here is an example b‐record format file. It contains the data “Hello, World” to be loaded at address 0.

```
000000000D48656C6C6F2C20576F726C640A
```

## SEE ALSO
http://www.freescale.com/files/32bit/doc/ref_manual/MC68VZ328UM.pdf

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_coe(5)

summary: Xilinx Coefficient File Format

text:
# srec_coe(5)

## NAME
srec_coe - Xilinx Coefficient File Format

## DESCRIPTION
The Xilinx Coefficient File Format has a general syntax of the form:

keyword

=

value

;

optional comment

radix‐keyword

=

value

;

optional comment

data‐keyword

=

value, ..., value;

There are numerous keywords, only the “memory_initialization_radix” and “memory_initialization_vector” keywords are used. The semicolons are mandatory.

### Size Multiplier
Binary data stored in this format expand approximately 4 times (5 time on Windows).

### See Also
http://www.xilinx.com/support/documentation/sw_manuals/xilinx11/cgn_r_coe_file_syntax.htm

## COPYRIGHT
srec_coe.5 version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_coe.5 program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_coe.5 -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_coe.5 -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_cosmac(5)

summary: RCA Cosmac Elf file format

text:
# srec_cosmac(5)

## NAME
srec_cosmac - RCA Cosmac Elf file format

## DESCRIPTION
This file takes the form of one or more RCA Cosmac Elf monitor commands, also known as the IDIOT/4 monitor. Only the change memory command (!M) is allowed.

The general form of the !M command takes the form

!Maaaa dd ... dd

The !M command writes data byte bytes (represented by character pairs dd) into successive memory locations, started at address aaaa. Spaces between data bytes are ignored. Using the comma (,) line continuation character resumes from the next address in sequence.

!Maaaa dd ... dd, dd ... dd

Using the semicolon (;) line continuation character takes an address on the next line

!Maaaa dd ... dd; aaaa dd ... dd

It is also possible to have the semicolon immediately after the command.

!M; aaaa dd ... dd

All of these forms may be used in combination.

### Size Multiplier
In general, binary data will expand in size by approximately 2.0 times when represented with this format.

## EXAMPLE
Here is an example Cosmac file. It contains the data “Hello, World[rq] to be loaded at address 0x1000.

```
!M1000 48656C6C6F2C20576F726C640A
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_dec_binary(5)

summary: DEC Binary (XXDP) file format

text:
# srec_dec_binary(5)

## NAME
srec_dec_binary - DEC Binary (XXDP) file format

## DESCRIPTION
The DEC Binary (XXDP) format was used on the PDP 11 series machines. This is a binary format, and is not readable or editable with a text editor. The file consists of records of the form

type

length

address

...data...

checksum

The field are defined as follows:

type

Two byte little‐endian value. Must always be 1.

length

Two byte little‐endian value. This is the number of bytes in the data, plus six.

address

Two byte little‐endian value. This is the load address of the data.

data

The data is simple raw bytes. There are (length‐6) of them.

checksum

The checcksum is a single byte. It is the negative of the simple summ of all the header and data bytes.

If the record length is exactly 6 (i.e. no data), this is the execution start address record, indicating the transfer address.

In addition there may be NUL padding characters between records. It is common for records to be padded so that they start on even byte boundaries. In the days of paper tape, it was common for the file to have many leading NULs, to generate blank leader on the tape.

### Size Multiplier
In general, raw binary data will expand in sized by approximately 1.03 times when represented with this format.

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_emon52(5)

summary: Elektor Monitor (EMON52) file format

text:
# srec_emon52(5)

## NAME
srec_emon52 - Elektor Monitor (EMON52) file format

## DESCRIPTION
This format is used by the monitor EMON52, developed by the European electronics magazine Elektor (Elektuur in Holland). Elektor wouldn't be Elektor if they didn't try to reinvent the wheel. It's a mystery why they didn't use an existing format for the project. Only the Elektor Assembler will produce this file format, reducing the choice of development tools dramatically.

### Records
All data lines are called records, and each record contains the following four fields:

cc

aaaa

:

dd ... dd

ssss

The field are defined as follows:

cc

The byte count. A two digit hex value (1 byte), counting the actual data bytes in the record. The byte count is separated from the next field by a space.

aaaa

The address field. A four hex digit (2 byte) number representing the first address to be used by this record.

:

The address field and the data field are separated by a colon.

dd

The actual data of this record. There can be 1 to 255 data bytes per record (see cc) All bytes in the record are separated from each other (and the checksum) by a space.

ssss

Data Checksum, adding all bytes of the data line together, forming a 16 bit checksum. Covers only all the data bytes of this record.

Please note that there is no End Of File record defined.

### Byte Count
The byte count cc counts the actual data bytes in the current record. Usually records have 16 data bytes. I don't know what the maximum number of data bytes is. It depends on the size of the data buffer in the EMON52.

### Address Field
This is the address where the first data byte of the record should be stored. After storing that data byte, the address is incremented by 1 to point to the address for the next data byte of the record. And so on, until all data bytes are stored.

The address is represented by a 4 digit hex number (2 bytes), with the MSD first.

### Data Field
The payload of the record is formed by the Data field. The number of data bytes expected is given by the Byte Count field.

### Checksum
The checksum is a 16 bit result from adding all data bytes of the record together.

### Size Multiplier
In general, binary data will expand in sized by approximately 3.8 times when represented with this format.

## EXAMPLE
Here is an example of an EMON52 file:

```
10 0000:57 6F 77 21 20 44 69 64 20 79 6F 75 20 72 65 61 0564
10 0010:6C 6C 79 20 67 6F 20 74 68 72 6F 75 67 68 20 61 05E9
10 0020:6C 6C 20 74 68 69 73 20 74 72 6F 75 62 6C 65 20 05ED
10 0030:74 6F 20 72 65 61 64 20 74 68 69 73 20 73 74 72 05F0
04 0040:69 6E 67 21 015F
```

## SEE ALSO
http://sbprojects.fol.nl/knowledge/fileformats/emon52.htm

## AUTHOR
This man page was taken from the above Web page. It was written by San Bergmans <sanmail@bigfoot.com>


title: srec_fairchild(5)

summary: Fairchild Fairbug file format

text:
# srec_fairchild(5)

## NAME
srec_fairchild - Fairchild Fairbug file format

## DESCRIPTION
The Fairchild Fairbug format has 8‐byte records. A file begins with an address record and ends with an end‐of‐file record.

There are three record types in this file format.

Address records are of the form

S

nnnn

indicating the address for the following data records. Data records are of the form

X

ffffffffffffffff

c

Each data record begins with an X and always contains 8 data bytes. The ff characters are hexadecimal byte values (8 bytes). Each data byte is represented by 2 hexadecimal characters. The c character is a hex digit being the the nibble‐sum of the data bytes. A 1‐digit hexadecimal checksum follows the data in each data record. The checksum represents, in hexadecimal notation, the sum of the binary equivalents of the 16 digits in the record; the half carry from the fourth bit is ignored. The programmer ignores any character (except for address characters and the asterisk character, which terminates the data transfer) between a checksum and the start character of the next data record. This space can be used for comments. The end‐of‐file record has the form

*

The last record consists of an asterisk only, which indicates the end of file.

### Size Multiplier
In general, binary data will expand in sized by approximately 2.4 times when represented with this format.

## EXAMPLE
Here is an example Fairchild Fairbug file. It contains the data “Hello, World[rq] to be loaded at address 0x1000. Notice how the last record is padded with 0xFF bytes.

```
S1000
X48656C6C6F2C2057C
X6F726C64210AFFFF3
*
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_fastload(5)

summary: LSI Logic Fast Load file format

text:
# srec_fastload(5)

## NAME
srec_fastload - LSI Logic Fast Load file format

## DESCRIPTION
The FastLoad Format uses a compressed ASCII format that permits files to be downloaded in less than half the time taken for Motorola S‐records.

The base‐64 encoding used is "A‐Za‐z0−9,.". The data is encoded in groups of 4 characters (3 bytes, 24 bits).

The character '/' is used to introduce a special function. Special functions are:

Annnnnn

Defines an address.

Bnn

Define a single byte.

Cnnnn

Compare the checksums. The checksum is a simple positive 16‐bit sum, of the data bytes only.

EAA

Define the program's entry point. The address will be the current address as defined by the A command. (The AA number in this command is ignored.) This must be the last entry in the file.

KAA

Clear the checksum. (The AA number in this command is ignored.)

Sname,X

Define a symbol. The address of the symbol will be the current address as defined by the A command.

Znn

Clear a number of bytes.

### Size Multiplier
In general, binary data will expand in sized by approximately 1.4 times when represented with this format.

## EXAMPLE
Here is an example LSI Logic Fast Load format file. It contains the data “Hello, World[rq] to be loaded at address 0.

```
/AAAA
SGVsbG8sIFdvcmxk/BAK/CARS/AAAA/EAA
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_formatted_binary(5)

summary: Formatted Binary file format

text:
# srec_formatted_binary(5)

## NAME
srec_formatted_binary - Formatted Binary file format

## DESCRIPTION
This is the PDP‐11 paper tape format, described in the DEC‐11‐GGPC‐D PDP‐11 "Paper Tape Software Programming Handbook" 1972.

The file starts with a character sequence which appears as an arrow when punched on 8‐hole paper tape.

0x08, 0x1C, 0x2A, 0x49, 0x08, 0x00

Then follows a byte count, encoded big‐endian in the low 4 bits of the next 4 bytes. The high bits should be zero.

Then follows a 0xFF byte.

The data follows, as many bytes as specified in the header.

The trailer consists of the following bytes:

0x00, 0x00,

and then a 2‐byte checksum (big‐endian). The alternate header sequence

0x08, 0x1C, 0x3E, 0x6B, 0x08, 0x00

is followed by an 8‐nibble big‐endian byte count.

### Size Multiplier
In general, binary data will expand in sized very little when represented with this format.

## EXAMPLE
Here is a hex dump of a formatted binary file containing the data "Hello, World!".

```
0000: 08 1C 2A 49 08 00 00 00  ..*I....
0008: 00 0E FF 48 65 6C 6C 6F  ...Hello
0010: 2C 20 57 6F 72 6C 64 21  , World!
0018: 0A 00 00 04 73           ....s
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_forth(5)

summary: FORTH file format

text:
# srec_forth(5)

## NAME
srec_forth - FORTH file format

## DESCRIPTION
This format can be read by FORTH interpreters

The file starts with HEX to set the number base.

Each line contains the address, the byte and a store command, either C! for RAM or EEC! for EEPROM

## EXAMPLE
Here is an example srec[hy]forth file. It contains the data “Hello, World” to be loaded at address 0x1000.

```
HEX
48 1000 C!
65 1001 C!
6C 1002 C!
6C 1003 C!
6F 1004 C!
2C 1005 C!
20 1006 C!
57 1007 C!
6F 1008 C!
72 1009 C!
6C 100A C!
64 100B C!
0A 100C C!
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_fpc(5)

summary: four packed code file format

text:
# srec_fpc(5)

## NAME
srec_fpc - four packed code file format

## SYNOPSIS
All ASCII based file formats have one disadvantage in common: they all need more than double the amount of characters as opposed to the number of bytes to be sent. Address fields and checksums will add even more characters. So the shorter the records, the more characters have to be sent to get the file across.

The FPC format may be used to reduce the number of characters needed to send a file in ASCII format, although it still needs more characters than the actual bytes it sends. FPC stands for "Four Packed Code". The reduction is accomplished by squeezing 4 real bytes into 5 ASCII characters. In fact every ASCII character will be a digit in the base 85 number system. There aren't enough letters, digits and punctuation marks available to get 85 different characters, but if we use both upper case and lower case letters we will manage. This implies that the FPC is case sensitive, as opposed to all other ASCII based file formats.

### Base 85
The numbering system is in base 85, and is somewhat hard to understand for us humans who are usually only familiar with base 10 numbers. Some of us understand base 2 and base 16 as well, but base 85 is for most people something new. Luckily we don't have to do any math with this number system. We just convert a 32 bit number into a 5 digit number in base 85. A 32 bit number has a range of 4,294,967,296, while a 5 digit number in base 85 has a range of 4,437,053,125, which is enough to do the trick. One drawback is that we always have to send multiples of 4 bytes, even if we actually want to send 1, 2 or 3 bytes. Unused bytes are padded with zeroes, and are discarded at the receiving end.

The digits of the base 85 numbering system start at %, which represents the value of 0. The highest value of a digit in base 85 is 84, and is represented by the character 'z'. If you want to check this with a normal ASCII table you will notice that we have used one character too many! Why? I don't know, but for some reason we have to skip the '*' character in the row. This means that after the ')' character follows the '+' character.

We can use normal number conversion algorithms to generate the FPC digits, with this tiny difference. We have to check whether the digit is going to be equal or larger than the ASCII value for '*'. If this is the case we have to increment the digit once to stay clear of the '*'. In base 85 MSD digits go first, like in all number systems!

The benefit of this all is hopefully clear. For every 4 bytes we only have to send 5 ASCII characters, as opposed to 8 characters for all other formats.

### Records
Now we take a look at the the formatting of the FPC records. We look at the record at byte level, not at the actual base 85 encoded level. Only after formatting the FPC record at byte level we convert 4 bytes at a time to a 5 digit base 85 number. If we don't have enough bytes in the record to fill the last group of 5 digits we will add bytes with the value of 0 behind the record.

$

ss

cc

ffff

aaaaaaaa

dddddddd

The field are defined as:

$

Every line starts with the character $, all other characters are digits of base 85.

ss

The checksum. A one byte 2's‐complement checksum of all bytes of the record.

cc

The byte‐count. A one byte value, counting all the bytes in the record minus 4.

ffff

Format code, a two byte value, defining the record type.

aaaaaaaa

The address field. A 4 byte number representing the first address of this record.

dddddddd

The actual data of this record.

### Record Begin
Every record begins with the ASCII character "$". No spaces or tabs are allowed in a record. All other characters in the record are formed by groups of 5 digits of base 85.

### Checksum field
This field is a one byte 2's‐complement checksum of the entire record. To create the checksum make a one byte sum from all of the bytes from all of the fields of the record:

Then take the 2's‐complement of this sum to create the final checksum. The 2's‐complement is simply inverting all bits and then increment by 1 (or using the negative operator). Checking the checksum at the receivers end is done by adding all bytes together including the checksum itself, discarding all carries, and the result must be $00. The padding bytes at the end of the line, should they exist, should not be included in checksum. But it doesn't really matter if they are, for their influence will be 0 anyway.

### Byte Count
The byte count cc counts the number of bytes in the current record minus 4. So only the number of address bytes and the data bytes are counted and not the first 4 bytes of the record (checksum, byte count and format flags). The byte count can have any value from 0 to 255.

Usually records have 32 data bytes. It is not recommended to send too many data bytes in a record for that may increase the transmission time in case of errors. Also avoid sending only a few data bytes per record, because the address overhead will be too heavy in comparison to the payload.

### Format Flags
This is a 2 byte number, indicating what format is represented in this record. Only a few formats are available, so we actually waste 1 byte in each record for the sake of having multiples of 4 bytes.

Format code 0 means that the address field in this record is to be treated as the absolute address where the first data byte of the record should be stored.

Format code 1 means that the address field in this record is missing. Simply the last known address of the previous record +1 is used to store the first data byte. As if the FPC format wasn't fast enough already ;‐)

Format code 2 means that the address field in this record is to be treated as a relative address. Relative to what is not really clear. The relative address will remain in effect until an absolute address is received again.

### Address Field
The first data byte of the record is stored in the address specified by the Address field aaaaaaaa. After storing that data byte, the address is incremented by 1 to point to the address for the next data byte of the record. And so on, until all data bytes are stored.

The length of the address field is always 4 bytes, if present of course. So the address range for the FPC format is always 2**32.

If only the address field is given, without any data bytes, the address will be set as starting address for records that have no address field.

Addresses between records are non sequential. There may be gaps in the addressing or the address pointer may even point to lower addresses as before in the same file. But every time the sequence of addressing must be changed, a format 0 record must be used. Addressing within one single record is sequential of course.

### Data Field
This field contains 0 or more data bytes. The actual number of data bytes is indicated by the byte count in the beginning of the record less the number of address bytes. The first data byte is stored in the location indicated by the address in the address field. After that the address is incremented by 1 and the next data byte is stored in that new location. This continues until all bytes are stored. If there are not enough data bytes to obtain a multiple of 4 we use 0x00 as padding bytes at the end of the record. These padding bytes are ignored on the receiving side.

### End of File
End of file is recognized if the first four bytes of the record all contain 0x00. In base 85 this will be “$%%%%%”. This is the only decent way to terminate the file.

### Size Multiplier
In general, binary data will expand in sized by approximately 1.7 times when represented with this format.

## Example
Now it's time for an example. In the first table you can see the byte representation of the file to be transferred. The 4th row of bytes is not a multiple of 4 bytes. But that does not matter, for we append $00 bytes at the end until we do have a multiple of 4 bytes. These padding bytes are not counted in the byte count however!

```
D81400000000B000576F77212044696420796F7520726561
431400000000B0106C6C7920676F207468726F7567682061
361400000000B0206C6C20746861742074726F75626C6520
591100000000B030746F207265616420746869733F000000
00000000
```

Only after converting the bytes to base 85 we get the records of the FPC type file format presented in the next table. Note that there is always a multiple of 5 characters to represent a multiple of 4 bytes in each record.

```
$kL&@h%%,:,B.\?00EPuX0K3rO0JI))
$;UPR'%%,:<Hn&FCG:at<GVF(;G9wIw
$7FD1p%%,:LHmy:>GTV%/KJ7@GE[kYz
$B[6\;%%,:\KIn?GFWY/qKI1G5:;-_e
$%%%%%
```

As you can see the length of the lines is clearly shorter than the original ASCII lines.

## SEE ALSO
http://sbprojects.fol.nl/knowledge/fileformats/fpc.htm

## AUTHOR
This man page was taken from the above Web page. It was written by San Bergmans <sanmail@bigfoot.com>

For extra points: Who invented this format? Where is it used?


title: srec_idt(5)

summary: IDT/sim binary file format

text:
# srec_idt(5)

## NAME
srec_idt - IDT/sim binary file format

## DESCRIPTION
This format comes from Integrated Device Technology (IDT) System Integration Manager (IDT/sim).

It is almost identical to the Motorola S‐Record format, except that most of each record is in binary, and there is no line termination character. The 'S' and tag characters are the same (ascii), however all other bytes are emitted as binary, rather than as a 2‐byte hexadecimal ascii encoding.

## SEE ALSO
srec_motorola(5)

The orginal Motorola S‐Record format.

srec_wilson(5)

For a different spin on making S‐Record into a more densely packed binary file.

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_intel(5)

text:
# srec_intel(5)

## NAME
srec_intel - Intel Hexadecimal object file format specification

## DESCRIPTION
This format is also known as the Intel MCS‐86 Object format.

This document describes the hexadecimal object file format for the Intel 8‐bit, 16‐bit, and 32‐bit microprocessors. The hexadecimal format is suitable as input to PROM programmers or hardware emulators.

Hexadecimal object file format is a way of representing an absolute binary object file in ASCII. Because the file is in ASCII instead of binary, it is possible to store the file is non‐binary medium such as paper‐tape, punch cards, etc.; and the file can also be displayed on CRT terminals, line printers, etc.. The 8‐bit hexadecimal object file format allows for the placement of code and data within the 16‐bit linear address space of the Intel 8‐bit processors. The 16‐bit hexadecimal format allows for the 20‐bit segmented address space of the Intel 16‐bit processors. And the 32‐bit format allows for the 32‐bit linear address space of the Intel 32‐bit processors.

--address-length=2

“i8hex”

16‐bit

--address-length=3

“i16hex”

20‐bit

segmented

--address-length=4

“i32hex”

32‐bit

linear

The hexadecimal representation of binary is coded in ASCII alphanumeric characters. For example, the 8‐bit binary value 0011‐1111 is 3F in hexadecimal. To code this in ASCII, one 8‐bit byte containing the ASCII code for the character '3' (0011‐0011 or 0x33) and one 8‐bit byte containing the) ASCII code for the character 'F' (0100‐0110 or 0x46) are required. For each byte value, the high‐order hexadecimal digit is always the first digit of the pair of hexadecimal digits. This representation (ASCII hexadecimal) requires twice as many bytes as the binary representation.

A hexadecimal object file is blocked into records, each of which contains the record type, length, memory load address and checksum in addition to the data. There are currently six (6) different types of records that are defined, not all combinations of these records are meaningful, however. The record are:

•

Data Record (8‐, 16‐, or 32‐bit formats)

•

End of File Record (8‐, 16‐, or 32‐bit formats)

•

Extended Segment Address Record (16‐ or 32‐bit formats)

•

Start Segment Address Record (16‐ or 32‐bit formats)

•

Extended Linear Address Record (32‐bit format only)

•

Start Linear Address Record (32‐bit format only)

### General Record Format
Record Mark

Record Length

Load Offset

Record Type

Data

Check sum

Record Mark.

Each record begins with a Record Mark field containing 0x3A, the ASCII code for the colon (“:”) character.

Record Length

Each record has a Record Length field which specifies the number of bytes of information or data which follows the Record Type field of the record. This field is one byte, represented as two hexadecimal characters. The maximum value of the Record Length field is hexadecimal 'FF' or 255.

Load Offset

Each record has a Load Offset field which specifies the 16‐bit starting load offset of the data bytes, therefore this field is only used for Data Records. In other records where this field is not used, it should be coded as four ASCII zero characters (“0000” or 0x30303030). This field is two byte, represented as four hexadecimal characters.

Record Type

Each record has a Record Type field which specifies the record type of this record. The Record Type field is used to interpret the remaining information within the record. This field is one byte, represented as two hexadecimal characters. The encoding for all the current record types are: 0

Data Record

1

End of File Record

2

Extended Segment Address Record

3

Start Segment Address Record

4

Extended Linear Address Record

5

Start Linear Address Record

Data

Each record has a variable length Data field, it consists of zero or more bytes encoded as pairs of hexadecimal digits. The interpretation of this field depends on the Record Type field.

Checksum

Each record ends with a Checksum field that contains the ASCII hexadecimal representation of the two's complement of the 8‐bit bytes that result from converting each pair of ASCII hexadecimal digits to one byte of binary, from and including the Record Length field to and including the last byte of the Data field. Therefore, the sum of all the ASCII pairs in a record after converting to binary, from the Record Length field to and including the Checksum field, is zero.

### Extended Linear Address Record
(32‐bit format only)

Record Mark (“:”)

Record Length (2)

Load Offset (0)

Record Type (4)

ULBA (2 bytes)

Check sum

The 32‐bit Extended Linear Address Record is used to specify bits 16‐31 of the Linear Base Address (LBA), where bits 0‐15 of the LBA are zero. Bits 16‐31 of the LBA are referred to as the Upper Linear Base Address (ULBA). The absolute memory address of a content byte in a subsequent Data Record is) obtained by adding the LBA to an offset calculated by adding the Load Offset field of the containing Data Record to the index of the byte in the Data Record (0, 1, 2, ... n). This offset addition is done) modulo 4G (i.e. 32‐bits from 0xFFFFFFFF to 0x00000000) results in wrapping around from the end to the beginning of the 4G linear address defined by the LBA. The linear address at which a particular byte is loaded is calculated as:

(LBA + DRLO + DRI) MOD 4G

where: DRLO

is the Load Offset field of a Data Record.

DRI

is the data byte index within the Data Record.

When an Extended Linear Address Record defines the value of LBA, it may appear anywhere within a 32‐bit hexadecimal object file. This value remains in effect until another Extended Linear Address Record is encountered. The LBA defaults to zero until an Extended Linear Address Record is encountered. The contents of the individual fields within the record are: Record Mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains 0x3032, the hexadecimal encoding of the ASCII characters “02”, which is the length, in bytes, of the ULBA data information within this record.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters “0000”, since this field is not used for this record.

Record Type

This field contains 0x3034, the hexadecimal encoding of the ASCII character “04”, which specifies the record type to be an Extended Linear Address Record.

ULBA

This field contains four ASCII hexadecimal digits that specify the 16‐bit Upper Linear Base Address value. The value is encoded big‐endian (most significant digit first).

Checksum

This field contains the check sum on the Record Length, Load Offset, Record Type, and ULBA fields.

### Extended Segment Address Record
(16‐ or 32‐bit formats)

Record Mark (“:”)

Record Length (2)

Load Offset (0)

Record Type (2)

USBA (2 bytes)

Check sum

The 16‐bit Extended Segment Address Record is used to specify bits 4‐19 of the Segment Base Address (SBA), where bits 0‐3 of the SBA are zero. Bits 4‐19 of the SBA are referred to as the Upper Segment Base Address (USBA). The absolute memory address of a content byte in a subsequent Data Record is) obtained by adding the SBA to an offset calculated by adding the Load Offset field of the containing Data Record to the index of the byte in the Data Record (0, 1, 2, ... n). This offset addition is done modulo 64K (i.e. 16‐bits from 0xFFFF to 0x0000 results in wrapping around from the end to the beginning of the 64K segment defined by the SBA. The address at which a particular byte is loaded is calculated as:

SBA + ((DRLO + DRI) MOD 64K)

where: DRLO

is the LOAD OFFSET field of a Data Record.

DRI

is the data byte index within the Data Record.

When an Extended Segment Address Record defines the value of SBA, it may appear anywhere within a 16‐bit hexadecimal object file. This value remains in effect until another Extended Segment Address Record is encountered. The SBA defaults to zero until an Extended Segment Address Record is encountered.

The contents of the individual fields within the record are:

Record Mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains 0x3032, the hexadecimal encoding of the ASCII characters '02', which is the length, in bytes, of the USBA data information within this record.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters '0000', since this field is not used for this record.

Record Type

This field contains 0x3032, the hexadecimal encoding of the ASCII character “02”, which specifies the record type to be an Extended Segment Address Record.

USBA

This field contains four ASCII hexadecimal digits that specify the 16‐bit Upper Segment Base Address value. The field is encoded big‐endian (most significant digit first).

Checksum

This field contains the check sum on the Record length, Load Offset, Record Type, and USBA fields.

### Data Record
(8‐, 16‐ or 32‐bit formats)

Record Mark (“:”)

Record Length

Load Offset

Record Type

Data

Check sum

The Data Record provides a set of hexadecimal digits that represent the ASCII code for data bytes that make up a portion of a memory image. The method for calculating the absolute address (linear in the 8‐bit and 32‐bit case and segmented in the 16‐bit case) for each byte of data is described in the discussions of the Extended Linear Address Record and the Extended Segment Address Record.

The contents of the individual fields within the record are:

Record Mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains two ASCII hexadecimal digits that specify the number of data bytes in the record. The maximum value is 255 decimal.

Load Offset

This field contains four ASCII hexadecimal digits representing the offset from the LBA (see Extended Linear Address Record see Extended Segment Address Record) defining the address which the first byte of the data is to be placed.

Record Type

This field contains 0x3030, the hexadecimal encoding of the ASCII character “00”, which specifies the record type to be a Data Record.

Data

This field contains pairs of ASCII hexadecimal digits, one pair for each data byte.

Checksum

This field contains the check sum on the Record Length, Load Offset, Record Type, and Data fields.

Note: Care must be taken when the addresses with an record span the end of addressing. The behaviour is different for linear and segmented addressing modes.

linear

If a record starts just short of 2**32, and would finish after 2**32, the later part of the record wraps around to address 0. TP 8n segment If a record starts just for of a 2**16 boundary, and would finish after that 2**16 boundary, the later part of the record wraps around to address 0 within the same segment (not the next segment).

The srec_cat(1) program will never output records such as these, it will always produce separate records on output.

### Start Linear Address Record
(32‐bit format only)

Record Mark (“:”)

Record Length (4)

Load. Offset (0)

Record Type (5)

EIP (4 bytes)

Check sum

The Start Linear Address Record is used to specify the execution start address for the object file. The value given is the 32‐bit linear address for the EIP register. Note that this record only specifies the code address within the 32‐bit linear address space of the 80386. If the code is to start execution in the real mode of the 80386, then the Start Segment Address Record should be used instead, since that record specifies both the CS and IP register contents necessary for real mode.

The Start Linear Address Record can appear anywhere in a 32‐bit hexadecimal object file. If such a record is not present in a hexadecimal object file, a loader is free to assign a default execution start address.

The contents of the individual fields within the record are:

Record mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record length

The field contains 0x3034, the hexadecimal encoding of the ASCII characters “04”, which is the length, in bytes, of the EIP register content within this record.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters “0000”, since this field is not used for this record.

Record Type

This field contains 0x3035, the hexadecimal encoding of the ASCII character “05”, which specifies the record type to be a Start Linear Address Record.

EIP

This field contains eight ASCII hexadecimal digits that specify the 32‐bit EIP register contents. The field is encoded big‐endian (most significant digit first).

Checksum

This field contains the check sum on the Record length, Load Offset, Record Type, and EIP fields.

### Start Segment Address Record
(16‐ or 32‐bit formats)

Record Mark (“:”)

Record Length (4)

Load. Offset (0)

Record Type (3)

CS (2 bytes)

IP (2 bytes)

Check sum

The Start Segment Address Record is used to specify the execution start address for the object file. The value given is the 20‐bit segment address for the CS and IP registers. Note that this record only specifies the code address within the 20‐bit segmented address space of the 8086/80186. The Start Segment Address Record can appear anywhere in a 16‐bit hexadecimal object file. If such a record is not present in a hexadecimal object file, a loader is free to assign a default start address.

The contents of the individual fields within the record are:

Record Mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains 0x3034, the hexadecimal encoding of the ASCII characters “04”, which is the length, in bytes, of the CS and IP register contents within this record.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters “0000”, since this field is not used for this record.

Record Type

This field contains 0x3033, the hexadecimal encoding of the ASCII character '03', which specifies the record type to be a Start Segment Address Record.

CS

This field contains four ASCII hexadecimal digits that specify the 16‐bit CS register contents. The field is encoded big‐endian (most significant digit first).

IP

This field contains four ASCII hexadecimal digits that specify the 16‐bit IP register contents. The field is encoded big‐endian (most significant digit first).

Checksum

This field contains the check sum on the Record length, Load Offset, Record Type, CS, and IP fields.

### End of File Record
(8‐, 16‐, or 32‐bit formats)

Record Mark (“:”)

Record Length (0)

Load Offset (0)

Record Type (1)

Check sum (0xFF)

The End of File Record specifies the end of the hexadecimal object file.

The contents of the individual fields within the record are:

Record mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains 0x3030, the hexadecimal encoding of the ASCII characters “00”. Since this record does not contain any Data bytes, the length is zero.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters “0000”, since this field is not used for this record. In ancient times, i8hex used this for the start address record.

Record Type

This field contains 0x3031, the hexadecimal encoding of the ASCII character “01”, which specifies the record type to be an End of File Record.

Checksum

This field contains the check sum an the Record Length, Load Offset, and Record Type fields. Since all the fields are static, the check sum can also be calculated statically, and the value is 0x4646, the hexadecimal encoding of the ASCII characters “FF”.

### Size Multiplier
In general, binary data will expand in sized by approximately 2.3 times when represented with this format.

## EXAMPLE
Here is an example Intel hex file. It contains the data “Hello, World” to be loaded at address 0.

```
:0D00000048656C6C6F2C20576F726C640AA1
:00000001FF
```

## REFERENCE
This information comes (very indirectly) from Microprocessors and Programmed Logic, Second Edition, Kenneth L. Short, 1987, Prentice‐Hall, ISBN 0‐13‐580606‐2.

http://en.wikipedia.org/wiki/Intel_HEX

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au

### Derivation
This manual page is derived from a file marked as follows:

Intel Hexadecimal Object File Format Specification; Revision A, 1/6/88

Disclaimer: Intel makes no representation or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Intel reserves the right to revise this publication from time to time in the content hereof without obligation of Intel to notify any person of such revision or changes. The publication of this specification should not be construed as a commitment on Intel's part to implement any product.


title: srec_intel16(5)

summary: Intel Hexadecimal 16\[hy]bit file format specification

text:
# srec_intel16(5)

## NAME
srec_intel16 - Intel Hexadecimal 16‐bit file format specification

## DESCRIPTION
This format is also known as the INHX16 format.

This document describes the hexadecimal object file format for 16‐bit microprocessors.

This format is very similar to the srec_intel(5) format, except that the addresses are word addresses. The count field is a word count.

The hexadecimal representation of binary is coded in ASCII alphanumeric characters. For example, the 8‐bit binary value 0011‐1111 is 3F in hexadecimal. To code this in ASCII, one 8‐bit byte containing the ASCII code for the character '3' (0011‐0011 or 0x33) and one 8‐bit byte containing the) ASCII code for the character 'F' (0100‐0110 or 0x46) are required. For each byte value, the high‐order hexadecimal digit is always the first digit of the pair of hexadecimal digits. This representation (ASCII hexadecimal) requires twice as many bytes as the binary representation.

A hexadecimal object file is blocked into records, each of which contains the record type, length, memory load address and checksum in addition to the data. There are currently six (6) different types of records that are defined, not all combinations of these records are meaningful, however. The record are:

•

Data Record

•

End of File Record

•

Extended Segment Address Record

•

Start Segment Address Record

•

Extended Linear Address Record

•

Start Linear Address Record

### General Record Format
Record Mark

Record Length

Load Offset

Record Type

Data

Check sum

Record Mark.

Each record begins with a Record Mark field containing 0x3A, the ASCII code for the colon (“:”) character.

Record Length

Each record has a Record Length field which specifies the number of 16‐bit words of information or data which follows the Record Type field of the record. This field is one byte, represented as two hexadecimal characters. The maximum value of the Record Length field is hexadecimal 'FF' or 255.

Load Offset

Each record has a Load Offset field which specifies the 16‐bit starting load offset of the data words, therefore this field is only used for Data Records (if the words are loaded as bytes, the address needs to be doubled). In other records where this field is not used, it should be coded as four ASCII zero characters (“0000” or 0x30303030). This field one 16‐bit word, represented as four hexadecimal characters.

Record Type

Each record has a Record Type field which specifies the record type of this record. The Record Type field is used to interpret the remaining information within the record. This field is one byte, represented as two hexadecimal characters. The encoding for all the current record types are: 0

Data Record

1

End of File Record

5

Execution Start Address Record

Data

Each record has a variable length Data field, it consists of zero or more 16‐bit words encoded as set of 4 hexadecimal digits, most significant digit first. The interpretation of this field depends on the Record Type field.

Checksum

Each record ends with a Checksum field that contains the ASCII hexadecimal representation of the two's complement of the 8‐bit bytes that result from converting each pair of ASCII hexadecimal digits to one byte of binary, from and including the Record Length field to and including the last byte of the Data field. Therefore, the sum of all the ASCII pairs in a record after converting to binary, from the Record Length field to and including the Checksum field, is zero.

### Data Record
(8‐, 16‐ or 32‐bit formats)

Record Mark (“:”)

Record Length

Load Offset

Record Type

Data

Check sum

The Data Record provides a set of hexadecimal digits that represent the ASCII code for data bytes that make up a portion of a memory image.

The contents of the individual fields within the record are:

Record Mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains two ASCII hexadecimal digits that specify the number of 16‐bit data words in the record. The maximum value is 255 decimal.

Load Offset

This field contains four ASCII hexadecimal digits representing the word address at which the first word of the data is to be placed. (For an exquivalent bytes address, double it.)

Record Type

This field contains 0x3030, the hexadecimal encoding of the ASCII character “00”, which specifies the record type to be a Data Record.

Data

This field contains sets of four ASCII hexadecimal digits, one set for each 16‐bit data word, most significant digit first.

Checksum

This field contains the check sum on the Record Length, Load Offset, Record Type, and Data fields.

### Execution Start Address Record
Record Mark (“:”)

Record Length (4)

Load Offset (0)

Record Type (5)

EIP (4 bytes)

Check sum

The Execution Start Address Record is used to specify the execution start address for the object file. This is where the loader is to jump to begin execution once the hex load is complete.

The Execution Start Address Record can appear anywhere in a hexadecimal object file. If such a record is not present in a hexadecimal object file, a loader is free to assign a default execution start address.

The contents of the individual fields within the record are:

Record mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record length

The field contains 0x3032, the hexadecimal encoding of the ASCII characters “02”, which is the length, in bytes, of the EIP register content within this record.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters “0000”, since this field is not used for this record.

Record Type

This field contains 0x3035, the hexadecimal encoding of the ASCII character “05”, which specifies the record type to be a Start Address Record.

EIP

This field contains eight ASCII hexadecimal digits that specify the address. The field is encoded big‐endian (most significant digit first).

Checksum

This field contains the check sum on the Record length, Load Offset, Record Type, and EIP fields.

### End of File Record
This shall be the last record in the file.

Record Mark (“:”)

Record Length (0)

Load Offset (0)

Record Type (1)

Check sum (0xFF)

The End of File Record specifies the end of the hexadecimal object file.

The contents of the individual fields within the record are:

Record mark

This field contains 0x3A, the hexadecimal encoding of the ASCII colon (“:”) character.

Record Length

The field contains 0x3030, the hexadecimal encoding of the ASCII characters “00”. Since this record does not contain any Data bytes, the length is zero.

Load Offset

This field contains 0x30303030, the hexadecimal encoding of the ASCII characters “0000”, since this field is not used for this record.

Record Type

This field contains 0x3031, the hexadecimal encoding of the ASCII character “01”, which specifies the record type to be an End of File Record.

Checksum

This field contains the check sum an the Record Length, Load Offset, and Record Type fields. Since all the fields are static, the check sum can also be calculated statically, and the value is 0x4646, the hexadecimal encoding of the ASCII characters “FF”.

### Size Multiplier
In general, binary data will expand in sized by approximately 2.3 times when represented with this format.

## EXAMPLE
Here is an example INHX16 file. It contains the data “Hello, World” to be loaded at address 0.

```
:0700000065486C6C2C6F5720726F646CFF0AA8
:00000001FF
```

## COPYRIGHT
srec_cat version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_cat program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_cat -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_cat -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_logisim(5)

summary: format Logisim EPROM load files

text:
# srec_logisim(5)

## NAME
srec_logisim - format Logisim EPROM load files

## DESCRIPTION
The file format used for image files is intentionally simple; this permits you to write a program, such as an assembler, that generates memory images that can then be loaded into memory. As an example of this file format, if we had a 256‐byte memory whose first five bytes were 2, 3, 0, 20, and -1, and all subsequent values were 0, then the image would be the following text file.

v2.0 raw 02 03 00 14 ff

The first line identifies the file format used (currently, there is only one file format recognized). Subsequent values list the values in hexadecimal, starting from address 0; you can place several such values on the same line. Logisim will assume that any values unlisted in the file are zero. The image file can use run‐length encoding; for example, rather than list the value 00 sixteen times in a row, the file can include 16*00 rather than repeat 00 sixteen times. Notice than the number of repetitions is written in base 10. Files produced by Logisim will use run‐length encoding for runs of at least four values

### Size Multiplier
In general, binary data will expand in sized by approximately 2.95 times when represented with this format.

### Commentary
This format is particularly deficient.

•

The is no way for changing address in‐flight. And therefore the format can't have holes in the data.

•

There are no checksums, or any other error checking.

•

There is no provision for a comment header, as distinct to the “v2.0 raw” magic number.

•

There is no provision for an execution start adddress.

## SEE ALSO
http://ozark.hendrix.edu/~burch/logisim/docs/2.3.0/guide/mem/menu.html

## COPYRIGHT
srec_logisim.5 version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_logisim.5 program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_logisim.5 -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_logisim.5 -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au


title: srec_mem(5)

summary: Lattice Memory Initialization format

text:
# srec_mem(5)

## NAME
srec_mem - Lattice Memory Initialization format

## DESCRIPTION
A Lattice Memory Initialization format (.mem), by Lattice Semiconductor, file is an ASCII text file that consists of a header followed by lines of memory data.

### Syntax
The data must be in one of the following formats: Bin (binary), Hex (hexadecimal), or Address‐Hex (described below).

For hexadecimal values, both upper and lower case can be used. If the data has fewer bits than the specified data width, the most significant bits are filled with 0. Any address not specified will be filled with 0.

Comments can be added at any point after the header (defined below) by starting the comment with a pound sign (#) or two slashes (//). The comment then includes everything to the end of the line. Comments may be added to any of the data, but never add comments to the header.

### Header
A .mem file starts with a header, which declares the file format, memory size, and address and data display radix for Memory Generator. The syntax of the header is:

```
#Format=Bin | Hex | AddrHex
#Depth=1 to 65536
#Width=1 to 256
#AddrRadix=index‐number
#DataRadix=index‐number
#Data
```

The index‐number can be one of the following numbers. AddrRadix and DataRadix can have different values.

```
Binary: 0
Octal: 1
Decimal: 2
Hexadecimal: 3
```

For example, the following header says the .mem file is using the binary format for a 32x8 memory. When displayed in Memory Generator, the address will be shown in hexadecimal and the data will be shown in binary.

```
#Format=Bin
#Depth=32
#Width=8
#AddrRadix=3
#DataRadix=0
#Data
```

### Bin and Hex Formats
The data is represented in binary or hexadecimal format. Each line of data specifies the contents for one memory location, starting with address 0. That is, the first line is for address 0, the second line is for address 1, and so on. For each line, the data is interpreted as least significant bit on the right.

For example, in the Bin format, the following lines will initialize address 0 to “00011011”, address 1 to “11111010” (assuming it is a 32x8 memory).

```
# for a 32x8 memory
11011
11111010
```

In the Hex format, the following lines will initialize address 0 to “003B”, address 1 to “FB0A” (assuming it is a 32x16 memory).

```
# for a 32x16 memory
3B
FB0A
```

### AddrHex
The data is represented in hexadecimal format. Each line consists of an address followed by a colon and then any number of data words, separated by spaces:

address: data data> data...

The data will be applied starting at <address> and filling in sequentially from there. For example:

```
A0:03 F3 3E 4F
B2:3B 9F
```

will initialize A0 with 03, A1 with F3, A2 with 3E, A3 with 4F, B2 with 3B, and B3 with 9F. The other addresses will be initialized to 0. So A4 through B1 will be set to 0.

### See Also

```
http://help.latticesemi.com/docs/webhelp/eng/wwhelp/wwhimpl/common/html/wwhelp.htm#href=Design%20Entry/memory_initialization_file.htm#1371843&single=true
```

### Size Multiplier
The size multiplier depends on the width selected. As files grow larger, their size multipliers will approach those in the table, from above.

Width

Linux

Windows

8

2.96

3.0

16

2.47

2.5

32

2.25

2.28

64

2.13

2.15

### Byte Order
This format is implicitly big‐endian. Use a -byte‐swap filter if you need something different.

## COPYRIGHT
srec_mem version 1.64

Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

The srec_mem program comes with ABSOLUTELY NO WARRANTY; for details use the 'srec_mem -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'srec_mem -VERSion License' command.

## MAINTAINER
Scott Finneran

E‐Mail:

scottfinneran@yahoo.com.au

Peter Miller

E‐Mail:

pmiller@opensource.org.au