1 QEMU CHARACTER "DEVICES" MANAGEMENT 2 3 I. CharDriverState objects: 4 --------------------------- 5 6 One of the strangest abstraction in QEMU is the "CharDriverState" 7 (abbreviated here as "CS"). 8 9 The CS is essentially an object used to model a character stream that 10 can be connected to things like a host serial port, a host network socket, 11 an emulated device, etc... 12 13 What's really unusual is its interface though, which comes from the fact 14 that QEMU implements a big event loop with no blocking i/o allowed. You 15 can see "qemu-char.h" for the full interface, but here we will only describe 16 a 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_write( 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 134 II. CharDriverState users: 135 -------------------------- 136 137 As described above, a CharDriverState "user" is a piece of code that can write 138 to a CharDriverState (by calling qemu_chr_write() explicitely) and can also 139 read from it after registering can_read/read handlers for it through 140 qemu_chr_add_handlers(). 141 142 Typical 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 152 III. CharBuffer objects: 153 ------------------------ 154 155 The Android emulator provides an object called a CharBuffer which acts as 156 a CharDriverState object that implements a *write* buffer to send data to a 157 given CS object, called the endpoint. You can create one with: 158 159 #include "charpipe.h" 160 CharDriverState* qemu_chr_open_buffer( CharDriverState* endpoint ); 161 162 This function returns a new CS object that will buffer in the heap any data 163 that is sent to it, but cannot be sent to the endpoint yet. On each event loop 164 iteration, the CharBuffer will try to send data to the endpoint until it 165 doesn't have any data left. 166 167 This can be useful to simplify certain CS users who don't want to maintain 168 their own emit buffer. Note that writing to a CharBuffer always succeeds. 169 170 Note also that calling qemu_chr_add_handler() on the CharBuffer will do the 171 same on the endpoint. Any endpoint-initiated calls to can_read()/read() 172 callbacks are passed directly to your handler functions. 173 174 175 IV. CharPipe objects: 176 --------------------- 177 178 The Android emulator also provides a convenient abstraction called a "charpipe" 179 used to connect two CharDriverState users together. For example, this is used 180 to connect a serial port emulation (in hw/goldfish_tty.c) to the internal 181 GSM modem emulation (see telephony/modem_driver.c). 182 183 Essentially, a "charpipe" is a bi-directionnal communication pipe whose two 184 endpoints are both CS objects. You call "qemu_chr_open_pipe()" to create the 185 pipe, 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 191 When you write to one end of the pipe (with qemu_chr_write()), the charpipe will 192 try to write as much data as possible to the other end. Any remaining data is stored 193 in a heap-allocated buffer. 194 195 The charpipe will try to re-send the buffered data on the next event loop 196 iteration by calling the can_read/read functions of the corresponding user, 197 if there is one. 198 199 Note that there is no limit on the amount of data buffered in a charpipe, 200 and writing to it is never blocking. This simplifies CharDriverState 201 users who don't need to worry about buffering issues. 202
