blob: b22a8c4c97cba7d238d0046d7b3b9be4fd37c4ca [file] [log] [blame]
Daniel Stenbergd3f4c362002-10-01 08:20:33 +00001 Rockbox From A Technical Angle
2 ==============================
3
4Background
5
6 Björn Stenberg started this venture back in the late year 2001. The first
7 Rockbox code was committed to CVS end of March 2002. Rockbox 1.0 was
8 released in June.
9
10Booting and (De)Scrambling
11
12 The built-in firmware in the Archos Jukebox reads a file from disk into
13 memory, descrambles it, verifies the checksum and then runs it as code. When
14 we build Rockbox images, we scramble the result file to use the same kind of
15 scrambling that the original Archos firmware uses so that it can be loaded
16 by the built-in firmware.
17
Linus Nielsen Feltzingec72d5a2002-10-30 23:39:37 +000018 1) The built-in firmware starts
19 2) It looks in the root directory for a file called "archos.mod" (player)
20 or "ajbrec.ajz" (recorder)
21 3) If it finds one, it loads the file, descrambles it and runs it
22
Daniel Stenbergd3f4c362002-10-01 08:20:33 +000023CPU
24
Linus Nielsen Feltzingec72d5a2002-10-30 23:39:37 +000025 The CPU in use is a SH7034 from Hitachi, running at 11.0592MHz (recorder)
26 or 12MHz (player).
27 Most single instructions are executed in 1 cycle. There is a 4KB internal RAM
28 and a 2MB external RAM.
Daniel Stenbergd3f4c362002-10-01 08:20:33 +000029
30Memory Usage
31
Linus Nielsen Feltzingec72d5a2002-10-30 23:39:37 +000032 All Archos Jukebox models have only 2MB RAM. The RAM is used for everything,
Daniel Stenbergd3f4c362002-10-01 08:20:33 +000033 including code, graphics and config. To be able to play as long as possible
34 without having to load more data, the size of the mpeg playing buffer must
35 remain as big as possible. Also, since we need to be able to do almost
36 everything in Rockbox simultaneously, we use no dynamic memory allocation
37 system at all. All sub-parts that needs memory must allocate their needs
38 staticly. This puts a great responsibility on all coders.
39
40Playing MPEG
41
42 The MPEG decoding is performed by an external circuit, MAS3507D (for the
43 Player/Studio models) or MAS3587F (for the Recorder models).
44
Linus Nielsen Feltzingec72d5a2002-10-30 23:39:37 +000045 The CPU has a serial connection to the MAS for MP3 playback, using serial
46 port 0 at approx. 1mbit/s. The MAS has a handshake signal called DEMAND,
47 that informs the CPU when it wants more MP3 data. Whenever the DEMAND
48 signal goes high, it wants data sent over the serial line, and it wants it
49 quickly, within ~1ms. When the MAS has received enough data, it negates the
50 DEMAND signal and expects the incoming data stream to stop within 1ms.
51
52 The DEMAND signal is connected to a port pin on the CPU which can generate
53 an IRQ, but only on the falling edge. That means that the mpeg driver code
54  must poll the DEMAND signal every ms to keep the MAS happy. The mpeg code
55 does use the IRQ to detect the falling edge when the MAS is "full".
56
57 Unfortunately, the serial port on the CPU sends the LSB first, and the MAS
58 expects the MSB first. Therefore we have to revers the bit order in every
59 byte in the loaded MP3 data. This is referred to as "bit swapping" in the
60 Rockbox code.
61
62 The internal DMA controller is used to feed the serial port with data. The
63 driver works roughly like this:
64
65 1) Load MP3 data into the RAM buffer
66 2) Bitswap the data
67 3) Load the DMA source pointer to the next 64Kbyte block to be transferred
68 4) Wait until DEMAND is high
69 5) Enable the DMA
70 6) Wait until the falling DEMAND pin generates an IRQ
71 7) Disable the DMA
72 8) Go to 4
73
74 The DMA generates an IRQ when the 64Kbyte block is transferred, and the
75 IRQ handler updates the DMA source pointer.
76
77
78 _____________________________
79 | |
80 DEMAND __________| |_____________
81 _ _ _ _ _ _ _ _ _
82 SC0 _____________/ \/ \/ \/ \/ \/ \/ \/ \/ \____________
83 \_/\_/\_/\_/\_/\_/\_/\_/\_/
84 ^ ^
85 | |
86 Poll sees the DEMAND The DEMAND pin generates
87 signal go high and an IRQ that in turn disables
88 enables the DMA the DMA again
Daniel Stenbergd3f4c362002-10-01 08:20:33 +000089
90Spinning The Disk Up/Down
91
92 To save battery, the spinning of the harddrive must be kept at a minimum.
93 Rockbox features a timeout, so that if no action has been performed within N
94 seconds, the disk will spin-down automaticly. However, if the disk was used
95 for mpeg-loading for music playback, the spin-down will be almost immediate
96 as then there's no point in timing out. The N second timer is thus only used
97 when the disk-activity is trigged by a user.
98
99FAT and Mounting
100
101 Rockbox scans the partitions of the disk and tries to mount them as fat32
102 filesystems at boot.
103
104Directory Buffer
105
106 When using the "dir browser" in Rockbox to display a single directory, it
107 loads all entries in the directory into memory first, then sorts them and
108 presents them on screen. The buffer used for all file entries is limited to
109 maximum 16K or 400 entries. If the file names are longish, the 16K will run
110 out before 400 entries have been used.
111
112 This rather limited buffer size is of course again related to the necessity
113 to keep the footprint small to keep the mpeg buffer as large as possible.
114
115Playlist Concepts
116
117 One of the most obvious limitations in the firmware Rockbox tries to
118 outperform, was the way playlists were dealt with.
119
120 When loading a playlist (which is a plain text file with file names
121 separated by newlines), Rockbox will scan through the file and store indexes
122 to all file names in an array. The array itself has a 10000-entry limit (for
123 memory size reasons).
124
125 To play a specific song from the playlist, Rockbox checks the index and then
126 seeks to that position in the original file on disk and gets the file name
127 from there. This way, very little memory is wasted and yet very large
128 playlists are supported.
129
130Playing a Directory
131
132 Playing a full directory is using the same technique as with playlists. The
133 difference is that the playlist is not a file on disk, but is the directory
134 buffer.
135
136Shuffle
137
138 Since the playlist is a an array of indexes to where to read the file name,
Linus Nielsen Feltzingec72d5a2002-10-30 23:39:37 +0000139 shuffle modifies the order of these indexes in the array. The algorithm is
140 pretty much like shuffling a deck of cards, and it uses a pseudo random
141 generator called the Mersenne Twister. The randomness is identical for the
142 same random seed. This is the secret to good resume. Even when you've shut
143 down your unit and re-starts it, using the same random seed as the previous
144 time will give exactly the same random order.
Daniel Stenbergd3f4c362002-10-01 08:20:33 +0000145
146Saving Config Data
147
148 The Player/Studio models have no battery-backuped memory while the Recorder
149 models have 44 bytes battery-backuped.
150
151 To save data to be persistent and around even after reboots, Rockbox uses
152 harddisk sector 63, which is outside the FAT32 filesystem. (Recorder models
153 also get some data stored in the battery-backuped area).
154
155 The config is only saved when the disk is spinning. This is important to
156 realize, as if you change a config setting and then immediately shuts your
157 unit down, the new config is not saved.
158
Linus Nielsen Feltzingd6cdd2f2002-10-03 10:02:22 +0000159 DEVELOPERS:
160 The config checksum includes a header with a version number. This version
161 number must be increased when the config structure becomes incompatible.
162 This makes the checksum check fail, and the settings are reset to default
163 values.
164
Daniel Stenbergd3f4c362002-10-01 08:20:33 +0000165Resume Explained
166
167 ...
168
169Charging
170
171 (Charging concerns Recorder models only, the other models have hardware-
172 controlled charging that Rockbox can't affect.)
173
174 ...
Brandon Low05dccc32006-01-18 20:54:13 +0000175
176Profiling
177
178 Rockbox contains a profiling system which can be used to monitor call count
179 and time in function for a specific set of functions on a single thread.
180
181 To use this functionality:
182 1) Configure a developer build with profiling support.
183 2) Make sure that the functions of interest will be compiled with the
184 PROFILE_OPTS added to their CFLAGS
185 3) On the same thread as these functions will be run, surround the relevent
186 running time with calls to profile_thread and profstop. (For codecs,
187 this can be done in the codec.c file for example)
188 4) Compile and run the code on the target, after the section to be profiled
189 exits (when profstop is called) a profile.out file will be written to
190 the player's root.
191 5) Use the tools/profile_reader/profile_reader.pl script to convert the
192 profile.out into a human readable format. This script requires the
193 relevent map files and object (or library) files created in the build.
194 (ex: ./profile_reader.pl profile.out vorbis.map libTremor.a 0)
195
196 There is also a profile_comparator.pl script which can compare two profile
197 runs as output by the above script to show percent change from optimization
198
199 profile_reader.pl requires a recent binutils that can automatically handle
200 target object files, or objdump in path to be the target-objdump.