Onramp Hexadecimal is a simple language used to implement binary files in plain text hexadecimal with comments. This makes it possible to handwrite machine code and bytecode in clear, maintainable, auditable text.
A hex conversion tool is required to strip comments and convert the text to binary. There are many implementations in platform/hex/. The language they implement is described in this document.
An Onramp Hexadecimal file must be in plain text. All non-comment data is in ASCII.
In our Onramp sources we stick to the printable ASCII characters plus whitespace, although the tools should be able to handle any non-null bytes in comments. For maximum compatibility you should use UTF-8 if you want international characters in comments.
Bytes are specified as two hexadecimal characters. Characters can be in lowercase or uppercase.
48 65 6c 6C 6f
An Onramp Hex tool converts the above to the five bytes "Hello".
The ; character starts a line comment. The rest of the line until the next carriage return or line feed character is ignored.
; this is a comment
48 65 6c 6c 6f ; "Hello"A # character is intended to be used for debug info. No debug directives are currently defined for hex files. Currently all hex tools treat this as another kind of line comment.
(The hex/c89 tool generates line and symbol debug info without the need for debug directives in the input file.)
The space, horizontal tab, line feed and carriage return characters are considered whitespace. They are ignored (except that line endings end a comment.)
48 65 6c 6c 6f ; hex bytes can be spaced out
48656C6C6F ; or compressed
48 ; or separated in lines
65
6C
6C
6F
48656c ; or indented
6C6F ; with tabs or spaces
An address assertion is a special kind of comment that a hex tool can use to verify the current address.
The @ character starts an address assertion. It is followed by 0x and a hexadecimal address. A hex tool that supports address assertions verifies that the value of the address assertion matches the number of bytes that have been emitted so far.
The address must be followed by a line ending or by horizontal whitespace. After horizontal whitespace, the rest of the line is treated as a comment, except that it may be used for the generation of debug info.
@0x100 hello
; "Hello"
48 65 6c 6c 6f
@0x105
@0x105 =main (comment comment comment)
; ...
; ...
; ...
@0x140Address assertions are optional. Implementations of hex can instead treat the entire line starting from @ as a comment, the same as ; and #.
When generating debug info, if an address assertion is followed by an identifier on the same line, the hex/c89 tool will use this as the symbol name for subsequent bytes. Onramp hexadecimal bytecode files typically start each symbol with an address assertion containing the name of the symbol being defined, as seen in the example above.
This allows the debugger VM to provide rich stack traces and location information even for handwritten hexadecimal bytecode.
A backslash \ preceding a line feed or carriage return (i.e. at the end of a line) is forbidden. This is the case for all lines including comments and address assertions.
(The reason for this restriction is that some line-reading tools (such as the POSIX read command) may merge lines with trailing backslashes while others may not. This restriction removes the need to define whether a comment continues past an escaped newline.)
Given an input file like this:
; start of the file
@0x0 hello
48 65 6c 6c 6f ; Hello
20 ; <space>
# another comment
@0x6 world
776F726C64 # world
21 # !
@0x0000000C
0A ; line feed
@0x0D endThe hex tool converts the above to the following 13 bytes including a trailing line feed:
Hello world!