freecalypso-sw: doc/Firmware_Architecture annotate

annotate doc/Firmware_Architecture @ 1009:009d5bf2ff4c

rvinterf/lowlevel: formatting of FC-specific packet types split off into format_fc.c

author	Mychaela Falconia <falcon@ivan.Harhan.ORG>
date	Sun, 20 Mar 2016 20:23:54 +0000
parents	d92b110e06e0
children

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.

FreeCalypso > hg > freecalypso-sw

annotate doc/Firmware_Architecture @ 1009:009d5bf2ff4c