diff options
author | Björn Stenberg <bjorn@haxx.se> | 2007-01-08 23:52:01 +0000 |
---|---|---|
committer | Björn Stenberg <bjorn@haxx.se> | 2007-01-08 23:52:01 +0000 |
commit | 6d4c19707ef95942e323cbdc89fbbfdbe45e7cc5 (patch) | |
tree | d11bbebc69df06d60970d05b4816e13d93602f2d /www/docs/flash.t | |
parent | 8cece5a745f30234bfced4becfd9dfe4ca1047d4 (diff) | |
download | rockbox-6d4c19707ef95942e323cbdc89fbbfdbe45e7cc5.tar.gz rockbox-6d4c19707ef95942e323cbdc89fbbfdbe45e7cc5.zip |
Splitting out www
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@11952 a1c6a512-1295-4272-9138-f99709370657
Diffstat (limited to 'www/docs/flash.t')
-rw-r--r-- | www/docs/flash.t | 418 |
1 files changed, 0 insertions, 418 deletions
diff --git a/www/docs/flash.t b/www/docs/flash.t deleted file mode 100644 index 118940fe1c..0000000000 --- a/www/docs/flash.t +++ /dev/null | |||
@@ -1,418 +0,0 @@ | |||
1 | #define _PAGE_ Rockbox in Flash - FAQ and User Manual | ||
2 | #include "head.t" | ||
3 | <p> | ||
4 | by Jörg Hohensohn aka [IDC]Dragon | ||
5 | <p> | ||
6 | 1. Introduction<br> | ||
7 | 2. Method<br> | ||
8 | 3. Risks<br> | ||
9 | 4. Requirements<br> | ||
10 | 5. Flashing procedure<br> | ||
11 | 6. Bringing in a current or personal build of Rockbox<br> | ||
12 | 7. Known issues and limitations<br> | ||
13 | 8. Movies and images<br> | ||
14 | |||
15 | |||
16 | <h2>1. Introduction</h2> | ||
17 | <p> | ||
18 | Flashing | ||
19 | in the sense used here and elsewhere in regard to Rockbox means | ||
20 | reprogramming the flash memory of the Archos unit. Flash memory | ||
21 | (sometimes called "Flash ROM") is a type of nonvolatile | ||
22 | memory that can be erased and reprogrammed in-circuit. It is a | ||
23 | variation of electrically erasable programmable read-only memory | ||
24 | (EEPROM). | ||
25 | </p> | ||
26 | <p> | ||
27 | When | ||
28 | you bought your Archos, it came with the Archos firmware flashed. | ||
29 | Now, you can replace the built-in software with Rockbox. | ||
30 | </p> | ||
31 | <p> | ||
32 | Terminology used in the following:<br> | ||
33 | <b>Firmware</b> means the flash ROM content as a whole.<br> | ||
34 | <b>Image</b> means one operating software started from there. | ||
35 | </p> | ||
36 | <p> | ||
37 | By | ||
38 | reprogramming the firmware, we can boot much faster. Archos has a | ||
39 | pathetic boot loader, versus the boot time for Rockbox is much faster | ||
40 | than the disk spinup, in fact it has to wait for the disk. Your boot | ||
41 | time will be as quick as a disk spinup (e.g. 4 seconds from powerup | ||
42 | until resuming playback). | ||
43 | </p> | ||
44 | |||
45 | <h2>2. Method</h2> | ||
46 | <p> | ||
47 | The | ||
48 | replaced firmware will host a bootloader and 2 images. This possible | ||
49 | by compression. The first is the "permanent" backup, not to | ||
50 | be changed any more. The second is the default one to be started, the | ||
51 | first is only used when you hold the F1 key (will be Menu for recorders) | ||
52 | during start. Like | ||
53 | supplied here, the first image is the original Archos firmware, the | ||
54 | second is a current build of Rockbox. This second image is meant to | ||
55 | be reprogrammed, it can contain anything you like, if you prefer, you | ||
56 | can program the Archos firmware to there, too. | ||
57 | </p> | ||
58 | <p> | ||
59 | There are two programming tools supplied: | ||
60 | </p> | ||
61 | <ul> | ||
62 | <li> | ||
63 | The | ||
64 | first one is called "firmware_flash.rock" and is used to | ||
65 | program the whole flash with a new content. You can also use it to | ||
66 | revert back to the original firmware you've hopefully backup-ed. In | ||
67 | the ideal case, you'll need this tool only once. You can view this | ||
68 | as "formatting" the flash with the desired image | ||
69 | structure. | ||
70 | </li> | ||
71 | <li> | ||
72 | The | ||
73 | second one is called "rockbox_flash.rock" and is used to | ||
74 | reprogram only the second image. It won't touch any other byte, | ||
75 | should be safe to fool around with. If the programmed firmware is | ||
76 | inoperational, you can still use the F1 start with the Archos | ||
77 | firmware and Rockbox booted from disk to try better. | ||
78 | </li> | ||
79 | </ul> | ||
80 | <p> | ||
81 | More technical details will be provided in the future, as well as non-user | ||
82 | tools. There's an authoring tool which composed the firmware file with the | ||
83 | bootloader and the 2 images, the bootloader project, the plugin sources, and | ||
84 | the tools for the UART boot feature: a monitor program for the box and a PC | ||
85 | tool to drive it. Feel free to review the | ||
86 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash/flash_sourcecode.zip">sources</a> | ||
87 | for all of it, but be careful when fooling around with powerful toys! | ||
88 | </p> | ||
89 | |||
90 | <h2>3. Risks</h2> | ||
91 | <p> | ||
92 | Well, | ||
93 | is it dangerous? Yes, certainly, like programming a mainboard BIOS, | ||
94 | CD/DVD drive firmware, mobile phone, etc. If the power fails, your | ||
95 | chip breaks while programming or most of all the programming software | ||
96 | malfunctions, you'll have a dead box. We take no responsibility of | ||
97 | any kind, you do that at your own risk. However, we tried as | ||
98 | carefully as possible to bulletproof this code. The new firmware file | ||
99 | is completely read before it starts programming, there are a lot of | ||
100 | sanity checks. If any fails, it will not program. Before releasing | ||
101 | this, we have checked the flow with exactly these files supplied | ||
102 | here, starting from the original firmware in flash. It worked | ||
103 | reliably, there's no reason why such low level code should behave | ||
104 | different on your box. | ||
105 | </p> | ||
106 | <p> | ||
107 | There's | ||
108 | one ultimate safety net to bring back boxes with even completely | ||
109 | garbled flash content: the UART boot mod, which in turn requires the | ||
110 | serial mod. It can bring the dead back to life, with that it's | ||
111 | possible to reflash independently from the outside, even if the flash | ||
112 | is completely erased. It has been used that during development, else | ||
113 | Rockbox in flash wouldn't have been possible. | ||
114 | Extensive development effort went into the exploitation of the UART boot | ||
115 | mod. Mechanically adept users with good soldering skills can easily perform | ||
116 | these mods. Others may feel uncomfortable using the first tool | ||
117 | (firmware_flash.rock) for reflashing the firmware. | ||
118 | </p> | ||
119 | <p> | ||
120 | To comfort you a bit again: | ||
121 | If you are starting with a known-good image, you are unlikely to experience | ||
122 | problems. The flash tools have been stable for quite a while. Several users | ||
123 | have used them extensively, even flashing while playing! Although it worked, | ||
124 | it's not the recommended method. ;-)" | ||
125 | </p> | ||
126 | <p> | ||
127 | About | ||
128 | the safety of operation: Since we have dual boot, you're not giving | ||
129 | up the Archos firmware. It's still there when you hold F1 during | ||
130 | startup. So even if Rockbox from flash is not 100% stable for | ||
131 | everyone, you can still use the box, reflash the second image with an | ||
132 | updated Rockbox copy, etc. | ||
133 | </p> | ||
134 | <p> | ||
135 | The | ||
136 | flash chip being used by Archos is specified for 100,000 cycles (in | ||
137 | words: one hundred thousand), so you don't need to worry about that | ||
138 | wearing out. | ||
139 | </p> | ||
140 | |||
141 | <h2>4. Requirements</h2> | ||
142 | <p> | ||
143 | You need two things: | ||
144 | </p> | ||
145 | <ul> | ||
146 | <li> | ||
147 | The first is a Recorder, FM Recorder or Recorder V2 model. Be sure | ||
148 | you're using the correct package, they are different! The technology | ||
149 | works for the Player models, too. Players can also be flashed, but Rockbox | ||
150 | does not run cold-started on those, yet. | ||
151 | </li> | ||
152 | <li> | ||
153 | Second, | ||
154 | you need an in-circuit programmable flash. Chances are about 85% | ||
155 | that you have, but Archos also used an older flash chip which can't | ||
156 | do the trick. You can find out via Rockbox debug menu, entry | ||
157 | Hardware Info. If the flash info gives you question marks, you're | ||
158 | out of luck. The only chance then is to solder in the right chip | ||
159 | (SST39VF020), at best with the firmware already in. If the chip is | ||
160 | blank, you'll need the UART boot mod as well. | ||
161 | </li> | ||
162 | </ul> | ||
163 | |||
164 | <h2>5. Flashing procedure</h2> | ||
165 | <p> | ||
166 | Short | ||
167 | explanation: copy the firmware_*.bin files for your model from the | ||
168 | distribution to the root directory of your box, then run the | ||
169 | "firmware_flash.rock" plugin. Long version, step by step | ||
170 | procedure: | ||
171 | </p> | ||
172 | <ul> | ||
173 | <li> | ||
174 | download the correct package for you model, | ||
175 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash/flash_rec.zip">Recorder</a> | ||
176 | or | ||
177 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash/flash_fm.zip">FM</a>, | ||
178 | or | ||
179 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash/flash_v2.zip">V2</a>, | ||
180 | copy some files of it to your box: | ||
181 | <ol> | ||
182 | <li> | ||
183 | "ajbrec.ajz" | ||
184 | into the root directory (the version of Rockbox we're going to use | ||
185 | and have in the firmware file) | ||
186 | </li> | ||
187 | <li> | ||
188 | firmware_rec.bin or firmware_fm.bin or firmware_v2.bin (name depends on | ||
189 | your model) into the root directory (the complete firmware | ||
190 | for your model, with the bootloader and the two images). There now | ||
191 | is also a _norom variant, copy both, the plugin will decide which | ||
192 | one is required for your box. | ||
193 | </li> | ||
194 | <li> | ||
195 | the .rockbox subdirectory with all the plugins for Rockbox | ||
196 | </li> | ||
197 | </ol> | ||
198 | <li> | ||
199 | Restart the box so that the new ajbrec.ajz gets started. | ||
200 | </li> | ||
201 | </li> | ||
202 | <li> | ||
203 | Enter | ||
204 | the debug menu and select the hardware info screen. Check you flash | ||
205 | IDs (bottom line), and please make a note about your hardware mask | ||
206 | value (second line). The latter is just for our curiosity, not | ||
207 | needed for the flow. If the flash info shows question marks, you can | ||
208 | stop here, sorry. | ||
209 | </li> | ||
210 | <li> | ||
211 | Backup | ||
212 | the current firmware, using the first option of the debug menu (Dump | ||
213 | ROM contents). This creates 2 files in the root directory, which you | ||
214 | may not immediately see in the Rockbox browser. The 256kB-sized | ||
215 | "internal_rom_2000000-203FFFF.bin" one is your present | ||
216 | firmware. Back both up to your PC. | ||
217 | </li> | ||
218 | <li> | ||
219 | (optional) | ||
220 | While you're in this Rockbox version, it is recommended to give it a | ||
221 | test and play around with it, this version is identical to the one | ||
222 | about to be programmed. Make sure that especially USB access and | ||
223 | Rolo works. When done, restart again to have a fresh start and to be | ||
224 | back in this Rockbox version. | ||
225 | </li> | ||
226 | <li> | ||
227 | Use | ||
228 | the F2 settings to configure seeing all files within the browser. | ||
229 | </li> | ||
230 | <li> | ||
231 | Connect | ||
232 | the charger and make sure your batteries are also in good shape. | ||
233 | That's just for security reasons, it's not that flashing needs more | ||
234 | power. | ||
235 | </li> | ||
236 | <li> | ||
237 | Run | ||
238 | the "firmware_flash.rock" plugin. It again tells you about | ||
239 | your flash and the file it's gonna program. After F1 it checks the | ||
240 | file. Your hardware mask value will be kept, it won't overwrite it. | ||
241 | Hitting F2 gives you a big warning. If we still didn't manage to | ||
242 | scare you off, you can hit F3 to actually program and verify. The | ||
243 | programming takes just a few seconds. If the sanity check fails, you | ||
244 | have the wrong kind of boot ROM and are out of luck by now, sorry. | ||
245 | </li> | ||
246 | <li> | ||
247 | In | ||
248 | the unlikely event that the programming should give you any error, | ||
249 | don't switch off the box! Otherwise you'll have seen it working for | ||
250 | the last time. While Rockbox is still in DRAM and operational, we | ||
251 | could upgrade the plugin via USB and try again. If you switch it | ||
252 | off, it's gone. | ||
253 | </li> | ||
254 | <li> | ||
255 | Unplug | ||
256 | the charger, restart the box and hopefully be in Rockbox straight | ||
257 | away! You may delete "firmware_flash.rock" then, to avoid | ||
258 | your little brother playing with that. Pressing On+Play can do it, | ||
259 | or your PC. You can also delete the ".bin" files. | ||
260 | </li> | ||
261 | <li> | ||
262 | Try | ||
263 | starting again, this time holding F1 while pressing On. It should | ||
264 | boot the Archos firmware, which then loads rockbox from disk. In | ||
265 | fact, even the Archos firmware comes up quicker, because their | ||
266 | loader is replaced by mine. | ||
267 | </li> | ||
268 | </ul> | ||
269 | <h2>6. Bringing in a current or personal build of Rockbox</h2> | ||
270 | <p> | ||
271 | Short | ||
272 | explanation: very easy, just play a .ucl file like "rockbox.ucl" | ||
273 | from the download or build. Long version: | ||
274 | </p> | ||
275 | <p> | ||
276 | The | ||
277 | second image is the working copy, the "rockbox_flash.rock" | ||
278 | plugin from this package reprograms it. The plugins needs to be | ||
279 | consistant with the Rockbox plugin API version, otherwise it will | ||
280 | detect mismatch and won't run. | ||
281 | </p> | ||
282 | <p> | ||
283 | It | ||
284 | requires an exotic input, a UCL-compressed image, because that's the | ||
285 | internal format. UCL is a nice open-source compression library. The | ||
286 | decompression is very fast and less than a page of C-code. The | ||
287 | efficiency is even better than Zip with maximum compression, cooks it | ||
288 | down to about 58% of the original size. For details on UCL, see: | ||
289 | <a href="http://www.oberhumer.com/opensource/ucl/">www.oberhumer.com/opensource/ucl/</a> | ||
290 | |||
291 | </p> | ||
292 | <p> | ||
293 | Linux | ||
294 | users will have to download it from there and compile it, for Win32 | ||
295 | and Cygwin the executables are in | ||
296 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash">the packages</a>. | ||
297 | The sample program from that download is called "uclpack". | ||
298 | We'll use that to compress "rockbox.bin" which is the | ||
299 | result of the compilation. This is a part of the build process | ||
300 | meanwhile. If you compile Rockbox yourself, you should copy uclpack | ||
301 | to a directory which is in the path, we recommend placing it in the | ||
302 | same dir as SH compiler. | ||
303 | </p> | ||
304 | <p> | ||
305 | Don't | ||
306 | flash any "old" builds which don't have the latest | ||
307 | coldstart ability. They won't boot. These instructions refer to | ||
308 | builds from cvs state 2003-07-10 on. | ||
309 | </p> | ||
310 | <p> | ||
311 | Here are the steps: | ||
312 | </p> | ||
313 | <ul> | ||
314 | <li> | ||
315 | If | ||
316 | you start from a .ajz file, you'll need to descramble it first into | ||
317 | "rockbox.bin", by using "descramble ajbrec.ajz | ||
318 | rockbox.bin". IMPORTANT: For an FM, the command is different, | ||
319 | use "descramble -fm ajbrec.ajz rockbox.bin"! Otherwise the | ||
320 | image won't be functional. Compress the image using uclpack, | ||
321 | algorithm 2e (the most efficient, and the only one supported by the | ||
322 | bootloader), with maximum compression, by typing "uclpack --2e | ||
323 | --best rockbox.bin rockbox.ucl". You can make a batch file for | ||
324 | this and the above step, if you like. | ||
325 | </li> | ||
326 | <li> | ||
327 | Normally, | ||
328 | you'll simply download or compile rockbox.ucl. Copy it together with | ||
329 | ajbrec.ajz and all the rocks to the appropriate places, replacing | ||
330 | the old. | ||
331 | </li> | ||
332 | <li> | ||
333 | Just | ||
334 | "play" the .ucl file, this will kick off the | ||
335 | "rockbox_flash.rock" plugin. It's a bit similar to the | ||
336 | other one, but it's made different to make the user aware. It will | ||
337 | check the file, available size, etc. With F2 it's being programmed, | ||
338 | no need for warning this time. If it goes wrong, you'll still have | ||
339 | the permanent image. | ||
340 | </li> | ||
341 | <li> | ||
342 | It | ||
343 | may happen that you get an "Incompatible Version" error, | ||
344 | if the plugin interface has changed meanwhile. You're running an | ||
345 | "old" copy of Rockbox, but are trying to execute a newer | ||
346 | plugin, the one you just downloaded. The easiest solution is to rolo | ||
347 | into this new version, by playing the ajbrec.ajz file. Then you are | ||
348 | consistant and can play rockbox.ucl. | ||
349 | </li> | ||
350 | <li> | ||
351 | When | ||
352 | done, you can restart the box and hopefully your new Rockbox image. | ||
353 | </li> | ||
354 | </ul> | ||
355 | <p> | ||
356 | If | ||
357 | you like or have to, you can also flash the Archos image as the | ||
358 | second one, e.g. in case Rockbox from flash doesn't work for you. | ||
359 | This way you keep the dual bootloader and you can easily try | ||
360 | different later. You can download | ||
361 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash">UCLs</a> | ||
362 | for the latest firmware | ||
363 | <a href="http://joerg.hohensohn.bei.t-online.de/archos/flash">here</a>. | ||
364 | |||
365 | </p> | ||
366 | |||
367 | <h2>7. Restoring the original firmware</h2> | ||
368 | <p> | ||
369 | If you'd like to revert to the original firmware, you can | ||
370 | do like you did when you flashed Rockbox for the first time (section 5), but | ||
371 | copy and rename your backup to be | ||
372 | "firmware_rec.bin" on the box this time. Keep the Rockbox | ||
373 | copy and the plugins of this package for that job, because that's the | ||
374 | one it was tested with. | ||
375 | </p> | ||
376 | |||
377 | <h2>8. Known issues and limitations</h2> | ||
378 | <p> | ||
379 | Latest | ||
380 | Rockbox now has a charging screen, but it is in an early stage. | ||
381 | You'll get it when the unit is off and you plug in the charger. The | ||
382 | Rockbox charging algorithm is first measuring the battery voltage for | ||
383 | about 40 seconds, after that it only starts charging when the | ||
384 | capacity is below 85%. You can use the Archos charging (which always | ||
385 | tops off) by holding F1 while plugging in. Some FM users reported | ||
386 | charging problems even with F1, they had to revert to the original | ||
387 | flash content. | ||
388 | </p> | ||
389 | <p> | ||
390 | If the plugin API is changed, new builds may render the plugins | ||
391 | incompatible. When updating, make sure you grab those too, and rolo | ||
392 | into the new version before flashing it. | ||
393 | </p> | ||
394 | <p> | ||
395 | There | ||
396 | are two variants of how the boxes starts, therefore the normal and | ||
397 | the _norom firmware files. The vast majority of the | ||
398 | Player/Recorder/FM all have the same boot ROM content, | ||
399 | differentiation comes later by flash content. Rockbox identifies this | ||
400 | boot ROM with a CRC value of 0x222F in the hardware info screen. Some | ||
401 | recorders have the boot ROM disabled (it might be unprogrammed) and | ||
402 | start directly from a flash mirror at address zero. They need the new | ||
403 | _norom firmware, it has a slightly different bootloader. Without a | ||
404 | boot ROM there is no UART boot safety net. To compensate for that as | ||
405 | much as possible the MiniMon monitor is included, it starts with | ||
406 | F3+On. Using that the box can be reprogrammed via serial if the first | ||
407 | ~2000 bytes of the flash are OK. | ||
408 | </p> | ||
409 | |||
410 | <h2>8. Movies and images</h2> | ||
411 | <p> | ||
412 | Jörg's AVI movie (1.5MB) <a href="flash/rockbox_flash_boot.avi">rockbox_flash_boot.avi</a> | ||
413 | showing his unit booting Rockbox from flash. | ||
414 | <p> | ||
415 | Roland's screendump from the movie:<br> | ||
416 | <img src="flash/rockbox-flash.jpg" width="352" height="288"> | ||
417 | |||
418 | #include "foot.t" | ||