LinuxKernelDevelopment: GettingStarted

RandyDunlap
LinuxKernelDeveloper, Mentor,andJanitor IEEENorthcon May19,2005
Copyright2005RandyDunlap,Allrightsreserved.

Agenda

Timetable:10:00am3:00pmwith15minutebreakeveryhour, pluslunch Lotsoftimeforquestionsanddiscussion Abstract: Linuxdevelopmentisfastpacedand[astheysayinOregon]things aredifferenthere.ThistutorialintroducessomeoftheLinuxculture andhowtogetthingsdonewell.

Copyright2005RandyDunlap,Allrightsreserved.

Opensourcedevelopmentstyle,values,culture Linuxrapiddevelopmentcycle Linuxmaintainersandhierarchy Communicationsmethods Advantagesofhavingadriverinthemainlinekerneltree Codingstyle HowtosubmitLinuxkernelpatches Somebestknownpractices Legal/Licenses Testing WorkingintheLinuxkerneltree
3 Copyright2005RandyDunlap,Allrightsreserved.

Topics

MajorGoals

Encouragenewdevicedriverdevelopmentandsupport Drivercodemergedandmaintainedinmainline(GPL)

Copyright2005RandyDunlap,Allrightsreserved.

DevelopmentStyle,Values,andCulture

Learningcurve,thingsaredifferent Meritocracygoodideas&goodcodearerewarded ChancetoworkonarealOSanypartsofitthatinterestyou Massiveamountsofopencommunicationviaemail,IRC,etc.

Copyright2005RandyDunlap,Allrightsreserved.

LinuxCulture

Workinopen,notbehindcloseddoors(insmokefilledrooms)# Communityallegianceisveryhigh DowhatisrightforLinux Meritocracy:goodideasandgoodcodearerewarded Oftendrivenbyidealsandpragmatism,bottomupdevelopment Notdrivenbymarketingrequirements Don'tjusttake,givebacktoo:#

Modificationsare&remainGPL(ifdistributed) Paymentinkind,selfinterest Improvesoftwarequality,featuresused/understoodmore

6 Copyright2005RandyDunlap,Allrightsreserved.

Committedtofollowingandusingstandards(e.g.,POSIX,IETF) Committedtocompatibilitywithothersystemsoftware Informaldesign/development:Notmuchexternalhighlevelproject planningordesigndocs(maybesomeinternallyatcompanies);can appeartobechaotic Newideasbestpresentedascode,notspecificationsor requirements RERO:ReleaseEarly,ReleaseOftenforcomments,help,testing, communityacceptance# Possibledownsides:flames,embarrassment
7 Copyright2005RandyDunlap,Allrightsreserved.

LinuxCulture(2)

LinuxCulture(3)

Developmentcommunityishighlytechnical Motivatedandcommitted,butsincemanyarevolunteers,treatthem withrespectandask/influencethem,don'ttell Continuouscodereview(includingsecurity) Continuousimprovement Havefun!!:) Followtheculture

Copyright2005RandyDunlap,Allrightsreserved.

LinuxDevelopmentValues

Scratchyourownitch Weekenders>bigbusiness Code,nottalk Pragmatism,nottheory Thickskin Codeproducermakes[most] decisions Pride,principles,ethics, honesty Performance

Hardware&softwarevendor neutral Technicalmerit,notpolitics, who,ormoney Maintainability&aesthetics: cleanimplementation,not uglyhacks(codingsytle) Peerreviewofpatches (technical&style) Contributionsearnrespect
Copyright2005RandyDunlap,Allrightsreserved.

SomeThingstoAvoid

Patents,binarymodules,NDA Proprietarybenchmarks Hugepatchfiles AddingmoreIOCTLs Marketing Designdocuments Mentionofaccomplishments outsideoftheopensourceworld Nopatchrationale

HowdoIinterceptasystemcall (orreplaceasyscalltable entry)? Makingdemandsinsteadof requests This{driver/feature}mustbe merged,it'simportanttoour company. Dateorreleaseversion requirements
Copyright2005RandyDunlap,Allrightsreserved.

10

SomeGoodTermstoUse

Simpler DeletesNlinesofcode Faster(withdata) Smaller(withdata) Here'sthecode.... Seriesofsmallpatches....

Tested...(howmanyconfigs) Buildson8architectures

11

Copyright2005RandyDunlap,Allrightsreserved.

WhenNewInfrastructureIsNeeded

Ifadriverneedssomenewgeneralpurposesubsystem infrastructure,don'ttrytomergeitintothedriverthatwillbe rejected Workwithothers(onml)todefineandimplementnewinfrastructure

MultipathI/O(MPIO) SCSItransportservices WirelessLANstack RAID?? FCStateoftheUnion:http://lwn.net/Articles/132579/

12 Copyright2005RandyDunlap,Allrightsreserved.

Driverdeveloperscanhaveanimpactonkernelinfrastructure

DriversforNewHardware

IfyourcompanywantstodevelopaGPLdriverandmergeitinto Linuxmainline,that'sgreatnews.Workwiththedevelopment community(onpublicmailinglists)toaccomplishthatgoal. Shortofthat,ifyourcompanycanmakehardwareinterfacespecs publicandhardwareavailable,there'sagoodprobabilitythat someoneinthedevelopmentcommunitywilldevelopaGPLdriver forit. Shortofthat,makethehardwareinterfacespecsavailableprivately tosomeone,butallowthemtodevelopandpublishaGPLdriver.

13 Copyright2005RandyDunlap,Allrightsreserved.

NewDriverDevelopment

Requires1+dedicatedfulltimesoftwareengineertokeepupwith mailinglistsandkernelchanges,staycurrent,becomeapartofthe developmentcommunity Thisisacontinuous,ongoingcommitment,notaninfrequentcameo appearance. Submitdriversformainlineinclusionandacceptance,nottodistros. Majordistrosnowrequireprogresstowardmainlineacceptance. REROfortestinginthewild(community),inyourlab,andatthe distros

14 Copyright2005RandyDunlap,Allrightsreserved.

DevelopmentCycle

Movedfromsplitstable(2.even)anddevelopment(2.odd)trees causeddelayandbackportmania Nowacceptingdevelopmentpatchesintothemmpatchsetand movingthemtothemainlinekerneltreeafterashakeoutperiod (e.g.,2.6.11mm3) 2.6.xkernelversioncycle:makepatchesagainstLinus'stree (unlesstheyonlyapplytosomeothertreeorpatchset) Timebetween2.6.xreleases,intermediate2.6.xrcN Nightlysnapshots;automatedbuildsofreleases;commitsml 2.6.x.ystablekernelpatches
15 Copyright2005RandyDunlap,Allrightsreserved.

Linux2.6KernelTree&Branches
mainline 2.6.112.6.12rc12.6.12rc22.6.12rc32.6.12rc4.....2.6.12 mmpatchset:review/testherebeforemergeintomainline mm1mm1mm1mm1mm1 mm2mm2mm2 2.6.12rc3mm3 stablepatchseries 2.6.11.12.6.11.22.6.11.32.6.11.4.....2.6.11.9
16 Copyright2005RandyDunlap,Allrightsreserved.

MergestoMainline(withexceptions)
Mainlinekernel.org(Torvalds) mmpatchset(Morton) Subsystemmaintainers USB PPC XFS

SCSI

Block

Contributors(100s)

17

Copyright2005RandyDunlap,Allrightsreserved.

DevelopmentCycles

Rapiddevelopmentcycle,notimelines/schedules Onlyonlinedocumentationhasachanceofbeinguptodate Accommodatelargechangesandhighrateofchangewithout regressions Opendiscussion(mailinglists,archives,notprivate)# RERO,facilitatestestingonalargevarietyofplatforms# Maintainersavailableandaccessible,don'tdisappearforlong periodsoftime Testsuites Bugtracking
18 Copyright2005RandyDunlap,Allrightsreserved.

RatesofKernelChange

firstsixmonthsof2.4devel:220,000lines,+600,000lines firstsixmonthsof2.6devel:600,000lines,+900,000lines

1.5Mlineschangedina6.2Mlinetree 64MBdiffinsixmonthsandthat'sthestablekernel

Current2.6.11>2.6.12rc4(10weeks):729Klines,22MBdiff Current2.6.12rc4mm1patchset:414Klines,13MBdiff

19

Copyright2005RandyDunlap,Allrightsreserved.

Opensourcedevelopmentstyle,values,culture Linuxrapiddevelopmentcycle Linuxmaintainersandhierarchy Communicationsmethods Advantagesofhavingadriverinthemainlinekerneltree Codingstyle HowtosubmitLinuxkernelpatches Somebestknownpractices Legal/Licenses Testing WorkingintheLinuxkerneltree
20 Copyright2005RandyDunlap,Allrightsreserved.

Topics

MaintainersandHierarchy

Loosehierarchywithbenevolentdictator Kernelseriesmaintainers(2.6)LinusandAndrewMorton Patch(stable)maintainers(2.6.x.y)GregKroahHartmanand ChrisWright Toplevelmaintainersaregatekeepers,integrators,tiebreakersor overrulerswhenneeded Delegatetolieutenantsandindividualmaintainers;sharetheload Strongtrustsystem>beginwithsmallpatchesforcredibility Maintainersdon'thaveabsoluteauthority

21 Copyright2005RandyDunlap,Allrightsreserved.

Maintainers&Hierarchy(2)

KernelJanitors,securitykernels,someembeddedsupport Archandsubsystemmaintainers:coordinatesubsystemsand maintainconsistency Drivermaintainers:coverallcurrentmainlinekernelsandupdateto newkernelAPIs,evendevelopmentAPIs Seefiles:linux/MAINTAINERSandlinux/CREDITS

22

Copyright2005RandyDunlap,Allrightsreserved.

Communications

Communicatingishard,let'sgoshopping Writingideas/thoughtsdownisgood(buttoowordymaybeignored) Participateconstructively Mailinglists&archives(newsgroups) Workinginopen/public(technicalreaders/writers)vs. embarrassment Discussionanddecisionsonlists,nomeetingsrequired Workthroughconcensus(withexceptions) Projectwebpages,IRCchannels Developerconferences
23 Copyright2005RandyDunlap,Allrightsreserved.

MailingListEtiquette

UseReplytoAll,threaded(MessageID,References)

>>TryAorB. >IpreferA,soundOK? yes

Bepromptwithreplies(beingresponsiveisimportant) Noencodedorzippedattachments(inlinepreferred,text/plain attachmentsOK);othersareoftenignored NoHTMLorcommercialemail,noautoreplies(OOO/vacation) ALLCAPS==SHOUTING Use<80columnwidthlines(7072isgood)

24 Copyright2005RandyDunlap,Allrightsreserved.

MailingListEtiquette(2)

Keepittechnicalandprofessional.Ifattacked(flamed),stickwith technicalpoints,don'tgetinvolvedwithattacks,&moveon. Trimreplies(body)torelevantbits(don'tmodifyrecipientlist). Don'tcrossposttoclosedmailinglists. NonEnglishspeakers http://www.arm.linux.org.uk/armlinux/mletiquette.php RFC1855:NetiquetteGuidelines:http://www.ietf.org/rfc/rfc1855.txt

25

Copyright2005RandyDunlap,Allrightsreserved.

MailingListEtiquette:Notopposting

A:http://en.wikipedia.org/wiki/Top_post Q:WeredoIfindinfoaboutthisthingcalledtopposting? A:Becauseitmessesuptheorderinwhichpeoplenormallyread text. Q:Whyistoppostingsuchabadthing? A:Topposting. Q:Whatisthemostannoyingthinginemail? A:No. Q:ShouldIincludequotationsaftermyreply?

26 Copyright2005RandyDunlap,Allrightsreserved.

MailingLists

Mostlistshavespamfilters[togetpast];youprobablyneedtouse themalso LKMLa.k.alinuxkernel(@vger.kernel.org) LKMLFAQathttp://www.tux.org/lkml/ Index:http://vger.kernel.org/vgerlists.htmlandtheirarchives Kernelpatchcommitsml:bkcommitshead@vger.kernel.org

27

Copyright2005RandyDunlap,Allrightsreserved.

MoreKernelProjectMailingLists

Networkingdevelopment:netdev@oss.sgi.com Index:http://oss.sgi.com/ecartis/ Subsystems:arches,filesystems,MM/VM(http://www.linuxmm.org ),security,drivers(ACPI[SF.net],I2C,IDE,video,PCI,PCMCIA, IEEE1394[SF.net],USB[SF.net],SCSI,Infiniband,Bluetooth) MoremailinglistsinMAINTAINERSfileandat http://kernelnewbies.org

28

Copyright2005RandyDunlap,Allrightsreserved.

MailingListsforLinuxStarters

http://kernelnewbies.orgkernelnewbies@nl.linux.org http://janitor.kernelnewbies.orgkerneljanitors@lists.osdl.org os_drivers@lists.osdl.org kernelmentors@selenic.com Trivialpatchmonkey: http://www.kernel.org/pub/linux/kernel/people/rusty/trivial/ http://vger.kernel.org/majordomoinfo.htmlhaslistinfoandtaboos Kernelannouncements:linuxkernelannounce@vger.kernel.org

29 Copyright2005RandyDunlap,Allrightsreserved.

MailingListArchives

Archivesforalmostall

http://gmane.orghasinterface http://marc.theaimsgroup.com/hasmany,withSearch http://lkml.orgkernellistonly Googlegroups

http://www.kerneltraffic.org/summaries http://lwn.net/summaries

30

Copyright2005RandyDunlap,Allrightsreserved.

ProjectWebPages

SourceForge.net(http://sf.net):webpages,mailinglists,CVS,bug tracking,etc. OSDL:http://lists.osdl.orghttp://developer.osdl.org http://bugme.osdl.org Hardwarevendors:IBM,HP,Dell Distrovendors(RedHat,SUSE,Debian)

31

Copyright2005RandyDunlap,Allrightsreserved.

DevelopmentConferences

LinuxSymposium(Ottawa,July) LinuxConferenceAU(LCA,usuallyMarchApril) LinuxTag(Germany,June) LinuxKongress(Germany,September) Kernel(July),GCC(June),Desktop(July)summits Focusedminisummits(networking,powermanagement)

32

Copyright2005RandyDunlap,Allrightsreserved.

RelatedDocumentation

lwn.netarticles:http://lwn.net/Articles/driverporting/ LDD3book:http://lwn.net/Kernel/LDD3/ DriverDOsandDON'Ts:attheKJwebsite Arjan:HowNottoWriteaDriver(OLS,atKJwebsite) Greg(PCI,USBmaintainer):CodingStyle,WritingPortableCode, etal(http://www.kroah.com/linux/) Andrew(topkernelmaintainer):TPP:ThePerfectPatch: http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt# Jeff(netdriversmaintainer):http://linux.yyz.us/patchformat.html#

33 Copyright2005RandyDunlap,Allrightsreserved.

WhyMergeIntotheMainlineKernelTree

BackgroundonkernelAPI/ABI

KernelAPIisnotstable;nokernelbinaryAPI(ABI) Astatic(stable)APIlimitsinnovationandaddscruft

UserspaceAPIisverystableandwillremainso Interfacesandstructuresdependontoolchain&kernelconfig optionsanddistrochanges,sosinglekernelABIisn'tfeasible Oldinterfacesareremoved(sometimesafteradeprecatedgrace period),preventingtheircontinuedusewhichcouldcausesystem outagesandkernelbloat Seefile:linux/Documentation/featureremovalschedule.txt

34

Copyright2005RandyDunlap,Allrightsreserved.

AdvantagesofMergingintoMainline(1/3)

Keepsthedriverupdatedandworking,evenifitsmaintainer disappearsortheOEMstopssupporting/updatingit KernelAPIchangesaremergedforyou:performance improvements,bugfixes,securityfixes,parameterorstructure changes Kernelchangesincreasequalityofdriverwhilemaintenancecoststo themaintainerdecrease(areamortized) Otherpeoplewilladdfeaturestoyourdriver Otherswillfind&fixbugsinyourdriver Otherswillfind&fixperformance/tuningopportunities
35 Copyright2005RandyDunlap,Allrightsreserved.

MoreMergeAdvantages(2/3)

DriverisautomaticallyshippedinallLinuxdistroswithout havingtoaskdistrostomerge&shipitsoallstayinsync Driverisavailableforuseon20+CPUarchitecutures,notjusta handful[stillrequiresproperendianhandling;checkwith'sparse'] Drivergetbroadertestingandreview Drivermaintainerisrelievedfrommaintainingexternal patchsetsdifficultevenifopensourcecode Offersauniformfeaturesettoallusers Becomesthedefactodriver(withyouasMaintainer),keepingwork focusedononedriver
36 Copyright2005RandyDunlap,Allrightsreserved.

MergeAdvantages(3/3)

Severallargedistrovendorsrequireupstreamprogress(e.g., publicreviewsonmailinglists)

Mergingviadistroscanleadtoincompatibilitieswithmainline

Discouragesminiforking&fragmentation:badforusers(different features&bugs)&fortheforkmaintainer

Userswithnonmainlinedriverscanenduphelplessor unsupportedorlockedintoonedistro

37

Copyright2005RandyDunlap,Allrightsreserved.

DisadvantagesofMerging

Mustadaptcodetokernelcodingstyle Mustgothrupeerreviewandrespondtofeedback,makechanges Removecompatibilitylayers,oldkernelversionsupport,otherOS support Mayneedtomakeitarchportable(endianness,wordsizes) Mayneeddesignchangesorfeaturesadded Probablywilltakeseveralweeksofpostingpatches,feedback,more changes,butthat'saonetimething Costofnotlistening:investmanyearsindevelopmentthen toldthearchitectureiswrong,redoit
38 Copyright2005RandyDunlap,Allrightsreserved.

MergetoMainline(summary)

Bigefforttousemainlinepublickernelformerging Keepsalldistrovendorsthesame Providesformoreandbettertesting,review,andbugtracking

39

Copyright2005RandyDunlap,Allrightsreserved.

Opensourcedevelopmentstyle,values,culture Linuxrapiddevelopmentcycle Linuxmaintainersandhierarchy Communicationsmethods Advantagesofhavingadriverinthemainlinekerneltree Codingstyle HowtosubmitLinuxkernelpatches Somebestknownpractices Legal/Licenses Testing WorkingintheLinuxkerneltree
40 Copyright2005RandyDunlap,Allrightsreserved.

Topics

CodingStyle

Cleancode,notforotherOSesorforotherLinuxversions Usecomments,butnotforobviouscode;ondatastructures Drivers,filesystems,etc.,arenotarchspecific(mustbearch portable) Followstyleinsurroundingcode Veryminimaluseoftypedefs(onlyforbasictypes) Minimizeuseof#ifdefinCsourcefiles,usestubsinheaderfiles instead(asmuchaspossible/feasible) Documentation/:CodingStyle,SubmittingPatches/Drivers,&web pages
41 Copyright2005RandyDunlap,Allrightsreserved.

CodingStyle(2)

Don'tabusethekernelAPI Simplerisbetter(eschewobfuscation) Minimizemacrousage(preferinlinefunctionsfortypechecking) Stubs:include/linux/highmem.h,init.h,module.h,sched.h,swap.h, include/asmgeneric/dmamapping.h LinuxkerneliswritteninC,notC++ Use/*...*/forcomments(not//) Functioncommentsinkerneldocstyle Use(butdon'tabuse)'goto',especiallyforerrorhandling(one functionexitpath)[andundoallocationsetc.inerrorhandling]
42 Copyright2005RandyDunlap,Allrightsreserved.

CodingStyle(3)

UseC99stylestructinitializers Usetabsforindentation,notspaces(Tabsizeis8) Don'tdisableorignorecompilerwarnings Use'sparse'forevenmorewarnings

$makeC=1...

Use'makecheckstack','makebuildcheck','makenamespacecheck' tocheckfordetails Don'tmakefunctionsordataglobalunlessneeded(mostly'static') Don'tusedeprecatedkernelAPIs Don'tuseanonymousunions(gcc2.9xtoolproblem)

43 Copyright2005RandyDunlap,Allrightsreserved.

CodingStyle(4)

Avoid'extern'inCfiles,useheadersinstead #includefileorder

<linux/file.h>(alphabeticallywhenpossible) <asm/file.h>(alphabeticallywhenpossible) localfile.h(alphabeticallywhenpossible)

Don't#includefilesunlesstheyareneeded/used

44

Copyright2005RandyDunlap,Allrightsreserved.

CodingStyle(5)(Policies)

Don'tinitstaticorglobaldatato0(it'sallclearedduringinit) Initializedatastaticallyinsteadofduringinitruntimeifpossible Don'tabusethekernelstack(it'ssmall) Don'tuserecursion(sometimesOKifithasalowbound) Pushdataconversions(likegraphics)touserspace Forlocking(mutexes,criticalregions),don'tuse'volatile',analyze anduselocksorsemaphores Don'tuseordependonBIOScallsordataexceptduringkernelinit, andthenaslittleaspossible

45 Copyright2005RandyDunlap,Allrightsreserved.

CodingStyle(6)(Policies)

Don'taddIOCTLs,use/sys(sysfs) Don'ttrustdatacomingfromuserspace Don'tread/writefilesfromkernelspace(exception:firmware downloads) CheckthatcodecompilesUP/SMPandMODULE/notMODULEand onmultiplearchesifapplicableandpossible

46

Copyright2005RandyDunlap,Allrightsreserved.

HowtoSubmitLinuxKernelPatches

Patchcurrentmainlinefromkernel.orgormmpatchset Sendpatchestosubsystemmaintainer,drivermaintainer,&mailing list# Eachpatch(re)submissionshouldincludefeaturejustificationand explanation,notjustthepatch# UsetheDCO(Signedoffby:your.name@example.com)# Patchesshouldbeencapsulated(selfcontained)asmuchas possible,nottouchingothercode(whenthatmakessense)#

47

Copyright2005RandyDunlap,Allrightsreserved.

SubmittingPatches(2)

ONEpatchperemail,logicalprogressionofpatches,notmega patchesandnotzipped(cannotreview/reply)# Don'tdomultiplethingsinonepatch(likefixabuganddosome cleanup) Checkyouremailclient:sendapatchtoyourselfandseethatitstill applies(doesn'tdamagewhitespace,linebreaks,contentchanged) beforegoingpublicwithit Patchmustapplywith'patchp1';i.e.,useexpecteddirectorylevels

48

Copyright2005RandyDunlap,Allrightsreserved.

register_chrdev() can return errors (negative) other then -EBUSY, so check for any negative error code. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> diffstat:= drivers/pcmcia/ds.c | 4 ++-1 files changed, 2 insertions(+), 2 deletions(-) diff -Naurp ./drivers/pcmcia/ds.c~ds_check_major ./drivers/pcmcia/ds.c --- ./drivers/pcmcia/ds.c~ds_check_major 2005-05-12 13:16:41.000000000 -0700 +++ ./drivers/pcmcia/ds.c 2005-05-12 19:45:36.000000000 -0700 @@ -1592,9 +1592,9 @@ static int __init init_pcmcia_bus(void) /* Set up character device for user mode clients */ i = register_chrdev(0, "pcmcia", &ds_fops); if (i == -EBUSY) if (i < 0) printk(KERN_NOTICE "unable to find a free device # for " "Driver Services\n"); "Driver Services (error=%d)\n", i); else major_dev = i;
49 Copyright2005RandyDunlap,Allrightsreserved.

+ +

SomeBestKnownPractices#

Trackorigin(s)ofyoursoftware(COO:CertificateofOrigin) UserDCO(Developer'sCertificateofOrigin)forkernelcontributions Managementapprovalandlegalclearancetosubmitsourcecode SomecompaniesmayrequireaWaiverofCopyright Sendpatchesdirectlytotheirintendedmaintainerformerging(they don'ttrollmailinglistslookingforpatchestomerge) Copypatchestotheappropriatemailinglist(s),notprivate(don't workinisolation) Subscribetorelevantmailinglists(oruseonerepresentativeforthis) Listentoreviewfeedbackandpromptlyrespondtoit
50 Copyright2005RandyDunlap,Allrightsreserved.

BestKnownPractices(2)#

Linusnormallydoesnotacknowledgewhenhemergesapatch Usecorrect'diff'directorylevel(linux/topleveldirectory)andoptions (up) Usesourcecodetoconveyideas Generatepatchfilesagainstthelatestdevelopmenttreebranch (rcN)ormainlinekernelifthereisnocurrentdevelopmentbranch Makefocusedpatchesoraseriesofpatches,notlargepatchesthat covermanyareasorthatjustsynchronizea(CVS)repositorywith thekernelsourcetree Usetheavailabledocs.
51 Copyright2005RandyDunlap,Allrightsreserved.

BestKnownPractices(3)#

IncludeCopyrightandlicense:MODULE_LICENSE(GPL); Useanemailclientthatsupportsinsertingpatchesinline(notas attachments) Beginwithsmallpatches:usekerneljanitorml Forlargerpatchesorcompletedriversorfeatures,usethekernel mentorsml(forbeginnerfeedback/comments/corrections) Don'tmisuse(abuse)thekernelAPI;e.g.,avoidvoid*function arguments Don'tpostprivateemailrepliestoapublicml(withoutpermission) Don'tintroducegratuitouswhitespacechangesinpatches
52 Copyright2005RandyDunlap,Allrightsreserved.

BestKnownPractices(4)#

Backupyourpatchwithperformancedata(ifapplicable) Don'taddbinaryIOCTLsunlesstherearenootheracceptable options;usesysfs(/sys)orprocfs(/proc)orprivatefsifpossible MakeLinuxdriversthatarenativeLinuxdrivers,notashimfrom anotherOS Don'tintroducekerneldriversifthesamefunctionalitycanbedone reasonablyinuserspace Trytobeprocessoranddistroagnostic(exceptforCPUspecific code) Don'tbeafraidtoacceptpatchesfromothers
53

Copyright2005RandyDunlap,Allrightsreserved.

BestKnownPractices(5)#

Keepyourpatch(es)updatedforthecurrentkernelversion Resubmitpatchesiftheyarenotreceivingcomments Releaseearly,releaseoften Open,publicdiscussiononmailinglists Onepatchperemail Largepatchesshouldbesplitintologicalpiecesandmailedasa patchseries Maketestingtoolsavailable&easytouse;yourdevice(s)willget bettertesting Givinghardwaretodeveloperscanresultindriverswrittenforyou
54

Copyright2005RandyDunlap,Allrightsreserved.

Opensourcedevelopmentstyle,values,culture Linuxrapiddevelopmentcycle Linuxmaintainersandhierarchy Communicationsmethods Advantagesofhavingadriverinthemainlinekerneltree Codingstyle HowtosubmitLinuxkernelpatches Somebestknownpractices Legal/Licenses Testing WorkingintheLinuxkerneltree
55 Copyright2005RandyDunlap,Allrightsreserved.

Topics

Legal&LicensePoints

IANAL,getlegaladvice Opensourceisabusinessdecision,freesoftwareisanethicalone All(internalorexternal)kernelmodulesmustbeopensource,GPL compatiblelicensed(dual) EXPORT_SYMBOL()andEXPORT_SYMBOL_GPL() http://www.opensource.orgOpenSourceInitiative,manyopen sourcelicenseslisted,butdesireistosignificantlyreducetonumber oflicensesthatareused Trackoriginsofsoftwareusedinternallyindevelopment UseDCOforLinuxkernelcontributions#
56 Copyright2005RandyDunlap,Allrightsreserved.

BugReportingandTracking

kernelbugsdatabase:fixbugsorhelpupdateinfo: http://bugzilla.kernel.orgor http://bugme.osdl.org Mailinglistsareheavilyusedforbugreporting Sourceforge.netprojectpages:someprojectsusethisbugtracker otherprojectspecificbugtracking

57

Copyright2005RandyDunlap,Allrightsreserved.

KernelTestProjects

LTP:http://ltp.sourceforge.net OpenPOSIXtestsuite: http://posixtest.sourceforge.net OSDLPLMforbuildingandcrossbuildingpatches: http://www.osdl.org/plmcgi/plm/ OSDLSTPframeworkandservers: http://www.osdl.org/stp/

58

Copyright2005RandyDunlap,Allrightsreserved.

VirtualizationforKernelTesting

UMLfortesting VirtualizationfortestingLinuxvirtualizationsummary: http://www.linuxsymposium.org/proceedings/reprints/ReprintWright OLS2004.pdf XEN,qemu,Bochs(x86)

59

Copyright2005RandyDunlap,Allrightsreserved.

WorkingintheLinuxKernelTree

About16,000sourcefiles corefunctionality:kernel/,mm/,init/,ipc/,lib/ drivers/,fs/,net/ arch/,security/,crypto/,....

60

Copyright2005RandyDunlap,Allrightsreserved.

KernelConfig

Generateoreditconfigwithanyof: make{menuconfig,xconfig,gconfig,config,defconfig,oldconfig} Buildkernel:makeall Installkernel:

1:sutoroot 2:makeinstall 3:makemodules_install 4:editLILOorGRUBconfig(andrunlilo) 5:reboot

61 Copyright2005RandyDunlap,Allrightsreserved.

PatchMaintenanceTools

Use'diff'tocreatepatches(evenforcompletenewfilesortoaddor removefiles) Manualdiffing:

Candiffcompleteunmodifiedtreevs.amodifiedtree Candiffoneorafewmodifiedfilesvs.theiroriginalfiles Use'gendiff'or'genpatch'togeneratepatchsets

Use'patch'toapplypatchesthatyoucreateorreceive 'patchkernel'toupdatekerneldirectoryinplace

62

Copyright2005RandyDunlap,Allrightsreserved.

PatchTools(2)

Canuse'patchscripts'or'quilt'forpatchmanagement

http://www.zip.com.au/~akpm/linux/patches/patchscripts0.20/ http://savannah.nongnu.org/projects/quilt

Sendaseriesofpatches(e.g.): http://www.speakeasy.org/~pj99/sgi/sendpatchset orsimilarscriptinpatchscripts SCMs:yourchoice,flavoroftheday 'git'forkernelsourcecodemanagement:http://www.kernel.org/git/

63

Copyright2005RandyDunlap,Allrightsreserved.

References(1/3)

http://lwn.net/Articles/driverporting/ http://lwn.net/Kernel/LDD3/LinuxDeviceDrivers3rded. *****subscribetoLWN.net***** http://kernelnewbies.orgarticles,documents,scripts,book recommendations,beginnerQ&A,IRC,mailinglist http://janitor.kernelnewbies.orgdocs,scripts,Dos/DONTs,TODO list,IRC,mailinglist http://www.linuxsymposium.org/2005/OLSproceedings

64

Copyright2005RandyDunlap,Allrightsreserved.

References(2/3)

http://www.kroah.com/linux/conferenceslides,papers,talks,tools, codingstyle,developmentprocess,dealingwithkernelcommunity, writingportablekernelcode http://people.redhat.com/arjanv/olspaper.pdfHowtoNOTwrite kernelcodeactualexamples(OLS2002) OLS2004keynote,AndrewMorton: http://www.zip.com.au/~akpm/linux/patches/stuff/ols2004.txt

65

Copyright2005RandyDunlap,Allrightsreserved.

References(3/3)

Linuxkernelsourcetree: linux/ MAINTAINERS,CREDITS CodingStyle SubmittingPatches SubmittingDrivers featureremovalschedule.txt(deprecated) stable_api_nonsense.txt linux/Documentation/

66

Copyright2005RandyDunlap,Allrightsreserved.

Credits

HughBlemings JamesBottomley MattDomsch JeffGarzik ClydeGriffin ChristophHellwig GerrittHuizenga GregKroahHartman

PatMochel AndrewMorton ArjanvandeVen RicWheeler CliffWhite ChrisWright ToppostingA&Qfroma.sigon theoldcrackmonkeyml

67

Copyright2005RandyDunlap,Allrightsreserved.