git @ Cat's Eye Technologies BefOS / 56e7b48
Merge READMEs and TODO. Give it a DOS-friendly file extension. --HG-- rename : README.markdown => README.md Chris Pressey 8 years ago
4 changed file(s) with 274 addition(s) and 271 deletion(s). Raw diff Collapse all Expand all
+0
-10
README.markdown less more
0 BefOS - an Operating System for the Linearly Challenged
1 =======================================================
2
3 This is the reference distribution for BefOS, a toy Befunge-themed OS
4 written in 8086 assembler in the NASM format.
5
6 See the file `README.txt` in the `doc` directory for more information.
7
8 The contents of this distribution have been placed into the public
9 domain; see the file `UNLICENSE` for more information.
0 BefOS
1 =====
2
3 This is the reference distribution for BefOS, a toy Befunge-themed OS
4 written in 8086 assembler in the NASM format.
5
6 The contents of this distribution have been placed into the public
7 domain; see the file `UNLICENSE` for more information.
8
9 Note that this README is based on what was originally written for the
10 BefOS project way back in the 20th century. Therefore parts of it may
11 be crufty, outdated, and generally unfashionable. Probably best to
12 take it all with a grain of salt.
13
14 BefOS - an Operating System for the Linearly Challenged
15 -------------------------------------------------------
16
17 Version 0.9 revision 2012.0827
18
19 This work by Chris Pressey of Cat's Eye Technologies
20 has been placed into the public domain (see UNLICENSE.)
21
22 ,---------------------------------------------------.
23 | * WARNING! * CAUTION * PROCEED AT YOUR OWN RISK * |
24 | |
25 | * THIS PRODUCT IS PROVIDED "AS IS" * |
26 | |
27 | * CAT'S EYE TECHNOLOGIES CAN NOT BE HELD LIABLE * |
28 | * FOR ANY DAMAGES RESULTING FROM ITS USE * |
29 `---------------------------------------------------'
30
31 What is it?
32 -----------
33
34 BefOS is a toy OS written in 100% 8086 assembler. It requires the
35 following hardware (or a decently emulated version thereof):
36
37 Processor: 100% Intel 8086+ Compatible
38 BIOS: 100% IBM PC Compatible
39 Video: 100% VGA Compatible
40 Keyboard: 100% Standard 101/102-Key Compatible
41 RAM: 640K base, 8M extended
42 Storage: 1.44M floppy drive 0 (A:)
43
44 BefOS was originally written in Borland's Turbo Assembler format,
45 but this version has been translated to use the free assembler
46 NASM.
47
48 Booting into BefOS
49 ------------------
50
51 Using Bochs or some other emulator: point the emulated A: drive of
52 the emulator at the file disk/befos.flp, and boot from the floppy.
53 The 'test' target in the top-level (and disk/) Makefile will run
54 Bochs automatically on this floppy image.
55
56 Using Windows: run BEKERNEL.COM. (Note that I'm not sure if this
57 works anymore in the NASM version; I haven't tried it. You still
58 need a blank floppy in drive A:, though.)
59
60 For real: install the floppy image (disk/befos.flp) onto a blank,
61 1.44M floppy disk, using a tool such as 'fdimage.exe' (which is
62 available at ftp://ftp.freebsd.org/pub/FreeBSD/tools/). Then
63 reset your computer and boot off that floppy.
64
65 Using BefOS
66 -----------
67
68 Once you've booted into BefOS, you'll see a blue screen with some stuff
69 on it.
70
71 Here is a quick-and-dirty guide to the top line of this display:
72
73 B the BefOS 'logo.'
74 (light) yellow = working, green = worked, red = failed
75 (4 hex digits) amount of base memory available, in K
76 (4 hex digits) amount of extended memory available, in K
77 (green bar)
78 (4 hex digits) link to next cluster of current cluster
79 (4 hex digits) link to previous cluster of current cluster
80 (4 hex digits) link to application cluster of current cluster
81 (4 hex digits) link to colour cluster of current cluster
82 (4 hex digits) link to help cluster of current cluster
83 (green bar)
84 (16 OEM chars) description of current cluster
85 (green bar)
86 (4 hex digits) value of last keystroke detected
87 (2 hex digits) value of current byte under cursor
88 (4 hex digits) current cluster number, starts at 0
89
90 And here are some key bindings: (NYI=Not Yet Implemented):
91
92 PgUp Up One Cluster
93 PgDn Down One cluster
94
95 Ctrl-PgUp Link to Previous Cluster (header)
96 Ctrl-PgDn Link to Next Cluster (header)
97 F1 Link to Help Cluster (header)
98
99 Up Move Pointer Up One Row
100 Down Move Pointer Down One Row
101 Left Move Pointer Left One Column
102 Right Move Pointer Right One Column
103
104 ^2 (^@) Write 0
105 ^A to ^Z Write 1 - 26
106 ESC Write 27
107 ^\ Write 28
108 ^] Write 29
109 ^6 (^^) Write 30
110 ^- (^_) Write 31
111 Space Write 32
112 !..~ Write 33 - 126
113 Ctrl-Bkspc Write 127
114
115 Alt-L Load (refresh from disk)
116 Alt-R Run (if AA==ffff, executes machine code)
117
118 F4 Change Properties (Header)
119 Alt-- Delete Properties (Header)
120 Alt-= Initialize Properties (Header)
121
122 Alt-M show More data on screen
123 Alt-N show less data on screeN
124
125 Alt-G Go to cluster number
126
127 NYI*1 Alt-E Edit: allow writes
128 Alt-U fill cluster Uniformly with current byte
129 Alt-C Copy cluster data & header to clipboard
130 Alt-P Paste cluster data & header from clipboard
131 Alt-H toggle High bit
132 Alt-S Save (commit changes to data & header to disk)
133
134 Alt-Q Quit (MS-DOS only)
135 *2 Alt-I Install cluster from file (MS-DOS only)
136
137 *1: writes are always allowed in this version so BE CAREFUL WITH ALT-S.
138 *2: type the filename into the start of the cluster buffer and
139 terminate it with a null (Ctrl-2)
140
141 Cluster Format
142 --------------
143
144 Each cluster has a 'header' which is in fact stored in the LAST
145 48 bytes of the second cluster. The first 2000 bytes are data.
146 The header is structured thus:
147
148 +------------------------------------------------+
149 |VVNNPPAACCHHxxxxxxxxxxxxxxxxxxxxDDDDDDDDDDDDDDDD|
150 +------------------------------------------------+
151
152 VV = word indicating header type.
153
154 bef0 indicates standard BefOS header, the only type supported.
155
156 NN = word containing the cluster number of the next cluster.
157
158 0000 indicates that there is no next cluster.
159
160 PP = word containing the cluster number of the previous cluster.
161
162 0000 indicates that there is no previous cluster.
163
164 AA = word containing the cluster number of the first cluster of
165 the application for which this is a document.
166
167 0000 indicates that there is no special application for this
168 generic document.
169
170 ffff indicates that this IS an application written in
171 x86 machine code.
172
173 CC = word containing the cluster number of
174 this cluster's colour cluster.
175
176 0000 indicates that this cluster is monochrome.
177
178 HH = 2 bytes containing the cluster number of
179 this cluster's help-cluster.
180
181 0000 indicates that this cluster is helpless.
182
183 xxxxxxxxxxxxxxxxxxxx = 20 bytes reserved.
184
185 DDDDDDDDDDDDDDDD = 16 bytes ASCII description e.g. "Seismology Now"
186
187
188
189 ------------------------------------------------------------------
190
191 But the following is more like what I would like it to be...
192
193 ------------------------------------------------------------------
194
195 First, we say that 1 "screen" is 4096 bytes:
196 80x25char + 80x25colour + 96 bytes header.
197 A "tableau" is a set of 80x25 screens = 2000 * 4K = 8M.
198 There is one tableau on the computer which maps to it's extended RAM.
199
200 One 1.44M floppy disk can contain six columns = 150 screens.
201
202 Header:
203
204 +------------------------------------------------+
205 |VVAAxxxxxxxxxxxxDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD|
206 |DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD|
207 +------------------------------------------------+
208
209 VV = word indicating header type.
210
211 bef0 indicates standard BefOS header, the only type supported.
212
213 AA = word containing the cluster number of the first cluster of
214 the application for which this is a document.
215
216 0000 indicates that there is no special application for this
217 generic document.
218
219 ffff indicates that this IS an application written in
220 x86 machine code.
221
222 xxxxxxxxxxxx = 12 bytes reserved.
223
224 DD..DD = 80 bytes ASCII description.
225
226
227 Building BefOS
228 --------------
229
230 BefOS can be built on FreeBSD (and probably Linux and Cygwin.)
231 Just type 'make clean all' from the top level to build it all.
232
233 Here is what is in the various directories:
234
235 bin/
236 amalgam8 Constructs a boot disk image from BefOS objects
237 extract8 Extracts BefOS objects from a boot disk image
238 txt2page Turns a text file into a BefOS object file
239 mkbfinc.pl Used during build to generate list of API calls
240 disk/ Contains bootable BefOS boot disk images
241 obj/ Contains BefOS objects that will be amalgamated
242 src/ Contains source code for BefOS:
243 apps/ Source code for the BefOS applications installed
244 boot/ Source code for the boot disk's boot block
245 inc/ Include files shared by many BefOS object sources
246 kernel/ Source file for the core components of BefOS
247 page/ Misc files that become BefOS pages on the disk
248 tools/ Source code for the util programs put in bin/
249 turbo/ The original Turbo Assembler sources for BefOS
250
251
252 Putative TODO list
253 ------------------
254
255 * Clean up the code base
256 * Rebrand the thing because I don't like the name BefOS
257 * Update the README
258 * Document the entry points
259 * Abstract "main loop" out of bekernel.s, into editor.s
260 * Translate all tools to Python? Or at least Perl.
261 * Switch to unreal mode on boot
262 * Allow editing memory pages
263 * "current page" also needs "current device"
264 * can be just the base RAM for now
265 * Implement an actual VM for it (likely something rather befungeoid, but
266 not Befunge)
267 * Execute from "current exection page"
268 * If "current execution page" is "current displayed page",
269 also update cursor while executing
270 * Rewrite Editor in the befungeoid VM?
271 * Fix syscalls
272 * Really, you should only be able to syscall a Beeble (=Befunge-05)
273 instruction
+0
-236
doc/README.txt less more
0 BefOS - an Operating System for the Linearly Challenged
1 =======================================================
2
3 Version 0.9 revision 2012.0827
4
5 This work by Chris Pressey of Cat's Eye Technologies
6 has been placed into the public domain (see UNLICENSE.)
7
8 ,---------------------------------------------------.
9 | * WARNING! * CAUTION * PROCEED AT YOUR OWN RISK * |
10 | |
11 | * THIS PRODUCT IS PROVIDED "AS IS" * |
12 | |
13 | * CAT'S EYE TECHNOLOGIES CAN NOT BE HELD LIABLE * |
14 | * FOR ANY DAMAGES RESULTING FROM ITS USE * |
15 `---------------------------------------------------'
16
17 What is it?
18 -----------
19
20 BefOS is a toy OS written in 100% 8086 assembler. It requires the
21 following hardware (or a decently emulated version thereof):
22
23 Processor: 100% Intel 8086+ Compatible
24 BIOS: 100% IBM PC Compatible
25 Video: 100% VGA Compatible
26 Keyboard: 100% Standard 101/102-Key Compatible
27 RAM: 640K base, 8M extended
28 Storage: 1.44M floppy drive 0 (A:)
29
30 BefOS was originally written in Borland's Turbo Assembler format,
31 but this version has been translated to use the free assembler
32 NASM.
33
34 Booting into BefOS
35 ------------------
36
37 Using Bochs or some other emulator: point the emulated A: drive of
38 the emulator at the file disk/befos.flp, and boot from the floppy.
39 The 'test' target in the top-level (and disk/) Makefile will run
40 Bochs automatically on this floppy image.
41
42 Using Windows: run BEKERNEL.COM. (Note that I'm not sure if this
43 works anymore in the NASM version; I haven't tried it. You still
44 need a blank floppy in drive A:, though.)
45
46 For real: install the floppy image (disk/befos.flp) onto a blank,
47 1.44M floppy disk, using a tool such as 'fdimage.exe' (which is
48 available at ftp://ftp.freebsd.org/pub/FreeBSD/tools/). Then
49 reset your computer and boot off that floppy.
50
51 Using BefOS
52 -----------
53
54 Once you've booted into BefOS, you'll see a blue screen with some stuff
55 on it.
56
57 Here is a quick-and-dirty guide to the top line of this display:
58
59 B the BefOS 'logo.'
60 (light) yellow = working, green = worked, red = failed
61 (4 hex digits) amount of base memory available, in K
62 (4 hex digits) amount of extended memory available, in K
63 (green bar)
64 (4 hex digits) link to next cluster of current cluster
65 (4 hex digits) link to previous cluster of current cluster
66 (4 hex digits) link to application cluster of current cluster
67 (4 hex digits) link to colour cluster of current cluster
68 (4 hex digits) link to help cluster of current cluster
69 (green bar)
70 (16 OEM chars) description of current cluster
71 (green bar)
72 (4 hex digits) value of last keystroke detected
73 (2 hex digits) value of current byte under cursor
74 (4 hex digits) current cluster number, starts at 0
75
76 And here are some key bindings: (NYI=Not Yet Implemented):
77
78 PgUp Up One Cluster
79 PgDn Down One cluster
80
81 Ctrl-PgUp Link to Previous Cluster (header)
82 Ctrl-PgDn Link to Next Cluster (header)
83 F1 Link to Help Cluster (header)
84
85 Up Move Pointer Up One Row
86 Down Move Pointer Down One Row
87 Left Move Pointer Left One Column
88 Right Move Pointer Right One Column
89
90 ^2 (^@) Write 0
91 ^A to ^Z Write 1 - 26
92 ESC Write 27
93 ^\ Write 28
94 ^] Write 29
95 ^6 (^^) Write 30
96 ^- (^_) Write 31
97 Space Write 32
98 !..~ Write 33 - 126
99 Ctrl-Bkspc Write 127
100
101 Alt-L Load (refresh from disk)
102 Alt-R Run (if AA==ffff, executes machine code)
103
104 F4 Change Properties (Header)
105 Alt-- Delete Properties (Header)
106 Alt-= Initialize Properties (Header)
107
108 Alt-M show More data on screen
109 Alt-N show less data on screeN
110
111 Alt-G Go to cluster number
112
113 NYI*1 Alt-E Edit: allow writes
114 Alt-U fill cluster Uniformly with current byte
115 Alt-C Copy cluster data & header to clipboard
116 Alt-P Paste cluster data & header from clipboard
117 Alt-H toggle High bit
118 Alt-S Save (commit changes to data & header to disk)
119
120 Alt-Q Quit (MS-DOS only)
121 *2 Alt-I Install cluster from file (MS-DOS only)
122
123 *1: writes are always allowed in this version so BE CAREFUL WITH ALT-S.
124 *2: type the filename into the start of the cluster buffer and
125 terminate it with a null (Ctrl-2)
126
127 Cluster Format
128 --------------
129
130 Each cluster has a 'header' which is in fact stored in the LAST
131 48 bytes of the second cluster. The first 2000 bytes are data.
132 The header is structured thus:
133
134 +------------------------------------------------+
135 |VVNNPPAACCHHxxxxxxxxxxxxxxxxxxxxDDDDDDDDDDDDDDDD|
136 +------------------------------------------------+
137
138 VV = word indicating header type.
139
140 bef0 indicates standard BefOS header, the only type supported.
141
142 NN = word containing the cluster number of the next cluster.
143
144 0000 indicates that there is no next cluster.
145
146 PP = word containing the cluster number of the previous cluster.
147
148 0000 indicates that there is no previous cluster.
149
150 AA = word containing the cluster number of the first cluster of
151 the application for which this is a document.
152
153 0000 indicates that there is no special application for this
154 generic document.
155
156 ffff indicates that this IS an application written in
157 x86 machine code.
158
159 CC = word containing the cluster number of
160 this cluster's colour cluster.
161
162 0000 indicates that this cluster is monochrome.
163
164 HH = 2 bytes containing the cluster number of
165 this cluster's help-cluster.
166
167 0000 indicates that this cluster is helpless.
168
169 xxxxxxxxxxxxxxxxxxxx = 20 bytes reserved.
170
171 DDDDDDDDDDDDDDDD = 16 bytes ASCII description e.g. "Seismology Now"
172
173
174
175 ------------------------------------------------------------------
176
177 But the following is more like what I would like it to be...
178
179 ------------------------------------------------------------------
180
181 First, we say that 1 "screen" is 4096 bytes:
182 80x25char + 80x25colour + 96 bytes header.
183 A "tableau" is a set of 80x25 screens = 2000 * 4K = 8M.
184 There is one tableau on the computer which maps to it's extended RAM.
185
186 One 1.44M floppy disk can contain six columns = 150 screens.
187
188 Header:
189
190 +------------------------------------------------+
191 |VVAAxxxxxxxxxxxxDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD|
192 |DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD|
193 +------------------------------------------------+
194
195 VV = word indicating header type.
196
197 bef0 indicates standard BefOS header, the only type supported.
198
199 AA = word containing the cluster number of the first cluster of
200 the application for which this is a document.
201
202 0000 indicates that there is no special application for this
203 generic document.
204
205 ffff indicates that this IS an application written in
206 x86 machine code.
207
208 xxxxxxxxxxxx = 12 bytes reserved.
209
210 DD..DD = 80 bytes ASCII description.
211
212
213 Building BefOS
214 --------------
215
216 BefOS can be built on FreeBSD (and probably Linux and Cygwin.)
217 Just type 'make clean all' from the top level to build it all.
218
219 Here is what is in the various directories:
220
221 bin/
222 amalgam8 Constructs a boot disk image from BefOS objects
223 extract8 Extracts BefOS objects from a boot disk image
224 txt2page Turns a text file into a BefOS object file
225 mkbfinc.pl Used during build to generate list of API calls
226 disk/ Contains bootable BefOS boot disk images
227 obj/ Contains BefOS objects that will be amalgamated
228 src/ Contains source code for BefOS:
229 apps/ Source code for the BefOS applications installed
230 boot/ Source code for the boot disk's boot block
231 inc/ Include files shared by many BefOS object sources
232 kernel/ Source file for the core components of BefOS
233 page/ Misc files that become BefOS pages on the disk
234 tools/ Source code for the util programs put in bin/
235 turbo/ The original Turbo Assembler sources for BefOS
+0
-25
doc/TODO.txt less more
0 Putative todo list:
1
2 Clean up the code base
3 Rebrand the thing because I don't like the name BefOS
4 Update the README
5 Document the entry points
6 Abstract "main loop" out of bekernel.s, into editor.s
7 Translate all tools to Python? Or at least Perl.
8
9 Switch to unreal mode on boot
10
11 Allow editing memory pages
12 - "current page" also needs "current device"
13 - can be just the base RAM for now
14
15 Implement an actual VM for it (likely something rather befungeoid, but not Befunge)
16 - Execute from "current exection page"
17 - If "current execution page" is "current displayed page",
18 also update cursor while executing
19 Rewrite Editor in the befungeoid VM?
20
21
22 Fix syscalls
23 - Really, you should only be able to syscall a Beeble (=Befunge-05) instruction
24