MP3TSi: Home | News Archive | Developer Guide | External Input | ISA MP3 Card | ECU Security | Colour LCD | FAQ | External Links | email me

Developer Guide

Important Notice

I apologize; I didn't update the header on this page, so my email address was not valid. I did not intend to come off as a snob by not answering email sent to the previous address; I just didn't get the mail. Sorry! I've corrected the address; please try sending again.

Introduction

Okay, so you bought a PJRC MP3 player. What have you gotten yourself into? A whole lotta fun, that's what! But it could be a bit frustrating if you just have to look at code and schematics alone to figure out the details and caveats of developing for this amazing project. So hopefully, you will find plenty of useful information here.

Yeah, yeah, get to the good stuff already!

Okay, this is a work-in-progress. I try to update as I learn new things.

• 8051 architecture
• Setting up a build environment (Windows or Linux)
• Setting up source code management
• Uploading new firmware
• Musings
• PJRC glossary
• Setting up a dual-boot Linux/Windows system

8051 architecture

Visit one of these sites for a tutorial on 8051 (important!):

• http://www.8052.com/tut8051.phtml
• http://www.ee.fit.edu/courses/ece1552/ATutor.htm

Setting up a build environment

• Windows

  I found this method to be successful. Paul's Tools page has a link to "good" versions of AS31 (the assembler) and SDCC (the compiler). Use his page to download and install them. Look for the Windows icon on the page.

  Perl -- I recommend ActivePerl, do a web search for it. Install it. 'Nuff said.

  Okay, now you need to install CygWin, in order to run the makefile (to build the code).

  1. Try this: Cygwin setup program. Run the program directly, or save it to your desktop or a familiar place and run it.
  2. Click Next.
  3. Select Install from Internet and click Next.
  4. Use C:\cygwin as your root dir if possible. Everything in this guide will assume you've done that, so if you choose a different drive/directory, it's up to you to substitute your choice where appropriate. Install for all users, and use Unix as the default text file type. Click Next.
  5. Choose whatever you like for your Local Package Directory. It's basically where the temporary files will be stored. Click Next.
  6. Choose Direct Connection. Click Next.
  7. Select a download site. Just pick one. Click Next.
  8. Now you'll see a list of packages to install. Click on the View button for a better view. Find and select the following:
     • bash
     • make
     • cvs
     • perl
     • vim (or your preferred editor)
     You only need the binaries. Click Next when you've selected the packages you want.
  9. It'll install the stuff, and when it's done, you can choose your icon/shortcut prefs. Whatever.
  Note that you can always run the CygWin setup program again and add more stuff, or remove stuff, etc. Cool!

  You should have already installed SDCC to C:\SDCC. Now, you're going to point your bash shell to the SDCC installation. Edit the text file in C:\cygwin\home\your_user_name called .bash_profile and add this line:

  export PATH=$PATH:/cygdrive/c/sdcc/bin

  Substitute a different drive letter and path if applicable. Now, when you start your CygWin bash, your path will include a reference to SDCC's binary directory, which will allow the makefile to run correctly.

• Linux

  You don't need to do a lot, if you have a typical Linux system. Make sure Perl is good to go, and GNU make is set up also. Then, you just need to follow the instructions on Paul's 8051 page to install SDCC and AS31, although it was a bit of a pickle to figure out where to place the files. You see, the archive contains a README that suggests it is easy to set up SDCC, but it's not that easy. You have to configure 'n' build it. Probably same goes for AS31. Sorry if I'm being a bit vague here, but the page is mainly for Windows users, because if you are brave enough to use Linux, you probably know enough to help yourself in the first place. But you can always email me with questions.

Source code management

Here are some tips for command-line CVS in Linux:

• Create a root directory for the CVS stuff in your home directory somewhere. In my case, I created an 'mp3' user for the system, and so in '/home/mp3', I created a directory called 'mp3-cvs', which I use as my CVS root folder. Inside that will go Paul's mp3 CVS module.
• Follow Paul's instructions on logging in.
• Enter your CVS root folder (eg. /home/mp3/mp3-cvs), and run 'cvs update' to get the latest version of all files for the 'mp3' module. If you are familiar with Visual SourceSafe, you should recognize the term 'project' -- in CVS, the same idea is called a 'module', and you must do checkouts by modules, not individual files (as far as I have discovered, anyhow). No problem, because you just edit the files you want to change, and ignore the others.
• When you are ready to edit the code, checkout the whole module (mp3).
• If you want to undo/cancel/scrap your changes to a particular file, delete your local copy of the file, and then do a 'cvs update filename' to get a fresh copy from the repository.

Building new firmware

Update: Tom Parker suggested that one can do an "authenticated" (or was it "authorized"?) checkout, which will make all the files in your working directory (your local copy) writeable, so you won't need to fiddle with jw002.asm.

Uploading new firmware

• You made changes only to the C code (basically, the app)
  1. From the PM2 prompt, press X and the C code will be deleted.
  2. Now, just send main.hex to the serial port. You can do this with a terminal program's ASCII upload, or you can even use a copy command. In Linux, my terminal (minicom) wouldn't upload properly, so I use cp main.hex /dev/ttyS0 instead, and, since I'm running X, I use a second terminal running minicom to monitor the results. Neat, huh? :^)
• You made changes to the C code or the drivers
  1. From the PM2 prompt, press Y.
  2. Send devmain.hex, as described above.
• You changed everything! (???)
  1. From PM2, press Z.
  2. Press Y to confirm.
  3. Send mp3player.hex, as described previously.

Fast firmware upload

There are some things to watch out for with the fast firmware upload on Win systems. One is, if you're using CygWin, you'll probably need to make a soft-link for perl. The hex2fdl script, for example, expects to find perl in /usr/bin, and on my system, it was in /CygDrive/c/Perl/bin (ActivePerl's default installation directory). You can just make a soft-link in /usr/bin called "perl" which points to the actual executable (eg. "ln -s /CygDrive/c/Perl/bin/perl /usr/bin/perl"). The other issue is that (currently, anyway), newlines get mangled into CRLFs on Win-type systems, so you'll need to tweak hex2fdl a bit by adding the ":raw" layer directive to the binmode near the top.

Musings

On my laptop, Linux compiles faster than Windows, especially the "peephole" stuff. I don't have any timings, but the difference is obvious to me.

If you're doing C development, a good place to start learning is the memory management. It's important to understand how the [A|a]ddr[5|6|7] functions work or at least what they do. Basically, memory is always allocated in 4K-byte blocks, and these blocks may be mapped into the 8051's address space. There are limitations: you may map, at most, any 3 blocks at a single time. Obviously, you must map a block before you can use the memory at that block. More on this subject later...

PJRC glossary

• block: [usually] refers to a 4Kb (4096 byte) block of memory stored on the SIMM
  • the maximum number of blocks supported by the player is 8192, hence the maximum useful SIMM size of 32Mb
  • in the C code, up to 3 of these 4Kb blocks may be mapped into the 8051's address space at any one time; use addr5() for the first, addr6() for the second, and addr7() for the third
• cluster: a disk cluster, size depends on how the drive was formatted
  • typical values are 4, 8, 16, or 32 Kb
  • I think Windows refers to it as an "allocation unit" when you format/chkdsk
• sector: typically 512 bytes in size
• LBA: logical block addressing

Setting up a dual-boot Win/Linux machine

I am running a laptop that dual-boots NT and Linux. It was was a little tricky to set up, because my particular laptop (a used IBM Thinkpad 760ED) is a bit of a strange one. The serial port was disabled when I bought, and the BIOS setup has no facility to enable/disable it. It had to be done with a driver disk from IBM. If you are using only Linux, try the this site. I had to disable the IR serial port's IRQ before I could enable the COM1 serial port. That's fine, because I don't intend to use the IR port. You should be able to figure out the utility, but you can email me for help if you need to.

For a dual-boot NT/Linux setup on a 2GB drive, I first installed Linux (Debian potato 2.2), with partitions similar to the following layout (this is my table after installing NT, however -- you can see that the NT partition became the boot partition after NT was installed. NT is fine with placing the boot loader pretty much anywhere on the disk, AFAIK. Here's the table (as seen in cfdisk 2.10f):

Name	Flags	Part Type	FS Type	[Label]	Size (MB)
hda1		Primary	Linux ext2		10.33
hda5		Logical	Linux swap		33.04
hda6		Logical	Linux swap		33.04
hda7		Logical	Linux ext2		999.17
hda3	Boot	Primary	FAT16	[NO NAME ]	1038.39

I installed LILO on the boot partition (at the start of the disk), and when I reached a root shell, I used the dd command (in my case, I believe it was dd if=/dev/hda1 of=/linux.boo bs=512 count=1) to copy the boot sector to a temporary file (linux.boo). Then I stuck in a disk, did mount /floppy, then cp linux.boo /floppy, and finally umount /floppy. Make a copy on another floppy just in case the first is bad (never trust floppies). Then install NT. Finally, copy linux.boo into NT's root directory (in my case, C:\), and add a line to BOOT.INI that says something like c:\linux.boo="Linux". Oh yeah, you'll have to unhide/unsystem/unreadonly the file with attrib or whatever first (and restore the attributes after your change). Restart, and you should have dual-boot working.

You'll also need to install AS31 and SDCC. You can find a link to a stable version on the PJRC file area on Yahoo Groups, or at PJRC.com. If you get the Linux version, you'll need to build it and install it. You'll obviously need the common development packages (gcc, etc) to build AS31 and SDCC. You'll need the gtklib library to build AS31. You may need to install other packages as well in order to build SDCC. Go to the AS31/SDCC page for more help.