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.
24typedef 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 */
42SyncSocket* 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 */
51CoreConnection* 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 */
58void 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 */
68int 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 */
74void 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 */
87int 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 */
103int 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 */
121int 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 */
135CoreConnection* 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 */
145void 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 */
153int 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 */
161static inline int
162core_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