FreeCalypso > hg > fc-tourmaline
annotate doc/Nucleus-change @ 257:3edd1a600218
mfw_mme.c: hack to get initial battery state on boot
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Thu, 13 May 2021 04:32:53 +0000 |
parents | a1799f6d6aa7 |
children |
rev | line source |
---|---|
54
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
1 The specific integration of ATI Nucleus PLUS RTOS in TI's stable TCS211 fw |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
2 (which served as the baseline for several vendors' production fw) exhibits one |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
3 hair-raising bug. While we don't know for sure where and how they maintained |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
4 Nucleus library sources for compilation (the version we got has them censored |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
5 out), we do see that Nucleus header files (nucleus.h and ??_defs.h) exist in |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
6 two different locations in the source tree in two different versions: |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
7 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
8 * One version exists under chipsetsw/os/nucleus |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
9 * The other version exists under gpf/inc/nuc & gpf/inc/nuc/arm7 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
10 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
11 The two versions of these header files under these two paths in TCS211 are not |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
12 the same! The main nucleus.h header file is the same in both places, cs_defs.h |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
13 and tm_defs.h versions differ only in comments, but tc_defs.h is the real |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
14 kicker: the version under gpf/inc/nuc has an extra field added to the TC_HCB |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
15 aka NU_HISR structure, making this structure one word longer than in the other |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
16 version! More specifically, in ATI's original Nucleus this structure is 22 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
17 words long with 4 unused dummy words at the end; TI's GPF version adds a fifth |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
18 dummy word (thankfully toward the end, not shifting any actually-used members |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
19 of the struct), putting the total struct size at 23 words. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
20 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
21 It would be one thing if TI had made this change consistently, but they didn't: |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
22 some modules were compiled with one version of the headers and got the 22-word |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
23 version of the struct, while other modules were compiled with the other header |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
24 file version and got the 23-word version of the struct. How can their fw work |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
25 with this bug in it? Answer: TCS211 fw works despite this Nucleus integration |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
26 bug because: |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
27 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
28 * None of the actually-used members of the struct change offsets between the |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
29 two versions; |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
30 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
31 * Some places in the code have 22-word structs allocated in memory while other |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
32 places have 23-word structs, but when they pass pointers to these structs to |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
33 Nucleus API functions, those functions don't access past the actually-used |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
34 part at the beginning (the part before dummy words), and they never do |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
35 anything like zeroing out the full size of the expected struct. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
36 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
37 * The only place in TCS211 fw where the total size of the struct matters is |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
38 where NU_HISR is embedded in another structure, and there is one such place |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
39 in GPF. Here breakage would result if different modules using these structs |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
40 and arrays were compiled with different header file versions, but all modules |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
41 that touch this part are compiled with the GPF version of nucleus.h, NU_DEBUG |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
42 and tc_defs.h. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
43 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
44 Needless to say, resolving this bogosity has been an important part of |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
45 FreeCalypso firmware deblobbing. Naturally the most ideal solution would have |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
46 been to remove the bogus extra word added by TI and consistently use the |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
47 original 22-word struct everywhere, but there is one further complication: I |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
48 (Mother Mychaela) don't feel comfortable with moving away from the original blob |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
49 version of the OSL component of GPF, and these COFF objects have been compiled |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
50 with the 23-word version of TC_HCB aka NU_HISR. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
51 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
52 The following alternative approach has been implemented in FC Tourmaline: |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
53 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
54 * The new source version of Nucleus by Comrade XVilka has been checked in under |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
55 src/nucleus, and this new source version is the one we are using instead of |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
56 TI's binary object version. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
57 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
58 * The new Nucleus header files src/nucleus/nucleus.h and src/nucleus/??_defs.h |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
59 are the only ones used in Tourmaline - both old versions have been removed |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
60 from active -I include paths. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
61 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
62 * The new src/nucleus/tc_defs.h header file has been patched to replicate TI's |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
63 23-word version of TC_HCB aka NU_HISR, and the NU_HISR_SIZE definition in |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
64 src/nucleus/nucleus.h has also been adjusted to match. |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
65 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
66 Thus we are using the 23-word version of TC_HCB aka NU_HISR everywhere, with 5 |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
67 dummy words at the end rather than 4, adding 4 extra bytes of wasted RAM space |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
68 to every instance of this struct throughout the firmware - but there are only a |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
69 small number of these instances, thus the waste is negligible. In return we |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
70 gain 100% consistency (the same version of the struct is used everywhere in our |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
71 fw), and we retain the ability to keep the original OSL blobs which I am not |
a1799f6d6aa7
doc/Nucleus-change article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff
changeset
|
72 ready to give up. |