Import of the watch repository from Pebble

src/libos/include/mcu/cache.h

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+// Instruction cache and data cache are entirely separate. Therefore, you must both flush data
+// cache _and_ invalidate instruction cache for that region in order to properly execute new code.
+
+// A cache flush means the data is written out from the cache into memory. A cache invalidate
+// means the data in the cache is thrown out and will be reloaded from memory on the next access.
+// A flush does keep the data still in cache, so if you want to write out and invalidate, you want
+// to use flush_invalidate.
+
+// All cache operations MUST operate on the cache line size. You can safely flush memory that isn't
+// part of your buffer, but invalidation CAN AND WILL destroy other memory! Be very careful!
+
+// The cache line size on Cortex-M7 is 32 bytes.
+
+//! Enable instruction cache.
+void icache_enable(void);
+//! Disable instruction cache.
+void icache_disable(void);
+//! Returns whether or not ICache is enabled
+bool icache_is_enabled(void);
+//! Returns line size of ICache.
+uint32_t icache_line_size(void);
+
+//! Invalidate entire instruction cache.
+void icache_invalidate_all(void);
+//! Invalidate instruction cache for `addr` for `size` bytes.
+//! `addr` and `size` should both be aligned by the cache line size.
+void icache_invalidate(void *addr, size_t size);
+
+//! Enable data cache.
+void dcache_enable(void);
+//! Disable data cache.
+void dcache_disable(void);
+//! Returns whether or not DCache is enabled
+bool dcache_is_enabled(void);
+//! Returns line size of DCache.
+uint32_t dcache_line_size(void);
+
+//! Flush entire data cache.
+void dcache_flush_all(void);
+//! Invalidate entire data cache.
+void dcache_invalidate_all(void);
+//! Flush, then invalidate entire data cache.
+void dcache_flush_invalidate_all(void);
+
+//! Flush data cache for `addr` for `size` bytes.
+//! `addr` and `size` should both be aligned by the cache line size.
+void dcache_flush(const void *addr, size_t size);
+//! Invalidate data cache for `addr` for `size` bytes.
+//! `addr` and `size` should both be aligned by the cache line size.
+void dcache_invalidate(void *addr, size_t size);
+//! Flush, then invalidate data cache for `addr` for `size` bytes.
+//! `addr` and `size` should both be aligned by the cache line size.
+void dcache_flush_invalidate(const void *addr, size_t size);
+
+//! Aligns an address and size so that they are both aligned to the ICache line size, and still
+//! covers the range requested.
+void icache_align(uintptr_t *addr, size_t *size);
+//! Aligns an address and size so that they are both aligned to the DCache line size, and still
+//! covers the range requested.
+void dcache_align(uintptr_t *addr, size_t *size);
+
+//! For aligning things to work with the data cache, you will want to check what the cache line
+//! size is, and align accordingly. However, the hardware peripheral also might require a minimum
+//! alignment. So you pass the minimum alignment in bytes into `min`, and the return value is the
+//! mask you can apply to get the minimum aligned address.
+uint32_t dcache_alignment_mask_minimum(uint32_t min);