mm/pdx: Add comments throughout the codebase for pdx
PATCH v3 1/1 mm/pdx: Add comments throughout the codebase for pdx
Document the behaviour of the pdx machinery in Xen. Some logic is fairly opaque and hard to follow without it being documented anywhere. This explains the rationale behind compression and its relationship to frametable indexing and directmap management.
While modifying the file:
* Convert u64 -> uint64_t
* Remove extern keyword from function prototypes
No functional change.
---
v3:
* Exended the pdx=frametableindex definition also cover the directmap (to the extent that it still applies to every port)
* [pdx.c] Removed auxiliary variable and turned the case analysis comment into a full paragraph.
* [pdx.h] Removed stray sentence in pdx.h
* [pdx.h] Made example in pdx_region_mask() clearer
* [pdx.h] Clarified set_pdx_range() and pdx_init_mask()
--- xen/common/pdx.c | 59 +++++++++++++++++- xen/include/xen/mm.h | 11 ++++ xen/include/xen/pdx.h | 140 ++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 203 insertions(+), 7 deletions(-)
xen/common/pdx.c +56 -3
@@ -20,13 +20,56 @@#include <xen/bitops.h> #include <xen/nospec.h> -/* Parameters for PFN/MADDR compression. */ +/* +* Diagram to make sense of the following variables. The masks and shifts +* are done on mfn values in order to convert to/from pdx: +* +* pfn_hole_mask +* pfn_pdx_hole_shift (mask bitsize) +* | +* |---------| +* | | +* V V +* -------------------------- +* |HHHHHHH|000000000|LLLLLL| <--- mfn +* -------------------------- +* ^ ^ ^ ^ +* | | |------| +* | | | +* | | pfn_pdx_bottom_mask +* | | +* |-------| +* | +* pfn_top_mask +* +* ma_{top,va_bottom}_mask is simply a shifted pfn_{top,pdx_bottom}_mask, +* where ma_top_mask has zeroes shifted in while ma_va_bottom_mask has +* ones. +*/ + +/** Maximum (non-inclusive) usable pdx */ unsigned long __read_mostly max_pdx; + +/** Mask for the lower non-compressible bits of an mfn */ unsigned long __read_mostly pfn_pdx_bottom_mask = ~0UL ; + +/** Mask for the lower non-compressible bits of an maddr or vaddr */ unsigned long __read_mostly ma_va_bottom_mask = ~0UL ; + +/** Mask for the higher non-compressible bits of an mfn */ unsigned long __read_mostly pfn_top_mask =0 ; + +/** Mask for the higher non-compressible bits of an maddr or vaddr */ unsigned long __read_mostly ma_top_mask =0 ; + +/** +* Mask for a pdx compression bit slice. +* +* Invariant: valid(mfn) implies (mfn & pfn_hole_mask) == 0 +*/ unsigned long __read_mostly pfn_hole_mask =0 ; + +/** Number of bits of the "compressible" bit slice of an mfn */ unsigned int __read_mostly pfn_pdx_hole_shift =0 ; unsigned long __read_mostly pdx_group_valid[BITS_TO_LONGS(
@@ -42,7 +85,7 @@ bool __mfn_valid(unsigned long mfn) }/* Sets all bits from the most-significant 1-bit down to the LSB */ -static u64 __init fill_mask (u64 mask) +static uint64_t __init fill_mask (uint64_t mask) {while (mask & (mask +1 )) mask |= mask +1 ;
@@ -57,8 +100,18 @@ uint64_t __init pdx_init_mask(uint64_t base_addr) (uint64_t)1 << (MAX_ORDER + PAGE_SHIFT)) - 1); } -u64 __init pdx_region_mask (u64 base,u64 len) +uint64_t __init pdx_region_mask (uint64_t base,uint64_t len) { +/* +* We say a bit "moves" in a range if there exist 2 addresses in that +* range that have that bit both set and cleared respectively. We want +* to create a mask of _all_ moving bits in this range. We do this by +* comparing the first and last addresses in the range, discarding the +* bits that remain the same (this is logically an XOR operation). The +* MSB of the resulting expression is the most significant moving bit +* in the range. Then it's a matter of setting every bit in lower +* positions in order to get the mask of moving bits. +*/ return fill_mask (base ^ (base + len -1 )); }
xen/include/xen/mm.h +11 -0
@@ -31,6 +31,17 @@* (i.e. all devices assigned to) a guest share a single DMA address space * and, by default, Xen will ensure dfn == pfn. * +* pdx: Page InDeX +* Indices into the frame table holding the per-page's book-keeping +* metadata. A compression scheme may be used, so there's a possibly non +* identity mapping between valid(mfn) <-> valid(pdx). See the comments +* in pdx.c for an in-depth explanation of that mapping. This also has a +* knock-on effect on the directmap, as "compressed" pfns have no +* corresponding mapped frames. +* +* maddr: Machine Address +* The physical address that corresponds to an mfn +* * WARNING: Some of these terms have changed over time while others have been * used inconsistently, meaning that a lot of existing code does not match the * definitions above. New code should use these terms as described here, and
xen/include/xen/pdx.h +136 -4
171 lines not on this page · raw message
Signature · 1 line
2.34.1
xen/include/xen/mm.h line 40
Quoted 13 lines · Alejandro Vallejo
xen/include/xen/mm.h +7
-0@@ -31,6 +31,17 @@* (i.e. all devices assigned to) a guest share a single DMA address space * and, by default, Xen will ensure dfn == pfn. * +* pdx: Page InDeX +* Indices into the frame table holding the per-page's book-keeping +* metadata. A compression scheme may be used, so there's a possibly non +* identity mapping between valid(mfn) <-> valid(pdx). See the comments +* in pdx.c for an in-depth explanation of that mapping. This also has a +* knock-on effect on the directmap, as "compressed" pfns have no +* corresponding mapped frames.
Didn't you mean to keep the directmap part optional, which would call for saying "may" here (twice)? Yet then ...
Quoted 10 lines
xen/include/xen/pdx.h +4
-0@@ -1,6 +1,73 @@#ifndef __XEN_PDX_H__#define __XEN_PDX_H__ +/* +* PDX (Page inDeX) +* +* This file deals with optimisations pertaining to frame table and
xen/include/xen/pdx.h line 17
Quoted 10 lines
xen/include/xen/pdx.h +10
-0+* directmap indexing, A pdx is an index into the frame table, which +* typically also means an index into the directmap[1]. However, having an +* identity relationship between mfn and pdx could waste copious amounts of +* memory in empty frame table entries and page tables. There are some +* techniques to bring memory wastage down. +* +* [1] Some ports apply further modifications to a pdx before indexing the +* directmap. This doesn't change the fact that the same compression +* present in the frame table is also present in the directmap +* whenever said map is present.
.. you mention it here as non-optional as well. Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
Jan
Hi,
Quoted 16 lines · Jan Beulich
xen/include/xen/mm.h line 40
Quoted 13 lines · Alejandro Vallejo
xen/include/xen/mm.h +7
-0@@ -31,6 +31,17 @@* (i.e. all devices assigned to) a guest share a single DMA address space * and, by default, Xen will ensure dfn == pfn. * +* pdx: Page InDeX +* Indices into the frame table holding the per-page's book-keeping +* metadata. A compression scheme may be used, so there's a possibly non +* identity mapping between valid(mfn) <-> valid(pdx). See the comments +* in pdx.c for an in-depth explanation of that mapping. This also has a +* knock-on effect on the directmap, as "compressed" pfns have no +* corresponding mapped frames. Didn't you mean to keep the directmap part optional,
I did.
Quoted 1 line
which would call for saying "may" here (twice)?
That paragraph as-is doesn't really mandate a directmap. It merely state that there are knock-on effects on directmap indexing, not that there's always a directmap to index.
Quoted 27 lines
Yet then ...
Quoted 10 lines
xen/include/xen/pdx.h +4
-0@@ -1,6 +1,73 @@#ifndef __XEN_PDX_H__#define __XEN_PDX_H__ +/* +* PDX (Page inDeX) +* +* This file deals with optimisations pertaining to frame table and xen/include/xen/pdx.h line 17
Quoted 10 lines
xen/include/xen/pdx.h +10
-0+* directmap indexing, A pdx is an index into the frame table, which +* typically also means an index into the directmap[1]. However, having an +* identity relationship between mfn and pdx could waste copious amounts of +* memory in empty frame table entries and page tables. There are some +* techniques to bring memory wastage down. +* +* [1] Some ports apply further modifications to a pdx before indexing the +* directmap. This doesn't change the fact that the same compression +* present in the frame table is also present in the directmap +* whenever said map is present. .. you mention it here as non-optional as well. Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
Quoted 1 line
Jan
The [1] note states "whenever said map is present", meaning that it may not be present. Saying it's optional is a stretch though. It's not like we can choose right now.
Quoted 1 line
Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
arm32 doesn't have a directmap at all. arm64 uses biased pdx as indices (they are offset by a constant), so they are still subject to compression.
Alejandro
Quoted 53 lines · Alejandro Vallejo
Quoted 16 lines · Jan Beulich
xen/include/xen/mm.h line 40
Quoted 13 lines · Alejandro Vallejo
xen/include/xen/mm.h +7
-0@@ -31,6 +31,17 @@* (i.e. all devices assigned to) a guest share a single DMA address space * and, by default, Xen will ensure dfn == pfn. * +* pdx: Page InDeX +* Indices into the frame table holding the per-page's book-keeping +* metadata. A compression scheme may be used, so there's a possibly non +* identity mapping between valid(mfn) <-> valid(pdx). See the comments +* in pdx.c for an in-depth explanation of that mapping. This also has a +* knock-on effect on the directmap, as "compressed" pfns have no +* corresponding mapped frames. Didn't you mean to keep the directmap part optional,
I did.
Quoted 1 line
which would call for saying "may" here (twice)?
That paragraph as-is doesn't really mandate a directmap. It merely state that there are knock-on effects on directmap indexing, not that there's always a directmap to index.
Quoted 27 lines
Yet then ...
Quoted 10 lines
xen/include/xen/pdx.h +4
-0@@ -1,6 +1,73 @@#ifndef __XEN_PDX_H__#define __XEN_PDX_H__ +/* +* PDX (Page inDeX) +* +* This file deals with optimisations pertaining to frame table and xen/include/xen/pdx.h line 17
Quoted 10 lines
xen/include/xen/pdx.h +10
-0+* directmap indexing, A pdx is an index into the frame table, which +* typically also means an index into the directmap[1]. However, having an +* identity relationship between mfn and pdx could waste copious amounts of +* memory in empty frame table entries and page tables. There are some +* techniques to bring memory wastage down. +* +* [1] Some ports apply further modifications to a pdx before indexing the +* directmap. This doesn't change the fact that the same compression +* present in the frame table is also present in the directmap +* whenever said map is present. .. you mention it here as non-optional as well. Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
Quoted 1 line
Jan
Quoted 7 lines
The [1] note states "whenever said map is present", meaning that it may not be present. Saying it's optional is a stretch though. It's not like we can choose right now.
Quoted 1 line
Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
arm32 doesn't have a directmap at all. arm64 uses biased pdx as indices (they are offset by a constant), so they are still subject to compression.
Hmm, then our understanding of "optional" was differing: I understood "use of compressed indexes is optional", when you apparently meant "the use of a directmap is optional". If this is the case, then I agree with the chosen wording. (Nevertheless using the suggested "may" wouldn't yield and incorrect outcome.)
Jan
Quoted 62 lines · Jan Beulich
Quoted 53 lines · Alejandro Vallejo
Quoted 16 lines · Jan Beulich
xen/include/xen/mm.h line 40
Quoted 13 lines · Alejandro Vallejo
xen/include/xen/mm.h +7
-0@@ -31,6 +31,17 @@* (i.e. all devices assigned to) a guest share a single DMA address space * and, by default, Xen will ensure dfn == pfn. * +* pdx: Page InDeX +* Indices into the frame table holding the per-page's book-keeping +* metadata. A compression scheme may be used, so there's a possibly non +* identity mapping between valid(mfn) <-> valid(pdx). See the comments +* in pdx.c for an in-depth explanation of that mapping. This also has a +* knock-on effect on the directmap, as "compressed" pfns have no +* corresponding mapped frames. Didn't you mean to keep the directmap part optional,
I did.
Quoted 1 line
which would call for saying "may" here (twice)?
That paragraph as-is doesn't really mandate a directmap. It merely state that there are knock-on effects on directmap indexing, not that there's always a directmap to index.
Quoted 27 lines
Yet then ...
Quoted 10 lines
xen/include/xen/pdx.h +4
-0@@ -1,6 +1,73 @@#ifndef __XEN_PDX_H__#define __XEN_PDX_H__ +/* +* PDX (Page inDeX) +* +* This file deals with optimisations pertaining to frame table and xen/include/xen/pdx.h line 17
Quoted 10 lines
xen/include/xen/pdx.h +10
-0+* directmap indexing, A pdx is an index into the frame table, which +* typically also means an index into the directmap[1]. However, having an +* identity relationship between mfn and pdx could waste copious amounts of +* memory in empty frame table entries and page tables. There are some +* techniques to bring memory wastage down. +* +* [1] Some ports apply further modifications to a pdx before indexing the +* directmap. This doesn't change the fact that the same compression +* present in the frame table is also present in the directmap +* whenever said map is present. .. you mention it here as non-optional as well. Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
Quoted 1 line
Jan
Quoted 7 lines
The [1] note states "whenever said map is present", meaning that it may not be present. Saying it's optional is a stretch though. It's not like we can choose right now.
Quoted 1 line
Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
arm32 doesn't have a directmap at all. arm64 uses biased pdx as indices (they are offset by a constant), so they are still subject to compression.
Quoted 7 lines
Hmm, then our understanding of "optional" was differing: I understood "use of compressed indexes is optional", when you apparently meant "the use of a directmap is optional". If this is the case, then I agree with the chosen wording. (Nevertheless using the suggested "may" wouldn't yield and incorrect outcome.)
Jan
Like this?
``` * pdx: Page InDeX * Indices into the frame table holding the per-page's book-keeping * metadata. A compression scheme may be used, so there's a possibly non * identity mapping between valid(mfn) <-> valid(pdx). See the comments * in pdx.c for an in-depth explanation of that mapping. This also may * have a knock-on effect on the directmap, as "compressed" pfns may not * have corresponding mapped frames. ```
If so, sure. I don't mind either way. I'm happy for those 2 _may_s to be added.
Thanks,
Alejandro
Quoted 81 lines · Alejandro Vallejo
Quoted 59 lines · Jan Beulich
Quoted 58 lines · Alejandro Vallejo
Quoted 16 lines · Jan Beulich
xen/include/xen/mm.h line 40
Quoted 13 lines · Alejandro Vallejo
xen/include/xen/mm.h +7
-0@@ -31,6 +31,17 @@* (i.e. all devices assigned to) a guest share a single DMA address space * and, by default, Xen will ensure dfn == pfn. * +* pdx: Page InDeX +* Indices into the frame table holding the per-page's book-keeping +* metadata. A compression scheme may be used, so there's a possibly non +* identity mapping between valid(mfn) <-> valid(pdx). See the comments +* in pdx.c for an in-depth explanation of that mapping. This also has a +* knock-on effect on the directmap, as "compressed" pfns have no +* corresponding mapped frames. Didn't you mean to keep the directmap part optional,
I did.
Quoted 1 line
which would call for saying "may" here (twice)?
That paragraph as-is doesn't really mandate a directmap. It merely state that there are knock-on effects on directmap indexing, not that there's always a directmap to index.
Quoted 27 lines
Yet then ...
Quoted 10 lines
xen/include/xen/pdx.h +4
-0@@ -1,6 +1,73 @@#ifndef __XEN_PDX_H__#define __XEN_PDX_H__ +/* +* PDX (Page inDeX) +* +* This file deals with optimisations pertaining to frame table and xen/include/xen/pdx.h line 17
Quoted 10 lines
xen/include/xen/pdx.h +10
-0+* directmap indexing, A pdx is an index into the frame table, which +* typically also means an index into the directmap[1]. However, having an +* identity relationship between mfn and pdx could waste copious amounts of +* memory in empty frame table entries and page tables. There are some +* techniques to bring memory wastage down. +* +* [1] Some ports apply further modifications to a pdx before indexing the +* directmap. This doesn't change the fact that the same compression +* present in the frame table is also present in the directmap +* whenever said map is present. .. you mention it here as non-optional as well. Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
Quoted 1 line
Jan
The [1] note states "whenever said map is present", meaning that it may not be present. Saying it's optional is a stretch though. It's not like we can choose right now.
Quoted 1 line
Didn't you tell me that Arm doesn't use compressed indexes into the directmap?
Quoted 8 lines
Quoted 2 lines
arm32 doesn't have a directmap at all. arm64 uses biased pdx as indices (they are offset by a constant), so they are still subject to compression.
Hmm, then our understanding of "optional" was differing: I understood "use of compressed indexes is optional", when you apparently meant "the use of a directmap is optional". If this is the case, then I agree with the chosen wording. (Nevertheless using the suggested "may" wouldn't yield and incorrect outcome.)
Like this?
``` * pdx: Page InDeX * Indices into the frame table holding the per-page's book-keeping * metadata. A compression scheme may be used, so there's a possibly non * identity mapping between valid(mfn) <-> valid(pdx). See the comments * in pdx.c for an in-depth explanation of that mapping. This also may * have a knock-on effect on the directmap, as "compressed" pfns may not * have corresponding mapped frames. ```
Quoted 1 line
If so, sure. I don't mind either way. I'm happy for those 2
_may_sto be added.
Yes please.
Thanks, Jan