readme.txt

Frank s MP3 Player Source Files

Frank's MP3 Player Source Files
===============================

These files are provided for personal non-commercial
use only. Using them in whole or in part for any other
purpose requires written permission from the author.
Email: [e-mail]



BUILDING
========

To build the code, type (in a DOS box):
  make

This will create the file: frankmp3.hex
which can then be programmed into the Mega128
Flash memory using PonyProg (recommended) or
a similar programming utility.

Assuming of course you have AVR GCC installed!
I strongly recommend winavr which may be found at 
http://www.avrfreaks.com  WinAVR is what I use to 
build the code.



PROGRAMMING
===========

PonyProg is highly recommended. I've used it under
Win95, Win98se, Win2000 and WinXP. It can be downloaded
from http://www.lancos.com

I use the parallel port programming dongle which was 
provided with many of the Atmel starter kits (STK200 & 
STK300 kits). The dongle is also available from Kanda systems.
A schematic for the dongle can be found on my website,
on the lancos website, and other places. 



FLASH CONFIG BITS
=================

The Mega128 contains several configuration bits in Flash
memory quite separate from the main bank of Flash program memory.
These config bits MUST be programmed correctly or the AVR
will not work as you might hope. For this project the bits should
be programmed as follows:

JTAGEN (JTAG enable) OFF
M103C  (Mega103 compatibility mode) OFF

For using the 16 MHz crystal:
CKOPT      ON
CKSEL3..1  OFF OFF OFF
CKSEL0     OFF
SUT1..0    OFF OFF

The following are optional, but this is what I have:
BootLock12, 11, 02, 01 all OFF
Lock2, Lock1  both OFF
WDTON OFF
OCDEN OFF
SPIEN ON
EESAVE OFF
BOOTSIZE1..0  ON ON
BOOTRST OFF
BODLEVEL ON
BODEN ON

When using PonyProg, these bits are found in the
Command - Security & Configuration Bits menu.



BACKUPS
=======

To backup all the source files, place a disk in the floppy
drive and type "backup"  (no quotes). This will run the
backup.bat batch file. You will need a frankmp3 directory on
the floppy disk.



MAKEFILE
========

The makefile for this project is simply called "makefile".
Read it (with a text editor); it'll give you an idea of the
files involved in building this project. If you want to edit
the makefile, there are 2 spots of interest. Close to the top
is where you list your files to be built. In the case of this
project there is only a single .c file, as it #include's the
other .c files. Cheeky huh! If you create new .c files, either
add them to the #include list at the bottom of frankmp3.c, or
add them to the make file. Also in the make file are listed
the .s assembler files. At the bottom of the make file are the
dependencies for the .s assembler files.


EDITING FILES
=============

I encourage people to play with the code, add features, etc.
If you come up with something good (and well tested!) email it 
to me so I can look at merging it into the main code line.

Please keep in mind that SRAM is exceptionally limited. If your
new feature needs one or two bytes you'll be OK. If you need 50 or
100 bytes, think again! Remember there is loads of flash memory.
Whenever you can make a tradeoff between program code size and
SRAM usage, choose the larger program code size every single time.
Look in the source code for examples on how to put strings in flash
and then access them (otherwise by default the compiler will copy
them into SRAM :-(  Have fun!  I do.

As a tip, when reading through the source files, "grep" is really
useful for finding things. For example you see a reference to the
function "IRInit" and want to see it. Type, at a command line:
    grep "IRInit" *.c *.s
and grep will tell you the files it's contained in, plus print the
appropriate lines. Very handy for finding things. By default grep is
case-sensitive. For case insensitive, use:
    grep -i "irinit" *.c *.s



THE FILELIST
============

The descriptions for each file are not always exactly correct.
Sometimes "extra" routines slip into a file that may not quite
belong there <grin> But this should give you a good idea on where
to look for things. (And remember to use "grep" to help.)

Header Files:

frankasm.h      Included ONLY by .s files. Not used by .c files
fvhmp3c.h       Included ONLY by .c files. Not used by .s files
frankmp3.h      Included by both .s and .c files

Assembler Files:

ide.s           Implements the basic IDE (ATA) interface routines
fat32.s         Uses the IDE routines to read the FAT32 filesystem on the disk
queues.s        Also known as ring buffers, circular buffers, etc
serial.s        Deals with everything serial. USB, TWI, UART etc is considered serial.

C Files:

frankmp3.c      Top-level file, calls and/or #INCLUDES everything else. Contains main loop.
mp3init.c       Variety of routines vaguely related to initializations
mp3pc.c         Play Control. Basic player control (start, stop, etc)
mp3srial.c      Serial-related routines (TWI, USB are considered serial)
mp3menus.c      Menu-related routines (the menu framework code, plus actual menu functions)
sta-init.c      Don't edit without good reason; this is initialisation sequence for STA013 codec

Other:

readme.txt      This file
issues.txt      Known problems
makefile        build instructions for the code
backup.bat      batch file, copies all source files to floppy disk (a:\frankmp3 directory)



Frank Van Hooft
9 February 2004
http://www.frankvh.com/mp3player