The !pfn Debugger Extension Command

The !pfn command takes one documented parameter and dumps the corresponding MMPFN structure. Microsoft documents that the command can dump the entire page frame database but does not document how: !pfn 0 1 does it in all known versions. Some other undocumented incantations may be useful. Some are defective.

It will surprise nobody that Microsoft’s seemingly substantial Debugger Reference (still helpfully included with the debugger for offline use) omits very much that Microsoft’s debuggers can do. What may surprise is how old an undocumented feature can be yet remain undocumented. This undocumented functionality that this note presents of the !pfn command dates from the debugger as supplied with the Device Driver Kit (DDK) for Windows NT 3.51 and may be even older, no earlier kernel-mode debugger having yet been obtained for inspection.

Can this really have gone unnoticed for so long? Much of the point to debugger extension commands is that they’re easy to use. They are just as easily used differently from what’s documented. Where a command is documented as taking one argument, as is !pfn, it must sometimes happen that programmers enter a second argument by accident if not just for fun or mischief. If the command then behaves differently, and especially if it produces something useful, news of it soon circulates as folklore. Surely?

For the !pfn command in particular, Microsoft itself gives a big hint that there’s something to look for. It’s even fair to say that Microsoft documents that the command can do something undocumented. Starting with the DDK for Windows XP, the !pfn documentation begins with the following one-line summary of what the command can do:

The !pfn extension displays information about a specific page frame or the entire page frame database.

Presumably, this sentence was not composed without someone at Microsoft having thought that dumping the entire page frame database may be useful (and without their being aware that this extra functionality had been undocumented). But then what’s given as the syntax is only

!pfn PageFrame

and the one argument is described as

Specifies the hexadecimal number of the page frame to be displayed.

Where then is the means of displaying information about the entire page frame database? The answer, of course, is that what Microsoft documents as the syntax is incomplete.

Syntax

!pfn PageFrame [Flags [Partition]]

Parameters

The PageFrame parameter is ordinarily a page frame number. It can instead be the address of an MMPFN structure if the Flags parameter is zero or is missing.

The Flags, for want of a better name, select from different methods of progressing through the database.

The Partition is the address of a memory partition object. This parameter is ignored unless Flags is non-zero.

Expression Evaluation

The MASM expression evaluator is forced for the first two parameters. The current expression evaluator is used for the third. For all, the expression can contain aliases.

Availability

The !pfn command is nowadays implemented in the KDEXTS.DLL debugger extension. It becomes a debugger extension command because KDEXTS exports its handler by name as the pfn function. This is true of all known versions, not just of KDEXTS since Windows XP but also of KDEXTX86.DLL from the Windows 2000 DDK and earlier. I do not, however, intend to track the changes of behaviour through all these versions. This note is prepared from inspection of KDEXTS version 10.0.16299.91, which I refer to below as this note’s reference version.

At the heart of the !pfn command is that it dumps the MMPFN structure. At the very least, the command requires that the debugger has the use of a symbol file for the kernel and that this symbol file has type information for nt!_MMPFN. This type information is present in all known public symbol files for the kernel starting from Windows 2000 SP3.

Less obvious is that although Microsoft documents the !pfn command as supported through KDEXTS in “Windows XP and later”, the !pfn command depends on memory-manager state that this note’s reference version of KDEXTS does not initialise unless the Windows build number at the target machine is at least 7600, i.e., unless the target machine is running Windows 7 or higher. Try to use the !pfn command when debugging an earlier version and you will be told

Target machine operating system not supported

Behaviour

As suggested by Microsoft’s one-line description, the !pfn command has two modes. Given one parameter, or zero as the second, the !pfn command dumps one MMPFN structure. Otherwise, the !pfn command dumps potentially very many MMPFN structures, including the whole of them.

Single Mode

For dumping one MMPFN structure, the !pfn command’s value relative to using the dt command to inspect the type directly is:

For any given page frame number, the corresponding MMPFN can be located by using the page frame number as an index into an array whose address is given by the internal variable MmPfnDatabase. The debugger may instead know this address from the same-named KDDEBUGGER_DATA member. Before the 1607 release of Windows 10, programmers also have the shortcut of knowing that 64-bit Windows keeps its MMPFN array at the preset address 0xFFFFFA80`00000000.

If the PageFrame parameter is less than what the debugger knows for MmPfnDatabase, then it is a page frame number. Otherwise, it is interpreted as an address and the command dumps the MMPFN that contains this address. Either way, the command does not validate that the address it computes for the MMPFN is not beyond the MmPfnDatabase array.

The dump continues for multiple lines, necessarily including the following five:

    PFN pfn      at address mmpfn
    flink       flink     blink / share count blink     pteaddress pteaddr
    reference count ref     used entry count  used      cache     color color  Priority priority
    restore pte original  containing page pteframe  location   flagcodes
    flagtext

The first line tells which MMPFN is being dumped, both by the page frame number of the physical page that the MMPFN describes and by the address of the MMPFN itself. The remaining lines are resolved from members of the MMPFN:

Placeholder MMPFN Source Remarks
flink u1.Flink  
blink u2.Blink  
pteaddr PteAddress  
ref u3.e2.ReferenceCount  
used UsedPageTableEntries
OriginalPte.u.Soft.UsedPageTableEntries
x64 only
cache u3.e1.CacheAttribute plain-text representation, see below
color u4.PageColor
u3.e1.PageColor
 
priority u3.e3.Priority
u3.e1.Priority
 
original OriginalPte  
pteframe u4.PteFrame
PteFrame
 
location u3.e1.PageLocation plain-text representation, see below
flagcodes various single-character codes, see below
flagtext various plain-text representations, see below

See that the command resolves some fields from alternative locations in the MMPFN structure. This is a heavily overloaded structure which Microsoft has evidently been determined should not grow. Over the nearly 20 years of Windows versions that the !pfn command is documented as supporting, many of the MMPFN members have moved around, even in terms of the symbols that are needed for referring to them programmatically. For all the convenience of this command’s sparing the programmer from the details, there is the occasional oversight (whether of the coding or of getting “Windows XP and later” updated in the documentation): before version 6.0, the priority would need to be found from u4.Priority.

The 2-bit CacheAttribute takes its values from the MI_PFN_CACHE_ATTRIBUTE enumeration. What the !pfn command resolves these to for the cache placeholder is:

The 3-bit PageLocation takes its values from the MMLISTS enumeration. What the !pfn command resolves these to for the location placeholder is:

The location is specially important for interpreting what shows for flink and blink. A location other than Active and Trans means that the MMPFN is in one or another list. The flink and blink then are page frame numbers of the next and previous MMPFN in the same list. For pages whose location is Active or Trans, the four or eight bytes that hold the u1.Flink and u2.Blink members are available for other use, hence their definitions as members of unions. The most notable other use is indicated by the output’s header: the blink may instead be a share count. However, the output does not get this share count from the u2.ShareCount member. What shows for flink and blink is only ever obtained from u1.Flink and u2.Blink. In recent versions, one (in 32-bit Windows) or both (in 64-bit) is only a bit field so that what shows for flink and blink is only a portion of what other use is made of the same space. This is problematic in 64-bit Windows since flink may show just the first 36 bits of a 64-bit pointer. To see the whole pointer, you must resort to some alternative such as dumping the MMPFN in detail by feeding its address to the dt command.

Eight single-bit MMPFN members are described in the flagcodes and flagtext placeholders, all but one in both:

Code Text Source
M Modified u3.e1.Modified
P Shared u4.PrototypePte
u3.e1.PrototypePte
R ReadInProgress u3.e1.ReadInProgress
W WriteInProgress u3.e1.WriteInProgress
E InPageError u3.e3.InPageError
u3.e1.InPageError
u4.InPageError
X ParityError u3.e3.ParityError
u3.e1.ParityError
Y RemovalRequested u3.e3.RemovalRequested
u3.e1.RemovalRequested
V VerifierAllocation u4.VerifierAllocation
u3.e1.VerifierAllocation
  LockedDown see below

Additional lines of output are possible between these two representations of 1-bit flags. Both are outside the present scope of this note. Information can be shown about the page’s inclusion in a memory partition, as determined from the u4.Partition member. Even more information, in this case about large and even huge pages, according to whether PteFrame has an indicative value, will not in practice be seen outside Microsoft, at least not by those of us who have only the public symbol files, since it requires type information for an internal variable named nt!MiLargePageSizes. (This also applies, by the way, to LockedDown in what is otherwise the plain-text representation of single-bit flags.)

Database Mode

When given a non-zero Flags parameter, the !pfn command displays one line of information for each of potentially very many page frames—including the whole of them, just as promised by Microsoft’s description. Zero for the PageFrame parameter has a conventional meaning of surveying the MmPfnDatabase from start to end in the straightforward order. Anything other than zero for the PageFrame is a page frame number from which to start the survey, which is then filtered in various ways depending on the starting page and on the Flags.

This note presently simplifies by ignoring that the Partition parameter can constrain the survey just to pages that belong to the given partition.

Whole

For the straightforward survey of the whole database, give zero for the PageFrame. The Flags are immaterial, except for zero and seven. The command !pfn 0 0 just dumps the MMPFN for page frame 0 as if Flags had been omitted. Since this MMPFN is empty, the dump is not useful (except as another way to obtain the base address of the MMPFN array). The command !pfn 0 7 attempts to follow an OriginalPte chain (see below) from this empty MMPFN for page frame 0, which becomes infinite.

When dumping the entire page frame database, successive MMPFN structures in the array are each described by one line, all under the one header:

 Page    Flink  Blk/Shr Ref V    PTE   Address  SavedPTE Frame  State
pfn   flink    blink   ref    pteaddr address original pteframe location flagcodes

This one-line dump for each MMPFN necessarily misses some of what is shown over multiple lines when asking about just one MMPFN. Apart from fields that are omitted entirely, there is also that the flagcodes in this one-line dump do not allow for Y or V. There is, however, an addition, even a useful one: the address is the one virtual address that maps to the physical page, if there is indeed just one, else is zero if the page is shared.

Dumping the whole of the page frame database can of course take very many minutes. Memory is fetched from the target in blocks of up to 2000 MMPFN structures. The dump is easily cancelled because the command checks for termination, e.g., through Ctrl-Break, after interpreting each structure.

Filtered

With a non-zero PageFrame and non-zero Flags, the survey is only of some of the database:

  1. PageFrame specifies a page at which to start;
  2. the dump is only of pages that have the same location as the starting page;
  3. Flags specifies an order in which to proceed through the database.

The selected MMPFN structures are each described by one line, all under the one header, as above except to append the priority (in decimal):

 Page    Flink  Blk/Shr Ref V    PTE   Address  SavedPTE Frame  State
pfn   flink    blink   ref    pteaddr mappedva original pteframe location flagcodes priority

If the starting page’s location is Active or Trans, the dump necessarily continues in increasing order of page frame number: Flags is ignored.

For any other location, the starting page is in a list and the dump can usefully follow the list’s links, either forwards or backwards. That the !pfn command can do this obviously very helpful work goes back at least to the implementation in the KDEXTX86.DLL from the DDK for Windows NT 3.51. In those simple days, the list is ordinarily followed forwards, with u1.Flink as the page frame number to proceed to, but backwards, using u2.Blink, if Flags is 3.

Nowadays, strong caution is in order. More values are recognised for the Flags, but some are coded defectively. The following summary is only of what seems to be intended:

Flags Description Requirements
1 (or any non-zero not below) forward through list  
2 forward through list but for the same NUMA node starting page has Standby as location;
target is 64-bit Windows build 8000 or higher
3 backward through list  
4 backward through list but for the same NUMA node starting page has Standby as location;
target is 64-bit Windows build 8000 or higher
5 forward through OriginalPte chain  
7 backward through OriginalPte chain  
9 up through PteFrame chain  

For cases 2 and 4 for Flags, failure to meet the Requirements produces the complaints:

PFN pfn is not a standby page

or

This build does not support per-NUMA-node standby lists
NUMA Node Links

Most defects seem to originate with the introduction of per-NUMA-node standby lists in advance of 64-bit Windows 8. These have their own forward and backward links, each split into high and low parts according to where they could be made to fit. What KDEXTS does to piece these links together has little in common with how the kernel (now) does it. The thinking here is that KDEXTS retains code that actually does work for some pre-release build of Windows 8 but which never got updated as the kernel’s implementation evolved. This might explain why KDEXTS depends on the MMPFN to have a member named StandbyBits which is shown in no public symbol file for any of the kernel versions that are known to this study. However this mismatch of interpretation came about, the practical result is that cases 1, 2, 3 and 4 for Flags are defective if the starting page’s location is Standby and the target is 64-bit Windows build 8000 or higher.

See that the following of the ordinary forward and backward links for standby pages is affected, not just of the per-NUMA-node links. To KDEXTS, interpretation of the Flink and Blink is signficantly different for pages on standby lists than for others. No evidence exists of interpretation through formally defined bit fields. The whole qwords of the Flink and Blink are each treated in two equal parts. The low and high words have respectively the high 32 bits of the ordinary link and the per-NUMA-node link. The low four bits of each link are found from a miscellany of other locations.

Link in Standby List Source of High 32 Bits Source of Low 4 Bits
ordinary forward link low 32 bits of Flink 4-bit StandbyBits
ordinary backward link low 32 bits of Blink 4-bit VaType
per-NUMA-node forward link high 32 bits of Flink low 4 bits of 8-bit ViewCount
per-NUMA-node backward link high 32 bits of Blink high 4 bits of 8-bit ViewCount

This is, incidentally, as good a reminder as any that internal detail surmised from a debugging aid is not certainly correct. Debugger extensions, in particular, are written separately from whatever component they have internal knowledge of. Such knowledge can be out of date, as here, or built differently. Examples are even known of incorrect type information in public symbol files, as with the PROCESSINFO and THREADINFO structures.

OrginalPte Chain

In the OriginalPte chain for cases 5 and 7 of the Flags, the OriginalPte.u.Long in one MMPFN is the page frame number of the next. This is not, of course, what the OriginalPte ordinarily holds. The circumstances in which the whole of it is a page frame number are not presently understood for recent Windows versions.

Given that an MMPFN does have an OriginalPte chain, following the chain backwards has no formal support. What KDEXTS does when Flags is 7 is to search the whole database from the start for the first MMPFN whose OriginalPte.u.Long is the page frame number to move backwards from. Presumably in anticipation of repeating this search and eventually of having to search to the end, giving 7 for Flags causes KDEXTS to fetch the whole of the page frame database from the target before even looking at the MMPFN for PageFrame. It fetches the database in blocks of up to 2000 MMPFN structures, just as when dumping the whole database, but instead of showing a header and dumping a line for each MMPFN, it instead shows one period for every 256 page frames, presumably to assure that progress is being made.

Unfortunately, the OriginalPte.u.Long in an MMPFN can be within range for a page frame number without being intended as one: if the !pfn command with 5 or 7 for Flags doesn’t stop with the start page, it typically hangs (needing termination by Ctrl-Break).

PteFrame Chain

See that the !pfn dump of a single MMPFN presents the u4.PteFrame (previously a direct PteFrame member) as a containing page. It’s only natural to ask for the containing page of the containing page and thence to make a PteFrame chain. Some hint of the usefulness is that Microsoft’s own example in the !pfn documentation shows two !pfn commands, one for the containing page of the other. Showing the PteFrame chain seems to be the intention when Flags is 9. The usefulness, however, is greatly diminished because successive pages in this chain will not have the same location and therefore don’t show in the dump. This does not matter in practice, though, because the dump is anyway defective. The chain must terminate at the highest level of the page mapping algorithm, but KDEXTS does not allow for this and so the !pfn dump with 9 for Flags hangs.