Add a section for known issues
Document the issues with the emulator and gingerbread
Change-Id: Ic60fcbbabb6d8bc46b0dcd5e250859b5ff7d1e60
diff --git a/src/source/known-issues.md b/src/source/known-issues.md
new file mode 100644
index 0000000..9f5e872
--- /dev/null
+++ b/src/source/known-issues.md
@@ -0,0 +1,36 @@
+<!--
+ Copyright 2010 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Known Issues #
+
+Even with our best care, small problems sometimes slip in. This page keeps
+track of the known issues around using the Android source code.
+
+## Black Gingerbread Emulator ##
+
+**Symptom**: The emulator built directly from the gingerbread branch
+doesn't start and stays stuck on a black screen.
+
+**Cause**: The gingerbread branch uses version R7 of the emulator,
+which doesn't have all the features necessary to run recent versions
+of gingerbread.
+
+**Fix**: Use version R12 of the emulator, and a newer kernel that matches
+those tools. No need to do a clean build.
+
+ $ repo forall external/qemu -c git checkout aosp/tools_r12
+ $ make
+ $ emulator -kernel prebuilt/android-arm/kernel/kernel-qemu-armv7
diff --git a/src/source/sidebar.md b/src/source/sidebar.md
index 31d782b..362eb04 100644
--- a/src/source/sidebar.md
+++ b/src/source/sidebar.md
@@ -4,6 +4,7 @@
- [Downloading the Source](downloading.html)
- [Building and Running](building.html)
- [Building for Devices](building-devices.html)
+- [Known Issues](known-issues.html)
# Navigating the Source #