diff options
Diffstat (limited to 'android/protocol/core-connection.h')
| -rw-r--r-- | android/protocol/core-connection.h | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/android/protocol/core-connection.h b/android/protocol/core-connection.h new file mode 100644 index 0000000..5701f8c --- /dev/null +++ b/android/protocol/core-connection.h @@ -0,0 +1,169 @@ +/* Copyright (C) 2010 The Android Open Source Project +** +** This software is licensed under the terms of the GNU General Public +** License version 2, as published by the Free Software Foundation, and +** may be copied, distributed, and modified under those terms. +** +** This program is distributed in the hope that it will be useful, +** but WITHOUT ANY WARRANTY; without even the implied warranty of +** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +** GNU General Public License for more details. +*/ + +/* + * This file contains declaration related to communication between emulator's + * UI and core through a console port. + */ + +#ifndef QEMU_ANDROID_CORE_CONNECTION_H +#define QEMU_ANDROID_CORE_CONNECTION_H + +#include "android/sync-utils.h" + +// Opaque CoreConnection structure. +typedef struct CoreConnection CoreConnection; + +// Base console port +#define CORE_BASE_PORT 5554 + +// Maximum number of core porocesses running simultaneously on a machine. +#define MAX_CORE_PROCS 16 + +// Socket timeout in millisec (set to 5 seconds) +#define CORE_PORT_TIMEOUT_MS 5000 + +/* Opens core console socket. + * Param: + * sockaddr Socket address to the core console. + * Return: + * Sync socket descriptor on success, or -1 on failure, with errno appropriately + * set. + */ +SyncSocket* core_connection_open_socket(SockAddress* sockaddr); + +/* Creates descriptor for a console client. + * Param: + * console_socket Socket address for the console. + * Return: + * Allocated and initialized descriptor for the client on success, or NULL + * on failure. + */ +CoreConnection* core_connection_create(SockAddress* console_socket); + +/* Frees descriptor allocated with core_connection_create. + * Param: + * desc Descriptor to free. Note that this routine will simply free the memory + * used by the descriptor. + */ +void core_connection_free(CoreConnection* desc); + +/* Opens a socket handle to the console. + * Param: + * desc Console client descriptor. Note that if the descriptor has been already + * opened, this routine will simply return with success. + * Return: + * 0 on success, or -1 on failure with errno properly set. This routine will + * return in at most one second. + */ +int core_connection_open(CoreConnection* desc); + +/* Closes a socket handle to the console opened with core_connection_open. + * Param: + * desc Console client descriptor opened with core_connection_open. + */ +void core_connection_close(CoreConnection* desc); + +/* Synchronously writes to the console. See CORE_PORT_TIMEOUT_MS for the timeout + * value used to wait for the write operation to complete. + * Param: + * desc Console client descriptor opened with core_connection_open. + * buffer Buffer to write. + * to_write Number of bytes to write. + * written_bytes Upon success, contains number of bytes written. This parameter + * is optional, and can be NULL. + * Return: + * 0 on success, or -1 on failure. + */ +int core_connection_write(CoreConnection* desc, + const void* buffer, + size_t to_write, + size_t* written_bytes); + +/* Synchronously reads from the console. See CORE_PORT_TIMEOUT_MS for the + * timeout value used to wait for the read operation to complete. + * Param: + * desc Console client descriptor opened with core_connection_open. + * buffer Buffer to read data to. + * to_read Number of bytes to read. + * read_bytes Upon success, contains number of bytes that have been actually + * read. This parameter is optional, and can be NULL. + * Return: + * 0 on success, or -1 on failure. + */ +int core_connection_read(CoreConnection* desc, + void* buffer, + size_t to_read, + size_t* read_bytes); + +/* Switches opened console client to a given stream. + * Param: + * desc Console client descriptor opened with core_connection_open. Note + * that this descriptor should represent console itself. In other words, + * there must have been no previous calls to this routine for that + * descriptor. + * stream_name Name of the stream to switch to. + * handshake Address of a string to allocate for a handshake message on + * success, or an error message on failure. If upon return from this + * routine that string is not NULL, its buffer must be freed with 'free'. + * Return: + * 0 on success, or -1 on failure. + */ +int core_connection_switch_stream(CoreConnection* desc, + const char* stream_name, + char** handshake); + +/* Creates a console client, and switches it to a given stream. + * console_socket Socket address for the console. + * stream_name Name of the stream to switch to. + * handshake Address of a string to allocate for a handshake message on + * success, or an error message on failure. If upon return from this + * routine that string is not NULL, its buffer must be freed with 'free'. + * Return: + * Allocated and initialized descriptor for the switched client on success, or + * NULL on failure. + */ +CoreConnection* core_connection_create_and_switch(SockAddress* console_socket, + const char* stream_name, + char** handshake); + +/* Detaches opened console client from the console. + * By console protocol, writing "\r\n" string to the console will destroy the + * console client. + * Param: + * desc Console client descriptor opened with core_connection_open. + */ +void core_connection_detach(CoreConnection* desc); + +/* Gets socket descriptor associated with the core connection. + * Param: + * desc Console client descriptor opened with core_connection_open. + * Return + * Socket descriptor associated with the core connection. + */ +int core_connection_get_socket(CoreConnection* desc); + +/* Calculates timeout for transferring the given number of bytes via core + * connection. + * Return: + * Number of milliseconds during which the entire number of bytes is expected + * to be transferred via core connection. + */ +static inline int +core_connection_get_timeout(size_t data_size) +{ + // Min 2 seconds + 10 millisec for each transferring byte. + // TODO: Come up with a better arithmetics here. + return 2000 + data_size * 10; +} + +#endif // QEMU_ANDROID_CORE_CONNECTION_H |