>jbohren.

com< home articles tutorials projects photo

articlelist

articlepages

rssfeed

27Sep2014byJonathanBohren<meatjbohren.com>

XenomaionUbuntu12.04(LTS)
xenomai realtime tutorial

Introduction
Thisisatutorialonbuildinganx86(32or64bit)LinuxkernelwiththeXenomaipatchesonUbuntuLinux.
Theendresultisadebianpackagewhich,wheninstalled,properlyregistersitselfwiththeUbuntupackage
managementsystemsothatyoudontclutterupyourmachineandcanquicklyiterateifyouneedtotry
differentconfigurationoptions.
NotethatthereareseveralwaystogetrealtimesupportonLinux,andyoushouldmakesurethatyoure
usingtheapproachthatrequirestheleastamountofefforttofulfillyourneeds.
Thefollowingisadaptedfrom:
BuildingakernelwithUbuntu
Xenomai2.6README
Thistutorialwasoriginallyhostedongooglecode,buthasmovedheresincethatpagemightgoawayat
somepoint.
ThereareadditionaldetailsforotheroptionsaswellnumerouscommentsonasimilarXenomaibuildgivenin
anothertutorialbySeanKelleyhere.

Contents
Introduction
BuildandInstallaXenomaiPatchedLinuxKernel
DownloadandInstallUbuntu12.04
PackagePrerequisites
PickaXenomaiVersion
SetupConvenienceVariablesandWorkspace
DownloadandUnpackXenomai
DownloadandUnpacktheLinuxKernelSource
PatchtheKernel
ConfiguretheKernel
RequiredOptions
RTSocketCANOptions
OptionsforManyThreadedSystemslikeOrocos
BuildtheKernel
ConfigureXenomaiUserLibraries
AddxenomaiGroupForNonrootUsage
BootandTesttheXenomaiKernel
EstimateClockLatency
TroubleshootingandOtherConfigurationOptions
IOAPIC
Nouveau
PeakCANBusDriver(peak_pci)
IRQProblems
NvidiaCardsandNvidiaDrivers

BuildandInstallaXenomaiPatchedLinuxKernel
DownloadandInstallUbuntu12.04
Ubuntu12.04PrecisePangolinisanUbuntuLTS(LongTermSupport)release,andaninstallisocanbe
foundonUbuntusservers.WhileUbuntu14.04TrustyTaheristhemostrecentLTSreleaseatthetimeof
thiswriting,ithasnotbeensufficientlytestedbytheroboticscommunity.

PackagePrerequisites
sudo apt-get install kernel-package
sudo apt-get install fakeroot build-essential crash kexec-tools makedumpfile kernel-wedge
sudo apt-get build-dep linux
sudo apt-get install git-core libncurses5 libncurses5-dev libelf-dev asciidoc binutils-dev
sudo apt-get install qt3-dev-tools libqt3-mt-dev

PickaXenomaiVersion
Xenomai2.6.3isthelateststablereleaseasofthiswriting.Xenomaisupportsthefollowingkernelsonx86
architecturesandhasbeentestedbyuswiththefollowingUbuntudistributions.Notethatsomecombinations
ofXenomaipatchesandkernelshavehadobservedissues.

Xenomai
Version

Mainline
Kernel

Ubuntu12.04
Issues
LTS

2.6.1

3.2.21

NosupportforPEAKPCIeCard.

2.6.2

3.5.7

Debianpackagesnotbuilding.

2.6.2.1

3.5.7

None

2.6.3

3.5.7

None

2.6.3

3.8.13

Observedintermittentdeadlocksandnetworkfloodson

IntelE5platform.

FormoreinformationonthekernelsusedbyvariousUbuntudistributions,seetheUbuntukernelversion
map.

SetupConvenienceVariablesandWorkspace
Firstnavigatetoanemptydirectorytoactastheworkspace.Thensetupthefollowingenvironmentvariables
basedonwhichversionsofXenomaiandLinuxyouplanonusing:
export linux_version=3.5.7
export linux_tree=`pwd`/linux-$linux_version
export xenomai_version=2.6.3
export xenomai_root=`pwd`/xenomai-$xenomai_version
export build_root=`pwd`/build
mkdir $build_root

DownloadandUnpackXenomai
wget http://download.gna.org/xenomai/stable/xenomai-$xenomai_version.tar.bz2
tar xf xenomai-$xenomai_version.tar.bz2

DownloadandUnpacktheLinuxKernelSource
Formoredetailsonbuildingkernelsindebian,seetheUbuntukernelcompilingdocumentation.
First,downloadthelinuxkernelsources,anduntarthem:
wget http://www.kernel.org/pub/linux/kernel/v3.0/linux-$linux_version.tar.bz2
tar xf linux-$linux_version.tar.bz2

Second,copythekernelconfigthatyourmachineisalreadyusingasthebasisfortherealtimekernel:

cp -vi /boot/config-`uname -r` $linux_tree/.config

PatchtheKernel
Thiswillmodifythevanillakernelyourceyoujustdownloaded.
$xenomai_root/scripts/prepare-kernel.sh --arch=x86\
--adeos=`find $xenomai_root | grep $linux_version-x86`\
--linux=$linux_tree

ConfiguretheKernel
ThisisthemostimportantstepincreatingaXenomaikernelandinvolveplatformspecificoptions.Beloware
severalwhichyouneedtosetregardlessofyourplatformorapplication.
cd $linux_tree
make menuconfig

RequiredOptions
Thefollowingrequiredoptionsarelistedbelowastheyappearinthekernelconfiguration:
Real-time sub-system
ENABLE Xenomai
ENABLE Nucleus
Power management and ACPI options
ACPI (Advanced Configuration and Power Interface) Support
DISABLE Processor
CPU Frequency scaling
DISABLE CPU Frequency scaling
Processor Type and Features
SET Processor family

NOTE:Ifyourkerneldoesnotboot,andgetsstuckat Xenomai: debug mode enabled try

beingmoreagressivewithdisablingkerneloptionssuggestedontheXenomaiwiki.

RTSocketCANOptions
IfyouplanonusingRTSocketCANorotherhardwareinterfaces,youneedtoenablethesemanuallyunder
Real-time sub-system .Forexample,ifyouplanonusinga2portPEAKPCICANbuscardforrobotics
applications,youshouldenablethefollowing:
Real-time sub-system
Nucleus
Drivers
CAN drivers

ENABLE RT-Socet-CAN, CAN raw socket interface

SET Maximum number of devices =4
SET Size of receive ring buffers (must be 2^N) =1024
SET Maximum number of receive buffers per device =32
ENABLE Philips SJA1000 CAN controller
ENABLE PEAK PCI Card

OptionsforManyThreadedSystemslikeOrocos
IfyouplanonrunningOrocoswithmanythreads(likewhenusingROSintegration),youshouldincreasethe
numberofXenomairegistryslots.
Real-time sub-system
Nucleus

SET Number of registry slots =4096

BuildtheKernel
Nowyoucanbuildthekernelintoadebianpackageandinstallit:

export CONCURRENCY_LEVEL=7
fakeroot make-kpkg --bzimage --initrd --append-to-version=-xenomai-$xenomai_version kernel-image kernel-header
cd ..
sudo dpkg -i linux-image-*.deb
sudo dpkg -i linux-headers-*.deb

ConfigureXenomaiUserLibraries
Inordertowritecodethatusesxenomai,youalsoneedtobuildandinstallthexenomaiuserspacelibs.
cd $build_root
$xenomai_root/configure\
--enable-shared\
--enable-smp\
--enable-posix-auto-mlockall\
--enable-dlopen-skins\
--enable-x86-sep
make
sudo make install

AddxenomaiGroupForNonrootUsage
Normallyonly root canrunXenomaiprocesses,unlessyouelevateaspecificgroupsprivileges.
Firstaddthexenomaigroup:
sudo addgroup xenomai

Then,addtheuserswhowillbeallowedtouserealtimetaskstothegroup.Forthecurrentuseryoucan
simplyexecute:
sudo adduser `whoami` xenomai

Then,addthexenomaiGIDtothexenomaiconfiguration.First,getthegroupid:
cat /etc/group | sed -nr "s/xenomai:.:([0-9]+):.*/\1/p"

Then,modifythegrubdefaults(locatedat /etc/default/grub )sothat GRUB_CMD_LINE_LINUX_DEFAULT

definesthe xeno_nucleus.xenomai_gid variable.Forexample,ifthexenomaiGIDfromaboveis 1001 ,
thislineshouldread:
GRUB_CMDLINE_LINUX_DEFAULT="xeno_nucleus.xenomai_gid=1001"

Thenupdategrub:
sudo update-grub

BootandTesttheXenomaiKernel
Nowyoucanreboot.Ifyoucantbootupforsomereason,reviewthatyoufollowedallofthestepswithno
errorsandlookatthetroubleshootingnotesatthebottomofthistutorial.

EstimateClockLatency
Forthebesttimingperformance,onceyouvegotyoursystemrunning,youshouldestimateyourclock
latencywiththexenomai latency program.Youshouldrunthisprogramunderheavyload,andthenstore
theresultingvaluein /cat/proc/latency .FormoredetailsonthisseethisXenomailistthread.

TroubleshootingandOtherConfigurationOptions
IOAPIC
Dependingonyourhardware,youmightneedtoreconfiguregrubaftertryingtoboot.Ifyougettheerror:
MP-BIOS bug: 8254 timer not connected to IO-APIC

Thenyouneedtoaddthenoapicoptiontoyourgrubconfigdefaults(locatedat /etc/default/grub ).To

dothisinGrub2,add noapic to GRUB_CMD_LINE_LINUX_DEFAULT sothatitlookslikethis(withthe
appropriatexenomaiGID):
GRUB_CMDLINE_LINUX_DEFAULT="xeno_nucleus.xenomai_gid=1001 noapic"

Thenupdategrub:
sudo update-grub

Nouveau
Ifyoursystemgetsthroughthebootsequence(shownaslongasyoudonthavequietenabledinthegrub
config)andthenthescreengoesblack,itmightbeaproblemwiththeNouveaugraphicsdriver.Inthiscase,
modifythegrubconfigdefaults(locatedat /etc/default/grub )sothat GRUB_CMD_LINE_LINUX_DEFAULT
readslikeso:
GRUB_CMDLINE_LINUX_DEFAULT="splash noapic rdblacklist=nouveau nouveau.modeset=0"

Thenupdategrub:
sudo update-grub

PeakCANBusDriver(peak_pci)
IfyoureusingthePEAKCANBusdriver,youmayneedtoblacklistthenonrealtimepeak_pcikernelmodule
byaddingthefollowingto /etc/modprobe.d/blacklist-pcan.conf :
blacklist peak_pci

Withoutthis,thenonrtdrivercantakeprecedenceandpreventyoufromaccessingthedevice.

IRQProblems
IRQs(interruptrequests)cansometimescollidebetweendifferenthardware.Ifyourehavingtroubleusinga
certainkindofPCIhardware,thismightbethesourceoftheproblem.
First,todetermineifyourehavinganIRQproblem,grepyourkernellogformentionsofIRQcollisions,like
so:
grep -i irq /var/log/kern.log
grep -i irq /var/log/kern.log.1

IfyouseesomethingdescribinganIRQalreadybeinginusethenyourehavinganIRQcollisionproblem.
Thereatleasttwowaystofixthis.Thefirst,istosimplymoveyourPCIcardsaround.Thisisviableifthe
IRQsarefromtwodifferentPCIdevices.IfthetwodevicestryingtousethesameIRQareonthesamePCI,
device,however,thiswontmakeadifference.ThisiscurrentlythecasewithPEAKPCIedualportCANBus
cards.
Inthiscase,youcanenableIRQsharinginyourkernelconfig,andrebuildyourkernel.Thisoptioncanbe
foundherewhilerunning make menuconfig :
Real-time sub-system
Nucleus

ENABLE Shared interrupts

FormorehelpdebuggingIRQproblems,seeUbunutusIRQdebugginghelp.

NvidiaCardsandNvidiaDrivers
YoucantusecurrentNvidiadriverswithaXenomaikernel.
Exceptwhereotherwisenoted,contentonthissiteislicensedundera
CreativeCommonsAttributionShareAlike3.0License.
PrivacyPolicy