Memory Management: What Every Driver Writer Needs To Know: February 28, 2005

Memory Management: What Every Driver Writer Needs to Know
February 28, 2005
Abstract his !a!er !rovides in"ormation about a##o$ating and using memory in %erne#&mode drivers "or the Mi$roso"t' Windows' "ami#y o" o!erating systems( )t des$ribes the ty!es o" memory that are avai#ab#e "or driver use, the a!!ro!riate te$hni*ues "or a##o$ating and using ea$h ty!e, and the best ways to test "or memory&re#ated !rob#ems( his in"ormation a!!#ies "or the "o##owing o!erating systems: Mi$roso"t Windows +ista, Mi$roso"t Windows -erver, 200. Mi$roso"t Windows /0 Mi$roso"t Windows 2000 he $urrent version o" this !a!er is maintained on the Web at: htt!:11www(mi$roso"t($om1whd$1driver1%erne#1mem&mgmt(ms!2 3e"eren$es and resour$es dis$ussed here are #isted at the end o" this !a!er( Contents
)ntrodu$tion (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( . 4 +irtua# and 0hysi$a# Memory((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((. 2 +irtua# 5ddress -!a$e((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((6 . 0hysi$a# 5ddress -!a$e(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((8 6 Memory Des$ri!tor 7ists(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((44 5 0oo# Memory((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( 46 8 Kerne# -ta$%(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( 48 9 Memory 5##o$ation e$hni*ues(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((4: 8 5$$essing Devi$e 3egisters(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((26 : 5$$essing Memory "or )1; <u""ers((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((29 40 Ma!!ing Devi$e Memory and 3egisters into =ser -!a$e((((((((((((((((((((((((((((((((((((((((((((((((.0 44 -hared Memory and -yn$hroni>ation(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((.4 42 esting and roub#eshooting((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((.4 4. -ummary o" ?uide#ines(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((.. 46 3esour$es((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((( .6
Memory Management: What Every Driver Writer Needs to Know - 2
Disclaimer
his is a !re#iminary do$ument and may be $hanged substantia##y !rior to "ina# $ommer$ia# re#ease o" the so"tware des$ribed herein( he in"ormation $ontained in this do$ument re!resents the $urrent view o" Mi$roso"t @or!oration on the issues dis$ussed as o" the date o" !ub#i$ation( <e$ause Mi$roso"t must res!ond to $hanging mar%et $onditions, it shou#d not be inter!reted to be a $ommitment on the !art o" Mi$roso"t, and Mi$roso"t $annot guarantee the a$$ura$y o" any in"ormation !resented a"ter the date o" !ub#i$ation( his White 0a!er is "or in"ormationa# !ur!oses on#y( M)@3;-;F M5KE- N; W5335N )E-, E/03E--, )M07)ED ;3 - 5 = ;3A, 5- ; BE )NF;3M5 );N )N B)- D;@=MEN ( @om!#ying with a## a!!#i$ab#e $o!yright #aws is the res!onsibi#ity o" the user( Without #imiting the rights under $o!yright, no !art o" this do$ument may be re!rodu$ed, stored in or introdu$ed into a retrieva# system, or transmitted in any "orm or by any means Ce#e$troni$, me$hani$a#, !hoto$o!ying, re$ording, or otherwiseD, or "or any !ur!ose, without the e2!ress written !ermission o" Mi$roso"t @or!oration( Mi$roso"t may have !atents, !atent a!!#i$ations, trademar%s, $o!yrights, or other inte##e$tua# !ro!erty rights $overing subEe$t matter in this do$ument( E2$e!t as e2!ress#y !rovided in any written #i$ense agreement "rom Mi$roso"t, the "urnishing o" this do$ument does not give you any #i$ense to these !atents, trademar%s, $o!yrights, or other inte##e$tua# !ro!erty( =n#ess otherwise noted, the e2am!#e $om!anies, organi>ations, !rodu$ts, domain names, e&mai# addresses, #ogos, !eo!#e, !#a$es and events de!i$ted herein are "i$titious, and no asso$iation with any rea# $om!any, organi>ation, !rodu$t, domain name, emai# address, #ogo, !erson, !#a$e or event is intended or shou#d be in"erred( F 2005 Mi$roso"t @or!oration( 5## rights reserved( Mi$roso"t, Windows, and Windows -erver are either registered trademar%s or trademar%s o" Mi$roso"t @or!oration in the =nited -tates and1or other $ountries( he names o" a$tua# $om!anies and !rodu$ts mentioned herein may be the trademar%s o" their res!e$tive owners(
February 28, 2005
ntrod!ction
Kerne#&mode drivers a##o$ate memory "or various !ur!oses, su$h as storing interna# data or using as )1; bu""ers( o he#! driver writers use memory $orre$t#y, this !a!er e2!#ains the "o##owing: Fundamenta# in"ormation about !hysi$a# and virtua# memory and address s!a$es( y!es o" memory that are avai#ab#e to drivers and when to use ea$h ty!e( e$hni*ues "or a##o$ating memory to satis"y a driverGs diverse re*uirements(
e$hni*ues "or a$$essing memory a##o$ated by other $om!onents "or )1; o!erations( e$hni*ues "or sharing memory with other %erne#&mode and user&mode $om!onents( e$hni*ues "or testing and troub#eshooting memory a##o$ation and usage !rob#ems(
Note:
his !a!er does not $over memory a##o$ation "or dire$t memory a$$ess CDM5D( Aou $an "ind detai#ed in"ormation about a## as!e$ts o" DM5 in HDM5 -u!!ort in Windows Drivers,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er(
" #irt!al and $hysical Memory

he amount o" virtua# and !hysi$a# memory that is su!!orted on any $om!uter that runs the Mi$roso"t' Windows' o!erating system is determined by the hardware $on"iguration and the edition o" Windows in use( ;n .2&bit hardware, the virtua# address s!a$e is 6 ?< and the ma2imum amount o" !hysi$a# memory ranges "rom 6 to428 ?<( ;n 86&bit hardware, the virtua# address s!a$e is 48 terabytes and the ma2imum amount o" memory ranges "rom 86 ?< to 4 terabyte( ab#e 4 #ists the amount o" virtua# memory and the ma2imum amount o" !hysi$a# memory that ea$h edition o" Windows su!!orts( %able "& #irt!al and $hysical Memory '!((ort in Windows ;!erating system Edition +irtua# Ma2imum !hysi$a# version memory memory Mi$roso"t Windows -tandard 6 ?< 6 ?< -erver, 200. -0 4 Web 6 ?< 2 ?< Enter!rise 6 ?< 86 ?<, i" hardware su!!orts 0hysi$a# 5ddress E2tension C05ED Enter!rise C86& 48 4 terabyte bitD terabytes Data$enter 6 ?< 428 ?<, i" hardware su!!orts 05E Data$enter C86& 48 4 terabyte bitD terabytes
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - )
;!erating system version Windows -erver 200.
Edition -tandard Web Enter!rise Enter!rise C86& bitD Data$enter Data$enter C86& bitD Bome 0ro"essiona# 86&bit Edition +ersion 200. 0ro"essiona# -erver 5dvan$ed -erver Data$enter -erver
+irtua# memory 6 ?< 6 ?< 6 ?< 48 terabytes 6 ?< 48 terabytes 6 ?< 6 ?< 48 terabytes 6 ?< 6 ?< 6 ?< 6 ?<
Ma2imum !hysi$a# memory 6 ?< 2 ?< .2 ?<, i" hardware su!!orts 05E 86 ?< 428 ?<, i" hardware su!!orts 05E 542 ?< 6 ?< 6 ?< 428 ?< 6 ?< 6 ?< 8 ?< .2 ?<, i" hardware su!!orts 05E
Windows /0
Windows 2000
2 #irt!al Address '(ace

5 virtua# address identi"ies a #o$ation in virtua# memory( he virtua# address s!a$e is divided into two ranges: user s!a$e and system s!a$e( User space is the !ortion o" the virtua# address s!a$e into whi$h Windows ma!s user&mode !ro$esses, !er&!ro$ess data, and user&mode dynami$ #in% #ibraries CD77sD( Ea$h !ro$ess has its own $onte2t, that is, the $ode and data that the !ro$ess uses( Whi#e the !ro$ess is running, a !ortion o" the $onte2t, $a##ed the wor%ing set, is resident in memory( System space, a#so $a##ed kernel space, is the !ortion o" the address s!a$e in whi$h the o!erating system and %erne#&mode drivers are resident( )t is a$$essib#e on#y to %erne#&mode $ode( he distin$tion between user s!a$e and system s!a$e is im!ortant in maintaining system se$urity( 5 user&mode thread $an a$$ess data on#y in the $onte2t o" its own !ro$ess( )t $annot a$$ess data within other !ro$ess $onte2ts or within the system address s!a$e( his restri$tion !revents user&mode threads "rom reading and writing data that be#ongs to other !ro$esses or to the o!erating system and drivers, whi$h $ou#d resu#t in se$urity vu#nerabi#ities and !ossib#y even a system $rash( Kerne#&mode drivers are trusted by the o!erating system and $onse*uent#y $an a$$ess both user s!a$e and system s!a$e( When a driver routine is $a##ed in the $onte2t o" a user thread, a## o" the threadGs data remains in the user&mode address s!a$e( he driver $an a$$ess the user&s!a$e data "or the threadJi" it ta%es the ne$essary se$urity !re$autionsJin addition to a$$essing system&s!a$e data( he user&mode thread, however, does not have a$$ess to the system&s!a$e data o" the driver( he si>es o" the system and user address s!a$es de!end on whether the hardware is .2&bit or 86&bit and on the o!tions a!!#ied to <oot(ini(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - *
2&"
#irt!al Address '(ace on 32-bit +ardware
;n .2&bit ma$hines, the #ower 2 ?< o" the virtua# address s!a$e is user s!a$e and the u!!er 2 ?< is reserved as system s!a$e by de"au#t( )" user&mode a!!#i$ations re*uire additiona# virtua# address s!a$e, an administrator $an reserve . ?< "or user s!a$e, thus #eaving on#y 4 ?< o" system s!a$e, by a!!#ying the 1.?< swit$h to <oot(ini and then restarting the ma$hine( his swit$h is a#so use"u# during testing to see how a driver !er"orms with #imited system address s!a$e( he swit$h is su!!orted on Windows -erver 200. Ca## editionsD, Windows /0 Ca## versionsD, Windows 2000 5dvan$ed -erver, and Windows 2000 Data$enter -erver( Figure 4 shows how the virtua# address s!a$e is organi>ed on .2&bit systems( C he "igure is not drawn to s$a#e(D
,ig!re "& -ayo!t o. virt!al address s(ace on 32-bit systems
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - /
5s the "igure shows, the user address s!a$e o$$u!ies the #ower range o" the virtua# address s!a$e and the system address s!a$e o$$u!ies the u!!er range( <y de"au#t, both user and system s!a$e are 2 ?<( When Windows is started with the 1 .?< swit$h, the si>e o" the user s!a$e in$reases to . ?<( he remaining 4 ?< o" virtua# address s!a$e $ontains the system address s!a$e( he !ro$ess !age tab#es and hy!ers!a$e remain at the same addresses, but other $om!onents do not( When the system address s!a$e is #imited to 4 ?<, the ma2imum si>es o" the !aged and non!aged !oo#s are redu$ed and #ess s!a$e is avai#ab#e "or system !age tab#e entries C0 EsD and the "i#e system $a$he as we##( he "i#e system $a$he, whi$h is im!#emented in so"tware, is not the same as the !ro$essor $a$he, whi$h is im!#emented in hardware( Kee! in mind, however, that this #imit a!!#ies on#y to the amount o" the $a$he that is visib#e at any given time( he system uses a## the !hysi$a# memory in the ma$hine "or $a$hing( he e2a$t si>es o" the !aged and non!aged !oo#s, 0 Es, and "i#e system $a$he vary wide#y "rom re#ease to re#ease( ;n the )nte# 0entium 0ro and #ater !ro$essors, whi$h su!!ort 05E, Windows $an su!!ort u! to 428 ?< o" !hysi$a# memory( 05E !rovides on#y additiona# !hysi$a# memory and does not in$rease the si>e o" the virtua# address s!a$e( When 05E is enab#ed, the virtua# address s!a$e remains un$hanged at 6 ?< and the #ayout o" the 2&?< system s!a$e is #arge#y un$hanged( ;!erating system su!!ort "or 05E is !rovided by a s!e$ia# version o" the Windows %erne#, whi$h is named Nt%rn#!a(e2e Csing#e&!ro$essor versionD or Nt%r!am!(e2e Cmu#ti&!ro$essor versionD( )n this version o" the %erne#, 0 Es and !age dire$tory entries Cwhi$h are invo#ved in ma!!ing virtua# memory to !hysi$a# memoryD are 86 bits wide( )" the a!!ro!riate devi$e and driver su!!ort is !resent, the 05E %erne#s su!!ort dire$t )1; "or the entire !hysi$a# address s!a$e Cin$#uding any !hysi$a# memory above 6 ?<D(
2&2
#irt!al Address '(ace on /)-bit +ardware
;n 86&bit ma$hines, the virtua# address s!a$e is 48 terabytes, with 8 terabytes o" user s!a$e and another 8 terabytes o" system s!a$e( he #ayout is simi#ar to that "or .2&bit Windows, e2$e!t that the si>es are !ro!ortionate#y #arger( 5s with .2&bit hardware, the si>es vary "rom re#ease to re#ease( @urrent#y, Windows runs on two 86&bit ar$hite$tures: )nte# )tanium and 286, whi$h in$#udes the 5MD86 and the )nte# E2tended Memory 86 e$hno#ogy( ;n 288 and 286 hardware, the !age si>e is 6 K<( ;n )tanium hardware, the !age si>e is 8 K<( 0ointers on both )tanium and 286 ar$hite$tures are 86 bits #ong(
2&3 Addressing
%y(es0 Constants0 and Macros 1sed in
<e$ause o" the di""eren$es between the 288, 286, and )tanium ar$hite$tures, drivers shou#d not use hard&$oded va#ues or ma%e assum!tions about the !age si>e, !ointer si>e, or address ranges o" the hardware( For e2am!#e, on 86&bit hardware, a virtua# address in whi$h the highest&order bit is set is not ne$essari#y a system& s!a$e address( C he same is true "or .2&bit hardware when Windows is started with the 1.?< swit$h(D )nstead, driver $ode shou#d a#ways use the a!!ro!riate $onstants, ty!es, and ma$ros, whi$h are de"ined in Wdm(h and Ntdd%(h( hese in$#ude the "o##owing:
February 28, 2005
@onstant, ty!e, or ma$ro 0+;)D Cor other data&s!e$i"i$ !ointer ty!eD 0BA-)@57K5DD3E -05?EK-)LE <A E-K ;K05?Ema$ro =7;N?K0 3 0+;)D86
=sage +irtua# addresses
0hysi$a# addresses Number o" bytes in a !age on the $urrent hardware Cused in memory a##o$ationD Number o" !ages re*uired to ho#d the in!ut number o" bytes on the $urrent hardware +ariab#es that might ho#d either an address or data o" a s$a#ar ty!e 0ointers on )tanium and 286 hardware on#yM does not return va#id in"ormation on 288 hardware
@ode that uses these ma$ros and ty!es $an de!end on Windows to do the right thing, regard#ess o" the under#ying hardware !#at"orm( Most drivers run on 05E systems without modi"i$ation( For 05E $om!atibi#ity, drivers that !er"orm DM5 must use the systemGs DM5 routines to ensure that address si>e issues are hand#ed $orre$t#y( )n addition, drivers shou#d not use =7;N?, 0+;)D, or 0+;)D86 "or !hysi$a# addresses( ;n 05E systems, the =7;N? and 0+;)D ty!es are on#y .2 bits #ong and there"ore $annot store !hysi$a# addresses above 6 ?<( he 0+;)D86 ty!e does not return va#id in"ormation on the 288 ar$hite$ture( )nstead o" using =7;N?, 0+;)D, or 0+;)D86, drivers shou#d use =7;N?K0 3( 5dditiona# #imitations a!!#y "or $ertain devi$e ty!es( For "urther detai#s, see the Windows DDK, whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er(
2&)
Ma((ing #irt!al Memory to $hysical Memory
his se$tion !rovides a brie" overview o" how the Windows memory manager ma!s !ages in virtua# memory to !ages in !hysi$a# memory( 5 genera# understanding o" this ma!!ing is he#!"u# in writing a driver, but you do not need to understand the detai#s( For a more detai#ed e2!#anation, see Inside Windows 2000, whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er( Every !age in virtua# memory is #isted in a !age tab#e, whi$h in turn identi"ies the $orres!onding !hysi$a# !age( he system and @0= use in"ormation "rom the virtua# address to "ind the $orre$t entry in the !age tab#e "or a s!e$i"i$ !age( Figure 2 shows how the memory manager ma!s virtua# memory to !hysi$a# memory( )n the "igure, a virtua# address !oints to a s!e$i"i$ #o$ation on a virtua# !age( he virtua# address $ontains a byte o""set and severa# inde2 va#ues that the system and the @0= use to #o$ate the !age tab#e entry that ma!s the virtua# !age into !hysi$a# memory( 5"ter the memory manager "inds the !age tab#e entry, it uses the o""set to "ind a byte in !hysi$a# memory, whi$h is identi"ied by a !hysi$a# address(
February 28, 2005
,ig!re 2& Ma((ing #irt!al to $hysical Memory
he #ength and #ayout o" a virtua# address de!end on the hardware( +irtua# addresses on 288 hardware are .2 bits #ong and $ontain two !age&tab#e inde2es: one is an inde2 into a !age dire$tory, whi$h identi"ies the !age tab#e that ma!s the virtua# address, and the other inde2 identi"ies the !age tab#e itse#"( )n 05E mode, the address $ontains a third inde2 that is 2 bits wide( +irtua# addresses are 68 bits #ong on 286 hardware and 6. bits #ong on )tanium hardware, and the number o" inde2es is a#so di""erent( Bowever, on a## 86&bit hardware, Windows stores and mani!u#ates virtua# addresses as 86&bit va#ues( Drivers must not re#y on the 6.&bit and 68&bit interna# address #engths C"or e2am!#e, by attem!ting to en$ode additiona# in"ormation in !ointersD be$ause Mi$roso"t might $hange these va#ues at any time(
3 $hysical Address '(ace

he !hysi$a# address s!a$e en$om!asses the set o" addresses that !hysi$a# memory $an o$$u!y( he ma2imum si>e o" the !hysi$a# address s!a$e is determined by the number o" bits o" !hysi$a# address that the @0= and $hi!set $an de$ode( his si>e a#so estab#ishes the theoreti$a# ma2imum amount o" !hysi$a# memory C35MD on the system( 5s hardware has evo#ved, the number o" address bits has in$reased, #eading to #arger !hysi$a# address s!a$es and !otentia##y greater amounts o" 35M( @urrent 288 @0=s use .2, .8, or 60 bits "or !hysi$a# addresses in the modes that Windows su!!orts, a#though the $hi!sets that are atta$hed to some 60&bit !ro$essors #imit the si>es to "ewer bits( @urrent re#eases o" .2&bit Windows su!!ort a ma2imum o" .9 bits o" !hysi$a# address "or use as genera#&!ur!ose 35M Cmore may be used "or )1; s!a$e 35MD, "or a ma2imum !hysi$a# address s!a$e o" 428 ?<( C hese va#ues may in$rease in the "uture(D Windows a#so $ontinues to su!!ort o#der !ro$essors that
February 28, 2005
de$ode on#y .2 bits o" !hysi$a# address Cand thus $an address a ma2imum o" 6 ?<D( 5 !ro$essor that uses "u## 86&bit virtua# addresses $an theoreti$a##y address 48 e2abytes( C5n e2abyte is a bi##ion gigabytes, and a terabyte is a thousand gigabytes(D @urrent re#eases o" 86&bit Windows su!!ort "rom 60 to 50 address bits and 428 ?< to 4 terabyte o" 35M, de!ending on the s!e$i"i$ edition o" the o!erating system( he number o" bits that are su!!orted in !hysi$a# addresses is im!ortant to driver writers be$ause it estab#ishes the range o" destination addresses "or DM5( @urrent#y, drivers must be ab#e to hand#e )1; trans"ers that use .9&bit !hysi$a# addresses, and this number $ou#d in$rease in the "uture( For drivers that use the Windows DM5 routines instead o" the obso#ete hardware abstra$tion #ayer CB57D routines, in$reased address #engths are not a !rob#em even i" the devi$e hardware su!!orts on#y .2 address bits be$ause the DM5 routines !er"orm any doub#e& bu""ering that might be re*uired to hand#e the addressing di""eren$es( -ome o#der drivers, however, do not use the Windows DM5 routines( )" su$h a driver assumes that its devi$e wi## never be re*uired to !er"orm )1; to an address greater than 6 ?<, it is #i%e#y to "ai# on some newer 288 !#at"orms on whi$h !hysi$a# addresses $an e2tend u! to 428 ?<( hese drivers shou#d be revised to use the Windows DM5 routines( he !hysi$a# address s!a$e is used to address more than Eust 35M( )t is a#so used to address a## o" the memory and some o" the registers !resented by devi$es( @onse*uent#y, i" a ma$hine is $on"igured with the ma2imum amount o" !hysi$a# memory, some o" that memory wi## be unusab#e be$ause some o" the !hysi$a# address s!a$e is ma!!ed "or other uses( Devi$e memory and registers are ma!!ed into the !hysi$a# address s!a$e at address ranges that the $hi!set $ontro#s( Memory #o$ations are read and written through 7;5D and - ;3E instru$tionsM in the 288 assemb#y #anguage, #oad and store are im!#emented through the M;+ instru$tion( 5#though some devi$e registers are ma!!ed into the !hysi$a# address s!a$e, others are )1; s!a$e instead, de!ending on the design o" the devi$e hardware and the $hi!set in the individua# ma$hine( )1; s!a$e is a ho#dover "rom the ear#y days o" mi$ro!ro$essors when memory was a #imited resour$e and "ew devi$es had their own addressab#e memory( @reating a se!arate, #imited address s!a$e through whi$h to address devi$e registers saved im!ortant main memory s!a$e "or the o!erating system and a!!#i$ations( ;n the hardware !#at"orms that Windows $urrent#y su!!orts, )1; s!a$e is im!#emented as a se!arate 86&K< !hysi$a# address s!a$e( 7o$ations in )1; s!a$e are read and written through )N and ;= instru$tions( he addresses that are used to identi"y #o$ations in a !hysi$a# address s!a$e are o"ten $a##ed physical addresses( Bowever, this term $an sometimes be $on"using be$ause not a## !hysi$a# addresses are a#i%eJevery !hysi$a# address identi"ies a #o$ation re#ative to the bus on whi$h it is !#a$ed( he "o##owing terms more !re$ise#y des$ribe the !hysi$a# addresses: 0ro$essor&re#ative !hysi$a# addresses Devi$e&bus re#ative !hysi$a# addresses
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - "5
=nderstanding whi$h ty!e o" !hysi$a# address ea$h $om!onent uses $an he#! you ensure that your driver uses the $orre$t ty!e o" address "or ea$h $onte2t( Figure . shows the ty!es o" addresses used by various system $om!onents( )n the "igure: he #ight gray area at the to! shows the virtua# address s!a$e(
he unshaded area shows the o!erating system and drivers, whi$h $an use either virtua# addresses or !hysi$a# addresses, de!ending on the situation( he dar%er gray areas at the bottom show $om!onents that use !hysi$a# addresses( he $om!onents in the #ighter area use !ro$essor&re#ative !hysi$a# addresses, and those in the dar%er area use devi$e bus&re#ative !hysi$a# addresses(
,ig!re 3& $hysical addresses
he "o##owing se$tions des$ribe !ro$essor&re#ative and devi$e&bus&re#ative !hysi$a# address in more detai#(
3&"
$rocessor-6elative $hysical Addresses
5 !ro$essor&re#ative !hysi$a# address is an address that the @0= !#a$es on the @0= bus( his address identi"ies a #o$ation in the !hysi$a# memory s!a$e, whi$h
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - ""
$ontains a## addresses that $an be the target o" a M;+ instru$tion( When the memory manager and the @0= trans#ate a virtua# address to a !hysi$a# address, the resu#t is a !ro$essor&re#ative !hysi$a# address( 5"ter the @0= issues an instru$tion with a !ro$essor&re#ative !hysi$a# address, the memory $ontro##er Ca#so $a##ed the North <ridgeD de$odes the address and dire$ts it a!!ro!riate#y( )" the address identi"ies a #o$ation in !hysi$a# memory, the memory $ontro##er, in theory, trans#ates it to the s!e$i"i$ #o$ation re#ative to the memory bus at whi$h the memory is #o$ated( ;n standard 0@ !#at"orms, however, the !ro$essor& re#ative !hysi$a# address is a#most a#ways the same as the address in !hysi$a# memory s!a$e, so the trans#ation is sim!#y a one&to&one identity ma!!ing( )" the address identi"ies a #o$ation that is ma!!ed to a devi$e, the memory $ontro##er trans#ates it to a devi$e&bus&re#ative !hysi$a# address( )t $an then !#a$e the trans#ated address on the a!!ro!riate bus(
3&2
Device-7!s-6elative $hysical Addresses
he device-bus relative address space de"ines a set o" addresses that identi"y #o$ations on a s!e$i"i$ bus(
Note
he Windows DDK uses the term H#ogi$a# address s!a$eI to des$ribe the devi$e& bus re#ative address s!a$es and the term H#ogi$a# addressI to des$ribe an address that is used to identi"y a #o$ation in them( 7i%e H!hysi$a# address,I these terms are sometimes $on"using be$ause they are o"ten used in other $onte2ts and with other meanings( )n theory, ea$h devi$e bus $an have its own address s!a$e( )n !ra$ti$e, however, most 0@ !#at"orms im!#ement on#y a sing#e root devi$e bus( he "ew !#at"orms that im!#ement more than one root devi$e bus sim!#y segment the avai#ab#e address s!a$e without trans#ating it, so that a## the root buses a!!ear to share a sing#e address s!a$e( )n addition, the 0@) -!e$i"i$ation de"ines the re#ationshi! between the address s!a$es o" !arent and $hi#d 0@) buses and !rohibits trans#ations( 5ny trans#ations that are !er"ormed in su$h ma$hines must ta%e !#a$e at the #eve# o" the root devi$e bus( When a devi$e re$eives a devi$e&bus&re#ative address, it de$odes the address to determine whether the bus $y$#e is intended "or it and, i" so, "or whi$h o" its registers( Devi$es issue devi$e&bus re#ative !hysi$a# addresses when they !er"orm DM5( hese addresses are #ater trans#ated to !ro$essor&re#ative !hysi$a# addresses Cty!i$a##y by the memory $ontro##erD( he ma! registers that are $entra# to the Windows DM5 mode# are essentia##y an abstra$tion o" this trans#ation ste!( he use o" ma! registers ensures that any devi$e $an !er"orm DM5 to any #o$ation in !hysi$a# memory, regard#ess o" any addressing #imitations in the devi$e( De!ending on the individua# ma$hine, the ma! registers might be im!#emented in hardware or in so"tware(
) Memory Descri(tor -ists

5 memory des$ri!tor #ist CMD7D des$ribes a #ist o" !ages in !hysi$a# memory( )nterna##y, the Windows %erne# uses MD7s in numerous ways( For e2am!#e, when the )1; manager sets u! a dire$t )1; re*uest to send to a driver, it $reates an MD7
February 28, 2005
to des$ribe the )1; bu""er( he driver re$eives a !ointer to the MD7 in the re*uest at r(-8MdlAddress( When the driver re$eives the re*uest, the !ages des$ribed by the MD7 have a#ready been #o$%ed into memory by the $reator o" the MD7( o use virtua# addresses to a$$ess the bu""er des$ribed by the MD7, the driver $a##s Mm9et'ystemAddress,orMdl'a.e to ma! the bu""er into system s!a$e( his "un$tion returns a va#id system&s!a$e virtua# address that the driver $an use to a$$ess the bu""er( Drivers $reate MD7s in the "o##owing situations: he driver re$eives an )1; re*uest "or neither bu""ered nor dire$t CME B;DKNE) BE3D )1;( he driver initiates an )1; re*uest to send to another driver( he driver s!#its a #arge )1; bu""er into two or more sma##er bu""ers(
he driver a##o$ates !hysi$a# memory "rom a s!e$i"i$ !hysi$a# address range( When a driver re$eives a re*uest "or ME B;DKNE) BE3 )1;, a !ointer to a bu""er is !art o" the re*uest( )" the originator o" the )1; re*uest is another %erne#&mode $om!onent, the bu""er $an be in system s!a$e( More o"ten, however, the originator o" the re*uest is a user&mode !ro$ess, so the bu""er is in user s!a$e( o read and write to this user&s!a$e bu""er, the driver must $reate an MD7 that des$ribes these !ages and must ensure that they remain a$$essib#e unti# the driver has $om!#eted the )1; re*uest( @reating the MD7 #o$%s the !ages into memory so that any subse*uent a$$ess is guaranteed to be !rote$ted( )" the driver must use virtua# addresses to a$$ess the !ages des$ribed by the MD7, it must ma! those !ages into the system address s!a$e using Mm9et'ystemAddress,orMdl'a.e( his "un$tion returns a va#id system&s!a$e virtua# address with whi$h the driver $an sa"e#y a$$ess the bu""er( When a driver initiates an )1; re*uest, it a##o$ates an MD7 to des$ribe the bu""er in the )1; re*uest( For e2am!#e, a driver might send a devi$e )1; $ontro# re*uest C)30KMNK)N E3N57KDE+)@EK@;N 3;7D to a #ower driver in its sta$% to re*uest some %ind o" intervention with the hardware( he driver wou#d $a## oAllocateMdl to $reate an MD7 and #ater use a di""erent system "un$tion to "i## in the MD7, de!ending on the ty!e o" re*uest( )" the re*uest s!e$i"ies dire$t )1;, the #ower driver wou#d re$eive a !ointer to the MD7 in the re*uest at r(-8MdlAddress( o s!#it a #arge )1; bu""er into sma##er bu""ers, a driver might a#so use an MD7( y!i$a##y, s!#itting a bu""er in this way is re*uired on#y during dire$t )1; o!erations, i" the su!!#ied bu""er is too #arge "or the devi$e or i" the driver or devi$e $an o!erate more e""i$ient#y with severa# sma##er bu""ers( o s!#it a bu""er, the driver $a##s oAllocateMdl to $reate the new MD7, and then $a##s o7!ild$artialMdl to ma! a subset o" the range des$ribed by the origina# MD7 into the new one( 5 driver that a##o$ates !hysi$a# memory "rom a s!e$i"i$ range o" addresses must a#so $reate an MD7 to des$ribe the a##o$ated memory( )n this $ase, the driver $a##s MmAllocate$ages,orMdl Cwhi$h a##o$ates the memoryD, $reates the MD7, and #o$%s the !ages( )" the driver re*uires a$$ess to the !ages through virtua# addresses, the driver a#so $a##s Mm9et'ystemAddress,orMdl'a.e to ma! the !ages into virtua# memory and return a virtua# address "or the driverGs use(
February 28, 2005
ab#e 2 summari>es Windows routines that $reate and mani!u#ate MD7s( %able 2& '!mmary o. MD- 6o!tines Name Des$ri!tion MmAllocateMa((ingAddress 3eserves a range o" virtua# addresses "or ma!!ing, but does not a$tua##y ma! them to !hysi$a# memory( o ma! the virtua# addresses in the reserved range to !hysi$a# addresses, the driver #ater $a##s oAllocateMdl, Mm$robeAnd-oc:$ages, and MmMa(-oc:ed$agesWith6eservedMa((in g( his te$hni*ue is #ess e""i$ient than $a##ing Mm9et'ystemAddress,orMdl'a.e or MmMa(-oc:ed$agesXxx, but is use"u# be$ause it a##ows driver e2e$ution to $ontinue in situations when $a##ing these #atter "un$tions "ai#s( oAllocateMdl 5##o$ates an MD7 "or a bu""er, given the starting virtua# address o" the bu""er and its #ength( his routine does not asso$iate the !hysi$a# !ages in the bu""er with the a##o$ated MD7( o do so, the driver must $a## Mm7!ildMdl,orNon$aged$ool, o7!ild$artialMdl, or Mm$robeAnd-oc:$ages( Mm$robeAnd-oc:$ages @on"irms that the !ages des$ribed by an MD7 !ermit the re*uested ty!e o" a$$ess and, i" so, #o$%s those !ages into memory( Mm7!ildMdl,orNon$aged$ool Fi##s in an MD7 to des$ribe a bu""er that is a##o$ated in system&s!a$e memory "rom the non!aged !oo#( he MD7 must have been a##o$ated by oAllocateMdl( 5 driver $an a#so use this "un$tion on )1; s!a$e, ty!i$a##y by ma!!ing the s!a$e with MmMa( o'(ace and then !assing the returned virtua# address to Mm7!ildMdl,orNon$aged$ool( MmAllocate$ages,orMdl 5##o$ates non!aged, non$ontiguous !ages "rom !hysi$a# memory, s!e$i"i$a##y "or an MD7( 5 driver $a##s this "un$tion to a##o$ate !hysi$a# memory "rom a !arti$u#ar address range( Do not use this "un$tion to a##o$ate memory "or DM5M use the systemGs DM5 routines instead( his "un$tion might return "ewer !ages than the $a##er re*uested( here"ore, the driver must $a## Mm9etMdl7yteCo!nt to veri"y the number o" bytes a##o$ated( Mm9et'ystemAddress,orMdl Ma!s the !hysi$a# !ages des$ribed by an 'a.e MD7 into system s!a$e and returns a virtua# address "or the MD7( he returned virtua# address $an be used at any )3O7 and in any !ro$ess $onte2t(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - ")
Name o7!ild$artialMdl
MmAdvanceMdl
Mm9etMdl#irt!alAddress o,reeMdl Mm,ree$ages,romMdl
Des$ri!tion Ma!s !art o" a bu""er des$ribed by an e2isting MD7 into a new MD7 that the driver !revious#y a##o$ated by $a##ing oAllocateMdl( )n$reases the starting address o" an MD7( 5 driver $a##s this "un$tion to u!date the MD7 to des$ribe a !artia# bu""er when )1; o!erations are not Cor $annot beD $om!#eted, either be$ause not enough memory is avai#ab#e or be$ause the devi$e $an write on#y !art o" the bu""er at a time( 3eturns the starting virtua# address o" an MD7( Frees an MD7 that was !revious#y a##o$ated by oAllocateMdl( Frees the !ages des$ribed by an MD7 that was !revious#y $reated by MmAllocate$ages,orMdl(
* $ool Memory
Windows !rovides !oo#s o" !aged and non!aged memory that drivers and other $om!onents $an a##o$ate( he E2e$utive $om!onent o" the o!erating system manages the memory in the !oo#s and e2!oses the E;Allocate$oolXxx "un$tions "or use by drivers( 0oo# memory is a subset o" avai#ab#e memory and is not ne$essari#y $ontiguous( he si>e o" ea$h !oo# is #imited and de!ends on the amount o" !hysi$a# memory that is avai#ab#e and varies great#y "or di""erent Windows re#eases( he !aged !oo# is e2a$t#y what its name im!#ies: a region o" virtua# memory that is subEe$t to !aging( he si>e o" the !aged !oo# is #imited and de!ends on both the amount o" avai#ab#e !hysi$a# memory on ea$h individua# ma$hine and the s!e$i"i$ o!erating system re#ease( For e2am!#e, the ma2imum si>e o" the !aged !oo# is about 6:4 M< on .2&bit hardware running Windows /0 and about 850 M< on Windows -erver 200. -04( he non!aged !oo# is a region o" system virtua# memory that is not subEe$t to !aging( Drivers use the non!aged !oo# "or many o" their storage re*uirements be$ause it $an be a$$essed at any )3O7( 7i%e the !aged !oo#, the non!aged !oo# is #imited in si>e( ;n a .2&bit 288 system that is started without the 1.?< swit$h, the non!aged !oo# is #imited to 258 M<M with the 1.?< swit$h, the #imit is 428 M<( ;n 86&bit systems, the non!aged !oo# $urrent#y has a #imit o" 428 ?<( he !oo# si>es and ma2imums may vary great#y "or di""erent Windows re#eases(
*&"
6<- Considerations
When you design your driver, %ee! in mind that the system $annot servi$e a !age "au#t at )3O7 D)-05 @BK7E+E7 or higher( here"ore, drivers must use non!aged !oo# "or any data that $an be a$$essed at D)-05 @BK7E+E7 or higher( Aou $annot move a bu""er that was a##o$ated "rom the !aged !oo# into the non!aged !oo#, but you $an #o$% a !aged bu""er into memory so that it is tem!orari#y non!aged( 7o$%s must never be a##o$ated in the !aged !oo# be$ause the system a$$esses them at D)-05 @BK7E+E7 or higher, even i" the #o$%s are used to syn$hroni>e $ode that runs be#ow D)-05 @BK7E+E7(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - "*
-torage "or the "o##owing items $an genera##y be a##o$ated "rom the !aged !oo#, de!ending on how the driver uses them: )n"ormation about devi$e resour$es, re#ations, $a!abi#ities, inter"a$es, and other detai#s that are hand#ed in )30KMNK0N0KO=E3AKP re*uests( he 0#ug and 0#ay manager sends a## *ueries at 05--)+EK7E+E7, so un#ess the driver must re"eren$e this in"ormation at a higher )3O7, it $an sa"e#y store the data in !aged memory( he registry !ath !assed to DriverEntry( -ome drivers save this !ath "or use during WM) initia#i>ation, whi$h o$$urs at 05--)+EK7E+E7( Whi#e running at D)-05 @BK7E+E7 or be#ow, a driver $an a##o$ate memory "rom the non!aged !oo#( 5 driver $an a##o$ate !aged !oo# on#y whi#e it is running at 05--)+EK7E+E7 or 50@K7E+E7 be$ause 50@K7E+E7 syn$hroni>ation is used within the !oo# manager $ode "or !ageab#e re*uests( Furthermore, i" the !aged !oo# is nonresident, a$$essing it at D)-05 @BK7E+E7Jeven to a##o$ate itJwou#d $ause a "ata# bug $he$%( For a $om!#ete #ist o" standard driver routines and the )3O7 at whi$h ea$h is $a##ed, see H-$hedu#ing, hread @onte2t, and )3O7,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er( )n addition, the Windows DDK #ists the )3O7 at whi$h system and driver routines $an be $a##ed(
*&2
-oo:aside -ists
7oo%aside #ists are "i2ed&si>e, reusab#e bu""ers that are designed "or stru$tures that a driver might need to a##o$ate dynami$a##y and "re*uent#y( he driver de"ines the si>e, #ayout, and $ontents o" the entries in the #ist to suit its re*uirements, and the system maintains #ist status and adEusts the number o" avai#ab#e entries a$$ording to demand( When a driver initia#i>es a #oo%aside #ist, Windows $reates the #ist and ho#ds the bu""ers in reserve "or "uture use by the driver( he number o" bu""ers that are in the #ist at any given time de!ends on the amount o" avai#ab#e memory and the si>e o" the bu""ers( 7oo%aside #ists are use"u# whenever a driver needs "i2ed&si>e bu""ers and are es!e$ia##y a!!ro!riate "or $ommon#y used and reused stru$tures, su$h as )1; re*uest !a$%ets C)30sD( he )1; manager a##o$ates its own )30s "rom a #oo%aside #ist( 5 #oo%aside #ist $an be a##o$ated "rom either the !aged or the non!aged !oo#, a$$ording to the driverGs re*uirements( 5"ter the #ist has been initia#i>ed, a## bu""ers "rom the #ist $ome "rom the same !oo#(
*&3
Caching
Drivers $an a##o$ate $a$hed or non$a$hed memory( @a$hing im!roves !er"orman$e, es!e$ia##y "or a$$ess to "re*uent#y used data( 5s a genera# ru#e, drivers shou#d a##o$ate $a$hed memory( he 288, 286, and )tanium ar$hite$tures a## su!!ort $a$he&$oherent DM5, so drivers $an sa"e#y use $a$hed memory "or DM5 bu""ers( Drivers rare#y re*uire non$a$hed memory( 5 driver shou#d a##o$ate no more non$a$hed memory than it needs and shou#d "ree the memory as soon as it is no #onger re*uired(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - "/
*&)
*&)&"
Alignment
he a#ignment o" the data stru$tures in a driver $an have a big im!a$t on the driverGs !er"orman$e and e""i$ien$y( wo ty!es o" a#ignment are im!ortant: Natura# a#ignment "or the data si>e @a$he&#ine a#ignment Nat!ral Alignment
Natura# a#ignment means a#igning data a$$ording to its ty!e( he Mi$roso"t @ $om!i#er a#igns individua# data items on an a!!ro!riate boundary "or their si>e( For e2am!#e, =@B53s are a#igned on 4&byte boundaries, ints on 6&byte boundaries, and 7;N?s and =7;N?s on 6&byte boundaries( )ndividua# data items within a stru$ture are a#so natura##y a#ignedJthe $om!i#er adds !adding bytes i" re*uired( When you $om!i#e, stru$tures are a#igned a$$ording to the a#ignment re*uirements o" the #argest member( =nions are a#igned a$$ording to the re*uirements o" the "irst member o" the union( o a#ign individua# members o" a stru$ture or union, the $om!i#er a#so adds !adding bytes( When you $om!i#e a .2& bit driver, !ointers are .2 bits wide and o$$u!y 6 bytes( When you $om!i#e a 86&bit driver, !ointers are 86 bits and o$$u!y 8 bytes( 5 stru$ture that $ontains a !ointer, there"ore, might re*uire di""erent amounts o" !adding on .2&bit and 86&bit systems( )" the stru$ture is used on#y interna##y within the driver, di""eren$es in !adding are not im!ortant( Bowever, you must ensure that the !adding is the same on .2&bit and 86&bit systems in either o" the "o##owing situations: he stru$ture is used by both .2&bit and 86&bit !ro$esses running on a 86& bit ma$hine( he stru$ture might be !assed to or used on .2&bit hardware as a resu#t o" being saved on dis%, sent over the networ%, or used in a devi$e )1; $ontro# re*uest C);@ 7D( Aou $an reso#ve this issue by using !ragmas Cas des$ribed be#owD or by adding e2!#i$it dummy variab#es to the stru$ture Eust "or !adding( For $ross&!#at"orm $om!atibi#ity, you shou#d e2!#i$it#y a#ign data on 8&byte boundaries on both 86&bit and .2&bit systems( 0ro!er a#ignment enab#es the !ro$essor to a$$ess data in the minimum number o" o!erations( For e2am!#e, a 6&byte va#ue that is natura##y a#igned $an be read or written in one $y$#e( 3eading a 6&byte va#ue that does not start on a 6&byte Cor mu#ti!#eD boundary re*uires an additiona# $y$#e, and the re*uested bytes must be !ie$ed together into a sing#e 6&byte unit be"ore the va#ue $an be returned( )" the !ro$essor tries to read or write im!ro!er#y a#igned data, an a#ignment "au#t $an o$$ur( ;n 288 hardware, the a#ignment "au#ts are invisib#e to the user( he hardware "i2es the "au#t as des$ribed in the !revious !aragra!h( ;n 286 hardware, a#ignment "au#ts are disab#ed by de"au#t and the hardware simi#ar#y "i2es the "au#t( ;n the )nte# )tanium ar$hite$ture, however, i" an a#ignment "au#t o$$urs whi#e 86&bit %erne#&mode $ode is running, the hardware raises an e2$e!tion( CFor user&mode $ode, this is a de"au#t setting that an individua# a!!#i$ation $an $hange, a#though disab#ing a#ignment "au#ts on the )tanium $an severe#y degrade !er"orman$e(D o !revent e2$e!tions and !er"orman$e !rob#ems that are re#ated to misa#ignment, you shou#d #ay out your data stru$tures $are"u##y( When a##o$ating memory, ensure that you a##o$ate enough s!a$e to ho#d not Eust the natura# data si>e, but a#so the !adding that the $om!i#er adds( For e2am!#e, the "o##owing stru$ture in$#udes a .2&
February 28, 2005
bit va#ue and an array( he array e#ements $an be either .2 or 86 bits #ong, de!ending on the hardware(
struct Xx { DWORD NumberOfPointers; PVOID Pointers[1]; };
When this de$#aration is $om!i#ed "or 86&bit hardware, the $om!i#er adds an e2tra 6 bytes o" !adding to a#ign the stru$ture on an 8&byte boundary( here"ore, the driver must a##o$ate enough memory "or the !added stru$ture( For e2am!#e, i" the array $ou#d have a ma2imum o" 400 e#ements, the driver shou#d $a#$u#ate the memory re*uirements as "o##ows:
FIE D!OFF"E# $struct Xx% Pointers& ' 1(()si*eof$PVOID&
he F)E7DK;FF-E ma$ro returns the byte o""set o" the 0ointers array in the stru$ture /2( =sing this va#ue in the $a#$u#ation a$$ounts "or any bytes o" !adding that the $om!i#er might add a"ter the Number;"0ointers "ie#d( o "or$e a#ignment on a !arti$u#ar byte boundary, a driver $an use any o" the "o##owing: he storage $#ass *ua#i"ier ==decls(ec>align>?? or the DE@7-0E@K57)?NCD ma$ro he (ac:>? !ragma he 0sh!a$%N(h and 0o!!a$%(h header "i#es
o $hange the a#ignment o" a sing#e variab#e or stru$ture, you $an use ==decls(ec>align>?? or the DE@7-0E@K57)?NCD ma$ro, whi$h is de"ined in the Windows DDK( he "o##owing ty!e de"inition sets a#ignment "or the =7;N?K548 ty!e at 48 bytes, thus a#igning the two "ie#ds in the stru$ture and the stru$ture itse#" on 48&byte boundaries:
t+,e-ef DE. "PE.!/ I0N$11& 2 ON0 2 ON0!/11; t+,e-ef struct { 2 ON0!/11 3; 2 ON0!/11 b; } #E"#;
Aou $an a#so use the (ac:>? !ragma to s!e$i"y the a#ignment o" stru$tures( his !ragma a!!#ies to a## de$#arations that "o##ow it in the $urrent "i#e and overrides any $om!i#er swit$hes that $ontro# a#ignment( <y de"au#t, the DDK bui#d environment uses (ac: >3?( he de"au#t setting means that any data item with natura# a#ignment u! to and in$#uding 8 bytes is natura##y a#igned, not ne$essari#y 8&byte a#igned, and everything #arger than 8 bytes is a#igned on an 8&byte boundary( hus, two adEa$ent =7;N? "ie#ds in a 86&bit a#igned stru$ture are adEa$ent, with no !adding between them( 5nother way to $hange the a#ignment o" data stru$tures in your $ode is to use the header "i#es 0sh!a$%N(h C!sh!a$%4(h, !sh!a$%2(h, !sh!a$%6(h, !sh!a$%8(h, and !sh!a$%48(hD and 0o!!a$%(h, whi$h are insta##ed as !art o" the Windows DDK( he 0sh!a$%N(h "i#es $hange a#ignment to a new setting, and 0o!!a$%(h returns a#ignment to its setting be"ore the $hange was a!!#ied( For e2am!#e:
4inc5u-e 6,s7,3c89:7; t+,e-ef struct !"#R2.#!#</#!NEED"!#WO!=>#E!P/.?IN0 { @) contents of structure :::
February 28, 2005
} "#R2.#!#</#!NEED"!#WO!=>#E!P/.?IN0; 4inc5u-e 6,o,,3c8:7;
)n the e2am!#e, the !sh!a$%2(h "i#e sets 2&byte a#ignment "or everything that "o##ows it in the sour$e $ode, unti# the !o!!a$%(h "i#e is in$#uded( Aou shou#d a#ways use these header "i#es in !airs( 7i%e the (ac:>? !ragma, they override any a#ignment settings s!e$i"ied by $om!i#er swit$hes( For more in"ormation about a#ignment and the Mi$roso"t $om!i#ers, see the Windows DDK and the M-DN #ibrary, whi$h are #isted in the 3esour$es se$tion o" this !a!er( *&)&2 Cache--ine Alignment
When you design your data stru$tures, you $an "urther in$rease the e""i$ien$y o" your driver by $onsidering $a$he&#ine a#ignment in addition to natura# a#ignment( Memory that is $a$he&a#igned starts at a !ro$essor $a$he&#ine boundary( When the hardware u!dates the !ro$essor $a$he, it a#ways reads an entire $a$he #ine rather than individua# data items( here"ore, using $a$he&a#igned memory $an redu$e the number o" $a$he u!dates ne$essary when the driver reads or writes the data and $an !revent other $om!onents "rom $ontending "or u!dates o" the same $a$he #ine( 5ny memory that starts on a !age boundary is $a$he&a#igned( Drivers ty!i$a##y a##o$ate non!aged, $a$he&a#igned memory to ho#d "re*uent#y a$$essed driver data( )" !ossib#e, #ay out data stru$tures so that individua# "ie#ds are un#i%e#y to $ross $a$he #ine boundaries( he si>e o" a $a$he #ine is genera##y "rom 48 to 428 bytes, de!ending on the hardware( he Ke9et6ecommended'haredDataAlignment "un$tion returns the re$ommended a#ignment on the $urrent hardware( @a$he&#ine a#ignment is a#so im!ortant "or shared data that two or more threads $an a$$ess $on$urrent#y( o redu$e the number o" $a$he u!dates, "ie#ds that are !rote$ted by the same #o$% and are u!dated together shou#d be in the same $a$he #ine( -tru$tures that are !rote$ted by di""erent #o$%s and $an there"ore be a$$essed simu#taneous#y on two di""erent !ro$essors shou#d be in di""erent $a$he #ines( 7aying out data stru$tures in this way !revents !ro$essors "rom $ontending "or the same $a$he #ine, whi$h $an have a !ro"ound e""e$t on !er"orman$e( For more in"ormation about $a$he #ine a#ignment on mu#ti!ro$essor systems, see HMu#ti!ro$essor @onsiderations "or Kerne#&Mode Drivers,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er(
/ Kernel 'tac:
he %erne# sta$% is a #imited storage area that is used "or in"ormation that is !assed "rom one "un$tion to another and "or #o$a# variab#e storage( he si>e o" the sta$% $an vary among di""erent hardware !#at"orms and di""erent versions o" the o!erating system, but it is a#ways a s$ar$e resour$e( 5#though the sta$% is ma!!ed into system s!a$e, it is $onsidered !art o" the thread $onte2t o" the origina# $a##ing routine, not !art o" the driver itse#"( )t is there"ore guaranteed to be resident whenever the thread is running, but it $an be swa!!ed out a#ong with the thread( <e$ause the %erne# sta$% is asso$iated with the thread $onte2t, "un$tions su$h as o9et6emaining'tac:'i@e Cwhi$h returns the amount o" %erne# sta$% s!a$e that is $urrent#y avai#ab#eD and o9et'tac:-imits Cwhi$h returns the addresses o" the
February 28, 2005
sta$%D !rovide in"ormation about the %erne# sta$% in the thread "rom whi$h they are $a##ed( 5 driver $an use these system routines to determine whether enough sta$% s!a$e remains to $a## a "un$tion to !er"orm a tas%( )" not, the driver $an *ueue the tas% to a wor% item, whi$h runs in a se!arate thread( he sta$% si>e and #imit "un$tions are use"u# !rimari#y in "i#e system drivers( Drivers "or !hysi$a# devi$es ty!i$a##y have sha##ow sta$% usage and there"ore do not o"ten re*uire these "un$tions( Drivers shou#d use the %erne# sta$% $onservative#y( Beavi#y re$ursive "un$tions that are !assed many bytes o" data $an *ui$%#y de!#ete sta$% s!a$e and $ause a system $rash( )nstead o" !assing #arge amounts o" data, the driver shou#d !ass a !ointer to the data( ;n 286&based systems, Windows does not a##ow third&!arty so"tware to a##o$ate memory Qon the sideQ and use it as a %erne# sta$%( )" the o!erating system dete$ts one o" these modi"i$ations or any other unauthori>ed !at$h, it generates a bug $he$% and shuts down the system( o he#! ensure stabi#ity and re#iabi#ity o" the o!erating system and a better e2!erien$e "or $ustomers, drivers "or a## !#at"orms shou#d avoid these !ra$ti$es(
2 Memory Allocation %echniA!es

he best te$hni*ue "or a##o$ating memory de!ends on how the memory wi## be used( ab#e . summari>es the Windows %erne#&mode memory a##o$ation routines that are dis$ussed in this se$tion( %able 3& '!mmary o. Memory Allocation 6o!tines Name Des$ri!tion E;Allocate$oolXxx 5##o$ates !aged or non!aged, $a$hed, and $a$he&a#igned memory "rom the %erne#&mode !oo#( E;Allocate$oolWith%ag is the !rimary "un$tion "or memory a##o$ation( AllocateCommon7!..er 5##o$ates a bu""er "or $ommon&bu""er DM5 and ensures $ross&!#at"orm $om!atibi#ity( MmAllocateContig!o!sMem 5##o$ates non!aged, !hysi$a##y $ontiguous, ory $a$he&a#igned memory( R'(eci.yCacheS Drivers shou#d not use these "un$tions to a##o$ate memory "or DM5 be$ause the addresses that they return are not guaranteed to be $om!atib#e a$ross a## hardware $on"igurations( Drivers shou#d use AllocateCommon7!..er instead( MmAllocateMa((ingAddress 3eserves virtua# addresses in a s!e$i"i$ range "or #ater use in an MD7, but does not ma! them to !hysi$a# memory( he driver $an #ater use oAllocateMdl, Mm$robeAnd-oc:$ages, and MmMa(-oc:ed$agesWith6eservedMa((ing to ma! the virtua# addresses to !hysi$a# memory( MmAllocateNoncachedMem 5##o$ates non!aged, non$a$hed, !age&a#igned ory memory( Drivers rare#y use this "un$tionM they must not use it to a##o$ate bu""ers "or DM5(
February 28, 2005
Name MmAllocate$ages,orMdl
Des$ri!tion 5##o$ates non!aged, non$ontiguous !ages "rom !hysi$a# memory, s!e$i"i$a##y "or an MD7( 5n MD7 $an des$ribe u! to 6 ?<( his "un$tion might return "ewer !ages than the $a##er re*uested( here"ore, the driver must $a## Mm9etMdl7yteCo!nt to veri"y the number o" a##o$ated bytes( 5 driver $an $a## this "un$tion to a##o$ate !hysi$a# memory "rom a !arti$u#ar address range, su$h as a##o$ating memory "or a devi$e that $annot address memory above 6 ?<( Bowever, drivers shou#d not use this "un$tion to a##o$ate bu""ers "or DM5( ;n#y the Windows DM5 routines guarantee the $ross&!#at"orm $om!atibi#ity that drivers re*uire(
he "o##owing se$tions $over te$hni*ues "or a##o$ating memory "or severa# s!e$i"i$ !ur!oses: 0oo# memory "or #ong&term storage 7oo%aside #ists @ontiguous memory
2&"
Allocating Memory .or -ong-%erm 'torage
0oo# memory is a!!ro!riate "or most #ong&term driver storage re*uirements( he !oo# a##o$ation routines a##o$ate $a$hed memory "rom the !aged or non!aged %erne#&mode !oo#s( Drivers shou#d use !oo# memory un#ess they have other s!e$i"i$ re*uirements, su$h as the "o##owing: he devi$e or driver re*uires more than a !age o" !hysi$a##y $ontiguous memory( C3emember that !age si>e varies de!ending on the ma$hine ar$hite$ture(D he devi$e re*uires non$a$hed or write&$ombined memory( -ome video devi$es "a## into this $ategory( he devi$e has $onstraints that #imit the range o" addresses it $an use(
0oo# memory is a #imited resour$e, so drivers shou#d a##o$ate it e$onomi$a##y( When you design your driver, !#an your memory a##o$ations a$$ording to memory ty!e, a##o$ation si>e, and a##o$ation #i"etime( Free the a##o$ated memory as soon as you are done using it( )" your driver re*uires #arge amounts o" non!aged !oo# "or #ong&term use, a##o$ate the memory at startu! i" !ossib#e, either in the DriverEntry routine or in an AddDevice routine( <e$ause the non!aged !oo# be$omes "ragmented as the system runs, #ater attem!ts to a##o$ate memory "rom the non!aged !oo# $ou#d "ai#( 5 driver shou#d not, however, !rea##o$ate e2$essive#y #arge b#o$%s o" memory Csevera# megabytes, "or e2am!#eD and try to manage its own a##o$ations within that b#o$%( 5#though this te$hni*ue might wor% "or your driver, it o"ten resu#ts in ine""i$ient memory usage a$ross the system and thus !oor !er"orman$e system& wide( 3emember that other drivers and a!!#i$ations a#so re*uire memory( Never a##o$ate #ots o" memory HEust in $aseI your driver might need it( 5s a genera# design guide#ine, $onsider !rea##o$ating on#y enough memory "or one )1; transa$tion and
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 2"
then !ro$ess the transa$tions seria##y( )" the transa$tions a## re*uire same&si>ed a##o$ations, $onsider using #oo%aside #ists be$ause these bu""ers are dynami$a##y a##o$ated( Drivers $an a##o$ate $a$hed memory "rom either the !aged !oo# or the non!aged !oo# by using the "o##owing E;Allocate$oolXxx routines: E;Allocate$oolWith%ag E;Allocate$oolWith%ag$riority E;Allocate$oolWith<!ota%ag
Drivers must use the tagged versions o" the !oo# a##o$ation routines be$ause the nontagged versions are obso#ete( <oth WinDbg and Driver +eri"ier use !oo# tags to tra$% memory a##o$ations( agging !oo# a##o$ations $an sim!#i"y "inding memory& re#ated bugs, in$#uding #ea%s( <e sure to use uni*ue tags so that the debugging and testing too#s $an !rovide use"u# in"ormation(
Note
he !oo# ty!e Non$aged$oolM!st'!cceed has been de!re$ated( Drivers shou#d s!e$i"y the !oo# ty!e Non$aged$ool or Non$aged$oolCacheAligned instead and shou#d return the N - 5 =- va#ue - 5 =-K)N-=FF)@)EN K3E-;=3@E- i" the a##o$ation "ai#s( he Driver +eri"ier "#ags any !oo# a##o$ation that is s!e$i"ied as Non$aged$oolM!st'!cceed as "ata# and $auses a bug $he$%( CNote that on versions o" Windows ear#ier than Mi$roso"t Windows +ista, s!e$i"ying Non$aged$oolCacheAligned is the same as s!e$i"ying Non$aged$ool( ;n Windows +ista, however, s!e$i"ying Non$aged$oolCacheAligned ensures that the system a##o$ates $a$he&a#igned memory(D )n the "o##owing e2am!#e, the driver a##o$ates a bu""er "rom non!aged !oo#, a#igned on a !ro$essor $a$he&#ine boundary:
A+=uffer B Ex/55oc3tePoo5Wit7#3C$NonP3Ce-Poo5.3c7e/5iCne-% A/X!=2FFER!"IDE% Etse#E&; if $A+=uffer BB N2 & { DebuCPrint$$1% F .3nEt 355oc3te A+=uffer GnF&&; return$"#/#2"!IN"2FFI.IEN#!RE"O2R.E"&; }
he e2am!#e s!e$i"ies the !oo# tag in reverse order so that it a!!ears as H estI in the debugger( CAou shou#d use a tag that uni*ue#y identi"ies your driver(D )n the e2am!#e, M5/K<=FFE3K-)LE s!e$i"ies the number o" bytes to a##o$ate( <e$ause o" rounding and a#ignment, the driver might re$eive a bu""er o" e2a$t#y the re*uested si>e or a #arger bu""er( he E;Allocate$oolXxx routines a#ign and round a##o$ations as "o##ows: -i>e re*uested 7ess than or e*ua# to C05?EK-)LE T si@eo. C0;;7KBE5DE3DD ?reater than C05?EK-)LE T si@eo. C0;;7KBE5DE3DD -i>e a##o$ated Number o" bytes re*uested De"au#t a#ignment 8&byte boundary C48&byte on 86&bit WindowsD( 5##o$ation is $ontiguous and does not $ross !age boundary( 0age&a#igned( 0ages are not ne$essari#y !hysi$a##y $ontiguous, but they are a#ways virtua##y $ontiguous(
Number o" bytes re*uested, rounded u! to ne2t "u## !age si>e
February 28, 2005
he !oo# header is 8 bytes #ong on .2&bit systems and 48&bytes #ong on 86&bit systems( he si>e o" the !oo# header does not a""e$t the $a##er( o use the !oo# most e""i$ient#y, avoid $a##ing the memory a##o$ation routines re!eated#y to re*uest sma## a##o$ations o" #ess than 05?EK-)LE( )" your driver norma##y uses severa# re#ated stru$tures together, $onsider bund#ing those stru$tures into a sing#e a##o$ation at driver start&u!( For e2am!#e, the -@-) !ort driver bund#es an )30, a -@-) re*uest b#o$% C-3<D, and an MD7 into a sing#e a##o$ation( <y a##o$ating the memory at start&u!, you redu$e the number o" times your driver $a##s memory a##o$ation routines and there"ore the number o" situations in whi$h it must be !re!ared to hand#e an a##o$ation "ai#ure( E#iminating su$h "ai#ure s$enarios great#y sim!#i"ies the error !aths in your driver( 0oo# memory remains a##o$ated unti# the driver e2!#i$it#y "rees it( <e"ore the driver e2its, it must $a## E;,ree$ool or E;,ree$oolWith%ag to "ree a## the memory that it a##o$ated with any o" the E;Allocate$oolXxx variants( Fai#ing to "ree the memory $auses memory #ea%s, whi$h $an eventua##y s#ow system !er"orman$e and $ause other $om!onents to "ai#(
2&2
Creating and 1sing -oo:aside -ists
5 driver $a##s E; nitiali@eBNC$aged-oo:aside-ist to set u! a #oo%aside #ist, E;Allocate,romBNC$aged-oo:aside-ist to a##o$ate a bu""er "rom the #ist, and E;,ree%oBNC$aged-oo:aside-ist to "ree a bu""er to the #ist( Even i" a #oo%aside #ist is a##o$ated in !aged memory, the head o" the #ist must be a##o$ated in non!aged memory be$ause the system s$ans it at D)-05 @BK7E+E7 to !er"orm various boo%%ee!ing $hores( y!i$a##y, drivers store a !ointer to the head o" the #ist in the devi$e e2tension( For e2am!#e, a networ% ada!ter driver that re$eives data into "i2ed&si>e b#o$%s might set u! a #oo%aside #ist "or the b#o$%s as "o##ows:
ExIniti35i*eNP3Ce- oo83si-e ist $HF-oD3t3I;RecJ oo83si-e ist% N2 % N2 % (% RecJ=5oc8"i*e% K ciNL% (&;
he #oo%aside #ist in the e2am!#e is a##o$ated "rom non!aged memory be$ause the driver a$$esses it at D)-05 @BK7E+E7 or higher( he "irst !arameter identi"ies the #o$ation in non!aged memory where the driver stores the head o" the #ist( his #o$ation must be at #east si@eo. CN05?EDK7;;K5-)DEK7)- D( he two N=77 !arameters re!resent the driver routines that the system $a##s to a##o$ate and "ree bu""ers "rom the #ist( )" the driver !asses N=77, the system uses E;Allocate$oolWith%ag and E;,ree$oolWith%ag( 5#though a driver $an su!!#y its own routines, using the systemGs a##o$ation routines is genera##y more e""i$ient( he "ourth !arameter su!!#ies interna# "#ags and must be >ero( he "i"th !arameter, 3e$v<#o$%-i>e, s!e$i"ies the si>e o" ea$h bu""er in the #ist, and the si2th is the tag used "or the !oo# a##o$ation( he "ina# !arameter is a#so reserved "or interna# use and must be >ero( 7ater, to a##o$ate and use a bu""er "rom the #ist, the driver $a##s E;Allocate,romN$aged-oo:aside-ist, as "o##ows:
,RecJ=5oc8 B Ex/55oc3teFromNP3Ce- oo83si-e ist $ HF-oD3t3I;RecJ oo83si-e ist&;
February 28, 2005
)" the a##o$ation "ai#s "or any reason, the a##o$ation routine returns a N=77 !ointer( he driver shou#d va#idate the resu#t and either return an error or retry the o!eration unti# it re$eives a va#id !ointer( o "ree a bu""er that was a##o$ated "rom the #ist, the driver $a##s E;,ree%oN$aged-oo:aside-ist, !assing a !ointer to the head o" the #ist and a !ointer to the bu""er to "ree, as "o##ows:
ExFree#oNP3Ce- oo83si-e ist $ HF-oD3t3I;RecJ oo83si-e ist% ,RecJ=5oc8&;
o avoid using memory unne$essari#y, drivers shou#d "ree bu""ers as soon as they are no #onger needed( Fina##y, when the driver no #onger needs any bu""ers "rom the #ist, it $a##s E;DeleteN$aged-oo:aside-ist(
ExDe5eteNP3Ce- oo83si-e ist $ HF-oD3t3I;RecJ oo83si-e ist&;
he #ist need not be em!ty be$ause this "un$tion de#etes any remaining bu""ers and then de#etes the #ist itse#"( Drivers that run on Windows /0 and #ater versions $an use #oo%aside #ists to a##o$ate s$atter1gather #ists "or DM5, as des$ribed in HDM5 -u!!ort in Windows Drivers,I whi$h is #isted in the 3esour$es se$tion o" this !a!er(
2&3

Allocating Contig!o!s Memory
Drivers that re*uire a !age or more o" $ontiguous memory $an a##o$ate it by using one o" the "o##owing: he DM5 "un$tions AllocateCommon7!..er or 9et'catter9ather-ist MmAllocate$ages,orMdl MmAllocateContig!o!sMemory'(eci.yCache
o a##o$ate memory "or DM5 bu""ers, drivers shou#d $a## AllocateCommon7!..er or 9et'catter9ather-ist( For more in"ormation about these DM5 "un$tions, see the Windows DDK and HDM5 -u!!ort in Windows Drivers,I whi$h are #isted in the 3esour$es se$tion o" this !a!er( MmAllocate$ages,orMdl a##o$ates !ages "rom a s!e$i"ied range o" !hysi$a# addresses( here"ore, it is use"u# "or drivers o" devi$es that $annot address memory in $ertain ranges( For e2am!#e, some devi$es $annot address memory above 6 ?<( he driver "or su$h a devi$e $ou#d use this "un$tion to ensure that a bu""er was a##o$ated in memory be#ow 6 ?<( Bowever, that this "un$tion a##o$ates inde!endent !ages that are not !hysi$a##y $ontiguousM that is, ea$h entry in the MD7 ma!s a !age o" memory, but !ages are ty!i$a##y not $ontiguous with res!e$t to ea$h other( )" your devi$e re*uires no more than a !age o" $ontiguous memory at a time, but re*uires many su$h !ages, MmAllocate$ages,orMdl is a!!ro!riate( Do not use this "un$tion to a##o$ate bu""ers "or DM5Juse the DM5 routines instead( Drivers that need #arger amounts o" !hysi$a##y $ontiguous memory shou#d use MmAllocateContig!o!sMemory'(eci.yCache ( Drivers shou#d try to a##o$ate su$h memory during driver initia#i>ation be$ause !hysi$a# memory is #i%e#y to be$ome "ragmented as the system runs( 5 driver shou#d a##o$ate on#y as mu$h $ontiguous memory as it needs, and it shou#d "ree the memory as soon as it is no #onger needed(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 2)
MmAllocateContig!o!sMemory'(eci.yCache returns the base virtua# address o" the ma!!ed region( he "o##owing sam!#e shows how a driver might a##o$ate $ontiguous memory in a s!e$i"i$ range:
oMest/cce,t3b5e:Nu3-P3rt B (; =oun-3r+Au5ti,5e:Nu3-P3rt B (; <iC7est/cce,t3b5e:Nu3-P3rt B (xFFFFFFFF; Aem=uff B Am/55oc3te.ontiCuousAemor+",ecif+.3c7e$Aem enCt7% oMest/cce,t3b5e% <iC7est/cce,t3b5e% =oun-3r+Au5ti,5e% AmNon.3c7e-&; if $Aem=uff BB N2 & { return$"#/#2"!IN"2FFI.IEN#!RE"O2R.E"&; }
)n the e2am!#e, the driver a##o$ates $ontiguous, non$a$hed memory in the "irst 6 ?< o" the !hysi$a# address s!a$e( Mem7ength s!e$i"ies the number o" re*uired $ontiguous bytes( he driver !asses >ero in the 7owest5$$e!tab#e !arameter to indi$ate that the range o" addresses it $an use starts at >ero, and it !asses 02FFFFFFFF in the Bighest5$$e!tab#e !arameter to indi$ate that the range ends at 6 ?<( )t sets <oundaryMu#ti!#e to >ero be$ause there are no boundaries within the s!e$i"ied range that the memory shou#d not $ross( he "un$tion returns a "u## mu#ti!#e o" the systemGs !age si>e( )" Mem7ength is not a mu#ti!#e o" the !age si>e, the "un$tion rounds u! to the ne2t "u## !age( Do not use MmAllocateContig!o!sMemory'(eci.yCache to a##o$ate bu""ers "or DM5 and then $a## Mm9et$hysicalAddress to trans#ate the returned virtua# address to an address with whi$h to !rogram your DM5 $ontro##er( his a!!roa$h does not wor% on a## hardware, and your devi$e and driver wi## not be $ross&!#at"orm $om!atib#e( =se AllocateCommon7!..er or 9et'catter9ather-ist instead(
3 Accessing Device 6egisters

Devi$e registers are among a devi$eGs hardware resour$es, whi$h are assigned to the devi$e during 0#ug and 0#ay enumeration( 3egisters $an be ma!!ed into memory or into the 86&K< )1; s!a$e, de!ending on the ty!e o" devi$e, the bus to whi$h it is atta$hed, and the under#ying hardware !#at"orm( he 288, 286, and )tanium !ro$essors, a#ong with most $ommon buses Cin$#uding 0@), 0@) E2!ress, )-5, and E)-5D, su!!ort both memory ma!!ing and )1; ma!!ing( -ome other hardware ar$hite$tures, however, su!!ort on#y memory ma!!ing( 5s des$ribed ear#ier in H0hysi$a# 5ddress -!a$e,I )1; ma!!ing is a ho#dover "rom ear#y mi$ro!ro$essor designs( oday, however, most ma$hines have more than enough !hysi$a# address s!a$e to ho#d a## the devi$e registers( 5s a resu#t, newer devi$es are ty!i$a##y memory&ma!!ed( )n a memory&ma!!ed devi$e, the devi$e registers are ma!!ed to addresses in the !hysi$a# memory s!a$e( he driver then ma!s those addresses into the virtua# address s!a$e be"ore it uses them( Devi$e registers that are ma!!ed into )1; s!a$e are read and written with the 3E5DK0;3 K !! and W3) EK0;3 K !! ma$ros( Devi$e registers that are ma!!ed into memory are read and written with the 3E5DK3E?)- E3K !! and W3) EK3E?)- E3K !! ma$ros( hus, )1; ma!!ing is sometimes $a##ed 0;3 ma!!ing and the ma!!ed resour$es are $a##ed 0;3 resour$es Cwith or without the $a!ita# #ettersD( -imi#ar#y, memory ma!!ing is sometimes $a##ed 3E?)- E3 ma!!ing and the $orres!onding resour$es are $a##ed 3E?)- E3 resour$es(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 2*
5t devi$e enumeration, the bus driver re*uests )1; or memory ma!!ing "or ea$h devi$e resour$e, in res!onse to *ueries "rom the 0#ug and 0#ay manager( he 0#ug and 0#ay manager assigns raw and trans#ated resour$es to the devi$e and !asses a #ist o" the assigned resour$es to the devi$eGs "un$tion driver in the )30KMNK- 53 KDE+)@E re*uest( he raw resour$e ty!e re"#e$ts how the hardware is wired( he trans#ated resour$e ty!e indi$ates where the resour$e is ma!!ed on the $urrent system and thus whether the driver shou#d use 0;3 or 3E?)- E3 ma$ros to read and write the resour$e( Knowing how your devi$e hardware is wired does not ne$essari#y te## you how its resour$es wi## be ma!!ed be$ause some $hi!sets $hange the ma!!ing( here"ore, drivers must be !re!ared to su!!ort both ty!es o" ma!!ing "or ea$h register( De"ining wra!!ers "or the ma$ros is a $ommon strategy "or su!!orting both ty!es o" ma!!ings( o determine the ma!!ing "or ea$h individua# hardware resour$e, a driver ins!e$ts the resour$e #ists !assed in the )30KMNK- 53 KDE+)@E re*uest( 3esour$es o" ty!e Cm6eso!rce%y(eMemory are memory&ma!!ed, and resour$es o" ty!e Cm6eso!rce%y(e$ort are )1;&ma!!ed( Ea$h resour$e has a starting address and a #ength( Drivers shou#d !arse and save the trans#ated resour$e #ists in the devi$e e2tension, and then use the trans#ated resour$es to read and write devi$e registers( Most drivers do not need the raw resour$es( he resour$e #ist a#so $ontains a set o" "#ags that !rovide additiona# in"ormation about the assigned resour$es( For )1;&ma!!ed resour$es, the "#ags indi$ate the ty!e o" de$oding that the devi$e !er"orms and whether the devi$e de$odes 40, 42, or 48 bits o" the !ort address( For memory&ma!!ed resour$es, the "#ags indi$ate whether the memory $an be read, written, or bothM whether it is $a$hed or write& $ombinedM whether it $an be !re"et$hedM and whether the devi$e uses 26&bit addressing( o read or write a register in )1; s!a$e by using the 3E5DK0;3 K !! and W3) EK0;3 K !! ma$ros, a driver shou#d $ast the !ort address to a !ointer o" ty!e 0+;)D or 0=@B53 Ci" !ointer addition is re*uiredD( For e2am!#e:
PortPointer B $PVOID&$2 ON0!P#R&ResourceI;u:Port:"t3rt:Nu3-P3rt
<e"ore reading or writing a resour$e in memory s!a$e, the driver must $a## MmMa( o'(ace to get a virtua# address "or the trans#ated !hysi$a# address( he driver then must use the returned virtua# address in $a##s to the 3E5DK3E?)- E3K !! and W3) EK3E?)- E3K !! ma$ros( 3emember that the driver shou#d use the $orre$t ty!e o" !ointer "or the data to be read or written with the 0;3 and 3E?)- E3 ma$ros( For e2am!#e, a driver shou#d use 0=@B53 to read or write an unsigned $hara$ter, 0=-B;3 "or a short integer, and so "orth( he "o##owing e2am!#e shows how a driver gets the resour$es that have been assigned to its devi$e( he driver re$eives the trans#ated resour$e #ist in the start& devi$e )30 at 0arameters(-tartDevi$e(5##o$ated3esour$es rans#ated( he va#ue at this #o$ation !oints to a @MK3E-;=3@EK7)- that des$ribes the hardware resour$es that the 0#ug and 0#ay manager assigned to the devi$e( he base address registers C<53sD are a#ways returned in order(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 2/
)n the sam!#e, the driver !arses the resour$e #ist to determine whether its $ontro# and status registers are ma!!ed to )1; s!a$e CCm6eso!rce%y(e$ortD or memory CCm6eso!rce%y(eMemoryD( )t then sets !ointers to the ma$ros it wi## use to a$$ess the registers in its devi$e e2tension at FdoData&U3ead0ort and FdoData&UWrite0ort(
,3rti35Resource ist#r3ns53te- B Hst3c8I;P3r3meters:"t3rtDeJice: /55oc3te-Resources#r3ns53te-I; ist[(]: P3rti35Resource ist; resource#r3ns B H,3rti35Resource ist#r3ns53te-I;P3rti35Descri,tors[(]; for $i B (; i 6 ,3rti35Resource ist#r3ns53te-I;.ount; i''% resource#r3ns''& { sMitc7 $resource#r3nsI;#+,e& { c3se .mResource#+,ePortO @@ #7e contro5 3n- st3tus $."R& reCisters @@ 3re in ,ort s,3ce: @@ "3Je t7e b3se 3--ress 3n- 5enCt7: F-oD3t3I;Io=3se/--ress B $PVOID&$2 ON0!P#R&$ resource#r3nsI;u:Port:"t3rt:Nu3-P3rt&; F-oD3t3I;IoR3nCe B resource#r3nsI;u:Port: enCt7; @@ /55 3ccesses 3re 2"<OR# Mi-e% so @@ cre3te 3n 3ccessor t3b5e to re3- 3n- Mrite @@ t7e ,orts: F-oD3t3I;Re3-Port B RE/D!POR#!2"<OR#; F-oD3t3I;WritePort B WRI#E!POR#!2"<OR#; bre38; c3se .mResource#+,eAemor+O @@ #7e ."R reCisters 3re in memor+ s,3ce: @@ #7is -eJice rePuires 3 ."R memor+ s,3ce t73t @@ is (x1((( in si*e: /ssert if itLs not: @@ /""ER#$resource#r3nsI;u:Aemor+: enCt7 BB (x1(((&; @@ #7e -riJer c3n re3- 3n- Mrite reCisters in @@ memor+ s,3ce b+ usinC t7e RE/D!RE0I"#ER!) @@ m3cros: F-oD3t3I;Re3-Port B RE/D!RE0I"#ER!2"<OR#; F-oD3t3I;WritePort B WRI#E!RE0I"#ER!2"<OR#; @@ "3Je t7e st3rtinC 3--ress: F-oD3t3I;AemP7+s/--ress B resource#r3nsI;u:Aemor+:"t3rt; @@ @@ @@ @@ @@ @@ A3, t7e returne- ,7+sic35 3--ress to 3 Jirtu35 3--ress: We c3n use t7e V/ to c355 c355 RE/D!RE0I"#ER) 3n- WRI#E!RE0I"#ER) m3cros: We c3n 35so -efine t7e ."R/--ress structure t73t m3,s on to, of t7e reCisters: We c3n t7en re3- 3n- Mrite reCisters -irect5+ b+ n3me:
February 28, 2005
F-oD3t3I;."R/--ress B AmA3,Io",3ce$ resource#r3nsI;u:Aemor+:"t3rt% resource#r3nsI;u:Aemor+: enCt7% AmNon.3c7e-&; if $F-oD3t3I;."R/--ress BB N2 & { DebuCPrint$ERROR% D=0!INI#% FAmA3,Io",3ce f3i5e-GnF&; st3tus B "#/#2"!IN"2FFI.IEN#!RE"O2R.E"; } bre38; }
)" the registers are in !hysi$a# memory s!a$e, the driver $a##s MmMa( o'(ace to ma! them into system&s!a$e virtua# memory( -!e$i"ying non$a$hed memory is im!ortant to ensure that new va#ues are immediate#y written to the devi$e, without being he#d in the !ro$essor $a$he( @ontro# and status registers shou#d a#ways be ma!!ed un$a$hed( ;n&board memory $an be ma!!ed $a$hed, un$a$hed, or un$a$hed1write&$ombined, de!ending on how it wi## be used( 5s an a#ternative to using the 3E5DK3E?)- E3K !! and W3) EK3E?)- E3K !! ma$ros to read and write the registers, you $an de"ine a stru$ture that mat$hes the register #ayout and then read and write the "ie#ds o" that stru$ture( )n the !re$eding sam!#e, the stru$ture at FdoData&U@-35ddress is de"ined "or this !ur!ose( )" the order in whi$h you set bits in the registers is im!ortant, you shou#d de$#are the register "ie#ds o" the stru$ture as volatile to !revent $om!i#er reordering o" read and write instru$tions( De!ending on e2a$t#y what a !arti$u#ar $ode se*uen$e does, you might a#so need to use memory barriers to !revent some hardware ar$hite$tures "rom reordering memory a$$ess( Bow to use both the volatile %eyword and memory barriers is des$ribed in HMu#ti!ro$essor @onsiderations "or Kerne#&mode Drivers,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er( he sam!#e $ode saves !ointers to the ma$ros it wi## use to read and write the registers in its devi$e e2tension( )n most $ases, this te$hni*ue wor%s be$ause the 0;3 and 3E?)- E3 ma$ros have the same semanti$s( For e2am!#e, 3E5DK0;3 K=-B;3 and 3E5DK3E?)- E3K=-B;3 o!erate in the same way on a## !#at"orms( Bowever, 3E5DK0;3 K<=FFE3K=@B53 and 3E5DK3E?)- E3K<=FFE3K=@B53 are e2$e!tions( ;n some !#at"orms, 3E5DK0;3 K<=FFE3K=@B53 u!dates the !ort address a"ter it reads a byte, but on others it does not( o wor% around this issue, avoid using both o" these ma$ros( )nstead, $a## 3E5DK0;3 K=@B53 or 3E5DK3E?)- E3K=@B53 in a #oo! unti# the !ro$essor has read the $orre$t number o" bytes(
4 Accessing Memory .or DE 7!..ers

For some ty!es o" )1;, the )1; manager a##o$ates bu""ers and ma!s them "or use by the driver( For others, the driver must !er"orm additiona# ma!!ing( <u""ered )1; re*uests CD;K<=FFE3EDK); and ME B;DK<=FFE3EDD in$#ude a !ointer to a system&s!a$e bu""er that $ontains a $o!y o" the data that was !assed in the $a##erGs user&s!a$e bu""er( he driver $an read and write to the bu""er dire$t#y through this !ointer( he driver does not need to a##o$ate bu""er s!a$e( Dire$t )1; re*uests CD;KD)3E@ K);, ME B;DK)NKD)3E@ , ME B;DK;= KD)3E@ , ME B;DKD)3E@ K ;KDE+)@E, and ME B;DKD)3E@ KF3;MKDE+)@ED in$#ude an MD7 that des$ribes a user&s!a$e bu""er that has been #o$%ed into !hysi$a# memory( he MD7 ma!s the virtua#
February 28, 2005
addresses in user s!a$e to the !ro$essor&re#ative !hysi$a# addresses that des$ribe the bu""er( o read or write to the bu""er, the driver $an use the user&s!a$e bu""er !ointer on#y whi#e it is running in the $onte2t o" the $a##ing !ro$ess, and it must ta%e measures to !revent se$urity brea$hes( y!i$a##y, however, the driver is running in an arbitrary !ro$ess $onte2t and must instead use system s!a$e virtua# addresses( o obtain the system&s!a$e virtua# addresses that $orres!ond to the addresses in the MD7, the driver !asses the MD7 !ointer to Mm9et'ystemAddress,orMdl'a.e( he returned va#ue is a system&s!a$e virtua# address through whi$h the driver $an a$$ess the bu""er( 3e*uests "or neither bu""ered nor dire$t )1; CME B;DKNE) BE3D in$#ude an unva#idated !ointer to a bu""er in user s!a$e( )" the driver wi## a$$ess the bu""er on#y "rom the $onte2t o" the re*uesting user&mode thread, it $an do so through the user& s!a$e address Cthe !ointerDJbut on#y a"ter va#idating the address and a$$ess method and on#y within an e2$e!tion hand#er( )" the driver wi## a$$ess the bu""er "rom an arbitrary thread $onte2t, it shou#d $reate an MD7 to des$ribe the bu""er, va#idate the user&s!a$e address, #o$% the bu""er into the !hysi$a# address s!a$e, and then ma! the bu""er into system s!a$e( 5#though the dis!at$h routines o" many drivers run in the $onte2t o" the $a##ing thread, you $an assume that this is true on#y in "i#e&system drivers and other highest&#eve# drivers( )n other drivers, you must a$*uire a system&s!a$e virtua# address "or the user&s!a$e bu""er( For more in"ormation about the $onte2t in whi$h s!e$i"i$ standard driver routines are $a##ed, see H-$hedu#ing, hread @onte2t, and )3O7,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er( 5 driver that a$$esses a user&mode bu""er in the $onte2t o" the user&mode thread must do so $are"u##y to avoid $orru!ting memory and $ausing system $rashes( he driver must wra! a## attem!ts to a$$ess the bu""er in an e2$e!tion hand#er be$ause another thread might "ree the bu""er or $hange the a$$ess rights whi#e the driver is a$$essing it( Furthermore, the driver must a$$ess the bu""er on#y at )3O7 05--)+EK7E+E7 or 50@K7E+E7 be$ause the !ages in the bu""er are not #o$%ed into memory( o va#idate the bu""er, the driver $a##s $robe,or6ead or $robe,orWrite, !assing a !ointer to the bu""er, its #ength, and its a#ignment( <oth o" these ma$ros raise a - 5 =-K5@@E--K+);75 );N e2$e!tion i" the address and #ength do not s!e$i"y a va#id range in user s!a$e and a - 5 =-KD5 5 A0EKM)-57)?NMEN e2$e!tion i" the beginning o" the address range is not a#igned on the s!e$i"ied byte boundary( )n addition, $robe,orWrite raises the - 5 =-K5@@E--K+);75 );N e2$e!tion i" the bu""er is not avai#ab#e "or write a$$ess( he "o##owing e2am!#e shows how a driver that is running in the $onte2t o" the user& mode !ro$ess $an va#idate "or read a$$ess a bu""er that is !assed in an );@ 7 re*uest:
in=uf B ir,",I;P3r3meters:DeJiceIo.ontro5:#+,eQIn,ut=uffer; in=uf enCt7 B ir,",I;P3r3meters:DeJiceIo.ontro5:In,ut=uffer enCt7; tr+ { ProbeForRe3-$ in=uf% in=uf enCt7% si*eof$ 2.</R & &; } exce,t$EX.EP#ION!EXE.2#E!</ND ER& { nt"t3tus B 0etExce,tion.o-e$&; "IO.# !?DPRIN#$$ FExce,tion M7i5e 3ccessinC in=uf (XR(SX in T TAE#<OD!NEI#<ERGnF%
February 28, 2005
nt"t3tus&&; bre38; }
+a#idating the bu""er on$e u!on re$eiving the )1; re*uest is not enough( he driver must en$#ose every a$$ess in an e2$e!tion hand#er and use $robe,or6ead or $robe,orWrite be"ore reading or writing the bu""er( Most drivers, however, $annot de!end u!on being in the user !ro$ess $onte2t when they read or write a bu""er that was !assed in an );@ 7( 5ny driver that might need to a$$ess the bu""er "rom an arbitrary thread $onte2t must ma! the bu""er into system s!a$e as "o##ows: 4( 5##o$ate and initia#i>e an MD7 that is #arge enough to des$ribe the bu""er( 2( @a## Mm$robeAnd-oc:$ages to !robe the bu""er "or va#idity and a$$ess mode( )" the bu""er is va#id, Mm$robeAnd-oc:$ages #o$%s its !ages into memory( .( Ma! the #o$%ed !ages into system s!a$e by $a##ing Mm9et'ystemAddress,orMdl'a.e( Even though the !ages are resident in memory, the driver must a$$ess them through a system&s!a$e address be$ause the user&s!a$e address $ou#d be$ome inva#id at any time either be$ause o" #egitimate system a$tions Csu$h as trimming the !age "rom the wor%ing setD or inadvertent or ma#i$ious user a$tions Csu$h as de#eting the bu""er in another threadD( he "o##owing e2am!#e shows how to !er"orm these ste!s:
@@ @@ @@ @@ @@ @@ /55oc3te AD % ,3ssinC t7e Jirtu35 3--ress su,,5ie- in t7e IRP% its 5enCt7% F/ "E to in-ic3te t73t it is not 3 secon-3r+ buffer% #R2E to in-ic3te t73t t7e ,3Ces s7ou5be c73rCe- 3C3inst t7e Puot3 of t7e rePuestinC ,rocess% 3n- N2 to in-ic3te t73t t7e AD is not -irect5+ 3ssoci3te- Mit7 3n I@O rePuest: &;
m-5 B Io/55oc3teA-5$in=uf% in=uf enCt7% F/ "E% #R2E% N2 if$Um-5& { nt"t3tus B "#/#2"!IN"2FFI.IEN#!RE"O2R.E"; return; } tr+ { AmProbe/n- oc8P3Ces$m-5% 2serAo-e% IoRe3-/ccess&; } exce,t$EX.EP#ION!EXE.2#E!</ND ER& { nt"t3tus B 0etExce,tion.o-e$&; "IO.# !?DPRIN#$$ FExce,tion M7i5e 5oc8inC in=uf (XR(SX in F FAE#<OD!NEI#<ERGnF% nt"t3tus&&; IoFreeA-5$m-5&; }
@@ @@ A3, t7e ,7+sic35 ,3Ces -escribe- b+ t7e AD into s+stem @@ s,3ce: Note t73t m3,,inC 3 53rCe buffer t7is M3+ @@ incurs 3 5ot of s+stem oJer7e3-: @@ buffer B
February 28, 2005
Am0et"+stem/--ressForA-5"3fe$m-5% Norm35P3CePriorit+ &; if$Ubuffer& { nt"t3tus B "#/#2"!IN"2FFI.IEN#!RE"O2R.E"; Am2n5oc8P3Ces$m-5&; IoFreeA-5$m-5&; }
he bu""er !ointer that Mm9et'ystemAddress,orMdl'a.e returns is a va#id system&s!a$e !ointer to the userGs bu""er( <e$ause the !ages in the bu""er are resident C#o$%edD in memory, the driver $an now a$$ess them without an e2$e!tion hand#er( When the driver has "inished using the bu""er, it must un#o$% the !ages and "ree the MD7, as "o##ows:
Am2n5oc8P3Ces$m-5&; IoFreeA-5$m-5&;
he driver must $a## these "un$tions in the order shown( Freeing the MD7 be"ore un#o$%ing the !ages $ou#d resu#t in a system $rash be$ause the #ist o" !ages to be un#o$%ed is "reed a#ong with the MD7 and is thus not guaranteed to be a$$essib#e a"ter the o,reeMdl has returned(
"5 Ma((ing Device Memory and 6egisters into 1ser '(ace

5s a genera# ru#e, drivers shou#d avoid ma!!ing devi$e memory and registers into user s!a$e( )nstead, drivers shou#d share memory with user&mode $om!onents on#y through ma!!ed bu""ers Cty!i$a##y !assed in );@ 7sD, as shown in the ME B;DKNE) BE3 )1; e2am!#e ear#ier in this !a!er( E2!osing hardware to user&mode $ontro# is ris%y and !oses !otentia# threats to system se$urity( Doing so re*uires signi"i$ant#y more $ode than wou#d be re*uired i" a$$ess were stri$t#y #imited to %erne# mode, and it re*uires additiona# attention to se$urity issues( )" your reason "or su$h a design is to im!rove !er"orman$e, $onsider this de$ision $are"u##y( he transition to %erne# mode does not re*uire mu$h overhead when $om!ared to the additiona# $oding, debugging, and testing that are invo#ved with user&mode a$$ess( =ser&mode !ro$esses $annot be trusted( he additiona# $ode is re*uired "or the "o##owing reasons: he hardware register inter"a$es must be $om!#ete#y se$ure be"ore they are e2!osed in user mode( Aou must $are"u##y ana#y>e the hardware to determine how a user&mode a!!#i$ation might use the e2!osed inter"a$es( 3emember to $onsider every !ossib#e o!tionJin$#uding both in$orre$t and intentiona##y ma#i$ious misuse( hen you must ensure that you do not e2!ose any !aths through whi$h a user&mode a!!#i$ation $ou#d $ause the bus to hang, !er"orm DM5 into random areas o" memory, or $rash the system "or any other reason( 5 user&mode !ro$ess might du!#i$ate the hand#e to the a##o$ated memory into another !ro$ess, whi$h $an then issue )1; re*uests( o !rote$t against ma#i$ious user a!!#i$ations, the driver must $he$% every )1; re*uest to ensure that it $ame "rom the !ro$ess into whi$h the memory was origina##y ma!!ed( )n addition, the driver must ta%e additiona# ste!s to ensure that it is noti"ied when the origina# !ro$ess ends, even i" another !ro$ess sti## has an o!en hand#e to the ma!!ed memory(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 3"
he driver must unma! the memory when the user&mode !ro$ess e2its, and it must syn$hroni>e the unma!!ing o!eration with other )1; o!erations on the hand#e( Bibernation and sto!&devi$e re*uests re*uire additiona# hand#ing so that the driver $an unma! the memory i" the user&mode a!!#i$ation has not $#osed its hand#e(
"" 'hared Memory and 'ynchroni@ation

Many drivers share memory with other $om!onents( For e2am!#e: 5dEa$ent drivers in the same sta$% might share memory ma!!ed "or their devi$e( 5 driver might $reate a wor%er thread that uses $onte2t in"ormation or memory #o$ations that are a#so a$$essed e#sewhere in the driver( 5 driver might need to share a bu""er with a user&mode a!!#i$ation(
)n addition, any driver routines that are reentrant or $an run $on$urrent#y might share memory( )n a## su$h situations, the driver must ensure the integrity o" the data by syn$hroni>ing a$$ess to the shared #o$ations( he most a!!ro!riate syn$hroni>ation te$hni*ue de!ends on how the memory is used and whi$h other $om!onents use it( For a $om!#ete des$ri!tion o" the syn$hroni>ation te$hni*ues "or %erne#&mode $om!onents, see H7o$%s, Dead#o$%s, and -yn$hroni>ation,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er( )n addition, some drivers must share memory with user&mode $om!onents( =ser& mode $om!onents $annot a##o$ate virtua# memory in the system address s!a$e( 5#though it is !ossib#e to ma! system&s!a$e addresses into user s!a$e, drivers shou#d avoid doing so "or se$urity reasons( Drivers and user&mode $om!onents must use other strategies "or sharing memory( HManaging =ser&Mode )ntera$tions: ?uide#ines "or Kerne#&Mode DriversI des$ribes s!e$i"i$ te$hni*ues "or sharing bu""ers and se$tion obEe$ts with user&mode $om!onents( his !a!er is #isted in the 3esour$es se$tion at the end o" this !a!er(
"2 %esting and %ro!bleshooting

<ugs re#ated to memory a$$ess and a##o$ation are $ommon, but they $an be di""i$u#t to "ind( -ym!toms $an range "rom a gradua# s#owing o" system !er"orman$e be$ause o" memory #ea%s to an abru!t $rash i" a driver attem!ts to a$$ess !aged memory at the wrong )3O7( @rashes $aused by su$h bugs $an o$$ur #ong a"ter a driver a$$esses an inva#id #o$ation( @orru!ted memory $an $ause errors and $rashes in !ro$esses that are $om!#ete#y unre#ated to the o""ending driver( -ome o" the most $ommon memory&re#ated errors invo#ve the "o##owing: 5ttem!ts to a$$ess memory that has a#ready been "reed( 5ttem!ts to a$$ess beyond the end o" a##o$ated memory Cmemory and bu""er overrunsD( 5ttem!ts to a$$ess be"ore the start o" a##o$ated memory Cmemory and bu""er underrunsD( 5ttem!ts to a$$ess !aged memory at )3O7 D)-05 @BK7E+E7 or higher(
February 28, 2005
Fai#ure to "ree memory Cmemory #ea%sD( Freeing the same memory twi$e(
Fai#ure to $he$% the status a"ter attem!ting to a##o$ate or re"eren$e memory(
"2&"
%ools .or Discovering Memory-6elated Errors
Many o" the too#s !rovided with the Windows DDK o""er "eatures s!e$i"i$a##y designed to "ind memory&re#ated errors( For e2am!#e: Driver +eri"ier Driver +eri"ier has o!tions to use the %erne# s!e$ia# memory !oo#, tra$% memory !oo# usage, $he$% DM5 o!erations, and simu#ate #ow&resour$e situations( ?#oba# F#ags C?F#agsD ?F#ags sets "#ags that enab#e !oo# tagging, !rovide "or bu""er overrun and underrun dete$tion, and s!e$i"y tags "or memory a##o$ations "rom the %erne# s!e$ia# !oo#( @a## =sage +eri"ier C@=+D @=+ $he$%s to ensure that data stru$tures that must be in non!aged memory are a$tua##y there( 0oo#Mon and 0oo# ag 0oo#Mon and 0oo# ag gather and dis!#ay data about memory a##o$ations( ra$%ing this data $an he#! you to "ind memory #ea%s( 03E"ast with driver&s!e$i"i$ ru#es 03E"ast $an dete$t !otentia# errors in sour$e $ode by simu#ating e2e$ution o" a## !ossib#e $ode !aths on a "un$tion&by&"un$tion basis( Errors dete$ted by 03E "ast in$#ude memory and resour$e #ea%s, e2$essive sta$% use, and in$orre$t usage o" numerous %erne#&mode "un$tions( he best way to test your driver is to use a## o" these too#s re!eated#y, both inde!endent#y and in $ombination( =sing @=+ with Driver +eri"ier $an be !arti$u#ar#y use"u#( Aou shou#d a#so test on various memory $on"igurations( o $hange the memory $on"iguration o" the test system, you $an use various boot !arameters( he 1.?< swit$h e2!ands user s!a$e to . ?<, #eaving on#y 4 ?< "or a## %erne#& mode $om!onents( ;n 286 and )tanium systems, and on 288 systems that have 05E enab#ed and more than 5 ?< o" !hysi$a# memory, the 1no#owmem swit$h #oads the system, drivers, and a!!#i$ations into memory above the 6&?< boundary( esting under these $onditions he#!s you $he$% "or errors that are re#ated to address trun$ation when using memory above 6 ?< and ina!!ro!riate re#ian$e on memory be#ow 6 ?<( he 1ma2mem and 1burnmemory swit$hes a#so #imit the memory avai#ab#e to the system by redu$ing the avai#ab#e memory by a s!e$i"i$ amount( he 1ma2mem swit$h $an be used with Windows 2000 or #ater versions o" Windows( he 1burnmemory swit$h is more !re$ise and $an be used with Windows /0 and #ater versions(
February 28, 2005
"2&2
7est $ractices .or $rogramming and %esting
?ood !rogramming and testing te$hni*ues $an he#! you !revent !rob#ems as we## as "ind them( he "o##owing shou#d be standard !ra$ti$es "or a## driver writers: 5#ways use !oo# tags when a##o$ating memory( Driver +eri"ier, ?F#ags, 0oo#Mon, and 0oo# ag use these tags in tra$%ing !oo# a##o$ations, and the debuggers dis!#ay a bu""erGs tag a#ong with its $ontents( +a#idate the #ength o" every bu""er be"ore a$$essing it( +a#idate every user&s!a$e address by !robing within an e2$e!tion hand#er(
@he$% the returned status every time you try to a##o$ate or a$$ess memory( Never assume that an o!eration $annot "ai#( )" an error o$$urs, return a "ai#ure status "rom the driver or modi"y and retry the o!eration i" a!!ro!riate( 3emember: i" an attem!t to a$$ess memory "ai#s be$ause o" an inva#id !ointer and your driver "ai#s to $at$h the error when it o$$urs, the driver $ou#d !ro!agate the addressing error, resu#ting in errors that a!!ear mu$h #ater and seem unre#ated to the driver( 5#ways use Driver +eri"ier( est every driver on both sing#e&!ro$essor and mu#ti!ro$essor hardware( <e$ause Windows treats hy!er&threaded !ro$essors as two @0=s, you $an !er"orm minima# mu#ti!ro$essor testing on a ma$hine with a sing#e hy!er& threaded !ro$essor( )n e""e$t, a dua#&!ro$essor hy!er&threaded ma$hine !rovides "our !ro$essors and serves as better test system( he new mu#ti$ore !ro$essors wou#d be an even better test system than the hy!er&threaded systems( For additiona# suggestions "or testing, see H esting "or Errors in 5$$essing and 5##o$ating MemoryI, whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er(
"3 '!mmary o. 9!idelines

he "o##owing is a summary o" guide#ines "or memory a##o$ation and usage in %erne#&mode drivers( Do not ma%e assum!tions about the hardware !#at"orm, the !ointer si>e, or the #o$ation or si>e o" the virtua# address s!a$es( Ma%e your driver !#at"orm& inde!endent by using ma$ros, ty!es, and system&de"ined $onstants, su$h as 0BA-)@57K5DD3E--, 05?EK-)LE, and so "orth( 7ay out data stru$tures e""i$ient#y, $onsidering natura# and $a$he&#ine a#ignment and the !ro$essor !age si>e( When !ossib#e, reuse a##o$ated data stru$tures( For more in"ormation about using memory e""i$ient#y, see H-i2 i!s "or E""i$ient Memory =se,I whi$h is #isted in the 3esour$es se$tion at the end o" this !a!er( 5##o$ate on#y as mu$h memory as your devi$e and driver re*uire "or norma# o!erations( 5#ways $he$% the trans#ated resour$es to determine whether your devi$e registers are ma!!ed into memory or )1; s!a$e( Do not a##o$ate e2$essive amounts o" memory that your driver might never use( Aour devi$e must $oe2ist with other hardware and a!!#i$ations( =se the systemGs DM5 routines( 3e!#a$ing them with your own routines is a#most guaranteed to $ause your driver to "ai# on some hardware $on"igurations(
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 3)
=se #oo%aside #ists when your driver needs "i2ed&si>e, reusab#e bu""ers(
est your driver with as many di""erent too#s, and on as many di""erent hardware $on"igurations, as !ossib#e(
") 6eso!rces
Windows DDK htt!:11www(mi$roso"t($om1whd$1devtoo#s1dd%1de"au#t(ms!2 Kernel-Mode Driver Architect!re Design 9!ide Memory Management -yn$hroni>ation e$hni*ues Driver 0rogramming e$hni*ues CH86&bit )ssuesID Kernel-Mode Driver Architect!re 6e.erence -tandard Driver 3outines Driver -u!!ort 3outines Driver Develo(ment %ools <oot ;!tions "or Driver esting and Debugging oo#s "or esting Drivers CQDriver +eri"ier,Q Q?F#ags with 0age Bea! +eri"i$ation,Q and Q0oo#MonQD A((endi; 0ro$essor&-!e$i"i$ )n"ormation Kernel-Mode ,!ndamentals -$hedu#ing, hread @onte2t, and )3O7 htt!:11www(mi$roso"t($om1whd$1driver1%erne#1)3O7(ms!2 7o$%s, Dead#o$%s, and -yn$hroni>ation htt!:11www(mi$roso"t($om1whd$1driver1%erne#1#o$%s(ms!2 Mu#ti!ro$essor @onsiderations "or Kerne#&Mode Drivers htt!:11www(mi$roso"t($om1whd$1driver1%erne#1M0Kissues(ms!2 DMA DM5 -u!!ort in Windows Drivers htt!:11www(mi$roso"t($om1whd$1driver1%erne#1dma(ms!2 'haring Memory with 1ser-Mode =ser&Mode )ntera$tions: ?uide#ines "or Kerne#&Mode Drivers htt!:11www(mi$roso"t($om1whd$1driver1%erne#1KM&=M?uide(ms!2 %esting esting "or Errors in 5$$essing and 5##o$ating Memory htt!:11www(mi$roso"t($om1whd$1driver1se$urity1mem&a##o$Ktst(ms!2 $er.ormance -i2 i!s "or E""i$ient Memory =se htt!:11www(mi$roso"t($om1whd$1driver1!er"orm1mem&a##o$(ms!2 M'DN FWindows Data Alignment on $,0 ;3/0 and ;3/-/)G htt!:11msdn(mi$roso"t($om1#ibrary1de"au#t(as!Vur#W1#ibrary1en& us1dvKvste$hart1htm#1v$$onWindowsData5#ignment;n)0F/88/88&86(as! Windows +ardware and Driver Central )n$#udes Windows Driver Deve#o!ment Kits CDDKD, Windows Bardware @om!atibi#ity est CB@ D Kits, and Windows 7ogo 0rogram re*uirements htt!:11www(mi$roso"t($om1whd$1de"au#t(ms!2
February 28, 2005
Memory Management: What Every Driver Writer Needs to Know - 3*
7oo:s nside Microso.t Windows 25550 %hird Edition -o#omon, David 5( and Mar% 3ussinovi$h( 3edmond, W5: Mi$roso"t 0ress, 2000(
February 28, 2005

Memory Management: What Every Driver Writer Needs To Know: February 28, 2005

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Memory Management: What Every Driver Writer Needs To Know: February 28, 2005

Uploaded by

Copyright:

Available Formats

Memory Management: What Every Driver Writer Needs to Know

February 28, 2005

Memory Management: What Every Driver Writer Needs to Know - 2

February 28, 2005

Memory Management: What Every Driver Writer Needs to Know - 3

" #irt!al and $hysical Memory

February 28, 2005