armv7: cosmetic changes to new cache code

This clarifies and/or fixes formatting of some comments and
alphabetizes some function prototypes and inlines. It also
corrects references to "modified virtual address" (MVA).

Change-Id: Ibcdda4febf915cc4a1996a5bbb4ffecbcb50a324
Signed-off-by: David Hendricks <dhendrix@chromium.org>
Reviewed-on: http://review.coreboot.org/2869
Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
Tested-by: build bot (Jenkins)

src/arch/armv7/include/arch/cache.h

@@ -25,6 +25,8 @@
  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
+ *
+ * cache.h: Cache maintenance API for ARMv7
  */
 
 #ifndef ARMV7_CACHE_H
@@ -128,12 +130,6 @@ static inline void dccisw(uint32_t val)
 	asm volatile ("mcr p15, 0, %0, c7, c14, 2" : : "r" (val));
 }
 
-/* data cache invalidate by set/way */
-static inline void dcisw(uint32_t val)
-{
-	asm volatile ("mcr p15, 0, %0, c7, c6, 2" : : "r" (val));
-}
-
 /* data cache clean by MVA to PoC */
 static inline void dccmvac(unsigned long mva)
 {
@@ -146,6 +142,12 @@ static inline void dcimvac(unsigned long mva)
 	asm volatile ("mcr p15, 0, %0, c7, c6, 1" : : "r" (mva));
 }
 
+/* data cache invalidate by set/way */
+static inline void dcisw(uint32_t val)
+{
+	asm volatile ("mcr p15, 0, %0, c7, c6, 2" : : "r" (val));
+}
+
 /* instruction cache invalidate all by PoU */
 static inline void iciallu(void)
 {
@@ -210,25 +212,29 @@ static inline void write_sctlr(unsigned int val)
  * Cache maintenance API
  */
 
-/* invalidate all TLBs */
+/* dcache clean and invalidate all (on current level given by CCSELR) */
-void tlb_invalidate_all(void);
-
-/* clean and invalidate entire dcache on current level (given by CCSELR) */
 void dcache_clean_invalidate_all(void);
 
-/* invalidate entire dcache on current level (given by CCSELR) */
+/* dcache clean and invalidate by modified virtual address to PoC */
-void dcache_invalidate_all(void);
-
-/* invalidate and clean dcache by machine virtual address to PoC */
 void dcache_clean_invalidate_by_mva(unsigned long addr, unsigned long len);
 
-/* invalidate entire icache on current level (given by CSSELR) */
+/* dcache invalidate all (on current level given by CCSELR) */
+void dcache_invalidate_all(void);
+
+/* icache invalidate all (on current level given by CSSELR) */
 void icache_invalidate_all(void);
 
+/* tlb invalidate all */
+void tlb_invalidate_all(void);
+
+/*
+ * Generalized setup/init functions
+ */
+
 /* invalidate all caches on ARMv7 */
 void armv7_invalidate_caches(void);
 
-/* MMU setup by machine virtual address */
+/* MMU setup by modified virtual address */
 void mmu_setup_by_mva(unsigned long start, unsigned long size);
 
 #endif /* ARMV7_CACHE_H */

src/arch/armv7/lib/cache.c

@@ -26,7 +26,9 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * cache.c: Low-level cache operations for ARMv7
+ * cache.c: Cache maintenance routines for ARMv7-A and ARMv7-R
+ *
+ * Reference: ARM Architecture Reference Manual, ARMv7-A and ARMv7-R edition
  */
 
 #include <types.h>
@@ -52,8 +54,8 @@ void tlb_invalidate_all(void)
 {
 	/*
 	 * FIXME: ARMv7 Architecture Ref. Manual claims that the distinction
-	 * instruction vs. data TLBs is deprecated in ARMv7. But that doesn't
+	 * instruction vs. data TLBs is deprecated in ARMv7, however this does
-	 * really seem true for Cortex-A15?
+	 * not seem to be the case as of Cortex-A15.
 	 */
 	tlbiall();
 	dtlbiall();
@@ -64,7 +66,8 @@ void tlb_invalidate_all(void)
 
 void icache_invalidate_all(void)
 {
-	/* icache can be entirely invalidated with one operation.
+	/*
+	 * icache can be entirely invalidated with one operation.
 	 * Note: If branch predictors are architecturally-visible, ICIALLU
 	 * also performs a BPIALL operation (B2-1283 in arch manual)
 	 */
@@ -77,7 +80,12 @@ enum dcache_op {
 	OP_DCISW
 };
 
-/* do a dcache operation on entire cache by set/way */
+/*
+ * Do a dcache operation on entire cache by set/way. This is done for
+ * portability because mapping of memory address to cache location is
+ * implementation defined (See note on "Requirements for operations by
+ * set/way" in arch ref. manual).
+ */
 static void dcache_op_set_way(enum dcache_op op)
 {
 	uint32_t ccsidr;