FreeCalypso > hg > freecalypso-sw

annotate doc/Firmware_Architecture @ 888:0590cfd5803f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gsm-fw/configs/pirelli-gsm added
author Space Falcon <falcon@ivan.Harhan.ORG>
date Sun, 28 Jun 2015 15:40:47 +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.