Doc: CODA on-device debugging agent

Reviewed-by: Pawel Polanski

3 files changed, 105 insertions, 46 deletions

diff --git a/doc/images/qtcreator-symbian-run-settings.png b/doc/images/qtcreator-symbian-run-settings.png
index 39656b41c8..50fc30fd34 100644
--- a/doc/images/qtcreator-symbian-run-settings.png
+++ b/doc/images/qtcreator-symbian-run-settings.png
diff --git a/doc/qtcreator.qdoc b/doc/qtcreator.qdoc
index 3793049eba..dd9d5df2a3 100644
--- a/doc/qtcreator.qdoc
+++ b/doc/qtcreator.qdoc
@@ -4133,7 +4133,7 @@
         The tool tip of the target selector shows more details about the actual
         device that will be used when you run your application.
 
-        \o Start the \gui{App TRK} application on your device.
+        \o Start the debugging agent (CODA or App TRK) application on your device.
 
         \o Click the \gui Run button.
 
@@ -4153,10 +4153,10 @@
         \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
         have been installed on the development PC.
         \o The device is connected through USB cable in \e{PC Suite} mode.
-        \o \gui{App TRK} is running on the device, using the USB connection,
+        \o The debugging agent (CODA or App TRK) is running on the device, using
+           the USB connection,
            with the status \e connected.
-        \o The device is detected and selected in the run configuration
-           details.
+        \o The device is detected and selected in the \gui {Run Settings}.
      \endlist
 
     If this does not help to solve your problem, search the qt-creator@trolltech.com
@@ -4474,7 +4474,7 @@
 
     You can also pass command line arguments to your application on the device.
     Press the \gui{Device info button} to get more information about the selected
-    device, such as the CPU type and the running TRK version.
+    device, such as the CPU type and the running debugging agent version.
 
     \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
 
@@ -5449,11 +5449,11 @@
 
     \list 1
 
-        \o Install Qt libraries, Qt mobile libraries, and the TRK
-        debugging application on the device. For more information,
+        \o Install Qt libraries, Qt mobile libraries, and a
+        debugging agent on the device. For more information,
         see \l{Setting Up Development Environment for Symbian}.
 
-        \o Start TRK on the device.
+        \o Start the debugging agent, App TRK or CODA, on the device.
 
         \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
 
@@ -5522,7 +5522,7 @@
         mobile functions and create your own scripts.
 
         \o To test the application on a Symbian device, install Qt libraries
-        and the TRK debugging application on the device. For more information,
+        and a debugging agent on the device. For more information,
         see \l{Setting Up Development Environment for Symbian}.
 
         \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
@@ -6834,14 +6834,14 @@
 
        \o \bold Post-mortem to debug crashed processes on Windows.
 
-       \o \bold TRK to debug processes running on a Symbian device.
+       \o \bold On-device to debug processes running on a mobile device.
 
     \endlist
 
     \note Debugging QML and JavaScript is supported only in plain mode.
 
     When you click the \gui {Start Debugging} button, the debugger is launched
-    in the appropriate operating mode (plain, terminal, or TRK), based on the
+    in the appropriate operating mode (plain, terminal, or on-device), based on the
     build and run settings for the active project. Select \gui Debug menu options
     to launch the debugger in the other modes.
 
@@ -6899,18 +6899,16 @@
     on Windows. Click the \gui {Debug in Qt Creator} button in the error message
     that is displayed by the Windows operating system.
 
-    \section2 TRK Mode
+    \section2 On-device Mode
 
-    The TRK mode is a special mode available only for Symbian. It
-    debugs processes running on a Symbian
-    device using the App TRK application that runs on the device.
-
-    To launch the debugger in the TRK mode, open the project, select Symbian as the
-    target, and click the \gui {Start Debugging} button.
-
-    For more information on setting up Symbian projects, see
-    \l{Setting Up Development Environment for Symbian}.
+    The on-device mode is a special mode available for run configurations
+    targeting mobile devices. It debugs processes running on mobile
+    devices using on-device debugging agents, such as CODA on Symbian and
+    gdbserver on Maemo and MeeGo.
 
+    To launch the debugger in the on-device mode, open the project, select a
+    run configuration that targets a mobile device, and click the
+    \gui {Start Debugging} button.
 
 */
 
@@ -7001,16 +6999,16 @@
             \o gcc
             \o gdb
             \o Yes
-            \o TRK
+            \o On-device
         \row
             \o Maemo
             \o gcc
             \o gdb
             \o Yes
-            \o Remote
+            \o On-device
     \endtable
 
-    For more information on the debugger modes, see \l{Debugger Modes of Operation}.
+    For more information on the debugger modes, see \l{Launching the Debugger in Different Modes}.
 
     \omit
 
@@ -7038,9 +7036,10 @@
 
        \o RemoteGdbAdapter interacts with the gdbserver running on Linux.
 
-       \o TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
-       the gdb serial protocol are used between gdb and the adapter. The TRK
-       protocol is used between the adapter and AppTRK running on the device.
+       \o CodaGdbAdapter interacts with Symbian devices. The gdb protocol and
+       the gdb serial protocol are used between gdb and the adapter. The
+       target communication framework (TCF) protocol is used between the
+       adapter and the CODA debugging agent running on the device.
 
      \endlist
 
@@ -7175,9 +7174,9 @@
     features (like QtWebKit) are used.
 
     The debugger is launched in the appropriate operating mode (plain, terminal,
-    or TRK), based on the build and run settings for the active project.
+    or on-device), based on the build and run settings for the active project.
     Select \gui Debug menu options to launch the debugger in other modes.
-    For more information, see \l{Debugger Modes of Operation}.
+    For more information, see \l{Launching the Debugger in Different Modes}.
 
     \note Debugging QML and JavaScript is supported only in plain mode.
 
@@ -7786,7 +7785,8 @@
         Uses gdb to call the function \c func on the value specified by
         \a {item.value} and output the resulting item. This function is
         not available when debugging core dumps and it is not available
-        on the Symbian platform due to restrictions imposed by AppTRK.
+        on the Symbian platform due to restrictions imposed by the on-device
+        debugging agent.
 
     \o \gui{putItem(self, item)} - The "master function", handling
         basic types, references, pointers and enums directly, iterates
@@ -10394,8 +10394,9 @@
 
     \list
 
-        \o Debugging large applications on Symbian devices using the Symbian S^3
-           operating system might not work, because the TRK debug agent might not be able to
+        \o Debugging large applications on Symbian devices using the Symbian^3
+           operating system might not work, because the on-device debugging agent
+           might not be able to
            access memory when the operating system starts paging. This causes breakpoint
            handling and symbol resolution to fail. For more information, see
            \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
diff --git a/doc/symbiandev.qdoc b/doc/symbiandev.qdoc
index eac78a8782..07b1b43848 100644
--- a/doc/symbiandev.qdoc
+++ b/doc/symbiandev.qdoc
@@ -56,6 +56,17 @@
     the required applications on Symbian devices. You can also use any of
     the standard methods for installing applications.
 
+    To debug applications on Symbian devices by using the Qt Creator \gui Debug
+    mode, you must install an on-device debugging agent on the device. You have
+    a choice between App TRK and CODA debugging agents. For more information,
+    see
+    \if defined(qcmanual)
+    \l{Using On-device Debugging Agents}.
+    \else
+    \e \l{http://doc.qt.nokia.com/qtcreator-latest/creator-developing-symbian.html}{Using On-device Debugging Agents}.
+    \endif
+
+
     The tool chain for building applications locally on the development PC for
     the \gui {Symbian Device} target is only supported on Windows.
     If you develop on Linux or Mac OS, you must use the Remote Compiler
@@ -72,14 +83,9 @@
     following:
     \list
         \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
-        \o The
-            \if defined(qcmanual)
-            \l{http://tools.ext.nokia.com/trk/}{App TRK}
-            \else
-            \e {App TRK}
-            \endif
-            application for your device
-        \o \e Qt installed on the device
+        \o An on-device debugging agent, \e {App TRK} or \e CODA, installed on
+           the device
+         \o \e Qt installed on the device
          \o \e {Qt Mobility APIs} installed on the device, if you use them in
          applications
         \o \e {QtWebKit} installed on the device, if you use web functionality
@@ -98,6 +104,7 @@
     to install Carbide.c++ v2.0.0 or higher.
     \endif
 
+
     \section1 Installing Required Applications on Devices
 
     Separate installation packages are provided for Symbian^3 and Symbian^1
@@ -127,8 +134,7 @@
         \o Choose \gui {Start > Qt SDK > Symbian^3 Qt 4.7.2 > Install TRK
         (Debug Agent) for Symbian^3 on Device} and follow the
         instructions on the screen to install
-        the TRK
-        debugging application to the device.
+        the App TRK debugging agent to the device.
 
         \o Choose \gui {Start > Qt SDK > Symbian^3 Qt 4.7.2 > Install QtWebKit
         for for Qt 4.7.2 on Symbian^3 Device} and follow the
@@ -157,8 +163,7 @@
         \o Choose \gui {Start > Qt SDK > Symbian^1 Qt 4.7.2 > Install TRK
         (Debug Agent)} for the type of the connected device and follow the
         instructions on the screen to install
-        the TRK
-        debugging application to the device.
+        the App TRK debugging agent to the device.
 
         \o Choose \gui {Start > Qt SDK > Symbian^1 Qt 4.7.2 > Install QtWebKit
         for for Qt 4.7.2 on Symbian^1 Device} and follow the
@@ -169,7 +174,59 @@
     In addition, you can install an example application and demos to Symbian^1
     devices.
 
+
     \if defined(qcmanual)
+    \section1 Using On-device Debugging Agents
+
+    CODA is a new on-device debugging agent that will eventually replace App TRK.
+    You can choose which debugging agent to use in the \gui {Run Settings} for
+    the project.
+
+    CODA offers the following benefits:
+
+    \list
+
+        \o  Extended error information
+
+        \o  Debugging over WLAN
+
+        \o  Extended information about the device
+
+    \endlist
+
+    CODA differs from App TRK in the following ways:
+
+    \list
+
+        \o  Coda does not support debugging over a Bluetooth connection.
+
+        \o  Coda supports only Symbian^1 and Symbian^3 devices. It does not
+            support S60 3rd Edition devices.
+
+    \endlist
+
+    \section2 Installing Debugging Agents
+
+    You can download CODA from the
+    \l{http://tools.ext.nokia.com/coda/}{CODA download server}:
+
+    \list
+
+        \o  Symbian^1 versions of CODA are located in the pf5250 folder.
+
+        \o  Symbian^3 versions of CODA are located in the tb92 folder.
+
+    \endlist
+
+    The builds that are marked as \e delta builds work on top of App TRK, and
+    therefore, App TRK and CODA can co-exist on a device. Other than the delta
+    builds cannot be installed on a device where App TRK is installed.
+
+    The \QSDK installation program creates a shortcut for installing
+    App TRK on Symbian devices, but you can also download and install it
+    separately from the
+    \l{http://tools.ext.nokia.com/trk/}{App TRK download server}.
+
     \section1 Adding Symbian Platform SDKs
 
     \QSDK contains all the tools you need for developing Qt applications for
@@ -177,7 +234,7 @@
     install additional Symbian Platform SDKs:
 
     \list
-        \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}
+        \o \l{http://www.forum.nokia.com/info/sw.nokia.com/id/ec866fab-4b76-49f6-b5a5-af0631419e9c/S60_All_in_One_SDKs.html}
            {S60 Platform SDK 3rd Edition FP1 or higher}.
         \o Either the GCCE ARM Toolchain that is included in the Symbian
            SDKs, or RVCT 2.2 [build 686] or later (which is not available free
@@ -229,7 +286,8 @@
         The tool tip of the target selector shows more details about the actual
         device that will be used when you run your application.
 
-        \o Start the \gui{App TRK} application on your device and deny the
+        \o Start the debugging application, App TRK or CODA, on the device and
+        deny the
         Bluetooth connection.
 
         \o Select \gui Options to select USB as connection type.