annotate loadtools/flash.h @ 1000:39a6090a052a

doc/How-flash-really-works: article written
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 09 Dec 2023 09:08:19 +0000
parents c5133c3c11b1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 /* this header file contains definitions for fc-loadtool flash support */
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2
506
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
3 /* global configuration */
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
4 #define FLASH_GLOBAL_CFG_NONE 0
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
5 #define FLASH_GLOBAL_CFG_SINGLE_4M 1
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
6 #define FLASH_GLOBAL_CFG_SINGLE_8M 2
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
7 #define FLASH_GLOBAL_CFG_DUAL_8M 3
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
8
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 /*
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 * The following structures represent an "abstract"
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 * description of flash devices.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 *
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 * A "region" is a consecutive group of erase units of the same size.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 */
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 struct flash_region_desc {
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 uint32_t sector_size;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 unsigned nsectors;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 };
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 #define CFI_MAX_REGIONS 4
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 /*
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 * The info in struct flash_geom can be either
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 * gathered from CFI or hard-coded.
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 */
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 struct flash_geom {
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 uint32_t total_size;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 unsigned nregions;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 struct flash_region_desc regions[CFI_MAX_REGIONS];
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 unsigned total_sectors;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 };
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
506
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
34 struct cfi_check {
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
35 int offset;
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
36 uint8_t expect_val;
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 };
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
976
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
39 /*
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
40 * In order to examine non-volatile sector lock state of AMD-style flash
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
41 * chips, we need to know how their sectors are grouped for the purpose
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
42 * of locking: aggregation of sectors into groups that can only be locked
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
43 * or unlocked as a unit, and also grouping into independent-read partitions
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
44 * where each partition needs its own Autoselect sequence.
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
45 */
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
46
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
47 struct lock_group_desc {
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
48 uint32_t block_size;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
49 unsigned nblocks;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
50 int is_group;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
51 int part_begin;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
52 int part_end;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
53 };
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
54
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
55 #define MAX_AMD_LOCK_GROUPS 8
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
56
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
57 struct amd_lock_info {
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
58 unsigned ngroups;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
59 struct lock_group_desc groups[MAX_AMD_LOCK_GROUPS];
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
60 int have_status_word_3;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
61 int have_status_word_7;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
62 int have_mode_lock_bits;
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
63 int have_pln_lock_reg;
979
c5133c3c11b1 fc-loadtool flash: implement PL-J PPB programming functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 976
diff changeset
64 int (*ppb_program_one)();
c5133c3c11b1 fc-loadtool flash: implement PL-J PPB programming functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 976
diff changeset
65 int (*ppb_program_all)();
c5133c3c11b1 fc-loadtool flash: implement PL-J PPB programming functions
Mychaela Falconia <falcon@freecalypso.org>
parents: 976
diff changeset
66 int (*ppb_erase_all)();
976
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
67 };
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
68
506
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
69 struct flash_device {
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 char *name;
506
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
71 struct cfi_check *cfi_table;
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
72 int required_global_config;
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
73 struct flash_geom *bank_geom[2];
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 struct flash_cmdset *cmdset;
976
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
75 struct amd_lock_info *lock_info[2];
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 };
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 /* the following structures describe flash banks as accessible to us */
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 struct sector_info {
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 uint32_t start;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 uint32_t size;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 };
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 struct flash_cmdset {
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 char *cmdset_name;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 int (*reset_cmd)();
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 int (*status_cmd)();
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 int (*unlock_sector)();
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 int (*erase_sector)();
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 int (*prep_for_program)();
711
44cdfc4fed4c fc-loadtool: flash prot-reg command implemented
Mychaela Falconia <falcon@freecalypso.org>
parents: 664
diff changeset
92 int (*read_prot_reg)();
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 char *loadagent_setbase_cmd;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 char *loadagent_program_cmd;
664
77a0001d8849 fc-loadtool: prep for binary flash programming
Mychaela Falconia <falcon@freecalypso.org>
parents: 652
diff changeset
95 char *loadagent_binmode_cmd;
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 int needs_unlock;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 };
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 struct flash_bank_info {
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 uint32_t base_addr;
506
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
101 struct flash_device *device;
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 struct flash_geom *geom;
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 struct flash_cmdset *ops;
976
ff4ce8d5ece4 fc-loadtool flash: definitions for AMD sector lock architecture
Mychaela Falconia <falcon@freecalypso.org>
parents: 711
diff changeset
104 struct amd_lock_info *amd_lock;
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 struct sector_info *sectors;
506
0dd2c87c1b63 fc-loadtool flash support overhaul
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
106 int detect_done;
0
e7502631a0f9 initial import from freecalypso-sw rev 1033:5ab737ac3ad7
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 };