Xen project Mailing List

[Xen-devel] [PATCH v2 5/5] doc: correct intel_psr_cat_cdp.pandoc syntax

"make -C docs all" fails due to incorrect markdown syntax in intel_psr_cat_cdp.pandoc. Correct it. Signed-off-by: Juergen Gross <jgross@xxxxxxxx> --- docs/features/intel_psr_cat_cdp.pandoc | 366 ++++++++++++++++----------------- 1 file changed, 175 insertions(+), 191 deletions(-) diff --git a/docs/features/intel_psr_cat_cdp.pandoc b/docs/features/intel_psr_cat_cdp.pandoc index 04fb256dd9..c619e2cc99 100644 --- a/docs/features/intel_psr_cat_cdp.pandoc +++ b/docs/features/intel_psr_cat_cdp.pandoc @@ -104,19 +104,18 @@ PSR infrastructure in Xen. CAT/CDP defines a range of MSRs to assign different cache access patterns which are known as CBMs, each CBM is associated with a COS. - ``` E.g. L2 CAT: - +----------------------------+----------------+ - IA32_PQR_ASSOC | MSR (per socket) | Address | - +----+---+-------+ +----------------------------+----------------+ - | |COS| | | IA32_L2_QOS_MASK_0 | 0xD10 | - +----+---+-------+ +----------------------------+----------------+ - +-------------> | ... | ... | - +----------------------------+----------------+ - | IA32_L2_QOS_MASK_n | 0xD10+n (n<64) | - +----------------------------+----------------+ - ``` - + + +----------------------------+----------------+ + IA32_PQR_ASSOC | MSR (per socket) | Address | + +----+---+-------+ +----------------------------+----------------+ + | |COS| | | IA32_L2_QOS_MASK_0 | 0xD10 | + +----+---+-------+ +----------------------------+----------------+ + +-------------> | ... | ... | + +----------------------------+----------------+ + | IA32_L2_QOS_MASK_n | 0xD10+n (n<64) | + +----------------------------+----------------+ + L3 CAT/CDP uses a range of MSRs from 0xC90 ~ 0xC90+n (n<128). L2 CAT uses a range of MSRs from 0xD10 ~ 0xD10+n (n<64), following the L3 @@ -132,41 +131,39 @@ PSR infrastructure in Xen. note that all (and only) contiguous '1' combinations are allowed (e.g. FFFFH, 0FF0H, 003CH, etc.). - ``` - +----+----+----+----+----+----+----+----+ - | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 | - +----+----+----+----+----+----+----+----+ - COS0 | A | A | A | A | A | A | A | A | Default Bitmask - +----+----+----+----+----+----+----+----+ - COS1 | A | A | A | A | A | A | A | A | - +----+----+----+----+----+----+----+----+ - COS2 | A | A | A | A | A | A | A | A | - +----+----+----+----+----+----+----+----+ - - +----+----+----+----+----+----+----+----+ - | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 | - +----+----+----+----+----+----+----+----+ - COS0 | A | A | A | A | A | A | A | A | Overlapped Bitmask - +----+----+----+----+----+----+----+----+ - COS1 | | | | | A | A | A | A | - +----+----+----+----+----+----+----+----+ - COS2 | | | | | | | A | A | - +----+----+----+----+----+----+----+----+ - - +----+----+----+----+----+----+----+----+ - | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 | - +----+----+----+----+----+----+----+----+ - COS0 | A | A | A | A | | | | | Isolated Bitmask - +----+----+----+----+----+----+----+----+ - COS1 | | | | | A | A | | | - +----+----+----+----+----+----+----+----+ - COS2 | | | | | | | A | A | - +----+----+----+----+----+----+----+----+ - ``` + +----+----+----+----+----+----+----+----+ + | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 | + +----+----+----+----+----+----+----+----+ + COS0 | A | A | A | A | A | A | A | A | Default Bitmask + +----+----+----+----+----+----+----+----+ + COS1 | A | A | A | A | A | A | A | A | + +----+----+----+----+----+----+----+----+ + COS2 | A | A | A | A | A | A | A | A | + +----+----+----+----+----+----+----+----+ + + +----+----+----+----+----+----+----+----+ + | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 | + +----+----+----+----+----+----+----+----+ + COS0 | A | A | A | A | A | A | A | A | Overlapped Bitmask + +----+----+----+----+----+----+----+----+ + COS1 | | | | | A | A | A | A | + +----+----+----+----+----+----+----+----+ + COS2 | | | | | | | A | A | + +----+----+----+----+----+----+----+----+ + + +----+----+----+----+----+----+----+----+ + | M7 | M6 | M5 | M4 | M3 | M2 | M1 | M0 | + +----+----+----+----+----+----+----+----+ + COS0 | A | A | A | A | | | | | Isolated Bitmask + +----+----+----+----+----+----+----+----+ + COS1 | | | | | A | A | | | + +----+----+----+----+----+----+----+----+ + COS2 | | | | | | | A | A | + +----+----+----+----+----+----+----+----+ We can get the CBM length through CPUID. The default value of CBM is calcul- ated by `(1ull << cbm_len) - 1`. That is a fully open bitmask, all ones bitm- - ask. The COS[0] always stores the default value without change. + ask. The COS\[0\] always stores the default value without change. There is a `IA32_PQR_ASSOC` register which stores the COS ID of the VCPU. HW enforces cache allocation according to the corresponding CBM. @@ -209,8 +206,8 @@ PSR infrastructure in Xen. System administrator can change PSR allocation policy at runtime by tool stack. Since L2 CAT shares COS with L3 CAT/CDP, a COS corresponds to a 2-tuple, like - [L2 CBM, L3 CBM] with only-CAT enabled, when CDP is enabled, one COS correspo- - nds to a 3-tuple, like [L2 CBM, L3 Code_CBM, L3 Data_CBM]. If neither L3 CAT + \[L2 CBM, L3 CBM\] with only-CAT enabled, when CDP is enabled, one COS correspo- + nds to a 3-tuple, like \[L2 CBM, L3 Code_CBM, L3 Data_CBM\]. If neither L3 CAT nor L3 CDP is enabled, things would be easier, one COS corresponds to one L2 CBM. @@ -240,160 +237,146 @@ PSR infrastructure in Xen. * Hypervisor interfaces: - 1. Boot line parameter "psr=cat" enables L2 CAT and L3 CAT if hardware suppo- - rted. "psr=cdp" enables CDP if hardware supported. - - 2. SYSCTL: - - XEN_SYSCTL_PSR_CAT_get_l3_info: Get L3 CAT/CDP information. - - XEN_SYSCTL_PSR_CAT_get_l2_info: Get L2 CAT information. - - 3. DOMCTL: - - XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM: Get L3 CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM: Set L3 CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE: Get CDP Code CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE: Set CDP Code CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA: Get CDP Data CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA: Set CDP Data CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM: Get L2 CBM for a domain. - - XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM: Set L2 CBM for a domain. +> 1. Boot line parameter "psr=cat" enables L2 CAT and L3 CAT if hardware suppo- +> rted. "psr=cdp" enables CDP if hardware supported. +> +> 2. SYSCTL: +> +> > * XEN_SYSCTL_PSR_CAT_get_l3_info: Get L3 CAT/CDP information. +> > * XEN_SYSCTL_PSR_CAT_get_l2_info: Get L2 CAT information. +> +> 3. DOMCTL: +> +> > * XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM: Get L3 CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM: Set L3 CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE: Get CDP Code CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE: Set CDP Code CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA: Get CDP Data CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA: Set CDP Data CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM: Get L2 CBM for a domain. +> > * XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM: Set L2 CBM for a domain. * xl interfaces: - 1. psr-cat-show -lX domain-id - Show LX cbm for a domain. - => XEN_SYSCTL_PSR_CAT_get_l3_info / - XEN_SYSCTL_PSR_CAT_get_l2_info / - XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM / - XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE / - XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA / - XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM - - 2. psr-cat-set -lX domain-id cbm - Set LX cbm for a domain. - => XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM / - XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE / - XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA / - XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM - - 3. psr-hwinfo - Show PSR HW information, including L3 CAT/CDP/L2 CAT - => XEN_SYSCTL_PSR_CAT_get_l3_info / - XEN_SYSCTL_PSR_CAT_get_l2_info - -* Key data structure: - - 1. Feature properties - - ``` - static const struct feat_props { - unsigned int cos_num; - enum cbm_type type[PSR_MAX_COS_NUM]; - enum cbm_type alt_type; - bool (*get_feat_info)(const struct feat_node *feat, - uint32_t data[], unsigned int array_len); - void (*write_msr)(unsigned int cos, uint32_t val, enum cbm_type type); - } *feat_props[PSR_SOCKET_FEAT_NUM]; - ``` - - Every feature has its own properties, e.g. some data and actions. A - feature property pointer array is declared to save every feature's - properties. - - - Member `cos_num` - - `cos_num` is the number of COS registers the feature uses, e.g. L3/L2 - CAT uses 1 register but CDP uses 2 registers. - - - Member `type` - - `type` is an array to save all 'enum cbm_type' values of the feature. - It is used with cos_num together to get/write a feature's COS registers - values one by one. - - - Member `alt_type` - - `alt_type` is 'alternative type'. When this 'alt_type' is input, the - feature does some special operations. - - - Member `get_feat_info` - - `get_feat_info` is used to return feature HW info through sysctl. - - - Member `write_msr` - - `write_msr` is used to write out feature MSR register. +> 1. psr-cat-show -lX domain-id +> Show LX cbm for a domain. - 2. Feature node + => XEN_SYSCTL_PSR_CAT_get_l3_info / + XEN_SYSCTL_PSR_CAT_get_l2_info / + XEN_DOMCTL_PSR_CAT_OP_GET_L3_CBM / + XEN_DOMCTL_PSR_CAT_OP_GET_L3_CODE / + XEN_DOMCTL_PSR_CAT_OP_GET_L3_DATA / + XEN_DOMCTL_PSR_CAT_OP_GET_L2_CBM + +> 2. psr-cat-set -lX domain-id cbm +> Set LX cbm for a domain. - ``` - struct feat_node { - unsigned int cos_max; - unsigned int cbm_len; - uint32_t cos_reg_val[MAX_COS_REG_CNT]; - }; - ``` + => XEN_DOMCTL_PSR_CAT_OP_SET_L3_CBM / + XEN_DOMCTL_PSR_CAT_OP_SET_L3_CODE / + XEN_DOMCTL_PSR_CAT_OP_SET_L3_DATA / + XEN_DOMCTL_PSR_CAT_OP_SET_L2_CBM - When a PSR enforcement feature is enabled, it will be added into a - feature array. +> 3. psr-hwinfo +> Show PSR HW information, including L3 CAT/CDP/L2 CAT - - Member `cos_max` + => XEN_SYSCTL_PSR_CAT_get_l3_info / + XEN_SYSCTL_PSR_CAT_get_l2_info - `cos_max` is one of the hardware info of CAT. It means the max number - of COS registers. As L3 CAT/CDP/L2 CAT all have it, it is declared in - `feat_node`. - - - Member `cbm_len` - - `cbm_len` is one of the hardware info of CAT. It means the max number - of bits to set. - - - Member `cos_reg_val` - - `cos_reg_val` is an array to maintain the value set in all COS registers - of the feature. The array is indexed by COS ID. - - 3. Per-socket PSR features information structure - - ``` - struct psr_socket_info { - bool feat_init; - struct feat_node *features[PSR_SOCKET_FEAT_NUM]; - spinlock_t ref_lock; - unsigned int cos_ref[MAX_COS_REG_CNT]; - DECLARE_BITMAP(dom_ids, DOMID_IDLE + 1); - }; - ``` - - We collect all PSR allocation features information of a socket in this - `struct psr_socket_info`. - - - Member `feat_init` - - `feat_init` is a flag, to indicate whether the CPU init on a socket - has been done. - - - Member `features` - - `features` is a pointer array to save all enabled features poniters - according to feature position defined in `enum psr_feat_type`. - - - Member `ref_lock` - - `ref_lock` is a spin lock to protect `cos_ref`. - - - Member `cos_ref` - - `cos_ref` is an array which maintains the reference of one COS. It maps - to cos_reg_val[MAX_COS_REG_NUM] in `struct feat_node`. If one COS is - used by one domain, the corresponding reference will increase by one. If - a domain releases the COS, the reference will decrease by one. The array - is indexed by COS ID. - - - Member `dom_ids` +* Key data structure: - `dom_ids` is a bitmap, every bit corresponds to a domain. Index is - domain_id. It is used to help restore the cos_id of the domain to 0 when - a socket is offline and then online again. +> 1. Feature properties +> +> static const struct feat_props { +> unsigned int cos_num; +> enum cbm_type type[PSR_MAX_COS_NUM]; +> enum cbm_type alt_type; +> bool (*get_feat_info)(const struct feat_node *feat, +> uint32_t data[], unsigned int array_len); +> void (*write_msr)(unsigned int cos, uint32_t val, enum cbm_type type); +> } *feat_props[PSR_SOCKET_FEAT_NUM]; +> +> > Every feature has its own properties, e.g. some data and actions. A +> > feature property pointer array is declared to save every feature's +> > properties. +> > +> > * Member `cos_num` +> > `cos_num` is the number of COS registers the feature uses, e.g. L3/L2 +> > CAT uses 1 register but CDP uses 2 registers. +> > +> > * Member `type` +> > `type` is an array to save all 'enum cbm_type' values of the feature. +> > It is used with cos_num together to get/write a feature's COS registers +> > values one by one. +> > +> > * Member `alt_type` +> > `alt_type` is 'alternative type'. When this 'alt_type' is input, the +> > feature does some special operations. +> > +> > * Member `get_feat_info` +> > `get_feat_info` is used to return feature HW info through sysctl. +> > +> > * Member `write_msr` +> > `write_msr` is used to write out feature MSR register. +> +> 2. Feature node +> +> struct feat_node { +> unsigned int cos_max; +> unsigned int cbm_len; +> uint32_t cos_reg_val[MAX_COS_REG_CNT]; +> }; +> +> > When a PSR enforcement feature is enabled, it will be added into a +> > feature array. +> > +> > * Member `cos_max` +> > `cos_max` is one of the hardware info of CAT. It means the max number +> > of COS registers. As L3 CAT/CDP/L2 CAT all have it, it is declared in +> > `feat_node`. +> > +> > * Member `cbm_len` +> > `cbm_len` is one of the hardware info of CAT. It means the max number +> > of bits to set. +> > +> > * Member `cos_reg_val` +> > `cos_reg_val` is an array to maintain the value set in all COS registers +> > of the feature. The array is indexed by COS ID. +> +> 3. Per-socket PSR features information structure +> +> struct psr_socket_info { +> bool feat_init; +> struct feat_node *features[PSR_SOCKET_FEAT_NUM]; +> spinlock_t ref_lock; +> unsigned int cos_ref[MAX_COS_REG_CNT]; +> DECLARE_BITMAP(dom_ids, DOMID_IDLE + 1); +> }; +> +> > We collect all PSR allocation features information of a socket in this +> > `struct psr_socket_info`. +> > +> > * Member `feat_init` +> > `feat_init` is a flag, to indicate whether the CPU init on a socket +> > has been done. +> > +> > * Member `features` +> > `features` is a pointer array to save all enabled features poniters +> > according to feature position defined in `enum psr_feat_type`. +> > +> > * Member `ref_lock` +> > `ref_lock` is a spin lock to protect `cos_ref`. +> > +> > * Member `cos_ref` +> > `cos_ref` is an array which maintains the reference of one COS. It maps +> > to cos_reg_val\[MAX_COS_REG_NUM\] in `struct feat_node`. If one COS is +> > used by one domain, the corresponding reference will increase by one. If +> > a domain releases the COS, the reference will decrease by one. The array +> > is indexed by COS ID. +> > +> > * Member `dom_ids` +> > `dom_ids` is a bitmap, every bit corresponds to a domain. Index is +> > domain_id. It is used to help restore the cos_id of the domain to 0 when +> > a socket is offline and then online again. # Limitations @@ -407,6 +390,7 @@ We can execute above xl commands to verify L2 CAT and L3 CAT/CDP on different HWs support them. For example: + root@:~$ xl psr-hwinfo --cat Cache Allocation Technology (CAT): L2 Socket ID : 0 -- 2.13.6 _______________________________________________ Xen-devel mailing list Xen-devel@xxxxxxxxxxxxxxxxxxxx https://lists.xenproject.org/mailman/listinfo/xen-devel

©2013 Xen Project, A Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation.
Xen Project is a trademark of The Linux Foundation.