commit 6fede366f7978c6e4901399a22b3f15926cc88a7
parent eb09e3781be61b23ff0b84c521475c99f6d74d26
Author: Brian Swetland <swetland@frotz.net>
Date: Sat, 13 Jun 2015 17:32:39 -0700
flash-agent: header file to define flash agent images
Diffstat:
| A | include/agent/flash.h | | | 130 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 130 insertions(+), 0 deletions(-)
diff --git a/include/agent/flash.h b/include/agent/flash.h
@@ -0,0 +1,130 @@
+// agent/flash.h
+//
+// Copyright 2015 Brian Swetland <swetland@frotz.net>
+//
+// 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.
+
+#ifndef _AGENT_FLASH_H_
+#define _AGENT_FLASH_H_
+
+typedef unsigned int u32;
+
+#define AGENT_MAGIC 0x42776166
+#define AGENT_VERSION 0x00010000
+
+typedef struct flash_agent {
+ u32 magic;
+ u32 version;
+ u32 flags;
+ u32 load_addr;
+
+ u32 data_addr;
+ u32 data_size; // bytes
+ u32 flash_addr;
+ u32 flash_size; // bytes
+
+ u32 reserved0;
+ u32 reserved1;
+ u32 reserved2;
+ u32 reserved3;
+
+ int (*setup)(struct flash_agent *agent);
+ int (*erase)(void *flash, u32 size);
+ int (*write)(void *flash, void *data, u32 size);
+ int (*ioctl)(u32 op, void *ptr, u32 arg0, u32 arg1);
+} flash_agent;
+
+int flash_agent_setup(flash_agent *agent);
+int flash_agent_erase(void *flash, u32 size);
+int flash_agent_write(void *flash, void *data, u32 size);
+int flash_agent_ioctl(u32 op, void *ptr, u32 arg0, u32 arg1);
+
+#define ERR_NONE 0
+#define ERR_FAIL -1
+#define ERR_INVALID -2
+#define ERR_ALIGNMENT -3
+
+#define FLAG_WSZ_256B 0x00000100
+#define FLAG_WSZ_512B 0x00000200
+#define FLAG_WSZ_1K 0x00000400
+#define FLAG_WSZ_2K 0x00000800
+#define FLAG_WSZ_4K 0x00001000
+// optional hints as to underlying write block sizes
+
+#define FLAG_BOOT_ROM_HACK 0x00000001
+// Allow a boot ROM to run after RESET by setting a watchpoint
+// at 0 and running until the watchpoint is hit. Necessary on
+// some parts which require boot ROM initialization of Flash
+// timing registers, etc.
+
+
+// Flash agent binaries will be downloaded to device memory at
+// fa.load_addr. The memory below this address will be used as
+// the stack for method calls. It should be sized appropriately.
+//
+// The fa.magic field will be replaced with 0xbe00be00 (two
+// Thumb BKPT instructions) before download to device.
+//
+// Calling convention for flash_agent methods:
+// 1. SP will be set to fa.load_addr - 4
+// 2. LR will be set to fa.load_addr
+// 3. PC will be set to the method address
+// 4. R0..R3 will be loaded with method arguments
+// 5. Processor will be resumed (in Privileged Thread mode)
+// 6. Upon processor entry to debug mode
+// a. if PC == fa.base_addr, status read from R0
+// b. else status = fatal error
+
+
+// setup() must be invoked after processor reset and before any
+// other methods are invoked. The fields data_addr, data_size,
+// flash_addr, and flash_size are read back after this method
+// returns success (to allow it to dynamically size flash based
+// on part ID, etc).
+
+// fa.data_size must be a multiple of the minimum block size that
+// fa.write requires, so that if the host has to issue a series
+// of fa.write calls to do a larger-than-data-buffer-sized flash write,
+// subsequent write calls will have appropriate alignment.
+//
+// fa.write() may round writes up the the minimum write block size
+// as necessary, and should fill with 0s in that case.*
+//
+// fa.write() behaviour is undefined if the underlying flash has not
+// been erased first. It may fail (ERR_FAIL) or it may appear to
+// succeed, but flash contents may be incorrect.
+//
+// fa.write() may fail (ERR_ALIGN) if the start address is not aligned
+// with a flash page or block.*
+//
+// fa.erase() may round up to the next erasure block size if necessary
+// to ensure the requested region is erased.*
+//
+// fa.erase(fa.flash_addr, fa.flash_size) should cause a full erase if
+// possible.
+//
+// fa.ioctl() must return ERR_INVALID if op is unsupported.
+// Currently no ops are defined, but OTP/EEPROM/Config bits are
+// planned to be managed with ioctls.
+//
+// Bogus parameters may cause failure (ERR_INVALID)
+//
+// * In general, conveying the full complexity of embedded flash
+// configuration (which could include various banks of various sizes,
+// with differing write and erase block size requirements) is not
+// attempted. The goal is to provide an agent that can reasonably
+// handle reasonable flash requests (eg the user knows what a sane
+// starting alignment, etc is, does not split logical "partitions"
+// across physical erase block boundaries, etc)
+
+#endif
