| QEMU CHARACTER "DEVICES" MANAGEMENT |
| |
| I. CharDriverState objects: |
| --------------------------- |
| |
| One of the strangest abstraction in QEMU is the "CharDriverState" |
| (abbreviated here as "CS"). |
| |
| The CS is essentially an object used to model a character stream that |
| can be connected to things like a host serial port, a host network socket, |
| an emulated device, etc... |
| |
| What's really unusual is its interface though, which comes from the fact |
| that QEMU implements a big event loop with no blocking i/o allowed. You |
| can see "qemu-char.h" for the full interface, but here we will only describe |
| a few important functions: |
| |
| - qemu_chr_write() is used to try to write data into a CS object. Note that |
| success is not guaranteed: the function returns the number of bytes that |
| were really written (which can be 0) and the caller must deal with it. |
| This is very similar to writing to a non-blocking BSD socket on Unix. |
| |
| int qemu_chr_write( CharDriverState* cs, |
| const uint8_t* data, |
| int datalen ); |
| |
| This function may return -1 in case of error, but this depends entirely |
| on the underlying implementation (some of them will just return 0 instead). |
| In practice, this means it's not possible to reliably differentiate between |
| a "connection reset by peer" and an "operation in progress" :-( |
| |
| There is no way to know in advance how many bytes a given CharDriverState |
| can accept, nor to be notified when its underlying implementation is ready |
| to accept data again. |
| |
| |
| - qemu_chr_add_handler() is used to add "read" and "event" handlers |
| to a CS object. We will ignore "events" here and focus on the |
| "read" part. |
| |
| Thing is, you cannot directly read from a CS object. Instead, you provide |
| two functions that will be called whenever the object has something for |
| you: |
| |
| - a 'can_read' function that shall return the number of bytes |
| that you are ready to accept from the CharDriverState. Its |
| interface is: |
| |
| typedef int IOCanRWHandler (void* opaque); |
| |
| - a 'read' function that will send you bytes from the CharDriverState |
| |
| typedef void IOReadHandler (void* opaque, |
| const uint8_t* data, |
| int datalen); |
| |
| normally, the value of 'datalen' cannot be larger than the result |
| of a previous 'can_read' call. |
| |
| For both callbacks, 'opaque' is a value that you pass to the function |
| qemu_chr_add_handler() which signature is: |
| |
| void qemu_chr_add_handlers(CharDriverState *s, |
| IOCanRWHandler *fd_can_read, |
| IOReadHandler *fd_read, |
| IOEventHandler *fd_event, |
| void *opaque); |
| |
| - qemu_chr_open() is used to create a new CharDriverState object from a |
| descriptive string, its interface is: |
| |
| CharDriverState* qemu_chr_open(const char* filename); |
| |
| there are various formats for acceptable 'filenames', and they correspond |
| to the parameters of the '-serial' QEMU option described here: |
| |
| http://www.nongnu.org/qemu/qemu-doc.html#SEC10 |
| |
| For example: |
| |
| "/dev/<file>" (Linux and OS X only): |
| connect to a host character device file (e.g. /dev/ttyS0) |
| |
| "file:<filename>": |
| Write output to a given file (write only) |
| |
| "stdio": |
| Standard input/output |
| |
| "udp:[<remote_host>]:<remote_port>[@[<src_ip>]:<src_port>]": |
| Connect to a UDP socket for both read/write. |
| |
| "tcp:[<host>]:<port>[,server][,nowait][,nodelay]" |
| Connect to a TCP socket either as a client or a server. |
| |
| The 'nowait' option is used to avoid waiting for a client |
| connection. |
| |
| The 'nodelay' is used to disable the TCP Nagle algorithm to |
| improve throughput. |
| |
| For Android, a few special names have been added to the internal |
| implementation and redirect to program functions: |
| |
| "android-kmsg": |
| A CharDriverState that is used to receive kernel log messages |
| from the emulated /dev/ttyS0 serial port. |
| |
| "android-qemud": |
| A CharDriverState that is used to exchange messages between the |
| emulator program and the "qemud" multiplexing daemon that runs in |
| the emulated system. |
| |
| The "qemud" daemon is used to allow one or more clients in the |
| system to connect to various services running in the emulator |
| program. This is mainly used to bypass the kernel in order to |
| implement certain features with ease. |
| |
| (see docs/ANDROID-QEMUD.TXT for details) |
| |
| "android-gsm": |
| A CharDriverState that is used to connect the emulated system to |
| a host modem device with the -radio <device> option. Otherwise, |
| the system uses qemud to connect to the emulator's internal modem |
| emulation. |
| |
| "android-gps": |
| A CharDriverState that is used to connect the emulated system to a |
| host GPS device with the -gps <device> option. Otherwise the |
| system uses qemud to connect to the emulator's internal GPS |
| emulation. |
| |
| |
| II. CharDriverState users: |
| -------------------------- |
| |
| As described above, a CharDriverState "user" is a piece of code that can write |
| to a CharDriverState (by calling qemu_chr_write() explicitely) and can also |
| read from it after registering can_read/read handlers for it through |
| qemu_chr_add_handlers(). |
| |
| 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 Android emulated modem also uses a CS to talk with its client, |
| which will in most cases be an emulated serial port. |
| |
| |
| III. CharBuffer objects: |
| ------------------------ |
| |
| The Android emulator provides an object called a CharBuffer which acts as |
| a CharDriverState object that implements a *write* buffer to send data to a |
| given CS object, called the endpoint. You can create one with: |
| |
| #include "charpipe.h" |
| CharDriverState* qemu_chr_open_buffer( CharDriverState* endpoint ); |
| |
| This function returns a new CS object that will buffer in the heap any data |
| that is sent to it, but cannot be sent to the endpoint yet. On each event loop |
| iteration, the CharBuffer will try to send data to the endpoint until it |
| doesn't have any data left. |
| |
| This can be useful to simplify certain CS users who don't want to maintain |
| their own emit buffer. Note that writing to a CharBuffer always succeeds. |
| |
| Note also that calling qemu_chr_add_handler() on the CharBuffer will do the |
| same on the endpoint. Any endpoint-initiated calls to can_read()/read() |
| callbacks are passed directly to your handler functions. |
| |
| |
| IV. CharPipe objects: |
| --------------------- |
| |
| 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). |
| |
| 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 |
| pipe, and this function will return the two endpoints to you: |
| |
| #include "charpipe.h" |
| int qemu_chr_open_pipe(CharDriverState* *pfirst, |
| CharDriverState* *psecond); |
| |
| When you write to one end of the pipe (with qemu_chr_write()), the charpipe will |
| try to write as much data as possible to the other end. Any remaining data is stored |
| in a heap-allocated buffer. |
| |
| The charpipe will try to re-send the buffered data on the next event loop |
| iteration by calling the can_read/read functions of the corresponding user, |
| if there is one. |
| |
| Note that there is no limit on the amount of data buffered in a charpipe, |
| and writing to it is never blocking. This simplifies CharDriverState |
| users who don't need to worry about buffering issues. |
