1QEMU CHARACTER "DEVICES" MANAGEMENT 2 3I. CharDriverState objects: 4--------------------------- 5 6One of the strangest abstraction in QEMU is the "CharDriverState" 7(abbreviated here as "CS"). 8 9The CS is essentially an object used to model a character stream that 10can be connected to things like a host serial port, a host network socket, 11an emulated device, etc... 12 13What's really unusual is its interface though, which comes from the fact 14that QEMU implements a big event loop with no blocking i/o allowed. You 15can see "qemu-char.h" for the full interface, but here we will only describe 16a few important functions: 17 18 - qemu_chr_write() is used to try to write data into a CS object. Note that 19 success is not guaranteed: the function returns the number of bytes that 20 were really written (which can be 0) and the caller must deal with it. 21 This is very similar to writing to a non-blocking BSD socket on Unix. 22 23 int qemu_chr_read( CharDriverState* cs, 24 const uint8_t* data, 25 int datalen ); 26 27 This function may return -1 in case of error, but this depends entirely 28 on the underlying implementation (some of them will just return 0 instead). 29 In practice, this means it's not possible to reliably differentiate between 30 a "connection reset by peer" and an "operation in progress" :-( 31 32 There is no way to know in advance how many bytes a given CharDriverState 33 can accept, nor to be notified when its underlying implementation is ready 34 to accept data again. 35 36 37 - qemu_chr_add_handler() is used to add "read" and "event" handlers 38 to a CS object. We will ignore "events" here and focus on the 39 "read" part. 40 41 Thing is, you cannot directly read from a CS object. Instead, you provide 42 two functions that will be called whenever the object has something for 43 you: 44 45 - a 'can_read' function that shall return the number of bytes 46 that you are ready to accept from the CharDriverState. Its 47 interface is: 48 49 typedef int IOCanRWHandler (void* opaque); 50 51 - a 'read' function that will send you bytes from the CharDriverState 52 53 typedef void IOReadHandler (void* opaque, 54 const uint8_t* data, 55 int datalen); 56 57 normally, the value of 'datalen' cannot be larger than the result 58 of a previous 'can_read' call. 59 60 For both callbacks, 'opaque' is a value that you pass to the function 61 qemu_chr_add_handler() which signature is: 62 63 void qemu_chr_add_handlers(CharDriverState *s, 64 IOCanRWHandler *fd_can_read, 65 IOReadHandler *fd_read, 66 IOEventHandler *fd_event, 67 void *opaque); 68 69 - qemu_chr_open() is used to create a new CharDriverState object from a 70 descriptive string, its interface is: 71 72 CharDriverState* qemu_chr_open(const char* filename); 73 74 there are various formats for acceptable 'filenames', and they correspond 75 to the parameters of the '-serial' QEMU option described here: 76 77 http://www.nongnu.org/qemu/qemu-doc.html#SEC10 78 79 For example: 80 81 "/dev/<file>" (Linux and OS X only): 82 connect to a host character device file (e.g. /dev/ttyS0) 83 84 "file:<filename>": 85 Write output to a given file (write only) 86 87 "stdio": 88 Standard input/output 89 90 "udp:[<remote_host>]:<remote_port>[@[<src_ip>]:<src_port>]": 91 Connect to a UDP socket for both read/write. 92 93 "tcp:[<host>]:<port>[,server][,nowait][,nodelay]" 94 Connect to a TCP socket either as a client or a server. 95 96 The 'nowait' option is used to avoid waiting for a client 97 connection. 98 99 The 'nodelay' is used to disable the TCP Nagle algorithm to 100 improve throughput. 101 102 For Android, a few special names have been added to the internal 103 implementation and redirect to program functions: 104 105 "android-kmsg": 106 A CharDriverState that is used to receive kernel log messages 107 from the emulated /dev/ttyS0 serial port. 108 109 "android-qemud": 110 A CharDriverState that is used to exchange messages between the 111 emulator program and the "qemud" multiplexing daemon that runs in 112 the emulated system. 113 114 The "qemud" daemon is used to allow one or more clients in the 115 system to connect to various services running in the emulator 116 program. This is mainly used to bypass the kernel in order to 117 implement certain features with ease. 118 119 (see docs/ANDROID-QEMUD.TXT for details) 120 121 "android-gsm": 122 A CharDriverState that is used to connect the emulated system to 123 a host modem device with the -radio <device> option. Otherwise, 124 the system uses qemud to connect to the emulator's internal modem 125 emulation. 126 127 "android-gps": 128 A CharDriverState that is used to connect the emulated system to a 129 host GPS device with the -gps <device> option. Otherwise the 130 system uses qemud to connect to the emulator's internal GPS 131 emulation. 132 133 134II. CharDriverState users: 135-------------------------- 136 137As described above, a CharDriverState "user" is a piece of code that can write 138to a CharDriverState (by calling qemu_chr_write() explicitely) and can also 139read from it after registering can_read/read handlers for it through 140qemu_chr_add_handlers(). 141 142Typical examples are the following: 143 144 - The hardware serial port emulation (e.g. hw/goldfish_tty.c) will read data 145 from the kernel then send it to a CS. It also uses a small buffer that is 146 used to read data from the CS and send it back to the kernel. 147 148 - The Android emulated modem also uses a CS to talk with its client, 149 which will in most cases be an emulated serial port. 150 151 152III. CharBuffer objects: 153------------------------ 154 155The Android emulator provides an object called a CharBuffer which acts as 156a CharDriverState object that implements a *write* buffer to send data to a 157given CS object, called the endpoint. You can create one with: 158 159 #include "charpipe.h" 160 CharDriverState* qemu_chr_open_buffer( CharDriverState* endpoint ); 161 162This function returns a new CS object that will buffer in the heap any data 163that is sent to it, but cannot be sent to the endpoint yet. On each event loop 164iteration, the CharBuffer will try to send data to the endpoint until it 165doesn't have any data left. 166 167This can be useful to simplify certain CS users who don't want to maintain 168their own emit buffer. Note that writing to a CharBuffer always succeeds. 169 170Note also that calling qemu_chr_add_handler() on the CharBuffer will do the 171same on the endpoint. Any endpoint-initiated calls to can_read()/read() 172callbacks are passed directly to your handler functions. 173 174 175IV. CharPipe objects: 176--------------------- 177 178The Android emulator also provides a convenient abstraction called a "charpipe" 179used to connect two CharDriverState users together. For example, this is used 180to connect a serial port emulation (in hw/goldfish_tty.c) to the internal 181GSM modem emulation (see telephony/modem_driver.c). 182 183Essentially, a "charpipe" is a bi-directionnal communication pipe whose two 184endpoints are both CS objects. You call "qemu_chr_open_pipe()" to create the 185pipe, and this function will return the two endpoints to you: 186 187 #include "charpipe.h" 188 int qemu_chr_open_pipe(CharDriverState* *pfirst, 189 CharDriverState* *psecond); 190 191When you write to one end of the pipe (with qemu_chr_write()), the charpipe will 192try to write as much data as possible to the other end. Any remaining data is stored 193in a heap-allocated buffer. 194 195The charpipe will try to re-send the buffered data on the next event loop 196iteration by calling the can_read/read functions of the corresponding user, 197if there is one. 198 199Note that there is no limit on the amount of data buffered in a charpipe, 200and writing to it is never blocking. This simplifies CharDriverState 201users who don't need to worry about buffering issues. 202