/*
* Copyright (c) 2025 Jiri Svoboda
* Copyright (c) 2012 Jan Vesely
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* - The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/** @addtogroup libhound
* @addtogroup audio
* @{
*/
/** @file
* Common USB functions.
*/
#include <adt/list.h>
#include <errno.h>
#include <loc.h>
#include <macros.h>
#include <str.h>
#include <stdbool.h>
#include <stdlib.h>
#include <stdio.h>
#include <types/common.h>
#include "protocol.h"
#include "client.h"
#include "server.h"
enum ipc_methods {
/** Create new context representation on the server side */
IPC_M_HOUND_CONTEXT_REGISTER = IPC_FIRST_USER_METHOD,
/** Release existing context representation on the server side */
IPC_M_HOUND_CONTEXT_UNREGISTER,
/** Request list of objects */
IPC_M_HOUND_GET_LIST,
/** Create new connection */
IPC_M_HOUND_CONNECT,
/** Destroy connection */
IPC_M_HOUND_DISCONNECT,
/** Switch IPC pipe to stream mode */
IPC_M_HOUND_STREAM_ENTER,
/** Switch IPC pipe back to general mode */
IPC_M_HOUND_STREAM_EXIT,
/** Wait until there is no data in the stream */
IPC_M_HOUND_STREAM_DRAIN,
};
/** PCM format conversion helper structure */
typedef union {
struct {
uint16_t rate;
uint8_t channels;
uint8_t format;
} __attribute__((packed)) f;
sysarg_t arg;
} format_convert_t;
/*
* CLIENT
*/
/** Well defined service name */
const char *HOUND_SERVICE = "audio/hound";
/** Server object */
static loc_srv_t *hound_srv;
/**
* Start a new audio session.
* @param service Named service typically 'HOUND_SERVICE' constant.
* @return Valid session on success, NULL on failure.
*/
hound_sess_t *hound_service_connect(const char *service)
{
service_id_t id = 0;
const errno_t ret =
loc_service_get_id(service, &id, IPC_FLAG_BLOCKING);
if (ret != EOK)
return NULL;
return loc_service_connect(id, INTERFACE_HOUND, IPC_FLAG_BLOCKING);
}
/**
* End an existing audio session.
* @param sess The session.
*/
void hound_service_disconnect(hound_sess_t *sess)
{
if (sess)
async_hangup(sess);
}
/**
* Register a named application context to the audio server.
* @param sess Valid audio session.
* @param name Valid string identifier
* @param record True if the application context wishes to receive data.
*
* @param[out] id Return context ID.
*
* @return EOK on success, Error code on failure.
*/
errno_t hound_service_register_context(hound_sess_t *sess,
const char *name, bool record, hound_context_id_t *id)
{
assert(sess);
assert(name);
ipc_call_t call;
async_exch_t *exch = async_exchange_begin(sess);
aid_t mid =
async_send_1(exch, IPC_M_HOUND_CONTEXT_REGISTER, record, &call);
errno_t ret = mid ? EOK : EPARTY;
if (ret == EOK)
ret = async_data_write_start(exch, name, str_size(name));
else
async_forget(mid);
if (ret == EOK)
async_wait_for(mid, &ret);
async_exchange_end(exch);
if (ret == EOK) {
*id = (hound_context_id_t) ipc_get_arg1(&call);
}
return ret;
}
/**
* Remove application context from the server's list.
* @param sess Valid audio session.
* @param id Valid context id.
* @return Error code.
*/
errno_t hound_service_unregister_context(hound_sess_t *sess,
hound_context_id_t id)
{
assert(sess);
async_exch_t *exch = async_exchange_begin(sess);
const errno_t ret = async_req_1_0(exch, IPC_M_HOUND_CONTEXT_UNREGISTER,
cap_handle_raw(id));
async_exchange_end(exch);
return ret;
}
/**
* Retrieve a list of server side actors.
* @param[in] sess Valid audio session.
* @param[out] ids list of string identifiers.
* @param[out] count Number of elements int the @p ids list.
* @param[in] flags list requirements.
* @param[in] connection name of target actor. Used only if the list should
* contain connected actors.
* @retval Error code.
*/
errno_t hound_service_get_list(hound_sess_t *sess, char ***ids, size_t *count,
int flags, const char *connection)
{
assert(sess);
assert(ids);
assert(count);
if (connection && !(flags & HOUND_CONNECTED))
return EINVAL;
async_exch_t *exch = async_exchange_begin(sess);
if (!exch)
return ENOMEM;
ipc_call_t res_call;
aid_t mid = async_send_3(exch, IPC_M_HOUND_GET_LIST, flags, *count,
connection != NULL, &res_call);
errno_t ret = EOK;
if (mid && connection)
ret = async_data_write_start(exch, connection,
str_size(connection));
if (ret == EOK)
async_wait_for(mid, &ret);
if (ret != EOK) {
async_exchange_end(exch);
return ret;
}
unsigned name_count = ipc_get_arg1(&res_call);
/* Start receiving names */
char **names = NULL;
if (name_count) {
size_t *sizes = calloc(name_count, sizeof(size_t));
names = calloc(name_count, sizeof(char *));
if (!names || !sizes)
ret = ENOMEM;
if (ret == EOK)
ret = async_data_read_start(exch, sizes,
name_count * sizeof(size_t));
for (unsigned i = 0; i < name_count && ret == EOK; ++i) {
char *name = malloc(sizes[i] + 1);
if (name) {
memset(name, 0, sizes[i] + 1);
ret = async_data_read_start(exch, name, sizes[i]);
names[i] = name;
} else {
ret = ENOMEM;
}
}
free(sizes);
}
async_exchange_end(exch);
if (ret != EOK) {
for (unsigned i = 0; i < name_count; ++i)
free(names[i]);
free(names);
} else {
*ids = names;
*count = name_count;
}
return ret;
}
/**
* Create a new connection between a source and a sink.
* @param sess Valid audio session.
* @param source Source name, valid string.
* @param sink Sink name, valid string.
* @return Error code.
*/
errno_t hound_service_connect_source_sink(hound_sess_t *sess, const char *source,
const char *sink)
{
assert(sess);
assert(source);
assert(sink);
async_exch_t *exch = async_exchange_begin(sess);
if (!exch)
return ENOMEM;
ipc_call_t call;
aid_t id = async_send_0(exch, IPC_M_HOUND_CONNECT, &call);
errno_t ret = id ? EOK : EPARTY;
if (ret == EOK)
ret = async_data_write_start(exch, source, str_size(source));
if (ret == EOK)
ret = async_data_write_start(exch, sink, str_size(sink));
async_wait_for(id, &ret);
async_exchange_end(exch);
return ret;
}
/**
* Destroy an existing connection between a source and a sink.
* @param sess Valid audio session.
* @param source Source name, valid string.
* @param sink Sink name, valid string.
* @return Error code.
*/
errno_t hound_service_disconnect_source_sink(hound_sess_t *sess, const char *source,
const char *sink)
{
assert(sess);
async_exch_t *exch = async_exchange_begin(sess);
if (!exch)
return ENOMEM;
ipc_call_t call;
aid_t id = async_send_0(exch, IPC_M_HOUND_DISCONNECT, &call);
errno_t ret = id ? EOK : EPARTY;
if (ret == EOK)
ret = async_data_write_start(exch, source, str_size(source));
if (ret == EOK)
ret = async_data_write_start(exch, sink, str_size(sink));
async_wait_for(id, &ret);
async_exchange_end(exch);
return ENOTSUP;
}
/**
* Switch IPC exchange to a STREAM mode.
* @param exch IPC exchange.
* @param id context id this stream should be associated with
* @param flags set stream properties
* @param format format of the new stream.
* @param bsize size of the server side buffer.
* @return Error code.
*/
errno_t hound_service_stream_enter(async_exch_t *exch, hound_context_id_t id,
int flags, pcm_format_t format, size_t bsize)
{
const format_convert_t c = {
.f = {
.channels = format.channels,
.rate = format.sampling_rate / 100,
.format = format.sample_format,
}
};
return async_req_4_0(exch, IPC_M_HOUND_STREAM_ENTER, cap_handle_raw(id),
flags, c.arg, bsize);
}
/**
* Destroy existing stream and return IPC exchange to general mode.
* @param exch IPC exchange.
* @return Error code.
*/
errno_t hound_service_stream_exit(async_exch_t *exch)
{
return async_req_0_0(exch, IPC_M_HOUND_STREAM_EXIT);
}
/**
* Wait until the server side buffer is empty.
* @param exch IPC exchange.
* @return Error code.
*/
errno_t hound_service_stream_drain(async_exch_t *exch)
{
return async_req_0_0(exch, IPC_M_HOUND_STREAM_DRAIN);
}
/**
* Write audio data to a stream.
* @param exch IPC exchange in STREAM MODE.
* @param data Audio data buffer.
* @size size of the buffer
* @return Error code.
*/
errno_t hound_service_stream_write(async_exch_t *exch, const void *data, size_t size)
{
return async_data_write_start(exch, data, size);
}
/**
* Read data from a stream.
* @param exch IPC exchange in STREAM MODE.
* @param data Audio data buffer.
* @size size of the buffer
* @return Error code.
*/
errno_t hound_service_stream_read(async_exch_t *exch, void *data, size_t size)
{
return async_data_read_start(exch, data, size);
}
/*
* SERVER
*/
static void hound_server_read_data(void *stream);
static void hound_server_write_data(void *stream);
static const hound_server_iface_t *server_iface;
/**
* Set hound server interface implementation.
* @param iface Initialized Hound server interface.
*/
void hound_service_set_server_iface(const hound_server_iface_t *iface)
{
server_iface = iface;
}
/** Server side implementation of the hound protocol. IPC connection handler.
*
* @param icall Pointer to initial call structure.
* @param arg (unused)
*
*/
void hound_connection_handler(ipc_call_t *icall, void *arg)
{
hound_context_id_t context;
errno_t ret;
int flags;
void *source;
void *sink;
/* Accept connection if there is a valid iface */
if (server_iface) {
async_accept_0(icall);
} else {
async_answer_0(icall, ENOTSUP);
return;
}
while (true) {
ipc_call_t call;
async_get_call(&call);
switch (ipc_get_imethod(&call)) {
case IPC_M_HOUND_CONTEXT_REGISTER:
/* check interface functions */
if (!server_iface || !server_iface->add_context) {
async_answer_0(&call, ENOTSUP);
break;
}
bool record = ipc_get_arg1(&call);
void *name;
/* Get context name */
ret = async_data_write_accept(&name, true, 0, 0, 0, 0);
if (ret != EOK) {
async_answer_0(&call, ret);
break;
}
context = 0;
ret = server_iface->add_context(server_iface->server,
&context, name, record);
/** new context should create a copy */
free(name);
if (ret != EOK) {
async_answer_0(&call, ret);
} else {
async_answer_1(&call, EOK, cap_handle_raw(context));
}
break;
case IPC_M_HOUND_CONTEXT_UNREGISTER:
/* check interface functions */
if (!server_iface || !server_iface->rem_context) {
async_answer_0(&call, ENOTSUP);
break;
}
/* get id, 1st param */
context = (hound_context_id_t) ipc_get_arg1(&call);
ret = server_iface->rem_context(server_iface->server,
context);
async_answer_0(&call, ret);
break;
case IPC_M_HOUND_GET_LIST:
/* check interface functions */
if (!server_iface || !server_iface->get_list) {
async_answer_0(&call, ENOTSUP);
break;
}
char **list = NULL;
flags = ipc_get_arg1(&call);
size_t count = ipc_get_arg2(&call);
const bool conn = ipc_get_arg3(&call);
char *conn_name = NULL;
ret = EOK;
/* get connected actor name if provided */
if (conn)
ret = async_data_write_accept(
(void **)&conn_name, true, 0, 0, 0, 0);
if (ret == EOK)
ret = server_iface->get_list(
server_iface->server, &list, &count,
conn_name, flags);
free(conn_name);
/* Alloc string sizes array */
size_t *sizes = NULL;
if (count)
sizes = calloc(count, sizeof(size_t));
if (count && !sizes)
ret = ENOMEM;
async_answer_1(&call, ret, count);
/* We are done */
if (count == 0 || ret != EOK)
break;
/* Prepare sizes table */
for (unsigned i = 0; i < count; ++i)
sizes[i] = str_size(list[i]);
/* Send sizes table */
ipc_call_t id;
if (async_data_read_receive(&id, NULL)) {
ret = async_data_read_finalize(&id, sizes,
count * sizeof(size_t));
}
free(sizes);
/* Proceed to send names */
for (unsigned i = 0; i < count; ++i) {
size_t size = str_size(list[i]);
ipc_call_t id;
if (ret == EOK &&
async_data_read_receive(&id, NULL)) {
ret = async_data_read_finalize(&id,
list[i], size);
}
free(list[i]);
}
free(list);
break;
case IPC_M_HOUND_CONNECT:
/* check interface functions */
if (!server_iface || !server_iface->connect) {
async_answer_0(&call, ENOTSUP);
break;
}
source = NULL;
sink = NULL;
/* read source name */
ret = async_data_write_accept(&source, true, 0, 0, 0,
0);
/* read sink name */
if (ret == EOK)
ret = async_data_write_accept(&sink,
true, 0, 0, 0, 0);
if (ret == EOK)
ret = server_iface->connect(
server_iface->server, source, sink);
free(source);
free(sink);
async_answer_0(&call, ret);
break;
case IPC_M_HOUND_DISCONNECT:
/* check interface functions */
if (!server_iface || !server_iface->disconnect) {
async_answer_0(&call, ENOTSUP);
break;
}
source = NULL;
sink = NULL;
/* read source name */
ret = async_data_write_accept(&source, true, 0, 0, 0,
0);
/* read sink name */
if (ret == EOK)
ret = async_data_write_accept(&sink,
true, 0, 0, 0, 0);
if (ret == EOK)
ret = server_iface->connect(
server_iface->server, source, sink);
free(source);
free(sink);
async_answer_0(&call, ret);
break;
case IPC_M_HOUND_STREAM_ENTER:
/* check interface functions */
if (!server_iface || !server_iface->is_record_context ||
!server_iface->add_stream ||
!server_iface->rem_stream) {
async_answer_0(&call, ENOTSUP);
break;
}
/* get parameters */
context = (hound_context_id_t) ipc_get_arg1(&call);
flags = ipc_get_arg2(&call);
const format_convert_t c = { .arg = ipc_get_arg3(&call) };
const pcm_format_t f = {
.sampling_rate = c.f.rate * 100,
.channels = c.f.channels,
.sample_format = c.f.format,
};
size_t bsize = ipc_get_arg4(&call);
void *stream;
ret = server_iface->add_stream(server_iface->server,
context, flags, f, bsize, &stream);
if (ret != EOK) {
async_answer_0(&call, ret);
break;
}
const bool rec = server_iface->is_record_context(
server_iface->server, context);
if (rec) {
if (server_iface->stream_data_read) {
async_answer_0(&call, EOK);
/* start answering read calls */
hound_server_write_data(stream);
server_iface->rem_stream(
server_iface->server, stream);
} else {
async_answer_0(&call, ENOTSUP);
}
} else {
if (server_iface->stream_data_write) {
async_answer_0(&call, EOK);
/* accept write calls */
hound_server_read_data(stream);
server_iface->rem_stream(
server_iface->server, stream);
} else {
async_answer_0(&call, ENOTSUP);
}
}
break;
case IPC_M_HOUND_STREAM_EXIT:
case IPC_M_HOUND_STREAM_DRAIN:
/* Stream exit/drain is only allowed in stream context */
async_answer_0(&call, EINVAL);
break;
default:
/*
* In case we called async_get_call() after we had
* already received IPC_M_PHONE_HUNGUP deeper in the
* protocol handling, the capability handle will be
* invalid, so act carefully here.
*/
if (call.cap_handle != CAP_NIL)
async_answer_0(&call, ENOTSUP);
return;
}
}
}
/**
* Read data and push it to the stream.
* @param stream target stream, will push data there.
*/
static void hound_server_read_data(void *stream)
{
ipc_call_t call;
size_t size = 0;
errno_t ret_answer = EOK;
/* accept data write or drain */
while (async_data_write_receive(&call, &size) ||
(ipc_get_imethod(&call) == IPC_M_HOUND_STREAM_DRAIN)) {
/* check drain first */
if (ipc_get_imethod(&call) == IPC_M_HOUND_STREAM_DRAIN) {
errno_t ret = ENOTSUP;
if (server_iface->drain_stream)
ret = server_iface->drain_stream(stream);
async_answer_0(&call, ret);
continue;
}
/* there was an error last time */
if (ret_answer != EOK) {
async_answer_0(&call, ret_answer);
continue;
}
char *buffer = malloc(size);
if (!buffer) {
async_answer_0(&call, ENOMEM);
continue;
}
const errno_t ret = async_data_write_finalize(&call, buffer, size);
if (ret == EOK) {
/* push data to stream */
ret_answer = server_iface->stream_data_write(
stream, buffer, size);
}
}
const errno_t ret = ipc_get_imethod(&call) == IPC_M_HOUND_STREAM_EXIT ?
EOK : EINVAL;
async_answer_0(&call, ret);
}
/**
* Accept reads and pull data from the stream.
* @param stream target stream, will pull data from there.
*/
static void hound_server_write_data(void *stream)
{
ipc_call_t call;
size_t size = 0;
errno_t ret_answer = EOK;
/* accept data read and drain */
while (async_data_read_receive(&call, &size) ||
(ipc_get_imethod(&call) == IPC_M_HOUND_STREAM_DRAIN)) {
/* drain does not make much sense but it is allowed */
if (ipc_get_imethod(&call) == IPC_M_HOUND_STREAM_DRAIN) {
errno_t ret = ENOTSUP;
if (server_iface->drain_stream)
ret = server_iface->drain_stream(stream);
async_answer_0(&call, ret);
continue;
}
/* there was an error last time */
if (ret_answer != EOK) {
async_answer_0(&call, ret_answer);
continue;
}
char *buffer = malloc(size);
if (!buffer) {
async_answer_0(&call, ENOMEM);
continue;
}
errno_t ret = server_iface->stream_data_read(stream, buffer, size);
if (ret == EOK) {
ret_answer =
async_data_read_finalize(&call, buffer, size);
}
}
const errno_t ret = ipc_get_imethod(&call) == IPC_M_HOUND_STREAM_EXIT ?
EOK : EINVAL;
async_answer_0(&call, ret);
}
/*
* SERVER SIDE
*/
/**
* Register new hound service to the location service.
* @param[in] name server name
* @param[out] id assigned service id.
* @return Error code.
*/
errno_t hound_server_register(const char *name, service_id_t *id)
{
errno_t rc;
if (!name || !id)
return EINVAL;
if (hound_srv != NULL)
return EBUSY;
rc = loc_server_register(name, &hound_srv);
if (rc != EOK)
return rc;
rc = loc_service_register(hound_srv, HOUND_SERVICE,
fallback_port_id, id);
if (rc != EOK) {
loc_server_unregister(hound_srv);
return rc;
}
return EOK;
}
/**
* Unregister server from the location service.
* @param id previously assigned service id.
*/
void hound_server_unregister(service_id_t id)
{
loc_service_unregister(hound_srv, id);
loc_server_unregister(hound_srv);
}
/**
* Set callback on device category change event.
* @param cb Callback function.
* @return Error code.
*/
errno_t hound_server_set_device_change_callback(dev_change_callback_t cb,
void *arg)
{
return loc_register_cat_change_cb(cb, arg);
}
/**
* Walk through all device in the audio-pcm category.
* @param callback Function to call on every device.
* @return Error code.
*/
errno_t hound_server_devices_iterate(device_callback_t callback)
{
if (!callback)
return EINVAL;
static bool resolved = false;
static category_id_t cat_id = 0;
if (!resolved) {
const errno_t ret = loc_category_get_id("audio-pcm", &cat_id,
IPC_FLAG_BLOCKING);
if (ret != EOK)
return ret;
resolved = true;
}
service_id_t *svcs = NULL;
size_t count = 0;
const errno_t ret = loc_category_get_svcs(cat_id, &svcs, &count);
if (ret != EOK)
return ret;
for (unsigned i = 0; i < count; ++i) {
char *name = NULL;
loc_service_get_name(svcs[i], &name);
callback(svcs[i], name);
free(name);
}
free(svcs);
return EOK;
}
/**
* @}
*/