goldfish: Add specification for Goldfish devices.
This adds a new document to properly specified the goldfish
virtual harware platform. This shall help for the following
cases:
- Porting goldfish support to upstream QEMU.
- Updating goldfish kernel sources to more recent Linux tree.
Change-Id: Icbf57fa7f3667bfb8e0785f6137d7d79db313b0e
diff --git a/docs/GOLDFISH-VIRTUAL-HARDWARE.TXT b/docs/GOLDFISH-VIRTUAL-HARDWARE.TXT
new file mode 100644
index 0000000..a0dc90d
--- /dev/null
+++ b/docs/GOLDFISH-VIRTUAL-HARDWARE.TXT
@@ -0,0 +1,917 @@
+Introduction
+============
+
+This file documents the 'goldfish' virtual hardware platform used to run some
+emulated Android systems under QEMU. It serves as a reference for implementers
+of virtual devices in QEMU, as well as Linux kernel developers who need to
+maintain the corresponding drivers.
+
+The following abbreviations will be used here:
+
+ $QEMU -> path to the Android AOSP directory, i.e. a git clone of
+ https://android.googlesource.com/platform/external/qemu.git
+
+ $KERNEL -> path to the Android goldfish kernel source tree, i.e. a git clone of
+ https://android.googlesource.com/kernel/goldfish.git
+
+ More specifically, to the android-goldfish-2.6.29 branch for now.
+
+'goldfish' is the name of a family of similar virtual hardware platforms, that
+mostly differ in the virtual CPU they support. 'goldfish' started as an
+ARM-specific platform, but has now been ported to x86 and MIPS virtual CPUs.
+
+Inside of QEMU, goldfish-specific virtual device implementation sources files
+are in $QEMU/hw/android/goldfish/*.c sources
+
+Inside the Linux kernel tree, they are under $KERNEL/arch/$ARCH/mach-goldfish,
+or $KERNEL/arch/$ARCH/goldfish/, as well as a few arch-independent drivers in
+different locations (detailed below).
+
+Goldfish devices appear to the Linux kernel as 'platform devices'. Read [1] and
+[2] for an introduction and reference documentation for these.
+
+Each device is identified by a name, and an optional unique id (an integer used
+to distinguish between several identical instances of similar devices, like
+serial ports, of block devices). When only one instance of a given device can
+be used, an ID of -1 is used instead.
+
+It also communicates with the kernel through:
+
+ - One or more 32-bit of I/O registers, mapped to physical addresses at
+ specific locations which depend on the architecture.
+
+ - Zero or more interrupt requests, used to signal to the kernel that an
+ important event occured.
+
+ Note that IRQ lines are numbered from 0 to 31, and are relative to the
+ goldfish interrupt controller, documented below.
+
+
+[1] http://lwn.net/Articles/448499/
+[2] https://www.kernel.org/doc/Documentation/driver-model/platform.txt
+
+
+I. Goldfish platform bus:
+=========================
+
+The 'platform bus', in Linux kernel speak, is a special device that is capable
+of enumerating other platform devices found on the system to the kernel. This
+flexibility allows to customize which virtual devices are available when running
+a given emulated system configuration.
+
+Relevant files:
+ $QEMU/hw/android/goldfish/device.c
+ $KERNEL/arch/arm/mach-goldfish/pdev_bus.c
+ $KERNEL/arch/x86/mach-goldfish/pdev_bus.c
+ $KERNEL/arch/mips/goldfish/pdev_bus.c
+
+Device properties:
+ Name: goldfish_device_bus
+ Id: -1
+ IrqCount: 1
+
+ 32-bit I/O registers (offset, name, abstract)
+
+ 0x00 BUS_OP R: Iterate to next device in enumeration.
+ W: Start device enumeration.
+
+ 0x04 GET_NAME W: Copy device name to kernel memory.
+ 0x08 NAME_LEN R: Read length of current device's name.
+ 0x0c ID R: Read id of current device.
+ 0x10 IO_BASE R: Read I/O base address of current device.
+ 0x14 IO_SIZE R: Read I/O base size of current device.
+ 0x18 IRQ_BASE R: Read base IRQ of current device.
+ 0x1c IRQ_COUNT R: Read IRQ count of current device.
+
+The kernel iterates over the list of current devices with something like:
+
+ IO_WRITE(BUS_OP, 0); // Start iteration, any value other than 0 is invalid.
+ for (;;) {
+ int ret = IO_READ(BUS_OP);
+ if (ret == 0 /* OP_DONE */) {
+ // no more devices.
+ break;
+ }
+ else if (ret == 8 /* OP_ADD_DEV */) {
+ // Read device properties.
+ Device dev;
+ dev.name_len = IO_READ(NAME_LEN);
+ dev.id = IO_READ(ID);
+ dev.io_base = IO_READ(IO_BASE);
+ dev.io_size = IO_READ(IO_SIZE);
+ dev.irq_base = IO_READ(IRQ_BASE);
+ dev.irq_count = IO_READ(IRQ_COUNT);
+
+ dev.name = kalloc(dev.name_len + 1); // allocate room for device name.
+ IO_WRITE(GET_NAME, dev.name); // copy to kernel memory.
+ dev.name[dev.name_len] = 0;
+
+ .. add device to kernel's list.
+ }
+ else {
+ // Not returned by current goldfish implementation.
+ }
+ }
+
+The device also uses a single IRQ, which it will raise to indicate to the kernel
+that new devices are available, or that some of them have been removed. The
+kernel will then start a new enumeration. The IRQ is lowered by the device only
+when a IO_READ(BUS_OP) returns 0 (OP_DONE).
+
+NOTE: The kernel hard-codes a platform_device definition with the name
+ "goldfish_pdev_bus" for the platform bus (e.g. see
+ $KERNEL/arch/arm/mach-goldfish/board-goldfish.c), however, the bus itself
+ will appear during enumeration as a device named "goldfish_device_bus"
+
+ The kernel driver for the platform bus only matches the "goldfish_pdev_bus"
+ name, and will ignore any device named "goldfish_device_bus".
+
+
+II. Goldfish interrupt controller:
+==================================
+
+IMPORTANT: The controller IS NOT USED IN EMULATED X86 SYSTEMS.
+ TODO(digit): Indicate which virtual PIC is used on x86 systems.
+
+Relevant files:
+ $QEMU/hw/android/goldfish/interrupt.c
+ $KERNEL/arch/arm/mach-goldfish/board-goldfish.c
+ $KERNEL/arch/mips/goldfish/goldfish-interrupt.c
+
+Device properties:
+ Name: goldfish_interrupt_controller
+ Id: -1
+ IrqCount: 0 (uses parent CPU IRQ instead).
+
+ 32-bit I/O registers (offset, name, abtract):
+ 0x00 STATUS R: Read the number of pending interrupts (0 to 32).
+ 0x04 NUMBER R: Read the lowest pending interrupt index, or 0 if none.
+ 0x08 DISABLE_ALL W: Clear all pending interrupts (does not disable them!)
+ 0x0c DISABLE W: Disable a given interrupt, value must be in [0..31].
+ 0x10 ENABLE W: Enable a given interrupt, value must be in [0..31].
+
+Goldfish provides its own interrupt controller that can manage up to 32 distinct
+maskable interrupt request lines. The controller itself is cascaded from a
+parent CPU IRQ.
+
+What this means in practice:
+
+ - Each IRQ has a 'level' that is either 'high' (1) or 'low' (0).
+
+ - Each IRQ also has a binary 'enable' flag.
+
+ - Whenever (level == 1 && enabled == 1) is reached due to a state change, the
+ controller raises its parent IRQ. This typically interrupts the CPU and
+ forces the kernel to deal with the interrupt request.
+
+ - Raised/Enabled interrupts that have not been serviced yet are called
+ "pending". Raised/Disabled interrupts are called "masked" and are
+ essentially silent until enabled.
+
+When the interrupt controller triggers the parent IRQ, the kernel should do
+the following:
+
+ num_pending = IO_READ(STATUS); // Read number of pending interrupts.
+ for (int n = 0; n < num_pending; ++n) {
+ int irq_index = IO_READ(NUMBER); // Read n-th interrupt index.
+ .. service interrupt request with the proper driver.
+ }
+
+IO_WRITE(DISABLE, <num>) or IO_WRITE(ENABLE, <num>) can change the 'enable' flag
+of a given IRQ. <num> must be a value in the [0..31] range. Note that enabling
+an IRQ which has already been raised will make it active, i.e. it will raise
+the parent IRQ.
+
+IO_WRITE(DISABLE_ALL, 0) can be used to lower all interrupt levels at once (even
+disabled one). Note that this constant is probably mis-named since it does not
+change the 'enable' flag of any IRQ.
+
+Note that this is the only way for the kernel to lower an IRQ level through
+this device. Generally speaking, Goldfish devices are responsible for lowering
+their own IRQ, which is performed either when a specific condition is met, or
+when the kernel reads from or writes to a device-specific I/O register.
+
+
+III. Godlfish timer:
+====================
+
+NOTE: This is not used on x86 emulated platforms.
+
+Relevant files:
+ $QEMU/hw/android/goldfish/timer.c
+ $KERNEL/arch/arm/mach-goldfish/timer.c
+ $KERNEL/arch/mips/goldfish/goldfish-time.c
+
+Device properties:
+ Name: goldfish_timer
+ Id: -1
+ IrqCount: 1
+
+ 32-bit I/O registers (offset, name, abstract)
+ 0x00 TIME_LOW R: Get current time, then return low-order 32-bits.
+ 0x04 TIME_HIGH R: Return high 32-bits from previous TIME_LOW read.
+ 0x08 ALARM_LOW W: Set low 32-bit value of alarm, then arm it.
+ 0x0c ALARM_HIGH W: Set high 32-bit value of alarm.
+ 0x10 CLEAR_INTERRUPT W: Lower device's irq level.
+ 0x14 CLEAR_ALARM
+
+This device is used to return the current host time to the kernel, as a
+high-precision signed 64-bit nanoseconds value, starting from a liberal point
+in time. This value should correspond to the QEMU "vm_clock", i.e. it should
+not be updated when the emulated system does _not_ run, and hence cannot be
+based directly on a host clock.
+
+To read the value, the kernel must perform an IO_READ(TIME_LOW), which returns
+an unsigned 32-bit value, before an IO_READ(TIME_HIGH), which returns a signed
+32-bit value, corresponding to the higher half of the full value.
+
+The device can also be used to program an alarm, with something like:
+
+ IO_WRITE(ALARM_HIGH, <high-value>) // Must happen first.
+ IO_WRITE(ALARM_LOW, <low-value>) // Must happen second.
+
+When the corresponding value is reached, the device will raise its IRQ. Note
+that the IRQ is raised as soon as the second IO_WRITE() if the alarm value is
+already older than the current time.
+
+IO_WRITE(CLEAR_INTERRUPT, <any>) can be used to lower the IRQ level once the
+alarm has been handled by the kernel.
+
+IO_WRITE(CLEAR_ALARM, <any>) can be used to disarm an existing alarm, if any.
+
+Note: At the moment, the alarm is only used on ARM-based system. MIPS based
+ systems only use TIME_LOW / TIME_HIGH on this device.
+
+
+III. Goldfish real-time clock (RTC):
+====================================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/timer.c
+ $KERNEL/drivers/rtc/rtc-goldfish.c
+
+Device properties:
+ Name: goldfish_rtc
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+ 0x00 TIME_LOW R: Get current time, then return low-order 32-bits.
+ 0x04 TIME_HIGH R: Return high 32-bits, from previous TIME_LOW read.
+ 0x08 ALARM_LOW W: Set low 32-bit value or alarm, then arm it.
+ 0x0c ALARM_HIGH W: Set high 32-bit value of alarm.
+ 0x10 CLEAR_INTERRUPT W: Lower device's irq level.
+
+This device is _very_ similar to the Goldfish timer one, with the following
+important differences:
+
+ - Values reported are still 64-bit nanoseconds, but they have a granularity
+ of 1 second, and represent host-specific values (really 'time() * 1e9')
+
+ - The alarm is non-functioning, i.e. writing to ALARM_LOW / ALARM_HIGH will
+ work, but will never arm any alarm.
+
+To support old Goldfish kernels, make sure to support writing to
+ALARM_LOW / ALARM_HIGH / CLEAR_INTERRUPT, even if the device never raises its
+IRQ.
+
+
+IV. Goldfish serial port (tty):
+===============================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/tty.c
+ $KERNEL/drivers/char/goldfish_tty.c
+ $KERNEL/arch/arm/mach-goldfish/include/debug-macro.S
+
+Device properties:
+ Name: goldfish_tty
+ Id: 0 to N
+ IrqCount:
+ I/O Registers:
+ 0x00 PUT_CHAR W: Write a single 8-bit value to the serial port.
+ 0x04 BYTES_READY R: Read the number of available buffered input bytes.
+ 0x08 CMD W: Send command (see below).
+ 0x10 DATA_PTR W: Write kernel buffer address.
+ 0x14 DATA_LEN W: Write kernel buffer size.
+
+This is the first case of a multi-instance goldfish device in this document.
+Each instance implements a virtual serial port that contains a small internal
+buffer where incoming data is stored until the kernel fetches it.
+
+The CMD I/O register is used to send various commands to the device, identified
+by the following values:
+
+ 0x00 CMD_INT_DISABLE Disable device.
+ 0x01 CMD_INT_ENABLE Enable device.
+ 0x02 CMD_WRITE_BUFFER Write buffer from kernel to device.
+ 0x03 CMD_READ_BUFFER Read buffer from device to kernel.
+
+Each device instance uses one IRQ that is raised to indicate that there is
+incoming/buffered data to read. To read such data, the kernel should do the
+following:
+
+ len = IO_READ(PUT_CHAR); // Read length of incoming data.
+ if (len == 0) return; // Nothing to do.
+
+ available = get_buffer(len, &buffer); // Get address of buffer and its size.
+ IO_WRITE(DATA_PTR, buffer); // Write buffer address to device.
+ IO_WRITE(DATA_LEN, available); // Write buffer length to device.
+ IO_WRITE(CMD, CMD_READ_BUFFER); // Read the data into kernel buffer.
+
+The device will automatically lower its IRQ when there is no more input data
+in its buffer. However, the kernel can also temporarily disable device interrupts
+with CMD_INT_DISABLE / CMD_INT_ENABLE.
+
+Note that disabling interrupts does not flush the buffer, nor prevent it from
+buffering further data from external inputs.
+
+To write to the serial port, the device can either send a single byte at a time
+with:
+
+ IO_WRITE(PUT_CHAR, <value>) // Send the lower 8 bits of <value>.
+
+Or use the mode efficient sequence:
+
+ IO_WRITE(DATA_PTR, buffer)
+ IO_WRITE(DATA_LEN, buffer_len)
+ IO_WRITE(CMD, CMD_WRITE_BUFFER)
+
+The former is less efficient but simpler, and is typically used by the kernel
+to send debug messages only.
+
+Note that the Android emulator always reserves the first two virtual serial
+ports:
+
+ - The first one is used to receive kernel messages, this is done by adding
+ the 'console=ttyS0' parameter to the kernel command line in
+ $QEMU/vl-android.c
+
+ - The second one is used to setup the legacy "qemud" channel, used on older
+ Android platform revisions. This is done by adding 'android.qemud=ttyS1'
+ on the kernel command line in $QEMU/vl-android.c
+
+ Read docs/ANDROID-QEMUD.TXT for more details about the data that passes
+ through this serial port. In a nutshell, this is required to emulate older
+ Android releases (e.g. cupcake). It provides a direct communication channel
+ between the guest system and the emulator.
+
+ More recent Android platforms do not use QEMUD anymore, but instead rely
+ on the much faster "QEMU pipe" device, described later in this document as
+ well as in docs/ANDROID-QEMU-PIPE.TXT.
+
+
+V. Goldfish framebuffer:
+========================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/fb.c
+ $KERNEL/drivers/video/goldfish_fb.c
+
+Device properties:
+ Name: goldfish_fb
+ Id: 0 to N (only one used in practice).
+ IrqCount: 0
+ I/O Registers:
+ 0x00 GET_WIDTH R: Read framebuffer width in pixels.
+ 0x04 GET_HEIGHT R: Read framebuffer height in pixels.
+ 0x08 INT_STATUS
+ 0x0c INT_ENABLE
+ 0x10 SET_BASE
+ 0x14 SET_ROTATION
+ 0x18 SET_BLANK W: Set 'blank' flag.
+ 0x1c GET_PHYS_WIDTH R: Read framebuffer width in millimeters.
+ 0x20 GET_PHYS_HEIGHT R: Read framebuffer height in millimeters.
+ 0x24 GET_FORMAT R: Read framebuffer pixel format.
+
+The framebuffer device is a bit peculiar, because it uses, in addition to the
+typical I/O registers and IRQs, a large area of physical memory, allocated by
+the kernel, but visible to the emulator, to store a large pixel buffer.
+
+The emulator is responsible for displaying the framebuffer content in its UI
+window, which can be rotated, as instructed by the kernel.
+
+IMPORTANT NOTE: When GPU emulation is enabled, the framebuffer will typically
+only be used during boot. Note that GPU emulation doesn't rely on a specific
+virtual GPU device, however, it uses the "QEMU Pipe" device described below.
+For more information, please read:
+
+ https://android.googlesource.com/platform/sdk/+/master/emulator/opengl/DESIGN
+
+On boot, the kernel will read various properties of the framebuffer:
+
+ IO_READ(GET_WIDTH) and IO_READ(GET_HEIGHT) return the width and height of
+ the framebuffer in pixels. Note that a 'row' corresponds to consecutive bytes
+ in memory, but doesn't necessarily to an horizontal line on the final display,
+ due to possible rotation (see SET_ROTATION below).
+
+ IO_READ(GET_PHYS_WIDTH) and IO_READ(GET_PHYS_HEIGHT) return the emulated
+ physical width and height in millimeters, this is later used by the kernel
+ and the platform to determine the device's emulated density.
+
+ IO_READ(GET_FORMAT) returns a value matching the format of pixels in the
+ framebuffer. Note that these values are specified by the Android hardware
+ abstraction layer (HAL) and cannot change:
+
+ 0x01 HAL_PIXEL_FORMAT_BRGA_8888
+ 0x02 HAL_PIXEL_FORMAT_RGBX_8888
+ 0x03 HAL_PIXEL_FORMAT_RGB_888
+ 0x04 HAL_PIXEL_FORMAT_RGB_565
+ 0x05 HAL_PIXEL_FORMAT_BGRA_8888
+ 0x06 HAL_PIXEL_FORMAT_RGBA_5551
+ 0x08 HAL_PIXEL_FORMAT_RGBA_4444
+
+ HOWEVER, the kernel driver only expects a value of HAL_PIXEL_FORMAT_RGB_565
+ at the moment. Until this is fixed, the virtual device should always return
+ the value 0x04 here. Rows are not padded, so the size in bytes of a single
+ framebuffer will always be exactly 'width * heigth * 2'.
+
+ Note that GPU emulation doesn't have this limitation and can use and display
+ 32-bit surfaces properly, because it doesn't use the framebuffer.
+
+The device has a 'blank' flag. When set to 1, the UI should only display an
+empty/blank framebuffer, ignoring the content of the framebuffer memory.
+It is set with IO_WRITE(SET_BLANK, <value>), where value can be 1 or 0. This is
+used when simulating suspend/resume.
+
+IMPORTANT: The framebuffer memory is allocated by the kernel, which will send
+its physical address to the device by using IO_WRITE(SET_BASE, <address>).
+
+The kernel really allocates a memory buffer large enough to hold *two*
+framebuffers, in order to implement panning / double-buffering. This also means
+that calls to IO_WRITE(SET_BASE, <address>) will be frequent.
+
+The allocation happens with dma_alloc_writecombine() on ARM, which can only
+allocate a maximum of 4 MB, this limits the size of each framebuffer to 2 MB,
+which may not be enough to emulate high-density devices :-(
+
+For other architectures, dma_alloc_coherent() is used instead, and has the same
+upper limit / limitation.
+
+TODO(digit): Explain how it's possible to raise this limit by modifyinf
+ CONSISTENT_DMA_SIZE and/or MAX_ORDER in the kernel configuration.
+
+The device uses a single IRQ to notify the kernel of several events. When it
+is raised, the kernel IRQ handler must IO_READ(INT_STATUS), which will return
+a value containing the following bit flags:
+
+ bit 0: Set to 1 to indicate a VSYNC event.
+
+ bit 1: Set to 1 to indicate that the content of a previous SET_BASE has
+ been properly displayed.
+
+Note that reading this register also lowers the device's IRQ level.
+
+The second flag is essentially a way to notify the kernel that an
+IO_WRITE(SET_BASE, <address>) operation has been succesfully processed by
+the emulator, i.e. that the new content has been displayed to the user.
+
+The kernel can control which flags should raise an IRQ by using
+IO_WRITE(INT_ENABLE, <flags>), where <flags> has the same format as the
+result of IO_READ(INT_STATUS). If the corresponding bit is 0, the an IRQ
+for the corresponding event will never be generated,
+
+
+VI. Goldfish audio device:
+==========================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/audio.c
+ $KERNEL/drivers/misc/goldfish_audio.c
+
+Device properties:
+ Name: goldfish_audio
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+ 0x00 INT_STATUS
+ 0x04 INT_ENABLE
+ 0x08 SET_WRITE_BUFFER_1 W: Set address of first kernel output buffer.
+ 0x0c SET_WRITE_BUFFER_2 W: Set address of second kernel output buffer.
+ 0x10 WRITE_BUFFER_1 W: Send first kernel buffer samples to output.
+ 0x14 WRITE_BUFFER_2 W: Send second kernel buffer samples to output.
+ 0x18 READ_SUPPORTED R: Reads 1 if input is supported, 0 otherwise.
+ 0x1c SET_READ_BUFFER
+ 0x20 START_READ
+ 0x24 READ_BUFFER_AVAILABLE
+
+This device implements a virtual sound card with the following properties:
+
+ - Stereo output at fixed 44.1 kHz frequency, using signed 16-bit samples.
+ Mandatory.
+
+ - Mono input at fixed 8 kHz frequency, using signed 16-bit samples.
+ Optional.
+
+For output, the kernel driver allocates two internal buffers to hold output
+samples, and passes their physical address with
+IO_WRITE(SET_WRITE_BUFFER_1, <buffer1>) and
+IO_WRITE(SET_WRITE_BUFFER_2, <buffer2>).
+
+After this, samples will be sent from the driver to the virtual device by
+using one of IO_WRITE(WRITE_BUFFER_1, <length1>) or
+IO_WRITE(WRITE_BUFFER_2, <length2>), depending on which sample buffer to use.
+NOTE: Each length is in bytes.
+
+Note however that the driver should wait, before doing this, until the device
+gives permission by raising its IRQ and setting the appropriate 'status' flags.
+
+The virtual device has an internal 'int_status' field made of 3 bit flags:
+
+ bit0: 1 iff the device is ready to receive data from the first buffer.
+ bit1: 1 iff the device is ready to receive data from the second buffer.
+ bit2: 1 iff the device has input samples for the kernel to read.
+
+Note that an IO_READ(INT_STATUS) also automatically lowers the IRQ level,
+except if the read value is 0 (which should not happen, since it should not
+raise the IRQ).
+
+The corresponding interrupts can be masked by using IO_WRITE(INT_ENABLE, <mask>),
+where <mask> has the same format as 'int_status'. A 1 bit in the mask enables the
+IRQ raise when the corresponding status bit is also set to 1.
+
+For input, the driver should first IO_READ(READ_SUPPORTED), which will return 1
+if the virtual device supports input, or 0 otherwise. If it does support it,
+the driver must allocate an internal buffer and send its physical address with
+IO_WRITE(SET_READ_BUFFER, <read-buffer>), then perform
+IO_WRITE(START_READ, <read-buffer-length>) to start recording and specify
+the kernel's buffer length.
+
+Later, the device will raise its IRQ and set bit2 of 'int_status' to indicate
+there are incoming samples to the driver. In its interrupt handler, the latter
+should IO_READ(READ_BUFFER_AVAILABLE), which triggers the transfer (from the
+device to the kernel), as well as return the size in bytes of the samples.
+
+
+VII. Goldfish battery:
+======================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/battery.c
+ $QEMU/hw/power_supply.h
+ $KERNEL/drivers/power/goldfish_battery.c
+
+Device properties:
+ Name: goldfish_battery
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+ 0x00 INT_STATUS R: Read battery and A/C status change bits.
+ 0x04 INT_ENABLE W: Enable or disable IRQ on status change.
+ 0x08 AC_ONLINE R: Read 0 if AC power disconnected, 1 otherwise.
+ 0x0c STATUS R: Read battery status (charging/full/... see below).
+ 0x10 HEALTH R: Read battery health (good/overheat/... see below).
+ 0x14 PRESENT R: Read 1 if battery is present, 0 otherwise.
+ 0x18 CAPACITY R: Read battery charge percentage in [0..100] range.
+
+A simple device used to report the state of the virtual device's battery, and
+whether the device is powered through a USB or A/C adapter.
+
+The device uses a single IRQ to notify the kernel that the battery or A/C status
+changed. When this happens, the kernel should perform an IO_READ(INT_STATUS)
+which returns a 2-bit value containing flags:
+
+ bit 0: Set to 1 to indicate a change in battery status.
+ bit 1: Set to 1 to indicate a change in A/C status.
+
+Note that reading this register also lowers the IRQ level.
+
+The A/C status can be read with IO_READ(AC_ONLINE), which returns 1 if the
+device is powered, or 0 otherwise.
+
+The battery status is spread over multiple I/O registers:
+
+ IO_READ(PRESENT) returns 1 if the battery is present in the virtual device,
+ or 0 otherwise.
+
+ IO_READ(CAPACITY) returns the battery's charge percentage, as an integer
+ between 0 and 100, inclusive. NOTE: This register is probably misnamed since
+ it does not represent the battery's capacity, but it's current charge level.
+
+ IO_READ(STATUS) returns one of the following values:
+
+ 0x00 UNKNOWN Battery state is unknown.
+ 0x01 CHARGING Battery is charging.
+ 0x02 DISCHARGING Battery is discharging.
+ 0x03 NOT_CHARGING Battery is not charging (e.g. full or dead).
+
+ IO_READ(HEALTH) returns one of the following values:
+
+ 0x00 UNKNOWN Battery health unknown.
+ 0x01 GOOD Battery is in good condition.
+ 0x02 OVERHEATING Battery is over-heating.
+ 0x03 DEAD Battery is dead.
+ 0x04 OVERVOLTAGE Battery generates too much voltage.
+ 0x05 UNSPEC_FAILURE Battery has unspecified failure.
+
+The kernel can use IO_WRITE(INT_ENABLE, <flags>) to select which condition
+changes should trigger an IRQ. <flags> is a 2-bit value using the same format
+as INT_STATUS.
+
+
+VIII. Goldfish events device (user input):
+==========================================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/events_device.c
+ $KERNEL/drivers/input/keyboard/goldfish_events.c
+
+Device properties:
+ Name: goldfish_events
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+ 0x00 READ R: Read next event type, code or value.
+ 0x00 SET_PAGE W: Set page index.
+ 0x04 LEN R: Read length of page data.
+ 0x08 DATA R: Read page data.
+ .... R: Read additional page data (see below).
+
+This device is responsible for sending several kinds of user input events to
+the kernel, i.e. emulated device buttons, hardware keyboard, touch screen,
+trackball and lid events.
+
+NOTE: Android supports other input devices like mice or game controllers
+ through USB or Bluetooth, these are not supported by this virtual
+ Goldfish device.
+
+NOTE: The 'lid event' is useful for devices with a clamshell of foldable
+ keyboard design, and is used to report when it is opened or closed.
+
+As per Linux conventions, each 'emulated event' is sent to the kernel as a
+series of (<type>,<code>,<value>) triplets or 32-bit values. For more
+information, see:
+
+ https://www.kernel.org/doc/Documentation/input/input.txt
+
+As well as the <linux/input.h> kernel header.
+
+Note that in the context of goldfish:
+
+ - Button and keyboard events are reported with:
+ (EV_KEY, <code>, <press>)
+
+ Where <code> is a 9-bit keycode, as defined by <linux/input.h>, and
+ <press> is 1 for key/button presses, and 0 for releases.
+
+ - For touchscreen events, a single-touch event is reported with:
+ (EV_ABS, ABS_X, <x-position>) +
+ (EV_ABS, ABS_Y, <y-position>) +
+ (EV_ABS, ABS_Z, 0) +
+ (EV_KEY, BTN_TOUCH, <button-state>) +
+ (EV_SYN, 0, 0)
+
+ where <x-position> and <y-position> are the horizontal and vertical position
+ of the touch event, respectfully, and <button-state> is either 1 or 0 and
+ indicates the start/end of the touch gesture, respectively.
+
+ - For multi-touch events, things are much more complicated. In a nutshell,
+ these events are reported through (EV_ABS, ABS_MT_XXXXX, YYY) triplets,
+ as documented at:
+
+ https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt
+
+ TODO(digit): There may be bugs in either the virtual device or driver code
+ when it comes to multi-touch. Iron out the situation and better
+ explain what's required to support all Android platforms.
+
+ - For trackball events:
+ (EV_REL, REL_X, <x-delta>) +
+ (EV_REL, REL_Y, <y-delta>) +
+ (EV_SYN, 0, 0)
+
+ Where <x-delta> and <y-delta> are the signed relative trackball displacement
+ in the horizontal and vertical directions, respectively.
+
+ - For lid events:
+ (EV_SW, 0, 1) + (EV_SYN, 0, 0) // When lid is closed.
+ (EV_SW, 0, 0) + (EV_SYN, 0, 0) // When lid is opened.
+
+When the kernel driver starts, it will probe the device to know what kind
+of events are supported by the emulated configuration. There are several
+categories of queries:
+
+ - Asking for the current physical keyboard 'charmap' name, used by the system
+ to translate keycodes in actual characters. In practice, this will nearly
+ always be 'goldfish' for emulated systems, but this out of spec for this
+ document.
+
+ - Asking which event codes are supported for a given event type
+ (e.g. all the possible KEY_XXX values generated for EV_KEY typed triplets).
+
+ - Asking for various minimum or maximum values for each supported EV_ABS
+ event code. For example the min/max values of (EV_ABS, ABS_X, ...) triplets,
+ to know the bounds of the input touch panel.
+
+The kernel driver first select which kind of query it wants by using
+IO_WRITE(SET_PAGE, <page>), where <page> is one of the following values:
+
+ PAGE_NAME 0x0000 Keyboard charmap name.
+ PAGE_EVBITS 0x10000 Event code supported sets.
+ PAGE_ABSDATA 0x20003 (really 0x20000 + EV_ABS) EV_ABS min/max values.
+
+Once a 'page' has been selected, it is possible to read from it with
+IO_READ(LEN) and IO_READ(DATA). In practice:
+
+ - To read the name of the keyboard charmap, the kernel will do:
+
+ IO_WRITE(SET_PAGE, PAGE_NAME); # Ind
+
+ charmap_name_len = IO_READ(LEN);
+ charmap_name = kalloc(charmap_name_len + 1);
+ for (int n = 0; n < charmap_name_len; ++n)
+ charmap_name[n] = (char) IO_READ(DATA);
+ charmap_name[n] = 0;
+
+ - To read which codes a given event type (here EV_KEY) supports:
+
+ IO_WRITE(SET_PAGE, PAGE_EVBITS + EV_KEY); // Or EV_REL, EV_ABS, etc...
+
+ bitmask_len = IO_READ(LEN);
+ for (int offset = 0; offset < bitmask_len; ++offset) {
+ uint8_t mask = (uint8_t) IO_READ(DATA):
+ for (int bit = 0; bit < 8; ++bit) {
+ int code = (offset * 8) + bit;
+ if ((mask & (1 << bit)) != 0) {
+ ... record that keycode |code| is supported.
+ }
+ }
+ }
+
+ - To read the range values of absolute event values:
+
+ IO_WRITE(SET_PAGE, PAGE_ABSDATA);
+ max_entries = IO_READ(LEN);
+ for (int n = 0; n < max_entries; n += 4) {
+ int32_t min = IO_READ(DATA + n);
+ int32_t max = IO_READ(DATA + n + 4);
+ int32_t fuzz = IO_READ(DATA + n + 8);
+ int32_t flat = IO_READ(DATA + n + 12);
+ int event_code = n/4;
+
+ // Record (min, max, fuzz, flat) values for EV_ABS 'event_code'.
+ }
+
+ Note that the 'fuzz' and 'flat' values reported by Goldfish are always 0,
+ refer to the source for more details.
+
+At runtime, the device implements a small buffer for incoming event triplets
+(each one is stored as three 32-bit integers in a circular buffer), and raises
+its IRQ to signal them to the kernel.
+
+When that happens, the kernel driver should use IO_READ(READ) to extract the
+32-bit values from the device. Note that three IO_READ() calls are required to
+extract a single event triplet.
+
+There are a few important notes here:
+
+ - The IRQ should not be raised _before_ the kernel driver is started
+ (otherwise the driver will be confused and ignore all events).
+
+ I.e. the emulator can buffer events before kernel initialization completes,
+ but should only raise the IRQ, if needed, lazily. Currently this is done
+ on the first IO_READ(LEN) following a IO_WRITE(SET_PAGE, PAGE_ABSDATA).
+
+ - The IRQ is lowered by the device once all event values have been read,
+ i.e. its buffer is empty.
+
+ However, on x86, if after an IO_READ(READ), there are still values in the
+ device's buffer, the IRQ should be lowered then re-raised immediately.
+
+
+IX. Goldfish NAND device:
+=========================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/nand.c
+ $KERNEL/drivers/mtd/devices/goldfish_nand.c
+
+Device properties:
+ Name: goldfish_nand
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+
+This virtual device can provide access to one or more emulated NAND memory
+banks [3] (each one being backed by a different host file in the current
+implementation).
+
+These are used to back the following virtual partition files:
+
+ - system.img
+ - data.img
+ - cache.img
+
+TODO(digit): Complete this.
+
+
+[3] http://en.wikipedia.org/wiki/Flash_memory#NAND_memories
+
+
+X. Goldfish MMC device:
+=======================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/mmc.c
+ $KERNEL/drivers/mmc/host/goldfish.c
+
+Device properties:
+ Name: goldfish_mmc
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+
+Similar to the NAND device, but uses a different, higher-level interface
+to access the emulated 'flash' memory. This is only used to access the
+virtual SDCard device with the Android emulator.
+
+TODO(digit): Complete this.
+
+
+XI. Goldfish memlog:
+=====================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/memlog.c
+
+Device properties:
+ Name: goldfish_memlog
+ Id: -1
+ IrqCount: 0
+ I/O Registers:
+ ???
+
+Obsolete debugging device. Should be removed from both the kernel and the
+emulator sources.
+
+
+XII. Goldfish switch:
+=====================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/switch.c
+ $KERNEL/arch/arm/mach-goldfish/switch.c
+ $KERNEL/arch/mips/goldfish/switch.c
+
+Device properties:
+ Name: goldfish_switch
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+
+Obsolete debugging device. Should be removed from both the kernel and the
+emulator sources.
+
+
+XIV. QEMU Pipe device:
+======================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/pipe.c
+ $KERNEL/drivers/misc/qemupipe/qemu_pipe.c
+
+Device properties:
+ Name: qemu_pipe
+ Id: -1
+ IrqCount: 1
+ I/O Registers:
+ 0x00 COMMAND W: Write to perform command (see below).
+ 0x04 STATUS R: Read status
+ 0x08 CHANNEL RW: Read or set current channel id.
+ 0x0c SIZE RW: Read or set current buffer size.
+ 0x10 ADDRESS RW: Read or set current buffer physical address.
+ 0x14 WAKES R: Read wake flags.
+ 0x18 PARAMS_ADDR_LOW RW: Read/set low bytes of parameters block address.
+ 0x1c PARAMS_ADDR_HIGH RW: Read/set high bytes of parameters block address.
+ 0x20 ACCESS_PARAMS W: Perform access with parameter block.
+
+This is a special device that is totally specific to QEMU, but allows guest
+processes to communicate directly with the emulator with extremely high
+performance. This is achieved by avoiding any in-kernel memory copies, relying
+on the fact that QEMU can access guest memory at runtime (under proper
+conditions controlled by the kernel).
+
+Please refer to $QEMU/docs/ANDROID-QEMU-PIPE.TXT for full details on the
+device's operations.
+
+
+XIII. QEMU Trace device:
+========================
+
+Relevant files:
+ $QEMU/hw/android/goldfish/trace.c
+ $KERNEL/drivers/misc/qemutrace/qemu_trace.c
+ $KERNEL/drivers/misc/qemutrace/qemu_trace_sysfs.c
+ $KERNEL/fs/exec.c
+ $KERNEL/exit.c
+ $KERNEL/fork.c
+ $KERNEL/sched/core.c
+ $KERNEL/mm/mmap.c
+
+Device properties:
+ Name: qemu_trace
+ Id: -1
+ IrqCount: 0
+ I/O Registers:
+
+TODO(digit)
+