Manual - Quantum Leaps

QP state machine frameworks for AVRQP Development KitAndroid-NDKDocument Revision ADecember 2012Copyright © Quantum Leaps, LLCwww.quantum-leaps.comwww.state-machine.com

Table of Contents1 Introduction ..................................................................................................................................................... 11.1 About QP .................................................................................................................................................... 21.2 About QM ................................................................................................................................................... 31.3 About the QP Port to Android-NDK ............................................................................................................ 41.4 Licensing QP .............................................................................................................................................. 41.5 Licensing QM .............................................................................................................................................. 42 Getting Started ................................................................................................................................................ 52.1 QDK Installation ............................................................................................................................................. 52.2 Android-NDK Tools Installation ...................................................................................................................... 72.3 Building the QP Libraries ............................................................................................................................... 82.4 Building the Example ..................................................................................................................................... 82.5 Building the Android Distributable .................................................................................................................. 92.6 Installing the Example Application on the Android Device ............................................................................. 102.7 Running the DPP Example Application .......................................................................................................... 123 Using QS Software Tracing ............................................................................................................................ 133.1 Example of QSPY Output .............................................................................................................................. 134 The QP Port to Android-NDK ......................................................................................................................... 154.1 The qf_port.h Header File .............................................................................................................................. 154.2 The qf_port.c Source File ............................................................................................................................... 154.3 The qs_port.c Source File .............................................................................................................................. 154.4 The bsp.c File for the DPP example ............................................................................................................... 155 Related Documents and References ............................................................................................................. 166 Contact Information ........................................................................................................................................ 17

1 IntroductionThis QP Development Kit (QDK) describes how to use the QP/C active object (actor) framework onAndroid-NDK (Android Native Development Kit).Integrating QP with Android at the native code level (running outside the Android's Delvik Virtual Machine)is interesting for applications requiring efficiency and real-time, or near real-time performance, such asgames. QP is an ideal platform for building highly modular, well structured, multithreaded Androidapplications based on the concept of active objects (a.k.a.Actors) and hierarchical state machines. Additinally, the freegraphical QM modeling tool can be used to generate largeparts of the code automatically.QP complements Android-NDK by providing the high-levelstructure, while OpenGL API renders the GUI. Also, the QP portto Android-NDK enables developers to build efficient,multithreaded Android applications at a much higher level thanPOSIX threads (Pthreads) and without fiddling directly with thetroublesome low-level mechanisms such as POSIX mutexes,condition variables, and so on.The actual software used in ths document is as follows:1. Android NDK r82. Cygwin + Devel package (for Windows builds)3. Android SDK4. Apache Ant5. Java runtime (needed for Apache Ant)6. QP/C/C++ 4.5.02 or higher and QM v 2.2.03.7. Qtools 4.5.xx or higher (for the QSPY build)For testing, the Application Note uses the Dining PhilosopherProblem (DPP) example application [QL ANDPP 08] running onAndroid ARM/MIPS/X86 emulators and Android devices (seeFigure 1).Figure 1 The Dining Philosophers ProblemQP Example running on Nexus 7 tabletCopyright © Quantum Leaps, LLC. All Rights Reserved.1 of 17

QDK Android-NDKwww.state-machine.com/android1.1 About QPQP is a family of very lightweight, open source, active objectframeworks for developing multi-threaded, event-driven applications.QP enables building well-structured, modular software as a set ofconcurrently executing hierarchical state machines (UML statecharts)directly in C or C++. QP is described in great detail in the book“Practical UML Statecharts in C/C++, Second Edition: Event-DrivenProgramming for Embedded Systems” [PSiCC2] (Newnes, 2008).As shown in Figure 2, QP consists of a universal UML-compliant eventprocessor (QEP), a portable real-time framework (QF), a tiny run-tocompletionkernel (QK), and software tracing instrumentation (QS).Current versions of QP include: QP/C and QP/C++, which requireabout 4KB of code and a few hundred bytes of RAM, and the ultralightweightQP-nano, which requires only 1-2KB of code and justseveral bytes of RAM. The Linux port described in this QDK Manualpertains to QP/C and QP/C++.Figure 2 QP components and their relationship with the target hardware, board support package(BSP), and the application comprised of state machinesQP can work with or without a traditional RTOS or OS. In the simplest configuration, QP can completelyreplace a traditional RTOS. QP can manage up to 63 concurrently executing tasks structured as statemachines (called active objects in UML).Copyright © Quantum Leaps, LLC. All Rights Reserved.2 of 17

QDK Android-NDKwww.state-machine.com/android1.2 About QMQM (QP Modeler) is a free, cross-platform, graphical UMLmodeling tool for designing and implementing real-time embeddedapplications based on the QP state machine frameworks. QM isavailable for Windows, Linux, and Mac OS X. QM provides intuitivediagramming environment for creating good looking hierarchical statemachine diagrams and hierarchical outline of your entire application.QM eliminates coding errors by automatic generation of compact Cor C++ code that is 100% traceable from your design. Please visitstate-machine.com/qm for more information about QM.The source code included with this QDK can be edited manually in atraditional code editor. However, significant parts of the code havebeen generated automatically by the QM modeling tool from thedpp.qm model file included in the QDK. The preferred way ofdeveloping QP applications is to make all the changes in the modeland generate the code automatically.Figure 3: The example model opened in the QM modeling toolCopyright © Quantum Leaps, LLC. All Rights Reserved.3 of 17

QDK Android-NDKwww.state-machine.com/android1.3 About the QP Port to Android-NDKIn this port, a QP application runs as a single process inside Android NativeActivity class, with eachQP active object executing in a separate lightweight POSIX thread (Pthread). The port uses a Pthreadmutex to implement the QP critical section and the Pthread condition variables to provide the blockingmechanism for event queues of active objects.The Android-NDK does not implement the standard C library fully. Instead it has it's own library calledBionic libc. The Bionic libc is designed to be small, fast and to use BSD licensing.The general assumption underlying the QP port to Android-NDK is that the application is going to be realtimeor perhaps “soft real-time”. This means that the port is trying to use the real-time features available inthe Bionic PThread API as much as possible. These features are tested against the Android Emulatorsoftware.The QP port to Android-NDK uses one dedicated Pthread to periodically call the QF_tick() function tohandle the armed time events. At startup, QP attempts to set the priority of this ”ticker” thread to themaximum, so that the system clock tick occurs in the timely manner.For QSPY tracing, an additional logger PThread is started. This thread works as a gateway for readingthe QSPY logging messages and feeding them through the standard Android logging mechanism.1.4 Licensing QPThe Generally Available (GA) distribution of QP available for download from the www.statemachine.com/downloadswebsite is offered with the following two licensing options:The GNU General Public License version 2 (GPL) as published by the FreeSoftware Foundation and appearing in the file GPL.TXT included in the packaging ofevery Quantum Leaps software distribution. The GPL open source license allowsyou to use the software at no charge under the condition that if you redistribute theoriginal software or applications derived from it, the complete source code for yourapplication must be also available under the conditions of the GPL (GPL Section2[b]).One of several Quantum Leaps commercial licenses, which are designed forcustomers who wish to retain the proprietary status of their code and therefore cannotuse the GNU General Public License. The customers who license Quantum Leapssoftware under the commercial licenses do not use the software under the GPL andtherefore are not subject to any of its terms.For more information, please visit the licensing section of our website at: www.statemachine.com/licensing.1.5 Licensing QMThe QM graphical modeling tool available for download from the www.statemachine.com/downloadswebsite is free to use, but is not open source. During theinstallation you will need to accept a basic End-User License Agreement (EULA),which legally protects Quantum Leaps from any warranty claims, prohibits removingany copyright notices from QM, selling it, and creating similar competitive products.Copyright © Quantum Leaps, LLC. All Rights Reserved.4 of 17

QDK Android-NDKwww.state-machine.com/android2 Getting StartedThis section describes how to install, build, and use QDK-Android-NDK based the Dining PhilosophersProblem (DPP) example. This information is intentionally included early in this document, so that youcould start using the QDK as soon as possible.NOTE: This QDK assumes that the standard QP baseline distribution has been installed, beforeinstalling this QDK. It is also strongly recommended that you read the QP tutorial before you startexperimenting with this QDK.2.1 QDK InstallationThe QDK code is distributed in a ZIP archive (qdkc_android-ndk.zip. You can unzip the archive intothe same directory into which you’ve installed all the QP baseline code. The installation directory youchoose will be referred henceforth as QP Root Directory . The following Listing 1 shows thedirectory structure and selected files included in the QDK-Android-NDK distribution. (Please refer to the“Overview of QP Directories and Files” video on the state-machine.com website to understand thegeneral structure of QP directories and files):Listing 1 Selected QP directories and files after installing QDK-Android-NDK.qpc\- QP/C installation directory+-doc\| +-AN_DPP.pdf - App Note “Dining Philosopher Problem Example”| +-AN_QP_and_POSIX.pdf – App Note “QP and POSIX”| +-QDK_Android-NDK.pdf – This QDK Manual|+-include/- QP public include files|+-ports/- QP ports| +-android-ndk/ - Android-NDK port| | +-gnu/ - GNU compiler| | | +-Android.mk - NDK-build makefile for QP libraries| | | +-AndroidManifest.xml - Manifest for the QP libraries| | | +-qep_port.h - QEP platform-dependent public include| | | +-qf_port.h - QF platform-dependent public include| | | +-qs_port.h - QS platform-dependent public include| | | +-qf_port.c - QF plaform-dependent implementation| | | +-qs_port.c - QSPY plaform-dependent implementation|+-examples/- subdirectory containing the QP example files| +-android-ndk/ - Android-NDK examples| | +-gnu/ - GNU compiler| | | +-dpp/ - Dining Philosopher Problem application| | | | +-jni/ - Java native interface compatible files| | | | | +-Android.mk - NDK-build makefile for application| | | | | +-Application.mk - NDK-build app build config| | | | | +-bsp.c - Board Support Package for Android| | | | | +-bsp.h - BSP header file| | | | | +-display.c - OpenGL display routines| | | | | +-display.h - OpenGL display routine API| | | | | +-dpp.h - the DPP header file| | | | | +-dpp.qm - the DPP model file for QMCopyright © Quantum Leaps, LLC. All Rights Reserved.5 of 17

QDK Android-NDKwww.state-machine.com/android| | | | | +-main.c - the main function| | | | | +-philo.c - the Philosopher active object| | | | | +-table.c - the Table active object| | | | || | | | +-libs/ - JNI ndk library accessed by NativeActivity| | | | | +-armeabi/ - JNI lib for armeabi architecture| | | | | | +-libdpp.so - JNI Shared lib QP/C Android NDK DPP| | | | | | +-libdpp-qspy.so - JNI Shared lib QP/C Android NDK DPP QSPY| | | | | +-armeabi-v7a/ - JNI lib for armeabi-v7a architecture| | | | | | +-libdpp.so - JNI Shared lib QP/C Android NDK DPP| | | | | | +-libdpp-qspy.so - JNI Shared lib QP/C Android NDK DPP QSPY| | | | | +-mips/ - JNI lib for mips architecture| | | | | | +-libdpp.so - JNI Shared lib QP/C Android NDK DPP| | | | | | +-libdpp-qspy.so - JNI Shared lib QP/C Android NDK DPP QSPY| | | | | +-x86/ - JNI lib for x86 architecture| | | | | | +-libdpp.so - JNI Shared lib QP/C Android NDK DPP| | | | | | +-libdpp-qspy.so - JNI Shared lib QP/C Android NDK DPP QSPY| | | | || | | | +-obj/ - various object files| | | | | +-convert_dependecies.sh - NDK-build auto-generated script| | | | | +-local - local object files| | | | | | +-armeabi/ - object files for armeabi| | | | | | +-armeabi-v7a/ - object files for armeabi-v7a| | | | | | +-mips/ - object files for mips| | | | | | +-x86/ - object files for x86| | | | || | | | +-bin/ - Packaged application files| | | | | +-DiningPhilosophersProblem-debug.apk - debug version| | | | +-res/ - resource files for application| | | | | +-drawable-ldpi/ - low res images for application| | | | | | +-application_icon.png - low res application icon| | | | | +-drawable-hdpi/ - high res images for application| | | | | | +-application_icon.png - high res application icon| | | | | +-drawable-mdpi/ - medium res images for application| | | | | | +-application_icon.png - meduim res application icon| | | | | +-drawable-xhdpi/ - xtra high res images for application| | | | | | +-application_icon.png - xtra high res application icon| | | | || | | | +-AndroidManifest.xml - Manifest for the QP libraries| | | | +-build.xml - Ant build script for buiding the app| | | | +-local.properties - Project properties for ANTCopyright © Quantum Leaps, LLC. All Rights Reserved.6 of 17

QDK Android-NDKwww.state-machine.com/android2.2 Android-NDK Tools InstallationYou need to install all of the following software on your computer.1. Android NDK r82. Cygwin + Devel package (for Windows builds)3. Android SDK4. Apache Ant5. Java runtime (needed for Apache Ant)6. QP/C/C++ 4.5.02 or higher and QM v 2.2.03.7. Qtools 4.5.xx or higher (for the QSPY build)If you are using Windows, setup the paths by modifying cygwin.bat, add following lines (if you are usingLinux or Mac, adjust accordingly):set PATH=/android-sdk/tools;/android-sdk/platformtools;;;set JAVA_HOME=set ANDROID_NDK_ROOT=set NDK_MODULE_PATH=set QTOOLS=set QPC=The following lising shows the real life example (please adjust to your installations):rem @echo offC:chdir C:\cygwin\binListing 2 Example of cygwin.bat (located in the Cygwin installation folder)set JAVA_HOME=/cygdrive/c/tools/java/jdk1.7.0_07set ANDROID_HOME=/cygdrive/c/tools/android/android-sdkset ANDROID_NDK_ROOT=/cygdrive/c/tools/android/android-ndk-r8bset NDK_MODULE_PATH=/cygdrive/d/qpset QPC=/cygdrive/d/qp/qpcset QPCPP=/cygdrive/d/qp/qpcppset QPN=/cygdrive/d/qp/qpnset QTOOLS=/cygdrive/d/qp/qtoolsset PATH=%ANDROID_HOME%/tools;%ANDROID_HOME%/platform-tools;%ANDROID_NDK_ROOT%;%JAVA_HOME%/bin;/cygdrive/c/tools/apache-ant-1.8.4/binbash --login -iMake sure that you can succesfully start:android.bat (from regular Windows command line)ant (from Cygwin or regular Windows command line)ndk-build and adb (from Cygwin).Copyright © Quantum Leaps, LLC. All Rights Reserved.7 of 17

QDK Android-NDKwww.state-machine.com/android2.3 Building the QP LibrariesAs QP libraries for Android are defined as modules, you don't need to build them separately. Instead theyare automatically pulled (and build) to the application through the module dependency system.The Android NDK build system is called ndk-build, which itself is a wrapper around GNU Make. It has aconcept of "modules". Each module is defined in a Android.mk file. In this file, the compiler flags anddependencies to other modules are declared. Most of the time, the modules map 1:1 to specific libraries.NOTE: The QP libraries and QP applications for Android-NDK can be built in the following four buildconfigurations:debug - this configuration is built with full debugging information and minimal optimization.release - this configuration is built with no debugging information and high optimization. Singlesteppingand debugging is effectively impossible due to the lack of debugging information andoptimized code, but the debugger can be used to download and start the executable.qspy-debug - this configuration is built with the QS software tracing instrumentation and fulldebugging information.qspy-release - this configuration is built with the QS software tracing instrumentation but nodebugging information.To select the QSPY version of the libdpp is packaged to the .apk-file, you need to modify the followingline in AndroidManifest.xml file in the application folder:to:2.4 Building the ExampleAs shown in Listing 1, the DPP application example for Android-NDK is located in the directoryqpc/examples/android-ndk/gnu/dpp/. This directory contains the Android.mk file and build.xml fileto build the example.The build is started using the following command (inside Cygwin for Windows):ndk-buildorndk-build NDK_DEBUG=1The latter command builds all libraries with debug symbols, and the first command without debugsymbols.The following screen shot shows the console output from the build in Cygwin on Windows. Plese note thatthe complete build takes a while, because the QP libraries and application code is re-build for allplatorms, such as 80x86, ARM, and MIPS. To clean the build, you can use the command:ndk-build cleanCopyright © Quantum Leaps, LLC. All Rights Reserved.8 of 17

QDK Android-NDKwww.state-machine.com/androidFigure 4 Building the DPP example in Cygwin on Windows:2.5 Building the Android DistributableAdditionally, after building the native shared library, you need to build and package the Android apkdistributablefile. The Android toolset uses the Ant tool to do this.The Ant tool reads its configuration for the build from the build.xml file, which in turn includes thelocal.properties file. These files need to be regenerated once to mach your configuration. This isdone using following command (from the application directory):android.bat update project -p .NOTE: The android.bat command prints some error messages to the Cygwin console, but youcan ignore them. At this point you only care for updating the local.properties file.After this, the Android package is build with following command:ant debugorant releaseCopyright © Quantum Leaps, LLC. All Rights Reserved.9 of 17

QDK Android-NDKwww.state-machine.com/androidFigure 5 Building the DPP example in Cygwin on Windows:2.6 Installing the Example Application on the Android DeviceThe DPP example is Android OpenGL application that needs to be transferred to the Android emulator ora real device. The transferring is done using a tool called "adb".To install an apk package to the emulator or a real device, first launch the Android emulator (Androidemulator is launched with the Anroid AVD Manager tool), or connect your Android device to the hostcomputer via a USB cable.Figure 6 Starting the Androidn emulator from the Androind AVDCopyright © Quantum Leaps, LLC. All Rights Reserved.10 of 17

QDK Android-NDKwww.state-machine.com/androidFigure 7 Android emulator before (left) and after (right) installing the DPP example applicationNext, from the Cygwing terminal issue following command:adb install -r bin/DiningPhilosophersProblem-debug.apkCopyright © Quantum Leaps, LLC. All Rights Reserved.11 of 17

QDK Android-NDKwww.state-machine.com/android2.7 Running the DPP Example ApplicationAfter succesfull installation, you can start the DPP application by clicking the application icon on theemulator or on the device.The DPP screen should appear and start running immediately. The application presents a white tablesurrounded by 5 seated philosophers. The philosophers are color coded with following codes:red = hungrygreen = eatingblue = thinkingFigure 8 Android running the DPP example application in normal mode (left) and paused (right)While the application is running, you can tap the screen to pause it (send the PAUSE_SIG to the Tableactive object). When the application is paused the circle in the middle changes the color from white togrey and the Table active object stops giving permissions to eat to the Philosophers, so after a short whileall Philos become hungry (red). Another tap on the screen resumes the normal operation.Copyright © Quantum Leaps, LLC. All Rights Reserved.12 of 17

QDK Android-NDKwww.state-machine.com/android3 Using QS Software TracingThe QP port to Android-NDK provides particularly easy access to the QS (Quantum Spy) software tracinginformation (see [Q_SPY-Ref] and Chapter 11 of [PSiCC2] book for more information about the QSsoftware tracing system). In the Android-NDK port, you can choose to have the QS data converted onthe-flyfrom the compressed binary to the human readable format for direct output to the Android systemlog. This on-the-fly formatting of the binary QS data is achieved by incorporating code normally used inthe QSPY host application into the application.To select which version of the libdpp is packaged to the .apk-file, you need to modify the following linein AndroidManifest.xml file:After this modification, you need to rerun the "ant debug" or "ant release" command and load theapplication to the emulator or device with "adb install -r".The QS data can be read using the "adb" tool while the qspy-enabled version of the application isrunning. To show QSPY-information, use following command:adb logcat -s "dpp"The parameter -s "dpp" instructs to show only messages with "dpp" tag.NOTE: This QS implementation requires access (during the build) to the QSPY host applicationcode, which resides in the Qtools collection. Therefore, Qtools needs to be installed in your systemand the QTOOLS environment variable must be defined.3.1 Example of QSPY OutputTo see the QS ouptut, issue the following command from the Cygwin prompt:adb logcat -s "dpp"Figure 9 The QSPY output after typing command adb logcat -s "dpp"Copyright © Quantum Leaps, LLC. All Rights Reserved.13 of 17

QDK Android-NDKwww.state-machine.com/androidCopyright © Quantum Leaps, LLC. All Rights Reserved.14 of 17

QDK Android-NDKwww.state-machine.com/android4 The QP Port to Android-NDKThe QP port to Android-NDK is based on the POSIX port, described in the Application Note “QP andPOSIX” (included in the QDK-Android-NDK). This section describes the modifications with respect to thePOSIX port.4.1 The qf_port.h Header FileSpecial thread type is defined to allow joining the pthread on exit. Without this, the Android processlifecycle might leave dangling threads.typedef struct PThreadTypeTag { /* Thread type struct */pthread_t thread;bool running;} PThreadType;4.2 The qf_port.c Source FileSCHED_FIFO scheduling policy is used for PThreads. This allows setting separate priorities for activeobjects.Q_ALLEGE(pthread_attr_setdetachstate(&attr,PTHREAD_CREATE_JOINABLE) == 0);The threads for Active Objects are created as joinable, so that the main thread can ensure termination ofall pthreads before exiting. This remedies the problems caused by Android process lifecycle.4.3 The qs_port.c Source FileCallback function: QSTimeCtr QS_onGetTime(void):clock_gettime() is used to achieve 1 usec accuracy with large enough roll over value.4.4 The bsp.c File for the DPP exampleCallback function Q_onAssert(): is implemented using __android_log_assert() function. Thisfunction causes signal 11 to be sent to the process for termination.Function BSP_displayPhilStat() only modify the values that are drawn on next animation thread framedraw.Function: QF_run(): the main loop blocks while the animation is stopped, waiting for events to arrive.When animation is running, frames are constantly re-drawn.Function android_main() is the entry point to the native application from "native application glue"component, originating from the Java NativeActivity class via JNI. Android makes sure that the .bssvariables are initialized when the library is first loaded. On concecutive start-ups the variables are notcleared. Because of this, the .bss is manually cleared on every startup.Callback function QSPY_onPrintLn() records are forwarded to android logging facility via__android_log_print() call.Copyright © Quantum Leaps, LLC. All Rights Reserved.15 of 17

QDK Android-NDKwww.state-machine.com/android5 Related Documents and ReferencesDocument[PSiCC2] “Practical UML Statecharts in C/C++,Second Edition”, Miro Samek, Newnes, 2008[QP 08] “QP Reference Manual”, QuantumLeaps, LLC, 2008[QL AN-DPP 08] “Application Note: DiningPhilosopher Problem Application”, QuantumLeaps, LLC, 2008[QL AN-POSIZ 12] “Application Note: QP andPOSIX”, Quantum Leaps, LLC, 2012[Android-DEV] “Android Developers” websitehttp://www.state-machine.com/doxygen/qpn/LocationAvailable from most online book retailers, such asamazon.com. See also: http://www.statemachine.com/psicc2.htmhttp://www.state-machine.com/resources/-AN_DPP.pdfhttp://www.state-machine.com/linux/-AN_QP_and_POSIX.pdfhttp://developer.android.com[Android-NDK] “Android NDK” websitehttp://developer.android.com/tools/sdk/ndk[Cygwin] “Cygwin websitehttp://www.cygwin.com/[Apache ANT] Ant websitehttp://ant.apache.org/Copyright © Quantum Leaps, LLC. All Rights Reserved.16 of 17

QDK Android-NDKwww.state-machine.com/android6 Contact InformationQuantum Leaps, LLC103 Cobble Ridge DriveChapel Hill, NC 27516USA+1 866 450 LEAP (toll free, USA only)+1 919 869-2998 (FAX)e-mail: info@quantum-leaps.comWEB : http://www.quantum-leaps.comhttp://www.state-machine.com“Practical UML Statechartsin C/C++, Second Edition:Event Driven Programmingfor Embedded Systems”,by Miro Samek,Newnes, 2008Copyright © Quantum Leaps, LLC. All Rights Reserved.17 of 17