Solutions - SQLite instrumentation

SQLite is a simple C-library that implements a SQL database engine. No configuration (except some space on your hard disk and the right to write on it) is necessary since everything is written to a file instead of to a database server. For more detailed information look at the homepage of SQLite. SQLite is often used when the configuration and maintenance of a real database server seems to be overkill. Famous tools are

• Trac from Edgewall software services. Trac is an enhanced wiki and issue tracking system, integrated with Subversion, for software development projects. Were using it internally and are very satisfied,
• OpenOffice SQLite SDBC Driver for OpenOffice.org 1.1.x,
• The database drivers for Qt, the C++ programming framework. Since we're currently working on a native ARM framework for Qt we will end up with a toolchain allowing fully known applications from a performance point of view since all important parts are ARM instrumented
• For a more comprehensive list take a look at the SQLite users list on the SQLite wiki.

Download instrumented SQLite library

The instrumented SQLite library can be either downloaded

• as patched source code (please see compile instructions for further proceeding)
• as patch for different SQLite versions (please see patch instructions and compile instructions for further proceeding)
• as binary package, (see Installation instructions for details)

Go to our download page for details (i.e. choose operating system and type of download). All changes to the SQLite library are free of charge, the source code stands under the same license as sqlite.

Patch instructions

If you've downloaded one of our patches to SQLite make sure that the versions of the patch and the SQLite package do not differ. For the following description we assume that you've downloaded the sqlite-3.2.2.tar.gz source package from the SQLite download page. The patch for this version is named sqlite-3.2.2_20050805.patch, where 20050805 is the date of the patch creation and may change for newer patches. First unpack the source package :

tar xzvf sqlite-3.2.2.tar.gz

This will create a directory sqlite-3.2.2 in your current working directory. It is further assumed that our patch resides in the same directory. So patching is simple by issuing the command

patch -p0 <sqlite-3.2.2_20050805.patch

This should produce some output similar to the following.

patching file sqlite-cvs/configure.ac
patching file sqlite-cvs/Makefile.in
patching file sqlite-cvs/src/arm/correlator_env.c
patching file sqlite-cvs/src/arm/correlator_string.c
patching file sqlite-cvs/src/arm/myarm_os.c
patching file sqlite-cvs/src/arm/myarmsdk.h
patching file sqlite-cvs/src/arm/myarm_tls.c
patching file sqlite-cvs/src/main.c
patching file sqlite-cvs/src/sqlite_arm.c
patching file sqlite-cvs/src/sqlite_arm.h
patching file sqlite-cvs/src/sqliteInt.h
patching file sqlite-cvs/src/vdbeapi.c
patching file sqlite-cvs/src/vdbeInt.h

If you get errors here please contact us so that we can fix the problem. Unfortunately you're not done yet. Since you have patched configure.ac you have to update configure by executing

autoreconf -i --force

This will update configure and all its surrounding files needed for a successful configuration. If you miss this step, configure will not detect the --with-arm parameter and the instrumentation will not work.

Compile instructions

ARM can be enabled during compilation of SQLite with the configure parameter

--with-arm=DIR

where DIR is the directory where the official ARM4 SDK libraries and includes reside (See OpenGroup ARM website). It is assumed that the headers (arm4.h, arm4sdk.h) reside under

DIR/c/include or DIR/sdk/c/include

while the libraries (libarm4.so, libarm4sdk.so) can be found under

DIR/libarm4, DIR/c/arm4sdk or DIR/lib

In case the paths do not reflect your needs feel free to change configure.ac in the SQLite source tree. In case ARM is not enabled via --with-arm no side effects will be produced since everything related to the ARM instrumentation is capsuled within #define statements.

Installation instructions

If you've downloaded one of our binary packages you need to know the configuration of these packages. You need to have an ARM library (libarm4.so and libarm4sdk.so) installed somewhere on your system and your LD_LIBRARY_PATH must point to the directories where these libraries reside. For a bash login shell this will look similar to

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/sdk4/c/arm4sdk:/opt/sdk4/libarm4

Here it is assumed that you have the ARM4 SDK installed in /opt/sdk4. Besides ARM, the installation prefix for the binary package was set to

/opt/sqlite

You should have no problems copying the binaries to another directory in your file system, but you can be sure it works if you keep it there.

How was SQLite ARMed? Some Background!

Since the SQLite API is well described it was not a big deal to put in the relevant ARM API functions to get a very simple but powerful ARM instrumented SQLite database.

The ARM application is registered and started when a database is opened. It is named "SQLite application". An application definition property is added providing the name of the operating system.

At the same time only one transaction definition called "SQLite query" is registered. For now this is the only transaction definition used.

The transaction is started at the time when the first sqlite_step() is called. The properties "DBNAME" (name of the database, e.g. test.db) and QUERY_NAME (e.g. "SELECT t1 from table1") are provided during the start of the transaction. The metric "PID" is provided as well, saving the id of the thread (or process in a single threaded environment) with the current transaction. The transaction is stopped when

• sqlite_step() returns SQLITE_DONE,
• the user calls sqlite_reset() or
• the user calls sqlite_finalize().