Linux on Realtek RTL8181

The RTL8181 Linux Cookbook
==========================
Copyright (C) 2004 Streetdata Pty Ltd (streetdata at users.sourceforge.net)


Introduction
------------
This document provides step-by-step instructions on building the open 
source RTL8181 linux port from rtl8181.sourceforge.net. You should read 
it sometime. :)


Packaging
---------
The RTL8181 distribution consists of several packages, available from 
the project's main website at rtl8181.sourceforge.net. Although each of 
the packages implements distinct functionality, you must install all of 
them in order to obtain a usable kernel.

At the time of writing this document, there are 3 distinct packages:

rtl8181-arch       - CPU detection and support, interrupt handling etc.
rtl8181-libpatfree - Patent-free MIPS ASM library
rtl8181-drivers    - Hardware drivers for devices embedded in RTL8181:
                     currently the serial port, flash memory and Ethernet.

Each package is available separately from the project download page.


Package contents
----------------
Each package archive contains two files of interest, named following a 
simple convention:

1. The drop-in archive: rtl8181-pkgname.tar.bz2

This is an archive of new files that need to be added to the kernel tree 
to obtain the specific functionality implemented by each package. 
These files are kversion-independent -- will work for all supported kernel 
versions. All new files are named such as to avoid conflicts with existing 
kernel file names, meaning that no files from the original kernel will be 
modified or overwritten during the installation of this archive.

2. The patch: rtl8181-pkgname-X.X.XX.diff

This is a kernel patch that enables the compile-time linking and the 
run-time operation of the package. This file is kversion-dependent and 
will only work for the kernel version indicated as X.X.XX in the 
template above. The distribution archive will contain one such file for 
each supported kernel version, so be sure to choose the one that matches 
yours. It is probably redundant to mention that this patch will modify 
existing kernel files.

Actually, there'd be 3 files of interest if we could get you interested 
in the README-pkgname file as well. Aah forget it. Two files. :)


Alternative packaging
---------------------
As of version 0.1.1, the RTL8181 distribution is also available as an 
all-inclusive kernel tree patch, named rtl8181-full-V.V.V-X.X.XX.diff, 
where V.V.V is the RTL8181 package version and X.X.XX is the kernel 
version to which it applies (example: rtl8181-full-0.1.1-2.4.27.diff = 
kernel patch version 0.1.1 for Linux kernel 2.4.27).


Pre-requisites
--------------
For compilation:
- A MIPS big-endian GCC cross-compile toolchain (see website for links).
- Patience.
- Clue.
- Luck.

For the firmware upload:
- A terminal program (such as minicom)
- A TFTP client
- Cables etc (see website for more information)


Installation using separate packages
------------------------------------
Start with a fresh, unmodified copy of the desired kernel version (confirm 
with the compatibility table that it's supported).

Change to the kernel tree top level directory:
	cd /usr/src/linux-2.4.18

Unpack the archive at the top level:
	bzcat /path/to/goodies/rtl8181-pkgname.tar.bz2 |tar xf -

Apply the patch at the top level:
	patch -p1 </path/to/goodies/rtl8181-pkgname-2.4.18.diff

Repeat the unpack/patch sequence for all provided packages.


Installation using the all-in-one patch
---------------------------------------
Start with a fresh, unmodified copy of the desired kernel version (confirm 
with the compatibility table that it's supported).

Change to the kernel tree top level directory:
	cd /usr/src/linux-2.4.27

Apply the all-inclusive patch at the top level:
	patch -p1 </path/to/goodies/rtl8181-full-0.1.1-2.4.27.diff


More patches
------------
Apply other third-party kernel patches as desired, but remember to verify 
the patches' compatibility with RISC architectures (the MIPS architecture 
in particular).


Ramdisk preparation
-------------------
Prepare a root ramdisk, either from scratch, or by modifying an existing 
one, previously extracted from an AP firmware file. 
Put a compressed copy in the arch/mips/ramdisk directory:
	gzip -9 </path/to/ramdisk/image >arch/mips/ramdisk.gz


Makefile changes
----------------
Edit the top-level kernel Makefile as follows:
- Change the ARCH line to ARCH := mips
- Change the CROSS_COMPILE line to CROSS_COMPILE := mips-linux-
  (the prefix of your cross-compile toolkit binaries, eg. mips-linux-gcc)


Configuration
-------------
Run "make menuconfig" or whatever your favourite flavour of make *config.

- Under "Machine selection" unselect all options on the page, then select 
"Support for Realtek RTL8181 SoC".
- Go to the new submenu "RTL8181 board configuration" and select the 
correct on-board RAM option for the target board.
- Enable the RTL8139 embedded Ethernet driver and select the correct PHY
(8305 if unsure).
- Enable flash ROM support (this will set the correct defaults for the 
"Memory Technology Devices" menuconfig page).
- Exit to the main configuration page.
- Under "CPU selection", select "CPU type" R3000; verify that the option 
"Use patent-free MIPS instruction subset" is checked.
- Under "Block devices", enable "RAM disk support" and "Initial RAM disk 
(initrd) support).
- Under "MIPS initrd options", enable "Embed root filesystem...".
- Under "Character devices", enable "Standard/generic..." support and 
"Support for console on serial port".
- Under "File systems", enable "Second extended" support if it's not 
enabled by default (2.4.24+).
- Configure other desired kernel options (netfilter etc), but remember: 
you want to keep it small. 

More configuration hints:
- Failure to select the correct RAM size will result in failure to boot.
  Use "AUTO" as a last resort, 8MiB as the fail-safe value (0.1.2+ only)
- Under "file systems", the sane choice would be to disable ISO9660 and
  everything NFS.
- Don't enable module support unless you really need it (for example, for 
  testing modular pre-release drivers). Since all hardware is on-chip, 
  compiling the drivers as modules would only add overhead.
  (it probably won't even work with the current version)


Building the kernel
-------------------
Run "make dep" and "make". If the build was successful, the kernel ELF 
image (vmlinux) will be made in the toplevel source directory.


Making the CSYS image
---------------------
Change to the rtl-lxload directory.
Point the Makefile KERNEL_ROOT declaration to the kernel directory.
Run "make" to generate the CSYS image (linux.bin). 

*** NOTE *** Refer to the rtl-lxload documentation for more information.


Uploading and flashing the firmware
-----------------------------------
The upload process is described in detail in Realtek's document INSTALL 
from the SDK rtl8181-linux tree. 

In a nutshell:

- Connect a terminal to the board's serial port
- Connect your computer's Ethernet to the board's eth0
- Configure your ethernet to IP 192.168.2.2/255.255.255.0

- Power up the board, observe the initial messages:
    ---RealTek(RTL8181)at .....
    no sys signature at 00010000!
    Jump to image start=0x80300000...
- Note the highest address after "no sys signature at". 
- Add 0x10000 to this value to find the flash offset of the firmware. 
  In the example above, the firmware offset is (0x10000+0x10000)=0x20000

- Power-cycle the board, press Esc in the terminal to drop to prompt.
- TFTP the CSYS image to the board's IP (192.168.2.1) in BINARY MODE.
- In the terminal, observe the message:
    "TFTP Client Upload File Size: 00XXXXXX Bytes at 80X00000"
  (00XXXXXX is the file size in hex, 80X00000 is the RAM address where the 
  image was stored - 80500000 or 80300000, depending on the btcode version)
- In the terminal, type the following command (careful):
    FLW 20000 80X00000 XXXXXX
    (20000    = the firmware offset, board-specific, calculated above,
     80X00000 = the RAM address from previous step: 80500000 or 80300000,
     XXXXXX   = the file size from previous step)
- Double-check the values when prompted and confirm the action (press "y")
- Allow the write operation to complete (you will receive a success message
  and return to prompt).

- Power-cycle the board again to boot the newly uploaded firmware.

*** NOTE *** Things that you DON'T want to do when flashing firmware:

- DON'T write to the flash memory area between 0-0x10000. You'll render 
  your board unusable beyond repair.
  As a general rule, a correct flash offset is a non-zero multiple of 
  0x10000 (0x10000, 0x20000, 0x30000 and sometimes 0x40000), with 20000 
  as the most common option.
- DON'T TFTP the firmware image in ASCII mode. You'll only waste a write 
  cycle. Make sure the TFTP client is set to BINARY mode before putting.
- DON'T power-down or power-cycle the board when FLW is in progress. 
  You may damage your board beyond repair.
- DON'T try to flash an image larger than your Flash ROM size.


Troubleshooting
---------------

1. The kernel won't patch cleanly.
Make sure you start with a clean version from kernel.org. If the 
compatibility table mentions any pre-requisite patches, apply them BEFORE 
the RTL8181 patches. If everything fails, report your failure in the 
online forum.

2. GCC warns that "the -mcpu option is deprecated" (kernel 2.4.18).
You can ignore the warnings.

3. The kernel build fails before completion
There are literally thousands of reasons why this can happen. Examine the 
error message for a hint of which file is causing the build process to fail. 
Most commonly, the build process will choke on a file related to a feature 
that you don't need anyway (like SCSI or VT console or PC keyboard support). 
Re-run the configuration step and disable the offending feature.
Report your failure in the online forum.

4. The kernel build chokes on one of *your* files!
Check the compatibility table again - the builds have only been tested 
with the listed versions. 
Have you applied any third-party patches? Try again without them.

5. After the firmware installation, the board reports a checksum error and 
   fails to boot.
Upload the image again and this time be sure to use BINARY TFTP mode.

6. The kernel starts booting, but freezes / panics / goes insane before 
   starting init.
Verify memory size declaration in the kernel configuration.
Try again without third-party patches.
Report your failure in the forum.

7. The Ethernet doesn't work with 8201SB support 
(< 0.1.2) Swap MACs in "make *config" and recompile.
(>=0.1.2) Verify and possibly update your HS record to include the correct
 board type.

8. The wireless interface is not available.
If you're feeling lucky, try the new wireless driver from the download page. 
Build instructions are included in the archive. Note that the current version 
can only be built as a module, so enable module support in your kernel.


Reporting successes, failures and bugs
--------------------------------------
1. Read the documentation, when available. The answer may be somewhere 
in there. Read the online forums.

2. Use the online forums to report stuff - private email can get lost or 
filtered out by some over-zealous spam filter (it happened before, 
apologies to those affected).

3. Nobody can or will fix the "doesn't work" bug. Please provide as much 
context information as you have - hardware configuration, kernel .config, 
dumps from the serial console, anything that you think could help.

--