amd64 pmap: explain pteindex

[kib]

Summary

Add description of how the page table pages are numbered by pmap_allocpte().

[markj]

sys/amd64/amd64/pmap.c

3811

"The page index of the PTE at address va is defined as follows" would be more clear to me.

3813

Duplicate '='

3820

s/is it/it is/

3821

If I understand this correctly, "height" might be clearer than "rank" in the context of a tree.

[kib]

sys/amd64/amd64/pmap.c

3811

IMO it is too vague. I used the basis of your sentence, but extended it as following:

* The page index of the page containing PTE at address va is defined
* as follows:

3813

It was a split formula, I reformatted to move formulas to display to avoid line break.

[kib]

Handle the first round of comments.

[markj]

sys/amd64/amd64/pmap.c

3811

It should be "the PTE".

"the page" sounds like there is a unique page, but really we are talking about each PTP in the hierarchy. So maybe: "The page indices of the page table pages encountered while translating virtual address va are defined as follows:"

3813

Should it be, "for the page table page (last level)"?

For the other entries, we are missing "the" as well.

3826

Maybe clarify also that the PML4 page always has pindex 0?

[kib]

sys/amd64/amd64/pmap.c

3826

PML4 page does not have index for the purpose of _pmap_allocpte() which uses this numbering. The PML4 page is statically allocated at the pinit() time.

In fact, the pteindex 0 is assigned to the pte which maps at zero.

[markj]

sys/amd64/amd64/pmap.c

3826

Indeed, I just thought it would be useful to clarify this fact for completeness.

[kib]

Change herald sentence as suggested by Mark. Add articles.

[kib]

Separately mention the root page.

[alc]

sys/amd64/amd64/pmap.c

3818–3819

What follows will be clearer if this sentence explicitly defines ptepindex as the page index of a page table page.

3822

"... the PDE that maps the page table page."

3831–3833

I think that this sentence is hard to understand.

[kib]

Alc suggestions.

[markj]

sys/amd64/amd64/pmap.c

3818

There should be a comma after "page indices", otherwise it is not really clear what "i.e." refers to.

[kib]

comma