annotate loadtools/flash.h @ 995:74024eb17e04

fc-loadtool help: improve language regarding 16 MiB flash chips In FC project history, 16 MiB flash originally meant Pirelli DP-L10. Then we got FCDEV3B with the same flash (our own design), but now we are discovering more Calypso devices that used such large flash, both late Calypso era (Sony Ericsson K2x0) as well as much earlier ones (FIC FLUID devices.txt file with 2004 dates, Leonardo+ rev 5). Hence we need to migrate to more generic or neutral language in associated documentation, without giving elevated status to specific examples that drove our early project history.
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 03 Dec 2023 21:11:12 +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 };