len0rd/rockbox
1
0
Fork 1
mirror of https://github.com/Rockbox/rockbox.git synced 2025-10-13 10:07:38 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Delete some _very_ obsolete documentation

Browse source 
Change-Id: I9c04c8eed8d7400d9d16f80c7dab1d6c8c42674f
This commit is contained in:
Solomon Peachy 2025-04-20 16:53:57 -04:00
parent 89a9b5cf39
commit 3383060990
5 changed files with 3 additions and 598 deletions
Download patch file Download diff file Expand all files Collapse all files

269
docs/API
View file

@ -1,269 +0,0 @@
$Id$
__________ __ ___.
Open \______ \ ____ ____ | | _\_ |__ _______ ___
Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ /
Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < <
Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \
\/ \/ \/ \/ \/
API summmary
[ This is outdated ]
LCD
#include <lcd.h>
Generic
Most LCD functions are specific for which output we work with, due to the
huge differences.
lcd_init() - init the LCD stuff
lcd_clear_display() - clear the whole display
lcd_backlight(on) - set backlight on/off
lcd_puts(x,y,string) write a string at given character position
Recorder
All the functions operate on a display buffer. You make the buffer get
shown on screen by calling lcd_update().
lcd_update() update the LCD according to the internal buffer.
lcd_update_rect(int x, int y, int height, int width)
Update the given rectangle to the LCD. Give arguments measured in
pixels. Notice that the smallest vertical resolution in updates that the
hardware supports is even 8 pixels. This function will adjust to those.
lcd_setfont(int font) set default font
lcd_setmargins(int x, int y) set top/left margins
lcd_putsxy(x,y,string,font) put a string at given position, using a
specific font
lcd_bitmap(src,x,y,width,height,clear) put a bitmap at given position
lcd_clearrect(x,y,width,height) clear a rectangle area
lcd_fillrect(x,y,width,height) fill a rectangle area
lcd_drawrect(x,y,width,height) draw a rectangle
lcd_invertrect(x,y,width,height) revert the graphics of the given area
lcd_drawline(x1,y1,x2,y2) draw a line between the coordinates
lcd_drawpixel(x,y) put a pixel on the given coordinate
lcd_clearpixel(x,y) clear the pixel at the given coordinate
lcd_fontsize(font,width,height) return the width and height of the font
Player
lcd_define_pattern(which,pattern,lenth) define a custom pattern
Buttons
#include <button.h>
These functions work the same regardless of which keypad you have, but they
return a different set of values. Note that the Recorder keypad has 10
keys, while the Player keypad only features 6.
int button_get(bool block)
Returns a bitmask for which keys were pressed. If 'block' is set TRUE it
won't return until a key is pressed.
Files
(These functions are POSIX look-alikes)
#include <file.h>
int open(const char *path, int oflag);
The open() function establishes the connection between a file and a file
descriptor. It creates an open file descrip- tion that refers to a file
and a file descriptor that refers to that open file description. The file
descriptor is used by other I/O functions to refer to that file.
int read(int fildes, void *buf, size_t nbyte);
The read() function attempts to read nbyte bytes from the file associated
with the open file descriptor, fildes, into the buffer pointed to by buf.
int lseek(int fildes, off_t offset, int whence);
The lseek() function sets the file pointer associated with the open file
descriptor specified by fildes as follows:
o If whence is SEEK_SET, the pointer is set to offset
bytes.
o If whence is SEEK_CUR, the pointer is set to its
current location plus offset.
o If whence is SEEK_END, the pointer is set to the size
of the file plus offset.
int write(int fildes, const void *buf, size_t nbyte);
NOT CURRENTLY SUPPORTED.
write writes up to count bytes to the file referenced by the file
descriptor fd from the buffer starting at buf.
int close(int fildes);
The close() function will deallocate the file descriptor indicated by
fildes. To deallocate means to make the file descriptor available for
return by subsequent calls to open(2) or other functions that allocate
file descriptors.
int rename(const char *old, const char *new);
NOT CURRENTLY SUPPORTED.
The rename() function changes the name of a file. The old argument points
to the pathname of the file to be renamed. The new argument points to the
new pathname of the file.
int remove(const char *pathname);
NOT CURRENTLY SUPPORTED.
remove deletes a name from the filesystem. It calls unlink for files,
and rmdir for directories.
Directories
#include <dir.h>
DIR *opendir(const char *name);
The opendir() function opens a directory stream corresponding to the
directory name, and returns a pointer to the directory stream. The
stream is positioned at the first entry in the directory.
struct dirent *readdir(DIR *dir);
The readdir() function returns a pointer to a dirent structure
representing the next directory entry in the directory stream pointed to
by dir. It returns NULL on reaching the end-of-file or if an error
occurred.
Add a description of the struct here.
int closedir(DIR *dir);
The closedir() function closes the directory stream associated with dir.
The directory stream descriptor dir is not available after this call.
String/Memory
#include <string.h>
strcmp()
strcpy()
memcpy()
memset()
...
Memory allocation
#include <dmalloc.h>
void *malloc(size_t size);
malloc() allocates size bytes and returns a pointer to the allocated
memory. The memory is not cleared.
void free(void *ptr);
free() frees the memory space pointed to by ptr, which must have been
returned by a previous call to malloc(), calloc() or realloc().
Otherwise, or if free(ptr) has already been called before, undefined
behaviour occurs.
void *realloc(void *ptr, size_t size);
realloc() changes the size of the memory block pointed to by ptr to size
bytes. The contents will be unchanged to the minimum of the old and new
sizes; newly allocated memory will be uninitialized. If ptr is NULL, the
call is equivalent to malloc(size); if size is equal to zero, the call is
equivalent to free(ptr). Unless ptr is NULL, it must have been returned
by an earlier call to malloc(), calloc() or realloc().
void *calloc(size_t nmemb, size_t size);
calloc() allocates memory for an array of nmemb elements of size bytes
each and returns a pointer to the allocated memory. The memory is set to
zero.
Various
#include <kernel.h>
void kernel_init(void)
Inits the kernel and starts the tick interrupt
void sleep(ticks)
Sleep a specified number of ticks, we have HZ ticks per second.
void yield(void)
Let another thread run. This should be used as soon as you have to "wait"
for something or similar, and also if you do anything that takes "a long
time". This function is the entire foundation that our "cooperative
multitasking" is based on. Use it.
int set_irq_level(int level)
Sets the interrupt level (0 = lowest, 15 = highest) and returns the
previous level. Note that you must shift the argument 4 bits to the left:
set_irq_level(level << 4);
void queue_init(struct event_queue *q)
Initialize an event queue. The maximum number of events in a queue is
QUEUE_LENGTH-1.
void queue_wait(struct event_queue *q, struct event *ev)
Receive an event in a queue, blocking the thread if the queue is empty.
void queue_post(struct event_queue *q, int id, void *data)
Post an event to a queue.
NOTE: Negative event ID's are for system use only!!!
bool queue_empty(struct event_queue* q)
Returns true if the queue is empty.
int queue_broadcast(int id, void *data)
Posts an event in all queues that has been initiated with queue_init().
Returns the number of queues that were posted to.
int tick_add_task(void (*f)(void))
Add a task to the tick task queue. The argument is a pointer to a
function that will be called every tick interrupt.
At most MAX_NUM_TICK_TASKS can be active at the same time.
int tick_remove_task(void (*f)(void))
Remove a task from the task queue.
void mutex_init(struct mutex *m)
Initialize a mutex.
void mutex_lock(struct mutex *m)
Lock a mutex. This will block the thread if the mutex is already locked.
Note that you will geta deadlock if you lock the mutex twice!
void mutex_unlock(struct mutex *m)
Unlock a mutex.

266
docs/BATTERY-FAQ
View file

@ -1,266 +0,0 @@
Q1: Are my batteries charged all the time when connected to my Player/Recorder?
A1: Player: the charging is all done by hardware and the exact functionality
is hard to determine. It is however not recommended to keep the charger
connected for more than 10-15 hours if you're not using the unit.
Recorder: no. The charging algorithm is carefully crafted in to not wear
out the batteries any more than necessary. If you're using your unit
connected to the charger most of the time, use the 'deep discharge' option
to save your batteries somewhat.
Q2: Will keeping my charger connected a long time damage my batteries? Can I
leave it over night?
A2: There's a deep discharge mode and you can switch trickle charge on and
off. If you use your AJB connected to the power supply the whole time,
select "deep discharge on" and "trickle charge off". If you want to charge
your AJB over night and take it with you the next day, select "deep
discharge off" (that it starts charging immediately) and "trickle charge
on" (that the batteries remain full).
Trickle charge is needed to keep the batteries full. That's necessary
because the device will stay powered on and continue to consume some power
from the batteries (the hardware does not allow running from the charger
without charging batteries, or powering off with the charger connected).
The trickle charge time is 12 hours. It should be enough for you to
disconnect your AJB in this time and turn it off / use it. However, after
12 hours of trickle charge, it will turn it off, the batteries are
discharged and another charge cycle is started.
As the Battery FAQ at http://www.greenbatteries.com/ puts it:
"A NiMH battery can be charged and discharged hundreds of times, but
whether that means 200 times or 800 times has a lot to do with how (you
use it)".
Q3: Does Rockbox charge the batteries more/less/worse/better than the Archos
firmware?
A3: Player: Rockbox doesn't affect the charging on Players, it is all done
by hardware logic out of software control.
Recorder: The whole algorithm is made to carefully charge the batteries
full and keep them full after that with a trickle charge option. Many
documents about charge ICs were considered. If you want to know details,
then look into docs/CHARGING_ALGORITHM. If you have comments, write to
mail@uwe-freese.de or the Rockbox mailinglist.
Test results with trickle charge (battery capacities measured with an
external charger, Model "Conrad Electronic Charge Manager 2010", ~100
EUR):
- after normal charge and top off time: 1798, 1834, 1819, 1815 mAh
- after normal + top off + trickle charge (12h): 1784, 1748, 1738, 1752 mAh
- charged with external charger: 1786, 1819, 1802, 1802 mAh
You can see, whenever you take your AJB with you in the 12h trickle charge
period, the batteries are at least 97% full. :)
Q4: What kind of batteries are there in my factory default Player/Recorder?
A4: Both ship with 1500 mAh NiMH (Nickel Metal Hydride) batteries.
Q5: Is it hard to change the batteries? Does it void my warranty?
A5: It is not very hard - the Archos manual and the FAQ on their web site
describe how to do it. Their technical support confirmed that replacing
the batteries with NiMH cells (of different capacities) will not void the
warranty. Just don't remove the screws.
Some units have been shipped with two sets of batteries, my Recorder 20
only had one set. Someone actually had Archos send him new batteries free
of charge after they had weared out, under the warranty.
Q6: How much do replacement batteries cost? Where can I buy them?
A6: http://www.greenbatteries.com sells 1800 mAh NiMH cells at $3.25USD each,
and I bought 4 of the same GP batteries for 20 euros in an home
electronics & household appliance store in Finland. NiMH batteries are
sold in almost all shops that sell consumer electronics, and in many
online shops. Browse around. There's a pretty good comparison between
different battery makes and models at the digital imaging resource site:
http://www.imaging-resource.com/ACCS/BATTS/BATTS.HTM In Germany,
www.reichelt.de sells GP 2000 batteries for 2,75 EUR (12/2002).
Q7: What kind of run-time can I expect on a set of fully-charged batteries
when running Rockbox?
A7: For the stock 1500 mAh cells, from 6 hours to 8 hours, depending on which
charger was used (see Q3) and the bitrate you use (higher bitrate means
more harddisk runtime). It depends a lot on the condition of the
batteries. With 2000 mAh batteries, you should reach about 10 hours or
more. We are looking into implementing more battery-saving techniques in
rockbox to make it rock longer. If you have a modified AJB with 8 MB, you
can reach playing times of up to 16 hours with 2100 mAh batteries.
Q8: Can I use different batteries in my Archos? How much playtime would
I gain by using 1800 mAh batteries instead of the 1500 mAh ones?
A8: Only use NiMH-type rechargeable batteries. It is considered to be safe to
use NiMH batteries of different capacities though, a lot of people have
purchaced 1700 or 1800 mAh batteries to replace the stock 1500 mAh cells
and have the device run a bit longer. 2000 mAh batteries are just
appearing in shops are equally good to use.
In theory, running time = capacity of batteries / current drawn by device,
so running time should increase linearly by the capacity, and 2000 mAh
over 1500 mAh should give 33% longer running time. In practice, the mAh
ratings are more or less tuned up by the marketing department (think of
watts on the back of "hi-fi" speakers and amplifiers) and what you
actually get out of the cells is something else than what is printed on
them. Check the excellent imaging-resource link above for details!
Q9: Can I use non-chargeable batteries in my Archos?
A9: This is not recommended. The unit has been designed to operate with four
1.2V batteries producing about 4.8V at most, and using 1.5V alkaline/zinc
carbon batteries will produce around 6.0V, which will heat up the unit a
lot more and might even damage it. The Archos manual explicitly tells you
not to do so. Also, if you connect the charger, it may even destroy both
the batteries and the unit.
Q10: Can I use a different charger?
A10: The short answer is: Using a different charger will void your warranty
and can be dangerous to your unit, so we can not recommend it.
On the other hand, people have successfully used different chargers with
similar specifications as the stock charger. The charger must have the
same kind of connector with same polarity (center positive/+). The
charger should supply at least 7-8 volts, and if it provides more than
10V, it probably should be regulated to 10V (do not directly plug it in
your 12V car battery or it's charger!). The universal travel charger
sold by Archos is specified at 12V, 1.2A so that's probably the maximum
rating you should use. A good circuit for powering from a car battery or
other source with a higher voltage would be a 600 mA fuse and a 10V
regulator like a 7810 of your favourite manufacturer in series.
Inside the Jukebox there is a regulator which limits the charging current
applied to the batteries. The higher the input voltage, the hotter this
IC gets. Don't use an input voltage above 12V. Using lower charging
voltage < 10V will slow down the charging. But the rockbox charging
algorithm should work then, too.
These are the output voltages of an original archos power supply:
- connected to AJB Recorder, not charging: 13,7 Volt
- connected to AJB Recorder, charging: going down to 10,4 Volt
Here is how changing the input voltage changes the charging current:
voltage charging current (limited only by the AJB)
------------------------------------------------------
7,0V 10 mA
7,5V 30 mA
8,0V 50 mA
8,5V 70 mA
9,0V 140 mA
9,5V 250 mA
10,0V 330 mA
10,5V 350 mA
11,0V 350 mA
11,5V 350 mA
12,0V 350 mA
To summarize:
- do not use an input voltage > 12V (it will only heat up the regulator)
- optimal input voltage is 10V (regulated)
- use a fuse of ~600mA
- using a different charger voids your warrenty
Many people are happy using an external quick charger which is specified
to work with NiMH batteries. This is completely safe and will not void
your warranty.
Q11: Can I buy a replacement charger exactly as the one Archos shipped?
A11: The FAQ on the Archos web site and the top of the charger both read:
Output: 9VDC 600mA
Center positive (+) polarity
The universal travel charger sold separately on the Archos web site is
specified for 12VDC, 1200mA output.
Chargers with similar (or user-adjustable) properties are available at
shops selling consumer electronics.
Q12: I often need to stop my player for about 15 minutes or so, and when I do
it runs off it's batteries. I was wondering, which is best: shutting the
player down completely and rebooting it when I want to listen again, or
leaving the unit on? Which way does it draw more power?
A12: In our testing we found the following results:
HDD off, backlight off, idle 94 mA
HDD off, backlight off, play 97 mA
HDD off, backlight on, idle 129 mA
HDD off, backlight on, play 131 mA
HDD on, backlight on, play 230 mA
HD on, reading, backlight off ~ 600 mA
HD spin up before read max 800 mA
Using the power draw measurements shown above, lets look at the numbers:
Power-down and restart vs. paused for 15 minutes.:
Pause for 15 minutes will draw: 94 mA / 60 minutes * 15 minutes =
23.5 mAh.
Power-down and restart will draw about (800mA / 3600 seconds * 3
seconds = 0.6666 mAh) + (600 mA / 3600 seconds * 6 seconds = 1.0 mAh) +
(230 mA / 3600 seconds * 8 seconds = 0.5111 mAh) = 2.18 mAh total used.
Thus, leaving it paused for 15 minutes draws more power (23.5 mAh) than
turning off and then on again (2.18 mAh).
So where is the break-even point?
Each second of pause will draw about 94 mAh / 3600 seconds = 26 µAh.
2.18 mAh / 26 µAh = 2180 µAh / 26 µAh = 83.5 seconds
Thus a shutdown and restart uses as much power as 83.5 seconds of pause.
Q13: When I plug in the charger when the Recorder is turned off, it turns
itself on and starts charging in the Archos software? What's up?
A13: There is a switch in the DC IN jack of the Jukebox - when a charger (or
whatever) is plugged in, the unit is powered on, even if the charger is
not plugged in a mains outlet.
If the charger is providing power at this point, the Archos firmware
located on the FLASH ROM does not load a new firmware version (like
Rockbox) from the disk, but goes into charging mode instead. You can use
this feature to get to the Archos charger if you want to.
However, if you put Rockbox in flash, it will always charge with the
Rockbox charging algorithm.
Q14: When I plug the charger in my Recorder, it doesn't immediately start
charging the batteries!
A14: When Rockbox is running on the Recorder (the device has been booted
without the charger) it's power management code runs once per minute
(thus the charge level and charging status is only updated every minute).
If the battery is not full, it will start charging. If the 'deep
discharge' mode is enabled in the settings menu, it will start charging
only when the battery is almost empty.
Q15: What about the memory effect? Should I be worried about it or not?
A15: That depends on who you ask. ;-) NiMH sellers say NiMHs are better and do
not have a memory effect, but the usual opinion seems to be that they do,
although it is very small.
However, if you use your AJB connected to the charger all the time,
we recommend you to use the deep discharge option.
Q16: When I start my Jukebox, (dis)connect the charger and browse through the
directories, the battery level changes a little bit. Sometimes it's even
going up without the charger is connected! What's wrong?
A16: Nothing's wrong. The battery level is calculated out of the voltage.
Because disk spinning, LED backlight, charger all influence the actual
battery voltage, it is usual that the battery level is going a little bit
up and down sometimes. This cannot be avoided although we tried to make
the battery level display as little confusing as we could.
Q17: My batteries are at 92%, the charger is connected to my recorder, deep
discharge is off. But charging doesn't start. What's wrong?
A17: Charging starts if the battery level is below 85%. This is because
charging batteries that *are* already more or less full is not good for
the batteries and the end of the charging cycle can't be detected safely.
So it's better to start at a level at least as low as 85%. If you want
to have full batteries in the morning, leave the charger connected over
night. Charging will then start some hours later. The second possibility:
Use the Archos charging algorithm. At least, your batteries will be full
one more time. ;-)
Q18: Why does rockbox show a question mark for the battery level?
A18: Rockbox waits for about a minute to show a battery reading, to increase
the reliability of the reading. In previous versions, the battery level
rockbox initially reported was always too low.

60
docs/BATTERY-FAQ-LIION
View file

@ -1,60 +0,0 @@
Q1. What kind of batteries are in my V2/FMR?
A1. They are 2200 mAh LiIon rechargeable batteries. Specifically, it is
two 1100 mAh LiIon cells in parallel, physically taped together.
Q2. Can I change the batteries?
A2. Yes, if you can find replacements. Archos does not sell them. One site
that does is: http://www.pdainternalbattery.com/archospdabattery.html.
Alternately, there are companies who make replacement battery assemblies
that might be able to help.
Q3. Ok, I got a replacement, now how do I put it in?
A3. Remove the two small screws on the top of your V2/FMR, and pry the lid off.
Now turn it upside down and shake it a little. It should just slide out.
Take note of the position it's in, and put the replacement in the same
way. Replace the cover.
Q4. How long should fully charged batteries run for?
A4. It depends on how you use it. If you're doing hard drive intensive
activities like formatting or transfering large amounts of data, probably
only a few hours. If you're only using it as an mp3 player it will depend
on the bitrate of the mp3s. Playing 128kbit mp3s, it should last around 8
hours. Playing lower quality recordings (32-64kbit) like audio books it
could be more like 12 or 14. Playing very high quality files (256kbit+)
it could be more like 4 or 6 hours. Also, doing the 8MB RAM mod will
significantly increase battery life.
Q5. How long does it take to fully charge the battery?
A5. About 50% charge is applied in the first hour. The rest takes up to 3
more hours.
Q6. I want/need a replacement charger. What kind should I get?
A6. A charger/adapter that outputs 6VDC at 700mAh and has a power plug with a
3.4mm O.D. x 1.3mm I.D., with positive center will have the same specs as
the original.
Q7. I've heard about options like deep discharge, but can't find them in the
menu. Where are they?
A7. These options are for the recorder (V1) only. Charging for the recorders is
done by software, but charging of the V2/FMR is controlled completely by
hardware.
Q8. Can the FMR/V2 charge its batteries through the USB port?
A8. Yes, though slowly since USB is limited to 500 mA. Charging is reduced or
eliminated when the FMR/V2 is connected through a passive hub. If a PCMCIA
USB adapter is being used in a laptop or similar device, it is very
important to connect the external power supply if one is provided.
The PCMCIA port cannot supply sufficient power by itself. The Belkin USB
2.0 adapter, for example, comes with a "wall wart" power supply that can
be plugged into the PCMCIA card.
Q9. Can I run my V2/FMR constantly with the power adapter plugged in without
any negative effects?
A9. Yes, as long as you aren't draining the battery faster than you're
charging it (like reading/writing a lot in USB mode).
Q10. Is it ok if I recharge the battery when I've only drained it part of the
way? Will that reduce the life of the battery?
A10. You can recharge at any time. Li-Ion batteries have virtually no
memory effect.

2
docs/CONTRIBUTING
View file

@ -69,7 +69,7 @@ Contributing code
-----------------
We have a public code review system based on git, which is also how you can
check out the latest version of the Rockbox sources.
See http://www.rockbox.org/wiki/UsingGit for details on how to setup your
See https://www.rockbox.org/wiki/UsingGit for details on how to setup your
environment and how to upload a change you have made for review.
We'd prefer that you don't submit patches to the bug tracker any more,

4
docs/UISIMULATOR
View file

@ -12,8 +12,8 @@
Get the very latest sources off the SVN server (or possibly get a recent
source code tarball).
All SVN details can be found here:
http://www.rockbox.org/wiki/UsingSVN
All Git details can be found here:
https://www.rockbox.org/wiki/UsingGit
2. Build Uisimulator