From 33830609908c594989bb27577d863c8c2a718633 Mon Sep 17 00:00:00 2001 From: Solomon Peachy Date: Sun, 20 Apr 2025 16:53:57 -0400 Subject: [PATCH] docs: Delete some _very_ obsolete documentation Change-Id: I9c04c8eed8d7400d9d16f80c7dab1d6c8c42674f --- docs/API | 269 ----------------------------------------- docs/BATTERY-FAQ | 266 ---------------------------------------- docs/BATTERY-FAQ-LIION | 60 --------- docs/CONTRIBUTING | 2 +- docs/UISIMULATOR | 4 +- 5 files changed, 3 insertions(+), 598 deletions(-) delete mode 100644 docs/API delete mode 100644 docs/BATTERY-FAQ delete mode 100644 docs/BATTERY-FAQ-LIION diff --git a/docs/API b/docs/API deleted file mode 100644 index bd2eb22204..0000000000 --- a/docs/API +++ /dev/null @@ -1,269 +0,0 @@ -$Id$ - __________ __ ___. - Open \______ \ ____ ____ | | _\_ |__ _______ ___ - Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / - Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < - Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ - \/ \/ \/ \/ \/ - - API summmary - -[ This is outdated ] - -LCD - - #include - - 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 - - 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 - - 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 *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 - - strcmp() - strcpy() - memcpy() - memset() - ... - -Memory allocation - - #include - - 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 - - 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. diff --git a/docs/BATTERY-FAQ b/docs/BATTERY-FAQ deleted file mode 100644 index 70ea6f6244..0000000000 --- a/docs/BATTERY-FAQ +++ /dev/null @@ -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. diff --git a/docs/BATTERY-FAQ-LIION b/docs/BATTERY-FAQ-LIION deleted file mode 100644 index 636610a101..0000000000 --- a/docs/BATTERY-FAQ-LIION +++ /dev/null @@ -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. diff --git a/docs/CONTRIBUTING b/docs/CONTRIBUTING index 22300199a8..03dfea01ee 100644 --- a/docs/CONTRIBUTING +++ b/docs/CONTRIBUTING @@ -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, diff --git a/docs/UISIMULATOR b/docs/UISIMULATOR index eafbe74585..b5852a8d11 100644 --- a/docs/UISIMULATOR +++ b/docs/UISIMULATOR @@ -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