/[projet1]/public/pc/tools/osdk/main/Osdk/_final_/documentation/doc_floppybuilder.htm
Defence Force logotype

Contents of /public/pc/tools/osdk/main/Osdk/_final_/documentation/doc_floppybuilder.htm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1117 - (show annotations)
Sun Feb 23 14:15:24 2014 UTC (5 years, 11 months ago) by dbug
File MIME type: text/html
File size: 13281 byte(s)
Minor changes, added documentation
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
2
3 <HTML lang=fr dir=ltr>
4 <HEAD>
5 <meta name="robots" content="noindex">
6 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
7 <title>OSDK - FloppyBuilder</title>
8 <link href="documentation.css" rel="stylesheet" type="text/css">
9 </HEAD>
10
11 <BODY>
12
13 <hr>
14 <A href="documentation.htm"><img src="arrow_back.gif"></A>
15 <img src="pics/osdk_logo_small.png">
16 <hr>
17
18 <h1>FloppyBuilder</h1>
19
20 <p>Important: <i>The rest of this documentation is going to try to explain how the whole process works, but the best example is to look at the real world sample demo
21 <B>Pushing The Envelope</b> <a href="http://miniserve.defence-force.org/svn/public/oric/demos/PushingTheEnvelope/">source code</a> in the SVN depot.</i>
22 </p>
23
24 <p id=chapter>Description</p>
25
26 <p>The FloppyBuilder is a relatively advanced tool which can be used to generate optimized DSK files.
27 </p>
28
29 <p>The Tap2Dsk tool is conceptually equivalent to the FloppyBuilder, the main difference being that Tap2Dsk generates Sedoric floppies while FloppyBuilder generates
30 floppy files that do not rely on the disk operating system, allowing the user to use almost all the Oric memory and most of the floppy surface.
31 </p>
32
33 <p>In order to use the FloppyBuilder, you need to create a description file using the syntax described in the following sections. From this description file will be generated both a DSK file and a header file.
34 </p>
35
36 <p>The DSK file is a floppy disk image (in the usual Oric format at used in emulators), while the header file contains informations about the floppy layout which can be used by the programmer to load the files.
37 </p>
38
39 <p>With this organisation comes an interesting chicken and egg problem: In order to generate the DSK file, the FloppyBuilder needs to have a list of files to write, but in order to access the files the user
40 code needs to know where the files are located and how large they are, which in turn impacts the content of the DSK file which may mean that the location of the file changed. To solved this cyclical dependency
41 the FloppyBuilder has been designed to be run in two different modes: The <b>initialization</b> mode and the <b>building</b> mode:
42 </p>
43
44 <ul>
45 <li>The FloppyBuilder will first be called in Initialization mode, which will generate a header file with enough information to make it possible to build the project without actually requiring that all files be present.</li>
46 <li>The user code is then assembled/compiled, it can reference and use the content of the header file, which will possibly not be entirelly correct but will allow the files to have the correct size.</li>
47 <li>The FloppyBuilder is then called in Building mode, which will require all files to be present, this pass will update the header file which should now contains correct data.</li>
48 <li>The user code is then assembled/compiled again, this time with all the correct information in the header file.</li>
49 <li>The FloppyBuilder is then called in Building mode a final time, we now have a valid DSK file.</li>
50 </ul>
51
52 <p>This process is admitely not very elegant, but it has the benefit of being simple and automated, and it allows for basically optimal file referencement:
53 You do not need to load a directory and search, you can just ask the loader to load a particular file immediately, identified by a single immediate value.
54 </p>
55
56 <p id=chapter>Invocation</p>
57
58 <p>The floppy builder does not take any optional switch or parameter at this point in time, the syntax is just one of these two situations:
59 </p>
60 <pre>
61 FloppyBuilder init description_file
62 FloppyBuilder build description_file
63 </pre>
64
65 <p id=chapter>The Description File format</p>
66
67 <p>Description file is a simple ASCII text format containing commands followed by a number of parameters. Empty lines are ignored, and semi-colon characters (;) are considered as comments.
68 </p>
69
70 <p>Here is a list of commands:
71 </p>
72
73 <ul>
74 <li>AddDefine define_name define_value</li>
75 <li>AddFile file address [optional_medatas]</li>
76 <li>DefineDisk sides tracks sectors</li>
77 <li>OutputFloppyFile dsk_file</li>
78 <li>OutputLayoutFile header_file</li>
79 <li>SetPosition track sector</li>
80 <li>SetCompressionMode</li>
81 <li>WriteSector file</li>
82 </ul>
83
84 <p>Here is an example of how these commands can be used:
85 </p>
86
87 <pre>
88 ;
89 ; ODSK Floppy Builder template description file
90 ;
91 DefineDisk 2 42 17 ; 2 sides, 42 tracks, 17 sectors
92 OutputLayoutFile floppy_description.h ; This file will be used by the loader (generated from this script)
93 OutputFloppyFile ..\build\FloppyBuilderTest.dsk ; The final DSK file containing the data (generated from this script)
94
95 ;
96 ; This defines the bootsectors to use for the various operating systems
97 ; - Jasmin loads the sector 1 of track zero in $400 and then runs it.
98 ; - Microdisc loads the sector 2 of track zero, the address is different on Atmos and Telestrat
99 ; - The system requires a third sector containing valid data
100 ;
101 ; Since we do not yet have a valid Jasmin reading code, all this bootsector will do is to
102 ; write a message saying that this floppy needs to be booted on a Microdisc compatible system.
103 ;
104 SetPosition 0 1 ; Set the head to track 0, sector 1
105 WriteSector ..\build\files\sector_1-jasmin.o ; Written to track 0, sector 1
106 WriteSector ..\build\files\sector_2-microdisc.o ; Written to track 0, sector 2
107 WriteSector ..\build\files\sector_3.o ; Written to track 0, sector 3
108
109 ;
110 ; Now here is the loader code, that one is Microdisc only
111 ;
112 SetPosition 0 4
113 AddFile ..\build\files\loader.o $fc00 ; Written to track 0, sector 4, and will be loaded in $fc00
114
115 ;
116 ; From now on we compress data (The loader should not be compressed)
117 ;
118 SetCompressionMode FilePack ; So far only two modes: 'None' and 'FilePack'
119
120 ;
121 ; Then the files used in this demo
122 ;
123 AddDefine LOADER_TEST_DEMO {FileIndex}
124 AddFile ..\build\files\testdemo.o $400 ; The main application, can be loaded by using the LOADER_TEST_DEMO define
125
126 AddDefine LOADER_FIRST_INTRO_PICTURE {FileIndex}
127 AddFile ..\build\files\test_picture.hir $a000 ; A hires picture loaded in $a000, can be access using the LOADER_FIRST_INTRO_PICTURE define
128 AddDefine LOADER_LAST_PICTURE {FileIndex}
129 </pre>
130
131 <p>This may look a bit complicated, but the beauty of the system is that the entire process is data driven because the generated data can be used almost transparently from either your assembler or C code.
132 </p>
133
134 <p id=chapter>The generated Header file</p>
135
136 <p>So, what does the generated header file looks like? If you would put the sample description file through the FloppyBuilder is here what you would get as a result:
137 </p>
138
139 <pre>
140 //
141 // Floppy layout generated by FloppyBuilder 0.15
142 // (The generated floppy is missing some files, a new build pass is required)
143 //
144
145 #ifdef ASSEMBLER
146 //
147 // Information for the Assembler
148 //
149 #ifdef LOADER
150 FileStartSector .byt 4,8,9
151 FileStartTrack .byt 0,0,0
152 FileStoredSizeLow .byt <1024,<44,<44
153 FileStoredSizeHigh .byt >1024,>44,>44
154 FileSizeLow .byt <1024,<44,<44
155 FileSizeHigh .byt >1024,>44,>44
156 FileLoadAdressLow .byt <64512,<1024,<40960
157 FileLoadAdressHigh .byt >64512,>1024,>40960
158 #endif // LOADER
159 #else
160 //
161 // Information for the Compiler
162 //
163 #endif
164
165 //
166 // Summary for this floppy building session:
167 //
168 #define FLOPPY_SIDE_NUMBER 2 // Number of sides
169 #define FLOPPY_TRACK_NUMBER 42 // Number of tracks
170 #define FLOPPY_SECTOR_PER_TRACK 17 // Number of sectors per track
171
172 //
173 // List of files written to the floppy
174 //
175 // Entry #0 '..\build\files\loader.o'
176 // - Loads at address 64512 starts on track 0 sector 4 and is 4 sectors long (1024 bytes).
177 // Entry #1 '..\build\files\testdemo.o'
178 // - Loads at address 1024 starts on track 0 sector 8 and is 1 sectors long (44 bytes).
179 // Entry #2 '..\build\files\test_picture.hir'
180 // - Loads at address 40960 starts on track 0 sector 9 and is 1 sectors long (44 bytes).
181 //
182 // 9 sectors used, out of 1428. (0% of the total disk size used)
183 //
184 #define LOADER_TEST_DEMO 1
185 #define LOADER_FIRST_INTRO_PICTURE 2
186 #define LOADER_LAST_PICTURE 3
187
188 //
189 // Metadata
190 //
191 #ifdef METADATA_STORAGE
192
193 #endif // METADATA_STORAGE
194 </pre>
195
196 <p>As you can see, the file contains some preprocessor information, tests, defines and actual entries:
197 </p>
198
199 <ul>
200 <li>Some #ifdef to handle both C and 6502 code. If ASSEMBLER is not defined at build time, the code will be assumed to be loaded from a C module</li>
201 <li>Some loader specific information, in the form of arrays of data with information for each file (location on track, size, loading address, compressed size, ...)</li>
202 <li>Some #define describing the format of the floppy (used by the loader to detect when it needs to change track or side)</li>
203 <li>Some #define that can be used to identify the files by ID (created by the AddDefine commands)</li>
204 <li>Some final #ifdef for the METADATA section (optional, more on that later)</li>
205 </ul>
206
207 <p id=chapter>The loader</p>
208
209 <p>We are now reaching the 'can do better' part. The loader is pretty much still a work in progress, if you take the source code of Pushing The Envelope as a base you could just keep it as is,
210 the only thing you may need to change is the <B>ldx #LOADER_SLIDESHOW</b> in <I>loader.asm</i> if you changed the define. The rest can be kept as is.
211 </p>
212
213 <p id=chapter>The loading API</p>
214
215 <p>If you kept the loader as is, you have access to two functions in the loading API:
216 </p>
217
218 <ul>
219 <li>LoadData (in $FFF7)</li>
220 <li>SetLoadAddress (in $FFF4)</li>
221 </ul>
222
223 <p>The function calls have been wrapped in 'loader_api.s', but basically all you need to do is to load a file is to pass the file entry number in the register X and then jmp to $fff7.
224 This will use the default address specified in the description file.
225 </p>
226
227 <p>If you want to load the data at another location, you can call the SetLoadAddress function in a similar way: Set X with the file entry number, A for the lower part of the address and Y for the high part,
228 then call $fff4. Subsequent calls to $fff7 for this file will use the new location (the call patched the loader table)
229 </p>
230
231
232 <p id=chapter>Historic</p>
233
234 <p>Here is the list of all releases with a short description of things that changed:
235 </p>
236
237 <p id=dateentry>Version 0.15</p>
238 - The output file now clearly states how much free room is available in bytes on the disk<br>
239
240 <p id=dateentry>Version 0.14</p>
241 - The MetaData tables will now not contain any information after the last file that declared metadata, this allows to not waste room in the loader for dummy data<br>
242
243 <p id=dateentry>Version 0.13</p>
244 - Added a new parameter to make it possible to bootstrap the floppy building process: With 'init' a description fill be generated even if data is missing,
245 this makes it possible to do a multi-pass build process which will not fail because it depends on things not yet generated :)<br>
246
247 <p id=dateentry>Version 0.12</p>
248 - The 'DefineDisk' command accepts a variable set of track definition values<br>
249
250 <p id=dateentry>Version 0.11</p>
251 - Added support for metadata that can be used later on by the programmer<br>
252
253 <p id=dateentry>Version 0.10</p>
254 - The compression code now generates correct data (it was using the Atari ST mode encoding, making the unpacking code not happy)<br>
255 - Added to the report file the occupation ratio of the floppy (by maintaining an internal list of used sectors also used to check if there's no overlap)<br>
256
257 <p id=dateentry>Version 0.9</p>
258 - Added the 'SetCompressionMode' command. Possible parameters are 'None' (default value) and 'FilePack'<br>
259
260 <p id=dateentry>Version 0.8</p>
261 - Cleaned up a bit the output description generation<br>
262
263 <p id=dateentry>Version 0.7</p>
264 - The code now automatically compute the gaps values based on the floppy structure parameters<br>
265 - The 'DefineDisk' command now works (at least for 2 sided, 42 tracks and 17 sectors floppies)<br>
266
267 <p id=dateentry>Version 0.6</p>
268 - Added the 'LoadDiskTemplate' and 'DefineDisk' commands (and removed these parameters from the command line)<br>
269 - Added the 'AddTapFile' command, similar to 'AddFile' but automatically removes the header and extract the start address of the file<br>
270
271 <p id=dateentry>Version 0.5</p>
272 - Fixed parsing of comments<br>
273 - added a 'OutputFloppyFile' command<br>
274 - validated that the number of sectors and tracks is correct in the 'SetPosition' command.<br>
275 - removed some unused variables<br>
276 - cleaned the offset/track/sector management code<br>
277 - the 'SetBootSector' command is now 'WriteSector' and automatically move to the next sector after writing data<br>
278
279 <p id=dateentry>Version 0.3</p>
280 - Work started in 2013 by Mickaël Pointier for the Oric 30th birthday<br>
281
282 <p id=dateentry>Version 0.2</p>
283 - Makedisk (c) 2002 Jérome Debrune, used on all Defence Force demos until 2013<br>
284
285 <hr>
286 <A href="documentation.htm"><img src="arrow_back.gif"></A>
287 <img src="pics/osdk_logo_small.png">
288 <hr>
289
290 </BODY>
291 </HTML>
292
293

  ViewVC Help
Powered by ViewVC 1.1.26