[libcamera-devel,1/2] libcamera: ipc: unix: Add a IPC mechanism based on Unix sockets

1525 diff mbox series

To be able to isolate an IPA component in a separate process an IPC
mechanism is needed to communicate with it. Add an IPC mechanism based
on Unix sockets which allows users to pass both data and file descriptors
to and from the IPA process.

The implementation allows users to send both data and file descriptors
in the same message. This allows users to more easily implement
serialization and deserialization of objects as all elements belonging
to an object can be sent in one message.

Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
---
 src/libcamera/include/ipc_unixsocket.h |  59 +++++
 src/libcamera/ipc_unixsocket.cpp       | 288 +++++++++++++++++++++++++
 src/libcamera/meson.build              |   2 +
 3 files changed, 349 insertions(+)
 create mode 100644 src/libcamera/include/ipc_unixsocket.h
 create mode 100644 src/libcamera/ipc_unixsocket.cpp

Hi Niklas,

Thank you for the patch.

On Thu, Jun 27, 2019 at 04:09:54AM +0200, Niklas Söderlund wrote:
> To be able to isolate an IPA component in a separate process an IPC
> mechanism is needed to communicate with it. Add an IPC mechanism based
> on Unix sockets which allows users to pass both data and file descriptors
> to and from the IPA process.
> 
> The implementation allows users to send both data and file descriptors
> in the same message. This allows users to more easily implement
> serialization and deserialization of objects as all elements belonging
> to an object can be sent in one message.
> 
> Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
> ---
>  src/libcamera/include/ipc_unixsocket.h |  59 +++++
>  src/libcamera/ipc_unixsocket.cpp       | 288 +++++++++++++++++++++++++
>  src/libcamera/meson.build              |   2 +
>  3 files changed, 349 insertions(+)
>  create mode 100644 src/libcamera/include/ipc_unixsocket.h
>  create mode 100644 src/libcamera/ipc_unixsocket.cpp
> 
> diff --git a/src/libcamera/include/ipc_unixsocket.h b/src/libcamera/include/ipc_unixsocket.h
> new file mode 100644
> index 0000000000000000..68edbe72e2af1298
> --- /dev/null
> +++ b/src/libcamera/include/ipc_unixsocket.h
> @@ -0,0 +1,59 @@
> +/* SPDX-License-Identifier: LGPL-2.1-or-later */
> +/*
> + * Copyright (C) 2019, Google Inc.
> + *
> + * ipc_unixsocket.h - IPC mechanism based on Unix sockets
> + */
> +
> +#ifndef __LIBCAMERA_IPC_UNIXSOCKET_H__
> +#define __LIBCAMERA_IPC_UNIXSOCKET_H__
> +
> +#include <cstdint>
> +#include <sys/types.h>
> +#include <vector>
> +
> +#include <libcamera/event_notifier.h>
> +
> +namespace libcamera {
> +
> +class IPCUnixSocket
> +{
> +public:
> +	struct Payload {
> +		std::vector<uint8_t> data;
> +		std::vector<int32_t> fds;
> +	};
> +
> +	IPCUnixSocket();

You also need a destructor that will call close().

> +
> +	int create();
> +	int attach(int fd);

To keep the socket semantics, should we call this bind() ?

> +	void close();

Should we have a isOpen() call too, or maybe name it isBound() ?

> +
> +	Signal<const Payload &> payloadReceived;

To avoid copying the payload in the slot receiving the signal, would it
make sense to replace this with a Signal<IPCUnixSocket *ipc> readyRead;
signal, and add a Payload receive(); function ? With copy ellision the
receive() function will just fill the Payload object from the caller,
which could come anywhere, could be dynamically allocated, and kept
around for longer than the payloadReceived signal would allow. Otherwise
a user that wants to keep the received payload around would need to make
a copy in the payloadReceived handler. You already have the receive()
function implemented as recv(), so it's a minor change.

> +
> +	int send(Payload &payload);

You can make the payload const. It will require a const_cast<> for the
buffer pointer in sendData(), but I think that's fine.

> +
> +private:
> +	struct Header {
> +		uint32_t data;
> +		uint8_t fds;
> +	};
> +
> +	int configure();
> +
> +	int sendData(void *buffer, size_t length, const int32_t *fds, unsigned int num);

How about passing the Payload reference to this function ? It would make
its signature simpler, and the code more readable in my opinion.

> +
> +	int recv();
> +	int recvData(void *buffer, size_t length, int32_t *fds, unsigned int num);

Same comment here.

> +
> +	void dataNotifier(EventNotifier *notifier);
> +
> +	int fd_;
> +	bool master_;

You never check the master flag, so I would drop it. Once the sockets
are created and bound there's no master or slave anymore, they're
symmetrical.

> +	EventNotifier *notifier_;
> +};
> +
> +} /* namespace libcamera */
> +
> +#endif /* __LIBCAMERA_IPC_UNIXSOCKET_H__ */
> diff --git a/src/libcamera/ipc_unixsocket.cpp b/src/libcamera/ipc_unixsocket.cpp
> new file mode 100644
> index 0000000000000000..7b3d8995374dac1e
> --- /dev/null
> +++ b/src/libcamera/ipc_unixsocket.cpp
> @@ -0,0 +1,288 @@
> +/* SPDX-License-Identifier: LGPL-2.1-or-later */
> +/*
> + * Copyright (C) 2019, Google Inc.
> + *
> + * ipc_unixsocket.cpp - IPC mechanism based on Unix sockets
> + */
> +
> +#include "ipc_unixsocket.h"
> +
> +#include <string.h>
> +#include <sys/socket.h>
> +#include <unistd.h>
> +
> +#include "log.h"
> +
> +/**
> + * \file ipc_unixsocket.h
> + * \brief IPC mechanism based on Unix sockets
> + */
> +
> +namespace libcamera {
> +
> +LOG_DEFINE_CATEGORY(IPCUnixSocket)
> +
> +/**
> + * \struct IPCUnixSocket::Payload
> + * \brief Container for an IPC payload
> + *
> + * Holds an array of bytes and an array of file descriptors that can be
> + * transported across a IPC boundary.
> + */
> +
> +/**
> + * \var IPCUnixSocket::Payload::data
> + * \brief Array of bytes to cross IPC boundary
> + */
> +
> +/**
> + * \var IPCUnixSocket::Payload::fds
> + * \brief Array of file descriptors to cross IPC boundary
> + */
> +
> +/**
> + * \class IPCUnixSocket
> + * \brief IPC mechanism based on Unix sockets
> + *
> + * The IPC mechanism provided by libcamera are centred around passing arrays of
> + * raw bytes and file descriptors between processes. The primary users of the
> + * IPC objects are pipeline handlers and Image Processing Algorithms components.
> + * A pipeline handler would act as an IPC master and send messages for an IPA to
> + * process and react to.

Note that this should be transparent for pipeline handlers, all handled
in the IPA proxy. How about not specifying this class to pipeline
handlers and IPAs, and replacing this first paragraph as follows to keep
it generic ?

 * The Unix socket IPC allows bidirectional communication between two processes
 * through unnamed Unix sockets. It implements datagram-based communication,
 * transporting entire payloads with guaranteed ordering.

> + *
> + * The IPC design is asynchronous, a message is queued to a receiver which gets
> + * notified that a message is ready to be consumed by a signal. The queuer of
> + * the message gets no notification when a message is delivers nor processed.

s/delivers/delivered/

> + * If such interactions are needed a protocol specific to the users use-case
> + * should be implemented on top of the IPC objects.
> + *
> + * The IPC design can transmit messages in any direction and the only difference
> + * from a master and slave operation is how they are created and attached to one
> + * another. After the two parts are setup the operation to send and receive
> + * messages are the same for both.

I would expand this paragraph to explain how the sockets are setup. How
about the following text ?

 * Establishment of an IPC channel is asymmetrical. The side that initiates
 * communication first instantiates a local side socket and creates the channel
 * with create(). The method returns a file descriptor for the remote side of
 * the channel, which is passed to the remote process through an out-of-band
 * communication method. The remote side then instantiates a socket, and binds
 * it to the other side by passing the file descriptor to bind(). At that point
 * the channel is operation and communication is bidirectional and symmmetrical.

> + */
> +
> +IPCUnixSocket::IPCUnixSocket()
> +	: fd_(-1), master_(false), notifier_(nullptr)
> +{
> +}
> +
> +/**
> + * \brief Create an new IPC channel
> + *
> + * Create a new IPC channel. Returned on success is a file descriptor which
> + * needs to be passed to the slave process and used when attaching to the IPC
> + * channel using attach().

 * This method creates a new IPC channel. The socket instance is bound to the
 * local side of the channel, and the method returns a file descriptor bound to
 * the remote side. The caller is responsible for passing the file descriptor to
 * the remote process, where it can be used with IPCUnixSocket::bind() to bind
 * the remote side socket.

> + *
> + * \return A file descriptor on success, negative error code on failure
> + */
> +int IPCUnixSocket::create()
> +{
> +	int sockets[2];
> +	int ret;
> +
> +	ret = socketpair(AF_UNIX, SOCK_DGRAM, 0, sockets);
> +	if (ret) {
> +		ret = -errno;
> +		LOG(IPCUnixSocket, Error)
> +			<< "Failed to create socket pair: " << strerror(-ret);
> +		return ret;
> +	}
> +
> +	fd_ = sockets[0];
> +	master_ = true;
> +
> +	ret = configure();
> +	if (ret)
> +		return ret;
> +
> +	return sockets[1];
> +}
> +
> +/**
> + * \brief Attach to an existing IPC channel

s/Attach/Bind/

> + * \param[in] fd File descriptor
> + *
> + * Attach to an existing IPC channel. The \a fd argument is the file descriptor
> + * returned from create() in the master process and passed to the slave process
> + * to be able to establish the IPC channel.

 * This method binds the socket instance to an existing IPC channel identified
 * by the file descriptor \fd. The file descriptor is obtained from the
 * IPCUnixSocket::create() method.

> + *
> + * \return 0 on success or a negative error code otherwise
> + */
> +int IPCUnixSocket::attach(int fd)
> +{
> +	fd_ = fd;
> +
> +	return configure();
> +}
> +
> +/**
> + * \brief Close the IPC channel
> + *
> + * Close the IPC channel, no communication is possible after close() have been
> + * called.

I would drop the first part of the sentence as it just repeats the
brief.

s/have been/has been/

> + */
> +void IPCUnixSocket::close()
> +{
> +	delete notifier_;

	notifier_ = nullptr;

> +
> +	if (fd_ == -1)
> +		return;
> +
> +	::close(fd_);
> +
> +	fd_ = -1;
> +}
> +
> +/**
> + * \brief Send a message payload
> + * \param[in] payload Message payload to send
> + *
> + * Queues the message payload for transmission to the other end of the IPC

"Queue" or "This method queues".

> + * channel.

And I would add "This method returns immediately, before the message is
delivered to the remote side."

> + *
> + * \return 0 on success or a negative error code otherwise
> + */
> +int IPCUnixSocket::send(Payload &payload)
> +{
> +	Header hdr;
> +	int ret;
> +
> +	if (fd_ < 0)
> +		return -ENOTCONN;
> +
> +	hdr.data = payload.data.size();
> +	hdr.fds = payload.fds.size();
> +
> +	ret = ::send(fd_, &hdr, sizeof(hdr), 0);
> +	if (ret < 0) {
> +		ret = -errno;
> +		LOG(IPCUnixSocket, Error)
> +			<< "Failed to send: " << strerror(-ret);
> +		return ret;
> +	}
> +
> +	ret = sendData(payload.data.data(), hdr.data, payload.fds.data(), hdr.fds);
> +	if (ret)
> +		return ret;
> +
> +	return 0;

Just

	return sendData(...);

> +}
> +
> +/**
> + * \var IPCUnixSocket::payloadReceived
> + * \brief A Signal emitted when a message payload is received
> + */
> +
> +int IPCUnixSocket::configure()
> +{
> +	notifier_ = new EventNotifier(fd_, EventNotifier::Read);
> +	notifier_->activated.connect(this, &IPCUnixSocket::dataNotifier);
> +
> +	return 0;

If this function never fails I would make it void.

I would also pass the fd to this function and store it in fd_ here. This
will make sure that both the fd_ and the notifier_ are set together,
avoiding buggy states where one would be valid and the other wouldn't.

> +}
> +
> +int IPCUnixSocket::sendData(void *buffer, size_t length, const int32_t *fds, unsigned int num)
> +{
> +	struct iovec iov[1];
> +	iov[0].iov_base = buffer;
> +	iov[0].iov_len = length;
> +
> +	char buf[CMSG_SPACE(num * sizeof(uint32_t))];
> +	memset(buf, 0, sizeof(buf));
> +
> +	struct cmsghdr *cmsg = (struct cmsghdr *)buf;
> +	cmsg->cmsg_len = CMSG_LEN(num * sizeof(uint32_t));
> +	cmsg->cmsg_level = SOL_SOCKET;
> +	cmsg->cmsg_type = SCM_RIGHTS;
> +
> +	struct msghdr msg;
> +	msg.msg_name = nullptr;
> +	msg.msg_namelen = 0;
> +	msg.msg_iov = iov;
> +	msg.msg_iovlen = 1;
> +	msg.msg_control = cmsg;
> +	msg.msg_controllen = cmsg->cmsg_len;
> +	msg.msg_flags = 0;
> +	memcpy(CMSG_DATA(cmsg), fds, num * sizeof(uint32_t));
> +
> +	if (sendmsg(fd_, &msg, 0) < 0) {
> +		int ret = -errno;
> +		LOG(IPCUnixSocket, Error)
> +			<< "Failed to sendmsg: " << strerror(-ret);
> +		return ret;
> +	}
> +
> +	return 0;
> +}
> +
> +int IPCUnixSocket::recv()
> +{
> +	Payload payload;
> +	Header hdr;
> +	int ret;
> +
> +	if (fd_ < 0)
> +		return -ENOTCONN;
> +
> +	ret = ::recv(fd_, &hdr, sizeof(hdr), 0);
> +	if (ret < 0) {
> +		ret = -errno;
> +		LOG(IPCUnixSocket, Error)
> +			<< "Failed to recv header: " << strerror(-ret);
> +		return ret;
> +	}
> +
> +	payload.data.resize(hdr.data);
> +	payload.fds.resize(hdr.fds);
> +
> +	ret = recvData(payload.data.data(), hdr.data, payload.fds.data(), hdr.fds);
> +	if (ret)
> +		return ret;
> +
> +	payloadReceived.emit(payload);
> +
> +	return 0;
> +}
> +
> +int IPCUnixSocket::recvData(void *buffer, size_t length, int32_t *fds, unsigned int num)
> +{
> +	struct iovec iov[1];
> +	iov[0].iov_base = buffer;
> +	iov[0].iov_len = length;
> +
> +	char buf[CMSG_SPACE(num * sizeof(uint32_t))];
> +	memset(buf, 0, sizeof(buf));
> +
> +	struct cmsghdr *cmsg = (struct cmsghdr *)buf;
> +	cmsg->cmsg_len = CMSG_LEN(num * sizeof(uint32_t));
> +	cmsg->cmsg_level = SOL_SOCKET;
> +	cmsg->cmsg_type = SCM_RIGHTS;
> +
> +	struct msghdr msg;
> +	msg.msg_name = nullptr;
> +	msg.msg_namelen = 0;
> +	msg.msg_iov = iov;
> +	msg.msg_iovlen = 1;
> +	msg.msg_control = cmsg;
> +	msg.msg_controllen = cmsg->cmsg_len;
> +	msg.msg_flags = 0;
> +
> +	if (recvmsg(fd_, &msg, 0) < 0) {
> +		int ret = -errno;
> +		LOG(IPCUnixSocket, Error)
> +			<< "Failed to recvmsg: " << strerror(-ret);
> +		return ret;
> +	}
> +
> +	memcpy(fds, CMSG_DATA(cmsg), num * sizeof(uint32_t));
> +
> +	return 0;
> +}
> +
> +void IPCUnixSocket::dataNotifier(EventNotifier *notifier)
> +{
> +	recv();
> +}
> +
> +} /* namespace libcamera */
> diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
> index 985aa7e8ab0eb6ce..45bd9d1793aa0b19 100644
> --- a/src/libcamera/meson.build
> +++ b/src/libcamera/meson.build
> @@ -13,6 +13,7 @@ libcamera_sources = files([
>      'ipa_interface.cpp',
>      'ipa_manager.cpp',
>      'ipa_module.cpp',
> +    'ipc_unixsocket.cpp',
>      'log.cpp',
>      'media_device.cpp',
>      'media_object.cpp',
> @@ -38,6 +39,7 @@ libcamera_headers = files([
>      'include/formats.h',
>      'include/ipa_manager.h',
>      'include/ipa_module.h',
> +    'include/ipc_unixsocket.h',
>      'include/log.h',
>      'include/media_device.h',
>      'include/media_object.h',

Hi Laurent,

Thanks for your feedback. As always a special thanks to your comments on 
the documentation!

On 2019-06-28 15:03:26 +0300, Laurent Pinchart wrote:

> > +	int sendData(void *buffer, size_t length, const int32_t *fds, 
> > unsigned int num);
> 
> How about passing the Payload reference to this function ? It would make
> its signature simpler, and the code more readable in my opinion.
> 
> > +
> > +	int recv();
> > +	int recvData(void *buffer, size_t length, int32_t *fds, unsigned int num);
> 
> Same comment here.

I kind of like this interface as the translation from C++ objects is 
handled in send() and receive() and {send,recv}Data() can deal with the 
just transmitting data. I will keep this for v2 while addressing all 
other comments in this review.