diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/MAINTAINERS | 8 | ||||
-rw-r--r-- | docs/PLUGIN_API | 88 | ||||
-rw-r--r-- | docs/TECH | 203 |
3 files changed, 1 insertions, 298 deletions
diff --git a/docs/MAINTAINERS b/docs/MAINTAINERS index 4928bb5a85..52ac7fb0db 100644 --- a/docs/MAINTAINERS +++ b/docs/MAINTAINERS | |||
@@ -25,13 +25,6 @@ NOTE: Port maintainers are simply developers who use a particular | |||
25 | target on a daily basis and are therefore able to report issues | 25 | target on a daily basis and are therefore able to report issues |
26 | specific to that target. | 26 | specific to that target. |
27 | 27 | ||
28 | :Archos Player/Studio: Jens Arnold | ||
29 | :Archos Recorder v1: Jens Arnold | ||
30 | :Archos Recorder 8MB: | ||
31 | :Archos FM Recorder: Linus Nielsen Feltzing | ||
32 | :Archos Recorder v2: Linus Nielsen Feltzing | ||
33 | :Archos Ondio FM: Jens Arnold, Marianne Arnold | ||
34 | :Archos Ondio SP: | ||
35 | :Creative Zen Vision: | 28 | :Creative Zen Vision: |
36 | :Creative Zen Vision:M: Maurus Cuelenaere | 29 | :Creative Zen Vision:M: Maurus Cuelenaere |
37 | :Creative Zen Vision:M 60GB: | 30 | :Creative Zen Vision:M 60GB: |
@@ -299,7 +292,6 @@ Build Tools | |||
299 | :rdf2binary: | 292 | :rdf2binary: |
300 | :convbdf: Daniel Stenberg | 293 | :convbdf: Daniel Stenberg |
301 | :codepages: | 294 | :codepages: |
302 | :player_unifont: | ||
303 | :uclpack: | 295 | :uclpack: |
304 | :wavtrim: Linus Nielsen Feltzing | 296 | :wavtrim: Linus Nielsen Feltzing |
305 | :voicefont: | 297 | :voicefont: |
diff --git a/docs/PLUGIN_API b/docs/PLUGIN_API index 768342bd80..b2fb94ed7e 100644 --- a/docs/PLUGIN_API +++ b/docs/PLUGIN_API | |||
@@ -810,25 +810,6 @@ enum yesno_res gui_syncyesno_run(const struct text_message * main_message, const | |||
810 | \return | 810 | \return |
811 | \description | 811 | \description |
812 | 812 | ||
813 | void i2c_begin(void) | ||
814 | \group MAS communication | ||
815 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
816 | \description | ||
817 | |||
818 | void i2c_end(void) | ||
819 | \group MAS communication | ||
820 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
821 | \description | ||
822 | |||
823 | int i2c_write(int address, const unsigned char* buf, int count ) | ||
824 | \group MAS communication | ||
825 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
826 | \param address | ||
827 | \param buf | ||
828 | \param count | ||
829 | \return | ||
830 | \description | ||
831 | |||
832 | void invalidate_icache(void) | 813 | void invalidate_icache(void) |
833 | \conditions (defined(CACHE_FUNCTIONS_AS_CALL)) | 814 | \conditions (defined(CACHE_FUNCTIONS_AS_CALL)) |
834 | \description | 815 | \description |
@@ -1433,56 +1414,6 @@ const unsigned long *rec_freq_sampr | |||
1433 | \return | 1414 | \return |
1434 | \description | 1415 | \description |
1435 | 1416 | ||
1436 | int mas_codec_readreg(int reg) | ||
1437 | \group MAS communication | ||
1438 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
1439 | \param reg | ||
1440 | \return | ||
1441 | \description | ||
1442 | |||
1443 | int mas_codec_writereg(int reg, unsigned int val) | ||
1444 | \group MAS communication | ||
1445 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
1446 | \param reg | ||
1447 | \param val | ||
1448 | \return | ||
1449 | \description | ||
1450 | |||
1451 | int mas_readmem(int bank, int addr, unsigned long* dest, int len) | ||
1452 | \group MAS communication | ||
1453 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) | ||
1454 | \param bank | ||
1455 | \param addr | ||
1456 | \param dest | ||
1457 | \param len | ||
1458 | \return | ||
1459 | \description | ||
1460 | |||
1461 | int mas_readreg(int reg) | ||
1462 | \group MAS communication | ||
1463 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) | ||
1464 | \param reg | ||
1465 | \return | ||
1466 | \description | ||
1467 | |||
1468 | int mas_writemem(int bank, int addr, const unsigned long* src, int len) | ||
1469 | \group MAS communication | ||
1470 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) | ||
1471 | \param bank | ||
1472 | \param addr | ||
1473 | \param src | ||
1474 | \param len | ||
1475 | \return | ||
1476 | \description | ||
1477 | |||
1478 | int mas_writereg(int reg, unsigned int val) | ||
1479 | \group MAS communication | ||
1480 | \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) | ||
1481 | \param reg | ||
1482 | \param val | ||
1483 | \return | ||
1484 | \description | ||
1485 | |||
1486 | void *memchr(const void *s1, int c, size_t n) | 1417 | void *memchr(const void *s1, int c, size_t n) |
1487 | \group strings and memory | 1418 | \group strings and memory |
1488 | \param s1 | 1419 | \param s1 |
@@ -1709,23 +1640,6 @@ void pcm_stop_recording(void) | |||
1709 | \conditions (CONFIG_CODEC == SWCODEC) && (defined(HAVE_RECORDING)) | 1640 | \conditions (CONFIG_CODEC == SWCODEC) && (defined(HAVE_RECORDING)) |
1710 | \description | 1641 | \description |
1711 | 1642 | ||
1712 | bool peak_meter_get_use_dbfs(void) | ||
1713 | \conditions ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
1714 | \return 1 if the meter currently is displaying dBfs values, 0 if the meter is displaying percent values | ||
1715 | \description | ||
1716 | |||
1717 | unsigned short peak_meter_scale_value(unsigned short val, int meterwidth) | ||
1718 | \conditions ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
1719 | \param val is the volume value (range: 0 <= val < MAX_PEAK) | ||
1720 | \param meterwidth is the width of the meter in pixel | ||
1721 | \return a value between 0 and meterwidth | ||
1722 | \description Scales a peak value as read from the MAS to the range of =meterwidth=. The scaling is performed according to the scaling method (dBfs / linear) and the range (peak_meter_range_min .. peak_meter_range_max). | ||
1723 | |||
1724 | void peak_meter_set_use_dbfs(bool use) | ||
1725 | \conditions ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F)) | ||
1726 | \param use If =use= is 0 use linear percent scale, else use dBfs | ||
1727 | \description Specifies whether the values displayed are scaled as dBfs or as linear percent values | ||
1728 | |||
1729 | int playlist_amount(void) | 1643 | int playlist_amount(void) |
1730 | \group playback control | 1644 | \group playback control |
1731 | \return the number of tracks in current playlist | 1645 | \return the number of tracks in current playlist |
@@ -2208,7 +2122,7 @@ void sound_set(int setting, int value) | |||
2208 | 2122 | ||
2209 | void sound_set_pitch(int pitch) | 2123 | void sound_set_pitch(int pitch) |
2210 | \group playback control | 2124 | \group playback control |
2211 | \conditions ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F) || (CONFIG_CODEC == SWCODEC)) | 2125 | \conditions (CONFIG_CODEC == SWCODEC) |
2212 | \param pitch | 2126 | \param pitch |
2213 | \description | 2127 | \description |
2214 | 2128 | ||
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. | ||