docs/TECH

   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.