manual: add the iPod Nano 3G

Adds the platform file, modelled on the Nano 2G's and the iPod
Classic's, and corrects the supported-versions text shared by the Nano
manuals, which said Rockbox does not run on the third generation.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Change-Id: Ie6290d67ae113086cb8a63c825eb9db9544c1d49

manual/getting_started/installation.tex

@@ -10,17 +10,27 @@ before beginning there are a few important things to know.
 follow the instructions at
 \wikilink{SansaE200RInstallation}.}}
 
-\opt{ipodnano,ipodnano2g,ipodvideo,ipod6g,e200,c200,c200v2,e200v2,clipv1,clipv2,cowond2,fuze,fuzev2}{
+\opt{ipodnano,ipodnano2g,ipodnano3g,ipodvideo,ipod6g,e200,c200,c200v2,e200v2,clipv1,clipv2,cowond2,fuze,fuzev2}{
 \begin{description}
 \item[Supported hardware versions.]
-    \opt{ipodnano,ipodnano2g}{
+    \opt{ipodnano,ipodnano2g,ipodnano3g}{
     The \playertype{} is available in multiple versions, not
-    all of which run Rockbox.  Rockbox presently runs only on
-    the first and second generation iPod Nano. Rockbox does
-    \emph{not} run on the third, fourth or fifth generation iPod Nano.
+    all of which run Rockbox.  Rockbox presently runs on the first,
+    second and third generation iPod Nano. Rockbox does
+    \emph{not} run on the fourth, fifth, sixth or seventh generation
+    iPod Nano.
     For information on identifying which iPod you own, see this page on
     Apple's website: \url{http://www.info.apple.com/kbnum/n61688}.
   }
+  \opt{ipodnano3g}{
+    The \playertype{} referred to by this manual is the third generation
+    model, the short and wide one with a \dapdisplaywidth{}x%
+    \dapdisplayheight{} screen. It came with 4GB and 8GB of flash storage.
+    Apple fitted several different NAND chips, and Rockbox so far supports
+    the models with Hynix NAND, 4GB and 8GB: on any other chip the
+    bootloader says so and starts Apple's firmware instead. The
+    installation section below says how to have your player's chip added.
+  }
   \opt{ipodvideo}{
     The \playertype{} is the 5th/5.5th generation \playerman{} only.
     For information on identifying which iPod you own, see this page on Apple's
@@ -349,7 +359,7 @@ It is also worth noting that data transfer rates are not likely to be improved w
   \end{itemize}
 }
 
-\opt{gigabeats,fiiom3k,shanlingq1}{
+\opt{gigabeats,fiiom3k,shanlingq1,ipodnano3g}{
   \note{The automated install is not yet available for the
   \playerlongtype{}. For now you can use the manual method to install Rockbox.
   Please still read the section on the automatic install as it explains
@@ -674,10 +684,12 @@ by Rockbox, in the main directory of your \daps{} drive.
         \opt{iriverh100,iriverh300}{\input{getting_started/iriver_install.tex}}
         \opt{mpiohd200,mpiohd300}{\input{getting_started/mpio_install.tex}}
         \opt{ipod}{
-          \nopt{ipod6g} {
+          \nopt{ipod6g,ipodnano3g} {
             \input{getting_started/ipod_install.tex}}
           \opt{ipod6g} {
-            \input{getting_started/ipod6g_install.tex}} }
+            \input{getting_started/ipod6g_install.tex}}
+          \opt{ipodnano3g} {
+            \input{getting_started/ipodnano3g_install.tex}} }
         \opt{iaudio}{\input{getting_started/iaudio_install.tex}}
         \opt{iriverh10,iriverh10_5gb}{\input{getting_started/h10_install.tex}}
         \opt{gigabeatf}{\input{getting_started/gigabeat_install.tex}}
@@ -934,10 +946,16 @@ completely follow the manual uninstallation instructions below.}}
 }
 
 \optv{ipod}{
+  \nopt{ipodnano3g}{
   To uninstall Rockbox and go back to using just the original iPod software, connect
   the \dap{} to your computer and follow the instructions to install
   the bootloader but, when prompted by ipodpatcher, enter \texttt{u} for uninstall
   instead of \texttt{i} for install.
+  }
+  \opt{ipodnano3g}{
+    Follow the DFU-mode steps above, then run
+    \fname{mks5lboot --bl-uninst ipodnano3g} to remove the bootloader.
+  }
 }
 
 \opt{iaudiom3,iaudiom5,iaudiox5}{

manual/getting_started/ipodnano3g_install.tex

@@ -0,0 +1,40 @@
+The third generation iPod Nano uses a DFU installer, \fname{mks5lboot},
+to install the bootloader in flash. Do not use \fname{ipodpatcher}.
+
+\warn{Rockbox supports the Nano 3G models fitted with Hynix NAND, the
+4~GB A514D3AD and the 8~GB A555D5AD. Apple fitted several other NAND
+chips to this player. Rockbox drives only chips that have been tested on
+hardware: on any other chip the bootloader says the NAND is not supported
+and starts Apple's firmware instead, leaving the player's storage
+untouched. The port is experimental: Apple's proactive
+refresh of blocks needing ECC correction is not implemented, and
+bad-block remapping has not been exercised on hardware. Keep a backup of
+all media.}
+
+If your player has another chip, you can help have it added. The NAND check in \fname{utils/ipodnano3g/nandcheck} of the
+source tree runs from DFU mode, installs nothing, writes nothing to the
+player, and collects what validating the chip needs: see that
+directory's \fname{README.md}.
+
+\caps{Rockbox Utility} can install the bootloader. To install it by hand
+instead, follow the steps below.
+
+Use \fname{mks5lboot} built from Rockbox sources
+with Nano 3G support, and the Nano 3G bootloader
+\fname{bootloader-ipodnano3g.ipod}. Older iPod Classic installers do not
+support this player. Build instructions and USB driver requirements are
+in \fname{utils/mks5lboot/README} in the source tree.
+
+\begin{enumerate}
+\item Install the Rockbox files on the player's FAT32 volume before
+installing the bootloader.
+\item Connect the player by USB. Close iTunes and stop iTunesHelper if
+they are running.
+\item Run \fname{mks5lboot --dfuscan --loop} in a terminal, then put the
+player in
+\href{https://freemyipod.org/wiki/Modes#DFU_mode}{DFU mode}.
+When it is detected, stop the scan with Ctrl+C.
+\item Run \fname{mks5lboot --bl-inst path/to/bootloader-ipodnano3g.ipod},
+replacing the path with the location of your Nano 3G bootloader.
+\item Wait for the installer to finish and the player to restart.
+\end{enumerate}

manual/platform/ipodnano3g.tex

@@ -0,0 +1,24 @@
+\def\UseOption{ipodnano3g}
+\edef\UseOption{\UseOption,HAVE_RB_BL_IN_FLASH}
+\edef\UseOption{\UseOption,IPOD_4G_PAD}
+\edef\UseOption{\UseOption,HAVE_BACKLIGHT}
+\edef\UseOption{\UseOption,ipod}
+
+\newcommand{\playerman}{Ipod}
+\newcommand{\playertype}{Nano}
+\newcommand{\playerlongtype}{\playertype{} 3rd generation}
+\newcommand{\dapdisplaywidth}{320}
+\newcommand{\dapdisplayheight}{240}
+\newcommand{\dapdisplaydepth}{16}
+\newcommand{\specimg}{ipodnano3g}
+%Used to name the player, e.g. ...to the \dap
+\newcommand{\dap}{player}
+%For use when referring to the player. E.g. the \daps\ capacity ...
+\newcommand{\daps}{player's}
+\newcommand{\firmwarefilename}{\fname{rockbox.ipod}}
+\newcommand{\firmwareextension}{\fname{ipod}}
+\newcommand{\screenshotsize}{8cm}
+\newcommand{\disk}{flash storage}
+
+% link external keymap file
+\input{platform/keymap-ipod4g.tex}

manual/rockbox_interface/main.tex

@@ -630,7 +630,7 @@ To turn on and off your Rockbox enabled \dap{} use the following keys:
   {
   \subsection{Starting the original firmware}
   \label{ref:Dualboot}
-  \opt{ipod4g,ipodcolor,ipodvideo,ipodnano,ipodnano2g,ipodmini}
+  \opt{ipod4g,ipodcolor,ipodvideo,ipodnano,ipodnano2g,ipodnano3g,ipodmini}
     {
     Rockbox has a dual-boot feature. To boot into the original firmware, shut
     down the device as described above. Turn on the \ButtonHold{} switch