Porting Boot to Gecko

  • Revision slug: Mozilla/Boot_to_Gecko/Porting
  • Revision title: Porting Boot to Gecko
  • Revision id: 299061
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment

Revision Content

Boot to Gecko (FirefoxOS) uses a kernel derived from Android, with a Gecko-based user interface on top of it. This article provides a basic guide to how to go about porting the operating system to new devices.

This guide assumes you're porting to a new device that already runs Android; if you're porting to another device, the job is going to be more involved.

Set up your build system

The first step is to configure your build system; you can follow the guide in B2G build prerequisites.

Clone the B2G repository

The first step is to clone the B2G repository.

git clone https://github.com/mozilla-b2g/B2G.git

Create a local backup of the original Android system

Next, you should back up your Android device before you start nuking it with your test builds of B2G. In addition, some of these bits will be needed by the build and install process.

mkdir my_device_backup
cd my_device_backup
adb pull /system system

Add a new device to config.sh

The next step is to add a new device to config.sh; you can use the existing ones as a template. This basically involves providing the instructions for fetching the correct files to do the build.

Create the manifest file for the new device

Now you need to add the required repos to the manifest file for the new device; this manifest file is called default.xml. Refer to the b2g-manifest file on github for a template. Each device has its own branch; you can use the galaxy-s2 branch as a reference.

Create a configuration tree for the new device

Create a new configuration tree for the new device. This should be at device/<manufacturer>/<device_id>. This tree should include, at least:

  • AndroidBoard.mk
  • AndroidProducts.mk
  • BoardConfig.mk
  • extract-files.sh
  • full_<device_id>.mk
  • idc files for touchscreen
  • init files (init.rc, init.<target>.rc, uevent.rc, ...)

The content here may differ a great deal from one device to another. In particular, BoardConfig.mk and extract-files.sh may differ significantly. This part requires a lot of hacking, testing, and debugging to figure out which binary blobs should be extracted.

Note: If you can find an existing reference on CyanogenMod for your device, this information will speed up the porting process. the XDA Forum is another good place to discuss and check for resources.

Rebuilt boot.img

Once you have all that done, you need to rebuild the boot image. This isn't usually needed for the kernel itself, but to pick up the changes to init.rc.

Changes to init.rc

The init.rc you use is not the one provided by B2G; instead, you need to pull it from the device.

The main things you'll need to modify are:

Import init.b2g.rc

Add the following lines to import init.b2g.rc:

on early-init
    start ueventd
    import /init.b2g.rc

Fix permissions

Correct the permissions on the files /system/b2g/b2g, /system/b2g/updater, /system/b2g/plugin-container; this should be done after the lines that mount the filesystem read/write:

chmod 0755 /system/b2g/b2g
chmod 0755 /system/b2g/updater
chmod 0755 /system/b2g/plugin-container

You might want to start by modifying the init.rc from the new device instead of using the init.rc provided by the build system; if so, you need to remember to set TARGET_PROVIDES_INIT_RC in BoardConfig.mk.

Prebuilt kernel vs. building the kernel from source

You can use a prebuilt kernel, or you may build the kernel from source. To build the kernel from source, add AndroidKernel.mk and the kernel config to the device configuration tree.

The maguro on the old build system is an example that builds the kernel from source.

Add the new device to flash.sh

Add the new device to flash.sh; the specifics of how to do this will depend on what tools need to be used to flash the new device.

Configure, build, and flash the new device

Now you can try building for and flashing to your new device:

ANDROIDFS_DIR=my_device_backup ./config.sh <device_id> default.xml
./build.sh
./flash.sh

Test and debug

We need some details added here; indeed, this entire article could use some help.

FAQ

Forthcoming

See also

Revision Source

<p>Boot to Gecko (FirefoxOS) uses a kernel derived from <a href="http://www.android.com/" title="http://www.android.com/">Android</a>, with a <a href="/en-US/docs/Gecko" title="/en-US/docs/Gecko">Gecko</a>-based user interface on top of it. This article provides a basic guide to how to go about porting the operating system to new devices.</p>
<p>This guide assumes you're porting to a new device that already runs Android; if you're porting to another device, the job is going to be more involved.</p>
<h2>Set up your build system</h2>
<p>The first step is to configure your build system; you can follow the guide in <a href="/en-US/docs/Mozilla/Boot_to_Gecko/B2G_build_prerequisites" title="/en-US/docs/Mozilla/Boot_to_Gecko/B2G_build_prerequisites">B2G build prerequisites</a>.</p>
<h2>Clone the B2G repository</h2>
<p>The first step is to clone the B2G repository.</p>
<pre>
git clone https://github.com/mozilla-b2g/B2G.git</pre>
<h2>Create a local backup of the original Android system</h2>
<p>Next, you should back up your Android device before you start nuking it with your test builds of B2G. In addition, some of these bits will be needed by the build and install process.</p>
<pre>
mkdir my_device_backup
cd my_device_backup
adb pull /system system</pre>
<h2>Add a new device to config.sh</h2>
<p>The next step is to add a new device to <a href="https://github.com/mozilla-b2g/B2G/blob/master/config.sh" title="https://github.com/mozilla-b2g/B2G/blob/master/config.sh"><code>config.sh</code></a>; you can use the existing ones as a template. This basically involves providing the instructions for fetching the correct files to do the build.</p>
<h2>Create the manifest file for the new device</h2>
<p>Now you need to add the required repos to the manifest file for the new device; this manifest file is called default.xml. Refer to the <a href="https://github.com/mozilla-b2g/b2g-manifest" title="https://github.com/mozilla-b2g/b2g-manifest"><code>b2g-manifest</code></a> file on github for a template. Each device has its own branch; you can use the <a href="https://github.com/mozilla-b2g/b2g-manifest/tree/galaxy-s2" title="https://github.com/mozilla-b2g/b2g-manifest/tree/galaxy-s2"><code>galaxy-s2</code></a> branch as a reference.</p>
<h2>Create a configuration tree for the new device</h2>
<p>Create a new configuration tree for the new device. This should be at <code>device/<em>&lt;manufacturer&gt;</em>/<em>&lt;device_id&gt;</em></code>. This tree should include, at least:</p>
<ul>
  <li><code>AndroidBoard.mk</code></li>
  <li><code>AndroidProducts.mk</code></li>
  <li><code>BoardConfig.mk</code></li>
  <li><code>extract-files.sh</code></li>
  <li><code>full_&lt;device_id&gt;.mk</code></li>
  <li>idc files for touchscreen</li>
  <li>init files (<code>init.rc</code>, <code>init.&lt;target&gt;.rc</code>, <code>uevent.rc</code>, ...)</li>
</ul>
<p>The content here may differ a great deal from one device to another. In particular, BoardConfig.mk and extract-files.sh may differ significantly. This part requires a lot of hacking, testing, and debugging to figure out which binary blobs should be extracted.</p>
<div class="note">
  <p><strong>Note:</strong> If you can find an existing reference on <a href="http://www.cyanogenmod.com/" title="http://www.cyanogenmod.com/">CyanogenMod</a> for your device, this information will speed up the porting process. the <a href="http://forum.xda-developers.com/" title="http://forum.xda-developers.com/">XDA Forum</a> is another good place to discuss and check for resources.</p>
</div>
<h2>Rebuilt boot.img</h2>
<p>Once you have all that done, you need to rebuild the boot image. This isn't usually needed for the kernel itself, but to pick up the changes to <code>init.rc</code>.</p>
<h3>Changes to init.rc</h3>
<p>The init.rc you use is <strong>not</strong> the one provided by B2G; instead, you need to pull it from the device.</p>
<p>The main things you'll need to modify are:</p>
<h4>Import init.b2g.rc</h4>
<p>Add the following lines to import <code>init.b2g.rc</code>:</p>
<pre>
on early-init
    start ueventd
    import /init.b2g.rc</pre>
<h4>Fix permissions</h4>
<p>Correct the permissions on the files <code>/system/b2g/b2g</code>, <code>/system/b2g/updater</code>, <code>/system/b2g/plugin-container</code>; this should be done after the lines that mount the filesystem read/write:</p>
<pre>
chmod 0755 /system/b2g/b2g
chmod 0755 /system/b2g/updater
chmod 0755 /system/b2g/plugin-container</pre>
<p>You might want to start by modifying the <code>init.rc</code> from the new device instead of using the <code>init.rc</code> provided by the build system; if so, you need to remember to set <code>TARGET_PROVIDES_INIT_RC</code> in <code>BoardConfig.mk</code>.</p>
<h3>Prebuilt kernel vs. building the kernel from source</h3>
<p>You can use a prebuilt kernel, or you may build the kernel from source. To build the kernel from source, add AndroidKernel.mk and the kernel config to the device configuration tree.</p>
<p>The <a href="https://github.com/andreasgal/B2G/tree/master/glue/gonk/device/toro/maguro" title="https://github.com/andreasgal/B2G/tree/master/glue/gonk/device/toro/maguro">maguro</a> on the old build system is an example that builds the kernel from source.</p>
<h2>Add the new device to flash.sh</h2>
<p>Add the new device to <code>flash.sh</code>; the specifics of how to do this will depend on what tools need to be used to flash the new device.</p>
<h2>Configure, build, and flash the new device</h2>
<p>Now you can try building for and flashing to your new device:</p>
<pre>
ANDROIDFS_DIR=my_device_backup ./config.sh &lt;device_id&gt; default.xml
./build.sh
./flash.sh</pre>
<h2>Test and debug</h2>
<p>We need some details added here; indeed, this entire article could use some help.</p>
<h2>FAQ</h2>
<p>Forthcoming</p>
<h2>See also</h2>
<ul>
  <li><a href="/en-US/docs/Mozilla/Boot_to_Gecko" title="/en-US/docs/Mozilla/Boot_to_Gecko">Boot to Gecko</a></li>
  <li><a href="https://github.com/mozilla-b2g/B2G" title="https://github.com/mozilla-b2g/B2G">B2G source code on Github</a></li>
  <li><a href="http://www.android.com/" title="http://www.android.com/">Android web site</a></li>
</ul>
Revert to this revision