diff options
Diffstat (limited to 'docs/TECH')
-rw-r--r-- | docs/TECH | 203 |
1 files changed, 0 insertions, 203 deletions
diff --git a/docs/TECH b/docs/TECH deleted file mode 100644 index 9ae71eec15..0000000000 --- a/docs/TECH +++ /dev/null | |||
@@ -1,203 +0,0 @@ | |||
1 | Rockbox From A Technical Angle | ||
2 | ============================== | ||
3 | |||
4 | Background | ||
5 | |||
6 | [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 | |||
9 | Björn Stenberg started this venture back in the late year 2001. The first | ||
10 | Rockbox code was committed to CVS end of March 2002. Rockbox 1.0 was | ||
11 | released in June. | ||
12 | |||
13 | Booting 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 | |||
21 | 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 | |||
26 | CPU | ||
27 | |||
28 | 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. | ||
32 | |||
33 | Memory Usage | ||
34 | |||
35 | All Archos Jukebox models have only 2MB RAM. The RAM is used for everything, | ||
36 | 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 | |||
43 | Playing 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 | |||
48 | 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 | ||
57 | must poll the DEMAND signal every ms to keep the MAS happy. The mpeg code | ||
58 | 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 | ||
92 | |||
93 | Spinning 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 | |||
102 | FAT and Mounting | ||
103 | |||
104 | Rockbox scans the partitions of the disk and tries to mount them as fat32 | ||
105 | filesystems at boot. | ||
106 | |||
107 | Directory 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 | |||
118 | Playlist 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 | |||
133 | Playing 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 | |||
139 | Shuffle | ||
140 | |||
141 | Since the playlist is a an array of indexes to where to read the file name, | ||
142 | 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. | ||
148 | |||
149 | Saving 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 | |||
162 | 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 | |||
168 | Resume Explained | ||
169 | |||
170 | ... | ||
171 | |||
172 | Charging | ||
173 | |||
174 | (Charging concerns Recorder models only, the other models have hardware- | ||
175 | controlled charging that Rockbox can't affect.) | ||
176 | |||
177 | ... | ||
178 | |||
179 | Profiling | ||
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 m68k-elf-objdump 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. | ||