FreeCalypso > hg > freecalypso-sw

annotate doc/Firmware_Architecture @ 923:10b4bed10192

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gsm-fw/L1: fix for the DSP patch corruption bug The L1 code we got from the LoCosto fw contains a feature for DSP CPU load measurement. This feature is a LoCosto-ism, i.e., not applicable to earlier DBB chips (Calypso) with their respective earlier DSP ROMs. Most of the code dealing with that feature is conditionalized as #if (DSP >= 38), but one spot was missed, and the MCU code was writing into an API word dealing with this feature. In TCS211 this DSP API word happens to be used by the DSP code patch, hence that write was corrupting the patched DSP code.
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Mon, 19 Oct 2015 17:13:56 +0000
parents d92b110e06e0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
868
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
1 Our FreeCalypso GSM firmware follows the same architecture as TI's TCS211;
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
2 this document is an attempt to describe this architecture.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
3
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
4 Nucleus environment
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
5 ===================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
6
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
7 Like all classic TI firmwares, ours is based on the Nucleus PLUS RTOS. Just
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
8 like TI's original code on which we are based, we use only a small subset of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
9 the functionality provided by Nucleus - but because the latter is a library,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
10 the pieces we don't use simply don't get pulled into the link. The main
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
11 function we get out of Nucleus is the scheduling of threads, or tasks as
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
12 Nucleus calls them.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
13
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
14 Our entry point code as we receive control from the Calypso boot ROM or from
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
15 other bootloaders on crippled targets or from loadagent in the case of fc-xram
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
16 loadable builds does some absolutely minimal initialization (set up sensible
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
17 memory access timings, copy iram.text to IRAM and .data to XRAM if we are
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
18 booting from flash, zero out our two bss segments (int.bss and ext.bss)) and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
19 jumps to Nucleus' assembly init entry point. Prior to jumping to Nucleus, we
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
20 don't even have a stack (all init code prior to that point is pure assembly and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
21 uses only ARM registers); Nucleus then sets up the stack pointer for everything
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
22 running under its control.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
23
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
24 Aside from just a few exceptions (ARM exception handlers come to mind, never
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
25 mind the pun), every piece of code in the firmware executes in one of the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
26 following contexts:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
27
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
28 * Application_Initialize(): this function and everything called from it execute
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
29 just before Nucleus' thread scheduler starts; at this point interrupts are
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
30 disabled at the ARM7 core level (in the CPSR) and must not be enabled; the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
31 stack is Nucleus' "system stack" which is also used by the scheduler and LISRs
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
32 as explained below.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
33
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
34 * Regular threads or tasks: once Application_Initialize() finishes, all code
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
35 with the exception of interrupt handlers (LISRs and HISRs as explained below)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
36 runs in the context of some Nucleus task. Whenever you are trying to debug
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
37 or simply understand some piece of code in the firmware, the first question
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
38 you should ask is "which task does this code execute in?". Most functional
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
39 components run in their own tasks, i.e., a given piece of code is only
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
40 intended to run within the Nucleus task that belongs to the component in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
41 question. On the other hand, some components are implemented as APIs,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
42 functions to be called from other components: these don't have their own task
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
43 associated with them, and instead they run in the context of whatever task
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
44 they were called from. Some only get called from one task: for example, the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
45 "uartfax" driver API calls only get called from the protocol stack's UART
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
46 entity, which is its own task. Other component API functions like FFS and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
47 trace can get called from just about any task in the system. Many components
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
48 have both their own task and some API functions to be called from other tasks,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
49 and the API functions oftentimes post messages to the task to be worked on by
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
50 the latter; the just-mentioned FFS and trace functions work in this manner.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
51
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
52 In our current GSM firmware (just like in TCS211) every Nucleus task is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
53 created either through Riviera or through GPF, and not in any other way - see
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
54 the description of Riviera and GPF below.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
55
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
56 * LISRs (Low level Interrupt Service Routines): these are the interrupt handlers
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
57 that run immediately when an ARM IRQ or FIQ comes in. The code at the IRQ and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
58 FIQ vector entry points calls Nucleus' magic stack switching function
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
59 (switches the CPU from IRQ/FIQ into SVC mode, saves the interrupted thread's
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
60 registers on that thread's stack, and switches to the "system" stack) and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
61 then calls TI's IRQ dispatcher implemented in C. The latter figures out
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
62 which Calypso interrupt needs to be handled and calls the handler configured
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
63 in the compiled-in table. Nucleus' LISR registration framework is not used
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
64 by the GSM fw, but these interrupt handlers should be viewed as LISRs
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
65 nonetheless.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
66
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
67 There is one additional difference between canonical Nucleus and TI's version
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
68 (we've replicated the latter): canonical Nucleus was designed to support
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
69 nested LISRs, i.e., IRQs re-enabled in the magic stack switching function,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
70 but in TI's version which we follow this IRQ re-enabling is removed: each LISR
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
71 runs with interrupts disabled and cannot be interrupted. (The corner case of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
72 an FIQ interruping an IRQ remains to be looked at more closely as bugs may be
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
73 hiding there, but Calypso doesn't really use FIQ interrupts.) There is really
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
74 no need for LISR nesting in our GSM fw, as each LISR is very short: most LISRs
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
75 do nothing more than trigger the corresponding HISR.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
76
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
77 * HISRs (High level Interrupt Service Routines): these hold an intermediate
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
78 place between LISRs and tasks, similar to softirqs in the Linux kernel. A
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
79 HISR can be activated by a LISR calling NU_Activate_HISR(), and when the LISR
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
80 returns, the HISR will run before the interrupted task (or some higher
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
81 priority task, see below) can resume. HISRs run with CPU interrupts enabled,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
82 thus more interrupts can occur, with their LISRs executing and possibly
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
83 triggering other HISRs. All triggered HISRs must complete and thereby go
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
84 "quiescent" before task scheduling resumes, i.e., all HISRs as a group have a
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
85 higher scheduling priority than tasks.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
86
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
87 Nucleus implements priority scheduling for tasks. Tasks have their priority set
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
88 when they are created (through Riviera or GPF, see below), and a higher priority
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
89 task will run until it gets blocked waiting for something, at which time lower
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
90 priority tasks will run. If a lower priority task sends a message to a higher
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
91 priority task, unblocking the latter which was waiting for incoming messages,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
92 the lower priority task will effectively suspend itself immediately while the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
93 higher priority task runs to process the message it was sent.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
94
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
95 HISRs oftentimes post messages to their associated tasks as well; if one of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
96 these messages unblocks a higher priority task, that unblocked task will run
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
97 upon the completion of the HISR instead of the original lower priority task
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
98 that was interrupted by the LISR that triggered the HISR. Nucleus' scheduler
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
99 is fun!
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
100
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
101 Major functional blocks
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
102 =======================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
103
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
104 At the highest level, all code in TI's classic firmwares and in our FreeCalypso
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
105 fw can be divided into 3 broad groupings:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
106
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
107 * GSM Layer 1: this code was developed by TI, is highly specific to TI's
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
108 baseband chipset family in general and to specific individual chips in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
109 particular (the code is liberally sprinkled with conditional compilation
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
110 based on DBB type, ABB type, DSP ROM version and so on), and is absolutely
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
111 necessary in order to operate a Calypso device as a GSM MS (mobile station)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
112 and not merely as a general purpose microprocessor platform. This code can
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
113 be considered to be the most important part of the entire firmware.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
114
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
115 L1 interties with Nucleus and with the G23M stack (with which it needs to
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
116 communicate) in a very peculiar way described later in this article.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
117
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
118 * G23M protocol stack: at the beginning of TI's involvement in the GSM baseband
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
119 chipset business, they only developed and maintained their own L1 code, while
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
120 the rest of the protocol stack (which is hardware-independent) was licensed
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
121 from another company called Condat. Later Condat as a company was fully
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
122 acquired by TI, and the once-customer of this code became its owner. The
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
123 name of TI/Condat's implementation of GSM layers 2&3 for the MS side is G23M,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
124 and it forms its own major division of the overall fw architecture.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
125
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
126 Underlying the G23M stack is a special layer called GPF, which was originally
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
127 Condat's Generic Protocol stack Framework. Apparently Condat was in the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
128 business of developing and maintaining a whole bunch of protocol stacks: GSM
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
129 MS side, GSM network side, TETRA and who knows what else. GPF was their
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
130 common underpinning for all of their protocol stack projects, which ran on top
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
131 of many different OS environments: Nucleus, pSOS, VxWorks, Unix/Linux, Win32
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
132 and who knows what else.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
133
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
134 In the case of FreeCalypso GSM fw, both the protocol stack and the underlying
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
135 OS environment are fixed: GSM and Nucleus, respectively. But GPF is still a
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
136 critically important layer in the firmware architecture: in addition to
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
137 serving as the glue between the G23M stack and Nucleus, it provides some
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
138 important support infrastructure for the protocol stack.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
139
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
140 * Miscellaneous peripheral accessories: under this category I (Space Falcon)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
141 place everything implemented through TI's Riviera framework. Historical
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
142 evidence indicates that TI's earliest firmwares did not have this part, i.e.,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
143 Riviera and everything built on top of it is a "non-essential" later
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
144 addition. It appears that TI originally invented Riviera in order to support
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
145 the development of fancy "feature phone" UI/application layers, complete with
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
146 Java, MMS, WAP, games and whatnot - things upon which our FreeCalypso project
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
147 looks with disdain - but in the TCS211 firmware from 2007 which I used as the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
148 reference for FreeCalypso this Riviera framework serves as the foundation for
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
149 some small but essential pieces of functionality: the FFS implementation, the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
150 SPI-based ABB access driver, the RTC driver and the debug trace facility.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
151
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
152 While it is certain that TI had some non-Riviera implementation of the just-
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
153 listed essential pieces in their earliest pre-Riviera days, trying to find
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
154 surviving sources from those days would be a "mission impossible" task. OTOH,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
155 reusing the Riviera code from TCS211 was quite easy, as the copy of TCS211 we
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
156 got has it in full source form with nothing omitted. Therefore, I took the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
157 sensible easy road and kept Riviera in FreeCalypso.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
158
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
159 The above division of the firmware into 3 broad functional groupings also
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
160 corresponds quite neatly with where each piece of our source code originally
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
161 came from. Our versions of L1 and G23M came in their entirety from TI's TCS3.2
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
162 program targeting their later LoCosto chipset (specifically from the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
163 TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src.zip release from Peek/FGW), whereas
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
164 everything in the 3rd division (Riviera and everything built on top of it) came
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
165 from our TCS211/Leonardo source from Sotovik.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
166
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
167 The just-listed divisions of the firmware are really separate software
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
168 environments which are linked together into one final image, but which have
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
169 very little in the way of interties. Each of the 3 realms has its own very
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
170 different coding style, its own set of header files and its own defined types.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
171 It is very rare for a module from one realm to include any header files or call
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
172 any functions from another realm, and while they all ultimately run on top of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
173 Nucleus, they interface with Nucleus in different ways: G23M goes through GPF,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
174 everything in Riviera land goes through Riviera, and L1 uses its own bizarre
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
175 mechanism which in our fw ends up going through GPF but hasn't always been this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
176 way - to be explained lated in this article.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
177
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
178 Also note that there is no mention of any handset UI code (or MMI in the GSM
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
179 industry's sexist speak) in the above breakdown of code divisions. This
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
180 document describes the architecture of TI's modem firmware in which the highest
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
181 layer is the AT command interface (part of the G23M suite, or its uppermost
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
182 layer to be precise), and which does not include any UI code. Our TI reference
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
183 sources do include their "MMI" code, but I haven't studied it closely enough
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
184 yet to comment on it properly, and the version of TCS211 which serves as our
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
185 primary reference is set up for the modem configuration without this "MMI" part.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
186 Making sense of TI's "MMI" code is a task to be tackled later in the project
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
187 when we have a working modem and are ready to start building a usable handset
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
188 with UI.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
189
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
190 Riviera and GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
191 ===============
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
192
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
193 Riviera and GPF are two parallel/independent/competing wrappers around or
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
194 layers above Nucleus. The way in which they are treated in our FreeCalypso fw
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
195 architecture is somewhat inverted: originally GPF was the essential framework
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
196 underlying the G23M stack (and to which L1 was also attached in a hacky way)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
197 while Riviera was added to support non-essential frills, but in our current FC
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
198 fw Riviera is always included just like Nucleus, whereas GPF only needs to be
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
199 included in the build when building with feature gsm (full GSM MS functionality)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
200 or feature l1stand (L1 standalone) - but is not needed if one wishes to build
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
201 an "in vivo" FFS editing agent, for example.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
202
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
203 This peculiar arrangement happened because of the source code availability
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
204 situation we found ourselves in. TCS211 uses real Riviera that is fully
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
205 independent of GPF (see below), and our copy thereof came with this part in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
206 full source form. On the other hand, we never got the complete original source
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
207 for GPF in one piece, thus our FC version of GPF had to be reconstructed from
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
208 bits and pieces. For this reason I made the decision early on to include
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
209 Riviera and some RV-based components in the "mandatory core" part of our FC fw
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
210 architecture, while leaving GPF to be worked on later. And when I did get to
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
211 reintegrating GPF, at that point it was natural to make it into an "optional"
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
212 component that is included only when needed.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
213
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
214 At some point in their post-Calypso TCS3.x program TI decided to eliminate
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
215 Riviera as an independent framework and to reimplement Riviera APIs (used by
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
216 peripheral but necessary code such as FFS, ETM, various drivers etc) over GPF.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
217 This arrangement is used in the TCS3.2 LoCosto code from which we lifted our
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
218 versions of L1 and G23M. However, I (Space Falcon) chose not to adopt this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
219 approach for FreeCalypso, and mimic the TCS211 way (Riviera entirely
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
220 independent of GPF) instead. The reasons were twofold: (1) there was no full
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
221 source for GPF and a painstaking reconstruction effort was required before we
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
222 could have our own working version of GPF in our gcc-built fw, and (2) I felt
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
223 more comfortable and familiar with following TCS211.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
224
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
225 Start-up process
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
226 ================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
227
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
228 I mentioned earlier that every Nucleus task in our firmware gets created and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
229 started either through Riviera or through GPF. All GPF tasks are created and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
230 placed into the runable state in the Application_Initialize() context: the work
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
231 is done by GPF init code in gsm-fw/gpf/frame/frame.c, and the top level GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
232 init function called from Application_Initialize() is StartFrame(). Thus when
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
233 Application_Initialize() finishes and the Nucleus thread scheduler starts
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
234 running for the first time, all GPF tasks are there to be scheduled.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
235
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
236 There is a compiled-in table of all protocol stack entities and the tasks in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
237 which they need to run which (in our fw) lives under gsm-fw/gpf/conf and which
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
238 logically belongs to GPF. Canonically each protocol stack entities runs in its
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
239 own task, but sometimes two or more are combined to run in the same task: for
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
240 example, in the minimal GSM "voice only" configuration (no CSD, fax or GPRS)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
241 CC, SMS and SS entities share the same task named CM. Unlike Riviera, GPF does
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
242 not support dynamic starting and stopping of tasks.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
243
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
244 As each GPF task starts running (immediately upon entry into Nucleus' scheduling
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
245 loop as Application_Initialize() finishes), pf_TaskEntry() function in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
246 gsm-fw/gpf/frame/frame.c is the first code it runs. This function creates the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
247 queue for messages to be sent to all entities running within the task in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
248 question, calls each entity's pei_init() function (repeatedly until it succeeds:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
249 it will fail until the other entities to which this entity needs to send
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
250 messages have created their message queues), and then falls into the main body
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
251 of the task: for all "regular" entities/tasks except L1, this main body consists
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
252 of waiting for messages (or signals or timeouts) to arrive on the queue and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
253 dispatching each received message to the appropriate handler in the right
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
254 entity.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
255
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
256 Riviera tasks get started in a different way. The same Application_Initialize()
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
257 function that calls StartFrame() to create and start all GPF tasks also calls
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
258 create_tasks() (found in gsm-fw/riviera/init/create_RVtasks.c), the appinit-time
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
259 function for starting the Riviera environment. But this function does not
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
260 create and start every configured Riviera task like StartFrame() does for GPF.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
261 Instead it creates a special helper task which will do this work once scheduled.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
262 Thus at the completion of Application_Initialize() and the beginning of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
263 scheduling the set of runable Nucleus tasks consists of all GPF ones plus the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
264 special RV starter task. Once the RV starter task gets scheduled, it will call
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
265 rvm_start_swe() to launch every configured Riviera SWE (SoftWare Entity), which
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
266 in turns entails creating the tasks in which these SWEs are to run.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
267
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
268 Dynamic memory allocation
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
269 =========================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
270
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
271 All dynamic memory allocation (i.e., all RAM usage beyond statically allocated
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
272 variables and buffers) is once again done either through Riviera or through GPF,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
273 and in no other way. Ultimately all areas of the physical RAM that will ever
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
274 be used by the fw in any way are allocated when the fw is compiled and linked:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
275 the areas from which Riviera and GPF serve their dynamic memory allocations are
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
276 statically allocated as char arrays in the respective C modules and placed in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
277 the int.ram or ext.ram section as appropriate; Riviera and GPF then provide
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
278 API functions that allocate memory dynamically from these statically allocated
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
279 large pools.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
280
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
281 Riviera and GPF have entirely separate memory pools from which they serve their
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
282 respective clients, hence there is no possibility of one affecting the other.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
283 Riviera's memory allocation scheme is very much like the classic malloc&free:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
284 there is one large unstructured pool from which all allocations are made, one
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
285 can allocate a chunk of any size, free chunks are merged when physically
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
286 adjacent, and fragmentation is an issue: a memory allocation request may fail
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
287 even when there is enough memory available in total if it is too fragmented.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
288
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
289 GPF's dynamic memory allocation facility is considerably more robust: while it
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
290 does maintain one or two (depending on configuration) memory pools of the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
291 traditional "dynamic" kind (like malloc&free, susceptible to fragmentation),
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
292 most GPF memory allocation works on "partition" memory instead. Here GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
293 maintains 3 separate groups of pools: PRIM, TEST and DMEM; each allocation
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
294 request must specify the appropriate pool group and cannot affect the others.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
295 Within each pool there is a fixed number of partitions of a fixed size: for
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
296 example, in TI's TCS211 GSM+GPRS configuration the PRIM pool group consists of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
297 190 partitions of 60 bytes, 110 partitions of 128 bytes, 50 partitions of 632
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
298 bytes and 7 partitions of 1600 bytes. An allocation request from a given pool
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
299 group (e.g., PRIM) can request any arbitrary size in bytes, but it gets rounded
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
300 up to the nearest partition size and allocated out of the respective pool. If
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
301 no free partitions are available, the requesting task is suspended until another
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
302 task frees on. Because these partitions are used primarily for intertask
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
303 communication, if none are free, it can only mean (assuming that the firmware
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
304 functions correcly) that all partitions have been allocated and sent to some
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
305 queue for some task to work on, hence eventually they will get freed.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
306
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
307 This scheme implemented in GPF is extremely robust in the opinion of this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
308 author, and the other purely "dynamic" scheme is used (in the case of GPF) only
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
309 for init-time allocations which are never freed, such as task stacks - hence
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
310 the GPF-based part of the firmware is not suspectible at all to the problem of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
311 memory fragmentation. But Riviera does suffer from this problem, and the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
312 concern is more than just theoretical: one major user of Riviera-based dynamic
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
313 memory allocation is the trace facility (described in its own section below),
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
314 and my observation of the trace output from Pirelli's proprietary fw (which
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
315 appears to use the same architecture with separate Riviera and GPF) suggests
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
316 that after the fw has been running for a while, Riviera memory gets fragmented
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
317 to a point where many traces are being dropped. Replacing Riviera's poor
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
318 dynamic memory allocation scheme with a GPF-like partition-based one is a to-do
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
319 item for our project.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
320
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
321 Message-based intertask communication
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
322 =====================================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
323
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
324 Even though all entities of the G23M protocol stack are linked together into
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
325 one monolithic fw image and there is nothing to stop them from calling each
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
326 other's functions and accessing each other's variables, they don't work that
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
327 way. Instead all communication between entities is done through messages, just
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
328 as if they ran in separate address spaces or even on separate processors.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
329 Buffers for this message exchange are allocated from a GPF partition pool: an
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
330 entity that needs to send a message to another entity allocates a buffer of the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
331 needed size, fills it with the message to be sent, and posts it on the recipient
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
332 entity's message queue, all through GPF services. The other entity simply
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
333 processes the stream of messages that arrives on its message queue, freeing each
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
334 message (returning the buffer to the partition pool in came from) as it is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
335 processed.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
336
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
337 Riviera-based tasks use a similar mechanism: unlike G23M protocol stack
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
338 entities, most Riviera-based functional modules provide APIs that are called as
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
339 functions from other tasks, but these API functions typically allocate a memory
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
340 buffer (through Riviera), fill it with the call parameters, and post it to the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
341 associated task's message queue (also in the Riviera land) to be worked on.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
342 Once the worker task gets the job done, it will either call a callback function
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
343 or post a response message back to the requestor - the latter option is only
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
344 possible if the requesting entity is also Riviera-based.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
345
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
346 A closer look at GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
347 ====================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
348
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
349 There are certain sublayers within GPF which need to be pointed out. The 3
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
350 major subdivisions within GPF are:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
351
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
352 * The meaty core of GPF: this part is the code under gsm-fw/gpf/frame in our
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
353 source tree. It appears that this part was originally intended to be both
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
354 project-independent (same for GSM, TETRA etc) and OS-independent (same for
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
355 Nucleus, pSOS, VxWorks etc). This is the part of GPF that matters for the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
356 G23M stack: all APIs called by PS entities are implemented here, and so are
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
357 all other PS-facing functions such as startup. (PS = protocol stack)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
358
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
359 * OS adaptation layer (OSL): this is the part of GPF that adapts it to a given
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
360 underlying OS, in our case Nucleus.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
361
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
362 * Test interface: see the code under gsm-fw/gpf/tst_drv and gsm-fw/gpf/tst_pei.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
363 This part handles the trace output from all entities that run under GPF and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
364 the mechanism for sending external debug commands to the GPF+PS subsystem.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
365
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
366 GPF was a difficult step in our GSM firmware reintegration process because no
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
367 complete source for it could be found anywhere: apparently GPF was so stable
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
368 and so independent of firmware particulars (Calypso or LoCosto, GSM only or
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
369 GSM+GPRS, modem or complete phone with UI etc) that it appears to have been
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
370 used and distributed as prebuilt binary libraries even inside TI. All TI fw
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
371 (semi-)sources we have use GPF in prebuilt library form and are not set up to
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
372 recompile any part of it from source. (They had to include all GPF header
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
373 files though, as most of them are included by G23M C modules, and it would be
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
374 too much hassle to figure out which ones are or aren't needed, hence all were
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
375 included.)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
376
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
377 Fortunately though, we were able to find the sources for most parts of GPF:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
378
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
379 * The LoCosto source in TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src.zip features the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
380 source for the "core" part of GPF under gpf/FRAME - these sources aren't
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
381 actually used by that fw's build system (it only uses the prebuilt binary
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
382 libs for GPF), but they are there.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
383
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
384 * Our TCS211 semi-src doesn't have any sources for the core part of GPF, but
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
385 instead it features the source for the test interface and some "misc" parts:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
386 under gpf/MISC and gpf/tst in that source tree - these sources are not present
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
387 in the LoCosto version from Peek.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
388
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
389 But one critical piece was still missing: the OS adaptation layer. It appears
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
390 that the GPF core (vsi_??? modules) and OSL (os_??? modules) were maintained
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
391 and built together, ending up together in frame_<blah>.lib files in the binary
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
392 form used to build firmwares, but the source for the "frame" part in the Peek
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
393 find contained only vsi_*.c and others, but not any of os_*.c.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
394
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
395 Thus we had to reconstruct GPF from the shattered bits and pieces we had. I
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
396 took the frame sources from Peek and the misc and tst sources from Sotovik, and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
397 saw that they compiled w/o problems in our gcc environment. Attempting to link
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
398 any firmware that uses GPF would have been futile at this point, as it would
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
399 have failed with undefined references to os_*() functions. Then I had to do
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
400 the hard work: disassemble the missing os_??? modules from the binary libs in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
401 the TCS211 version (hey, at least this one was known to work reliably) and write
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
402 new C code replicating the exact logic found in the disassembly of the known
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
403 working and fitting binary. This work is now mostly done (some non-essential
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
404 functions have been stubbed out to be revisited later), and the version of GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
405 used by FreeCalypso is a significant work of reconstruction, not merely lifted
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
406 from a readily available source and plopped in.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
407
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
408 A closer look at L1
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
409 ===================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
410
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
411 The L1 code is remarkable in how little intertie it has with the rest of the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
412 firmware it is linked into. It is almost entirely self-contained, expecting
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
413 only 4 functions to be provided by the underlying OS environment:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
414
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
415 os_alloc_sig -- allocate message buffer
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
416 os_free_sig -- free message buffer
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
417 os_send_sig -- send message to upper layers
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
418 os_receive_sig -- receive message from upper layers
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
419
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
420 It helps to remember that at the beginning of TI's involvement in the GSM
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
421 baseband chipset business, L1 was the only thing they "owned", while Condat,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
422 the maintainers of the higher level protocol stack, was a separate company.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
423 TI's "turnkey" solution must have consisted of their own L1 code plus G23M code
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
424 (including GPF etc) licensed from Condat, but I'm guessing that TI probably
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
425 wanted to retain the ability to sell their chips with their L1 without being
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
426 entangled by Condat: let the customer use their own GSM L23 stack, or perhaps
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
427 work out their own independent licensing arrangements with Condat. I'm
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
428 guessing that L1 was maintained as its own highly independent and at least
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
429 conceptually portable entity for these reasons.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
430
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
431 The way in which L1 is intertied into our FreeCalypso GSM fw is the same as how
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
432 it is done in TI's production firmwares, including both our TCS211 reference
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
433 and the TCS3.2 version from which we got our L1 source. There is a module
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
434 called OSX, which is an extremely thin adaptation layer that implements the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
435 APIs expected by L1 in terms of GPF. Furthermore, this OSX layer provides
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
436 header file isolation: the only "outside" (non-L1) header included by L1 is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
437 cust_os.h, and it defines the necessary interface to OSX *without* including
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
438 any other headers (no GPF headers in particular), using only the C language's
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
439 native types. Apart from this cust_os.h header, the entire OSX layer is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
440 implemented in one C module (osx.c, which we had to reconstruct from osx.obj as
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
441 the source was missing - but it's very simple) which does include some GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
442 headers and implements the OSX API in terms of GPF services. Thus in TI's
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
443 production firmwares and in our FC GSM fw L1 does sit on top of GPF, but very
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
444 indirectly.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
445
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
446 More specifically, the "production" version of OSX implements its API in terms
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
447 of *high-level* GPF functions, i.e., VSI. However, they also had an interesting
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
448 OP_L1_STANDALONE configuration which omitted not only all of G23M, but also the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
449 core of GPF and possibly the Riviera environment as well. We don't have a way
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
450 to recreate this configuration exactly as it existed inside TI because we don't
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
451 have the source bits specific to this configuration (our own standalone L1
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
452 configuration is implemented differently, see below), but we do have a little
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
453 bit of insight into how it worked.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
454
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
455 It appears that TI's OP_L1_STANDALONE build used a special "gutted" version of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
456 GPF in which the "meaty core" (VSI etc) was removed. The OS layer (os_???
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
457 modules implementing os_*() functions) that interfaces to Nucleus was kept, and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
458 so was OSX used by L1 - but this time the OSX API functions were implemented in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
459 terms of os_*() ones (low-level wrappers around Nucleus) instead of the higher-
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
460 level VSI APIs provided by the "meaty core" of GPF. It is purely a guess on my
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
461 part, but perhaps this hack was also done in the days before TI's acquisition
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
462 of Condat, and by omitting the "meaty core" of GPF, TI could claim that their
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
463 OP_L1_STANDALONE configuration did not contain any of Condat's "intellectual
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
464 property".
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
465
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
466 In FreeCalypso we do have a way to build a firmware image that includes L1 but
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
467 not G23M: it is our own L1 standalone configuration, enabled with a
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
468 feature l1stand line in build.conf. However, because IP considerations don't
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
469 apply to us (we operate under the doctrine of eminent domain), we are not
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
470 replicating TI's gutting of GPF: *our* L1 standalone configuration includes the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
471 full GPF (with OSX for L1 implemented in terms of VSI), but with a greatly
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
472 reduced set of tasks when G23M is omitted.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
473
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
474 Run-time structure of L1
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
475 ========================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
476
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
477 L1 consists of two major parts: L1S and L1A. L1S is the synchronous part where
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
478 the most time-critical functions are performed; it runs as a Nucleus HISR. The
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
479 hardware in the Calypso generates an interrupt on every TDMA frame (4.615 ms),
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
480 and the LISR handler for this interrupt triggers the L1S HISR. L1S communicates
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
481 with L1A through a shared memory data structure, and also sometimes allocates
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
482 message buffers and posts them to L1A's incoming message queue (both via OSX
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
483 API functions, i.e., via GPF in disguise).
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
484
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
485 L1A runs as a regular task under Nucleus, and includes a blocking call (to GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
486 via OSX) to wait for incoming messages on its queue. It is one big loop that
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
487 waits for incoming messages, then processes each received message and commands
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
488 L1S to do most of the work. The entry point to L1A in the L1 code proper is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
489 l1a_task(), although the responsibility for running it as a task falls on some
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
490 "glue" code outside of L1 proper. TI's production firmwares with G23M included
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
491 have an L1 protocol stack entity within G23M whose only job (aside from some
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
492 initialization) is to run l1a_task() in the Nucleus task created by GPF for
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
493 that protocol stack entity; we do the same in our firmware.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
494
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
495 Communication between L1 and G23M
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
496 =================================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
497
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
498 It is remarkable that L1 and G23M don't have any header files in common: L1
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
499 uses its own (almost fully self-contained), whereas the G23M+GPF realm is its
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
500 own world with its own header files. One has to ask then: how do they
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
501 communicate? OK, we know they communicate through primitives (messages in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
502 buffers allocated from GPF's PRIM partition memory pool) passes via message
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
503 queues, but what about the data structures in these messages? Where are those
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
504 defined if there are no header files in common between L1 and G23M?
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
505
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
506 The answer is that there are separate definitions of the L1<->G23M interface on
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
507 each side, and TI must have kept them in sync manually. Not exactly a
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
508 recommended programming or software maintenance practice for sure, but TI took
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
509 care of it, and the existing proprietary products based on TI's firmware are
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
510 rock solid, so it is not really our place to complain.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
511
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
512 TI's firmwares from the era we are working with (the TCS3.2/LoCosto source from
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
513 20090327 from which we took our L1 and G23M and the binary libs version of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
514 TCS211 from 20070608 which serves as our reference) also include a component
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
515 called ALR. It resides in the G23M code realm: G23M coding style, uses Condat
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
516 header files, runs as its own protocol stack entity under GPF. This component
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
517 appears to serve as a glue layer between the rest of the G23M stack (which is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
518 supposed to be truly hardware-independent) and TI's L1.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
519
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
520 Speaking of ALR, it is worth mentioning that there is a little naming
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
521 inconsistency here. ALR is known to the connect-by-name logic in GPF as "PL"
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
522 (physical layer, apparently), while the ACI entity (Application Control
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
523 Interface, the top level entity) is known to the same logic as "MMI". No big
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
524 deal really, but hopefully knowing this quirk will save someone some confusion.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
525
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
526 Debug trace facility
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
527 ====================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
528
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
529 See the RVTMUX document in the same directory as this one for general background
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
530 information about the debug and development interface provided by TI-based
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
531 firmwares. Our FreeCalypso GSM firmware implements an RVTMUX interface as well,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
532 and the most immediate use to which it is put is debug trace output. In this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
533 section I'm going to describe how this debug trace output is generated inside
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
534 the fw.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
535
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
536 The firmware component that "owns" the physical UART channel assigned to RVTMUX
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
537 is RVT, implemented in gsm-fw/riviera/rvt. It is a Riviera-based component,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
538 and it has a Nucleus task that is created and started through Riviera. All
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
539 calls to the actual driver for the UART are made from RVT. In the case of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
540 output from the Calypso GSM device to an external host, all such output is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
541 performed in the context of RVT's Nucleus task; this task drains RVT's message
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
542 queue and emits the content of allocated buffers posted to it, freeing them
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
543 afterward. (The dynamic memory allocation system in this case is Riviera's,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
544 which is susceptible to fragmentation - see discussion earlier in this article.)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
545 Therefore, every trace or other output packet emitted from a GSM device running
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
546 our fw (or any of the proprietary firmwares based on the same architecture)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
547 appears as a result of a message in a dynamically allocated buffer having been
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
548 posted to RVT's queue.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
549
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
550 RVT exports several API functions that are intended to be called from other
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
551 tasks, it is by way of these functions that most output is submitted to RVT.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
552 One can call rvt_send_trace_cpy() with a fully prepared output message, and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
553 that function will allocate a buffer from Riviera's dynamic memory allocator
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
554 properly accounted to RVT, fill it and post it to the RVT task's queue.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
555 Alternatively, one can can rvt_mem_alloc() to allocate the buffer, fill it in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
556 and then pass it to rvt_send_trace_no_cpy().
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
557
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
558 At higher levels, there are a total of 3 kinds of debug traces that can be
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
559 emitted:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
560
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
561 * Riviera traces: these are generated by various components implemented in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
562 Riviera land, although in reality any component can generate a trace of this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
563 form by calling rvf_send_trace() - this function can be called from any task.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
564
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
565 * L1 traces: L1 has its own trace facility implemented in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
566 gsm-fw/L1/cfile/l1_trace.c; it generates its traces as ASCII messages and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
567 sends them out via rvt_send_trace_cpy().
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
568
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
569 * GPF traces: code that runs in GPF/G23M land and uses those header files and
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
570 coding conventions etc can emit traces through GPF. GPF's trace functions
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
571 (implemented in gsm-fw/gpf/frame/vsi_trc.c) allocate a memory partition from
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
572 GPF's TEST pool, format the trace into it, and send the trace primitive to
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
573 GPF's special test interface task. That task receives trace and other GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
574 test interface primitives on its queue, performs some manipulations on them,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
575 and ultimately generates RVT trace output, i.e., a new dynamic memory buffer
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
576 is allocated in the Riviera land, the trace is copied there, and the Riviera
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
577 buffer goes to the RVT task for the actual output.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
578
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
579 Trace masking
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
580 =============
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
581
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
582 The RV trace facility invoked via rvf_send_trace() has a crude masking ability,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
583 but by default all traces are enabled. In TI's standard firmwares most of the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
584 trace output comes from L1: L1's trace output is very voluminous, and appears
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
585 to be fully enabled by default. I have yet to look more closely if there is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
586 any trace masking functionality in L1 and what the default trace verbosity
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
587 level should be.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
588
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
589 On the other hand, GPF and therefore G23M traces are mostly disabled by default.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
590 One can turn the trace verbosity level from any GPF-based entity up or down by
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
591 sending a "system primitive" command to the running fw, and another such command
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
592 can be used to save these masks in FFS, so that they will be restored on the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
593 next boot cycle and be effective at the earliest possible time. Enabling *all*
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
594 GPF trace output for all entities is generally not useful though, as it is so
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
595 verbose that a developer trying to make sense of it will likely drown in it.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
596
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
597 GPF compressed trace hack
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
598 =========================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
599
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
600 TI's Windows-based GSM firmware build systems include a hack called str2ind.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
601 Seeking to reduce the fw image size by eliminating trace ASCII strings from it,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
602 and seeking to reduce the load on the RVTMUX serial interface by eliminating
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
603 the transmission time of these strings, they passed their sources through an
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
604 ad hoc preprocessor that replaces these ASCII strings with numeric indices.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
605 The compilation process with this str2ind hack becomes very messy: each source
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
606 file is first passed through the C preprocessor, then the intermediate form is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
607 passed through str2ind, and finally the de-string-ified form is compiled, with
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
608 the compiler being told not to run the C preprocessor again.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
609
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
610 TI's str2ind tool maintains a table of correspondence between the original trace
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
611 ASCII strings and the indices they've been turned into, and a copy of this table
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
612 becomes essential for making sense of GPF trace output: the firmware now emits
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
613 only numeric indices which are useless without this str2ind.tab mapping table.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
614
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
615 Our FreeCalypso firmware does not currently implement this str2ind aka
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
616 compressed trace hack, i.e., all GPF trace output from our fw is in full ASCII
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
617 string form. I have not bothered to implement compressed traces because:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
618
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
619 * We have not yet encountered a case of the full ASCII strings causing a problem
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
620 either with fw images not fitting into the available memory or excessive load
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
621 on the RVTMUX interface;
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
622
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
623 * Implementing the hack in question would require extra work: the str2ind tool
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
624 would have to be reimplemented anew, as of the original we have no source,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
625 only a Windows binary, and requiring our free fw build process to run a
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
626 Windows binary under Wine is a no-no;
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
627
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
628 * I don't feel like doing all that extra work for what appears to be no real
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
629 gain;
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
630
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
631 * Having to run gcc with separate cpp and actual compilation steps with str2ind
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
632 sandwiched in between would be ugly and gross;
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
633
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
634 * Having to keep track of which str2ind.tab goes with which fw image and supply
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
635 the right table to our rvinterf tools would likely be a pita.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
636
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
637 So we shall stick with full ASCII string traces until and unless we run into an
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
638 actual (as opposed to hypothetical) problem with either fw image size or serial
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
639 interface load.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
640
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
641 RVTMUX command input
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
642 ====================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
643
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
644 RVTMUX is not just debug trace output: it is also possible for an external host
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
645 to send commands to the running fw via RVTMUX.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
646
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
647 Inside the fw RVTMUX input is handled by the RVT entity by way of a Nucleus
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
648 HISR. This HISR gets triggered when Rx bytes arrive at the designated UART,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
649 and it calls the UART driver to collect the input. RVT code running in this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
650 HISR parses the message structure and figures out which fw component the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
651 incoming message is addressed to. Any fw component can register to receive
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
652 RVTMUX packets, and provides a callback function with this registration; this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
653 callback function is called in the context of the HISR.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
654
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
655 In our current FC GSM fw there are two components that register to receive
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
656 external host commands via RVTMUX: ETM and GPF. ETM is described in my earlier
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
657 RVTMUX write-up. ETM is implemented as a Riviera SWE and has its own Nucleus
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
658 task; the callback function that gets called from the RVT HISR posts received
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
659 messages onto ETM's own queue drained by its task. The ETM task gets scheduled,
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
660 picks up the command posted to its queue, executes it, and sends a response
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
661 message back to the external host through RVT.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
662
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
663 Because all ETM commands funnel through ETM's queue and task, and that task
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
664 won't start looking at a new command until it finished handling the previous
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
665 one, all ETM commands and responses are in strict lock-step: it is not possible
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
666 to send two commands and have their responses come in out of order, and it makes
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
667 no sense to send another ETM command prior to receiving the response to the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
668 previous one. (But there can still be debug traces or other traffic intermixed
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
669 on RVTMUX in between an ETM command and the corresponding response!)
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
670
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
671 The other component that can receive external commands is GPF. GPF's test
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
672 interface can receive so-called "system primitives", which are ASCII string
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
673 commands parsed and acted upon by GPF, and also binary protocol stack
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
674 primitives. Remember how all entities in the G23M stack communicate by sending
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
675 messages to each other? Well, GPF's test interface allows such messages to be
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
676 injected externally as well, directed to any entity in the running fw. System
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
677 primitive commands can also be used to cause entities to send their outgoing
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
678 primitives to the test interface, either instead of or in addition to the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
679 originally intended recipient.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
680
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
681 Firmware subsetting
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
682 ===================
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
683
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
684 We have built our firmware up incrementally, piece by piece, starting from a
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
685 very small skeleton. As we added pieces working toward full GSM MS
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
686 functionality, the ability to build less functional fw images corresponding to
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
687 our earlier stages of development has been retained. Each piece we added is
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
688 "optional" from the viewpoint of our build system, even if it is absolutely
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
689 required for normal usage, and is enabled by the appropriate feature line in
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
690 build.conf.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
691
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
692 Our minimal baseline with absolutely no "features" enabled consists of:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
693
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
694 * Nucleus
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
695 * Riviera
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
696 * TI's basic drivers for GPIO, ABB etc
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
697 * RVTMUX on the UART port chosen by the user (RVTMUX_UART_port Bourne shell
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
698 variable in build.conf) and the UART driver for it
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
699 * FFS code operating on a fake FFS image in RAM
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
700
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
701 If one runs this minimal "firmware" on a Calypso device, one will see some
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
702 startup messages in RV trace format followed by a System Time trace every 20 s.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
703 This "firmware" can't do anything more, there is not even a way to command it
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
704 to power off or reboot.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
705
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
706 Working toward full GSM MS functionality, pieces can be added to this skeleton
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
707 in this order:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
708
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
709 * GPF
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
710 * L1
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
711 * G23M
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
712
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
713 feature gsm enables all of the above for normal usage; feature l1stand can be
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
714 used alternatively to build an L1 standalone image without G23M - we expect
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
715 that we may end up using a ramImage form of the latter for RF calibration on
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
716 our own Calypso hardware.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
717
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
718 ETM and various FFS configurations are orthogonal features to the choice of
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
719 core functionality level.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
720
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
721 Further reading
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
722 ===============
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
723
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
724 Believe it or not, some of the documentation that was written by the original
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
725 vendors of the software in question and which we've been able to locate turns
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
726 out to be fairly relevant and helpful, such that I recommend reading it.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
727
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
728 Documentation for Nucleus PLUS RTOS:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
729
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
730 ftp://ftp.ifctf.org/pub/embedded/Nucleus/nucleus_manuals.tar.bz2
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
731
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
732 Quite informative, and fits our version of Nucleus just fine.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
733
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
734 Riviera environment:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
735
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
736 ftp://ftp.ifctf.org/pub/GSM/Calypso/riviera_preso.pdf
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
737
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
738 It's in slide presentation form, not a detailed technical document, but
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
739 it covers a lot of points, and all that Riviera stuff described in the
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
740 preso *is* present in our fw for real, hence it should be considered
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
741 relevant.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
742
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
743 GPF documentation:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
744
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
745 http://scottn.us/downloads/peek/SW%20doc/frame_users_guide.pdf
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
746 http://scottn.us/downloads/peek/SW%20doc/vsipei_api.pdf
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
747
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
748 Very good reading, helped me understand GPF when I first reached this
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
749 part of firmware reintegration.
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
750
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
751 TCS3.x/LoCosto fw architecture:
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
752
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
753 http://scottn.us/downloads/peek/SW%20doc/TCS2_1_to_3_2_Migration_v0_8.pdf
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
754 ftp://ftp.ifctf.org/pub/GSM/LoCosto/LoCosto_Software_Architecture_Specification_Document.pdf
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
755
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
756 These TI docs focus mostly on how they changed the fw architecture from
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
757 their TCS2.x program (Calypso) to their newer TCS3.x (LoCosto), but one
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
758 can still get a little insight into the "old" TCS211 architecture they
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
759 were moving away from, which is the architecture I've adopted for
d92b110e06e0 doc/Firmware_Architecture written
Space Falcon <falcon@ivan.Harhan.ORG>
parents:
diff changeset
760 FreeCalypso.