1 /* Copyright (C) 2010 The Android Open Source Project
2 **
3 ** This software is licensed under the terms of the GNU General Public
4 ** License version 2, as published by the Free Software Foundation, and
5 ** may be copied, distributed, and modified under those terms.
6 **
7 ** This program is distributed in the hope that it will be useful,
8 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
9 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10 ** GNU General Public License for more details.
11 */
12
13 /*
14 * This file contains declaration related to communication between emulator's
15 * UI and core through a console port.
16 */
17
18 #ifndef QEMU_ANDROID_CORE_CONNECTION_H
19 #define QEMU_ANDROID_CORE_CONNECTION_H
20
21 #include "android/sync-utils.h"
22
23 // Opaque CoreConnection structure.
24 typedef struct CoreConnection CoreConnection;
25
26 // Base console port
27 #define CORE_BASE_PORT 5554
28
29 // Maximum number of core porocesses running simultaneously on a machine.
30 #define MAX_CORE_PROCS 16
31
32 // Socket timeout in millisec (set to 5 seconds)
33 #define CORE_PORT_TIMEOUT_MS 5000
34
35 /* Opens core console socket.
36 * Param:
37 * sockaddr Socket address to the core console.
38 * Return:
39 * Sync socket descriptor on success, or -1 on failure, with errno appropriately
40 * set.
41 */
42 SyncSocket* core_connection_open_socket(SockAddress* sockaddr);
43
44 /* Creates descriptor for a console client.
45 * Param:
46 * console_socket Socket address for the console.
47 * Return:
48 * Allocated and initialized descriptor for the client on success, or NULL
49 * on failure.
50 */
51 CoreConnection* core_connection_create(SockAddress* console_socket);
52
53 /* Frees descriptor allocated with core_connection_create.
54 * Param:
55 * desc Descriptor to free. Note that this routine will simply free the memory
56 * used by the descriptor.
57 */
58 void core_connection_free(CoreConnection* desc);
59
60 /* Opens a socket handle to the console.
61 * Param:
62 * desc Console client descriptor. Note that if the descriptor has been already
63 * opened, this routine will simply return with success.
64 * Return:
65 * 0 on success, or -1 on failure with errno properly set. This routine will
66 * return in at most one second.
67 */
68 int core_connection_open(CoreConnection* desc);
69
70 /* Closes a socket handle to the console opened with core_connection_open.
71 * Param:
72 * desc Console client descriptor opened with core_connection_open.
73 */
74 void core_connection_close(CoreConnection* desc);
75
76 /* Synchronously writes to the console. See CORE_PORT_TIMEOUT_MS for the timeout
77 * value used to wait for the write operation to complete.
78 * Param:
79 * desc Console client descriptor opened with core_connection_open.
80 * buffer Buffer to write.
81 * to_write Number of bytes to write.
82 * written_bytes Upon success, contains number of bytes written. This parameter
83 * is optional, and can be NULL.
84 * Return:
85 * 0 on success, or -1 on failure.
86 */
87 int core_connection_write(CoreConnection* desc,
88 const void* buffer,
89 size_t to_write,
90 size_t* written_bytes);
91
92 /* Synchronously reads from the console. See CORE_PORT_TIMEOUT_MS for the
93 * timeout value used to wait for the read operation to complete.
94 * Param:
95 * desc Console client descriptor opened with core_connection_open.
96 * buffer Buffer to read data to.
97 * to_read Number of bytes to read.
98 * read_bytes Upon success, contains number of bytes that have been actually
99 * read. This parameter is optional, and can be NULL.
100 * Return:
101 * 0 on success, or -1 on failure.
102 */
103 int core_connection_read(CoreConnection* desc,
104 void* buffer,
105 size_t to_read,
106 size_t* read_bytes);
107
108 /* Switches opened console client to a given stream.
109 * Param:
110 * desc Console client descriptor opened with core_connection_open. Note
111 * that this descriptor should represent console itself. In other words,
112 * there must have been no previous calls to this routine for that
113 * descriptor.
114 * stream_name Name of the stream to switch to.
115 * handshake Address of a string to allocate for a handshake message on
116 * success, or an error message on failure. If upon return from this
117 * routine that string is not NULL, its buffer must be freed with 'free'.
118 * Return:
119 * 0 on success, or -1 on failure.
120 */
121 int core_connection_switch_stream(CoreConnection* desc,
122 const char* stream_name,
123 char** handshake);
124
125 /* Creates a console client, and switches it to a given stream.
126 * console_socket Socket address for the console.
127 * stream_name Name of the stream to switch to.
128 * handshake Address of a string to allocate for a handshake message on
129 * success, or an error message on failure. If upon return from this
130 * routine that string is not NULL, its buffer must be freed with 'free'.
131 * Return:
132 * Allocated and initialized descriptor for the switched client on success, or
133 * NULL on failure.
134 */
135 CoreConnection* core_connection_create_and_switch(SockAddress* console_socket,
136 const char* stream_name,
137 char** handshake);
138
139 /* Detaches opened console client from the console.
140 * By console protocol, writing "\r\n" string to the console will destroy the
141 * console client.
142 * Param:
143 * desc Console client descriptor opened with core_connection_open.
144 */
145 void core_connection_detach(CoreConnection* desc);
146
147 /* Gets socket descriptor associated with the core connection.
148 * Param:
149 * desc Console client descriptor opened with core_connection_open.
150 * Return
151 * Socket descriptor associated with the core connection.
152 */
153 int core_connection_get_socket(CoreConnection* desc);
154
155 /* Calculates timeout for transferring the given number of bytes via core
156 * connection.
157 * Return:
158 * Number of milliseconds during which the entire number of bytes is expected
159 * to be transferred via core connection.
160 */
161 static inline int
core_connection_get_timeout(size_t data_size)162 core_connection_get_timeout(size_t data_size)
163 {
164 // Min 2 seconds + 10 millisec for each transferring byte.
165 // TODO: Come up with a better arithmetics here.
166 return 2000 + data_size * 10;
167 }
168
169 #endif // QEMU_ANDROID_CORE_CONNECTION_H
170