Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 1 | Rockbox From A Technical Angle |
| 2 | ============================== |
| 3 | |
| 4 | Background |
| 5 | |
Daniel Stenberg | 602532d | 2008-02-06 23:33:23 +0000 | [diff] [blame] | 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 | |
Nicolas Pennequin | 357ffb3 | 2008-05-05 10:32:46 +0000 | [diff] [blame] | 9 | Björn Stenberg started this venture back in the late year 2001. The first |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 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 | |
Linus Nielsen Feltzing | ec72d5a | 2002-10-30 23:39:37 +0000 | [diff] [blame] | 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 | |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 26 | CPU |
| 27 | |
Linus Nielsen Feltzing | ec72d5a | 2002-10-30 23:39:37 +0000 | [diff] [blame] | 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. |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 32 | |
| 33 | Memory Usage |
| 34 | |
Linus Nielsen Feltzing | ec72d5a | 2002-10-30 23:39:37 +0000 | [diff] [blame] | 35 | All Archos Jukebox models have only 2MB RAM. The RAM is used for everything, |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 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 | |
Linus Nielsen Feltzing | ec72d5a | 2002-10-30 23:39:37 +0000 | [diff] [blame] | 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 |
Nicolas Pennequin | 357ffb3 | 2008-05-05 10:32:46 +0000 | [diff] [blame] | 57 | must poll the DEMAND signal every ms to keep the MAS happy. The mpeg code |
Linus Nielsen Feltzing | ec72d5a | 2002-10-30 23:39:37 +0000 | [diff] [blame] | 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 |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 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, |
Linus Nielsen Feltzing | ec72d5a | 2002-10-30 23:39:37 +0000 | [diff] [blame] | 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. |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 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 | |
Linus Nielsen Feltzing | d6cdd2f | 2002-10-03 10:02:22 +0000 | [diff] [blame] | 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 | |
Daniel Stenberg | d3f4c36 | 2002-10-01 08:20:33 +0000 | [diff] [blame] | 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 | ... |
Brandon Low | 05dccc3 | 2006-01-18 20:54:13 +0000 | [diff] [blame] | 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 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. |