manual/advanced_topics/archos-flashing.tex

\section{\label{ref:Rockboxinflash}Rockbox in Flash}

\subsection{Introduction}

When you bought your \playertype, it came with the \playerman\ firmware in
flash ROM. When you power on your \dap, this \playerman\ firmware starts,
and then loads an updated firmware from disk if present (\firmwarefilename).
An ordinary Rockbox installation only replaces the on-disk firmware, leaving
the flash ROM contents intact. That means the \playerman\ firmware still
controls the boot process.

The main reason to change this is to improve the startup time of your player.
The \playerman\ bootloader is rather slow. With Rockbox in flash, your \dap\
will boot much faster, typically in three to five seconds. Furthermore you
might prefer a clean Rockbox environment, with as little remnants of the
\playerman\ software as possible.
\opt{rombox}{On your \dap\ it is also possible to execute Rockbox directly
  from flash ROM, increasing the amount of free RAM for buffering music. This
  is called \emph{Rombox}.
}

\warn{Flashing your \dap\ is somewhat dangerous, like programming a mainboard
  \emph{BIOS}, \emph{CD/DVD} drive firmware, mobile phone, etc. If the power
  fails, the chip breaks while programming or most of all the programming
  software malfunctions, you'll have a dead box. We take no responsibility of
  any kind, you do that at your own risk. However, we tried as carefully as
  possible to bulletproof this code. There are a lot of sanity checks. If any
  of them fails, it will not program.
}

\opt{ondio}{\warn{After flashing Rockbox, never try to ROLO the \playerman\
    firmware
    \opt{ondiofm}{versions 1.31f or 1.32b! These versions are flash updates
      themselves. If they are}
    \opt{ondiosp}{version 1.32b! This version is a flash update itself.
      If it is}
    applied when Rockbox is flashed, you'll end up with a garbled flash ROM
    and hence a dead box.
}}

There's an ultimate safety net to bring back boxes with even completely
garbled flash content: the \emph{UART} boot mod, which in turn requires the
\emph{serial} mod. With that it's possible to reflash independently from the
outside, even if the flash ROM is completely erased.
\nopt{ondio}{This won't work if you have one of the rare ``ROMless'' boxes. These
  have no boot ROM and boot directly from flash.
}
If the first $\approx$2~KB of the flash ROM are flashed OK, \emph{Minimon} can
be used for the same purpose.

\subsection{Terminology and Basic Operation}

\begin{description}
\item[Firmware:] The flash ROM contents as a whole.
\item[Image:] One operating software started from there.
\end{description}

The replacement firmware contains a bootloader and two images. The first image
is the \emph{permanent} rescue software, to be used in case something is wrong
with the second (main) image. In current firmware files this first image
contains \emph{Bootbox} (see wiki for details). The second image is what is
booted by default. The current firmware files contain a copy of Rockbox 3.2
in the main image. It can easily be updated/replaced later.

The bootloader allows to select which image to run. Pressing
\opt{RECORDER_PAD}{\ButtonFOne}\opt{PLAYER_PAD,ONDIO_PAD}{\ButtonLeft} at boot
selects the first image.
\opt{RECORDER_PAD}{\ButtonFTwo}\opt{PLAYER_PAD}{\ButtonPlay}\opt{ONDIO_PAD}{\ButtonUp}
selects the second image, which will also be booted if you don't press any
button. The button mapping is only there for completeness.
\opt{RECORDER_PAD}{\ButtonFThree}\opt{PLAYER_PAD,ONDIO_PAD}{\ButtonRight}
selects the built-in serial monitor called \emph{Minimon}. You should know this
in case you invoke it by accident. Minimon won't display anything on the
screen. To get out of it, perform a hardware shutdown of your \dap.

\subsection{Initial Flashing Procedure}

You only need to perform this procedure the first time you flash your
\playertype. You may also want to perform it in case the update procedure for
the second image recommends it. In the latter case do not perform the steps
listed under ``Preparation''.

\subsubsection{Preparation}

\nopt{ondio}{
  First, check whether your \playertype\ is flashable at all. Select
  \setting{System $\rightarrow$ Debug (Keep Out!) $\rightarrow$ View HW
  Info}. 
  \opt{lcd_charcell}{Cycle through the displayed values with \ButtonRight /
    \ButtonLeft\ until ``Flash:'' is displayed. If it shows question marks,
  }
  \opt{lcd_bitmap}{Check the values in the line starting with ``Flash:''. If it
    shows question marks after ``M='' and ``D='',
  }
  you're out of luck, your \dap\ is not flashable without modifying the
  hardware. You can stop here. Sorry.
}

\nopt{ondio}{If your \dap\ is flashable, you}\opt{ondio}{You} should perform a
backup of the current flash ROM contents, in case you want to restore it later.
Select \setting{System $\rightarrow$ Debug (Keep Out!) $\rightarrow$ Dump ROM
contents}. You'll notice a few seconds of disk activity. When you connect your
\dap\ to the PC afterwards, you'll find two files in the root of your \dap.
Copy the 256~KB-sized file named \fname{internal\_rom\_2000000-203FFFF.bin} to
a safe place.

\subsubsection{Flashing}

\begin{enumerate}
\item Download the correct package for your \dap\ from
  \url{http://download.rockbox.org/bootloader/archos/}. It is named
  \fname{flash-{\textless}model{\textgreater}-{\textless}version{\textgreater}.zip}.
  The current packages are v3.
\item Unzip the flash package to the root of your \dap.
  \nopt{ondio}{This will extract two files to the root,
    \fname{firmware\_{\textless}model{\textgreater}.bin} and
    \fname{firmware\_{\textless}model{\textgreater}\_norom.bin}.
    \opt{recorder,recorderv2fm}{(The {\textless}model{\textgreater} part is
      slighty different from that in the .zip file name.)
    }
    The flash plugin will select the correct one for your \dap.
  }
  \opt{ondio}{This will extract one file to the root,
    \fname{firmware\_{\textless}model{\textgreater}.bin}.
  }
  Now safely disconnect USB.
\item
  \nopt{ondio}{Make sure your batteries are in good shape and fully charged.}
  \opt{ondio}{Make sure you use a set of fresh batteries.}
  Flashing doesn't need more power than normal operation, but you don't want
  your \dap\ to run out of power while flashing.
\item Select \setting{Plugins $\rightarrow$ Applications}, and run the
  \fname{firmware\_flash} plugin. It will tell you about your flash and
  which file it is going to program. After pressing
  \opt{RECORDER_PAD}{\ButtonFOne}\opt{PLAYER_PAD}{\ButtonMenu}\opt{ONDIO_PAD}{\ButtonLeft}
  it will check the file. If the file is OK, pressing
  \opt{RECORDER_PAD}{\ButtonFTwo}\opt{PLAYER_PAD}{\ButtonOn}\opt{ONDIO_PAD}{\ButtonUp}
  will give you a big warning. If we still didn't manage to scare you off, you
  need to press 
  \opt{RECORDER_PAD}{\ButtonFThree}\opt{PLAYER_PAD,ONDIO_PAD}{\ButtonRight}
  to actually program and verify. The programming takes just a few seconds.
\item In the unlikely event that the programming or verify steps should give
  you any error, \emph{do not switch off the box!} Otherwise you'll have seen
  it working for the last time. While Rockbox is still in RAM and operational,
  we could upgrade the plugin via USB and try again. If you switch it off,
  it's gone.
\end{enumerate}

\note{After successful flashing you may delete the \fname{.bin} files from the
  root of your \dap.
}

\note{There are no separate flash packages for {\dap}s modified to have 8~MB
  of RAM. You need to use the corresponding package for non-modified
  \playertype. You should then install a Rockbox image that makes use of all
  available RAM as described in the following section.
}

\subsection{Updating the Rockbox Image in Flash}

When Rockbox is booted from flash, it does not check for an updated firmware
on disk. This is one of the reasons why it boots faster than the \playerman\
firmware. It means that whenever you update Rockbox, you also need to update
the image in the flash. This is a simple and safe procedure:

\begin{enumerate}
\item Download (or build) the Rockbox build you want to use, and unzip it to
  the root of your \dap. Safely disconnect USB.
\item ROLO into the new Rockbox version.
\item Go to the file browser, and enter the \fname{.rockbox} directory (you
  might need to set the \setting{File View} option to \setting{All}.)
\item Play the file \fname{rockbox.ucl}\opt{rombox}{, or preferably
  \fname{rombox.ucl}}, and follow the instructions. The plugin handling
  this is \fname{rockbox\_flash}, a viewer plugin.
\end{enumerate}

\subsection{Restoring the Original Flash ROM Contents}

In case you ever want to restore the original flash contents, you will need
the backup file. The procedure is very similar to initial flashing, with the
following differences:

\begin{enumerate}
\item Check that you do not have any \fname{firmware\_*.bin} files in your
  \dap's root.
\item Select \setting{Plugins $\rightarrow$ Applications}, and run the
  \fname{firmware\_flash} plugin. Write down the filename it displays in the
  first screen, then exit the plugin.
\item Connect USB, and copy the flash ROM backup file to the root of your
  \dap. \emph{Only use the backup file from that very box, otherwise you're
  asking for trouble!} Rename the file so that it matches the name requested
  by the \fname{firmware\_flash} plugin. Safely disconnect USB.
\end{enumerate}

Now follow the instructions given for initial flashing, starting with step 3.