[PATCH 7/7] doc: correct intel_psr_cat_cdp.pandoc syntax

[Juergen Gross <jgross@suse.com>]

"make -C docs all" fails due to incorrect markdown syntax in
intel_psr_cat_cdp.pandoc. Correct it.

Signed-off-by: Juergen Gross <jgross@suse.com>
---
 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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel