Writting you first linux kernel module - uni-hamburg.de · • Error number defini$ons at ... • #define ENOEXEC 8 /* Exec format error */ • #define ...

Wri$ngyourfirstLinuxkernelmodule

Prak$kumKernelProgrammingUniversityofHamburgScien$ficCompu$ng

Wintersemester2015/2016

Konstan$nosChasapisKonstan$nos.chasapis@informa$k.uni-hamburg.de

Outline

•  Beforeyoustart•  Helloworldmodule•  Build,loadandunload•  UserVSKernelspaceprogramming

18/11/15 Kernel Module Demo 1

Beforeyoustart

•  Defineyourmodule’sgoal•  Defineyourmodulebehaviour•  Knowyourhardwarespecifica$ons

–  Ifyouarebuildingadevicedriveryoushouldhavethemanual

•  Documenta$on–  /usr/src/linux/Documenta$on–  make{htmldocs|psdocs|pdfdocks|

rUdocks}–  /usr/src/linux/Documenta$on/DocBook


Roleofthedevicedriver•  SoXwarelayerbetweenapplica$onanddevice

“blackboxes”–  Offerabstrac$on

•  Makehardwareavailabletousers–  Hidecomplexity

•  Userdoesnotneedtoknowtheirimplementa$on•  Providemechanismnotpolicy

–  Mechanism•  Providingtheflexibilityandtheabilitythedevice

supports–  Policy

•  Controllinghowthesecapabili$esarebeingused


Roleofthedevicedriver

•  Policy-freecharacteris$cs–  Synchronousandasynchronousopera$ons–  Exploitthefullcapabili$esofthehardware–  OXenaclientlibraryisprovidedaswell

•  Providescapabili$esthatdonotneedtobeimplementedinsidethemodule


Outline



Helloworldmodule/*theshutdownfunc/on*/

sta$cvoid__exithello_exit(void){printk("Goodbye,!\n");}

/*declareswhichfunc/onwillbe

invokedwhenthemoduleisremoved*/module_exit(hello_exit);

/*headerfiles*/#include<linux/module.h>#include<linux/init.h>/*theini/aliza/onfunc/on*/

sta$cint__inithello_init(void){printk("Helloworld!\n");return0;/*success*/}/*declareswhichfunc/onwillbeinvokedwhenthemoduleisloaded*/module_init(hello_init);


Ini$aliza$onfunc$on•  Eachmodulemustuseone•  Declaredassta$c•  __init<name>

–  Useonlyatini$aliza$on•  __initdata

–  Markini$aliza$ondata•  Doesnotacceptparameters•  Returnserrorcode•  Kerneldropsinitfunc$onanddata

–  Makesthememoryavailabletothesystem

sta$cint__inithello_init(void){printk("Helloworld!\n");return0;/*success*/}module_init(hello_init);


Shutdownfunc$on•  Onlyifyouneedtounloadthemodule

•  Declaredassta$c•  __exit<name>

–  onlyatshutdown•  module_exit(<name>)

•  Ifnotdefined–  Modulescannotbeunloaded

•  Thebuildinmodulesdonotrequireshutdown

sta$cvoid__exithello_exit(void){printk("Goodbye,!\n");}

module_exit(hello_exit);


printk

•  SimilartoprinUbut:–  Printstothekernellogfile–  Doesnotsupportalltheformaongparameters

•  Veryexpensiveopera$on–  Lotsofprintk’scansignificantlyslowdownthe

system•  Acceptsloglevels

–  Ahinttothekerneltodecideifitshouldprintthestringtothelogfile

–  DefaultKERN_WARNING18/11/15 Kernel Module Demo 9

printk-loglevels•  KERN_EMER

–  Anemergencycondi$on

•  KERN_ALERT,

–  requiresimmediatearen$on

•  KERN_CRIT

•  KERN_ERR

•  KERN_WARNING

•  KERN_NOTICE

•  KERN_INFO

•  KERN_DEBUG18/11/15 Kernel Module Demo 10

Moduleparameters•  Passparameterstothemodulethrough

–  insmod–  modprobe

•  modprobereadsparametersthought–  /etc/modprobe

•  Readparametervaluewhilemoduleisloaded–  catsys/module/<mod_na>/parameters/

<param_na>


Moduleparameters

•  Parameterdeclara$on–  module_param(name,type,permission)

•  Permissionsmodesareasfileaccessmodes•  Parameterstypes:

–  bool,inbool(invertedbool)–  charp,string–  int,long,short–  uint,ulong,ushort

•  Alsoacceptsarraysparameters–  module_param_array(name,type,nump,

perm)


Errorhandling

•  Failuremayoccurduringini$aliza$onphase–  memoryalloca$on–  deviceisbusy

•  con$nueordrop?–  Ifwedrop

•  undoanyregistra$onac$vi$esperformedbefore•  incasewefailtounregisterthekernelgoesinto

unstablemode•  Recoveryisusuallyhandlewiththegoto

statement


Errorhandling•  Errornumberdefini$onsat<linux/errno.h>

–  Returnnega$vevalues-errorcode;•  #defineEPERM 1 /*Opera$onnotpermired*/•  #defineENOENT2 /*Nosuchfileordirectory*/•  #defineEIO 5 /*I/Oerror*/•  #defineENOEXEC 8 /*Execformaterror*/•  #defineEAGAIN 11 /*Tryagain*/•  #defineENOMEM 12 /*Outofmemory*/•  #defineEACCES13/*Permissiondenied*/•  #defineENOSYS 38 /*Func$onnotimplemented*/•  #defineENOTEMPTY39/*Directorynotempty*/


Outline



Compile

•  kbuild–  thesystemthatisusedtocompilekernel

modules–  /Documenta$on/kbuild/

•  Youmusthaveapre-buildkernelwithconfigura$onandheaderfiles

•  Manydistribu$onshavepackagesfortherequiredfilesandtools–  kernel-develpackageforCentOS


Compilecommand

•  make-C$KDIRM=$PWD[target]–  $KDIR

•  thedirectorywherethekernelsourceislocated.•  makewillchangethedirectoryforthecompileand

willreturnaXerthecompile

–  M=$PWD•  Informskbuildthatanexternalmoduleisbeing

build.•  ThevalueofMistheabsolutepaththedirectory

thatcontainsthesourcecodeofthemodule


makecommandtargets•  modules

–  Thedefaulttargetthatcanbeignored•  modules_install

–  Installstheexternalmodules–  Thedefaultloca$onis/lib/modules/<kernel_release>/

extra/•  clean

–  removeallgeneratedfilesinthemoduledirectoryonly•  help

–  listtheavailabletargetfortheexternalmodules


kbuildfile•  Containsthenameofthemodule(s)beingbuilt,alongwiththe

requisitesourcefiles–  obj-m:=<m_name>.o

•  kbuildwillbuild<m_name>.ofrom<m_name>.c–  Thenitwilllinkitandwillresultinthekernelmodule

<m_name>.ko–  Anaddi$onallineisneededtoaddmorefiles

•  <module_name>-y:=<src1>.o<src2>.o....–  Includefilesanddirectories

•  standardfilesusing#include<file>•  ccflags-y:=-Iinclude_path


Module.symversfile

•  ModuleversioningisenabledbytheCONFIG_MODVERSIONStag

•  ItisusedasasimpleApplica$onBinaryInterface(ABI)consistencycheck

•  Itcontainsalistofallexportedsymbolsfromakernelbuild

•  /proc/kallsyms


insmod(insertmodule)•  loadthemoduleintothekernel

•  triggerstheexecu$onofthemodule_initfunc$on

•  Similartotheldinuserspace•  Loadthemodulecodeanddataintothekernel

memory•  Linksanyunresolvedsymbolinthemoduletothe

symboltableofthekernel•  Acceptscommandlinearguments

•  Parameterstothekernelmodule•  Addanentryat/proc/modules•  Formoredetailscheckkernel/module.c

Kernel

Module

.init_module


rmmod(removemodule)•  Removes/unloadsthemodulefromthekernel•  Mustfreememoryandreleaserecourse•  Incaseoffailurethekernels$llbelievesthat

themoduleisinuse•  Incasethatrmmodfailstherebootprocessis

requiredtocleanthesystemsstate

Kernel

Module

.exit_module


Moretools•  lsmod(listmodules)

–  Listofthecurrentloadedmodules•  modprobe(similartoinsmod)

–  Searchforsymbolsthatarenotcurrentlydefinedinthekernel–  Incasethattherearethensearchforinkernelmodulestofind

modulesthatcontainthesesymbols–  Itloadsthesemodulesintothekernel

•  depmod–  Createsadependencyfile,usedbymodprobe

•  modinfo–  Showsinforma$onaboutaLinuxKernelmodule


Versiondependency•  Moduleshavetoberecompiledforeachversion

–  datastructuresandfunc$onprototypescanchangesfromversiontoversion

–  duringcompila$onthemoduleislinkedagainstafilenamedvermagic.o

–  Thisfilecontainstargetkernelversion,compilerversionetc.

•  Incasethatthemoduleiscompileagainstdifferentkernelversion–  insmod:Invalidmoduleformat


Versiondependency(cont.)•  Macrostodefinekernelversionduringcompila$onfoundin/

linux/version.h–  UTS_RELEASE,theversionofthiskerneltree–  LINUX_VERSION_CODE,binaryrepresenta$onofthe

kernelversion–  KERNEL_VERSION(major,minor,release),buildaninter

versioncode


KernelSymbolTable•  Kernelhasalreadyexportedsymbols•  Loadedmodulescanexportnewsymbols

–  offertheirfunc$onalitytoothermodules•  Stackmodulesontopofothermodules

–  Reducecomplexityofthemodules–  Addflexibilitytochoosemodulesdependingonthespecific

hardware•  Macrostoexportnewsymbols

–  EXPORT_SYMBOL(name);–  EXPORT_SYMBOL_GPL(make);

•  Expandintospecificvariabledeclara$onsstoredinthemoduleexecutablefile


dkms

•  DynamicKernelModuleSupport–  Frameworkthatenablesgenera$ngLinux

kernelmoduleswhosesourcesgenerallyresideoutsidethekernelsourcetree

–  Usedtoautoma$callyrebuiltmoduleswhenanewkernelisinstalled

–  Itisincludedinmanydistribu$ons


Outline



UserVS.Kernelprogramming•  kernelmoduleprogramming

–  similartoeventdrivenprogramming•  initfunc$on

–  says:heyIamhere,Iwillserveyourrequestsfromnowandon

•  exitfunc$on–  says:Iamgoingtoleaveyou..don'tbothertryingto

findmeanymore•  Unload

–  shouldreleaseanyresourcethatthemodulehadacquired


UserVS.Kernelprogramming•  kernelmodulerunsinkernelspace

–  Coreoftheopera$ngsystem–  Privilegedopera$ngsystemfunc$ons–  Fullaccesstoallmemoryandmachinehardware–  Kerneladdressspace

•  Userprogramsruninuserspace–  Itrestrictsuserprogramssotheycan'tmessresourcesowned

byotherprogramsorbytheOSkernel–  Limitedabilitytodobadthingslikecrashingthemachine


UserVS.Kernelprogramming•  SystemcallsSwitchbetweenuserandkernel•  Memoryhandling

–  mallocisClibrarycall-NOTasystemcall•  Usebrksystemcall

–  Kernelallocatesvirtualmemoryareafortheapplica$on

–  Lacksofmemoryprotec$on•  Portability

–  Kernelmodulesworkwithspecificversionanddistribu$onofthekernelandmightbeplaUorm-specific


UserVS.Kernelprogramming•  Kerneldoesnothavestandardheaders

–  IsnotlinkedagainstthestandardClibrary–  However,manyfunc$onsareimplementedinsidetheLinux

kernel•  Cannotexecuteeasilyfloa$ngpointopera$ons

–  Floa$ngpointopera$onsarearchitecturedependent–  Usually,implementedwithtraps,(triggerintegertofloa$ng

pointmodetransi$on)–  Inthekernelspaceitrequiressavingandrestoringthefloa$ng

pointopera$onsmanually•  Smallfixedsizestack

–  Configurableatcompile$me(4KBor8KB)18/11/15 Kernel Module Demo 32

MusicalbumasLKM•  BandreleasesalbumasLinuxkernelmodule

–  hrps://github.com/usrbinnc/netcat-cpi-kernel-module


Writting you first linux kernel module - uni-hamburg.de · • Error number defini$ons at ... • #define ENOEXEC 8 /* Exec format error */ • #define ...

Documents