1

RTXIMANUALINSTALLATION

NOTES ................................................................................................................................................................. 2PACKAGEDEPENDENCIES ................................................................................................................................... 3RequiredPackages .......................................................................................................................................... 3OptionalPackages........................................................................................................................................... 3

UBUNTU8.10/9.04(/9.10)PROCEDURE ............................................................................................................. 4INSTALLINGOPTIONALPACKAGES ................................................................................................................... 13DYNAMO ....................................................................................................................................................... 13Qwt ............................................................................................................................................................... 14

RTXIPLUGININSTALLATION ............................................................................................................................. 15RTXI1.1 ......................................................................................................................................................... 15RTXI1.2 ......................................................................................................................................................... 15

RTAIBENCHMARKTESTS .................................................................................................................................. 16LatencyTest .................................................................................................................................................. 16PreemptTest................................................................................................................................................. 16SwitchesTest ................................................................................................................................................ 17

RTXIPLUGINCREATIONWITHDEFAULT_GUI_MODEL..................................................................................... 18Makeandcompileyourownclass ................................................................................................................ 18Definemodelparameters,inputs,andoutputs............................................................................................ 19Initializethemodel ....................................................................................................................................... 20Theexecute()loop ........................................................................................................................................ 21Theupdate()function ................................................................................................................................... 21

SAMPLEKERNELCONFIG .................................................................................................................................. 23Ubuntu9.10(2.6.31‐14)+linux‐2.6.31.1+gcc4.4.1+RTAIMagma+COMEDICVS ................................... 23

TESTEDENVIRONMENTS .................................................................................................................................. 24

2

NOTES

1/26/2010 RTAIMagmasupportsuptoLinuxkernel2.6.31.8.11/1/2009 RTAIMagmasupportsuptoLinuxkernel2.6.31.1.8/13/2009 Notesupdated.InRTAI3.7.1,thereisnolongerauserspaceinterruptsmodule

(/usr/realtime/modules/rtai_usi.ko).Therelatedsupportisembeddedintheschedulernow.Notethatwithgcc4.3.x,thecstdlibmayneedtobeexplicitlyincluded.RTAI3.7.1seemstohaveaconflictwithComedi0.7.76inthattheydeclareamacrowiththesamenameanddifferentfunctiondeclaration:COMEDI_CLASS_DEVICE_CREATE.

6/15/2009 RTAIv3.7.1releasedwithaddedsupportforCOMEDIcomedi_get_subdevice_flags,andx86

upgradetoLinux2.6.29.4/9/2009 RTAIv3.7isreleasedwithrevisedCOMEDIsupportandLinuxsupportupto2.6.28.Butifyoulook

atthepatches,therearen’tanyfor2.6.28.ComedialsodoesnotlikeRTAI3.6‐cvsupposedlybecauseithasletters,insteadofjustnumbers,inthefilename.RTAI3.6.1stillworksgreat!

1/8/2009 RTAIclosedv3.6on12/10/2008.ThelatestLinuxkernelitsupportsis2.6.23(2/26/2008)fori386

andx86_64.Itsupports2.6.24(5/7/2008)forx86.DoNOTuseversion3.6‐cv.TheCOMEDI0.7.76driversdon’tseemtolikethelettersinthefilename.

3

PACKAGEDEPENDENCIES

RequiredPackages

LinuxKernel http://www.kernel.org/pub/linux/kernel/v2.6RTAI–real‐timeextension http://www.rtai.orgComedi–DAQdrivers http://www.comedi.orgComedilib http://www.comedi.orgHDF5 http://www.hdfgroup.org/HDF5/RTXI http://rtxi.org/QT3qt‐x11‐free‐3.3.8b.tar.gz ftp://ftp.qtsoftware.com/qt/source/

Makesureyouhavethefollowingpackagesinstalled.YouwilldefinitelyneedtodoifyouareinstallingfromaLiveCDorsimilarlyleandistribution.AlotofdistributionshaveniceGUIbasedpackageinstallers(e.g.SUSE‐>Yast‐>SoftwareManagement,Ubuntu‐>SynapticPackageManager).Thenameofthepackagewillvarybetweendistributionssothisisjustaguideline.

Configuringandcompilingstuff: automake make cvs subversion libtoolKernel: ncurses ncurses‐devel Comedi: flex bisonRTXI: qt3 qt3‐devel

OptionalPackagesGSL(gsl,gsl‐devel) http://www.gnu.org/software/gsl/MLton–forDYNAMO http://mlton.org/GnuMP–forDYNAMO http://gmplib.org/Nvidiagraphicsdriver(justincase) http://www.nvidia.com/Download/index.aspx?lang=en‐usQwt(requiredbysomeplugins) http://qwt.sourceforge.net/

4

UBUNTU8.10/9.04(/9.10)PROCEDURE

Alllinesbeginningwith“$”arecommandstoexecuteintheterminal.Tosavesometypingifyouaretryingtochangedirectoriesordosomethingtoafile,typethefirstfewlettersofthatfilenameandhitTAB.Thiswillattempttoautocompletethefilenameforyou.

1. InstallacleanversionofUbuntu.Itwillaskyoutocreateaninitialuser.

2. Loginastheuseryoucreated.Wewilluse“sudo”togetsuperuseradministrativeprivileges.Donotinstall

RTAIwhenloggedinasroot.Itwillnotwork.

3. GettherequiredpackagesforUbuntu.ThesecommandswilllookforthepackagesintheUbunturepository,identifyanydependenciestheyhave,andtellyouhowmuchadditionalspaceyouneedtoinstalleverything.JusthitENTERtoaccepteverythingandinstall.$ sudo apt-get update1 $ sudo apt-get upgrade2 $ sudo apt-get install cvs subversion build-essential $ sudo apt-get install kernel-package linux-source libncurses5-dev $ sudo apt-get install libtool automake $ sudo apt-get install bison flex qt3-dev-tools $ sudo apt-get install libboost-dev libboost-program-options-dev libgsl0-dev

4. DeterminewhichversionoftheLinuxkernelyouhaveandselectacorrespondingRTAIrelease.

$ cat /proc/version Thistellsyouyourcurrentkernelversion(Linuxversion2.6.##.#)aswellasyourgcccompilerversion.GrabacopyofRTAIandchecktheavailablekernelpatches.Versionsolderthan3.7arenotcompatiblewithgcc4.3.3.TogetthelatestCVS(development)versionthatwillbecompatiblewithmorerecentkernelversions:$ cd /opt3 $ sudo cvs -d:pserver:anonymous@cvs.gna.org:/cvs/rtai co magma $ sudo ln -s magma rtai4 Togetthecurrentstablereleaseversion(replacingtheversionnumberwiththeoneyouwant):$ cd /opt $ sudo wget –-no-check-certificate https://www.rtai.org/RTAI/rtai-3.7.1.tar.bz25

1“sudo”givesyousuperuseradministrativeprivileges.Typetherootpasswordattheprompt.2Installsanyupdatesforallpackagesyoucurrentlyhaveinstalled.3“cd”isthecommandtochangedirectories.The/optdirectoryisusuallyreservedforsoftwareandadd‐onpackagesthatarenotpartofthedefaultinstallation.4Thiscreatesasymboliclinksothatrtaipointstothemagmafolder.Thissavesyousometyping.Type$ ls -alintheterminaltoseehowthisworks.5Thisisacompressedformat.Thenextlinewillextractthefolder.

5

$ sudo tar xjvf rtai-3.7.1.tar.bz2 $ sudo ln -s rtai-3.7.1 rtai Navigatetothepatchesdirectoryforyourparticularhardwaree.g./opt/rtai/base/arch/x86/patches.6Listalltheavailablepatchesinthatfolder:$ ls FindthehighestLinuxkernelversionthatmatchesyours.Forexample,youmighthavekernelversion2.6.28‐genericandseeRTAIpatches:

hal‐linux‐2.6.28.2‐x86‐2.2.05.patchhal‐linux‐2.6.28.7‐x86‐2.2.06.patchhal‐linux‐2.6.28.9‐x86‐2.2.07.patch

Youshoulddownloadthevanilla(theofficial“clean”)kernel2.6.28.9.

5. Getthekernelthatcorrespondstoyourversionnumber.$ cd /usr/src $ sudo wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.##.#.tar.bz2 $ sudo tar xjvf linux-2.6.29.4.tar.bz2 $ sudo ln -s linux-2.6.29.4 linux

6. PatchthekernelwiththeRTAIpatchyouidentifiedinstep4.7$ cd /usr/src/linux $ sudo patch -p1 < /opt/rtai/base/arch/x86/patches/hal-linux-2.6.##.#-x86-###.patch Ifyouseemessagesabout“hunks”failing,checkthatthepatchyouareapplyingmatchesyourLinuxkernelversion.Usetheexactsameversion!Ifyouseenomessageatall,justalistofpatchedfiles,thepatchwassuccessful.

7. Configurethekernel.Wewilltakeyourexistingconfigurationasafoundationandthenmakesomemodifications.$ cd /usr/src/linux $ sudo cp /boot/config-‘uname -r‘ .config8 $ sudo make oldconfig

Youwillprobablybepromptedaboutabunchofdifferentconfigurationoptions.Acceptthedefaultoptionbypressingreturnforeachone.Usingthismethod,youwillhavealargekernelthathassupportformanydevicescompileddirectlyintothekernelorasloadablemodules.Tomakeasmallerkernel,disablesomefeaturesyouknowyoudon’tneed.Anobviousonewouldbetabletortouchscreeninputsupport.Tomakethekernelsignificantlysmaller,youcandisablekerneldebugging.Thefollowingcommandwillcreateamenuforconfiguringthekernelforreal‐time.Forsampleconfigurations,seeSAMPLEKERNELCONFIG.

6e.g./opt/rtai/base/arch/x86_64/patches7Thex86_64versionofRTAImayhaveanissuewiththeVDSO.Edit/arch/x86_64/vdso/voffset.h:setVDSO_TEXT_OFFSETto0xC00insteadof0x600.8The`inthefirstcommandisnotaregularsinglequote,butratherthekindonthe~(tilde)key.

6

Ifyoudonotsee“Adeos”,“Interruptpipeline”,or“IPIPE”options,theRTAIpatchdidnotwork.

$ sudo make menuconfig

8. Compilethecustomkernelandinstallit.Thiswilltakealongtime.Youwillgetaseriesof.debpackagesthatcanbecopiedandinstalledontoothercomputerssothatyoudon’thavetorecompiletheentirekernelagain.Ifyoudothis,thecomputersneedtohavesimilarspecifications,e.g.thesamekindofprocessor,thesameoriginalLinuxkernelversion.Ifthesedonotmatch,thereal‐timeperformancewillnotbeoptimizedorthekernelmayevenfailtoboot.$ sudo make-kpkg clean9 $ sudo make-kpkg --initrd kernel_image kernel_headers kernel_source Ifyourfolderpermissionsareincorrect,youmaygetthefollowingerrorwhenyoutrytocompile:dpkg-deb: control directory has bad permissions 2755 (must be >=0755 and <=0755) Sadly,youwillhaveto“clean”andrecompileafterexecutingthefollowingtofixthepermissions:$ chmod –R a-s /usr/src

9. Installthecustomkernel.$ cd /usr/src $ sudo dpkg -i linux-headers-2.6.29.4-adeos_2.6.29.4-adeos-10.00.Custom_i386.deb $ sudo dpkg -i linux-image-2.6.29.4-adeos_2.6.29.4-adeos-10.00.Custom_i386.deb10

10. Bootintoyournewreal‐timekernel!11

$ sudo reboot

11. Verifyhowmanyprocessorcoresarerecognizedbythekernel.Ifyouhaveamulti‐coreprocessoryouwillseesomeoutputforeachCPU.$ cat /proc/cpuinfo

12. ConfigureandinstallRTAIwithoutCOMEDIsupportfornow.MakesureyouselectthecorrectnumberofCPUsornoneoftheRTAImoduleswillload.Ifforsomereasonyoudon’twanttousealltheCPUsthatare

9make‐kpkgisascriptwhichautomatesandreplacesthesequence:makedep,makeclean,makebzImage,makemodules.Alwaysrunmake‐kpkgcleanbeforecompilinganewkernel.10TheLinuxbootloaderiscalledGrubandafterinstallinganewkernel,thefile/boot/grub/menu.lstshouldbeautomaticallyupdatedsothatyoucanchooseyournewkernelwhenbooting.Viewthisfiletomanuallycheckthis.Youwillneedsudoaccesstomanuallyeditit.Ubuntu9.10usesGrub2,whichwilltellyoualltheoperatingsystemsineverypartitionthatitfindswhenitupdatesGrub.Anin‐placeupgradefrom9.04to9.10mayormaynotreplacemenu.lstwithgrub.cfg.11IfyouhaveanewersystemwithanNvidiagraphicscard,thecorrectdrivermaynotbecompiledintothekernel.Youwillgetaterminalinterface(noGUIbecauseitcouldn’tstartanXserver)andsomemessagesthatmightsaysomethinglikeitfoundthemonitorbutcouldn’tsetanyprofilesorthatitcouldnotfindascreen.RebootintoyourdefaultkernelanddownloadtheNvidiadriver.Reboottothereal‐timekernel,navigatetothelocationwhereyoudownloadedthedriverandfollowtheNvidiainstructionstomanuallyinstallit.

7

availabletoyou,youcanbootLinuxwithanoptiontolimitthenumberofCPUs.Onthebootline,addtheflag:maxcpus=#.$ cd /opt/rtai $ sudo make menuconfig

General

Installation‐‐‐>/usr/realtimeKernelsource‐‐‐>/usr/src/linux

Machine (#)NumberofCPUs(SMP‐only)Add‐ons

[]RealTimeCOMEDIsupportinuserspace

YoumaygetanerrorthattheLinuxdirectorymustbespecified,inwhichcaseyouwillhavetoconfigureRTAIfromtheshell:$ sudo ./configure --with-linux-dir=/usr/src/linux --enable-testsuite --disable-rtailab $ sudo make clean12 $ sudo make $ sudo make install Ifyougetthefollowingerrorduringcompilation,reconfigureRTAIwithoutleds‐baseddebuggingsupport.../../../base/include/asm/rtai_leds.h:24:20: error: asm/io.h: No such file or directory $ sudo ./configure --with-linux-dir=/usr/src/linux --enable-testsuite --disable-rtailab\ --disable-leds

Tellyoursystemwheretofindthereal‐timescripts.Ineachopenshelloftheterminal: $ export PATH=/usr/realtime/bin:$PATH

13. Testthereal‐timeperformanceofyoursystem.Theoperatingsystemsplitsmemoryintokernelspace,reservedforrunningthekernelandsomedevicedrivers,anduserspace,whichiswhereuserapplicationsrun.In/usr/realtime/testsuitetherearetwofolders,/kernand/user,containingbenchmarktestsforkernelspaceanduserspace.Inthelatencyfolderrun:

$ sudo ./run

Ifthelatencytestfails,youwillprobablygeta“kernelpanic”thatfreezesyourentiresystem.Thisindicatesthatyourkernelisconfiguredincorrectlysothisisthefirsttestthatyoushouldrun.Youwanttoseezeroesintheverylastcolumnlabeled“overruns.”Tostopthetest,pressCTRL‐C.Formoreinformationaboutthisandotherreal‐timebenchmarktests,seeRTAIBENCHMARKTESTS.

14. GetComedi.

12Itisagoodideatorunmake cleanbeforemakewheneveryouneedtorecompileamodule.

8

$ cd /opt $ sudo cvs -d :pserver:anonymous@cvs.comedi.org:/cvs/comedi login Thereisnopassword,justhitEnter. $ sudo cvs -d :pserver:anonymous@cvs.comedi.org:/cvs/comedi co comedi $ sudo cvs -d :pserver:anonymous@cvs.comedi.org:/cvs/comedi co comedilib $ sudo cvs -d :pserver:anonymous@cvs.comedi.org:/cvs/comedi co comedi_calibrate

15. Configure,compile,andinstallCOMEDILIB.

$ cd /opt/comedilib $ sudo sh autogen.sh $ sudo ./configure –-with-udev-hotplug=/lib --sysconfdir=/etc $ sudo make $ sudo make install

16. Configure,compile,andinstallCOMEDI‐CALIBRATE.

$ cd /opt/comedi_calibrate $ sudo autoreconf -i $ sudo ./configure $ sudo make $ sudo make install UnderUbuntu9.10,configuremayfailandgivealibboost‐program‐optionserror.In/usr/lib,listallthelibboostlibraries:$ ls | grep libboost Youmayhavelibboost_program_options‐mtratherthanlibboost‐program_options.Youwillneedtochangeanyreferencestothislibrarytothecorrectlibraryname.Inthefile/opt/comedi_calibrate/configure.ac,findtheline:

AC_CHECK_LIB([boost_program_options],[main],,AC_MSG_ERROR([Failed to find libboost_program_options.]))

Changeboost_program_optionsinthefirstargumenttoboost_program_options‐mt.Youalsoneedtoedit/comedi/comedi_soft_calibrate/Makefile.am.Inthelinebeginningwithcomedi_soft_calibrate_LDADD,change–lboost_program_optionsto–lboost_program_options‐mt.Repeatallcommandsinstep16toconfigureCOMEDI‐CALIBRATE.

17. Configure,compile,andinstallCOMEDI.

$ cd /opt/comedi $ sudo sh autogen.sh $ sudo ./configure $ sudo make $ sudo make install $ sudo mkdir -p /usr/local/include/linux $ sudo cp include/linux/comedi.h include/linux/comedilib.h /usr/local/include/linux

9

Tocalibrateyourcard,usecomedi_calibrate,orcomedi_soft_calibrateifyouhaveaM‐seriesNIcard.

18. NowwewillrecompileRTAI,butthistimewithComedisupport!

$ cd /opt/rtai $ sudo make menuconfig

General

Installation‐‐‐>/usr/realtimeKernelsource‐‐‐>/usr/src/linux

Machine (#)NumberofCPUs(SMP‐only)Add‐ons

[*]RealTimeCOMEDIsupportinuserspaceCOMEDIinstallationdirectory‐‐‐>/opt/comedi

OrconfigureRTAIfromtheterminal:$ sudo ./configure --with-linux-dir=/usr/src/linux --enable-testsuite --disable-rtailab\ --disable-leds --enable-comedi-lxrt --with-comedi=/opt/comedi $ sudo make $ sudo make install

IfyoumadeamistakeconfiguringRTAI,youmustuninstallComediandComedilibbeforereinstallingRTAI.Comedimustbecompiledwithreal‐timesupportsoithastobebuiltafterRTAI.Touninstallgotothecomediandcomedlibdirectoriesand:$ sudo make uninstall

19. TouseRTAIyoumusthavethenecessaryRTAI&Comedimodulesloaded.CreatethesescriptstoloadallthemodulesweneedforRTXI.In/usr/realtime/bin:13 $ sudo nano /usr/realtime/bin/rtaiinsmod

# Inserts RTAI and Comedi modules in kernel and configures the drivers. insmod /usr/realtime/modules/rtai_hal.ko insmod /usr/realtime/modules/rtai_lxrt.ko insmod /usr/realtime/modules/rtai_sem.ko insmod /usr/realtime/modules/rtai_shm.ko modprobe kcomedilib insmod /usr/realtime/modules/rtai_comedi.ko # trick to avoid shared interrupts with uhci_hcd devices # modprobe -r uhci-hcd

13*DRIVER*istheComedidriveryouwillbeusing,e.g.ni_pcimio.IfyouhaveanolderNIE‐Seriescard,youmayneedtousetheni_atmiodriver.ThesecardsmaybedetectedasPlugandPlay(PnP)devices,whichyoucancheckbytypingdmesg andlookingforthem.Thisdriverhas2.6kernelsupportandshouldautomaticallyprobeforasupportedboard.Ifyourboardisnotrecognized,downloadtheisapnptoolspackagefromhttp://www.roestock.demon.co.uk/isapnptools/.

10

# Hardware dependent lines below. modprobe *DRIVER* # modprobe uhci-hcd # for the trick to avoid shared interrupts

CTRL‐Otosavethefile.CTRL‐Xtoexit.NowcreateascriptthatyoucanusetoquicklyremoveRTAI&Comedimodulesfromkernel:$ sudo nano /usr/realtime/bin/rtairmmod

# Removes RTAI and Comedi modules from kernel. modprobe -r *DRIVER* rmmod rtai_comedi modprobe -r kcomedilib rmmod rtai_shm rmmod rtai_sem rmmod rtai_lxrt rmmod rtai_hal

Makethesescriptsexecutable:$ sudo chmod +x /usr/realtime/bin/rtaiinsmod $ sudo chmod +x /usr/realtime/bin/rtairmmod

20. Nowlet’sexecuteyourscriptautomagicallywhenyoubootthekernel.Open/etc/rc.localforediting.Addalinetotheendbeforetheexit 0:

#!/bin/sh -e # # rc.local # # This script is executed at the end of each multiuser runlevel. # # By default this script does nothing. /usr/realtime/bin/rtaiinsmod exit 0

Rebootandcheckthatallthemoduleslistedinyourscripthavebeenloaded:$ lsmod | grep rtai YoucanalsocheckthekernellogtoseethatRTAIisregistered,thattheschedulerandtimeraresetup,theversionofCOMEDIthatisloaded,andtheIDsofanyavailableDAQcards:$ dmesg

21. InstalltheHDF5librariesinthecorrectlocation.Thiswilltakesometimetocompile.

11

$ cd /opt $ sudo wget http://www.hdfgroup.org/ftp/HDF5/current/src/hdf5-1.8.4.tar.gz $ tar xvf hdf5-1.8.4.tar.gz $ cd hdf5-1.8.4 $ sudo ./configure --prefix=/usr $ sudo make $ sudo make install

YoumayalsowanttogetthegraphicalHDFViewapplicationthatwillletyouexploreyourfile(http://www.hdfgroup.org/HDF5/).

22. GrabthelatestdevelopmentversionofRTXIfromSVN.We’llputitinyouruser’shomefolder.14

$ cd $HOME $ svn co https://rtxi.svn.sourceforge.net/svnroot/rtxi/trunk rtxi

23. Configure,build,&installRTXI.$ cd rtxi $ sh autogen.sh $ ./configure IftheQTlibraryisinstalledsomewherethatRTXIdoesn’tlook,youwillprobablygetanerroraboutnothavingaworkingQTinstallation.ItteststhisbytryingtocompileasmallQTapplication.ConfigureRTXIwiththecorrectlocationofQT,e.g.:$ ./configure –-with-Qt-dir=/usr/qt $ ./configure –-with-Qt-dir=/usr/lib/qt3 Nowdo:$ make $ sudo make install

InUbuntu9.10,oranydistributionwithautoconf>2.63,autogen.shmayproduceaconfigurescriptthatfailswithanfisyntaxerrorwhencheckingforaQtinstallation.Thisiscausedbyanemptyif–then‐else‐fistructureproducedbytheBNV_HAVE_QTmacroinautogen.sh.Inthe/rtxi/m4folder,editbnv_have_qt.m4.Aroundline510,youshouldseealinewiththiscomment:

# Leave bnv_qt_lib_dir undefined

Addalinebeforethislinethatisacolon“:”allbyitself:

: # Leave bnv_qt_lib_dir undefined

14ToupdateRTXI,repeatthesvncommandtograbthelatestversion.Makeabackupcopyoftheentire/rtxifolderfirstsothatyoucanrestoretheoldversionifthenewonedoesn’twork.

12

Thecolonisa“no‐operation”statementfortheshellandworksaroundthesyntaxerror.Instead,ofbnv_have_qt.m4,youmayhaveax_have_qt.m4.Theyareessentiallythesamefileandthesameinstructionsapply.

24. StartRTXIfromtheterminal.IfyoudidnotreboottotestyourscriptsforautomaticallyloadingtheRTAIand

Comedimodules,youwillhavetomanuallyinsertthemfirst:$ cd /usr/realtime/bin $ sudo ./rtaiinsmod $ rtxi

InwhateverterminalwindowyoustartRTXIfrom,youwillseeanyerrormessages,debuggingmsgsyouwriteinyourcode,etc.YoudonotwanttoseeanyerrorsaboutComedi.Ifyouseeanerroraboutnotbeingabletoload/etc/rtxi.conf,copyitthere:$ sudo cp $HOME/rtxi/rtxi.conf /etc

13

INSTALLINGOPTIONALPACKAGES

DYNAMOTheseinstructionswillallowyoutocompiletheDYNAMOtranslationscriptfromscratch.Youshouldalreadyhaveaworkingdynamoscript,anditshouldbelocatedin/usr/bin.

1. InstallMLton:

$ sudo apt-get install mlton

2. TheGnuMPBignumLibraryshouldbeincludedfromStep1butifnot,itisavailablefrom(http://gmplib.org/).Ifitcompilescorrectly,youshouldnotseeanyfailedtestsduring“makecheck.”Downloadthetarfileto/optandextractitthere.WhileinsidetheGMPfolder:$ ./configure --prefix=/usr $ make $ make check $ make install

3. In/rtxi/dynamo:$ mllex dl.lex $ mlyacc dl.grm $ mlton dynamo.mlb $ sudo cp dynamo /usr/bin

14

Qwt

InstallQwtlibrary(http://qwt.sourceforge.net/).Togetasnapshotofallthedevelopmentversion:

$ svn co https://qwt.svn.sourceforge.net/svnroot/qwt/branches/qwt-5.2 Togetthelateststablerelease:

$ svn co https://qwt.svn.sourceforge.net/svnroot/qwt/trunk/qwt Editqwtconfig.prisothatthecorrespondinglinesmatch:

unix{ INSTALLBASE=/usr}target.path =$$INSTALLBASE/libheaders.path =$$INSTALLBASE/include/qwt‐qt3doc.path =$$INSTALLBASE/doc/qwt‐qt3

Editqwt.prf:

unix{ QwtBase =/usr LIBS +=‐L$${QwtBase}/lib‐lqwt}

INCLUDEPATH +=$${QwtBase}/include/qwt‐qt3

Now:

$ cd /opt/qwt-5.2 $ sudo qmake $ sudo make $ sudo make install $ cd /usr/lib $ sudo ln -s qwt-qt3/libqwt.so libqwt.so $ sudo ln -s qwt-qt3/libqwt.so.5 libqwt.so.5

15

RTXIPLUGININSTALLATION

The/rtxi/pluginsdirectorycontainsmajorpluginsthatarenecessaryforsystemcontrolandcommonlyusedpluginssuchastheOscilloscopeorDataRecorder.

RTXI1.1Storecustommodelsin/rtxi/models.Eachplug‐inwillneeditsownMakefile.amfilethatisusedtogenerateafullMakefileforcompilation.In/rtxi,run./autogen.shand./configure.RemembertoconfigurewiththecorrectQtdirectoryifneeded.Thiswillautomaticallygeneratemakefilesindirectorieslocatedin/rtxi/models.Itwillalsogenerate/rtxi/models/Makefile.am/.Anymodelsdirectlyplacedin/rtxi/modelsshouldalreadybedetected.Ifyoumakesubdirectoriesin/rtxi/models,youwillhavetomanuallyedit/rtxi/models/Makefile.ammanuallytoincludethosemodels.

SUBDIRS = mimic neuron YOURMODELDIRS/YOURMODEL

In/rtxi,domakeandmakeinstall.

Ifyoumakefurtherchangestoyourmodelfiles,youonlyneedtodomakeinstallinrtxi.

RTXI1.2Inthisversion,youcancompileyourmodelsoutsidethesourcetree.InsteadofusingMakefile.amandusingtheautomakescriptstogenerateyourMakefiles,youwillmanuallycreateMakefiles.BelowisasampleMakefile.Youshouldgiveyourplug‐inaname,whichwillappearasmy_plugin.sowhenyouloadyourplug‐inwithinRTXI.Youshouldhaveonlyonemajorheaderfile.ALLothersourcefilesincludingotherincludedclassesshouldbelistedunderSOURCES.Thebacksplashsimplycontinuestheline.Youcouldlistthemallthesamelinewithaspaceinbetweeneachfilename.Youcanalsolinktoanyotherlibraries,suchasQwt.

PLUGIN_NAME = my_plugin HEADERS = my_plugin.h SOURCES = my_plugin.cpp \ included_class.h\ Included_class.cpp LIBS = -lqwt ### Do not edit below this line ### include $$(shell rtxi_plugin_config --pkgdata-dir)/Makefile.plugin_compile

16

RTAIBENCHMARKTESTS

LatencyTest

Thistestwillverifytheoverallperformanceofyoursystem.Inoneshotmode,itmeasuresthedifferenceintimebetweentheexpectedswitchtimeandthetimewhenataskisactuallycalledbythescheduler.Thistestprintsonelineeverysecondandgivesyoutheminimum,average,andmaximumlatenciesforthatperiodaswelltheminimumandmaximumoveralllatenciesthatoccurredovertheentiretest.Openupsomeotherprograms,copysomefilesfromonelocationtoanother,andloadthenetworkconnectiontoseehowitaffectsthelatency.Youshouldfindslightlyhigherlatencieswiththeuserspacetestthanthekernelspacetest.Yourreal‐timeperformanceislimitedbythemaximumlatency(latmax)youcanachieveandyougenerallydon’twanttobedoingothertasks.Youalsoshouldnotseeanyoverruns,whichoccurswhenthelatencycompletelyexceedsyournominalperiod.NegativetimeinthelatencytestisduetothefactthatRTAIperformsacalibrationatstartupthattriestominimizethejitterinthereal‐timetaskandanticipatesthecall.

##RTAIlatencycalibrationtool###period=100000(ns)#avrgtime=1(s)#donotusetheFPU#startthetimer#timer_modeisoneshotRTAITestsuite‐KERNELlatency(alldatainnanoseconds)RTH| latmin| ovlmin| latavg| latmax| ovlmax| overruns

RTD| ‐1524| ‐1524| ‐1442| ‐83| ‐83| 0 RTD| ‐1491| ‐1524| ‐1440| 3395| 3395| 0 RTD| ‐1489| ‐1524| ‐1441| 3381| 3395| 0 RTD| ‐1491| ‐1524| ‐1440| 3349| 3395| 0

Ifyouperiodicallyseeanoverrun(perhapsevery64seconds)thatresultsinamaximumlatencyofseveralhundredmicroseconds,youmayhaveanSMI(SystemMaintenanceInterrupt)issue.Thisfeaturecanbefoundoncertainchipsetse.g.Intel82845845.DisablingSMIcancausesomecomputerstooverheatandmaydamagethosecomputers.Other“latencykillers”are:heavyDMAactivities(usingtheharddisk),usinganacceleratedX‐server,USBlegacysupport,powermanagement(APMandACPI),andCPUfrequencyscaling.Ifyouhavedisabledalloftheseinthekernelalready,checkyourBIOSandseeifyoucandisablethemthere.

PreemptTest

Thistestisastressutilitythatverifiesthereal‐timeschedulersunderheavyprocessingload.Thissoftwarecombinesthelatencycalibrationtaskwithafastandslowtasktohavetwolevelsofpreemption.

17

RTAITestsuite‐UPpreempt(alldatainnanoseconds)RTH| latmin| latavg| latmax| jitfast| jitslow

RTD| ‐1781| ‐1267| 1930| 3228| 2724 RTD| ‐1782| ‐1143| 1930| 3228| 2724 RTD| ‐1782| ‐1135| 1930| 3228| 2724 RTD| ‐1782| ‐1166| 1930| 3228| 2724

SwitchesTest

ThistestprovidesinformationaboutthemaximumamountoftimeRTAIneedstodisableinterrupts.Thetestusesarepeatedsequenceofsuspend/resumeandsemaphoresignal/waitcallsunderaheavyprocessingload.Theswitchingtimeshouldbelessthanthemaximumlatencytime.ThereallatencylimitationisseldomduetoRTAIbutanintrinsicdrawbackofusingageneralpurposeCPUforreal‐timeapplications.

Nov1120:49:02dynamickernel:[9006.244009]Nov1120:49:02dynamickernel:[9006.244009]Waitforit...Nov1120:49:02dynamickernel:[9006.244009]Nov1120:49:02dynamickernel:[9006.244009]Nov1120:49:02dynamickernel:[9006.244009]FOR10TASKS:TIME14(MS),SUSP/RESSWITCHES40000,SWITCHTIME(INCLUDINGFULLFPSUPPORT)339(ns)Nov1120:49:02dynamickernel:[9006.244009]FOR10TASKS:TIME14(MS),SEMSIG/WAITSWITCHES40000,SWITCHTIME(INCLUDINGFULLFPSUPPORT)347(ns)Nov1120:49:02dynamickernel:[9006.244009]FOR10TASKS:TIME14(MS),RPC/RCV‐RETSWITCHES40000,SWITCHTIME(INCLUDINGFULLFPSUPPORT)385(ns)

18

RTXIPLUGINCREATIONWITHDEFAULT_GUI_MODEL

Thequickestwaytocreatingyourownplug‐inistomakeacopyofanexistingplug‐inandmodifyit.WerecommendthatyoustartwiththeHodgkin‐Huxleyneuronmodelwhichisautomaticallyprovidedasthe“neuron”plug‐in.Thesourcecodeisprovidedhereasthehhneuronmodel.Thismodelisbasedonthedefault_gui_modelclass,whichcreateslabelsandtextboxesforyourmodelparametersandstatevariablesaswellasthePause,Modify,andUnloadbuttons.Mostplug‐inswillfitintothisframework.Eachplug‐inisaseparateclassthatiscompiledasasharedlibraryorsharedobjectwitha*.sofileextension.Thesesharedobjectsfunctionbasicallylikeloadablemodulesandunlessotherwisespecified,youcaninstantiateanynumberofthem.Forexample,youcanhavemultipleHHmodelneuronsandmultipleOscilloscopesrunning,butforobviousreasons,youcanonlyhaveoneSystemControlpanel.Thefollowingsectionswillillustratetheportionsofcodethatyouwillneedtoedit.Besuretoleaveothersectionsofthecodeuntouched.

Makeandcompileyourownclass1. Renameyourcustomplug‐infolderandtheCPPandheaderfile.2. IntheCPPfile,changethereferencetoincludeyournewheaderfile.3. Ifyoulike,throughouttheCPPandheaderfile,changealltheclassnamestoyourownclass.Ifyou

startedfromtheHodgkin‐Huxleyneuronmodel,youwouldreplaceeveryinstanceof“Neuron”beforethefunctiondeclarationsandimplementions.

4. EdittheMakefiletorefertoyourclassandfilename.Youcan,ofcourse,incorporateotherclasses,andyoumustaddtheappropriateincludedfilestotheSOURCESlistintheMakefile.Listalltheadditional*.cppand*.hfilesontheSOURCESlinewithasinglespacebetweeneachfilename.Ifyouuseanyadditionallibraries,youcanaddthemusingthe“LIBS=”tag.BelowisthesampleMakefileprovidedas/usr/local/share/rtxi/Makefile.plugin_example.Asnoted,donoteditthelastline.Thiswillappendadditionalcodethatcorrectlylinksyournewplug‐inwithothersharedlibrariesonyoursystemandmakesthemavailabletoRTXI.FormoreexamplesofMakefiles,seeanyofthedownloadableplug‐insonthissite.

HereisasampleMakefileforRTXI1.2:

PLUGIN_NAME = my_plugin HEADERS = my_plugin.h SOURCES = my_plugin.cpp \ included_class.h\ Included_class.cpp LIBS = -lqwt ### Do not edit below this line ### include $$(shell rtxi_plugin_config --pkgdata-dir)/Makefile.plugin_compile

19

5. Compileyourplug‐in.Insideyourplug‐in’sdirectory:

$ make $ sudo make install

Youshouldseesomelibrariesappearinthatdirectoryandmy_plugin.soshouldbecopiedto/usr/local/lib/rtxi.WhenyougotothePlug‐inLoaderinRTXI,youshouldseeyournewplug‐inthere.

Definemodelparameters,inputs,andoutputs

EachlineinthestructurebelowdefinesanINPUT,OUTPUT,PARAMETER,STATEvariable,orCOMMENTfortheplug‐in.DeclaringanINPUTcreatesaslotforyourplug‐intoacquiredatafromtheDAQcardorfromanotherplug‐in.DeclaringanOUTPUTcreatesasignalthatisemittedfromyourplug‐inthatcanbesendtoyourDAQcardoranyotherplug‐in.TheseinputsandoutputswillbeaccessiblewhenyouopentheConnectorplug‐in.Intheexamplecodebelow,thereisonlyoneinput,Iapp,andit’svalueisaccessedasthevariable“input(0)”.Thevaluesofadditionalinputswouldbeaccessedas“input(1)”,“input(2)”,andsoon.Thesameruleappliesforoutputseg.thevalueofVmisaccessedas“output(0)”.

STATEvariablesandPARAMETERsarenumericdatatypes.StatevariablesareinternalmodelvariablesthatcannotbemodifiedbytheuserthroughtheGUI.Theirvaluesmaybeconstantortheymaychangeovertime.APARAMETERwillacceptuserinputthroughtheGUIandcanbemodifiedontheflyduringreal‐timeexecution.StatevariablesandparametersappearintheGUIintheorderthattheyaredeclared.Theonlyvisibledifferencebetweenthemisthatthetextboxesforstatevariablesarenoteditable.Youcansimplymonitorthevaluesofthestatevariablesastheychange.Intheexamplecode,thismechanismisusedtomonitortheionchannel’sactivationvariables,whicharedependentonmembranevoltageandintegratedinreal‐time.ACOMMENTissimilartoaPARAMETER,butisusedtostoretextstringssuchasinformationabouttheexperimentthatyouwouldliketolog.ThesearesavedtotheDataRecorderjustlikeparameters,butshouldnotbemodifiedinreal‐timeduringmodelexecution.

Thedeclarationofthesetypesfollowsasimplesyntax.ThefirstargumentoneachlineisthelabelforthetextboxintheGUI.Thisdoesnothavetobethesameasthevariablenameyouuseinthecodetoactuallystoretheparametervalues.ThesecondargumentisdisplayedasaTooltipwhenyouuseyourmousetohoverthecursoroverthatentryintheGUI.Enteranydescriptiveinformationhereaboutthevariable,suchasanexpandedformofyourtextlabelorthecorrectunitsofmeasurement.Thethirdargumentdefinesthevariableasaninput,output,etc.Noticethatforparameters,youcanalsospecifywhetheritisadoubleorintegernumerictype.

static DefaultGUIModel::variable_t vars[] = { {"Iapp","A",DefaultGUIModel::INPUT,}, {"Vm","V",DefaultGUIModel::OUTPUT,}, {"V0","mV",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"Cm","uF/cm^2",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"G_Na_max","mS/cm^2",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,},

20

{"E_Na","mV",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"G_K_max","mS/cm^2",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"E_K","mV",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"G_L","mS/cm^2",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"E_L","mV",DefaultGUIModel::PARAMETER|DefaultGUIModel::DOUBLE,}, {"rate","Hz", DefaultGUIModel::PARAMETER|DefaultGUIModel::UINTEGER,}, {"m" "Sodium Activation",DefaultGUIModel::STATE,}, {"h","Sodium Inactivation",DefaultGUIModel::STATE,}, {"n","Potassium Activation",DefaultGUIModel::STATE,}, };

Initializethemodel

Thenextsectionisthemodelconstructor.Ifyouchangedtheclassname,thiswouldread“YOURMODEL::YOURMODEL”.Youcansetthetextthatwillappearinthetitlebarofyourplug‐inwindow.Inthissection,youshouldinitializeallthevariablesandparametersandmakesurethattheGUIreflectstheactualvaluesthatarebeingused.Inmanyoftheothermodels,youwillfindmuchofthiscodebrokenoutintoaseparatefunctionorcontainedinsidetheupdate()functionundertheINITflag.Thereareseveralfunctionsherethatwillbeveryuseful.Toaccessthereal‐timeperiod,call:

RT::System::getInstance()->getPeriod();

Thisreturnstheperiodinnanoseconds.ToassignavariabletoaSTATEvariableintheGUI,use

setState("YOUR_GUI_LABEL",YOUR_VARIABLE);

YOUR_GUI_LABELmustexactlymatchthelabelthatyousetinvariable_tvars[]above.Similarly,youcaninitializetheGUIforPARAMETERswith:

setParameter("YOUR_GUI_LABEL",YOUR_VARIABLE);

ItisconvenienttoperformunitconversionswhencallingthesefunctionssothattheGUIacceptsinputinmoreuser‐friendlyunits.Finally,youshouldcallrefresh()toupdatetheGUItoreflectyourchanges.TheGUItextboxeswillbeinitializedtothecurrentvaluesofthevariablesandSTATEvariableswillbeupdatedperiodicallyduringmodelexecution.

Neuron::Neuron(void) : DefaultGUIModel("Neuron", ::vars, ::num_vars) { V = V0; m = m_inf(V0); h = h_inf(V0); n = n_inf(V0); period = RT::System::getInstance()->getPeriod() * 1e-6; setState("m", m); setState("h", h); setState("n", n); setParameter("V0", V0); setParameter("Cm", Cm); setParameter("G_Na_max", G_Na_max); setParameter("E_Na", E_Na); setParameter("G_K_max", G_K_max); setParameter("E_K", E_K);

21

setParameter("G_L", G_L); setParameter("E_L", E_L); setParameter("Iapp_offset", Iapp_offset); setParameter("rate", rate); refresh(); }

Theexecute()loop

Theexecute()functionwillruntocompletiononeverytimestep.Thecomputationsperformedheremustcompletewithinthereal‐timeperiodthatyouhavesetintheSystemControlpaneltomaintainsystemstability.Theefficiencyofyourcodeherewillaffecttheperformanceofyoursystem.Youshoulduseprivatevariablesdefinedintheclassheaderratherthancreatingvariablesinsidethefunctiononeverytimestep.Ifyouabsolutelymustcreateavariableinsideexecute(),useastaticcallsothatthesamememoryblockisusedeachtime.Youshouldbewaryofusingdo‐whileandforstructuresifyouareuncertainhowlongtheseloopswilltaketocomplete.Withintheexecutefunction,youmustalsobecarefultoboundtheoutputsignalandperformyourownerrorcheckingtomaintainthestabilityoftheclosed‐loop.Noticethatattheend,wehavesetoutput(0)toupdatetheoutputsignalemittedbythisplug‐in.

void Neuron::execute(void) { for (int i = 0; i < steps; ++i) solve(period / steps, y); output(0) = V * 1e-3; }

Theupdate()function

Thisfunctionisprovidedwithseveralflagstohelpyouorganizeyourcodeandhandleeventsinyourplug‐in.Theflagsprovidedwiththedefault_gui_modelclassare:

• INIT:non‐eventrelatedbutusefulforplacingcodetoinitializethemodel• MODIFY:calledwhenthe"Modify"buttonispressed• PAUSE:calledwhenthemodelispaused• UNPAUSE:calledwhenthemodelisunpaused• PERIOD:calledwhenthereal‐timeperiodofthesystemischanged

UndertheMODIFYflag,youshouldgraballthevaluesintheGUItextboxesandupdatethevaluesoftheparametersasfollows:

YOUR_VARIABLE = getParameter("YOUR_GUI_LABEL").toDouble();

IfyoudoanyunitconversionswithsetParameter(),makesureyoudotheinversewithgetParameter().ThePAUSEflagisespeciallyimportant.Iftheoutputoftheplug‐inisacurrentbeinginjectedintotheneuron,youdon'twanttobestillinjectingcurrentwhenyouthinkthemodelisstopped.Insomecases,youwillwanttoresetcertaininternalvariableswhenyoustoporstartthemodeleg.acounterthatkeepstrackofyourmodelexecutiontime.UnderthePERIODflag,youwillalwayswanttoupdateyourmodelwiththenewreal‐timeperiod.

22

void Neuron::update(DefaultGUIModel::update_flags_t flag) { if (flag == MODIFY) { V0 = getParameter("V0").toDouble(); Cm = getParameter("Cm").toDouble(); G_Na_max = getParameter("G_Na_max").toDouble(); E_Na = getParameter("E_Na").toDouble(); G_K_max = getParameter("G_K_max").toDouble(); E_K = getParameter("E_K").toDouble(); G_L = getParameter("G_L").toDouble(); E_L = getParameter("E_L").toDouble(); Iapp_offset = getParameter("Iapp_offset").toDouble(); rate = getParameter("rate").toDouble(); steps = static_cast (ceil(period * rate / 1000.0)); V = V0; m = m_inf(V0); h = h_inf(V0); n = n_inf(V0); } else if (flag == PERIOD) { period = RT::System::getInstance()->getPeriod() * 1e-6; steps = static_cast (ceil(period * rate / 1000.0)); } }

Manymodelswilluseaswitch‐casesyntaxforthissectionasfollows:

update(DefaultGUIModel::update_flags_t flag) { switch (flag) { case INIT: setParameter("V0 (mV)", QString::number(V0)); // initialized in mV, display in mV : setState("m", m); : break; case MODIFY: : break; case PAUSE; : break; case UNPAUSE: : break; case PERIOD: : break; default: break; } }

Makesureyouendeachcasewitha"break;".

23

SAMPLEKERNELCONFIG

Ubuntu9.10(2.6.31‐14)+linux‐2.6.31.1+gcc4.4.1+RTAIMagma+COMEDICVS

Menuconfig

GeneralsetupSet"Localversion‐appendtokernelrelease"to"‐adeos"[orwhateveryouwant]

Enableloadablemodulesupport [*]Moduleunloading []ModuleversioningsupportProcessortypeandfeatures

[*]Symmetricmulti‐processingsupport[]Supportsparseirqnumbering15Processorfamilyto“Pentium‐4/Celeron/Pentium‐4M/olderXeon”[whateveryouhave]PreemptionModel‐‐‐>PreemptibleKernel(Low‐LatencyDesktop)[*]Interruptpipeline[*]LocalAPICsupportonuniprocessors [*]IO‐APICsupportonuniprocessors

PowermanagementandACPIoptions[*]PowerManagementsupport[]SuspendtoRAMandstandby[]Hibernation[*]ACPI(AdvancedConfigurationandPowerInterfaceSupport []ACAdapter []Battery []Button [*]Fan [*]Dock [*]Processor [*]ThermalZone

[]SmartBatterySystemCPUFrequencyscaling []CPUFrequencyscaling

Kernelhacking []Kerneldebugging(optional:forsmallerkernel)

[]KGDB:kerneldebuggingwithremotegdbReturntoinstallationdirections,step7.

15Disablethisfeatureifyougetthefollowingerrorwhencompiling.Happily,thiserroroccursveryearlyintheprocess: include/linux/ipipe.h:76:2error:#error“CONFIG_NR_CPUSistoolarge,pleaselowerit

24

TESTEDENVIRONMENTS

DellOptiplex/AcerVeritonCPU:IntelPentiumDCPU3.00GHz(family:15,model:4)IntelCorporation82945G/GZ/P/PLDellDimensionCPU:IntelPentium43.20GHz(family:15,model:3)IntelCorporation82875P/E7210nVidiaNV34(GeforceFX5200)ASLMarquisCPU:Intel4‐coreXeonModelE54052.5GHz,1333mhzFSB,6M+6ML2cache,80W8GBDDR2‐667ECCFB‐DIMM(2GBx4)Intel5500/5520ChipsetASUSEN7200GS(GeForces7200GS)HPLaptop/newerDelldesktopCPU:IntelCoreDuoNvidiaASUSLaptopIntelCorporation82801I(ICH9Family)ATITechnologiesIncMobilityRadeonHD3650ASUSEeePC900IntelCorporationMobile915GM/PM/GMS/910GMLIntelCorporationMobile915GM/GMS/910GMLExpressGraphicsController(rev04)IntelCorporation82801FB/FBM/FR/FW/FRW(ICH6Family)