Boox M92 software development

The following instructions assume that you know how to install the required tools, such as rake and cmake, and missing libraries or header files that you may be missing for x86 compilation.

When you compile something for the Boox M92 and wish to share it, please link it to Boox M92 software list and/or Boox M92 project list.

Important note: Some components (gui_shell, system_manager) have not (yet?) been released by Onyx. If you're interested in hacking with the Boox M92, please join this thread.

Hopefully, we can show Onyx that there's a developer community out there that'd be willing to help. :)

Installing prebuilt toolchain and SDK

Download and install the prebuilt SDK [1] TODO: How to download the two files without cloning the whole repository

  git clone git://github.com/onyx-intl/toolchain.git
  cd toolchain/imx508
  sudo tar -C / -xzvf gcc-4.4.4-glibc-2.11.1-multilib-1.0.tar.gz
  sudo tar -C / -xzvf sdk_imx508.tar.gz

this will create directory trees in /opt/freescale and /opt/onyx

Compiling the SDK

You will need to compile the SDK for yourself if you either wish to compile sources for the X86 platform or if you wish to compile the packages of the booxsdk-opensource git repository [2]

Download the SDK sources [3].

 git clone https://github.com/onyx-intl/booxsdk.git
 cd booxsdk
 git submodule update --init

Take a moment to consult the troubleshooting subsection below and to check whether the mentioned issues are still current with your checkout.

Compile the SDK sources (you will need statically linked binaries, if you wish to run them on the Boox M92):

 rake -f Rakefile.imx508 build:static

If you wish to compile only either for ARM or for X86, you may specify the targets build:arm:static or build:x86:static .

Verbose output

You can trigger verbose output of rake by using the -v commandline parameter.

cmake can be rendered verbose adding the -DCMAKE_VERBOSE_MAKEFILE=ON commandline parameter in the :config section of Rakefile.imx508 .

Troubleshooting

This subsection refers to known issues preventing compilation at the respective time of writing (please add notes to the items if you find them corrected in the repository).

Check whether Rakefile.imx508 references the correct location of the toolchain (specifically arm_cc and arm_cxx). If not, you may need to patch it using the patchfile found at [4] (or correct it manually).

(build:arm:static on amd64): If the linker complains about undefined references to gzopen, gzread, and gzclose when building dictionary_test, the responsible CMakeLists.txt in the dictionary directory is missing inclusion of the libz. Patch can be found here: [5]

If rake behaves erratically (e.g., insists on using arm header files to build x86 binaries, or doesn't find the arm qt header files, because you unpacked the prebuilt SDK _after_ invoking rake), delete the respective build subdirectory and try again. It seems that configuration and makefiles therein are created once, and not updated upon invoking build again. Also make sure that you _don't_ have the environment set as described further below for your first x86 build.

Compiling boox-opensource/CMake packages

Note that some of the packages are not coded with portability in mind (e.g. casting pointers to int) - on amd64 machines, you may therefore run into trouble compiling for X86. You'll save yourself a lot of trouble compiling in a 32bit environment (e.g., by using a virtual machine ;) )

Download the sources [6].

 git clone https://github.com/onyx-intl/boox-opensource.git
 cd boox-opensource
 git submodule update --init

Copy or link the subdirectories found in code/src/ to code/src/ in your booxsdk directory.

Change into your booxsdk directory.

Add the subdirectories you wish to compile to code/src/CMakeLists.txt .

Take a moment to consult the troubleshooting subsection below and to check whether the mentioned issues are still current with your checkout.

Use the same build command you used to compile your SDK. The resulting binaries can be found in the build subdirectory.

Troubleshooting

This subsection refers to known issues preventing compilation at the respective time of writing (please add notes to the items if you find them corrected in the repository).

(build:arm:static on amd64) dict_tool CMakeLists.txt is missing inclusion of libz. Patch can be found here: [7]

fbreader CMakeLists.txt includes a library called cryptopenssl (which I did not find and which seems not needed, as it can be built without it). If your linker complains about not finding it: remove it from CMakeLists.txt. Patch can be found here: [8]

fbreader requires libcrypto, which is part of openssl, but missing in the SDK. You need to compile it. You can find it here: [9] ; Makefile patch to make openssl-0.9.8l easy to compile using the arm toolchain can be found here: [10]

Compiling libraries and applications for the M92

While the actual steps of course depend on the respective project, this section intends to give an overview about how to proceed in most cases.

You need to install the toolchain and the precompiled SDK (see above).

Setting environment variables

You need to set a few environment variables, so toolchain and libraries are found. It makes sense to create a script to do this for you.

 export PATH="/opt/onyx/arm/bin:/opt/freescale/usr/local/gcc-4.4.4-glibc-2.11.1-multilib-1.0/arm-fsl-linux-gnueabi/bin/:$PATH"
 export ONYX_SDK_ROOT=/opt/onyx/arm
 export PKG_CONFIG_PATH=/opt/onyx/arm/lib/pkgconfig/
 export QMAKESPEC=/opt/onyx/arm/mkspecs/qws/linux-arm-g++/

Compiling regular projects

Most software in Linux is compiled by first calling a configure script, and then executing make. If they're well-designed with portability in mind, you can compile the software by following the instructions below.

First, you need to set the environment, as described above.

Then you may want to create an installation directory to hold the compiled program/libraries:

 mkdir -p build/arm

You must tell configure about this installation directory and the intention to cross-compile. Don't forget to tell it where include and lib directories are (check ./configure --help), when building software depending on other libraries. You may also want to check the resulting Makefile whether they are configured in CFLAGS and LDFLAGS environment variables, and whether they are used in the ruleset below... some configure scripts seem to be broken to this respect.

 ./configure --prefix=`pwd`/build/arm --host=arm-linux

You will want to compile your binaries statically linked for the M92. To this end, replace all dynamic libraries mentioned in Makefile by static versions. In most cases, the commands below should do the trick. (If not, you'll need to edit it by hand ;) )

 mv Makefile Makefile.orig
 cat Makefile.orig | sed 's/\.la\([: ]\)/.a\1/g' | sed 's/\.la$/.a/'  > Makefile

Last, but not least, compile and install it. You'll find the binaries in build/arm after this step.

 make install

If you don't intend to debug the software on the machine, strip the debugging symbols to save space by calling

 arm-linux-strip <binary file you want to strip>

Compiling Qt/qmake Applications for ARM

The qmake project file myproject.pro only needs something like

 LIBS += -lonyxapp -lonyx_base -lonyx_ui -lonyx_screen -lonyx_sys -lonyx_wpa -lonyx_wireless -lonyx_data -lonyx_cms

depending on which onyx libraries you use. All other settings will be handled by using the correct qmakespec file.

You need to set the environment variables, as described above.

Then you can compile applications for ARM with the following commands:

 qmake myproject.pro
 make

Add the extension ".oar" to the resulting binary, otherwise the (file manager on the) M92 will not execute it.

Compiling for x86 is a bit more complicated. You need to compile the SDK and put the resulting libraries (libonyx*) in some directory, where qmake/make can find them.

Compiling software projects built in non-standard way

...ok... you're a bit on your own here... But in principle, as a rule of thumb, you'll:

• need to set the environment variables
• need to make sure that required libraries are in /opt/onyx/arm/lib/
• need to make sure that required library header files are in /opt/onyx/arm/include/
• need to make sure that when your build scripts use software to which a corresponding executable exists in /opt/freescale/usr/local/gcc-4.4.4-glibc-2.11.1-multilib-1.0/arm-fsl-linux-gnueabi/bin/ , it uses the one in said directory to compile binaries that are working on the M92
• spare yourself a lot of trouble by compiling your binaries statically linked
• save quite some space by stripping the binaries of debug symbols by use of arm-linux-strip

Installing required libraries

Build them, as described above.

Copy the resulting library files into /opt/onyx/arm/lib/ .

Copy the resulting header files into /opt/onyx/arm/include/

They should be ready to be used by other projects, now.

Where do I get sources?

All over places... to my experience, it is often the most convenient to use "apt-get source <package name>" on Debian and Debian derivates, such as Ubuntu. If you're unsure which package a binary belongs to, you can check that out with apt-file, which shows you the names and contents of packages:

 apt-get install apt-file
 apt-file update
 apt-file search <some string>   #e.g., apt-file search bin/sqlite3
 apt-get source <package name>

Troubleshooting

If you get linker errors about rpl_malloc or rpl_realloc , then you need to execute this _before_ running configure:

 export ac_cv_func_malloc_0_nonnull=yes
 export ac_cv_func_realloc_0_nonnull=yes

Compiling kernel and kernel modules

(To be done... until now, the exact kernel sources/patches are not yet published (some folks are nagging Onyx to do so) ... the kernel however seems close enough to the stock freescale SDK kernel to use compiled modules... one has however to correct the version information manually using a hex editor for now - Maybe someone will write a short howto and contribute a working .config? :) )

Note: as of March, 1st, there's a kernel source in the git repository - I guess some folks are currently checking this one out and hopefully will write a wiki entry about it, soon :) Update: There are still files missing...

Debugging

Optimally, gdbserver could be used (available in the toolchain), but I was not yet able to achieve a stable connection to the device. Another (less convenient) option is to use core dumps. Use a shell script to run your application on the M92:

 #!/bin/sh
 cd /media/flash
 ulimit -c unlimited
 ./yourapplication.oar

If the program crashes, a file named core is created. The cross gdb found in the toolchain can be used to analyze this file. Under QtCreator, use Settings->Toolchain to register the toolchain in /opt/freescale/... and then open the core file via Debug->Debug core file.

Troubleshooting

When you're using a makefile that calls cmake, "make VERBOSE=1" will show verbose cmake output. [11]

If your application won't be displayed, but the 'busy'-wheel keeps on spinning... Chances are that you didn't put this before calling .exec() ;)

 sys::SysStatus::instance().setSystemBusy(false);

Installing applications

Just copy the statically linked .oar file to a location of your choice onto either SDCard or internal Flash memory of your M92. ;)

Scripting on the M92

Aside from the the busybox shell, there's python support [12], [13].

Furthermore, there are some basic UI primitives available for scripting [14]

Pointers

• Source: [15] ([16])
• Rakefile patch to compile SDK: [17]
• Toolchain & Prebuild SDK: [18] ([19])
• 3rd Party library source: [20], (old? [21])
• CMake modules: [22] ([23])
• Freescale resources (including kernel): [24] ([25])
• QEmu file useful for development: [26] ([27])
• Flash procedure details: [28] , [29]
• Forums: Booxusers[30]
• OpenBoox (free firmware for _other_(!) Boox models) SDK documentation (but sdk use similiar - hence useful): [31]
• Browser is webkit(?): [32]
• Boox (60) partition information: [33] and boot process: [34]
• Input stuff apparently based on tslib: [35], [36], [37], [38]
• Cross compiling Python: [39] ([40], [41]). See also the article on setting up a scratchbox2 environment.
• Setting up a development environment with Scratchbox2 and a Debian rootstrap: [42].
• M92 disassembly and pictures of the 'naked' device ;) [43]