Update doc to reflect new Goldfish source locations
+ update docs/ANDROID-QEMU-PIPE.TXT to include missing
description of "parameters block" access mode.
Change-Id: I02b96ebd484d524410b4c5d8a780cf36596d908b
diff --git a/docs/ANDROID-FRAMEBUFFER.TXT b/docs/ANDROID-FRAMEBUFFER.TXT
index 9e7ac28..4ff97d2 100644
--- a/docs/ANDROID-FRAMEBUFFER.TXT
+++ b/docs/ANDROID-FRAMEBUFFER.TXT
@@ -4,8 +4,8 @@
This document tries to explain how framebuffer emulation works in the
Android emulator.
-1 - Hardware emulation (hw/goldfish_fb.c):
-------------------------------------------
+1 - Hardware emulation (hw/android/goldfish/fb.c):
+--------------------------------------------------
The emulated hardware provides a bunch of i/o registers to allow
the following:
@@ -17,6 +17,8 @@
and the internal pixel rotation to apply before display (see
goldfish_fb_write).
+ Read docs/GOLDFISH-VIRTUAL-HARDWARE.TXT for low-level details.
+
The pixel buffer is itself a set of physical pages allocated by the
kernel driver in the emulated system. These pages are contiguous in
the emulated system, but not in the emulator's process space which
@@ -53,7 +55,7 @@
foreach cl in fb.clients:
cl.update(cl.opaque, up.x, up.y. up.w, up.h)
- hw/goldfish_fb.c implements a producer
+ hw/android/goldfish/fb.c implements a producer
the QEmulator type in android/main.c implements a client.
diff --git a/docs/ANDROID-MEMCHECK.TXT b/docs/ANDROID-MEMCHECK.TXT
index 0c5e716..01e8ccf 100644
--- a/docs/ANDROID-MEMCHECK.TXT
+++ b/docs/ANDROID-MEMCHECK.TXT
@@ -25,7 +25,7 @@
and libc use a "magic page" that is set up in such a way that every write to
that page on the emulated system produces some sort of event in the emulator,
allowing emulator to receive data that emulated system has written to the "magic
-page". For more info on that, see hw/goldfish-trace.c
+page". For more info on that, see hw/android/goldfish/trace.c
In response to events, received from libc.so, emulator keep tracks of all blocks
that have been allocated from the heap on emulated system. Block descriptors are
diff --git a/docs/ANDROID-QEMU-PIPE.TXT b/docs/ANDROID-QEMU-PIPE.TXT
index c12dea0..e0d295c 100644
--- a/docs/ANDROID-QEMU-PIPE.TXT
+++ b/docs/ANDROID-QEMU-PIPE.TXT
@@ -36,9 +36,9 @@
In the emulator source tree:
- ./hw/goldfish_pipe.c implements the virtual driver.
+ ./hw/android/goldfish/pipe.c implements the virtual driver.
- ./hw/goldfish_pipe.h provides the interface that must be
+ ./hw/android/goldfish/pipe.h provides the interface that must be
implemented by any emulator pipe service.
./android/hw-pipe-net.c contains the implementation of the network pipe
@@ -157,7 +157,7 @@
This is the same than CMD_WAKE_ON_WRITE, but for readability instead.
REG_CHANNEL = <channel>
- REG_CMD = CMD_WAKE_ON_WRITE
+ REG_CMD = CMD_WAKE_ON_READ
7/ Polling for write-able/read-able state:
@@ -202,18 +202,62 @@
PIPE_WAKE_CLOSED can be signaled at any time.
+ 9/ Faster read/writes through parameter blocks:
+
+ Recent Goldfish kernels implement a faster way to perform reads and writes
+ that perform a single I/O write per operation (which is useful when
+ emulating x86 system through KVM or HAX).
+
+ This uses the following structure known to both the virtual device and
+ the kernel, defined in $QEMU/hw/android/goldfish/pipe.h:
+
+ struct access_params{
+ uint32_t channel;
+ uint32_t size;
+ uint32_t address;
+ uint32_t cmd;
+ uint32_t result;
+ /* reserved for future extension */
+ uint32_t flags;
+ };
+
+ This is simply a way to pack several parameters into a single structure.
+ Preliminary, e.g. at boot time, the kernel will allocate one such structure
+ and pass its physical address with:
+
+ PARAMS_ADDR_LOW = (params & 0xffffffff);
+ PARAMS_ADDR_HIGH = (params >> 32) & 0xffffffff;
+
+ Then for each operation, it will do something like:
+
+ params.channel = channel;
+ params.address = buffer;
+ params.size = buffer_size;
+ params.cmd = CMD_WRITE_BUFFER (or CMD_READ_BUFFER)
+
+ REG_ACCESS_PARAMS = <any>
+
+ status = params.status
+
+ The write to REG_ACCESS_PARAMS will trigger the operation, i.e. QEMU will
+ read the content of the params block, use its fields to perform the
+ operation then write back the return value into params.status.
+
+
Available services:
-------------------
tcp:<port>
- tcp:<hostname>:<port>
- Open a TCP socket to a given port. This provides a very fast
+ Open a TCP socket to a given localhost port. This provides a very fast
pass-through that doesn't depend on the very slow internal emulator
NAT router. Note that you can only use the file descriptor with read()
and write() though, send() and recv() will return an ENOTSOCK error,
as well as any socket ioctl().
+ For security reasons, it is not possible to connect to non-localhost
+ ports.
+
unix:<path>
Open a Unix-domain socket on the host.
@@ -222,3 +266,10 @@
Connects to the OpenGL ES emulation process. For now, the implementation
is equivalent to tcp:22468, but this may change in the future.
+
+ qemud
+
+ Connects to the QEMUD service inside the emulator. This replaces the
+ connection that was performed through /dev/ttyS1 in older Android platform
+ releases. See $QEMU/docs/ANDROID-QEMUD.TXT for details.
+
diff --git a/docs/ANDROID-QEMUD.TXT b/docs/ANDROID-QEMUD.TXT
index 8b4f8d6..61254f1 100644
--- a/docs/ANDROID-QEMUD.TXT
+++ b/docs/ANDROID-QEMUD.TXT
@@ -15,7 +15,7 @@
things since it does *not* require:
- writing/configuring a specific kernel driver
-- writing the corresponding hardware emulation code in hw/goldfish_xxxx.c
+- writing the corresponding hardware emulation code in hw/android/goldfish/*.c
- dealing with device allocation and permission issues in the emulated system
The emulator provides 'services' to various parts of the emulated system.
diff --git a/docs/ANDROID-TRACING.TXT b/docs/ANDROID-TRACING.TXT
index a216d83..5546e7b 100644
--- a/docs/ANDROID-TRACING.TXT
+++ b/docs/ANDROID-TRACING.TXT
@@ -1,6 +1,6 @@
This document details how the Android-specific -trace <name> instruction works.
-hw/goldfish_trace.c:
+hw/android/goldfish/trace.c:
- virtual hardware i/o memory used by the goldfish kernel to send event information
to the emulator (e.g. context switches, forks, execs, etc...). Used by both -trace
diff --git a/docs/CHAR-DEVICES.TXT b/docs/CHAR-DEVICES.TXT
index d6b2701..cf3870f 100644
--- a/docs/CHAR-DEVICES.TXT
+++ b/docs/CHAR-DEVICES.TXT
@@ -141,9 +141,9 @@
Typical examples are the following:
- - The hardware serial port emulation (e.g. hw/goldfish_tty.c) will read data
- from the kernel then send it to a CS. It also uses a small buffer that is
- used to read data from the CS and send it back to the kernel.
+ - The hardware serial port emulation (e.g. hw/android/goldfish/tty.c) will
+ read data from the kernel then send it to a CS. It also uses a small buffer
+ that is used to read data from the CS and send it back to the kernel.
- The Android emulated modem also uses a CS to talk with its client,
which will in most cases be an emulated serial port.
@@ -177,8 +177,8 @@
The Android emulator also provides a convenient abstraction called a "charpipe"
used to connect two CharDriverState users together. For example, this is used
-to connect a serial port emulation (in hw/goldfish_tty.c) to the internal
-GSM modem emulation (see telephony/modem_driver.c).
+to connect a serial port emulation (in hw/android/goldfish/tty.c) to the
+internal GSM modem emulation (see telephony/modem_driver.c).
Essentially, a "charpipe" is a bi-directionnal communication pipe whose two
endpoints are both CS objects. You call "qemu_chr_open_pipe()" to create the
diff --git a/docs/CPU-EMULATION.TXT b/docs/CPU-EMULATION.TXT
index 076f4e0..fdea4bd 100644
--- a/docs/CPU-EMULATION.TXT
+++ b/docs/CPU-EMULATION.TXT
@@ -80,8 +80,8 @@
will be based on which offset of the I/O memory is read from/written to and
eventually with which value.
-You can have a look at hw/goldfish_tty.c that implements an emulated serial
-port for the Goldfish platform.
+You can have a look at hw/android/goldfish/tty.c that implements an
+emulated serial port for the Goldfish platform.
"Goldfish" is simply the name of the virtual Linux platform used to build
the Android-emulator-specific kernel image. The corresponding sources are