Add Fiio M3K and Shanling Q1 manuals

Includes installation instructions and a description of Rockbox's
limitations versus the original firmware. Some things are still
missing, notably screenshots for the Q1. The M3K image also needs
to be updated to include the 'select' button.

Change-Id: Ib533206df01925203edeccdd75e1bf22f407e794

8 files changed, 482 insertions, 7 deletions

diff --git a/manual/advanced_topics/main.tex b/manual/advanced_topics/main.tex
index f1d1de69a1..940852d593 100755
--- a/manual/advanced_topics/main.tex
+++ b/manual/advanced_topics/main.tex
@@ -667,6 +667,8 @@ You just ``play'' a file with the extension %
 \opt{sansa,iriverh10,iriverh10_5gb,mrobe100,vibe500,samsungyh}{\fname{.mi4}.} %
 \opt{sansaAMS,fuzeplus}{\fname{.sansa}.} %
 \opt{gigabeatf,gigabeats}{\fname{.gigabeat}.} %
+\opt{fiiom3k}{\fname{.m3k}} %
+\opt{shanlingq1}{\fname{.q1}} %
 This can be used to test new firmware versions without deleting your
 current version.
 
diff --git a/manual/getting_started/installation.tex b/manual/getting_started/installation.tex
index 241c41d3f2..cc0c7af919 100644
--- a/manual/getting_started/installation.tex
+++ b/manual/getting_started/installation.tex
@@ -111,7 +111,36 @@ follow the instructions at
 \end{description}
 }
 
-\nopt{gigabeats}{
+\opt{fiiom3k,shanlingq1}{
+Although Rockbox is considered fully functional on the \playername{}, there are
+a few limitations compared to the original firmware which you should be aware
+of before installing.
+\begin{description}
+  \item[Filesystem support.] Rockbox only supports the FAT32 filesystem. Other
+    filesystems such as exFAT or NTFS are not supported.
+  \item[USB DAC.] This feature is not supported by Rockbox, but you can
+    dual-boot the original firmware if you want to use it.
+  \opt{shanlingq1}{\item[Wireless.] There is no support for Bluetooth or WiFi.
+    You can dual-boot the original firmware to use wireless functionality.}
+  \item[Hotswapping SD cards.] Rockbox runs from the SD card, not the internal
+    flash memory. Hotswapping is technically possible, but you need to install
+    the same version of Rockbox to each SD card.
+
+    Some features might not work correctly after hotswapping and you may
+    experience crashes or instability. Removing the SD card while data is being
+    written is liable to cause crashes and data loss, and possibly corrupt your
+    filesystem.
+  \opt{shanlingq1}{\item[Touchscreen.] There is only basic touchscreen support.
+    Further work is required to make the UI more usable with a touchscreen in
+    general.
+    \note{The touchscreen can be used in two modes, either a 3$\times$3 grid mode
+      which divides the screen into areas to emulate a set of physical
+      buttons (the default setting), or ``absolute point'' mode where the
+      touchscreen is used to point to items on the screen.\\}}
+\end{description}
+}
+
+\nopt{gigabeats,fiiom3k,shanlingq1}{
 \begin{description}
 
 \nopt{ipod1g2g}{
@@ -237,7 +266,8 @@ people. Rockbox Utility is a graphical application that does almost everything
 for you. However, should you encounter a problem, then the manual way is
 still available to you.\\
 
-\opt{gigabeats}{\note{The automated install is not yet available for the
+\opt{gigabeats,fiiom3k,shanlingq1}{
+  \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
   various important aspects of Rockbox, such as the different versions
@@ -312,9 +342,9 @@ housekeeping tool \caps{Rockbox Utility}. It allows you to:
 Prebuilt binaries for Windows, Linux and Mac OS X are
 available at the \wikilink{RockboxUtility} wiki page.\\
 
-\opt{gigabeats,ondavx777}{\note{Rockbox Utility does not currently support the
-\playertype{} and you will therefore need to follow the manual install
-instructions below.\\}}
+\opt{gigabeats,ondavx777,fiiom3k,shanlingq1}{
+\note{Rockbox Utility does not currently support the \playertype{} and you will
+therefore need to follow the manual install instructions below.\\}}
 
 When first starting \caps{Rockbox Utility} run ``Autodetect'',
 found in the configuration dialog (File $\rightarrow$ Configure). Autodetection
@@ -514,6 +544,7 @@ by Rockbox, in the main directory of your \daps{} drive.
         \opt{IMX233}{\input{getting_started/IMX233_install.tex}}
         \opt{samsungyh}{\input{getting_started/samsungyh_install.tex}}
         \opt{xduoox3}{\input{getting_started/xduoox3_install.tex}}
+        \opt{fiiom3k,shanlingq1}{\input{getting_started/jztool_install.tex}}
     }
 }
 
@@ -609,6 +640,9 @@ by Rockbox, in the main directory of your \daps{} drive.
 }
 \opt{e200}{Your e200 will automatically reboot and Rockbox should load.}
 
+\opt{fiiom3k,shanlingq1}{
+  Safely eject / unmount your \dap{}.
+}
 
 
 \subsection{Enabling Speech Support (optional)}\label{sec:enabling_speech_support}
@@ -772,11 +806,25 @@ completely follow the manual uninstallation instructions below.}}
     \playerman{} firmware.
 }
 
+\opt{fiiom3k,shanlingq1}{
+    If you want to remove the Rockbox bootloader, copy an original firmware
+    update to your microSD card and run the \playerman{} update by holding
+    \ActionBootOFRecovery{} while powering on the \dap{}.
+
+    Alternatively, if you took a backup of the original \playerman{} bootloader
+    you can copy the backup file, \bootbackupfilename{}, to your SD card and
+    select \emph{Restore bootloader} from the recovery menu. The recovery menu
+    can be accessed by holding \ActionBootRecoveryMenu{} when powering on. If
+    your \dap won't boot, use \fname{jztool} to load the bootloader over USB
+    and enter the recovery menu -- see \reference{ref:jztool_load_bootloader}.
+}
+
 \nopt{gigabeats}{
   If you wish to clean up your disk, you may also wish to delete the
   \fname{.rockbox} directory and its contents.
-  \nopt{iaudiom3,iaudiom5,iaudiox5}{Turn the \playerman{} off.
-    Turn the \dap{} back on and the original \playerman{} software will load.}
+  \nopt{iaudiom3,iaudiom5,iaudiox5,fiiom3k,shanlingq1}{
+    Turn the \playerman{} off. Turn the \dap{} back on and the original
+    \playerman{} software will load.}
 }
 
 \opt{gigabeats}{
diff --git a/manual/getting_started/jztool_install.tex b/manual/getting_started/jztool_install.tex
new file mode 100644
index 0000000000..c492b6987e
--- /dev/null
+++ b/manual/getting_started/jztool_install.tex
@@ -0,0 +1,156 @@
+You need a computer running Windows, Linux, or Mac to install the bootloader.
+The installation utility \fname{jztool} is a command line tool used to load the
+Rockbox bootloader on your \dap{}. Please note that it \emph{only} loads the
+Rockbox bootloader and does not modify your \dap{} in any way. Flashing the
+bootloader happens entirely on the \dap{}, without the intervention of your PC.
+
+It's possible to install Rockbox alongside any original firmware version.
+\opt{fiiom3k}{This includes the ``unofficial'' XVortex firmware.}
+It's also possible to update the original firmware after installing the Rockbox
+bootloader, but this will erase the Rockbox bootloader and you will have to
+install it again if you want to keep using Rockbox.
+
+\begin{itemize}\label{ref:jztool_load_bootloader}
+\item Download the Rockbox bootloader, \bootfilename{}, from
+  \opt{fiiom3k}{\download{bootloader/fiio/m3k/}.}
+  \opt{shanlingq1}{\download{bootloader/shanling/q1/}.}
+\item Download \fname{jztool} from \download{bootloader/fiio/m3k/}.
+\item Connect your player in USB boot mode:
+  \begin{enumerate}
+    \item Make sure your player is fully powered off.
+    \item Connect a USB cable to your player -- but don't plug it in to your
+      computer yet!
+    \item While holding the \ActionIngenicUSBBoot{} button, plug the other end
+      of the USB cable into your computer.
+    \item If your player has entered USB boot mode%
+      \opt{fiiom3k}{the button light will light up and the LCD will remain
+        black. The \playerman{} splash screen will not be displayed.}
+      \opt{shanlingq1}{the LCD will remain black and the \playerman{} splash
+        screen will not be displayed.}
+  \end{enumerate}
+\item Windows users need to follow \reference{ref:install_usb_driver} now
+  to make the \playertype{} accessible to \fname{jztool} before continuing.
+\item Open a command prompt or terminal in the folder where you downloaded
+  \fname{jztool}. Copy \bootfilename{} to that folder so you can easily refer
+  to it on the command line.
+
+  On Windows, run this command to load the bootloader onto your \dap{}.
+  \begin{code}
+    jztool.exe \jztoolsubcommand{} load \bootfilename{}
+  \end{code}
+  Linux or Mac users should run this command. Linux users need to run
+  \fname{jztool} as root to allow it access the USB device.
+  \begin{code}
+    ./jztool \jztoolsubcommand{} load \bootfilename{}
+  \end{code}
+\item If your \dap{} is showing the Rockbox recovery menu, then the Rockbox
+  bootloader has been loaded correctly.
+  % TODO: Screenshot of the recovery menu
+\end{itemize}
+
+To finish the install, you need to flash the Rockbox bootloader to your \dap{}
+using the recovery menu.
+
+\begin{itemize}
+\item Copy \bootfilename{} to the root of a FAT32-formatted SD card, and insert
+  it into your \dap{}.
+\item Select \emph{Backup bootloader} to back up the original firmware's
+  bootloader. This will create a file \bootbackupfilename{} on the root of your
+  SD card. You should back up this file somewhere safe before continuing with
+  the installation. In the unlikely event anything goes wrong, you can copy
+  \bootbackupfilename{} onto your SD card and choose \emph{Restore bootloader}
+  to restore the original \playerman{} bootloader.
+\item Select \emph{Install/update bootloader} from the menu. The installation
+  takes less than a second and once it has finished successfully, you can
+  unplug and power off your \dap{}.
+\end{itemize}
+
+Rarely, a new bootloader might be released to fix bugs or add certain features.
+Updating the bootloader follows the same process as the initial installation.
+Taking a backup is not necessary if you are only updating an existing Rockbox
+bootloader.
+
+Normally the installation will complete without incident, but you may encounter
+one of the following errors. Some are benign and easily corrected while others
+are more serious. You should seek help on one of the Rockbox support channels
+if you get a serious error.
+
+\begin{description}
+\item[File not found.]
+  If you selected \emph{Install/update bootloader}, the missing file is
+  \bootfilename{}; if you selected \emph{Restore bootloader}, the missing file
+  is \bootbackupfilename{}. Copy the missing file to your SD card, and make
+  sure your card is formatted to FAT32, then try again.
+\item[Bad archive.]
+  The file \bootfilename{} appears to be corrupted or doesn't contain the
+  expected contents. Try deleting it from your SD card and copying it again.
+  If the error persists, you might have a corrupted download; try downloading
+  the bootloader again.
+\item[NAND open/read/write error.]
+  This indicates a problem accessing your \daps{} internal flash memory.
+  Write errors are the most serious -- your existing bootloader may be
+  corrupted, leaving your \dap{} unbootable. Seek assistance if you encounter
+  any of these errors \emph{before} retrying the installation.
+\item[Disk I/O error.]
+  There was a problem reading or writing data on the SD card. This message can
+  also be displayed by \emph{Restore bootloader} if the backup file
+  \bootbackupfilename{} does not have the correct size.
+\item[Out of memory or Unknown error.]
+  These are serious errors indicating some low-level system problem.
+  They should never be encountered in normal circumstances.
+\end{description}
+
+\subsubsection{Install the USB driver}\label{ref:install_usb_driver}
+\note{This section is only applicable if you are running \fname{jztool} from
+a Windows computer. Linux and Mac users can safely ignore this section.}
+
+To use \fname{jztool} on a Windows computer, you need to install a USB driver
+so it can access the \dap{} in USB boot mode. \fname{jztool} uses a library
+called \fname{libusb} to access your \dap{}, and on Windows \fname{libusb} can
+use a number of different back-end drivers to access USB devices.
+
+Zadig (\url{https://zadig.akeo.ie/}) is a third-party tool which allows you to
+install various back-end drivers for use with \fname{libusb}-based programs.
+The recommended driver is WinUSB, which is provided by Microsoft and comes
+bundled with recent versions of Windows.
+
+\note{The Rockbox project is not associated with Zadig or its development.
+  In the unlikely event you encounter a Zadig-specific issue that cannot be
+  resolved on Rockbox support channels you may need to seek help elsewhere.}
+
+You will need administrator access to run Zadig. When you are ready, follow the
+steps below to install the driver.
+
+\begin{itemize}
+\item Download Zadig from \url{https://zadig.akeo.ie/}.
+\item Make sure your \dap{} is connected in USB boot mode
+  (see \reference{ref:jztool_load_bootloader}).
+\item Run Zadig and select the USB device corresponding to your player.
+  The USB ID of the \playername{} is \texttt{A108 1000} when it is connected in
+  USB boot mode.
+  % TODO: Screenshot of Zadig window
+  \warn{Be careful not to select the wrong USB device in Zadig! Zadig allows
+    you to override the USB driver of any USB device, and accidentally
+    overwriting the driver for an important device like your mouse or keyboard
+    can cause major problems. Always double check the device before clicking
+    install.}
+\item Select the WinUSB driver from the list and click \emph{Install}.
+\item Wait for the installation to finish, then close Zadig.
+\end{itemize}
+
+If the installation was successful you can return to
+\reference{ref:jztool_load_bootloader} and run \fname{jztool}. If you get
+``Cannot open USB device'' errors from \fname{jztool} or any
+\fname{libusb}-related errors, you can try some of the steps below to fix the
+problem.
+
+\begin{itemize}
+\item Unplug your \dap{} and force a power-off by holding the power button
+  for 10 seconds. Then reconnect it and try running \fname{jztool} again.
+\item Restart your computer and try again.
+\item Try installing a different USB driver, for example ``libusbK''.
+  Some users have reported difficulties with the WinUSB driver and have
+  had success by trying an alternate driver.
+\end{itemize}
+
+If problems persist you should ask for help on the Rockbox support channels.
diff --git a/manual/platform/fiiom3k.tex b/manual/platform/fiiom3k.tex
new file mode 100644
index 0000000000..0f44683214
--- /dev/null
+++ b/manual/platform/fiiom3k.tex
@@ -0,0 +1,28 @@
+% $Id$ %
+\def\UseOption{fiiom3k}
+\edef\UseOption{\UseOption,FIIO_M3K_PAD}
+\edef\UseOption{\UseOption,HAVE_BACKLIGHT}
+\edef\UseOption{\UseOption,HAVE_RB_BL_IN_FLASH}
+\edef\UseOption{\UseOption,fiiom3k}
+
+\newcommand{\playerman}{FiiO}
+\newcommand{\playertype}{M3K}
+\newcommand{\playerlongtype}{\playertype}
+\newcommand{\dapdisplaywidth}{240}
+\newcommand{\dapdisplayheight}{320}
+\newcommand{\dapdisplaydepth}{16}
+\newcommand{\specimg}{fiiom3k}
+%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.m3k}}
+\newcommand{\bootfilename}{\fname{bootloader.m3k}}
+\newcommand{\firmwareextension}{\fname{m3k}}
+\newcommand{\bootbackupfilename}{\fname{fiiom3k-boot.bin}}
+\newcommand{\jztoolsubcommand}{fiiom3k}
+\newcommand{\screenshotsize}{8cm}
+\newcommand{\disk}{SD card}
+
+% link external keymap file
+\input{platform/keymap-fiiom3k.tex}
diff --git a/manual/platform/keymap-fiiom3k.tex b/manual/platform/keymap-fiiom3k.tex
new file mode 100644
index 0000000000..ecf07bebd4
--- /dev/null
+++ b/manual/platform/keymap-fiiom3k.tex
@@ -0,0 +1,100 @@
+% $Id$
+
+\newcommand{\ButtonPower}{\btnfnt{Power}}
+\newcommand{\ButtonPlay}{\btnfnt{Play}}
+\newcommand{\ButtonVolUp}{\btnfnt{Volume Up}}
+\newcommand{\ButtonVolDown}{\btnfnt{Volume Down}}
+\newcommand{\ButtonUp}{\btnfnt{Up}}
+\newcommand{\ButtonDown}{\btnfnt{Down}}
+\newcommand{\ButtonLeft}{\btnfnt{Prev}}
+\newcommand{\ButtonRight}{\btnfnt{Next}}
+\newcommand{\ButtonSelect}{\btnfnt{Select}}
+\newcommand{\ButtonBack}{\btnfnt{Back}}
+\newcommand{\ButtonMenu}{\btnfnt{Menu}}
+\newcommand{\ButtonScrollFwd}{\btnfnt{Scroll Down}}
+\newcommand{\ButtonScrollBack}{\btnfnt{Scroll Up}}
+
+%Button actions, standard context
+\newcommand{\ActionStdPrev}{\ButtonUp{} or \ButtonScrollBack}
+\newcommand{\ActionStdPrevRepeat}{\ButtonUp{} or \ButtonScrollBack}
+\newcommand{\ActionStdNext}{\ButtonDown{} or \ButtonScrollFwd}
+\newcommand{\ActionStdNextRepeat}{\ButtonDown{} or \ButtonScrollFwd}
+\newcommand{\ActionStdOk}{\ButtonSelect}
+\newcommand{\ActionStdCancel}{\ButtonBack}
+\newcommand{\ActionStdContext}{\ButtonMenu{} or Long \ButtonSelect}
+\newcommand{\ActionStdMenu}{Long \ButtonBack}
+\newcommand{\ActionStdQuickScreen}{Long \ButtonMenu}
+\newcommand{\ActionQuickScreenExit}{\ButtonBack{}, \ButtonPower{}, or \ButtonSelect}
+\newcommand{\ActionStdUsbCharge}{\ButtonPlay}
+
+%Button actions, wps context
+\newcommand{\ActionWpsStop}{Long \ButtonPower}
+\newcommand{\ActionWpsBrowse}{Long \ButtonBack}
+\newcommand{\ActionWpsVolUp}{\ButtonVolUp}
+\newcommand{\ActionWpsVolDown}{\ButtonVolDown}
+\newcommand{\ActionWpsSkipPrev}{\ButtonLeft}
+\newcommand{\ActionWpsSkipNext}{\ButtonRight}
+\newcommand{\ActionWpsSeekBack}{Long \ButtonLeft}
+\newcommand{\ActionWpsSeekFwd}{Long \ButtonRight}
+\newcommand{\ActionWpsPlay}{\ButtonPlay{} or \ButtonSelect}
+\newcommand{\ActionWpsContext}{\ButtonMenu}
+\newcommand{\ActionWpsMenu}{\ButtonBack}
+\newcommand{\ActionWpsQuickScreen}{Long \ButtonMenu}
+\newcommand{\ActionWpsHotkey}{Long \ButtonPlay}
+\newcommand{\ActionWpsAbSetAPrevDir}{Long \ButtonUp}
+\newcommand{\ActionWpsAbSetBNextDir}{Long \ButtonDown}
+\newcommand{\ActionWpsAbReset}{Long \ButtonSelect}
+
+%Button actions, tree context
+\newcommand{\ActionTreeWps}{Long \ButtonBack}
+\newcommand{\ActionTreeStop}{Long \ButtonPlay}
+\newcommand{\ActionTreeParentDirectory}{\ButtonBack}
+\newcommand{\ActionTreeEnter}{\ButtonSelect}
+\newcommand{\ActionTreeHotkey}{\ButtonPlay}
+
+%Button actions, YesNo context
+\newcommand{\ActionYesNoAccept}{\ButtonPlay{} or \ButtonSelect}
+
+%Button actions, Virtual Keyboard Context
+\newcommand{\ActionKbdSelect}{\ButtonSelect}
+\newcommand{\ActionKbdUp}{\ButtonUp}
+\newcommand{\ActionKbdDown}{\ButtonDown}
+\newcommand{\ActionKbdLeft}{\ButtonLeft}
+\newcommand{\ActionKbdRight}{\ButtonRight}
+\newcommand{\ActionKbdPageFlip}{\ButtonMenu}
+\newcommand{\ActionKbdDone}{\ButtonPlay}
+\newcommand{\ActionKbdAbort}{\ButtonPower}
+
+%Button actions, Pitch Screen context
+\newcommand{\ActionPsToggleMode}{\ButtonSelect}
+\newcommand{\ActionPsIncSmall}{\ButtonUp{} or \ButtonScrollBack}
+\newcommand{\ActionPsDecSmall}{\ButtonDown{} or \ButtonScrollFwd}
+\newcommand{\ActionPsIncBig}{\ButtonVolUp}
+\newcommand{\ActionPsDecBig}{\ButtonVolDown}
+\newcommand{\ActionPsNudgeLeft}{\ButtonLeft}
+\newcommand{\ActionPsNudgeRight}{\ButtonRight}
+\newcommand{\ActionPsReset}{Long \ButtonSelect}
+\newcommand{\ActionPsExit}{\ButtonPower}
+\newcommand{\ActionPsFaster}{\ButtonBack}
+\newcommand{\ActionPsSlower}{\ButtonMenu}
+
+%Button actions, Bookmark screen context
+\newcommand{\ActionBmDelete}{\ButtonPlay}
+
+%Plugin lib actions
+\newcommand{\PluginUp}{\ButtonUp}
+\newcommand{\PluginDown}{\ButtonDown}
+\newcommand{\PluginLeft}{\ButtonLeft}
+\newcommand{\PluginRight}{\ButtonRight}
+\newcommand{\PluginSelect}{\ButtonSelect}
+\newcommand{\PluginSelectRepeat}{Long \ButtonSelect}
+\newcommand{\PluginCancel}{\ButtonBack}
+\newcommand{\PluginExit}{\ButtonPower}
+\newcommand{\PluginScrollFwd}{\ButtonScrollFwd}
+\newcommand{\PluginScrollBack}{\ButtonScrollBack}
+
+%Bootloader keys
+\newcommand{\ActionIngenicUSBBoot}{\ButtonVolDown}
+\newcommand{\ActionBootRecoveryMenu}{\ButtonVolUp}
+\newcommand{\ActionBootOFPlayer}{\ButtonPlay}
+\newcommand{\ActionBootOFRecovery}{\ButtonPlay{} and \ButtonVolUp}
diff --git a/manual/platform/keymap-shanlingq1.tex b/manual/platform/keymap-shanlingq1.tex
new file mode 100644
index 0000000000..9476ca8a70
--- /dev/null
+++ b/manual/platform/keymap-shanlingq1.tex
@@ -0,0 +1,95 @@
+% $Id$
+
+\newcommand{\ButtonPower}{\btnfnt{Power}}
+\newcommand{\ButtonPlay}{\btnfnt{Play}}
+\newcommand{\ButtonVolUp}{\btnfnt{Volume Up}}
+\newcommand{\ButtonVolDown}{\btnfnt{Volume Down}}
+\newcommand{\ButtonPrev}{\btnfnt{Previous}}
+\newcommand{\ButtonNext}{\btnfnt{Next}}
+
+%Button actions, standard context
+\newcommand{\ActionStdPrev}{\ButtonPrev{} or \TouchActionStdPrev}
+\newcommand{\ActionStdPrevRepeat}{Long \ButtonPrev{} or \TouchActionStdPrevRepeat}
+\newcommand{\ActionStdNext}{\ButtonNext{} or \TouchActionStdNext}
+\newcommand{\ActionStdNextRepeat}{Long \ButtonNext{} or \TouchActionStdNextRepeat}
+\newcommand{\ActionStdCancel}{\ButtonPower{} or \TouchActionStdCancel}
+\newcommand{\ActionStdContext}{\TouchActionStdContext}
+\newcommand{\ActionStdQuickScreen}{\TouchActionStdQuickScreen}
+\newcommand{\ActionQuickScreenExit}{\TouchActionQuickScreenExit}
+\newcommand{\ActionStdMenu}{\TouchActionStdMenu}
+\newcommand{\ActionStdOk}{\ButtonPlay{} or \TouchActionStdOk}
+\newcommand{\ActionStdUsbCharge}{\ButtonPlay}
+
+%Button actions, wps context
+\newcommand{\ActionWpsPlay}{\ButtonPlay{} or \TouchActionWpsPlay}
+\newcommand{\ActionWpsSkipNext}{\ButtonNext{} or \TouchActionWpsSkipNext}
+\newcommand{\ActionWpsSeekFwd}{Long \ButtonNext{} \TouchActionWpsSeekFwd}
+\newcommand{\ActionWpsSkipPrev}{\ButtonPrev{} or \TouchActionWpsSkipPrev}
+\newcommand{\ActionWpsSeekBack}{Long \ButtonPrev{} or \TouchActionWpsSeekBack}
+\newcommand{\ActionWpsStop}{Long \ButtonPlay{} or \TouchActionWpsStop}
+\newcommand{\ActionWpsVolDown}{\ButtonVolDown{} or \TouchActionWpsVolDown}
+\newcommand{\ActionWpsVolUp}{\ButtonVolUp{} or \TouchActionWpsVolUp}
+\newcommand{\ActionWpsQuickScreen}{\TouchActionWpsQuickScreen}
+\newcommand{\ActionWpsMenu}{\TouchActionWpsMenu}
+\newcommand{\ActionWpsContext}{\TouchActionWpsContext}
+\newcommand{\ActionWpsBrowse}{\TouchActionWpsBrowse}
+\newcommand{\ActionWpsPitchScreen}{\TouchActionWpsPitchScreen}
+\newcommand{\ActionWpsIdThreeScreen}{\TouchActionWpsIdThreeScreen}
+\newcommand{\ActionWpsAbSetBNextDir}{\TouchActionWpsAbSetBNextDir}
+\newcommand{\ActionWpsAbSetAPrevDir}{\TouchActionWpsAbSetAPrevDir}
+\newcommand{\ActionWpsAbReset}{\TouchActionWpsAbReset}
+\newcommand{\ActionWpsHotkey}{\TouchBottomRight}
+
+%Button actions, tree context
+\newcommand{\ActionTreeWps}{\TouchActionTreeWps}
+\newcommand{\ActionTreeStop}{\TouchActionTreeStop}
+\newcommand{\ActionTreeEnter}{\TouchActionTreeEnter}
+\newcommand{\ActionTreeParentDirectory}{\TouchActionTreeParentDirectory}
+
+%Button actions, YesNo context
+\newcommand{\ActionYesNoAccept}{\TouchActionYesNoAccept}
+
+%Button actions, Virtual Keyboard Context
+\newcommand{\ActionKbdLeft}{\TouchActionKbdLeft}
+\newcommand{\ActionKbdRight}{\TouchActionKbdRight}
+\newcommand{\ActionKbdSelect}{\TouchActionKbdSelect}
+\newcommand{\ActionKbdDone}{\TouchActionKbdDone}
+\newcommand{\ActionKbdAbort}{\TouchActionKbdAbort}
+\newcommand{\ActionKbdUp}{\TouchActionKbdUp}
+\newcommand{\ActionKbdDown}{\TouchActionKbdDown}
+\newcommand{\ActionKbdCursorLeft}{\TouchActionKbdCursorLeft}
+\newcommand{\ActionKbdCursorRight}{\TouchActionKbdCursorRight}
+\newcommand{\ActionKbdBackSpace}{\TouchActionKbdBackSpace}
+\newcommand{\ActionKbdPageFlip}{\TouchActionKbdPageFlip}
+
+%Button actions, Pitch Screen context
+\newcommand{\ActionPsToggleMode}{\TouchActionPsToggleMode}
+\newcommand{\ActionPsIncSmall}{\TouchActionPsIncSmall}
+\newcommand{\ActionPsIncBig}{\TouchActionPsIncBig}
+\newcommand{\ActionPsDecSmall}{\TouchActionPsDecSmall}
+\newcommand{\ActionPsDecBig}{\TouchActionPsDecBig}
+\newcommand{\ActionPsNudgeLeft}{\TouchActionPsNudgeLeft}
+\newcommand{\ActionPsNudgeRight}{\TouchActionPsNudgeRight}
+\newcommand{\ActionPsReset}{\TouchActionPsReset}
+\newcommand{\ActionPsExit}{\TouchActionPsExit}
+\newcommand{\ActionPsSlower}{\TouchActionPsSlower}
+\newcommand{\ActionPsFaster}{\TouchActionPsFaster}
+
+%Button actions, Bookmark screen context
+\newcommand{\ActionBmDelete}{\TouchActionBmDelete}
+
+%Plugin lib actions
+\newcommand{\PluginUp}{\TouchTopMiddle}
+\newcommand{\PluginDown}{\TouchBottomMiddle}
+\newcommand{\PluginLeft}{\TouchMidLeft}
+\newcommand{\PluginRight}{\TouchMidRight}
+\newcommand{\PluginCancel}{\ButtonPower or \TouchBottomRight}
+\newcommand{\PluginExit}{\ButtonPower}
+\newcommand{\PluginSelect}{\TouchCenter}
+\newcommand{\PluginSelectRepeat}{Long \TouchCenter}
+
+%Bootloader keys
+\newcommand{\ActionIngenicUSBBoot}{\ButtonPlay}
+\newcommand{\ActionBootRecoveryMenu}{\ButtonNext}
+\newcommand{\ActionBootOFPlayer}{\ButtonPrev}
+\newcommand{\ActionBootOFRecovery}{\ButtonPrev{} and \ButtonNext}
diff --git a/manual/platform/shanlingq1.tex b/manual/platform/shanlingq1.tex
new file mode 100644
index 0000000000..a2dc6855dc
--- /dev/null
+++ b/manual/platform/shanlingq1.tex
@@ -0,0 +1,29 @@
+% $Id$ %
+\def\UseOption{shanlingq1}
+\edef\UseOption{\UseOption,SHANLING_Q1_PAD}
+\edef\UseOption{\UseOption,HAVE_BACKLIGHT}
+\edef\UseOption{\UseOption,HAVE_RB_BL_IN_FLASH}
+\edef\UseOption{\UseOption,shanlingq1}
+
+\newcommand{\playerman}{Shanling}
+\newcommand{\playertype}{Q1}
+\newcommand{\playerlongtype}{\playertype}
+\newcommand{\dapdisplaywidth}{360}
+\newcommand{\dapdisplayheight}{400}
+\newcommand{\dapdisplaydepth}{16}
+\newcommand{\specimg}{shanlingq1}
+%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.q1}}
+\newcommand{\bootfilename}{\fname{bootloader.q1}}
+\newcommand{\firmwareextension}{\fname{q1}}
+\newcommand{\bootbackupfilename}{\fname{shanlingq1-boot.bin}}
+\newcommand{\jztoolsubcommand}{shanlingq1}
+\newcommand{\screenshotsize}{8cm}
+\newcommand{\disk}{SD card}
+
+% link external keymap file
+\input{platform/keymap-shanlingq1.tex}
+\input{platform/keymap-touchscreen.tex}
diff --git a/manual/rockbox_interface/main.tex b/manual/rockbox_interface/main.tex
index 8e42e3ef4c..92d50ccd0a 100644
--- a/manual/rockbox_interface/main.tex
+++ b/manual/rockbox_interface/main.tex
@@ -715,6 +715,23 @@ To turn on and off your Rockbox enabled \dap{} use the following keys:
     and then press the \ButtonPower{} button.
     }
 
+  \opt{fiiom3k,shanlingq1}
+    {
+    Rockbox has a dual-boot feature. To boot into the original firmware,
+    hold \ActionBootOFPlayer{} when powering on the \dap{}.
+
+    You can trigger a normal \playerman{} firmware update by holding
+    \ActionBootOFRecovery{} when powering on the \dap{}.
+    \warn{Updating the original firmware will \textbf{erase} the Rockbox
+      bootloader.}
+
+    \subsection{Entering the recovery menu}
+    You can access the Rockbox bootloader's ``recovery menu'' by holding
+    \ActionBootRecoveryMenu{}. This menu can be used to connect your \dap{}
+    over USB to transfer files, update the Rockbox bootloader, or revert to a
+    bootloader you've previously backed up.
+    }
+
   }
 \subsection{Putting music on your \dap{}}