From dade16b86aa515e19b54aacfb0d5b768b64eb0e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?King=20K=C3=A9vin?= <kingkevin@cuvoodoo.info>
Date: Sun, 14 Aug 2016 19:25:38 +0200
Subject: [PATCH] document flash library

---
 lib/flash_internal.c | 111 +++++++++++++++++++++++++++++++++++++++++++
 lib/flash_internal.h |  45 ++++++++++++++++++
 2 files changed, 156 insertions(+)
 create mode 100644 lib/flash_internal.c
 create mode 100644 lib/flash_internal.h

diff --git a/lib/flash_internal.c b/lib/flash_internal.c
new file mode 100644
index 0000000..cf4dedf
--- /dev/null
+++ b/lib/flash_internal.c
@@ -0,0 +1,111 @@
+/* This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+/** library to read/write internal flash (code)
+ *  @file flash_internal.c
+ *  @author King Kévin <kingkevin@cuvoodoo.info>
+ *  @date 2016
+ *  @note peripherals used: none
+ */
+/* standard libraries */
+#include <stdint.h> // standard integer types
+#include <stdlib.h> // general utilities
+
+/* STM32 (including CM3) libraries */
+#include <libopencm3/stm32/desig.h> // device signature utilities
+#include <libopencm3/stm32/flash.h> // flash utilities
+
+#include "flash_internal.h" // flash storage library API
+#include "global.h" // global definitions
+
+/** the flash page size (medium-density devices have 1KiB page size) */
+#define PAGE_SIZE 1024
+
+bool flash_internal_read(uint32_t address, uint8_t *buffer, size_t size)
+{
+	// verify it's in the storage area
+	if (address<STORAGE_START || (address+size)>STORAGE_END) {
+		return false;
+	}
+	if (buffer==NULL || size==0) {
+		return false;
+	}
+
+	// copy data byte per byte
+	// a more efficient way would be to copy words, than the remaining bytes
+	for (size_t i=0; i<size; i++) {
+		buffer[i] = *((uint8_t*)address+i);
+	}
+
+	return true;
+}
+
+bool flash_internal_write(uint32_t address, uint8_t *buffer, size_t size)
+{
+	// verify it's in the storage area
+	if (address<STORAGE_START || (address+size)>STORAGE_END) {
+		return false;
+	}
+	if (buffer==NULL || size==0) {
+		return false;
+	}
+
+	uint8_t page[PAGE_SIZE]; // the complete page to write
+
+	flash_unlock(); // unlock flash to be able to write it
+	// go through memory
+	while (size) {
+		uint32_t page_pre = address%PAGE_SIZE; // the beginning data size in the page
+		address -= page_pre; // go to beginning of the page
+		storage_read(address, &page[0], page_pre); // copy existing data
+		if (size>=PAGE_SIZE-page_pre) { // no need to read tailing page data
+			for (uint16_t i=0; i<PAGE_SIZE-page_pre; i++) { // put buffer in page
+				page[page_pre+i] = buffer[i];
+			}
+			buffer += PAGE_SIZE-page_pre; // adjust remaining buffer
+			size -= PAGE_SIZE-page_pre; // adjust remaining size
+		} else { // need read tailing page data
+			for (uint16_t i=0; i<size; i++) { // put buffer in page
+				page[page_pre+i] = buffer[i];
+			}
+			buffer += size; // adjust remaining buffer
+			storage_read(address+page_pre+size, &page[page_pre+size], PAGE_SIZE-page_pre-size); // read tailing page data
+			size = 0; // adjust remaining size
+		}
+
+		// write page
+		flash_erase_page(address); // erase current page
+		if (flash_get_status_flags()!=FLASH_SR_EOP) { // operation went wrong
+			flash_lock(); // lock back flash to protect it
+			return false;
+		}
+		for (uint16_t i=0; i<PAGE_SIZE/2; i++) { // write whole page
+			flash_program_half_word(address+i*2, *((uint16_t*)page+i));
+			if (flash_get_status_flags()!=FLASH_SR_EOP) { // operation went wrong
+				flash_lock(); // lock back flash to protect it
+				return false;
+			}
+			if (*((uint16_t*)address+i)!=*((uint16_t*)page+i)) { // verify the programmed data is right
+				flash_lock(); // lock back flash to protect it
+				return false;
+			}
+		}
+
+		address += PAGE_SIZE; // go to next page
+
+	}
+	flash_lock(); // lock back flash to protect it
+
+	return true;
+}
diff --git a/lib/flash_internal.h b/lib/flash_internal.h
new file mode 100644
index 0000000..aaee58b
--- /dev/null
+++ b/lib/flash_internal.h
@@ -0,0 +1,45 @@
+/* This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+/** library to read/write internal flash (API)
+ *  @file flash_internal.h
+ *  @author King Kévin <kingkevin@cuvoodoo.info>
+ *  @date 2016
+ *  @note peripherals used: none
+ */
+#pragma once
+
+#include <libopencm3/stm32/desig.h> // device signature utilities
+
+/** how much data (in bytes) should we be able to store (be sure it's available and does not overlap the firmware) */
+#define STORAGE_SIZE 2048
+/** the end of the flash area where to store data */
+#define STORAGE_END FLASH_BASE+DESIG_FLASH_SIZE
+/** the start of the flash area where to store data (be sure it's after the firmware data) */
+#define STORAGE_START STORAGE_END-STORAGE_SIZE
+
+/** read data from internal flash
+ *  @param[in] address start address of the data to read
+ *  @param[out] buffer where to store the read data
+ *  @param[in] size how much data to read, in bytes
+ *  @return if read succeeded
+ */
+bool flash_internal_read(uint32_t address, uint8_t *buffer, size_t size);
+/** write data to internal flash
+ *  @param[in] address start address where to write data to
+ *  @param[in] buffer data to be written
+ *  @param[in] size how much data to write, in bytes
+ *  @return if write succeeded
+ */
+bool flash_internal_write(uint32_t address, uint8_t *buffer, size_t size);