annotate README @ 220:0ed36de51973

ABB semaphore protection overhaul The ABB semaphone protection logic that came with TCS211 from TI was broken in several ways: * Some semaphore-protected functions were called from Application_Initialize() context. NU_Obtain_Semaphore() called with NU_SUSPEND fails with NU_INVALID_SUSPEND in this context, but the return value wasn't checked, and NU_Release_Semaphore() would be called unconditionally at the end. The latter call would increment the semaphore count past 1, making the semaphore no longer binary and thus no longer effective for resource protection. The fix is to check the return value from NU_Obtain_Semaphore() and skip the NU_Release_Semaphore() call if the semaphore wasn't properly obtained. * Some SPI hardware manipulation was being done before entering the semaphore- protected critical section. The fix is to reorder the code: first obtain the semaphore, then do everything else. * In the corner case of L1/DSP recovery, l1_abb_power_on() would call some non-semaphore-protected ABB & SPI init functions. The fix is to skip those calls in the case of recovery. * A few additional corner cases existed, all of which are fixed by making ABB semaphore protection 100% consistent for all ABB functions and code paths. There is still one remaining problem of priority inversion: suppose a low- priority task calls an ABB function, and some medium-priority task just happens to preempt right in the middle of that semaphore-protected ABB operation. Then the high-priority SPI task is locked out for a non-deterministic time until that medium-priority task finishes its work and goes back to sleep. This priority inversion problem remains outstanding for now.
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 26 Apr 2021 20:55:25 +0000
parents a62e5bf88434
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
50
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 FreeCalypso Tourmaline firmware project
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 =======================================
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 In chronological terms, FC Tourmaline is our fourth firmware offering after
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 Citrine, Magnetite and Selenite. FC Tourmaline supports the following two
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 fundamental modes of operation:
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 * AT-command-controlled modem operation (no UI) is currently unchanged from
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 Magnetite hybrid; standard modem operation is supported on Tango/Caramel2,
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 FCDEV3B and Openmoko hardware targets.
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 * The new work being done in Tourmaline is phone handset functionality - the
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 goal is to produce firmware that can operate a suitable hardware unit as an
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 untethered end user phone. Only two hardware targets are supported in this
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 FC Tourmaline handset UI development venture: FC Luna development platform
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 and Motorola C139.
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 See the following articles under doc for further details:
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 C139-notes -- running smallbw version of the UI on Mot C139
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 Luna-notes -- running both UI versions on FC Luna
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 Modem-operation -- using the modem configuration
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 Technical details
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 =================
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 Just like FC Selenite, Tourmaline is derived from the hybrid config of
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 Magnetite. Also in common with Selenite, Tourmaline uses the new source
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 version of Nucleus. However, unlike Selenite, Tourmaline retains sole use of
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 the original TMS470 compiler (runs under Wine), retains the original blob
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 versions of OSL and OSX glue components of GPF in the default config (see
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 doc/Blob-status), and includes both modem and handset functional configs.
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 Purpose and goal
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 ================
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 As of late 2020, FreeCalypso has achieved everything that needs to be done on
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 the modem side: our Magnetite hybrid or Tourmaline stdmodem firmware running on
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 our Tango modem module embodies complete fulfillment of our long-standing desire
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 for a standard GSM+GPRS modem module with fully published circuit schematics and
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 firmware source code. No more significant work beyond maintenance is deemed to
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 be needed on the modem side.
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 OTOH, the other need for a FreeCalypso handset that can replace proprietary
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 phones like Mot C1xx or Pirelli DP-L10 running their original proprietary fw
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 still remains as unmet as it was when we started back in 2013. Thus the new
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 FreeCalypso work direction is to finally produce this FC handset, initially in
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 the form of FC firmware running on Mot C139 (and on FC Luna to keep up the
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 bigcolor config) and allowing the possibility of new FreeCalypso handset hw.
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 Seen from the perspective of handset rather than modem functionality, the
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 direction taken in Citrine and Selenite (going for 100% blob-free compilation
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 with gcc) is the wrong way to go. That direction would make sense if one cared
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 only about modem functionality rather than handset, but we are currently in the
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 opposite situation. In the case of handset functionality, going for a compiler
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 change to gcc in our current state when so many other parts are broken and in
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 need of fixing would be pure insanity, and we are not going there. Let us
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 first produce a working FreeCalypso handset (with fw compiled with TMS470 under
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 Wine, keeping the tiny remaining blobs) that can replace Mot/Pirelli's original
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 proprietary firmwares for daily use, and *then* think about moving to 100%
a62e5bf88434 first round of documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 blob-free gcc - in this order.