/
embed.1
211 lines (150 loc) · 6.14 KB
/
embed.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
.\" Manpage for embed
.\" Contact howe.r.j.89@gmail.com to correct errors or typos.
.TH embed 1 "17 Jun 2018" "0.1.0" "embed man page"
.SH NAME
embed \- embed virtual machine and eForth image
.SH SYNOPSIS
embed [-hqtTa] -i in.blk -o out.blk -I file.fth -O file.txt file.fth
.SH DESCRIPTION
A simple and compact Forth Virtual machine, derived from the H2 CPU
(from <https://github.com/howerj/forth-cpu>, which in turn derives from the J1
CPU). The virtual machine includes a built in eForth image which can be used
in lieu of loading one off of disk.
.SH OPTIONS
No options are mandatory.
.TP
.B -i in.blk
Select initial input block, this block will be loaded off of disk and used as
memory for the Virtual machine, maximum block size is 65536 bytes, or 32768
cells. If no input block is specified then an internal initial block will be
used instead, which contains a fully working eForth interpreter.
.TP
.B -o out.blk
Select the output block, the virtual machine is capable of saving sections of
its memory to disk and this option allows the user to specify which file the
memory is saved to. If no file is specified then any attempts by the virtual
machine to save memory to disk will fail.
.TP
.B -h
Print a help message and exit indicating failure.
.TP
.B -q
Turn quite mode on. It is up to the virtual machine image to respect this
option if it is given, this option just sets the bit to indicate a quite mode.
.TP
.B -t
Turn tracing on, this sets an option to turn on tracing in the virtual machine.
This will do anything if the library has been compiled with the NDEBUG macro
defined.
.TP
.B -I
Set input file. This replaces the standard input as the input file.
.TP
.B -O
Set output file. This replaces the standard output as the output file.
.TP
.B -T
Run the built in self tests, returning zero on success, and non-zero on
failure. The test results are printed to the screen.
.TP
.B file.fth
This option supplies a file to read from, by default the virtual machine
will read from stdin(3) if a file is not given. Multiple files can be
specified, but if a file is specified input will not be read from stdin(3).
.SH EXAMPLES
.TP
.B ./embed
This will make 'embed' use the built in virtual machine image, saving will
fail, and stdin(3) will be used as input.
.TP
.B ./embed -o out.blk
Set output block to 'out.blk', any changes using the save instruction will
be written to this file.
.TP
.B ./embed -i in.blk
Set the initial VM image to 'in.blk'
.TP
.B
Read from the standard input stream, or the file specified by '-I', after
processing the file list.
.TP
.B ./embed -i in.blk -o out.blk file.fth
.SH EFORTH
This manual page is not the right medium to describe eForth, the language
implemented in the default image loaded. eForth is a variant of Forth designed
to be portable and small. Forth is a stack based imperative programming with
minimal safety checks and footprint, it uses Reverse Polish Notation to
organize input and output arguments, allows for Reflection (the language can
inquire about its run time), has incremental compilation, and is extensible.
The default image includes the Forth interpreter, a simple editor, a
primitive disassembler, and CRC checks.
If you run the default image you should be greeted with a prompt that looks
something like this:
.TP
.B eFORTH v1984
.B 5290 11094
You can starting typing things in, the eForth interpreter gets its input a line
at a time and will print out 'ok' after a line has been successfully
interpreted.
Some examples:
.TP
.B 2 2 + .
This performs the simple sum '2+2' and it prints the result, you should see
the line:
.TP
4 ok
Printed out.
.TP
.B : hello ." Hello, World!" cr ;
.B hello
.TP
.B words
Displays all of the functions (Forth calls functions words) in the Forth
dictionary (the dictionary is a list of all defined words) in the currently
loaded vocabularies.
.TP
.B see words
The word 'see' is the Forth disassembler, it takes the next word, 'words' and
shows you how assembly for it. You can use 'see' to work out how words work
without the source code.
.TP
.B save
Save the current image to disk, this will fail if you do not specify an
output file when you ran the interpreter with the '-o' option.
.SH COMPILATION
Compilation requires a C compiler that supports the C99 standard at minimum,
if you have make installed you can type 'make' to build the interpreter, if
you do not:
.B cc -std=c99 main.c embed.c image.c util.c -o embed
.SH LIBRARY API AND PORTING
The library API itself is described in detail in the header for the library.
The goal of the library, and the virtual machine, is too be as flexible as
possible. It achieves flexibility by allowing the library user to pass in
callbacks to change the behavior of the Input/Output channels (of which there
are three available to the virtual machine), and also by allowing the user to
pass in a callback that can be used to do arbitrary things by pushing and
pulling data to and from the virtual machines stack.
It should be possible to port to most platforms quite easily, including various
microcontrollers (it might even be possible to do so just by providing the
right callbacks depending on your Board Support Package).
The header file describes what each function does, and the repository contains
example programs. The library should be simple to use, and if it is not please
contact the author to complain about it. Do not be afraid to hack around with
the virtual machine to get it to do what you want either, the program is
relatively short and should be easy to understand even if the code is dense.
.SH EXIT STATUS
This command returns zero on success and non zero on failure.
.SH SEE ALSO
For more information, see
.B https://github.com/howerj/embed
which contains the original program source.
.SH BUGS
For any bugs, contact the author. The eForth image is not standards compliant
with ANS Forth or any other Forth standard, however it does look to not
deviate if possible so if you find any simple changes please email me.
.SH AUTHOR
Richard James Howe (howe.r.j.89@gmail.com)
.SH COPYRIGHT
The embed program is licensed under the MIT license, Copyright (c) 2018,
Richard James Howe. The same applies to the images and source code to generate
those images.