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