Kamikaze.openwrt.org Docs Openwrt

8/4/2019 Kamikaze.openwrt.org Docs Openwrt

1/24

Contents1 T he R ou te r1.1 Gett ing started1.1.1 Installation1.1.2 Initialc onfiguration1.1.3 Fai lsafe mode1.2 Conf igu r ing OpenWrt1.2.1 Network1.2.2 Wireless1.3 Advanced configu ra t ion1.3.1 lfu!p]yg1.3.2 Init scripts1.3.3 Ne tw o rk s cr ip ts2 D ev elo pm e nt is su es2.1 The bu il d s ys tem2.1.1 Building an image2.1.2 Creating packages2.1.3 Crea ti ng k e rn e l modul es p ack age s2.1.4 Conventions2.1.5 Troubleshooting2.1.6 Using bu i ld env ironmen ts2.2 Ext ra tool s2.2.1 Image Bu il de r2.2.2 SD K2.3 Adding p la tfOrm sywort2.3.1 Wh ic h Op er at in g S y st em d oe s this device run?2.3.2 Finding an d using the 11ll ll Ill fi lcturerSD K2.4 Debugging an d debricking2.4.1 Addi ng a s er ia l p o rt2.4.2 JTAG2.5 &;porting bugs2.5.1 Usi ng t he T ra c t ic ke t s ys tem2.6 Submit t ing patches2.6.1 How to contribute2.6.2 Wher e t o l is te n a n d t a lk2.6.3 Pa tch Submi ss io n P roce ssChapter 1The Router1.1 Getting started1.1.1 Installation1.1.2 Initial cenflguration1.1.3 Failsafe mode1.2 Configuring OpenWrt1.2.1 NetworkThe n e two rk conf ig u ra ti on i nKamik aze is s to re d i n /etc/config/network an d is divided into i n te r face configura tions. Each in ter face conf igu ra tion ei therr ef e rs d ir e ct ly t o an ethernetlwifi interface (ethD,wID, ..o r t o a b r id g e cont ai ni ng r rr u hi pl e in te r fa c es , Itl oo k s l ik e this:

config interface l'lan"option ifnarne "ethO"option proto I'static"option ipaddr "192.168.1.1"option netrnask 11255.255.255.011option gateway "192.168.1.254"


2/24

option dns "192.168.1.254"ifnarne s pe cif ie s t he L in ux i nte rf ac e n ame . I f y o u w an t t o u se b ri dg in g o n o ne o r mo re i nt er fu ce s, s et ifnarne t o a l is t o f in ter fuces and add:

option type "bridge"Itis p os si ble t o u se VLAN t ag gi ng o n a n interface s imp ly b y a dd in g t he VLAN I Ds to it, e.g. ethO.1.T he se c an b e n este d a s w ell.This s et s u p a s imp le s ta ti c con fi gu ra ti on fur ethO. proto s peci fi es t he p ro to co l u sed fur t he i nt er fu ce. Th e d ef au lt imag e u su a1l yprov id es ' none' 'static','dhcp' and' pppoe' . Oth e rs c an b e add ed by i ns ta ll in g add it io n al p ack ag e s.Wh en u si ng t he 'static' rrethod li ke i n t he e xampl e, th e o pt io ns ipaddr and netmask a re manda to ry , wh il e gateway and dns are option al Y ou ca ns pe cif y mo re t ha n o ne DNS s er ve r, s ep ar at ed with spaces.DHCP cur ren tl y onl y accep ts ipaddr (IP a dd re ss to r eq ue st fr om th e s erv er) a nd hostname ( cl ient h o st name i dent ifYa s) - b ot h a re opt io n alPPP b as ed p ro to co ls (pppoe, pptp, ...) accep t t he se opt io ns :

usernam eT he PPP u se rn ame ( us ua lly with PAP au then ti cat ion ) passw ordT he PPP p as sw or d k ee pa liv eP in g th e P PP s erv er (u sin g LCP ). T he value of this op ti on s peci fi es t he maximum nwn be r o ff ail ed p in gs b ef ur e r ec on ne ct in g, T he p in g i nt er va l d ef au ks t o

5 , b ut c an b e c ha ng ed b y a pp en din g " ,< in te rv al> " t o t he k ee pa li ve v alu e demandU se D ia l o n D emand ( va lu e s pe ci fi es t he ImXimum idle tirre, server: (pp tp)T he r em ote p ptp s erv er IP

F or all p ro to co l ty pe s, y ou c an a ls o s pe cif y th e MTU b y u sin g th e mtu optionSetting up static routes

You c an s et u p s ta ti c r ou te s f ur a s pe cif ic i nt er fu ce t ha t will b e b ro ug ht u p a ft er t he i nt er fu ce is configured.S imp ly a dd a c on fi g s ec tio n li ke this:

config route foooption interface Ianoption target 1.1.1.0option netmask 255.255.255.0option gateway 192.168.1.1

T he n am e f ur th e ro ute s ec tio n is op tional , t he interface, target and gateway o pt io ns a re ma nd at or y. L e av in g o ut t he netmask option will tum t he routeinto a h os t r ou te .Set ting up the switch (currently I roadcom only)

The swit ch configura tion is set by adding a ' switch' conf ig s ec ti on Examp le :config switch

option vIanOoption vIanl

"ethO""1 2 3 4 5*"" a 5"

O n B ro ad com h ard wa re th e se ctio n n am e n ee ds to b e e th O, a s th e s witc h d riv er d oe s n ot d ete ct th e sw itc h o n a ny o th er p hy sic al d ev ic e. E ve ry v la n o ptio nnee ds to ha ve the nam e vla n< n> w here < n> is the VLAN n wn be r a s u se d in t he sw itc h d riv er . A s v alu e it ta ke s a l is t o f p or ts with t hese op tional su ff ixes:

'*': Se t t he d e fau lt VLAN ( PV ID ) o f th e P ort to th e c ur re nt VLAN 'u': F orc e th e p or t to b e u nta gg ed 't': F orc e the port to b e ta gge d

T he C PU p or t d efa ults to ta gg ed , a ll o th er p or ts to u nta gg ed . O n B ro ad com h ar dw ar e th e C PU p ort is a lw ay s 5 . T he o th er p orts m ay v ary with differenthardware.For ins tance, ify ou w ish to ha ve 3 v la ns, lik e o ne 3 -port sw itch, 1 port in a DMZ, and a no th er o ne a s y ou r WAN i nt er fu ce , u se t he f ull ow in g c on fi gu ra tio n:

config switchoption vIanO

"ethO""1 2 3 5*"


3/24

option vIanIoption vlan2

"0 5""4 5"

Three in ternces will b e au toma ti ca ll y c re a ted u si ng this swi tch layou t : ethO. 0 (vianO),ethO.1 ( via nI ) a nd ethO. 2 ( vl an 2) . Y o u c an t he n a ss ig n t ho sei ot er fa c es t o a cu st om ne two rk conf igw"at io nname l ik e lan, wan or dmz fu r inst ance .Setting up I P m connecthityOp enW rt s up po rts I Pv 6 c on ne ct iv it y u si ng PPP, T un ne l b r ok er s o r s ta tic a ss ig nment .If y ou u se P PP , IP v6 will b e se tup u sin g I P6 CP a nd there is no thing to configure,T o s etu p a n I Pv 6 twm el to a tu rm el b ro ke r, y ou c an in sta ll t he 6seripts package an d ed it t he /ete/ eonfig/ 6tunnel file an d ch ang e t he s e tt in g sacco rdi ng ly :

config 6tunneloption tnlifnameoption remoteip4option loealip4option localip6option prefix

'sixbone''l.0.0.1''l.0.0.2''2001::DEAD::BEEF::1', /64'

'tnlifname': S et th e in te rf ac e n am e o f th e I Pv 6 in IP v4 tu nn el 'remoteip4': I P a dd re ss o f th e r em o te e nd to e sta blish th e 6 in 4 tu nn el This address is g iv enby t he t unn el b r ok e r 'loealip4': I P a dd re ss o f y ou r r ou te r to e sta blis h th e 6 in 4 tunnel, It will u su ally m a tc h y ou r WAN I P a dd re ss . '10eali p6' :I Pv 6 a dd re ss to se tu p o n y ou r tu nn el s id e This address is g iv enby t he t unn el b ro k er 'prefix': I Pv 6 p re fix to s etu p o n th e LAN.

U sin g th e s am : p ac ka ge y ou c an a ls o s etu p a n I Pv 6 b rid ge d c on ne ctio n:config 6bridgeoption bridge 'br6'

By d ef au lt t he s cr ip t b ri dg es t he WAN i nt er fa ce with t he LAN i nt er fa ce an d u se s e bt ab le s t o fiher anything that is n ot I Pv 6 o n th e b rid ge .IPv6 s tat ic addres s ing is a ls o s up po rte d u sin g a s im ila r s etu p a s I Pv 4 b ut with the ip6 prefix ing (when app li cable).

config interfaceoption ifnameoption protooption ip6addroption ip6gw

"Ian""ethO""static""fe80: :200:ff:feOO:0/64""2001: :DEAF:BEE:1"

1.2.2WirelessThe W i Fi s et ti ng s a re c on fi gu re d i n t h e file /ete/ eonfig/wireless ( cu rr en tly s up po rt ed o n B r oa dc om , A th er os an d mac8 02 11 ). Wh en b oo ti ng t he r ou te rf ur t he f ir st t ime i t s h ou ld d et ec t y ou r c ar d an d c re a te a s ampl e conf ig u ra ti on file. By de fau lt 'option network lan' is commented. This preven t s unsecureds ha ri ng o f t he n etw o rk o ve r t he w ir el es s interface,E ac h w ir el es s d ri ve r h as its own conf ig u ra ti on s cr ip t i n / lib/wifi / dri ver _name. sh wh ich h and le s d r iv e r s p ec if ic o p ti on s an d configurations. This script isa ls o c al li ng d r iv er s pe ci fi c b in ar ie s li ke w lc f ur B r oa dc om , o r h os ta pd an d wpa_ supp li can t f ur a th e ro s.Th e r e as on fu r u s in g s uch a rch it ec tu r e, is t ha t i t a b s tr a ct s t he d r iv e r conf ig u ra ti onGeneric Broadcom wireless config:

config wifi-deviceoption typeoption channel

"wlO""broadcom""5"

config wifi-ifaceoption device "wlO"

# option network Ianoption mode "ap"option ssid "OpenWrt"option hidden "0"option encryption "none"


4/24

Generic Atheros wireless conf ig:config wifi-device

option typeoption channeloption hwrnode "11g"

"wifiO""atheros""5"

config wifi-ifaceoption device "wifiO"

# option network ianoption mode nap"option ssid "OpenWrt"option hidden "0"option encryption "none"

Generic mac80211 wireless conf ig:config wifi-device

option typeoption channel

"wifiO""rnacB0211""5"

config wifi-ifaceoption device "wlanO"

# option network ianoption mode "ap"option ssid "OpenWrt"option hidden "0"option encryption "none"

Generic mult i-radio Atheros wireless config:config wifi-device wifiOoption type atherosoption channel

config wifi-ifaceoption device wifiO

# option network ianoption mode apoption ssid OpenWrt _privateoption hiddenoption encryption none

config wifi-device wifiloption type atherosoption channel 11

config wifi-ifaceoption device wifil

# option network ianoption mode apoption ssid OpenWrt publicoption hiddenoption encryption none

The re a re t wo t yp es o fc on fi g s ec ti on s in this f i le . The 'wifi-device' rem to the physical wifi interface and 'wifi-iface' conf ig u re s a v ir tu a l i nt er fa c e onto p o f t h at (ifsupported by t he d r iver ).A full ou tl in e o f t he w i re le ss conf ig u ra ti on f il ewith d e sc r ip ti on o f e ach f ie ld :

config wifi-deviceoption typeoption countryoption channeloption maxassocoption distanceoption hwmode

wifi device namebroadcom, atheros, mac80211us, uk, fr, de, etc.1-141-12B (broadcorn only)1-n11b, 11g, 11a, llbg (atheros, rnacB0211)


5/24

option rxantenna 0,1,2 (atheros, broadcom)option txantenna 0,1,2 (atheros, broadcom)option txpower transmission power in dBm

config wifi-ifaceoption network the interface you want wifi to bridge withoption device wifiO, wifil, wifi2, wifiNoption mode ap, sta, adhoc, monitor, or wdsoption txpower (deprecated) transmission power in dBmoption ssid ssid nameoption bssid bssid addressoption encryption none, wep, psk, psk2, wpa, wpa2option keyoption keyloption key2option key3option key4option server

encryption keykeykey 2key 3keyip addressport0,10,10,1 (atheros, broadcom)0,1 (atheros, broadcom)

option portoption hiddenoption isolateoption dothoption wmm

Options for the vifi-device: typeT he d riv er to u se f ur this ioterface. countryThe c ou nt ry c od e u se d t o d et erm in e t he r eg ul at or y s et ti ng s. channelTh e wifi c ha nn el ( e. g. 1 -1 4, d ep en di ng o n y ou r c ou nt ry s et tin g) . maxassocOp ti on a l: Max i nrum mnnbe r o f a s so c ia ted c li en ts . T his feature is s up po rt ed o nl y o n t he b ro ad com chi ps et . distanceOp ti on al : D is ta nc e b et we en t he a p a nd t he f in th es t c li en t inmeters . T his feature is s up po rte d o nl y o n t he a th er os c hi ps et . modeThe f re q ue nc y b an d (b, g, bg, a) . T his feature is o nl y s up po rte d o n t he a th er os c hi ps et . diversity

Op ti on a l: En abl e d iv e rs it y f u r t he Wi -F i d evi ce . T his feature is s up po rt ed o nl y o n t he a th er os c hi ps et . rxantennaOp ti on al : A n te nn a i de nt if ie r ( 0 , 1 o r 2 ) f ur r ec ep ti on T his feature is s up po rte d b y a th er os a nd s om e b ro ad com c hip se ts . txantennaOp ti on al : A n te nn a i de nt if ie r ( 0 , 1 o r 2 ) f ur em is sio n T his feature is s up po rt ed b y a th er os a nd s ome b ro ad com chi ps et s. txpower S et th e tr an sm is sio n p ow er to b e u se d. T he amo un t is specified in dB m

Options for the vifi-iface: networkSe le c ts t he i nt er fa c e s e ct io n f rom /ete/ eonfig/network to b e u se d with this interface deviceS e t t he wifi d evi ce n ame. modeOpe ra ti ng mode:

o apAcce ss p oi nt mo deo sta

Cl ien t modeo adhoe

A d-H oc m od eo monitor

Mon it or mo deo wds

WDS po in t- to -p o in t link ssid S e t t he ssm to be used on the wifi device.


6/24

bssid S et th e B S SlD a dd re ss to b e u se d tor wds to s et th e m ac a dd re ss o f t he o th er w ds unit. txpower ( D ep re ca te d , s et inwi fi -d ev ic e ) Se t t he t ran smi s si on power to b e u se d. T he amount i s spec if i ed in dB m encryption

Enc ryp ti o n s e tt in g . Accep ts t he fu ll ow i ngv a lu e s:o noneo wepo psk, psk2

WPA (2 ) P re -s ha re d K e yo wpa, wpa2

WP A (2 ) RAD IU S key, keyl, key2, key3, key4 (wep, w pa a nd p sk )

W E P k ey , W PA k ey (p SK IO Od e)o r th e R AD IU S s ha re d se cre t (WP A RADIU S IO Od e) server (wpa)T he RAD IU S s er ve r ip address port (wpa)T he RAD IU S s er ve r p or t ( de fa uh s to 1812) hiddeno b ro ad ca st s t he s si d; 1 d is ab le s b ro ad c as ti ng o f t he s si d isolateOp ti on a l: I so l at io n i s a IOOdeu sua ll y s e t o n ho ts p ot s t ha t l imits t he c l ien ts t o conmrun ic a te o n ly with the A P and not with o t he r w i re le s s c li ent s. 0 d is abl e s

ap i so la t io n ( d el im i t) ; 1 en ab l es ap i so l at io n . dothOp ti on al : T o gg le 8 02 .1 1h IOOd e. 0 d is ab le s 8 02 .1 1h ( de fa ul t) ; 1 e na bl es it. wmmOp ti on al : T o gg le 8 02 .1 1 e IOOd e. 0 d is ab le s 8 02 .1 1 e ( de fa ul t) ; 1 e na bl es it.

Wr re le ss D is tr ib utio n S ys tem WDS is a n on -s ta nd ar d I OO dew hic h will b e w or kin g b etw e en t wo B ro ad com d ev ic es f ur in sta nc e b ut n ot b etw ee n aB r oa dc om and A th er os d ev ic e.U ne nc ry pte d WDS c on ne ctio ns This conf ig u ra ti on ex amp l e s hows you how to s etu p u ne nc ry pte d WDS c on ne ctio ns . W e a ss um e th at th e p ee r c on fig ur ed a sb el ow a s t he BSS ID c a: re :b a :b e:OO:O la nd t he r emo te WDS end p oi nt c a :f e: ba :b e:OO :0 2 (o pt io n b ss id f ie ld ).

config wifi-device "wlO"option type "broadcom"option channel "5"

config wifi-ifaceoption device "wlO"option network lanoption mode "ap"option ssid "OpenWrt"option hidden "0"option encryption "none"

config wifi-ifaceoption device "wIO"option network Ianoption mode wdsoption ssid "QpenWrt WDS"option bssid "ca:fe:ba:be:00:02"

E nc ry pte d WDS c on ne cti on s It i s a l so p os si bl e t o e nc ry p t WDS connections, psk, psk2 an d psk+psk2 rmdes are s u ppo rt ed . Con fi gu r at io n b e low i s anex amp l e conf ig u ra t io n u s in g P r e-Sha r ed - Key s with AES a lgo ri thm .

config wifi-device wIDoption type broadcomoption channel

config wifi-ifaceoption device "wIO"option network Ianoption mode apoption ssid "OpenWrt"option encryption psk2option key ""


7/24

config wifi-ifaceoption device "wlO"option network la noption mode wdsoption bssid ca:fe:ba:be:OO :02option ssid "OpenWrt WDS"option encryption psk2option ke y " "

S0 2. Ix c o nf ig ur at io n s O p enW r t s up p or ts b ot h 8 02 .1 x c li en t a n d A c ce ss P o in t c on fi gu ra ti on s. 8 02 .1 x c li en t is on ly work ing with A th er os o r ma c8 02 11d r iv e rs . Con fi g ur a ti on on ly s uppo rt s EAP t ype s 1LS, T IL S or P EA P.EAP-TLS

config wifi-ifaceoption device "athO"option network Ianoption ssid OpenWrtoption eap_type tlsoption ca cert "/etc/config/certs/ca.crt"option priv_key "/etc/config/certs/priv.crt"option priv_key pwd "PKCS#12 passphrase"

EAP-PEAPconfig wifi-iface

option deviceoption network

"athO"option ssidoption ea p _ typeoption ca _certoption authoption identityoption password

la nOpenWrtpeap"/etc/config/certs/ca.crt"MSCHAPV2usernamepassword

l im i ta ti on s: T h er e a re c er ta in l im i ta ti on sw h en c omb in in g mo de s, O n ly t he fo l lowing mode comb in a ti on s a r e s uppo rt ed : B roadcom :

o l sta, 0-3 x apo 1 -4 x a po l adhoco l monitor

WD S lin ks c an o nly b e u se d in p ure A P rm de a nd c an oo t u se WE P ( ex ce pt w h en sharing t he se t ti ngs with t h e mas te r i n te r fa c e, wh i ch is doneautomatical ly) .

A theros:o l x s ta, O -N x apo 1-Nxapo l x a dhoc

N is th e maxirrrum n wn be r o f V A P s th at th e r oo du le allows, it defaults to 4 , b ut c an b e c ha ng ed b y lo ad in g th e r oo du le with t he ma xv ap s=N p ar ame te r.A dd in g a n ew d riv er c on fig ur atio n S in ce w e c ur re ntly o nly s up po rt th re ad d if fe re nt w ir ele ss d riv ers : B ro ad com , A th er os a nd m a c8 02 11 , y ou m i gh t bei nt er e st ed i n addi ng s uppo rt f u r anot he r d r iv e r l ik e Ra li nk R12xOO , Tex as I n st rumen ts ACX100 /1 11.T he d riv er s pe cif ic s cr ip t s ho uld b e p la ce d in / lib /w if i/< dr iv er >. s h a nd h as to in clu de s ev er al f im c tio ns p r ov id in g:

d ete ctio n o f t h e d riv er p re se nc e en ab li ng /d i sab li ng t he wifi interfuce(s) c on fi gu ra ti on r ea di ng an d setting t hi rd -p a rt y p ro gr am ; c al li ng ( n a s, s up pl ic an t)

E a ch d ri ve r s cr ip t s ho ul d a p pe nd t he d ri ve r to a g lo ba l DRNERS v a ri ab le :append DRIVERS "driver name"


8/24

scan_ llllSnmcmn WIllarse m e /etc/ config/wireless ana make su re m ere are no conngeranonmcompauourues, use enannngruaaen :S:SW:swith a d- h oc mo de f or i ns ta nc e. T his c an b e m ore c om ple x if your d ri ve r s uppo rt s a l of o f con fi gu ra ti on op ti on s. Itd oe s n ot c ha ng e th e s ta te o f t he in te rf ac e.Example:

scan_dummy ()local device="$111

config_get vifs "$device" vifsfor vif in $vifs; do# check config consistency for wifi-iface sectionsdone# check mode combination

}

enable _ T his fimction will b ri ng u p t he wifi device an d op ti on a ll y c re a te appl ic a ti on s pec if ic conf ig u ra ti on f il es , e .g . f ur t he WP A au th ent ic a to r o rsupplicantExample:

enable dummy() {local device="Slll

config get vifs "$device" vifsfor vif in $vifs; do# bring up virtual interface belonging to# the wifi-device "$device"done

disable_ T his function will b ri ng d own th e wifi dev ice and al l i t s v i rtual in ter fuces (if supported).Example:

disable dummy() {local device="$111

# bring down virtual interfaces belonging to# "$device" regardless of whether they are# configured or not. Don't rely on the vifs# variable at this point

detect _ T his f imc ti on l ooks fur interfaces that are usable with t he d ri ve r. T empl at e configs ec ti on s f ur n ew d ev ic es s ho ul d b e w ri tt en t o s td ou t. Mu stcheck fur a lr eady ex is ti og con fi g s ec ti on s b el ong in g t o t he i nt er fu ces b efur e c re at io g n ew t emp la te s.Example:

detect_dummy ()[ wifi-devicecat EOF

config wifi-device dummydev

"$(config_get dummydev type)" J && return 0

option type dummy# REMOVE THIS LINE TO ENABLE WIFI:option disabled 1

config wifi-ifaceoption device dummy devoption mode apoption ssid OpenWrt

EOF

1.3 Advanced configurationStructure ofthe configuration files


9/24

me conng rues are UMOeu mID secuons ana opuons/vames.E ve ry s ec tio n h as a ty pe , b ut d oe s n ot n ec es sa rily h av e a n ar re . E ve ry o ptio n h as a n am e a nd a v alu e a nd is a ss ig ne d to t he sec tion it was wr it te n unde r.Syntax:config [""]

option ""41= Section# Option

Every parameter needs to b e a s in gl e s tr in g a nd is f urmat te d e xa ct ly l ik e a parameter f ur a s he ll f im c ti on . T h e s am : r ul es f ur Quoting a nd s pe ci al c ha ra ct er s a ls oa pp ly , a s it is p ar se d b y th e s heD.Parsing confignration files in custom scripts

To b e a bl e t o l oa d c on fi gu ra ti on f il es , y o u n ee d to i nc lu d e t he common f imc ti on s with:. /etc/functions.sh

T he n y ou ca n u se config_load to load config f il es . Th e f imc ti on f ir st ch eck s fu r a s ab soh rt e f il en ame and fulls back to loading it from/etc/config ( wb ic his th e m os t c ommon w ay o f u s in g it).I f y ou want to u se s pe ci al c al lb ac ks f ur s ec ti on s a nd /o r o pt io ns , y ou n ee d to def ine the fol lowing shel l fimctions before running config_load ( a ft e r includ ing/etc/functions. sh]:config_ cb () (

local type~"$l"local name="$2"# commands to be run for every section

option cb () {# commands to be run for every option

Y ou c an a lso alter option cb from config_cb b as ed o n th e s ec tio n ty pe . This a ll ows you to p ro ce ss e ve ry s in gl e config s ec ti on b as ed o n its typeindividually.conflg cb i s r u n e ve ry t ime a n ew s ec tio n s ta rts ( be fo re o ptio ns a re b ein g p ro ce ss ed ). Y o u c an a cc es s th e la st s ec tio n th ro ug h th e CONFIG_SECTIONv ar ia ble . A ls o a n e xt ra c al l to config_cb ( wi th ou t a n ew s ec ti on ) i s g e n er at ed a ft er config_load i s d o n e. T h at a llow s y ou to p ro ce ss s ec ti on s b ot h b ef or ea nd a ft er a ll o p ti on s w e re p ro ce ss ed .A no th er w ay o f iteratingo n c on fi g s ec tio ns i s u s in g t he config_ foreach command .Syntax:config foreach [] []

This command will r un th e s up pli ed f im c ti on f ur e ve ry s in gl e c o nf ig s ec ti on i n t he c ur re nt ly l oa de d c on fi g. T he s ec ti on n ar re will b e p as se d to th e f im c tio n a sa rg um en t I . I f t he s ec tio n ty pe is a dd ed to t he command line, t he f imct ion will o nl y b e c al le d f ur s ec ti on s o f t he g iv en t yp e.Y ou c an a cc es s a lr ea dy p ro ce ss ed o ptio ns with the conf i g_ge t command Syntax:

# print the value of the optionconfig_get

# store the value inside the variableconfig_get

Inbu sybox a s h t he t hr e e- op ti on config_get i s fas te r , because it d oe s n ot r es ult in a n e xtr a fo rk , s o it i s t h e p re fe rr ed w a y.A d di ti on al ly y ou c an a ls o mo di fY o r a dd o pt io ns to s e ct io n s by u s in g t he config _set command .Syntax:

config_set I fa c on fi g s ec ti on i s u n named , a n a ut oma ti ca ll y g en er at ed n ar re will b e a s si gn ed i nt er na ll y, e .g . cfgl, cfg2, ...While it is p os si bl e, u si ng u nn ar re d s ec ti on s th ro ug h t he se a ut og en er at ed n ame s i s s tr on gl y d is co ur ag ed . U se c al lb ac ks o r config_ foreach instead.


10/24

~.).~ llULplUg

1.3.2 lnit scriptsB ec au se O pe nW rt u se s its ow n init s cr ip t s ys tem , a ll init s cr ip ts mu st b e i ns ta ll ed a s /etc/init. d/ name use /etc/rc. common a s a w ra pp er .Exampre:/etc/init.d/httpd#!/bin/sh /etc/rc.common# Copyright (C) 2006 OpenWrt.orgSTART~50start () {

[ -d /www J && httpd -p 80 -h /www -r OpenWrt

stop ()killall httpd

a s y ou c an s ee , th e sc rip t d oe s n ot a ctu ally p ar se th e c omm an d l ine a rg ur re nt s it se lf T his is d on e b y t he w ra pp er s cr ip t /etc/rc. common.start () an d stop () a re th e b as ic f un ct io ns , w hi ch a hn os t a ny init scrip t shou ld prov ide . start () is c alle d w he n th e u se r r un s /etc/ ini t. d/httpdstart or (if t he s cr ip t i s en ab led an d do es not o v er ri de this b eh av io r) a t s ys tem b oo t time.Enabling an d disabling init s cr ip ts is d on e b y n nm in g /etc/ ini t. d/ name enable or /etc/ini t. d/ name disable. This c re at es o r r emo ve s s ymb oli c li nk sto th e init scrip t in /etc/rc. d, w hic h is p ro ce ss ed b y /etc/ in i t.d/rcS a t b oot time.The o rd er in w hi ch t he se s cr ip ts a re r un is d ef in ed i n t he v ar ia ble STARTi n t he init scrip t. Chang ing it requi res nnming /etc/ ini t. d/ name enable again.Y o u c an a ls o o ve rr id e t he se s ta nd ar d init script functions:

boot ()C omma nds to be run a t b oot time. Defau l ts to start () restart ()Rest ar t y our s er vi ce . De faul ts t o stop (); start () reload ()Re lo ad t he conf ig u ra ti on f il es f ur you r s er vi ce . De faul ts t o res tart ()

You c an a lso a dd c us to m c omman ds b y c re atin g th e a pp ro pr ia te fu nc tio ns an d r ef er en c in g t hem i n t h e EXTRA_COMMANDSa ri ab le , H e lp te xt i s a d de d i nEXTRAHELP.

status ()# print the status info

EXTRA COMMANDS="status"EXTRA HELP=" status Print the status of the service"

1.3.3 Network scriptsUsing the netwerk scripts

T o b e a ble to a cc es s th e n etw ork f un ctio ns , y ou n ee d to in clu de th e n ec ess ary sh ell sc rip ts b y n nm in g:. /etc/functions.shinclude /lib/networkscan interfaces

# common functions# include /lib/network/*.sh# read and parse the network config

S om e p ro to co ls , su ch a s P PP m i gh t c ha ng e t he c on fi gu re d in te rf ac e n ame s a t r un time (e.g. ethO => pppO fur P PP oE ). T hat's w hy yo u h ave to runscan_interfaces i ns te ad o f r ead in g t he v a lu es f romth e conf ig di re ct ly . A f te rn nming scan_interfaces, the' ifname' option will a lways cont ai n t hee ff ec ti ve in te rf ac e n ame (wh ic h is u se d f ur I P traffic) an d if t he p hy sic al d ev ic e n ame d if fe rs f rom it, it will b e s to re d in th e 'device' o ptio n T ha t m ea ns th atnnming con fig_get Ian ifname after scan_interfaces m i gh t n ot r et ur n t he s ame r es ul t a s n nm in g it befure.After nnming scan_interfaces, t he fu llowing funct ions are avai lab le :


11/24

- IlnO_conIlg ~n~erracel oo ks f ur a n etwo rk c on fi gu ra ti on t ha t i nc lu de s t he s pe ci fi ed n etwo rk i nt er fa ce .

setup_interface interface [config] [protocol]will s et u p t he s pe ci fi ed i nt er fa ce , o pt io na ll y o ve rr id in g t he n etwo rk c on fi gu ra ti on n am e o r t he p ro to co l t ha t it uses.

Writing protocol handler.

Y ou c an ad d cu sto m p ro to co l h an dlers by ad din g sh ell scrip ts to / lib/network. Th ey p ro vi de t he f ul low in g two s he ll f im ct io ns :scan_() {

local config="$l"# change the interface names if necessary

setup interface_()local interface="$l"local config="$2"# set up the interface

scan _protocolname i s o pt io na l a nd o nl y n ec es sa ry ify ou r p ro to co l u ses a cu sto m d ev ice, e.g . a tu nn el o r a PPP device.Chapter 2Development issues2.1 The build systemOne o f t he b ig ge st c ha ll en ge s t o g et ti ng s ta rt ed with e mb ed de d d ev ic es i s t ha t y ou c an no t j us t in st all a c op y o fL in ux an d expect to be able to com pile af irmwar e. Even ify ou d id re memb er t o i ns ta ll a c om pile r an d ev ery d ev elo pm en t too l o ffere d, y ou still w ou ld n ot h av e th e b asic set o f t oo ls n eed ed to p ro du ce af irmw are im ag e. T he e mb ed de d d ev ic e re pre se nt s a n e nt ire ly n ew h ard wa re p la tfo rm , w hi ch i s m o st o f th e t ime incompatible with t he h ard wa re o n y ou rd ev el opme nt m ac hin e, s o in a p ro ce ss c al le d c ro ss c om pi li ng y ou n ee d to p ro du ce a n ew c om pil er c ap ab le o f g en era ti ng c od e f ur y ou r e mb ed de d p la tfo rm , an dt he n u se it to c om pil e a b as ic L in ux d is tri bu tio n to ru n o n y ou r d ev ic e.T he p ro ce ss o f c re at in g a c ro ss c om pi le r c an b e tri ck y, it i s no t some th ing tha t i s r egu la rl y a tt emp te d an d s o t he re i s a c er ta in a mo un t o f m ys te ry an d blackmagic assoc iated with it. Inm an y c as es w he n y ou a re d ea lin g with e mb ed de d d ev ic es y ou will be p rov ide d with a b in ary c op y o f a c om pil er an d bas ic l ibra rie sr at he r t ha n i ns tr uc ti on s f ur c re at in g y ou r own - it is a t ime s av in g s te p b ut a t t he s am e t ime o ft en m ea ns y ou will b e u sin g a ra th er d ate d s et o ft oo ls . L ik ew is e, itis a ls o c om ro on t o b e p ro vi de d with a p atch ed co py o f t he L in ux k ern el fro m th e b oard o r ch ip v en do r, b ut this i s a ls o d at ed an d it can b e dif l icuh to s po te xa ctly w ha t h as b ee n m od ifi ed t o m ak e th e k ern el ru n o n th e e mb ed de d p la tfo rm2.1.1 Building an imageOpenWrt t ak es a d if fe re nt a pp ro ac h t o b ui ld in g a f irmwar e; d own lo ad in g, p at ch in g an d c omp il in g e ve ry th in g f rom s cr at ch , i nc lu di ng t he c ro ss c om p il er . T o p ut itin s im pl er t erm s, O pe nW rt d oe s n ot c on ta in a ny ex ec uta ble s o r e ve n s ou rc es , it is a n a utoma te d s ys te m fu r d ow nlo ad in g t he s ou rc es , p atc hi ng th em to w orkwith t he g iv en p la tf orm a nd c omp il in g the m c or re ct ly f ur t ha t p la tf orm, What this m ea ns is th at j us t b y c ha ng in g th e te mp la te , y ou c an c ha ng e any s te p i n t heprocess.A s a n e xa mp le , ifa n ew k ern el is r ele as ed , a s im ple c ha ng e t o o ne o f t he M ak efil es will d own lo ad t he l at es t k er ne l, p at ch it t o ru n o n t he e mb ed de d p la tfo rman d produce a new firm ware im age - there is no w ork to be done t ry ing t o tr ac k d ow n a n u nm od ifie d c op y o f t he e xi sti ng k ern el t o s ee w ha t c ha ng es had beenm ad e, t he p at ch es a re a lr ea dy p ro vi de d an d t he p ro ce ss e nd s u p a lrms t c om p le te ly t ra ns pa re nt . This d oe s n ot j us t a pp ly to t he k ern el , b ut t o a ny th in g in cl ud edwith O penW rt - Itis this o ne s im pl e u nd ers ta te d c on ce pt w hic h is w ha t a ll ow s O pe nW rt t o s ta y o n t he b le ed in g e dg e with t h e l at es t c omp i le rs , l at es t k e rne lsan d la test applications.S o let's tak e a lo ok at O penWrt an d s ee h ow this a l lworks .DownloadOpenWrt

This a rt ic le r efe rs to t he " Kami ka ze " b ra nc h o fO pe nW rt, w hic h c an b e d ow nl oa de d v ia subve rs ion u s ing the f ul low ing co rr nnand :$ svn checkout svn://svn.openwrt.org/openwrt/trunk kamikaze

Add it io na lly , th er e is a tr ac in te rfa ce o n h tt ps :/ /d ev .o pe nw rt.o rg /w hic hc an b e u se d t o m on it or s vn c omm its a nd b ro ws e th e s ou rc e re po si to ry .The directory ' t rueture

T he re a re fo ur k ey d ir ec to ri es in th e b as e:


12/24

toolchain package target

tools an d toolchain r ef er t o c ommon to ols w hi ch willb e u se d t o b ui ld t he f irmwa re ima ge , th e c omp ile r, an d th e C lib ra ry . T he r esu h o f this i s t hr ee n ewdirectories, build_dir/host, whi ch i s a t emp or ar y d ir ec to ry f ur b ui ld in g th e ta rg et in de pe nd en t to ols , build_dir/toolchain-* w hic h is u se d fu rb ui ld in g t he t oo lcha in fur a s pec if ic a rch it ec tu re , and staging_dir /toolchain-* wher e t he r es uh in g t oo lch ai n i s i ns ta ll ed . You willnot need to doanything with t he toolchain d i rec to ry unless yo u in tend to a dd a new version of one of the co mpone nts ab ove.

build_dir/host build_dir/toolchain-*

package is f ur e xa ctl y t ha t _ p ac ka ge s. Ina n O pe nW rt fir mw are , a hn ost e ve ry th in g is a n . Lpk, a softw are pa ckag e w hich ca n be ad ded to the firm wa re top ro vid e n ew f ea tu re s o r remo ve d to sa ve sp ac e. N ote th at p ac ka ge s a re a ls o m ain ta in ed o utsid e o f t he m ain tn mk a nd c an b e o bta in ed fro m su bv ers io n u sin gth e p ac ka ge r ee ds s ys tem :

$ ./scripts/feeds updateTho se p ac ka ge s c an b e u se d t o e xte nd th e f un ct io na li ty o f t he b uil d s ys tem an d n ee d to b e symlin ke d into the m ai n tn mk . O nc e y ou d o th at, th e p ac ka ge s willshow up i n t he r re nu f ur c on fi gu ra tio n. F rom k am ik az e y ou wou ld d o s ome th in g l ik e this:

$ ./scripts/feeds search nrnapSearch results in feed 'packages':nrnap Network exploration and/or security auditing utility$ ./scripts/feeds install nmap

To i nc lu de a ll p a ckag es , i ss ue t he ful low ing command:$ make package/symlinks

target rem to the em bedded platform, this contains items whi ch a re s pe ci fi c to a s pe ci fi c embe dd ed platform O f p ar ti cu la r in te re st h er e i s t h e"target/ linux" d ir ec to ry w hi ch is b ro ke n d own b y p la tf orm an d c on ta in s t he p at ch es to t he k er ne l, p ro fil e c on fig , f ur a p ar ti cu la r p la tf orm T he re 'sa ls o t he "target/ image" d ir ec to ry w h ic h d es cr ib es h ow to p ac ka ge a f irmwar e f ur a s pe cif ic platformB oth th e ta rg et a nd p ac ka ge ste ps willu se t he d ir ec to ry ''bu ild _d ir / " as a t empor ary d ir ec to ry fur comp il in g. Addi ti on al ly , any th in g down lo aded byth e to olc ha in , ta rg et o r p ac ka ge s te ps willb e p la ce d in th e "dl" directory.

build_dir/ dl

Building OpenWrt

Wh ile t he O pe nW r t b ui ld e nv ir onmmt w as i nte nd ed rmstly fur developers , it a ls o h as to b e s im ple e no ug h th at a n in ex pe rie nc ed e nd u se r c an e asily b uild his orhe r own customized firmware.Running t he command "make menuconfig"will b ri ng u p Ope nW r t's c on fig ur at io n menu s cr ee n, t hr ou gh this menu you can s el ec t wh ichp la tf urmyou' reta rg etin g, w hic h v er sio ns o f t he to olc ha in y ou w an t to u se to b uild a nd w ha t p ac ka ge s y ou want t o inst al l into the firmware im a ge . N ot e t ha t itwilla lso c he ck tom ak e su re y ou h av e th e b asic d ep en de nc ie s fu r it t o r un c or re ctl y. I f t h at m i l s , you willn ee d to i ns ta ll s ome I ID re to ols i n y ou r l oc al e nv ir or nn en t before y ou c anbegin.S im i la r t o t he l inux k er ne l c on fig , a hn os t e ve ry o pt io n h as t hr ee c ho ic es , y /m/ n whi ch a re r ep re se nt ed a s follows:

(pressingy)This willb e in clu de d in t he f irmwa re ima ge ( pr es si ng m)

This willb e c omp il ed b ut n ot in clu de d ( fu r la te r i ns ta ll) < > (p res sing n)This willn ot b e c omp ile d

After you 've f in i shed with t he menu conf ig ur at io n , exi t an d when p rompt ed , s av e yow- con fi gu ra ti on ch ang es .I f y o u w an t, y ou c an a ls o I ID difY th e k er ne l c on fi g f or th e s el ec te d t ar ge t s ys tem s imp ly r un "make kernel_ menuconfig" a n d th e b ui ld s ys tem willu np ac k t hek er ne l s ou rc es ( if ne ce ss ar y) , r unmen uc on fi g i ns id e o f th e k er ne l t re e, a nd t he n c op y t he k er ne l c on fi g to target/ linux/ /config s o th at it isp re se rv ed o ve r "make clean" calls.To b egi n comp il in g t he f irmwar e, t yp e "make".By de fau lt OpenWrt willonl y d is pl ay a high l ev e l o ve rv iew o f t he comp il e p ro ces s an d no t e ach i nd iv id u al


13/24

Example:

make[2] toolchain/installmake[3] -c toolchain installmake[2] target/compilemake[3] -c target compilemake[4] -c target/utils prepare[ ...]

T h i s make s i t e a si er t o mo ni to r w h ic h s te p i t' s a ct ua ll y c omp il in g an d r ed uc es th e am ou nt o f n o ise c au se d b y th e c om pile o utp ut. T o s ee th e full ou tp u t, r un t hecomnand ''make V=99".

During t he bu il d p roce ss , b u il dr o ot will d own lo ad a ll s ou rc es t o t he "dl"directory a nd will s t ar t pa t ch ing an d compi ling them in the ''build_dir / "d ir e ct or y . When f in is h ed , t he r e su lt in g firmwarewill be in the ''bin''irectory an d packages will be in the ''bin/packages''directory.2.1.2 Creating packagesO ne o f t he things th at w e'v e a tte m pte d to d o with O pe nW rt's te m pla te s ys tem is m a ke it in cr ed ib ly e as y to p or t s of tw are to O pe nW r t. I f y ou lo ok a t a ty pic alp ack age d ir e ct or y inOp enW rt y ou 'l l find tw o things:

package//Makefile package//patches package//files

The p a tch es d ir e ct or y i s o p ti on a l an d t yp ic al ly c on ta in s b ug f ix es o r o pt im i za ti on s t o r ed uc e t he s iz e o f t he e xe cu ta ble . T h e p ac ka ge make fi le i s t he impo rta ntitem, p ro vi de s t he s te ps a ct ua ll y n ee de d t o d own lo ad an d compi le t he p ack age .Th e f il es d ir e ct or y i s a ls o op ti on a l a nd t yp ic al l c on ta in s p ac ka ge s pe ci fi c s ta rt up s cr ip ts o r d el im i t c on g ur at io n f il es t h at c an b e u se d o ut o f t he b ox withOpenWrt.L oo kin g a t o ne o f th e p ac ka ge m a ke file s, y ou 'd h ar dly r ec og niz e it a s a m a ke file . T h r o u gh w ha t c an o nly b e d es cr ib ed a s b la ta nt d is re ga rd a nd a bu se o f th et rad it io n al mak e fonn at , t he makef il e h a s b een t ran sf ormed into an ob je c t o r ien ted t emp la te wh ich s imp li fi es t h e en ti re o rd ealH er e f or e xamp le , is package/bridge/Makefile:

# $Id: Makefile 5624 2006-11-23 00:29:07Z nbd $

include $(TOPDIR)/rules.mkPKG_NAME:~bridgePKG VERSION:~1.0.6PKG RELEASE:~l

PKG_SOURCE:~bridge-utils-$(PKG_VERSION) .tar.gz10 PKG_SOURCE_URL:~@SF/bridgeII PKG MD5SUM:~9b7dc52656f5cbec846a7ba3299f73bd12 PKG CAT:~zcatII

14 PKG_BUILD_DIR:~$(BUILD DIR)/brldge-utils-$(PKG_VERSION)is16 include $ (INCLUDE_DIR)/package.mk17

18 define Package/bridgew SECTION:~netw CATEGORY:=Base system21 TITLE:=Ethernet bridging configuration utilityn URL:~http://bridge.sourceforge.net/23 endef24

~ define Package/bridge/description26 Manage ethernet bridging:v a way to connect networks together to form a larger network.28 endef


14/24

~ define Build/ConfigureD $ ( ca ll Bu il d/Con fi gu re /De fau lt ,II --with-linux-headers="$(LINUX DIR)"3l34 endefas d efin e P ac ka ge /b rid ge /in sta ll37 $ ( INSTALL_DIR) $ ( 1) /u sr /s bin38 $ (I NSTALL _B IN ) $ (PKG _BUI LD _D IR )/b rc tl/b rc tl $ (l)/u sr /s bin /39 endef4041 $ (e va l $ (c all B uild Pa ck ag e, brid ge ))A s y ou c an s ee , t he re 's n ot I IU lChwo rk to b e don e ; ev eryt hi ng is hidden in o ther makefi les and abstracted to th e p oin t w he re y ou o nly n ee d to s pe ci fy a f ewvariables.

PKG N AMET he n am e o f t he pack age , as seen v ia rnenuconfig and ipkg PKG V ERSION

The u ps tr eam v er si on nwn be r t ha t w e a re d own lo ad in g PKG RELEASE

The v er sio n o f this p ack age Makef il e PKG SOURCE

The f il en ame o f t he o ri gi na l s ou rc es PKG SOURCE URL- -Where to d ownlo ad th e s ou rc es f rom ( no t ra il in g s l as h) , y ou c an a dd mu hip le d own lo ad s ou rc es b y s ep ar ati ng th em with aand a ca rr iag e r et ur n.

PKG M D5SUMA check sum to validat e the download PKG C ATHo w to d ec omp re ss th e s ou rc es ( zc at , bzcat, WlZip) PKG BUILD DIR

Where to compi le t he p ack ageThe PKG_ * vari ables define where to d ow nlo ad th e p ac ka ge fr om ; @SF is a s pe ci al k eywo rd f ur d ownl oa di ng p ac ka ge s f rom s ou rc ef ur ge . T he re is alsoa no th er k ey wo rd O f@GNUfu r g ra bb in g GNU s ou rc e re le ase s. If an y o f th e a bo ve rrentionned down lo ad s ou rc e m i l s , th e O p enW rt m ir ro rs will be used assource.Th e ml 5s um ( if pr es en t) is used to v er if y t he p ac ka ge w as d ownl oa de d c or re ct ly and PKG_BUILD_ DIR defines where to find th e p ac ka ge a fte r th e so urc es a reuncompressed into $ (BUILD_DIR) .A t th e b otto m o f th e file is wher e t he r ea l magi c h app en s, ' 'Bu il dPack ag e '' is a ma cr o s et u p b y t he e ar li er i nc lu de s ta temen ts . B ui ld Pa ck ag e o nl y ta ke s o nea rg ur re nt d ir ec tly - th e n ame o f th e p ac ka ge to b e bu il t, in this case "brdge ". All other infurmation is t ak en f rom th e d ef in e b lo ck s. This is a w ay of pro vid ing ale ve l o f v erb osity , it's in he re ntly c le ar w ha t th e c on te nts o f th e d es cr ip tio n temp la te in Package/bridge is, w hic h w ou ld n't b e th e c ase if we p ass ed thisi nf urmat io n d ir ec tl y a s t he N t h a rg umen t to BuildPackage.B uild Pa ck ag e u se s th e fu llo win g d efin es :Package/: match es t he a rg umen t p a ss ed to buiklroot, this d es cr ib es t he p ac ka ge t he menu co nf ig and i pk g e nt ri es . W i th in P ac ka ge / y ou c an d ef in e t heful lowing variables:

SECTIONThe t yp e o f p ac ka ge ( cu rr en tl y u nu se d) CATEG ORYWh ic h menu i t a p pe ar s in menucon fi g: Ne two rk , Sound, U t il it ie s, Muh imed ia . .. TITLEA s ho rt d es cr ip ti on o f th e p ac ka ge URLWhere to find t he o r ig ina l so ftware MAINTAINER(opt io na l)

Who to con ta c t con cerni ng t he p ack ag e DEPENDS ( o pti on al)

Wh ich p ack ag es mu st b e bui lt /i ns ta ll ed b efur e this p ac ka ge . T o r ef er en ce a d ep en de nc y d ef in ed in t he s ame Make fil e, u se . Ifd ef in ed a s a n e xte rn al p ac ka ge , u se +. F or a k er ne l v ers io n d ep en de nc y u se : @LINUX_2_

RTlTT,nONT,Y (ontional)


15/24

Set this option to I ifyou do NOT want your package to appear in rrenuconfig This isuseful for packages which are only used as build dependencies.Package// conffiles (optional):A list of config files installed by this package, one fileper line.Build/Prepare (optional):A set of commands to unpack a nd patch the sources. You may safely leave this undefined.Build/Configure (optional):You can leave this undefined ifthe source doesn't use configure or has a normal cong script , otherwise you can put your own commands here or use "s (callBuild/Configure/Default,


16/24

F o r external kernel m odules, you can add them to the build system just like if th ey w ere so ftw are p ack age s by d efin ing a K ern elP ackag e section in t he p a ck a gemakefile.H ere fu r in stan ce the M akefile fur th e I2 C su bsy tem k ern el m od ules:

# $Id $

I2CMENU:~I2C Bus

define KernelPackage/i2c-coreTITLE:~I2C supportDESCRIPTION:~Kernel modules for i2c supportSUBMENU:~$(I2CMENU)KCONFIG:~CONFIG I2C CORE CONFIG I2C DEV

10 FILES:~$(MODULES_DIR)/kernel/drivers/i2c/*.$(LINUX KMOD_SUFFIX)11 AUTOLOAD:~$(call AutoLoad,50,i2c-core i2c-dev)12 endef" $(eval $(call KernelPackage,i2c-core))T o g rou p k ern el m od ules un der a co mm on d escriptio n in r ne nu co nf ig , y ou might want to define a MENU v ariab le o n to p of th e k ernel m od ulesmakefile.

TITLEThe narre of the m odule as seen via rrenuconfig DESCRIPTIONT he d esc ription as see n via help in menuconfig

SUBMENUT he sub m enu under w hich this package will b e seen

KCONFIGK erne l co nfigu ratio n o ption d ep end en cy . F or ex terna l m odu les, rem ov e it.

FILESF il es y ou want to inlud e to this k er ne l m od ule p ac ka ge , s ep ar ate with spaces.

AUTOLOADMo du le s t ha t will be loaded autom atically on boot, the order you write them is the order they w ould be loaded.

After you have created your package/kernel/modules/ .mk, the new k ern el m odu les p ack age will a ut om a ti ca ll y s how in th e r re nu u nd er ''K ern elm o du le s" n ex t titre y ou run ''m ake m en uco nfig " an d if selected will b e b uilt a uto ma tic ally th e n ex t titre "rnake" is TIm.2.1.4 ConventionsT here are a couple conventions to follow r eg a rd in g p a ck a ge s:

files1 . c on fig ur atio n f il es f ollo w th e c on ve ntio n

.conf2. init files follow t he conven tion

.init patches

1. patches are num erically prefixed and nam ed rela ted to w hat they do2.1.5 TroubleshootingI f y ou find your package doesn 't show up in menuconfig, try th e fol lowing com mand to see ify ou g et th e c or re ct d esc rip tio n:

TOPDIR~$PWD make -C package/ DUMP~l V~99If you're just having trouble getting your package to com pile, there's a few shortcuts you can take. Instead of wait ing fur m ake to get to your package, you canr un o ne o f t he f ullo win g:

make package//clean V~99 make package//install V~99

A no th er n ic e t ri ck is that ifth e so urce d irecto ry un der build _dir / is newer t h a n the package directory, it w on't clobber it b y unpacking the sourcesagain. If you were working on a patch you could sim ply edit the sources under the build _dir/ / d ir ec to ry a nd r un t he in sta ll c omm an dabo ve, w hen sa tisfied , c op y th e p atch ed so urces elsew here an d d iffth em with the unpatched sources. A w arning though - ifyo u go m od ifY anything underpackaqe / it will rem ove the old sources and urm ack a fresh copv,


17/24

Oth e r u se fu l t ar ge ts i nc lu d e: make package//prepare V~99 make package//compile V~99 make package//configure V~99

2.1.6 Using build environmentsOpenWrt p ro vi de s a mean s o f bui ld in g imag e s fur r rr ul ti pl e con fi gu ra ti on s wh ich can u se r rr ul ti pl e ta rg et s in on e s in g le ch eckou t. Th es e environments sto re ac op y o f th e . co nf ig file g ene ra ted by make menuconfig an d the c ontents o f t he . /files f ul de r. Th e s cr ip t. /scripts/env is u se d to m an ag e th es eenvi ronment s, i t u ses git ( wh ic h n ee ds t o b e i ns ta ll ed o n y ou r s ys tem ) a s b ac ke nd f ur v er sio n c on tr olTh e command

./scripts/env helpp ro du ce s a s ho rt h el p t ex t w ith a l is t o f c omman ds .T o c re ate a n ew e nv ir on me nt n am ed current, r un t he fol low ing command

./scripts/env new currentThis will m ove your . config file and . / files (if i t e x i st s) t o t he env/ subdirectory an d crea t e sym1inks in th e b as e f ol de r.After nm ni ng make menucon fi g o r ch angi ng things in f i les!, your cur ren t s ta te will d ille r fro m w ha t h as b ee n sa ve d b ef or e, T o sh ow th es e c ha ng es , u se :

./scripts/env diffIf y ou w an t to sa ve th ese c ha ng es, n m:

./scripts/env saveIf y ou w an t to re ve rt y ou r c ha ng es to th e p re vio usly sa ve d c op y, n m:

./scripts/env revertI f y ou want, y ou c an n ow c re ate a s ec on d e nv iro nm en t u sin g t he new command. Itwill a sk y ou w he th er y ou w an t to m ak e it a c lo ne o f th e c urr en t e nv iro nm en t( e. g. f ur m in or c ha ng es ) o r if y ou w an t t o s ta rt w it h a c le an v er sio n ( e. g. f ur s ele cti ng a n ew t ar ge t) .T o sw itc h to a different env ironmen t (e .g . te stL], use:

./scripts/env switch testlT o renam e the cu rrent bra nch to a new nam e (e.g. test2), use:

./scripts/env rename test2If yo u w an t to get rid of env ironmen t swit ching an d keep every thing in th e b as e d ir ec to ry a ga in , u se :

./scripts/env clear

2.2 Extra tools2.2.1 Image Builder2.2.2 SD K

2.3 Adding platform supportLinux is n ow o ne o f t he m ost w id esp re ad o pe ra tin g sy stem fu r emb ed de d d ev ic es d ue to its o pe ne ss a s w en a s th e w id e v arie ty o fp la tfu nn s it c an r un o n M a nyr ranuf ac tu re r a ct ua ll y u se i t in f innware y ou c an f in d o n m an y d ev ic es : DVB- T d ec od er s, r ou te rs, p rin t se rv ers , D VD p la ye rs ... M o st o f th e time t he s to ckf innware is n ot r ea lly o pe n to th e c on sume r, e ve n if i t u se s o pe n s ou rc e s of tw ar e.Yo u might be in teres ted in nmning a L in ux b ase d f ir mw are f ur y ou r r ou te r f ur v ario us re aso ns: e xte nd in g th e u se o f a n etw or k p ro to co l (su ch a s I Pv 6), h av in gn ew fe atu re s, n ew p ie ce o f s oftw ar e in sid e, o r f ur se cu rity r ea so ns . A fully open -s ou rc e f irmwar e is d e- fa cto n ee de d f ur su ch a pp lic atio ns, sin ce y ou w an t to b ef re e to u se this o r t ha t v er sio n o f a p ar tic ul ar r ea so n, b e a bl e to c or re ct a p ar tic ul ar b ug . F ew manu fa ctu re rs d o s hip th eir r ou te rs w it h a S amp le D e ve lo pmentK it, th at w ou ld a llo w y ou to c re ate y ou r o wn an d c usto m f ir mw are a nd m ost o f th e time, w he n th ey d o, y ou will mos t lik ely n ot b e a ble to c om ple te th ef innware crea t ion process .This is o ne o f th e re aso ns w hy O pe nW rt an d other f innware ex is ts : p rov iding a vers ion independen t , an d to ols i nd ep en de nt f irmw ar e, th at c an b e nm o n v ar io us


18/24

p la tf orms , k nown t o b e running Linux original ly.2.3.1 Which Operating System does this device run?T he re is a lo t o fr re th od s to e nsu re y ou r d ev ic e is running L in ux . S om e o f t hem d o n ee d y ou r r ou te r to b e u ns cre we d an d o pen, som e can b e done by pro bin gt he d evi ce u si ng i ts ext er na l n etwork i nt er fa c es ,Operating System fingerprint ing and port scanning

A l ar ge b un ch o f to ol s o ve r t he I nte rn et e xis ts in order to let you do O S fingerprinting, we will sh ow h er e a n e xamp le u sin g nmap:nmap - p o -0 Starting Nmap 4.20 ( http://insecure.org ) at 2007-01-08 11:05 CETInteresting ports on 192.168.2.1:Not shown: 1693 closed portsPORT STATE SERVICE22/tcp open ssh23/tcp open te1net53/tcp open domain80/tcp open httpMAC Address: OO:13:xx:xx:xx:xx (Cisco-Linksys)Device type: broadband routerRunning: Linksys embeddedOS details: Linksys WRT54GS v4 running OpenWrt w/Linux kernel 2.4.30Network Distance: 1 hop

nma p is a ble to re po rt w he th er y ou r d ev ic e u se s a L in ux T CP II P s ta ck , an d i f so , will s how y ou whic h L in ux k er ne l v er sio n is p ro ba bl y r un s. This r ep or t is q uit ereliable an d i t c a n make t he d is tin ct io n b et we en BSD an d L in ux TCP/I P s ta ck s an d others.U si ng th e s am : to ol, y ou c an a ls o d o p or t s ca nn in g a nd s er vi ce v er sio n d is co ve ry . F or i ns ta nc e, th e f ol lowi ng c omn an d will r ep or t w hi ch I P- ba se d s er vi ce s a rerunning o n th e d ev ic e, a nd whic h v er sio n o f t he s er vi ce i s b e in g u se d:nmap - p o -sV Starting Nmap 4.20 ( http://insecure.org ) at 2007-01-08 11:06 CETInteresting ports on 192.168.2.1:Not shown: 1693 closed portsPORT STATE SERVICE VERSION22/tcp open ssh Dropbear sshd 0.48 (protocol 2.0)23/tcp open telnet Busybox telnetd53/tcp open domain ISC Bind dnsmasq-2.3580/tcp open http OpenWrt BusyBox httpdMAC Address: OO:13:xx:xx:xx:xx (Cisco-Linksys)Service Info: Device: WAPThe w eb s er ve r v er si on , i f i de nt if ie d, c an b e d et ermi ni ng in k no win g th e O pe ra tin g S ys tem F or in sta nc e, th e BOA w eb se rv er is ty pic al fr om d ev ic es running anopen -s ou rc e Un ix o r Un ix -l ik e .Wireless Communications F1ngerprinting

Although this meth od is n ot re ally k no wn a nd w id es pr ea d, u sin g a w ire le ss s ca nn er to d is co ve r w hic h O S y ou r r ou te r o r A cc ess P oin t ru n c an b e u se d. W e d on ot h av e a c le ar e xamp le o f h o w this c ou ld b e a ch ie ve d, b ut y ou will h av e to m on ito r ra w 8 02 .1 1 f ra rr es a nd c om pa re th em to a v er y s im ila r d ev ic e running aLinux based fi rmware .Web server security exploits

The L in ks ys WRT54G was o rig in all y h a ck ed b y u si ng a '' pi ng b ug " d is co ve re d in t he web i nt er fu ce. T his tip h as n ot b ee n f ix ed f ur mo nt hs b y L in ks ys , a llowi ngp eo ple t o e na bl e th e ''b oo t_ w ait " h el pe r p ro ce ss v ia th e w eb in te rfu ce . M a ny w eb se rv ers u se d in f irmw ar es a re o pe n s ou rc e w eb s er ve r, thus a ll ow ing t he cod eto be aud ited to find a n e xp lo it O nc e y ou k no w th e w eb se rv er v ers io n th at r un s o n y ou r d ev ic e, b y u sin g nmap -s V or so, you might be in teres ted in usinge xp lo its to r ea ch s he ll a cc es s o n y ou r d ev ic e.Nati'" TelnetlSSH access

Some f in nwa re s might h av e r es tr ic te d o r u nr es tr ic te d T el ne t/ SSH a cc es s, i fs o, try to lo g in with t he web i nt er fa ce l og in /p a ssword a nd s ee if y ou c an ty pe ins or re comnands . This is a ctu ally th e c ase fu r s orr e B ro ad com BCM9 63 xx b as ed fin nw ar es s uc h a s th e o ne in N euf1Cege te l ISP rou te rs , C lu b -I nt er ne t ISPC I- B ox a nd many o th er s. S or re c omman ds , l ik e c at might b e le ft here and b e use d to determ ine the Linux kernel vers ionAnalysing a binary firmware imageYou a re v ery lik ely to find a f ir mw are b in ary im ag e o n th e m an ufa ctu re r w eb site , e ve n if y ou r d ev ic e ru ns a p ro pr ie ta ry o pe ra tin g s ystem I f s o, y ou c an
http://insecure.org/http://insecure.org/http://insecure.org/http://insecure.org/


19/24

d own lo ad it an d u se a n h ex ad ec ima l e di to r t o f in d p r in ta bl e w o rd s s uc h a s vm li nu x, l in ux , r amd is k, mtd and o th e rs .S om e U nix to ols lik e h ex dump o r s tr in gs c an b e u se d to a na ly se th e f ir mw ar e. B elo w th er e is a n e xam ple with a b in ar y f irmwa re f utmd o th er t he I nte rn et :hexdump -C 1 less (more)00000000 46 49 52 45 32 2e 35 2e 30 00 00 00 00 00 00 00 1FIRE2 .5.0 ....... 100000010 00 00 00 00 31 2e 30 2e 30 00 00 00 00 00 00 00 1.... 1.0.0 ....... 100000020 00 00 00 00 00 00 00 38 00 43 36 29 00 Oa e6 de I....... 8.C6) ..??I00000030 54 49 44 45 92 89 54 66 If 8b 08 08 f8 10 68 42 ITIDE ..Tf. ... ?hBI00000040 02 03 72 61 6d 64 69 73 6b 00 ee 7d 09 be d5 d3 I..ramdisk.?}. ??? 100000050 da ff f3 9b f7 39 7b ef 73 f6 19 3b 53 67 ea 44 1????9{?s?;Sg?DIS c ro ll o ve r t he f irmwar e t o find p rin ta bl e w o rd s t ha t c an b e s ig ni fi ca nt .Amount ofIlas h memory

L i nux can h a rd ly fit in a 2MB f la sh d ev ic e, o nc e y ou h av e o pe ne d th e d ev ic e an d l oc a ted t he f la s h ch ip , try t o f in d its ch ar ac te r is ti cs o n t he Int er n et . I f y our f la shch ip is a 2 MB or l es s d ev ic e, y ou r d ev ic e i smo s t l ik el y t o run a p ro prie ta ry O S su ch a s W in dR iv er V xW ork s, o r a custom mana fa ct ur er OS l ik e Z y xe l Z y nOS .O p enW rt d oe s n ot c ur re nt ly run o n d ev ic es w hic h h av e 2MB o r le ss o f f la sh m emo ry . This limitationwill p ro ba bly n ot b e w or ke d around s in ce t ho s e d evi ce sare m ost of th e t ime mi cr o- ro ut er s, o r W i re le ss A c ce ss P oi nt s, w h ic h a re n ot t he main OpenWr t t ar g et .Pluging a ser ia l port

By u si ng a s er ia l p o rt an d a le ve l s h ifte r, y ou m a y r ea ch th e c on so le th at is b e in g s ho wn b y th e d ev ic e f ur d eb ug gin g o r f la sh in gpurposes. By anal ys in g t he ou tp u tof this d ev ic e, y ou c an e as il y n o ti ce ift he d ev ic e u se s a L in ux k er ne l or something different,2.3.2 Finding and using th e manufacturer SD KO nc e y ou a re s ur e y ou r d ev ic e run a L in ux b as ed f irmwa re , y ou will b e a ble to s ta rt h ac kin g o n it. I f t he m an uf ac tu re r r es pe cte d th e G PL, itwill h av e r ele as ed aS ampl e D e ve lo pment K it with t he d evi ce .GPL >iolations

Some r ra ne fa ct ur er s d o r el ea se a L in ux b as ed b in ar y f irmwar e, with n o s ou rc es a t all. The f ir st s te p b ef ur e d oi ng anything i s t o r ea d t he l ic en se c om i ng with yourd evi ce , t hen write t hern abou t this la ck o f O pe n S ou rc e c od e. I f t he r ra nu fa ctu re r a ns we rs y ou th ey d o n ot h av e to re le as e a SDK c on ta in in g O pe n S ou rc es of tw ar e, th en w e r ec omm en d y ou g et in t o uc h with t he gp l -v inl a tions.o rg comrrnmi ty.You will find b elo w a s am p le le tte r th at c an b e s en t to th e m an uf uc tu re r:

Mi s s, Mi s te r,I a m u sin g a < de vic e n am e> , an d I c anno t find n eith er o n y ou r w eb site n or o n th e CD -ROM th e o pe n s ou rc e s of tw ar e u se d to b uild o r m o dif y th e f ir mw ar e.Inc on fu rma nc e t o t he GPL li ce ns e, y ou h av e t o r el ea se t he f ul low in g s ou rc es :

c om p le te to o1 ch ain t ha t m ad e th e k er ne l an d appl ic a ti on s b e comp il ed ( g ee , b in u ti ls , l ib c ) to ols to b uild a c us to m f ir mw ar e ( mk sq ua sh fs , m kc ram lS .. .) k ern el so urce s with p atc hes to m ak e it run on this speci f ic hardware , this do es no t i nc lu d e b in a ry d r iv e rs

Thank y ou v er y m u ch in a dv an ce f ur y ou r a ns we r.B e st r eg ar ds , < y ou r n ame>

Using the SDK

O nc e th e SDK is a va ila ble , y ou a re m os t lik ely n o t to b e a ble to b uild a c om p le te o r f un ctio na l f i rmware using it, b ut p ar ts o f it, lik e o nly th e k er ne l, o r o nly th er oo t f ile sy stem Mo st m a nu fa ctu re rs d o n ot r ea lly c ar e re le as in g a to ol th at d o w or k e ve ry t ime you uocormress an d u se i t.Y o u s ho ul d a nyw ay b e a ble t o u se t he f ul low in g c ompo ne nt s:

k ern el so urc es with mo re o r l es s f un ct io na l p a tc he s f ur y ou r h ar dw a re b ina ry d riv ers link ed o r to b e lin ke d with t he s h ip p ed k e rn e l v e rs io n p ac ka ge s o f t he to o1 ch ai n u se d t o c omp il e t he w h ol e f irmwar e: g ee , b in ut il s, l ib c o r uC li bc binary tools to create a va l id f irmwa re imag e

Y ou r w ork c an b e d iv id ed into t he fu llowing tasks : c re ate a c le an p atc h o f th e h ar dw ar e s pe cif ic p ar t o f th e Iin ux ke rn el


20/24

s po t p ote nti al k er ne l GPL v io la ti on s e sp ec ia lly o n n et fi lte r an d USB sta ck stu ff m ake the b in ary drive rs w ork, until th er e a re o pe n s ou rc e d ri ve rs u se sta nd ard a GNU to o1 ch ain to m ak e w ork in g e xe cu ta ble s u nd ers ta nd an d write o pe n s ou rc e t oo ls t o g en er ate a v ali d f irmwa re ima ge

Creating a bar"""'e specific kernel patcb

Mos t o f t he tir re , th e k er ne l so urc e th at c om es a lo ng with th e SDK is n ot r ea lly c le an , an d is n ot a s ta nd ar d L in ux v er sio n, it a ls o h as a rc hi te ctu re s pe cif ic f ix esb ac kp or te d f rom t he CVS o r t he g it r ep os it or y o f th e k er ne l d ev el opmen t t re es . A nyway, s ome p ar ts c an b e e as ily is ol ate d an d used as a good start to m ake avanilla k er ne l w or k y ou r h ar dw ar e.S ome d ir ec to ri es a re v er y l ik el y t o h av e l oc al mo dif ic at io ns n ee de d t o make y ou r h ar dw ar e b e r ec og niz ed an d u sed unde r Linux. F ir st o f a ll, y ou n ee d to findout t he l inux k er ne l v er sio n t ha t i s u s ed b y y ou r h ar dw a re , this c an b e fo un d b y e ditin g th e J in ux lM a ke file f ile .head -5 linux-2.x.x/MakefileVERSION ~ 2PATCHLEVEL ~ xSUBLEVEL ~ YEXTRAVERSION ~ zNAME=A fancy nameS o n ow , y ou k no w th at y ou h av e to d ow nlo ad a s ta nd ar d k er ne l ta rb all a t k em el.o rg th at m atc he s th e v ers io n b ein g u se d b y y ou r h ard wa re .T hen you can crea te a ditI f il e b e tween t he two t re es , e sp ec ia ll y f ur t he fuDow ingd ir ec to ri es :diff -urN linux-2.x.x/arch/ linux-2.xox-modified/arch/ > Ol-architecture.patchdiff -urN linux-2.x.x/include/ linux-2.x.x-modified/include > 02-includes.patchdiff -urN linux-2.x.x/drivers/ linux-2.x.x-modified/drivers > 03-drivers.patchThis will c on st it ut e a b as ic s et o f th re e p atc he s t ha t a re v er y li ke ly to c on ta in any n ee de d m od ific atio ns th at h as b ee n m ad e to th e sto ck Lin ux k ern el to r un o ny ou r sp ec ific d ev ic e. O f c ou rse , th e c on te nt p ro du ce d b y th e ditI -urN m ay no t a lw ays be rele vant, so th at you hav e to clean up those p atc hes to on ly le t t he'mist h av e" c od e in to t hemThe f ir st p a tch will c on ta in a ll t he c od e th at is n ee de d b y th e b oa rd to b e in itia liz ed a t sta rtu p, a s w ell a s p ro ce ss or d ete ctio n an d o th er b oo t tim: specific fixes.T he s ec on d p at ch will cont ai n a ll u s e fu l d ef in it io n s f ur t ha t b oa rd : addr es se s, k er ne l granularity, redefini tions, processor fa m ily a nd f ea tu re s . ..T he th ir d p atc h m ay c on ta in d riv er s f ur: s eria l c on so le , e th er ne t N IC , w ire le ss N IC , U SB N IC ... M o st o f t he tim: this p a tch cont ai ns no th in g e ls e t han "glue"c od e th at h as b ee n a dd ed to m ak e th e b in ary d riv er w ork with t he L i nux k e rn e l This code m i gh t n ot b e u se fu l ify ou p la n o n writ ing d ri ve rs f rom s cr atc h f ur thishardware.Using the device bootloader

The b oo tlo ad er i s t h e f ir st p r og ram th at is s ta rte d right a fte r y ou r d ev ic e h as b ee n p ow er ed o n This p ro gr am , c an b e m or e o r le ss so ph istic ate d, s om e d o le ty ou d o n etw or k b oo tin g, U SB m ass sto ra ge b oo tin g ... T he b oo tlo ad er is d ev ic e an d a rc hit ec tu re s pe ci fi c, s ome b oo tl oa de rs w er e d es ig ne d t o b e u ni ve rs al s uc has R ed Boot or U - B oot so that yo u ca n m eet tho se loa ders on totally different platfurms an d e xp ec t th em to b eh av e th e same w ay .I f y o ur d ev ic e r un s a p ro pr ie ta ry o pe ra ti ng s ys tem , y ou a re v er y li ke ly to d ea l with a p ro prie ta ry b oo t lo ad er a s w eD . This may n ot a lw a ys b e a l im ita ti on , s omep ro pr ie ta ry b oo tlo ad er s c an e ve n h av e s ou rc e c od e a va il ab le ( i. e : B r oa dc om CFE) .A cc or di ng t o t he b oo tlo ad er f ea tu re s, b ac kin g o n t he d ev ic e will b e m ore o r le ss e asie r. I t is v ery p ro ba ble th at th e b oo tlo ad er, e ve n e xo tic an d rare, has adocumen ta ti on s omewhe re ov er t he I nt er ne t. In o rde r to kn ow w hat will be poss ib le with your boot loader an d th e w ay y ou a re g oin g to h ac k th e d ev ic e, lo oko ve r t he f uD ow in g f ea tu re s :

d oe s th e b oo tlo ad er a llo w n et b oo tin g vi a b oo tp IDHCP /N FS o r tftp does the bootlo ader a cce pt loa ding E LF bina ries ? d oe s t he b oo tlo ad er h av e a k er neV fi rmwar e s iz e li mit at io n? does the bootloader expect a firmware f orma t to b e l oa de d with ? are the loaded files e xecuted from R AM or flash ?

N et b oo tin g is s ome th in g v er y c on ve ni en t, b ec au se y ou will o nl y h a ve to s et u p n et wo rk b oo ti ng s er ve rs o n y ou r d ev el opmen t s ta tio n, an d k ee p t he o rig in alf irmwa re o n th e d ev ic e till y ou a re su re y ou c an re pla ce it. This a ls o p re ve nt s y ou r d ev ic e f rom b ei ng f la sh ed , an d po ten ti a lly b r icked every tim: y ou w an t to te sta mod if ica tion on the kerneVfil esys temIf y ou r d ev ic e n ee ds to b e f la sh ed e ve ry tim: y ou l oa d a f irmwar e, th e b oo tl ad er m i gh t o nly a cc ep t a sp ec ific firmw ar e f urr na t to b e lo ad ed , so th at y ou will haveto u nd er sta nd t he f irmwar e f ur rn at a s w eD .Making binary dri",rs _rkAs we h av e e xp la in ed b ef or e, m a nu fu ct ur er s d o r ele as e b in ar y d ri ve rs i n t he ir GPL tarball When t ho se d riv er s a re s ta ti ca lly l in ke d i nt o t he k er ne l, t he y b ec ome


21/24

GPL as well , fu rtu na te ly o r tm fu rtu na te ly , m os t o f th e d riv ers a re n ot s ta ti ca lly lin ke d. T h i s anyw ay lets you a chance to dynam ically link the driver with th ec ur re nt k er ne l v er si on , and try to m ake them w ork together.T h i s is one of the m ost tricky and grey part of the fully o pe n so urc e proje cts. S om e drive rs re quire few m od if ic atio ns to b e w ork in g with y ou r c us to m k er ne l,be ca use th ey w orke d with a n e ar li er k er ne l, and few m odific ation s ha ve be en m ad e to the ke rne l in -b etw een th os e v ers ion s. T h i s is fur insta nc e the c ase with th ebinary driver of the B roadcom B CM 43xx W ireless C hip sets, w here only few differences w ere m ade to the netw ork in terface structures.Som e general princip les can be applied no m atter w hich kernel version is used in order to m ake binary drivers w ork with y ou r c us to m k er ne l:

turn o n ke rne l d ebu gg ing fea tu re s suc h a s:o CONFIG DEBUG KERNEL_o CONFIG DETECT SOFTLOCKUP_o CONFIG DEBUG KOBJECT_o CONFIG KALLSYM So CONFIG_KALLSYMS_ALL

link binary drivers w hen possib le to the current kernel version try to loa d th ose b ina ry drive rs catch the lockups and u nd er sta nd th em

M ost of the time, l oa di ng b in ar y d ri ve rs will fail, and generate a kernel oops. Y ou can know the last sym bol the binary drivers attempted to use, and see in thek e rn e l h e ad e rs file, ifyou do not have to m ove som e structures field before or after that sym bol in order to keep com patibily with both the binary driver and thes to ck k ern el d riv er s.Understanding the firmware format

Yo u might want to un de rs ta nd the firmware f or ma t, e ve n ifyou are not yet capable of running a custom firm ware on your device, because t hi s i s so me tim es ab lo ck in g p art o f t he f la sh in g p ro ce ss .A f innware forrrat is m ost of the time com posed of the fol lowing fields:

header, contain ing a f innware ve rsio n a nd a dditio na l fie ld s: V end or, H ardw are ve rsion ... CRC32 checksum on either the whole file or just part o fit B inary and/or com pressed kernel im age B inary and/or com pressed root filesystem im age po te ntia l g arb age

O nce you have figured out how the firm ware forrrat is p ar ti ti on ed , y ou will have to write your ow n tool that produces valid f innware b in ar ie s. O n e thing to bevery c ar ef ul h er e is the endianness of either the m achine that produces the b inary firm ware and the device that will b e fl as he d u sin g this b in a ry f irmwar e .Writ ing a f lash map driwr

The flash map driver has an important ro le in m aking your custom firmw are w ork because it is re sp on sib le of m ap pin g th e c orre ct flas h re gion s and associatedrights to s pe cific pa rts o f the s yste m su ch a s: bo otloa de r, k ern el, us er file sy ste mW riting yo ur o wn fla sh m ap d riv er is not really a bard task once you know how your firm ware image and flash is s tru ctu re d. Y ou will f ind b elow a c om men te dexam ple that covers the case of the device w here the bootloader can pass to the kernel its partition plan .F irs t o f all, you need to m ake your flash m ap driver be visible in the kernel configuration options, this can be done by editing the filelinux/drivers/mtdlmapslKconfig:config MTD_DEVICE_FLASH

tristate "Device Flash device"depends on ARCHITECTURE && DEVICEhelpFlash memory access on DEVICE boards. Currently only works withBootloader Foa and Bootloader Bar.

Then add your source file to the linux/drivers/m td lmapslM akefIle, so that it will be c om piled a lon g with t he k er ne lobj-\$(CONFIG_MTD_DEVICE_FLASH) += device-flash.oYou can then write the kernel driver itself; by creating a Iinuxldrivers/m tdlm aps/device-flash .c C source file.// Includes that are required for the flash map driver to know of the prototypes:#include #include #include #include #include #include


22/24

*inc~ude I I Put some flash map definitions here:#define WINDOW ADDR OxlFCOOOOO 1* Real address of the flash *1#define WINDOW SIZE Ox400000 1* Size of flash *1#define BUSWIDTH 2 1* Buswidth *1static void exit device_mtd_cleanup(void);static struct mtd info *device_mtd_info;static struct map_info devicd_map = {.name = "device",

.size = WINDOW_SIZE,

.bankwidth ~ BUSWIDTH,

.phys ~ WINDOW_ADDR,);

static int init device_mtd_init(void)I I Display that we found a flash map device

printk("device: Ox\%08x at Ox\%08x\n", WINDOW_SIZE, WINDOW_ADDR);I I Remap the device address to a kernel address

device_map.virt = ioremap(WINDOW_ADDR, WINDOW_SIZE);I I If impossible to remap, exit with the EIO errorif (!device_map.virt) {printk("device: Failed to ioremap\n");

return -EIO;

I I Initialize the device mapsimple_map init(&device_map);

1* MTD informations are closely linked to the flash map deviceyou might also use "jedec probe" "amd probe" or "intel_probe" *1device mtd info do_map_probe("cfi_probe", &device_map);

if (device_mtd_info)device mtd info->owner THIS_MODULE;int parsed_nr_parts = 0;I I We try here to use the partition schema provided by the boot loader specific code

if (parsed_nr_parts ~~ 0) {int ret = parse_bootloader_partitions(device_mtd_info, &parsed_parts, 0);if (ret> 0) {part_type = "BootLoader";

parsed_nr_parts = ret;

add_mtd_partitions(devicd_mtd_info, parsed_parts, parsed_nr_parts);return 0;

iounmap(device_map.virt);return -ENXIO;

I I This function will make the driver clean up the MTD device mappingstatic void exit device_mtd_cleanup(void)

I I If we found a MTD device beforeif (device_mtd_info) {

I I Delete every partitionsdel_mtd_partitions(device mtd info);I I Delete the associated map

map_destroy(device_mtd_info);

I I If the virtual address is already in useif (device map.virt) {

I I Unmap the physical address to a kernel space addressiounmap(device_map.virt);

I I Reset the structure fielddevice_map.virt = 0;


23/24

II Macros that indicate which function is called on loadinglunloading the modulemodule_init(device_mtd_init);module_exit(device_mtd_cleanup);

II Macros defining license and author, parameters can be defined here too.MODULE_LICENSE("GPL");MODULE_AUTHOR("Me, myself and I


24/24

It is important to do a ll t he s e s tep s r epea ted ly : listen to wh at o th er p eo pl e th in k. talk e xp la in in g wh at p ro bl em y ou a re a dd re ss in g a nd y ou r p ro po se d s ol uti on do write useful patches including documentation test. test. test.

2.6.2 Where to listen and talk google to f ind things related to your p roblem M a ilin g l is ts: http://1ists.openwrt.org/ W iki: check the w iki: http://wikiopenwrt.orglOpenWrtDocs Fo rum: h tt p: // fu ru rn openwr to rg / IRC: irc. freenode. net, channels #openwrt ao d #openwrt-devel TRAC: h tt ps :/ /d ev.op enw r t. or g/ t he i ss ue /b ug/ ch ang e t ra cki ng s ys tem

It is o fte n b es t to d oc um en t w ha t y ou a re d oin g b ef ur e y ou d o it. The p ro ce ss o f d oc ument at io n o ft en e xp os es p os si ble imp ro vemen ts . K e ep y ou rdo cument at io n up to date.2.6.3 Pateh Submission Process

I. Use gi t o r s vn to c re at e a p at ch . C re at in g p at ch es manual ly with diff -urN a ls o w o rk s, b ut is usual ly unnecessary.2. Send a mail to [email protected] the fu llowing con ten ts :

a. [PATCH] in th e S ub je ct , f ul low ed b y:b . ( op ti on al) a l on ge r d es cr ip ti on o f y ou r p at ch in th e me ss ag e b od yC. Signed-off-by: Your name d . Y ou r a ctu al p atc h, inline, n ot w o rd w ra pp ed o r w h it es pa ce r na ng 1e d.

3 . P lea se re ad http://keme1trap.org/Linux/Email Clients ao d Patches to find o ut h ow to m ak e su re y ou r ema il c lie nt d oe sn 't d es tr oy y ou r p atc h.4 . P le as e u se y ou r r ea l n am e a nd ema il a dd re ss in the Signed-off-by l in e , f u l low ing t he s ame gu id e li ne s a s in t he L in uxK eme lp at ch s ubm is sio n

guidelines5 . E xampl e o f a p ro pe rl y f urmatt ed p atc h s ubm is sio n:

http://1ists.openwrt.org/pipermail/openwrt-deveV2007-November/OOI334.html
http://1ists.openwrt.org/http://wikiopenwrt.orglopenwrtdocs/mailto:[email protected]://keme1trap.org/Linux/Emailhttp://1ists.openwrt.org/pipermail/openwrt-deveV2007-November/OOI334.htmlhttp://1ists.openwrt.org/pipermail/openwrt-deveV2007-November/OOI334.htmlhttp://keme1trap.org/Linux/Emailmailto:[email protected]://wikiopenwrt.orglopenwrtdocs/http://1ists.openwrt.org/

Documents

Kamikaze.openwrt.org Docs Openwrt