FreeCalypso > hg > fc-tourmaline

annotate doc/Nucleus-change @ 197:a963d8cd8682

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bwsplash/README: additional notes
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 28 Mar 2021 23:51:56 +0000
parents a1799f6d6aa7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.