mescc-tools/docs/hex2.1

.\"Made with Love
.TH hex2 1 "JULY 2019" Linux "User Manuals"
.SH NAME

hex2 - The trivially bootstrappable linker that is designed to be introspectable by humans

.SH SYNOPSIS
.na

hex2 --architecture ARCHITECTURE --base-address ADDRESS --file FILE [--output FILE [--non-executable]]

.SH DESCRIPTION

hex2 is designed to allow humans to write elf and other binary
files by hand in a format that allows comments and ease of understanding.
.br

At its core is read 2 hex characters add them together
and output a single byte. You can override this and use
binary or octal input if you so desire, using the --octal
or --binary option.
.br
If no output file is specified the output will be send to standard out.
By default the file will be executable unless the option:
--non-executable is also passed.
.br

The supported ARCHITECTURES are as follows: knight-native,
knight-posix, x86, amd64, armv7l and aarch64.
If you fail to specify an architecture, the default of knight-native
will be used.
.br
The base address for which the binary is to be loaded into memory
and thus the relative and absolute pointers should be based,
is passed via --base-address if it is not provided the default
value of ZERO will be assumed.
.br

hex2 also support labels in the :LABEL format and relative
and absolute pointers to those labels in 8, 16, 24 or 32bit sizes.
!LABEL, @LABEL, ~LABEL and %LABEL for 8, 16, 24 and 32bit relative addresses
respectively and $LABEL and &LABEL for 16 and 32bit absolute
addresses respectively.
Should you wish to specify the bit and byte encoding of the
addresses to match your target --big-endian and --little-endian

On architectures that require word alignment the < and ^
characters have a special meaning; particularly pad to word
and use word base address calculation rather than standard
byte based address calculation; generally seen in the form:
^~LABEL EB for calls in ARM

.SH EXAMPLES

Typically, hex2 will be called in scripts used in bootstrapping
.br
# hex2 -f ELF-armv7l.hex2 -f cc.hex2 --little-endian --architecture armv7l --base-address 0x10000 -o cc
.br

.SH COMPATIBILITY

hex2 is compatible with all Turing complete machines;
even the ones that try to be Turing complete -1

.SH AUTHORS
Jeremiah Orians <Jeremiah@pdp10.guru>
.br
Jan (janneke) Nieuwenhuizen <janneke@gnu.org>

.SH COPYRIGHT
Copyright 2016-2019 Jeremiah Orians <Jeremiah@pdp10.guru>
.br
Copyright 2017 Jan Nieuwenhuizen <janneke@gnu.org>
.br
License GPLv3+.

.SH "SEE ALSO"
M1(1), blood-elf(1), kaem(1), syscalls(2)