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