View source for B2G/Architecture

This document describes at a high level how [[Gaia]] and [[B2G]] work in the port of [[Gecko]] to [[Gonk]].  If you don't know what these things are yet, don't worry, they'll be introduced below.

Gaia/B2G/Gecko are under heavy development, so some items below discuss how the code '''will''' work, instead of how it '''currently''' works.  This will be noted.

== Terminology ==

'''''[[Gaia]]''''' : The user interface of b2g.  Everything drawn to screen after b2g starts up is some part of Gaia.  Gaia implements a lock screen, home screen, telephone dialer, text-messaging application, camera app, ... and many more.  Gaia is written entirely in HTML, CSS, and JavaScript.  Its only interface to the underlying operating system is through Open Web APIs, which are implemented by Gecko.  Gaia works ''well'' when run on top of b2g; however, since it only uses standard web APIs, it works on other OSes and in other web browsers (albeit with degraded functionality).  Third-party applications can be installed alongside Gaia.

'''''[[Gecko]]''''' : The "application runtime" of b2g.  At a high level, Gecko implements the open standards for HTML, CSS, and JS and makes those interfaces run well on all the OSes that Gecko supports.  This means that Gecko consists of, among other things, a networking stack, graphics stack, layout engine, virtual machine (for JS), and porting layers.

'''''[[Gonk]]''''' : The lower-level "operating system" of b2g.  Gonk consists of a linux kernel and userspace hardware abstraction layer (HAL).  The kernel and several userspace libraries are common open-source projects: linux, libusb, bluez, etc.  Some other parts of the HAL are shared with the android project: GPS, camera, among others.  You could say that Gonk is an extremely simple linux distribution.  Gonk is a ''porting target'' of Gecko; there is a port of Gecko to Gonk, just like there is a port of Gecko to OS X, and a port of Gecko to Android.  Since the b2g project has full control over Gonk, we can expose interfaces to Gecko that aren't possible to expose on other OSes.  For example, Gecko has direct access to the full telephony stack and display framebuffer on Gonk, but doesn't have this access on any other OS.

== Booting ==

After turning on a b2g phone, execution starts in the primary bootloader.  From there, the process of loading the main OS kernel happens in the usual way: a succession of higher-level bootloaders bootstrap the next loader in the chain.  At the end of the process, execution is handed off to the linux kernel.

There's not a lot to say about the boot process, but there are a few things worth knowing
* The bootloaders usually show the first "splash screen" seen during device boot, which usually displays a vendor logo.
* The bootloaders implement flashing an image onto the device.  Different devices use different protocols.  Most phones use the fastboot protocol, but the Galaxy S II uses the "odin" protocol.
* By the end of the bootstrapping process, the modem image is usually loaded and running on the modem processor.  How this happens is highly device-specific and possibly proprietary.

== Kernel (Linux) ==

The linux kernel(s) in Gonk is reasonably close to upstream linux.  There are a few modifications made by AOSP that are not in upstream yet.  Vendors also modify the linux kernel and upstream those modifications on their own schedule.  But in general, the linux kernel is close to stock.

The startup process for linux is well documented elsewhere on the internet, so it's not covered here.  At the end of kernel startup, a userspace "init" process is launched, like in most other UNIX-like OSes.  At this point in execution, only a ramdisk is mounted.  The ramdisk is built during the b2g build process, and consists of critical utilities (like <code>init</code>), other startup scripts, and loadable kernel modules.

After launching the <code>init</code> process, the linux kernel services system calls from userspace and interrupts etc. from hardware devices.  Many devices are exposed to userspace through sysfs (documented elsewhere on the internet).  For example, here's some code that reads the battery state in Gecko ([https://github.com/cgjones/mozilla-central/blob/master/hal/gonk/GonkHal.cpp#L267 link to original code])
<pre>
  FILE *capacityFile = fopen("/sys/class/power_supply/battery/capacity", "r");
  double capacity = dom::battery::kDefaultLevel * 100;
  if (capacityFile) {
    fscanf(capacityFile, "%lf", &capacity);
    fclose(capacityFile);
  }
</pre>

== init ==

The <code>init</code> process in Gonk mounts necessary file systems, spawns system services, and acts a process manager after that.  This is very similar to <code>init</code> on other UNIX-like OSes.  <code>init</code> "interprets" scripts (init*.rc), that consist of commands.  Here's the main init script for the Galaxy S II

[https://github.com/michaelwu/clockworkmod_galaxys2_initramfs/blob/gingerbread/init.rc Main init script for the Galaxy S II]

In particular, <code>init</code> is responsible for launching the <code>b2g</code> process, described below.  Here's the snippet of code that launches <code>b2g</code>
<pre>
service b2g /system/b2g/b2g
    onrestart restart media
</pre>

== Userspace process architecture ==

At this point, it's best to step back a bit and look at how the various components of b2g fit together, at a very high level.
[[File:B2G-processes.png|thumb|650px|B2G processes]]

This diagram shows the main userspace processes in b2g.  ('''NOTE''': this diagram is subject to change, and not guaranteed to be 100% accurate.)  The dotted lines show processes that are spawned by <code>init</code>.  The solid lines show other communication channels.

The <code>b2g</code> process is the main system process.  It runs with high privileges: it has access to most hardware devices.  <code>b2g</code> communicates with the modem, draws to the display framebuffer, and talks to GPS, cameras, and other devices.  Internally, <code>b2g</code> runs Gecko code (libxul.so).  The details of how it communicates with hardware are discussed below.

The <code>b2g</code> process may spawn a number of low-rights "content processes".  These are where web applications and other web content are loaded.  These process communicate with the main Gecko server process through [https://developer.mozilla.org/en/IPDL IPDL], a message-passing system.

The <code>rild</code> process is the interface to the modem processor.  "RIL" is the "radio interface layer", "rild" is the "RIL daemon".  It's a proprietary "blob" of code implemented by hardware vendors.  <code>rild</code> allows a client to connect to a [https://github.com/michaelwu/clockworkmod_galaxys2_initramfs/blob/gingerbread/init.rc#L656 UNIX-domain socket it binds to].
<pre>
service ril-daemon /system/bin/rild
    socket rild stream 660 root radio
</pre>

In b2g, the rild client is the <code>rilproxy</code> process.  It just acts as a dumb forwarding proxy between <code>rild</code> and <code>b2g</code>.  The reason we need this proxy is an implementation detail, not important.  The code lives [https://github.com/mozilla-b2g/rilproxy here].

The <code>mediaserver</code> process controls audio and video playback.  Gecko talks to it through an android RPC mechanism.  The code for <code>mediaserver</code> lives [https://github.com/cgjones/android-frameworks-base/tree/gingerbread-b2g/media/libmediaplayerservice here].  Some of the media that Gecko can play (OGG Vorbis audio, OGG Theora video, and WebM video) are decoded by Gecko and sent directly to the mediaserver.  Other media files are decoded by [https://github.com/cgjones/android-frameworks-base/tree/gingerbread-b2g/media/libstagefright libstagefright], which is capable of accessing proprietary codecs and hardware decoders.  ('''NOTE''': B2G will not use the mediaserver process, in its current incarnation, in the long run.)

The <code>netd</code> process is used to configure network interfaces.  <code>wpa_supplicant</code> is the standard UNIX-ish daemon that connects to WiFi access points.  '''TODO: document other processes'''

== Gecko: Processing input events ==

Most action inside of Gecko is triggered by input events (button presses, touch-screen touches, and so forth).  Input events enter Gecko through the Gonk [https://github.com/cgjones/mozilla-central/blob/master/widget/gonk/nsAppShell.cpp#L532 "app shell"] (on b2g).  For example
<pre>
void
GeckoInputDispatcher::notifyKey(nsecs_t eventTime,
                                int32_t deviceId,
                                int32_t source,
                                uint32_t policyFlags,
                                int32_t action,
                                int32_t flags,
                                int32_t keyCode,
                                int32_t scanCode,
                                int32_t metaState,
                                nsecs_t downTime)
{
    UserInputData data;
    data.timeMs = nanosecsToMillisecs(eventTime);
    data.type = UserInputData::KEY_DATA;
    data.action = action;
    data.flags = flags;
    data.metaState = metaState;
    data.key.keyCode = keyCode;
    data.key.scanCode = scanCode;
    {
        MutexAutoLock lock(mQueueLock);
        mEventQueue.push(data);
    }
    gAppShell->NotifyNativeEvent();
}
</pre>

These input events originate from the standard linux input_event system, dispatched by input-device drivers.  We use [https://github.com/cgjones/android-frameworks-base/blob/gingerbread-b2g/libs/ui/InputReader.cpp a light abstraction over that] which provides some nice features like filtering of events.  [https://github.com/cgjones/android-frameworks-base/blob/gingerbread-b2g/libs/ui/EventHub.cpp#L450 Here's where input events originate]
<pre>
            if (pfd.revents & POLLIN) {
                int32_t readSize = read(pfd.fd, mInputBufferData,
                        sizeof(struct input_event) * INPUT_BUFFER_SIZE);
                if (readSize < 0) {
                    if (errno != EAGAIN && errno != EINTR) {
                        LOGW("could not get event (errno=%d)", errno);
                    }
                } else if ((readSize % sizeof(struct input_event)) != 0) {
                    LOGE("could not get event (wrong size: %d)", readSize);
                } else {
                    mInputBufferCount = readSize / sizeof(struct input_event);
                    mInputBufferIndex = 0;
                }
            }
        }
</pre>

After being read by Gecko, inputs are dispatched into the DOM from [https://github.com/cgjones/mozilla-central/blob/master/widget/gonk/nsAppShell.cpp#L213 here]
<pre>
static nsEventStatus
sendKeyEventWithMsg(PRUint32 keyCode,
                    PRUint32 msg,
                    uint64_t timeMs,
                    PRUint32 flags)
{
    nsKeyEvent event(true, msg, NULL);
    event.keyCode = keyCode;
    event.time = timeMs;
    event.flags |= flags;
    return nsWindow::DispatchInputEvent(event);
}
</pre>

From here on, the events are either consumed by Gecko internally, or dispatched to web applications as DOM events.

== Gecko: Graphics ==

At the very lowest level, Gecko uses OpenGL ES 2.0 to draw to a glcontext that wraps the hardware framebuffers.  Gecko sets up its graphics context [https://github.com/cgjones/mozilla-central/blob/master/widget/gonk/nsWindow.cpp#L79 here]
<pre>
        gNativeWindow = new android::FramebufferNativeWindow();
        sGLContext = GLContextProvider::CreateForWindow(this);
</pre>
The FramebufferNativeWindow is implemented [https://github.com/cgjones/android-frameworks-base/blob/gingerbread-b2g/libs/ui/FramebufferNativeWindow.cpp here].  It uses the "gralloc" hardware interface to the graphics driver to map buffers from the framebuffer device.

Gecko uses its [[Layers]] system to composite drawn content to the screen.  A full description of layers is beyond the scope of this document, but what approximately happens is
* Gecko draws separate regions of pages into memory buffers.  Sometimes, these buffers are system memory.  Other times, they're textures mapped into Gecko's address space, meaning Gecko draws directly to VRAM.  Drawing happens [https://github.com/cgjones/mozilla-central/blob/master/gfx/layers/basic/BasicLayers.cpp#L750 here], in the common case.
* Gecko composites these textures to screen using GL commands.  Composition of the pixels painted above would happen [https://github.com/cgjones/mozilla-central/blob/master/gfx/layers/opengl/ThebesLayerOGL.cpp#L288 here].

The details of how Gecko actually draws web content are beyond the scope of this document.

== Gecko: Hardware Abstraction Layer (hal) ==

(The Gecko hardware abstraction layer is not to be confused with the Gonk hardware abstraction layers.  Where possible, the Gecko hardware abstraction layer will be referred to as "hal", and the Gonk hardware abstraction layers will be referred to as "HAL".)

"hal" is one on the porting layers of Gecko.  It's used for low-level access to system interfaces across multiple platforms.  hal offers a cross-platform C++ API to the higher levels of Gecko, with implementations of those APIs per platform inside of hal itself.  hal is not exposed directly to anything other than C++ code in Gecko.

It's easiest to understand hal through an example.  We'll use the vibration API.  The hal API for vibration is [https://github.com/cgjones/mozilla-central/blob/master/hal/Hal.h#L55 here]
<pre>
void Vibrate(const nsTArray<uint32>& pattern);
</pre>
(Note: the real API is slightly more complicated, for reasons that aren't relevant to this discussion.  The complexities are omitted in this presentation.)

This API tells the vibration motor to turn on/off according to the pattern specified in <code>pattern</code>.  The API is implemented for Gonk [https://github.com/cgjones/mozilla-central/blob/master/hal/gonk/GonkHal.cpp#L171 here]
<pre>
void
Vibrate(const nsTArray<uint32> &pattern)
{
  EnsureVibratorThreadInitialized();
  sVibratorRunnable->Vibrate(pattern);
}
</pre>

which sends the request off to another thread [https://github.com/cgjones/mozilla-central/blob/master/hal/gonk/GonkHal.cpp#L107 here], where the real work is done
<pre>
  while (!mShuttingDown) {
    if (mIndex < mPattern.Length()) {
      uint32 duration = mPattern[mIndex];
      if (mIndex % 2 == 0) {
        vibrator_on(duration);
      }
      mIndex++;
      mMonitor.Wait(PR_MillisecondsToInterval(duration));
    }
    else {
      mMonitor.Wait();
    }
  }
</pre>

<code>vibrate_on()</code> is the Gonk HAL API for turning on the vibrator motor.  Internally, <code>vibrate_on()</code> writes a value to a kernel object exposed through sysfs, which in effect sends the kernel driver a message.

The hal APIs are supported across all platforms.  When Gecko is built for a platform that doesn't expose an interface to vibrator motors, then the "fallback" implementation of the hal API is used.  For vibration, it's [https://github.com/cgjones/mozilla-central/blob/master/hal/fallback/FallbackHal.cpp#L22 here]
<pre>
void
Vibrate(const nsTArray<uint32>& pattern)
{}
</pre>

Most web content runs in low-rights content processes (see above).  We can't assume those content processes have the necessary privileges to turn on the vibration motor, and in addition we want to resolve race conditions in a central location.  In hal, this is done through the "sandbox" implementation of hal.  The sandbox implementation merely proxies requests from content processes to the "Gecko server" process.  The proxy requests are sent through IPDL.  For vibration, the request originates [https://github.com/cgjones/mozilla-central/blob/master/hal/sandbox/SandboxHal.cpp#L42 here]
<pre>
void
Vibrate(const nsTArray<uint32>& pattern)
{
  Hal()->SendVibrate(pattern);
}
</pre>
which sends a message that's defined by [https://github.com/cgjones/mozilla-central/blob/master/hal/sandbox/PHal.ipdl#L94 this interface]
<pre>
    Vibrate(uint32[] pattern);
</pre>
to a receiver of the message defined [https://github.com/cgjones/mozilla-central/blob/master/hal/sandbox/SandboxHal.cpp#L172 here]
<pre>
  NS_OVERRIDE virtual bool
  RecvVibrate(const InfallibleTArray<unsigned int>& pattern)
  {
    // Forward to hal::, not hal_impl::, because we might be a
    // subprocess of another sandboxed process. The hal:: entry point
    // will do the right thing.
    hal::Vibrate(pattern);
    return true;
</pre>
(omitting some details that aren't relevant to this discussion).  So a vibration request sent by a content process on the Gecko port to Gonk eventually ends up in the GonkHal implementation of <code>Vibrate()</code>, discussed above.

== Gecko: DOM APIs ==

"DOM interfaces", approximately, are how web content communicates with Gecko.  There's a lot more to the DOM than that, but the longer discussion is beyond the scope of this document.  DOM interfaces are defined in [https://developer.mozilla.org/en/XPIDL IDL], which comprises both a foreign function interface (ffi) and object model (OM) between JavaScript and C++.  Again, there are more details that could be discussed here which are beyond the scope of this document.  Let's learn a bit of IDL by example.

The very simple vibration API is exposed to web content through an IDL interface.  That interface is [https://github.com/cgjones/mozilla-central/blob/master/dom/interfaces/base/nsIDOMNavigator.idl#L66 here]
<pre>
  [implicit_jscontext]
  void mozVibrate(in jsval aPattern);
</pre>
The <code>jsval</code> argument indicates that <code>mozVibrate</code> (our vendor-prefixed implementation of the vibration specification) accepts any JS value.  Details of working with jsvals are beyond the scope of this document.  The IDL compiler generates a C++ interface that's implemented [https://github.com/cgjones/mozilla-central/blob/master/dom/base/Navigator.cpp#L657 here]
<pre>
NS_IMETHODIMP
Navigator::MozVibrate(const jsval& aPattern, JSContext* cx)
{
  // ...
  hal::Vibrate(pattern);
  return NS_OK;
}
</pre>
There's quite a lot of code that's hidden here by the ellipsis ("..."), but let's ignore for it now.

The call to <code>hal::Vibrate()</code> transfers control from the DOM to hal.  From there, we enter the hal implementation discussed above.  A key point to note here is that the DOM implementation doesn't care what platform it's running on (Gonk or Windows or OS X or ...), nor does it care whether the code is running in a "content process" or the Gecko "server process".  This is all left to lower levels of the system.

The vibration API happens to be quite simple, so it's a good example.  The SMS API, which is much more complicated and has its own "remoting" layer from content processes to the server, is [https://github.com/cgjones/mozilla-central/tree/master/dom/sms here].

== RIL: Telephony ==

The RIL was discussed briefly above.  In this section, we'll how the various pieces interact in a little more detail.  The main actors are
* <code>rild</code> : the proprietary bit of code that talks to the proprietary modem firmware
* <code>rilproxy</code> : the daemon that proxies messages between <code>rild</code> and Gecko (the <code>b2g</code> process)
* Gecko (the <code>b2g</code> process) : implements the higher-level telephony stack

Let's start with an example that demonstrates the lower-level parts of the system.  When the modem receives an incoming call, it notifies the <code>rild</code> using a proprietary mechanism.  The rild then prepares a message for its client according to the "open" protocol [https://github.com/mozilla-b2g/android-hardware-ril/blob/master/include/telephony/ril.h here].  In this case, an incoming call generates the [https://github.com/mozilla-b2g/android-hardware-ril/blob/master/include/telephony/ril.h#L3290 RIL_UNSOL_RESPONSE_CALL_STATE_CHANGED] message.  This message is sent by rild to its client and received by rilproxy [https://github.com/mozilla-b2g/rilproxy/blob/master/src/rilproxy.c#L214 here]
<pre>
          ret = read(rilproxy_rw, data, 1024);
          if(ret > 0) {
            writeToSocket(rild_rw, data, ret);
          }
</pre>
where it's forwarded along to Gecko, on the socket connecting rilproxy and Gecko.  Gecko receives these forwarded bytes [https://github.com/cgjones/mozilla-central/blob/master/ipc/ril/Ril.cpp#L220 here]
<pre>
            int ret = read(fd, mIncoming->mData, 1024);
            // [handle errors]
            mIncoming->mSize = ret;
            sConsumer->MessageReceived(mIncoming.forget());
</pre>
The consumer is [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/SystemWorkerManager.cpp#L169 here], and repackages the message and dispatches it to a "worker thread" that implements the RIL state machine
<pre>
  virtual void MessageReceived(RilRawData *aMessage) {
    nsRefPtr<DispatchRILEvent> dre(new DispatchRILEvent(aMessage));
    mDispatcher->PostTask(dre);
  }
</pre>
The task posted to that thread is sent into the JS code on the RIL worker [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/SystemWorkerManager.cpp#L178 here]
<pre>
  return JS_CallFunctionName(aCx, obj, "onRILMessage", NS_ARRAY_LENGTH(argv),
                             argv, argv);
</pre>
which calls a function <code>onRILMessage()</code> in JS.  That function is defined [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/ril_worker.js#L2562 here].  The message bytes are processed a bit, until finally we dispatch the message [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/ril_worker.js#L888 here]
<pre>
  handleParcel: function handleParcel(request_type, length) {
    let method = this[request_type];
    if (typeof method == "function") {
      if (DEBUG) debug("Handling parcel as " + method.name);
      method.call(this, length);
    }
  }
};
</pre>
which calls into a function defined [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/ril_worker.js#L1184 here]
<pre>
RIL[UNSOLICITED_RESPONSE_CALL_STATE_CHANGED] = function UNSOLICITED_RESPONSE_CALL_STATE_CHANGED() {
  Phone.onCallStateChanged();
};
</pre>
and then we bounce around for a bit and get [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/ril_worker.js#L647 to]
<pre>
  getCurrentCalls: function getCurrentCalls() {
    Buf.simpleRequest(REQUEST_GET_CURRENT_CALLS);
  },
</pre>
This sends a request ''back'' to the rild to request the state of all currently-active calls.  The request follows a similar path back to rild (out from ril_worker.js, to SystemWorkerManager.cpp, off to Ril.cpp, then to rilproxy.c and finally written to the rild socket).  The response from rild is processed similarly to above, and then finally we detect that a new call has been received and notify the DOM [https://github.com/cgjones/mozilla-central/blob/master/dom/system/b2g/ril_worker.js#L1322 here]
<pre>
  _handleChangedCallState: function _handleChangedCallState(changedCall) {
    let message = {type: "callStateChange",
                   call: {callIndex: changedCall.callIndex,
                          state: changedCall.state,
                          number: changedCall.number,
                          name: changedCall.name}};
    this.sendDOMMessage(message);
  },
</pre>
This sets off a chain of events that results in the currently-active dialer application being notified of an incoming call.  In gaia, this notification is received [https://github.com/andreasgal/gaia/blob/master/apps/dialer/js/dialer.js#L297 here]
<pre>
  handleEvent: function fm_handleEvent(evt) {
    console.log('Call changed state: ' + evt.call.state);
    switch (evt.call.state) {
      case 'incoming':
        console.log('incoming call from ' + evt.call.number);
        this.incoming(evt.call);
        break;
      case 'connected':
        this.connected();
        break;
      case 'disconnected':
        this.disconnected();
        break;
      default:
        break;
    }
  },
</pre>
at the 'incoming' case in the switch statement.

== RIL: 3G Data ==

There is a RIL message that places a "data call" to the cellular tower, which enables data-transfer mode in the modem.  This data call ends up creating/activating a PPP interface device in the linux kernel that can be configured through usual interfaces. '''TODO'''

== WiFi ==

WiFi is implemented by a worker that uses jsctypes to open an interface to the wpa_supplicant.  The worker scans for available networks, chooses one to connect to, and then lets the higher-level network compontents configure the network.

== Network Manager ==

The network manager configures network interfaces opened by the 3g-data and wifi components.  '''TODO'''