Sorcery Limited Sorcery Limited 1 Porting C/C++ to Symbian OS Mark Wilcox Mark Wilcox
Sorcery LimitedSorcery Limited 11
Porting C/C++ to Symbian OS
Mark WilcoxMark Wilcox
Sorcery LimitedSorcery Limited 22
What I’m Talking About What is Porting?What is Porting? Why Port to Symbian OS?Why Port to Symbian OS? Porting Aids:Porting Aids:
P.I.P.S.P.I.P.S. OpenGL ESOpenGL ES Open C/C++ & RGAOpen C/C++ & RGA Coming Soon…Coming Soon…
How to do it – The Porting ProcessHow to do it – The Porting Process Common Problems (& Solutions)Common Problems (& Solutions) Examples:Examples:
Easy: SoundTouchEasy: SoundTouch More Complex: GuiTuneMore Complex: GuiTune
Sorcery LimitedSorcery Limited 33
What is Porting?
““Porting is the process of adapting software so that Porting is the process of adapting software so that an executable program can be created for a an executable program can be created for a computing environment that is different from the computing environment that is different from the one for which it was originally designed.” one for which it was originally designed.” (Wikipedia)(Wikipedia)
i.e. Making software work on different hardware or operating systems.
Sorcery LimitedSorcery Limited 44
Smartphone Market Share (Q4 2007)
65%12%
11%
7%5%
Symbian OS
Windows Mobile
RIM BlackBerry
iPhone
Linux
Why Port to Symbian OS? The Marketing Reason…The Marketing Reason…
The Hacker’s Reason…The Hacker’s Reason…The Geek’s Reason…The Geek’s Reason…
Sorcery LimitedSorcery Limited 55
Porting AidsP.I.P.S. Is POSIX on Symbian OSP.I.P.S. Is POSIX on Symbian OSOpenGL ESOpenGL ESOpen C/C++ for S60Open C/C++ for S60RGA – Real-time Graphics & AudioRGA – Real-time Graphics & Audio
Sorcery LimitedSorcery Limited 66
P.I.P.S. Is POSIX on Symbian OS
POSIX – Portable Operating System InterfacePOSIX – Portable Operating System Interface
P.I.P.S. Libraries:
LibraryLibrary FunctionalityFunctionality Function Function Coverage (%)Coverage (%)
libclibc Standard C and POSIX APIs Standard C and POSIX APIs 4747
libmlibm Mathematical and arithmetic APIs Mathematical and arithmetic APIs 4242
libpthreadlibpthread Thread creation and synchronizationThread creation and synchronization 6060
libdllibdl Dynamic loading and symbol lookup Dynamic loading and symbol lookup 100100
Sorcery LimitedSorcery Limited 77
OpenGL ES2D & 3D graphics for embedded systems2D & 3D graphics for embedded systemsSubset of desktop OpenGLSubset of desktop OpenGLMay need to switch floating-point to fixedMay need to switch floating-point to fixed3D Demos:3D Demos:
Sorcery LimitedSorcery Limited 88
Open CSuperset of P.I.P.S.Superset of P.I.P.S.Adds support for 5 more libraries:Adds support for 5 more libraries:LibraryLibrary FunctionalityFunctionality SourceSource Function Function
Coverage (%)Coverage (%)
libzlibz In-memory compression and In-memory compression and decompression functionsdecompression functions
zlibzlib 100100
libcryptlibcrypt Cryptography functionsCryptography functions OpenSSLOpenSSL 100100
libcryptolibcrypto Cryptographic services for SSL, Cryptographic services for SSL, TLS, S/MIME, SSH, OpenPGP…TLS, S/MIME, SSH, OpenPGP…
OpenSSLOpenSSL 7777
libssllibssl OpenSSL secure sockets layerOpenSSL secure sockets layer OpenSSLOpenSSL 8686
libgliblibglib General purpose utility libraryGeneral purpose utility library GNOMEGNOME 7777
Sorcery LimitedSorcery Limited 99
Open C++
More useful libraries:More useful libraries:
Standard C++ programming extension for Open CStandard C++ programming extension for Open C
LibraryLibrary FunctionalityFunctionality SourceSource
IOStreamsIOStreams Standard C++ input/output streamsStandard C++ input/output streams STLportSTLport
STLSTL C++ Standard Template LibraryC++ Standard Template Library STLportSTLport
BoostBoost Smart pointers, extra containers Smart pointers, extra containers and math-template functionsand math-template functions
BoostBoost
Sorcery LimitedSorcery Limited 1010
Real-time Graphics & AudioDistributed with Open C/C++Distributed with Open C/C++APIs developed for porting N-Gage gamesAPIs developed for porting N-Gage gamesNot a standard available anywhere elseNot a standard available anywhere elseCan create rich UI without Symbian idiomsCan create rich UI without Symbian idiomsMuch more than just graphics & audio:Much more than just graphics & audio:2D Graphics Sound Effects and Music Video Playback Timers
Input Devices Cameras Lights Device Status and Capabilities
Calendar Alerts/Todo Messaging
Sorcery LimitedSorcery Limited 1111
Open C/C++ & RGA Architecture
Sorcery LimitedSorcery Limited 1212
Coming Soon…Qt – cross-platform application frameworkQt – cross-platform application frameworkOpenKODE – cross-platform native APIsOpenKODE – cross-platform native APIsBetter standard C++ support on SymbianBetter standard C++ support on Symbian
Full support for a dynamically linked STLFull support for a dynamically linked STLSupport for streams and localesSupport for streams and localesThrowing operator newThrowing operator newBetter, though still limited, support for mixing standard C++ and Symbian C++ patternsBetter, though still limited, support for mixing standard C++ and Symbian C++ patternsSupport for global destructorsSupport for global destructors
Sorcery LimitedSorcery Limited 1313
How to do it – The Porting Process
1)1) Convert build filesConvert build files Create a bld.inf file and MMP file(s) for the projectCreate a bld.inf file and MMP file(s) for the project
2)2) Try to compile itTry to compile it3)3) Fix problems (loop until compiles)Fix problems (loop until compiles)4)4) Try to runTry to run5)5) Debug and fix (loop until runs)Debug and fix (loop until runs)6)6) TestTest7)7) Debug and fix (loop until works)Debug and fix (loop until works)
Sorcery LimitedSorcery Limited 1414
Common Problems (& Solutions)
Symbian has E32Main(), while standard C/C++ uses Symbian has E32Main(), while standard C/C++ uses main()main() Pre-Symbian OS v9.3 – add libcrt0.lib ‘glue code’ to your MMP Pre-Symbian OS v9.3 – add libcrt0.lib ‘glue code’ to your MMP
filefile Symbian OS v9.3 onwards – use new target type STDEXE in the Symbian OS v9.3 onwards – use new target type STDEXE in the
MMP file and ‘glue code’ is added automaticallyMMP file and ‘glue code’ is added automatically
No functions exported from a library by default on No functions exported from a library by default on Symbian OSSymbian OS Pre-Symbian OS v9.3 – add IMPORT_C to function declarations Pre-Symbian OS v9.3 – add IMPORT_C to function declarations
and EXPORT_C to the definitions for all exported functionsand EXPORT_C to the definitions for all exported functions Symbian OS v9.3 onwards – use new target types STDDLL or Symbian OS v9.3 onwards – use new target types STDDLL or
STDLIB and all functions with external linkage (non-static) are STDLIB and all functions with external linkage (non-static) are exported by defaultexported by default
Sorcery LimitedSorcery Limited 1515
Common Problems (& Solutions)
Out of memory and/or Kern-Exec 3 panics Out of memory and/or Kern-Exec 3 panics at run-timeat run-time Increase heap size via EPOCHEAPSIZE Increase heap size via EPOCHEAPSIZE
directive in the MMP file (although be aware directive in the MMP file (although be aware that device memory is limited and code may that device memory is limited and code may need re-design and/or allocation failure need re-design and/or allocation failure checks) – default is only 1MBchecks) – default is only 1MB
Increase stack size via EPOCSTACKSIZE Increase stack size via EPOCSTACKSIZE directive in the MMP file – default is only 8KB, directive in the MMP file – default is only 8KB, recommended value for Open C/C++ is 64KBrecommended value for Open C/C++ is 64KB
Sorcery LimitedSorcery Limited 1616
Common Problems (& Solutions)
Standard library clashes for existing ports:Standard library clashes for existing ports: There is an older partial implementation, developed to There is an older partial implementation, developed to
get a Java VM running on Symbian OS, in estlib.lib with get a Java VM running on Symbian OS, in estlib.lib with headers in:headers in:
\Epoc32\include\libc\Epoc32\include\libc This is incompatible with P.I.P.S. & Open C/C++, the two This is incompatible with P.I.P.S. & Open C/C++, the two
cannot be used together. The estlib implementation will cannot be used together. The estlib implementation will be deprecated when P.I.P.S. is considered sufficiently be deprecated when P.I.P.S. is considered sufficiently mature. In practice P.I.P.S. is already much better.mature. In practice P.I.P.S. is already much better.
Sorcery LimitedSorcery Limited 1717
Examples – SoundTouch DLL SoundTouch - open source Audio Processing LibrarySoundTouch - open source Audio Processing Library For changing:For changing:
Tempo (time-stretch) – faster or slower without affecting pitchTempo (time-stretch) – faster or slower without affecting pitch Pitch (key) – alter sound pitch or key without affecting tempoPitch (key) – alter sound pitch or key without affecting tempo Playback rate – alters tempo and pitch simultaneouslyPlayback rate – alters tempo and pitch simultaneously
Implemented in C++, using features of libc, libm and STLImplemented in C++, using features of libc, libm and STL Supports 16bit integer or 32bit floating-point PCMSupports 16bit integer or 32bit floating-point PCM Platform-independent – runs on Windows, Mac & LinuxPlatform-independent – runs on Windows, Mac & Linux Can perform real-time processing on 133MHz PentiumCan perform real-time processing on 133MHz Pentium
Sorcery LimitedSorcery Limited 1818
Examples – SoundTouch DLLVery simple bld.inf file:Very simple bld.inf file:
PRJ_PLATFORMS
DEFAULT
PRJ_EXPORTS
..\inc\SoundTouch.h
..\inc\FIFOSamplePipe.h
..\inc\STTypes.h
PRJ_MMPFILES
SoundTouch.mmp
Sorcery LimitedSorcery Limited 1919
Examples – SoundTouch DLL Fairly simple MMP file (copy most contents from Makefile)Fairly simple MMP file (copy most contents from Makefile)
TARGET SoundTouch.dll
TARGETTYPE dll
UID 0x1000008D 0x0839739D
CAPABILITY ReadUserData
USERINCLUDE ..\inc
SYSTEMINCLUDE \epoc32\include \epoc32\include\stdapis
SYSTEMINCLUDE \epoc32\include\stdapis\sys
SYSTEMINCLUDE \epoc32\include\stdapis\stlport
SOURCEPATH ..\src
SOURCE SoundTouch.cpp SoundTouchDllMain.cpp AAFilter.cpp
SOURCE FIFOSampleBuffer.cpp FIRFilter.cpp
SOURCE RateTransposer.cpp TDStretch.cpp
LIBRARY euser.lib
LIBRARY libc.lib libm.lib libstdcpp.lib
Sorcery LimitedSorcery Limited 2020
Examples – SoundTouch DLL Additional work:Additional work:
Make sure all the source and header files are copied into the Make sure all the source and header files are copied into the workspaceworkspace
Configure for 16bit integer samples in STTypes.hConfigure for 16bit integer samples in STTypes.h Add IMPORT_C & EXPORT_C to the exported function Add IMPORT_C & EXPORT_C to the exported function
declarations and definitionsdeclarations and definitions Compiling gave several errors, all with the same causeCompiling gave several errors, all with the same cause
throw std::runtime_error("Illegal number of channels");
Code like this:
Should compile by simply including <stdexcept> but <string> is needed as well. The string header should be included internally by <stdexcept> but it seems there is a bug in the Symbian version of STLport…
With <string> included in the relevant files it compiles for all build targets.
Sorcery LimitedSorcery Limited 2121
Examples – GuiTuneA more complex port of an open source A more complex port of an open source
guitar tuner for Linux.guitar tuner for Linux. Converted a device Converted a device
driver polling driver polling architecture to use architecture to use Symbian multimedia Symbian multimedia APIsAPIs
Sorcery LimitedSorcery Limited 2222
Examples – GuiTunePorted UI components from gtkmm to Ported UI components from gtkmm to
native Symbian controlsnative Symbian controls
Sorcery LimitedSorcery Limited 2323
Examples – GuiTune Still relatively simple changes to the original Still relatively simple changes to the original
code.code. Full details and code available from the Symbian Full details and code available from the Symbian
Developer Network at:Developer Network at:
developer.symbian.com/main/documentation/porting/developer.symbian.com/main/documentation/porting/
Sorcery LimitedSorcery Limited 2424
Where to Find Out MoreP.I.P.S. wiki page:P.I.P.S. wiki page: developer.symbian.com/wiki/display/pub/P.I.P.S.developer.symbian.com/wiki/display/pub/P.I.P.S.
Forum Nokia Open C/C++ resources:Forum Nokia Open C/C++ resources: www.forum.nokia.com/main/resources/technologies/openc_cpp/www.forum.nokia.com/main/resources/technologies/openc_cpp/
Symbian Developer Network porting page:Symbian Developer Network porting page: developer.symbian.com/main/documentation/porting/developer.symbian.com/main/documentation/porting/
Sorcery LimitedSorcery Limited 2525
Questions?