HERMIT(1)

NAME
hermit - flash-aware downloader and terminal program

SYNOPSIS
hermit [GENERAL OPTIONS] [COMMAND [COMMAND OPTIONS]] ...

DESCRIPTION

Hermit is a flash downloader/boot loader combination. The Hermit package consists of a single host-side downloader program, `hermit' (which is documented in this manual page), along with a target-specific boot loader for each supported target.

Hermit uses a target-provided memory map, allowing the host side to download to an arbitrary target without prior configuration. The memory map includes flash erase blocking information such as sizes, addresses, and locking characteristics. The host-side downloader is aware of the programming characteristics of flash, and will issue erase and program commands as needed to download an image. Download images will automatically be fragmented so as not to span multiple flash erase blocks with a single program command.

Hermit is designed as a downloader, not as a system monitor. All operation on the target is polling (not interrupt driven), and it is not possible to return to the target boot loader after another system has been loaded.

The target-side loader relocates itself to RAM before running, allowing it to reprogram its own image in Flash-ROM.

  COMMANDS
At least one of the following commands must be given on the command line. More than one command may be given; for example, the download command may be given more than once in order to download two files to different memory areas using a single connection to the target. Commands are executed in the order given; `download' followed by `terminal' will complete the download before entering terminal mode. Command options (see section below) apply to the preceding command.

download
    Download a file. You must specify an input file, and either an address or a named memory region. If a named memory region is specified, the given input file must fit entirely within the region. An address allows the input file to span multiple memory regions, although the download range may not span gaps in the memory map.

    Domnloads are checked for integrity using the CRC-32 checksum.

help
    Display command line help.

map Display the target's memory map.

terminal
    Enter interactive terminal mode.

upload
    Upload a file (not yet implemented).

  GENERAL OPTIONS
These options affect hermit operation in general, not the specific command they follow.

--ethernet
    Use Ethernet to communicate with the target. The default is to use only serial communications. Note that even with this option, the control channel uses a serial link; Ethernet is not a replacement for serial.

-Nifname, --netif=ifname
    Specify a network interface to be used for Ethernet communications. The default interface is eth0.

-Pportname, --port=portname
    Specify a serial port to be used for serial communications. The default port is /dev/ttyS0.

--remote-mac=mac
    Specify a MAC address for the remote end of the communication. This option may not be needed; an Ethernet-capable target may already have a unique MAC address. The address is specified using standard Ethernet notation, i.e. ``aa:bb:cc:dd:ee:ff''.

    If you need a temporary Ethernet address, just pick one at random. Unfortunately, there is no reserved internal-use MAC address range, as there is with IP network addressing. Make sure the address you pick doesn't have the high bit of the second octet (the multicast bit) set; it's probably safest to just use 00 as the first octet.

    Don't distribute anything with a MAC address which you didn't get from the IEEE.

-v, --verbose
    Generate verbose output.

-V, --version
    Print version string and exit.

  DOWNLOAD COMMAND OPTIONS
These options apply only to the preceding download command.

-aaddress, --address=address
    Specify a memory address (pointer) on the target.

--force-locked
    Force writes to flash blocks marked as locked by the target. Note that this may not actually enable writes (you'll sometimes have to change a jumper or a GPIO output to set the /WP line); this option just turns off the locked-block safety feature in the hermit downloader.

-ifilepath, --input-file=filepath
    Specify an input file for download. Hermit cannot download from standard input, since it needs to know the file size before beginning the download process.

-rname, --region=name
    Specify a named memory region on the target. The list of memory regions is retrieved from the target; to display the list, use the map command.

  MAP COMMAND OPTIONS
These options apply only to the preceding map command.

--anonymous-regions
    Show anonymous memory regions (regions without names) in the memory map. Anonymous regions are usually omitted from output, as they typically represent flash erase blocks.

  ENVIRONMENT VARIABLES
Some command functionality can be duplicated by setting environment variables. Values specified on the command line override values provided by the environment.

HERMIT_NETIF
    Sets network interface for Ethernet downloads; identical to `--netif'.

HERMIT_PORT
    Sets port (tty) for serial communications; identical to `--port'.

BUGS

•   Serial downloads take place at console speed (9600 baud). Incentive to fix this is low given the existence of Ethernet download.

•   Ethernet retransmits don't really work, and Ethernet polling never times out.

•   See the BUGS section in the distribution for more.

NOTES
Bootstrapping Hermit onto a new evaluation board can be a tricky process and can involve another, simpler bootstrap download program. See the README.<target> file in the Hermit documentation directory for instructions on this process.

AUTHOR
Mike Touloumtzis <miket@bluemug.com>