diff options
Diffstat (limited to 'www')
-rw-r--r-- | www/docs/flash.t | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/www/docs/flash.t b/www/docs/flash.t new file mode 100644 index 0000000000..a6664ec137 --- /dev/null +++ b/www/docs/flash.t | |||
@@ -0,0 +1,261 @@ | |||
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. What is this about?<br> | ||
7 | 2. How is it working?<br> | ||
8 | 3. Is it dangerous?<br> | ||
9 | 4. Will it work for me?<br> | ||
10 | 5. How do I flash the firmware?<br> | ||
11 | 6. How do I bring in a current / my personal build of Rockbox?<br> | ||
12 | 7. Known issues, limitations<br> | ||
13 | |||
14 | <h1>1. What is this about?</h1> | ||
15 | <p> | ||
16 | This package contains tools to update the flash content of Archos Jukebox | ||
17 | Recorder / FM. | ||
18 | <p> | ||
19 | Some terminology I'm gonna use in the following: | ||
20 | Firmware means the flash ROM content as a whole. | ||
21 | Image means one operating software started from there. | ||
22 | By reprogramming the firmware we can boot much faster. Archos has a pathetic | ||
23 | boot loader, versus the boot time for rockbox is much faster than the disk | ||
24 | spinup, in fact it has to wait for the disk. Your boot time will be as quick as | ||
25 | a disk spinup. In my case, that's 3 seconds from powerup until resuming | ||
26 | playback. | ||
27 | |||
28 | <h1>2. How is it working?</h2> | ||
29 | <p> | ||
30 | The replaced firmware will host a bootloader and 2 images. I use data | ||
31 | compression to make this possible. The first is the "permanent" backup, not to | ||
32 | be changed any more. The second is the default one to be started, the first is | ||
33 | only used when you hold the F1 key during start. Like supplied here, the first | ||
34 | image is the original Archos firmware, the second is a current build of | ||
35 | Rockbox. This second image is meant to be reprogrammed, it can contain anything | ||
36 | you like, if you prefer, you can program the Archos firmware to there, too. | ||
37 | <p> | ||
38 | I supply two programming tools: | ||
39 | <ul> | ||
40 | <li> The first one is called "firmware_flash.rock" and is used to program the | ||
41 | whole flash with a new content. You can also use it to revert back to the | ||
42 | original firmware you've hopefully backup-ed. In the ideal case, you'll need | ||
43 | this tool only once. You can view this as "formatting" the flash with the | ||
44 | desired image structure. | ||
45 | <li> The second one is called "rockbox_flash.rock" and is used to reprogram only | ||
46 | the second image. It won't touch any other byte, should be safe to fool around | ||
47 | with. If the programmed firmware is inoperational, you can still use the F1 | ||
48 | start with the Archos firmware and Rockbox booted from disk to try better. | ||
49 | </ul> | ||
50 | <p> | ||
51 | I will provide more technical details in the future, as well as my non-user | ||
52 | tools. There's an authoring tool which composed the firmware file with the | ||
53 | bootloader and the 2 images, the bootloader project, the plugin sources, and | ||
54 | the tools for the UART boot feature: a monitor program for the box and a PC | ||
55 | tool to drive it. | ||
56 | |||
57 | <h1>3. Is it dangerous?</h3> | ||
58 | <p> | ||
59 | Yes, certainly, like programming a mainboard BIOS, CD/DVD drive firmware, | ||
60 | mobile phone, etc. If the power fails, your chip breaks while programming or | ||
61 | most of all the programming software malfunctions, you'll have a dead box. And | ||
62 | I take no responsibility of any kind, you do that at your own risk. However, I | ||
63 | tried as carefully as possible to bulletproof this code. The new firmware file | ||
64 | is completely read before it starts programming, there are a lot of sanity | ||
65 | checks. If any fails, it will not program. Before releasing this, I have | ||
66 | checked the flow with exactly these files supplied here, starting from the | ||
67 | original firmware in flash. It worked reliably for me, there's no reason why | ||
68 | such low level code should behave different on your box. | ||
69 | <p> | ||
70 | There's one ultimate safety net to bring back boxes with even completely | ||
71 | garbled flash content: the UART boot mod, which in turn requires the serial | ||
72 | mod. It can bring the dead back to life, with that it's possible to reflash | ||
73 | completely from the outside, even if the flash is completely erased. I used | ||
74 | that during development, else Rockbox in flash wouldn't have been possible. | ||
75 | Most of the developing effort went into this tooling. So people skilled to do | ||
76 | these mods don't need to worry. The others may feel unpleasant using the first | ||
77 | tool for reflashing the firmware. | ||
78 | <p> | ||
79 | To comfort you a bit again: The flash tools are stable since a while. I use | ||
80 | them a lot and quite careless meanwhile, even reflashed while playing. However, | ||
81 | I don't generally recommend that. ;-) | ||
82 | <p> | ||
83 | About the safety of operation: Since we have dual boot, you're not giving up | ||
84 | the Archos firmware. It's still there when you hold F1 during startup. So even | ||
85 | if Rockbox from flash is not 100% stable for everyone, you can still use the | ||
86 | box, reflash the second image with an updated Rockbox copy, etc. | ||
87 | <p> | ||
88 | The flash chip being used by Archos is specified for 100,000 cycles (in words: | ||
89 | one hundred thousand), so you don't need to worry about that wearing out. | ||
90 | |||
91 | <h1>4. Will it work for me?</h1> | ||
92 | <p> | ||
93 | You need two things: | ||
94 | <ul> | ||
95 | <li> The first is a Recorder or FM model. Be sure you're using the correct | ||
96 | package, Recorder and FM are different! In principle, the technology works for | ||
97 | the Player models, too. It's just that no work has been spent on this | ||
98 | (developers welcome). | ||
99 | |||
100 | <li> Second, you need an in-circuit programmable flash. Chances are about 85% | ||
101 | that you have, but Archos also used an older flash chip which can't do the | ||
102 | trick. You can find out via Rockbox debug menu, entry Hardware Info. If the | ||
103 | flash info gives you question marks, you're out of luck. The only chance then | ||
104 | is to solder in the right chip (SST39VF020), at best with the firmware already | ||
105 | in. If the chip is blank, you'll need the UART boot mod as well. | ||
106 | </ul> | ||
107 | |||
108 | <h1>5. How do I flash the firmware?</h1> | ||
109 | <p> | ||
110 | I'm using the new plugin feature to run the flasher code. There's not really a | ||
111 | wrong path to take, however here's a suggested step by step procedure: | ||
112 | <ul> | ||
113 | <li> copy 3 files of <a href="http://joerg.hohensohn.bei.t-online.de/archos/">this package</a> to the root directory of your box:<ol> | ||
114 | <li> ajbrec.ajz (the version of Rockbox we're going to use and have in the | ||
115 | firmware file)<br> | ||
116 | <li> firmware_flash.rock (the plugin for this job)<br> | ||
117 | <li> firmware_rec.bin or firmware_fm.bin (the complete firmware for your model, | ||
118 | with my bootloader and the two images) | ||
119 | </ol> | ||
120 | <li> Restart the box so that the new ajbrec.ajz gets started. | ||
121 | |||
122 | <li> Enter the debug menu and select the hardware info screen. Check you flash | ||
123 | IDs (bottom line), and please make a note about your hardware mask value | ||
124 | (second line). The latter is just for my curiosity, not needed for the | ||
125 | flow. If the flash info shows question marks, you can stop here, sorry. | ||
126 | |||
127 | <li> Backup the current firmware, using the first option of the debug menu | ||
128 | (Dump ROM contents). This creates 2 files in the root directory, which you may | ||
129 | not immediately see in the Rockbox browser. The 256kB-sized | ||
130 | "internal_rom_2000000-203FFFF.bin" one is your present firmware. Back it up to | ||
131 | your PC. | ||
132 | |||
133 | <li> (optional) While you're in this Rockbox version, I recommend to give it a | ||
134 | test and play around with it, this version is identical to the one about to be | ||
135 | programmed. Make sure that especially USB access and Rolo works. When done, | ||
136 | restart again to have a fresh start and to be back in this Rockbox version. | ||
137 | |||
138 | <li> Use the F2 settings to configure seeing all files within the browser. | ||
139 | |||
140 | <li> Connect the charger and make sure your batteries are also in good | ||
141 | shape. I'm just being paranoid here, it's not that flashing needs more power. | ||
142 | |||
143 | <li> Run the "firmware_flash.rock" plugin. It again tells you about your flash | ||
144 | and the file it's gonna program. After F1 it checks the file. Your hardware | ||
145 | mask value will be kept, it won't overwrite it. Hitting F2 gives you a big | ||
146 | warning. If I still didn't manage to scare you off, you can hit F3 to | ||
147 | actually program and verify. The programming takes just a few seconds. | ||
148 | |||
149 | <li> In the unlikely event that the programming should give you any error, | ||
150 | don't switch off the box! Otherwise you'll have seen it working for the last | ||
151 | time. While Rockbox is still in DRAM and operational, we could upgrade the | ||
152 | plugin via USB and try again. If you switch it off, it's gone. | ||
153 | |||
154 | <li> When the programming is done, rename the "ajbrec.ajz" file to | ||
155 | ajbrec.ajz_" or so. Pressing On+Play can do it, or the PC via USB. This is a | ||
156 | nice trick to make only the Archos firmware find and load it, versus Rockbox | ||
157 | looks for the exact filename. Since Rockbox is up to date, there's no point in | ||
158 | having it loading this on startup. | ||
159 | |||
160 | <li> Unplug the charger, restart the box and hopefully be in Rockbox straight | ||
161 | away! You should delete "firmware_flash.rock" then, to avoid your little | ||
162 | brother playing with that. Again, pressing On+Play can do it, or your PC. You | ||
163 | can also delete the ".bin" files. | ||
164 | |||
165 | <li> Try starting again, this time holding F1 while pressing On. It should | ||
166 | boot the Archos firmware, which then loads rockbox from disk. In fact, even | ||
167 | the Archos firmware comes up quicker, because their loader is replaced by | ||
168 | mine. | ||
169 | |||
170 | </ul> | ||
171 | |||
172 | When for any reason you'd like to revert to the original firmware, you can do | ||
173 | like above, but copy and rename your backup to be "firmware_rec.bin" on the | ||
174 | box this time. Keep the Rockbox copy and the plugins of this package for that | ||
175 | job, because that's the one it was tested with. | ||
176 | |||
177 | <h1>6. How do I bring in a current / my personal build of Rockbox?</h1> | ||
178 | <p> | ||
179 | The second image is the working copy, the "rockbox_flash.rock" plugin from this | ||
180 | package reprograms it. I suggest to place the plugin to where you keep the | ||
181 | others, "/.rockbox/rocks/". The plugin needs to be consistant with the Rockbox | ||
182 | plugin API version, otherwise it will detect mismatch and won't run. | ||
183 | <p> | ||
184 | It currently requires an exotic input, a UCL-compressed image, because that's | ||
185 | my internal format. UCL is a nice open-source compression library I found and | ||
186 | use. The decompression is very fast and less than a page of C-code. The | ||
187 | efficiency is even better than Zip with maximum compression, cooks it down to | ||
188 | about 58% of the original size. For details on UCL, see: | ||
189 | http://www.oberhumer.com/opensource/ucl/ | ||
190 | <p> | ||
191 | Linux users will have to download it from there and compile it, for Win32 and | ||
192 | Cygwin I can do that, so the executables are in the package. The sample program | ||
193 | from that download is called "uclpack". We'll use that to compress | ||
194 | "rockbox.bin" which is the result of the compilation. If flashing becomes very | ||
195 | popular, this could be a part of the build process. | ||
196 | <p> | ||
197 | Don't flash any "old" builds which don't have the latest coldstart ability I | ||
198 | brought into cvs these days. They won't boot. These instructions refer to | ||
199 | builds from cvs state 2003-07-10 on. | ||
200 | <p> | ||
201 | Here are the steps: | ||
202 | <ul> | ||
203 | <li> If you start from a .ajz file, you'll need to descramble it first into | ||
204 | "rockbox.bin", by using "descramble ajbrec.ajz rockbox.bin". IMPORTANT: For an | ||
205 | FM, the command is different, use "descramble -fm ajbrec.ajz rockbox.bin"! | ||
206 | Otherwise the image won't be functional. | ||
207 | |||
208 | <li> Compress the image using uclpack, algorithm 2e (the most efficient, and | ||
209 | the only one supported by the bootloader), with maximum compression, by typing | ||
210 | "uclpack --2e --best rockbox.bin rockbox.ucl". You can make a batch file for | ||
211 | this and the above step, if you like. | ||
212 | |||
213 | <li> Copy the resulting file to the root directory of your box. | ||
214 | |||
215 | <li> Start the "rockbox_flash.rock" plugin. It's a bit similar to the other | ||
216 | one, but I made it different to make the user aware. It tells you the flash | ||
217 | size and the starting position (so you can calculate how much is left). After | ||
218 | pressing F1 it will check the file, available size, etc. With F2 it's being | ||
219 | programmed, no need for warning this time. If it goes wrong, you'll still have | ||
220 | the permanent image. | ||
221 | |||
222 | <li> When done, you can restart the box and hopefully your new Rockbox image. | ||
223 | |||
224 | </ul> | ||
225 | |||
226 | A more luxurious version of the plugin could do the descrambling and | ||
227 | compression by itself, but that's hard to do because a plugin is very limited | ||
228 | with memory (32kB for code and data). Currently I'm doing one flash sector | ||
229 | (4096 bytes) at a time. Don't know how slow the compression algorithm would be | ||
230 | on the box, that's the strenuous part. | ||
231 | |||
232 | <h1>7. Known issues, limitations</h1> | ||
233 | <p> | ||
234 | The latest ATA init fixes seemed to have solved early adopter's problems. | ||
235 | However, the wait for the harddisk is longer, you're unlikely to reach the 3 | ||
236 | seconds boot time. I hope it will improve one day again. If there should still | ||
237 | be ATA errors on startup, use F1-On for the Archos image. Then you can either | ||
238 | reprogram the original firmware from your backup, or live with F1-On until a | ||
239 | better Rockbox build resolves it, or program the Archos software in the second | ||
240 | image, too. | ||
241 | |||
242 | <p> | ||
243 | Loading the original Archos firmware via rolo may hang, if Rockbox is started | ||
244 | from flash. This is some initialization problem which I hope to fix, rolo-ing | ||
245 | Rockbox versions works OK. If you feel homesick, hold F1 during powerup. | ||
246 | |||
247 | <p> | ||
248 | The behavior with plugged charger differs from original: the box starts when | ||
249 | you plug it in (no charging screen). You can't power it off while the charger | ||
250 | is plugged in, instead it kindof restarts in an odd way, can give ATA init | ||
251 | errors in this case. This is not harmful, sortof reminds to unplug before | ||
252 | powering off. | ||
253 | |||
254 | <p> | ||
255 | Rockbox currently insists on starting the HD before doing anything useful. | ||
256 | This can be a problem if the batteries are deeply discharged and too weak to | ||
257 | power up the HD, preventing rockbox to start up and charge them. Current | ||
258 | workaround is to hold F1 while plugging in, this gives the Archos charging | ||
259 | screen. | ||
260 | |||
261 | #include "foot.t" | ||