vendorcode/amd/agesa: Clarify CAR disable

Clean up commentary on AMD_DISABLE_STACK to be clear that
it does a wbinvd to preserve coreboot CBMEM and
value of car_migrated.

Change-Id: I0f5e9c807f7990fcd5ca85f77b9d92312e775d3e
Signed-off-by: Marc Jones <marcj303@gmail.com>
Signed-off-by: Marshall Dawson <marshalldawson3rd@gmail.com>
Signed-off-by: Kyösti Mälkki <kyosti.malkki@gmail.com>
Reviewed-on: https://review.coreboot.org/20578
Reviewed-by: Marc Jones <marc@marcjonesconsulting.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

4 files changed, 118 insertions, 15 deletions

diff --git a/src/vendorcode/amd/agesa/f10/gcccar.inc b/src/vendorcode/amd/agesa/f10/gcccar.inc
index 88fa79d2ea..c490a61d58 100644
--- a/src/vendorcode/amd/agesa/f10/gcccar.inc
+++ b/src/vendorcode/amd/agesa/f10/gcccar.inc
@@ -360,6 +360,13 @@ fam10_enable_stack_hook_exit:
 *   Return any family specific controls to their 'standard'
 *   settings for using cache with main memory.
 *
+* Note: Customized for coreboot:
+*   A wbinvd is used to send cache to memory.  The existing stack is preserved
+*   at its original location and additional information is preserved (e.g.
+*   coreboot CAR globals, heap structures, etc.). This implementation should
+*   NOT be used with S3 resume IF the stack/cache area is not reserved and
+*   over system memory.
+*
 * Inputs:
 *       ESI - [31:24] flags; [15,8]= Node#; [7,0]= core#
 * Outputs:
@@ -419,7 +426,14 @@ fam10_enable_stack_hook_exit:
     mov     %ax, %bx                      # Save INVD -> WBINVD bit
     btr    $INVD_WBINVD, %eax            # Disable INVD -> WBINVD conversion for the invd instruction.
     _WRMSR
-    wbinvd                                # Clear the cache tag RAMs
+
+    #--------------------------------------------------------------------------
+    # Send cache to memory. Preserve stack and coreboot CAR globals.
+    # This shouldn't be used with S3 resume IF the stack/cache area is
+    # not reserved and over system memory.
+    #--------------------------------------------------------------------------
+    wbinvd
+
     mov    %bx, %ax                      # Restore INVD -> WBINVD bit
     _WRMSR
 
@@ -1581,8 +1595,17 @@ ClearTheStack:                          # Stack base is in SS, stack pointer is
 .endm
 
 /*****************************************************************************
-* AMD_DISABLE_STACK:  Destroy the stack inside the cache. This routine
-*                     should only be executed on the BSP
+* AMD_DISABLE_STACK:  Implementation is modified for coreboot from
+*                     the original AMD intent.  A WBINVD is used in the HOOK
+*                     to send dirty cache contents to DRAM backing before
+*                     disabling cache-as-ram.  This is not safe for S3 resume.
+*
+*                     todo:
+*                       * rework PI/AGESA source to set DRAM to UC to send
+*                         writes directly to memory
+*                       * move DCACHE_BASE or use postcar stage for teardown
+*                         to eliminate car_migrated problem that will occur
+*                         after wbinvd is changed back to invd
 *
 *   In:
 *       none
diff --git a/src/vendorcode/amd/agesa/f15/gcccar.inc b/src/vendorcode/amd/agesa/f15/gcccar.inc
index 9d566f2f1b..4d00df392d 100644
--- a/src/vendorcode/amd/agesa/f15/gcccar.inc
+++ b/src/vendorcode/amd/agesa/f15/gcccar.inc
@@ -361,6 +361,13 @@ fam10_enable_stack_hook_exit:
 *   Return any family specific controls to their 'standard'
 *   settings for using cache with main memory.
 *
+* Note: Customized for coreboot:
+*   A wbinvd is used to send cache to memory.  The existing stack is preserved
+*   at its original location and additional information is preserved (e.g.
+*   coreboot CAR globals, heap structures, etc.). This implementation should
+*   NOT be used with S3 resume IF the stack/cache area is not reserved and
+*   over system memory.
+*
 * Inputs:
 *       ESI - [31:24] flags; [15,8]= Node#; [7,0]= core#
 * Outputs:
@@ -420,7 +427,14 @@ fam10_enable_stack_hook_exit:
     mov     %ax, %bx                      # Save INVD -> WBINVD bit
     btr    $INVD_WBINVD, %eax            # Disable INVD -> WBINVD conversion for the invd instruction.
     _WRMSR
-    wbinvd                                # Clear the cache tag RAMs
+
+    #--------------------------------------------------------------------------
+    # Send cache to memory. Preserve stack and coreboot CAR globals.
+    # This shouldn't be used with S3 resume IF the stack/cache area is
+    # not reserved and over system memory.
+    #--------------------------------------------------------------------------
+    wbinvd
+
     mov    %bx, %ax                      # Restore INVD -> WBINVD bit
     _WRMSR
 
@@ -939,6 +953,13 @@ fam15_enable_stack_hook_exit:
 *   Return any family specific controls to their 'standard'
 *   settings for using cache with main memory.
 *
+* Note: Customized for coreboot:
+*   A wbinvd is used to send cache to memory.  The existing stack is preserved
+*   at its original location and additional information is preserved (e.g.
+*   coreboot CAR globals, heap structures, etc.). This implementation should
+*   NOT be used with S3 resume IF the stack/cache area is not reserved and
+*   over system memory.
+*
 * Inputs:
 *       ESI - [31:24] flags; [15,8]= Node#; [7,0]= core#
 * Outputs:
@@ -997,7 +1018,14 @@ fam15_enable_stack_hook_exit:
     _RDMSR
     btr     $INVD_WBINVD, %eax            # Disable INVD -> WBINVD conversion
     _WRMSR
-    wbinvd                                # Clear the cache tag RAMs
+
+    #--------------------------------------------------------------------------
+    # Send cache to memory. Preserve stack and coreboot CAR globals.
+    # This shouldn't be used with S3 resume IF the stack/cache area is
+    # not reserved and over system memory.
+    #--------------------------------------------------------------------------
+    wbinvd
+
     bts     $INVD_WBINVD, %eax            # Turn on Conversion of INVD to WBINVD
     _WRMSR
     #.endif                              # end
@@ -1582,8 +1610,17 @@ ClearTheStack:                          # Stack base is in SS, stack pointer is
 .endm
 
 /*****************************************************************************
-* AMD_DISABLE_STACK:  Destroy the stack inside the cache. This routine
-*                     should only be executed on the BSP
+* AMD_DISABLE_STACK:  Implementation is modified for coreboot from
+*                     the original AMD intent.  A WBINVD is used in the HOOK
+*                     to send dirty cache contents to DRAM backing before
+*                     disabling cache-as-ram.  This is not safe for S3 resume.
+*
+*                     todo:
+*                       * rework PI/AGESA source to set DRAM to UC to send
+*                         writes directly to memory
+*                       * move DCACHE_BASE or use postcar stage for teardown
+*                         to eliminate car_migrated problem that will occur
+*                         after wbinvd is changed back to invd
 *
 *   In:
 *       none
@@ -1629,4 +1666,3 @@ ClearTheStack:                          # Stack base is in SS, stack pointer is
     xor     %eax, %eax
 
 .endm
-
diff --git a/src/vendorcode/amd/agesa/f15tn/gcccar.inc b/src/vendorcode/amd/agesa/f15tn/gcccar.inc
index 330570e3e9..4f1e7a0b25 100644
--- a/src/vendorcode/amd/agesa/f15tn/gcccar.inc
+++ b/src/vendorcode/amd/agesa/f15tn/gcccar.inc
@@ -1033,6 +1033,13 @@ fam15_enable_stack_hook_exit:
 *   Return any family specific controls to their 'standard'
 *   settings for using cache with main memory.
 *
+* Note: Customized for coreboot:
+*   A wbinvd is used to send cache to memory.  The existing stack is preserved
+*   at its original location and additional information is preserved (e.g.
+*   coreboot CAR globals, heap structures, etc.). This implementation should
+*   NOT be used with S3 resume IF the stack/cache area is not reserved and
+*   over system memory.
+*
 * Inputs:
 *       ESI - [31:24] flags; [15,8]= Node#; [7,0]= core#
 * Outputs:
@@ -1250,7 +1257,14 @@ fam15_disable_stack_remote_read_exit:
     _RDMSR
     btr     $INVD_WBINVD, %eax            # Disable INVD -> WBINVD conversion
     _WRMSR
-    wbinvd                                # Clear the cache tag RAMs
+
+    #--------------------------------------------------------------------------
+    # Send cache to memory. Preserve stack and coreboot CAR globals.
+    # This shouldn't be used with S3 resume IF the stack/cache area is
+    # not reserved and over system memory.
+    #--------------------------------------------------------------------------
+    wbinvd
+
     #.if (bh == 01h) || (bh == 03h)      ; Is this TN or KM?
     cmp   $01, %bh
     jz    4f
@@ -1891,8 +1905,17 @@ ClearTheStack:                          # Stack base is in SS, stack pointer is
 .endm
 
 /*****************************************************************************
-* AMD_DISABLE_STACK:  Destroy the stack inside the cache. This routine
-*                     should only be executed on the BSP
+* AMD_DISABLE_STACK:  Implementation is modified for coreboot from
+*                     the original AMD intent.  A WBINVD is used in the HOOK
+*                     to send dirty cache contents to DRAM backing before
+*                     disabling cache-as-ram.  This is not safe for S3 resume.
+*
+*                     todo:
+*                       * rework PI/AGESA source to set DRAM to UC to send
+*                         writes directly to memory
+*                       * move DCACHE_BASE or use postcar stage for teardown
+*                         to eliminate car_migrated problem that will occur
+*                         after wbinvd is changed back to invd
 *
 *   In:
 *       none
diff --git a/src/vendorcode/amd/agesa/f16kb/gcccar.inc b/src/vendorcode/amd/agesa/f16kb/gcccar.inc
index 592ee6d00e..bd670590a7 100644
--- a/src/vendorcode/amd/agesa/f16kb/gcccar.inc
+++ b/src/vendorcode/amd/agesa/f16kb/gcccar.inc
@@ -269,6 +269,13 @@ MSR_MASK    = ((1 << MTRR_DEF_TYPE_EN)+(1 << MTRR_DEF_TYPE_FIX_EN))
 *   Read family specific values to determine the node and core
 *   numbers for the core executing this code.
 *
+* Note: Customized for coreboot:
+*   A wbinvd is used to send cache to memory.  The existing stack is preserved
+*   at its original location and additional information is preserved (e.g.
+*   coreboot CAR globals, heap structures, etc.). This implementation should
+*   NOT be used with S3 resume IF the stack/cache area is not reserved and
+*   over system memory.
+*
 * Inputs:
 *     none
 * Outputs:
@@ -602,8 +609,13 @@ fam16_disable_stack_remote_read_exit:
     _RDMSR
     btr     $INVD_WBINVD, %eax            # Disable INVD -> WBINVD conversion
     _WRMSR
-    wbinvd                                # Clear the cache tag RAMs
-    #invd
+
+    #--------------------------------------------------------------------------
+    # Send cache to memory. Preserve stack and coreboot CAR globals.
+    # This shouldn't be used with S3 resume IF the stack/cache area is
+    # not reserved and over system memory.
+    #--------------------------------------------------------------------------
+    wbinvd
 
     #Do Standard Family 16 work
     mov     $HWCR, %ecx                    # MSR:C001_0015h
@@ -1256,8 +1268,17 @@ ClearTheStack:                          # Stack base is in SS, stack pointer is
 .endm
 
 /*****************************************************************************
-* AMD_DISABLE_STACK:  Destroy the stack inside the cache. This routine
-*                     should only be executed on the BSP
+* AMD_DISABLE_STACK:  Implementation is modified for coreboot from
+*                     the original AMD intent.  A WBINVD is used in the HOOK
+*                     to send dirty cache contents to DRAM backing before
+*                     disabling cache-as-ram.  This is not safe for S3 resume.
+*
+*                     todo:
+*                       * rework PI/AGESA source to set DRAM to UC to send
+*                         writes directly to memory
+*                       * move DCACHE_BASE or use postcar stage for teardown
+*                         to eliminate car_migrated problem that will occur
+*                         after wbinvd is changed back to invd
 *
 *   In:
 *       none