summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/MAINTAINERS8
-rw-r--r--docs/PLUGIN_API88
-rw-r--r--docs/TECH203
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
25target on a daily basis and are therefore able to report issues 25target on a daily basis and are therefore able to report issues
26specific to that target. 26specific 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
813void i2c_begin(void)
814 \group MAS communication
815 \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F))
816 \description
817
818void i2c_end(void)
819 \group MAS communication
820 \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC)) && ((CONFIG_CODEC == MAS3587F) || (CONFIG_CODEC == MAS3539F))
821 \description
822
823int 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
832void invalidate_icache(void) 813void 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
1436int 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
1443int 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
1451int 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
1461int mas_readreg(int reg)
1462 \group MAS communication
1463 \conditions (!defined(SIMULATOR) && (CONFIG_CODEC != SWCODEC))
1464 \param reg
1465 \return
1466 \description
1467
1468int 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
1478int 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
1486void *memchr(const void *s1, int c, size_t n) 1417void *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
1712bool 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
1717unsigned 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
1724void 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
1729int playlist_amount(void) 1643int 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
2209void sound_set_pitch(int pitch) 2123void 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
4Background
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
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
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
26CPU
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
33Memory 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
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
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
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,
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
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
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
168Resume 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 ...
178
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 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.