flash.h (4746B)
1 // agent/flash.h 2 // 3 // Copyright 2015 Brian Swetland <swetland@frotz.net> 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 17 #ifndef _AGENT_FLASH_H_ 18 #define _AGENT_FLASH_H_ 19 20 typedef unsigned int u32; 21 22 #define AGENT_MAGIC 0x42776166 23 #define AGENT_VERSION 0x00010000 24 25 typedef struct flash_agent { 26 u32 magic; 27 u32 version; 28 u32 flags; 29 u32 load_addr; 30 31 u32 data_addr; 32 u32 data_size; // bytes 33 u32 flash_addr; 34 u32 flash_size; // bytes 35 36 u32 reserved0; 37 u32 reserved1; 38 u32 reserved2; 39 u32 reserved3; 40 41 #ifdef _AGENT_HOST_ 42 u32 setup; 43 u32 erase; 44 u32 write; 45 u32 ioctl; 46 #else 47 int (*setup)(struct flash_agent *agent); 48 int (*erase)(u32 flash_addr, u32 length); 49 int (*write)(u32 flash_addr, const void *data, u32 length); 50 int (*ioctl)(u32 op, void *ptr, u32 arg0, u32 arg1); 51 #endif 52 } flash_agent; 53 54 #ifndef _AGENT_HOST_ 55 int flash_agent_setup(flash_agent *agent); 56 int flash_agent_erase(u32 flash_addr, u32 length); 57 int flash_agent_write(u32 flash_addr, const void *data, u32 length); 58 int flash_agent_ioctl(u32 op, void *ptr, u32 arg0, u32 arg1); 59 #endif 60 61 #define ERR_NONE 0 62 #define ERR_FAIL -1 63 #define ERR_INVALID -2 64 #define ERR_ALIGNMENT -3 65 66 #define FLAG_WSZ_256B 0x00000100 67 #define FLAG_WSZ_512B 0x00000200 68 #define FLAG_WSZ_1K 0x00000400 69 #define FLAG_WSZ_2K 0x00000800 70 #define FLAG_WSZ_4K 0x00001000 71 // optional hints as to underlying write block sizes 72 73 #define FLAG_BOOT_ROM_HACK 0x00000001 74 // Allow a boot ROM to run after RESET by setting a watchpoint 75 // at 0 and running until the watchpoint is hit. Necessary on 76 // some parts which require boot ROM initialization of Flash 77 // timing registers, etc. 78 79 80 // Flash agent binaries will be downloaded to device memory at 81 // fa.load_addr. The memory below this address will be used as 82 // the stack for method calls. It should be sized appropriately. 83 // 84 // The fa.magic field will be replaced with 0xbe00be00 (two 85 // Thumb BKPT instructions) before download to device. 86 // 87 // Calling convention for flash_agent methods: 88 // 1. SP will be set to fa.load_addr - 4 89 // 2. LR will be set to fa.load_addr 90 // 3. PC will be set to the method address 91 // 4. R0..R3 will be loaded with method arguments 92 // 5. Processor will be resumed (in Privileged Thread mode) 93 // 6. Upon processor entry to debug mode 94 // a. if PC == fa.base_addr, status read from R0 95 // b. else status = fatal error 96 97 98 // setup() must be invoked after processor reset and before any 99 // other methods are invoked. The fields data_addr, data_size, 100 // flash_addr, and flash_size are read back after this method 101 // returns success (to allow it to dynamically size flash based 102 // on part ID, etc). 103 // - ERR_INVALID indicates an unsupported part 104 105 // fa.data_size must be a multiple of the minimum block size that 106 // fa.write requires, so that if the host has to issue a series 107 // of fa.write calls to do a larger-than-data-buffer-sized flash write, 108 // subsequent write calls will have appropriate alignment. 109 // 110 // fa.write() may round writes up the the minimum write block size 111 // as necessary, and should fill with 0s in that case.* 112 // 113 // fa.write() behaviour is undefined if the underlying flash has not 114 // been erased first. It may fail (ERR_FAIL) or it may appear to 115 // succeed, but flash contents may be incorrect. 116 // 117 // fa.write() may fail (ERR_ALIGN) if the start address is not aligned 118 // with a flash page or block.* 119 // 120 // fa.erase() may round up to the next erasure block size if necessary 121 // to ensure the requested region is erased.* 122 // 123 // fa.erase(fa.flash_addr, fa.flash_size) should cause a full erase if 124 // possible. 125 // 126 // fa.ioctl() must return ERR_INVALID if op is unsupported. 127 // Currently no ops are defined, but OTP/EEPROM/Config bits are 128 // planned to be managed with ioctls. 129 // 130 // Bogus parameters may cause failure (ERR_INVALID) 131 // 132 // * In general, conveying the full complexity of embedded flash 133 // configuration (which could include various banks of various sizes, 134 // with differing write and erase block size requirements) is not 135 // attempted. The goal is to provide an agent that can reasonably 136 // handle reasonable flash requests (eg the user knows what a sane 137 // starting alignment, etc is, does not split logical "partitions" 138 // across physical erase block boundaries, etc) 139 140 #endif