xref: /frameworks/native/libs/vr/libpdx/private/pdx/service.h

#ifndef ANDROID_PDX_SERVICE_H_
#define ANDROID_PDX_SERVICE_H_

#include <errno.h>
#include <log/log.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>

#include <algorithm>
#include <memory>
#include <mutex>
#include <string>
#include <unordered_map>
#include <vector>

#include "pdx/channel_handle.h"
#include "pdx/file_handle.h"
#include "pdx/message_reader.h"
#include "pdx/message_writer.h"
#include "pdx/service_endpoint.h"

namespace android {
namespace pdx {

class Service;

namespace opcodes {

/*
 * Reserved message opcodes used by libpdx. The reserved opcodes start at the
 * max positive signed integer for the system and go down.
 * In contrast, service opcodes start at zero and go up. This scheme leaves
 * most of the positive integer space for services, a tiny fraction of the
 * positive integer space for the framework, and the entire negative integer
 * space for the kernel.
 */
#define PDX_OPCODE(name, n) name = ((-1U >> 1) - (n))  // 0x7fff..ffff - n

enum {
  // System message sent when a new client channel is open.
  CHANNEL_OPEN = -1,
  // System message sent when a channel is closed.
  CHANNEL_CLOSE = -2,
  // Request the service to reload system properties.
  PDX_OPCODE(REPORT_SYSPROP_CHANGE, 0),
  // Request the service to dump state and return it in a text buffer.
  PDX_OPCODE(DUMP_STATE, 1),
};

}  // namespace opcodes

/*
 * Base class of service-side per-channel context classes.
 */
class Channel : public std::enable_shared_from_this<Channel> {
 public:
  Channel() {}
  virtual ~Channel() {}

  /*
   * Utility to get a shared_ptr reference from the channel context pointer.
   */
  static std::shared_ptr<Channel> GetFromMessageInfo(const MessageInfo& info);
};

/*
 * Message class represents an RPC message, and implicitly the blocked sender
 * waiting for a response. Every message should get a reply, at some point
 * (unless the endpoint is closed), to prevent clients from blocking
 * indefinitely. In order to enforce this and prevent leaking message ids,
 * Message automatically replies with an error to the client on destruction,
 * unless one of two things happens:
 *
 *     1. The service calls one of the reply methods before the Message is
 *        destroyed.
 *     2. The responsibility for the message is moved to another instance of
 *        Message, using either move construction or move assignment.
 *
 * The second case is useful for services that need to delay responding to a
 * sender until a later time. In this situation the service can move the
 * Message to another instance in a suitable data structure for later use. The
 * moved-to Message then takes on the same behavior and responsibilities
 * described above.
 */
class Message : public OutputResourceMapper, public InputResourceMapper {
 public:
  Message();
  Message(const MessageInfo& info);
  ~Message();

  /*
   * Message objects support move construction and assignment.
   */
  Message(Message&& other);
  Message& operator=(Message&& other);

  /*
   * Read/write payload, in either single buffer or iovec form.
   */
  Status<size_t> ReadVector(const iovec* vector, size_t vector_length);
  Status<size_t> Read(void* buffer, size_t length);
  Status<size_t> WriteVector(const iovec* vector, size_t vector_length);
  Status<size_t> Write(const void* buffer, size_t length);

  template <size_t N>
  inline Status<size_t> ReadVector(const iovec (&vector)[N]) {
    return ReadVector(vector, N);
  }

  template <size_t N>
  inline Status<size_t> WriteVector(const iovec (&vector)[N]) {
    return WriteVector(vector, N);
  }

  // Helper functions to read/write all requested bytes, and return EIO if not
  // all were read/written.
  Status<void> ReadVectorAll(const iovec* vector, size_t vector_length);
  Status<void> WriteVectorAll(const iovec* vector, size_t vector_length);

  inline Status<void> ReadAll(void* buffer, size_t length) {
    Status<size_t> status = Read(buffer, length);
    if (status && status.get() < length)
      status.SetError(EIO);
    Status<void> ret;
    ret.PropagateError(status);
    return ret;
  }
  inline Status<void> WriteAll(const void* buffer, size_t length) {
    Status<size_t> status = Write(buffer, length);
    if (status && status.get() < length)
      status.SetError(EIO);
    Status<void> ret;
    ret.PropagateError(status);
    return ret;
  }

  template <size_t N>
  inline Status<void> ReadVectorAll(const iovec (&vector)[N]) {
    return ReadVectorAll(vector, N);
  }

  template <size_t N>
  inline Status<void> WriteVectorAll(const iovec (&vector)[N]) {
    return WriteVectorAll(vector, N);
  }

  // OutputResourceMapper
  Status<FileReference> PushFileHandle(const LocalHandle& handle) override;
  Status<FileReference> PushFileHandle(const BorrowedHandle& handle) override;
  Status<FileReference> PushFileHandle(const RemoteHandle& handle) override;
  Status<ChannelReference> PushChannelHandle(
      const LocalChannelHandle& handle) override;
  Status<ChannelReference> PushChannelHandle(
      const BorrowedChannelHandle& handle) override;
  Status<ChannelReference> PushChannelHandle(
      const RemoteChannelHandle& handle) override;

  // InputResourceMapper
  bool GetFileHandle(FileReference ref, LocalHandle* handle) override;
  bool GetChannelHandle(ChannelReference ref,
                        LocalChannelHandle* handle) override;

  /*
   * Various ways to reply to a message.
   */
  Status<void> Reply(int return_code);
  Status<void> ReplyError(unsigned int error);
  Status<void> ReplyFileDescriptor(unsigned int fd);
  Status<void> Reply(const LocalHandle& handle);
  Status<void> Reply(const BorrowedHandle& handle);
  Status<void> Reply(const RemoteHandle& handle);
  Status<void> Reply(const LocalChannelHandle& handle);
  Status<void> Reply(const BorrowedChannelHandle& handle);
  Status<void> Reply(const RemoteChannelHandle& handle);

  template <typename T>
  inline Status<void> Reply(const Status<T>& status) {
    return status ? Reply(status.get()) : ReplyError(status.error());
  }

  inline Status<void> Reply(const Status<void>& status) {
    return status ? Reply(0) : ReplyError(status.error());
  }

  /*
   * Update the channel event bits with the given clear and set masks.
   */
  Status<void> ModifyChannelEvents(int clear_mask, int set_mask);

  /*
   * Create a new channel and push it as a file descriptor to the client. See
   * Service::PushChannel() for a detail description of this method's operation.
   */
  Status<RemoteChannelHandle> PushChannel(
      int flags, const std::shared_ptr<Channel>& channel, int* channel_id);

  /*
   * Create a new channel and push it as a file descriptor to the client. See
   * Service::PushChannel() for a detail description of this method's operation.
   */
  Status<RemoteChannelHandle> PushChannel(
      Service* service, int flags, const std::shared_ptr<Channel>& channel,
      int* channel_id);

  /*
   * Check whether the |ref| is a reference to channel to this service.
   * If the channel reference in question is valid, the Channel object is
   * returned in |channel| when non-nullptr.
   *
   * Return values:
   *  channel_id - id of the channel if the |ref| is a valid reference to
   *               this service's channel.
   * Errors:
   *  EOPNOTSUPP - the file descriptor is not a channel or is a channel to
   *  another service.
   *  EBADF - the file descriptor is invalid.
   *  FAULT - |channel_id| or |channel| are non-nullptr and point to invalid
   *  memory addresses.
   *  EINVAL - the value of |ref| is invalid or the message id for this
   *           message is no longer valid.
   */
  Status<int> CheckChannel(ChannelReference ref,
                           std::shared_ptr<Channel>* channel) const;

  /*
   * Overload of CheckChannel() that checks whether the channel reference is for
   * a channel to the service |service|.
   */
  Status<int> CheckChannel(const Service* service, ChannelReference ref,
                           std::shared_ptr<Channel>* channel) const;

  /*
   * Overload of CheckChannel() that automatically converts to shared pointers
   * to types derived from Channel.
   */
  template <class C>
  Status<int> CheckChannel(ChannelReference ref,
                           std::shared_ptr<C>* channel) const {
    std::shared_ptr<Channel> base_pointer;
    const Status<int> ret =
        CheckChannel(ref, channel ? &base_pointer : nullptr);
    if (channel)
      *channel = std::static_pointer_cast<C>(base_pointer);
    return ret;
  }

  template <class C>
  Status<int> CheckChannel(const Service* service, ChannelReference ref,
                           std::shared_ptr<C>* channel) const {
    std::shared_ptr<Channel> base_pointer;
    const Status<int> ret =
        CheckChannel(service, ref, channel ? &base_pointer : nullptr);
    if (channel)
      *channel = std::static_pointer_cast<C>(base_pointer);
    return ret;
  }

  /*
   * MessageInfo accessors.
   */
  pid_t GetProcessId() const;
  pid_t GetThreadId() const;
  uid_t GetEffectiveUserId() const;
  gid_t GetEffectiveGroupId() const;
  int GetChannelId() const;
  int GetMessageId() const;
  int GetOp() const;
  int GetFlags() const;
  size_t GetSendLength() const;
  size_t GetReceiveLength() const;
  size_t GetFileDescriptorCount() const;

  /*
   * Impulses are asynchronous and cannot be replied to. All impulses have this
   * invalid message id.
   */
  enum { IMPULSE_MESSAGE_ID = -1 };

  /*
   * Returns true if this Message describes an asynchronous "impulse" message.
   */
  bool IsImpulse() const { return GetMessageId() == IMPULSE_MESSAGE_ID; }

  /*
   * Returns a pointer to the impulse payload. Impulses are a maximum of 32
   * bytes in size and the start of the impulse payload is guaranteed to be
   * 8-byte aligned. Use GetSendLength() to determine the payload size.
   */
  const std::uint8_t* ImpulseBegin() const;

  /*
   * Returns one byte past the end of the impulse payload, as conventional for
   * STL iterators.
   */
  const std::uint8_t* ImpulseEnd() const;

  /*
   * Get/set the Channel object for the channel associated
   * with this message. It is up to the caller to synchronize
   * these in multi-threaded services.
   */
  std::shared_ptr<Channel> GetChannel() const;
  Status<void> SetChannel(const std::shared_ptr<Channel>& channnel);

  /*
   * Get the Channel object for the channel associated with this message,
   * automatically converted to the desired subclass of Channel.
   */
  template <class C>
  std::shared_ptr<C> GetChannel() const {
    return std::static_pointer_cast<C>(GetChannel());
  }

  /*
   * Gets the service this message was received on. Returns nullptr if the
   * service was destroyed.
   */
  std::shared_ptr<Service> GetService() const;

  /*
   * Raw access to the MessageInfo for this message.
   */
  const MessageInfo& GetInfo() const;

  bool replied() const { return replied_; }
  bool IsChannelExpired() const { return channel_.expired(); }
  bool IsServiceExpired() const { return service_.expired(); }

  /*
   * Returns true if the message is non-empty; that is the message can be
   * replied to using this instance.
   */
  explicit operator bool() const { return !replied_; }

  const void* GetState() const { return state_; }
  void* GetState() { return state_; }

 private:
  friend class Service;

  Message(const Message&) = delete;
  void operator=(const Message&) = delete;
  void Destroy();

  std::weak_ptr<Service> service_;
  std::weak_ptr<Channel> channel_;
  MessageInfo info_;
  void* state_{nullptr};
  bool replied_;
};

// Base class for RPC services.
class Service : public std::enable_shared_from_this<Service> {
 public:
  Service(const std::string& name, std::unique_ptr<Endpoint> endpoint);
  virtual ~Service();

  /*
   * Utility to get a shared_ptr reference from the service context pointer.
   */
  static std::shared_ptr<Service> GetFromMessageInfo(const MessageInfo& info);

  /*
   * Returns whether initialization was successful. Subclasses that override
   * this must call this base method and AND the results with their own. This
   * method is not intended to do any initialization work itself, only to
   * signal success or failure.
   */
  virtual bool IsInitialized() const;

  /*
   * Called by defaultHandleMessage in response to a CHANNEL_OPEN message.
   * This gives subclasses of Service a convenient hook to create per-channel
   * context in the form of a Channel subclass.
   *
   * The Channel instance returned by this is used to set the channel context
   * pointer for the channel that was just opened.
   */
  virtual std::shared_ptr<Channel> OnChannelOpen(Message& message);

  /*
   * Called by defaultHandleMessage in response to a CHANNEL_CLOSE message.
   * This give subclasses of Service a convenient hook to clean up per-channel
   * context.
   */
  virtual void OnChannelClose(Message& message,
                              const std::shared_ptr<Channel>& channel);

  /*
   * Set the channel context for the given channel. This keeps a reference to
   * the Channel object until the channel is closed or another call replaces
   * the current value.
   */
  Status<void> SetChannel(int channel_id,
                          const std::shared_ptr<Channel>& channel);

  /*
   * Get the channel context for the given channel id. This method should be
   * used sparingly because of the performance characteristics of the underlying
   * map; it is intended for limited, non-critical path access from outside of
   * message dispatch. In most cases lookup by id should be unnecessary in a
   * properly designed service; Message::GetChannel() should be used instead
   * whenever an operation is in the context of a message.
   *
   * Again, if you lookup a channel context object for a service by id in a
   * message handling path for the same service, you're probably doing something
   * wrong.
   */
  std::shared_ptr<Channel> GetChannel(int channel_id) const;

  /*
   * Get a snapshot of the active channels for this service. This is the
   * preferred way to access the set of channels because it avoids potential
   * deadlocks and race conditions that may occur when operating on the channel
   * map directly. However, it is more expensive than direct iteration because
   * of dynamic memory allocation and shared pointer reference costs.
   *
   * Automatically converts returned items to shared pointers of the type
   * std::shared_ptr<C>, where C is the subclass of Channel used by the service.
   */
  template <class C>
  std::vector<std::shared_ptr<C>> GetChannels() const {
    std::lock_guard<std::mutex> autolock(channels_mutex_);
    std::vector<std::shared_ptr<C>> items;
    items.reserve(channels_.size());

    for (const auto& pair : channels_) {
      items.push_back(std::static_pointer_cast<C>(pair.second));
    }

    return items;
  }

  /*
   * Close a channel, signaling the client file object and freeing the channel
   * id. Once closed, the client side of the channel always returns the error
   * ESHUTDOWN and signals the poll/epoll events POLLHUP and POLLFREE.
   *
   * The internal reference to the Channel instance associated with the channel
   * is removed, which may result in the Channel object being freed.
   *
   * OnChannelClosed is not called in response to this method call.
   */
  Status<void> CloseChannel(int channel_id);

  /*
   * Update the event bits for the given channel (given by id), using the
   * given clear and set masks.
   *
   * This is useful for asynchronously signaling events that clients may be
   * waiting for using select/poll/epoll.
   */
  Status<void> ModifyChannelEvents(int channel_id, int clear_mask,
                                   int set_mask);

  /*
   * Create a new channel and push it as a file descriptor to the process
   * sending the |message|. |flags| may be set to O_NONBLOCK and/or
   * O_CLOEXEC to control the initial behavior of the new file descriptor (the
   * sending process may change these later using fcntl()). The internal Channel
   * instance associated with this channel is set to |channel|, which may be
   * nullptr. The new channel id allocated for this channel is returned in
   * |channel_id|, which may also be nullptr if not needed.
   *
   * On success, returns the remote channel handle for the new channel in the
   * sending process' handle space. This MUST be returned to the sender via
   * Message::Reply(), Message::Write(), or Message::WriteVector().
   *
   * On error, returns an errno code describing the cause of the error.
   *
   * Service::OnChannelCreate() is not called in response to the creation of the
   * new channel.
   */
  Status<RemoteChannelHandle> PushChannel(
      Message* message, int flags, const std::shared_ptr<Channel>& channel,
      int* channel_id);

  /*
   * Check whether the |ref| is a reference to a channel to this service.
   * If the channel reference in question is valid, the Channel object is
   * returned in |channel| when non-nullptr.
   *
   * Return values:
   *  channel_id - id of the channel if the channel reference.
   * Errors:
   *  EOPNOTSUPP - the file descriptor is not a channel or is a channel to
   *  another service.
   *  EBADF - the file descriptor is invalid.
   *  FAULT - |channel_id| or |channel| are non-nullptr and point to invalid
   *  memory addresses.
   *  EINVAL - the value of |ref| is invalid or the message id for this
   *  message is no longer valid.
   */
  Status<int> CheckChannel(const Message* message, ChannelReference ref,
                           std::shared_ptr<Channel>* channel) const;

  /*
   * Overload of CheckChannel() that automatically converts to shared pointers
   * of types derived from Channel.
   */
  template <class C>
  Status<int> CheckChannel(const Message* message, ChannelReference ref,
                           std::shared_ptr<C>* channel) const {
    std::shared_ptr<Channel> base_pointer;
    const Status<int> ret =
        CheckChannel(message, ref, channel ? &base_pointer : nullptr);
    if (channel)
      *channel = std::static_pointer_cast<C>(base_pointer);
    return ret;
  }

  /*
   * Handle a message. Subclasses override this to receive messages and decide
   * how to dispatch them.
   *
   * The default implementation simply calls defaultHandleMessage().
   * Subclasses should call the same for any unrecognized message opcodes.
   */
  virtual Status<void> HandleMessage(Message& message);

  /*
   * Handle an asynchronous message. Subclasses override this to receive
   * asynchronous "impulse" messages. Impulses have a limited-size payload that
   * is transferred upfront with the message description.
   */
  virtual void HandleImpulse(Message& impulse);

  /*
   * The default message handler. It is important that all messages
   * (eventually) get a reply. This method should be called by subclasses for
   * any unrecognized opcodes or otherwise unhandled messages to prevent
   * erroneous requests from blocking indefinitely.
   *
   * Provides default handling of CHANNEL_OPEN and CHANNEL_CLOSE, calling
   * OnChannelOpen() and OnChannelClose(), respectively.
   *
   * For all other message opcodes, this method replies with ENOTSUP.
   */
  Status<void> DefaultHandleMessage(Message& message);

  /*
   * Called when system properties have changed. Subclasses should implement
   * this method if they need to handle when system properties change.
   */
  virtual void OnSysPropChange();

  /*
   * Get the endpoint for the service.
   */
  Endpoint* endpoint() const { return endpoint_.get(); }

  /*
   * Cancels the endpoint, unblocking any receiver threads waiting in
   * ReceiveAndDispatch().
   */
  Status<void> Cancel();

  /*
   * Iterator type for Channel map iterators.
   */
  using ChannelIterator =
      std::unordered_map<int, std::shared_ptr<Channel>>::iterator;

  /*
   * Iterates over the Channel map and performs the action given by |action| on
   * each channel map item (const ChannelIterator::value_type).
   * |channels_mutex_| is not held; it is the responsibility of the caller to
   * ensure serialization between threads that modify or iterate over the
   * Channel map.
   */
  template <class A>
  void ForEachChannelUnlocked(A action) const {
    std::for_each(channels_.begin(), channels_.end(), action);
  }

  /*
   * Iterates over the Channel map and performs the action given by |action| on
   * each channel map item (const ChannelIterator::value_type).
   * |channels_mutex_| is held to serialize access to the map; care must be
   * taken to avoid recursively acquiring the mutex, for example, by calling
   * Service::{GetChannel,SetChannel,CloseChannel,PushChannel}() or
   * Message::SetChannel() in the action.
   */
  template <class A>
  void ForEachChannel(A action) const {
    std::lock_guard<std::mutex> autolock(channels_mutex_);
    ForEachChannelUnlocked(action);
  }

  /*
   * Subclasses of Service may override this method to provide a text string
   * describing the state of the service. This method is called by
   * HandleSystemMessage in response to the standard
   * DUMP_STATE message. The string returned to the dump state client is
   * truncated to |max_length| and reflects the maximum size the client can
   * handle.
   */
  virtual std::string DumpState(size_t max_length);

  /*
   * Receives a message on this Service instance's endpoint and dispatches it.
   * If the endpoint is in blocking mode this call blocks until a message is
   * received, a signal is delivered to this thread, or the service is canceled.
   * If the endpoint is in non-blocking mode and a message is not pending this
   * call returns immediately with ETIMEDOUT.
   */
  Status<void> ReceiveAndDispatch();

 private:
  friend class Message;

  Status<void> HandleSystemMessage(Message& message);

  Service(const Service&);
  void operator=(const Service&) = delete;

  const std::string name_;
  std::unique_ptr<Endpoint> endpoint_;

  /*
   * Maintains references to active channels.
   */
  mutable std::mutex channels_mutex_;
  std::unordered_map<int, std::shared_ptr<Channel>> channels_;
};

/*
 * Utility base class for services. This template handles allocation and
 * initialization checks, reducing boiler plate code.
 */
template <typename TYPE>
class ServiceBase : public Service {
 public:
  /*
   * Static service allocation method that check for initialization errors.
   * If errors are encountered these automatically clean up and return
   * nullptr.
   */
  template <typename... Args>
  static inline std::shared_ptr<TYPE> Create(Args&&... args) {
    std::shared_ptr<TYPE> service(new TYPE(std::forward<Args>(args)...));
    if (service->IsInitialized())
      return service;
    else
      return nullptr;
  }

 protected:
  /*
   * Shorthand for subclasses to refer to this base, particularly
   * to call the base class constructor.
   */
  typedef ServiceBase<TYPE> BASE;

  ServiceBase(const std::string& name, std::unique_ptr<Endpoint> endpoint)
      : Service(name, std::move(endpoint)) {}
};

#ifndef STRINGIFY
#define STRINGIFY2(s) #s
#define STRINGIFY(s) STRINGIFY2(s)
#endif

#define PDX_ERROR_PREFIX "[" __FILE__ ":" STRINGIFY(__LINE__) "]"

/*
 * Macros for replying to messages. Error handling can be tedious;
 * these macros make things a little cleaner.
 */
#define CHECK_ERROR(cond, error, fmt, ...) \
  do {                                     \
    if ((cond)) {                          \
      ALOGE(fmt, ##__VA_ARGS__);           \
      goto error;                          \
    }                                      \
  } while (0)

#define REPLY_ERROR(message, error, error_label)                              \
  do {                                                                        \
    auto __status = message.ReplyError(error);                                \
    CHECK_ERROR(!__status, error_label,                                       \
                PDX_ERROR_PREFIX " Failed to reply to message because: %s\n", \
                __status.GetErrorMessage().c_str());                          \
    goto error_label;                                                         \
  } while (0)

#define REPLY_ERROR_RETURN(message, error, ...)                          \
  do {                                                                   \
    auto __status = message.ReplyError(error);                           \
    ALOGE_IF(!__status,                                                  \
             PDX_ERROR_PREFIX " Failed to reply to message because: %s", \
             __status.GetErrorMessage().c_str());                        \
    return __VA_ARGS__;                                                  \
  } while (0)

#define REPLY_MESSAGE(message, message_return_code, error_label)              \
  do {                                                                        \
    auto __status = message.Reply(message_return_code);                       \
    CHECK_ERROR(!__status, error_label,                                       \
                PDX_ERROR_PREFIX " Failed to reply to message because: %s\n", \
                __status.GetErrorMessage().c_str());                          \
    goto error_label;                                                         \
  } while (0)

#define REPLY_SUCCESS(message, message_return_code, error_label) \
  REPLY_MESSAGE(message, message_return_code, error_label)

#define REPLY_MESSAGE_RETURN(message, message_return_code, ...)          \
  do {                                                                   \
    auto __status = message.Reply(message_return_code);                  \
    ALOGE_IF(!__status,                                                  \
             PDX_ERROR_PREFIX " Failed to reply to message because: %s", \
             __status.GetErrorMessage().c_str());                        \
    return __VA_ARGS__;                                                  \
  } while (0)

#define REPLY_SUCCESS_RETURN(message, message_return_code, ...) \
  REPLY_MESSAGE_RETURN(message, message_return_code, __VA_ARGS__)

#define REPLY_FD(message, push_fd, error_label)                               \
  do {                                                                        \
    auto __status = message.ReplyFileDescriptor(push_fd);                     \
    CHECK_ERROR(!__status, error_label,                                       \
                PDX_ERROR_PREFIX " Failed to reply to message because: %s\n", \
                __status.GetErrorMessage().c_str());                          \
    goto error_label;                                                         \
  } while (0)

#define REPLY_FD_RETURN(message, push_fd, ...)                           \
  do {                                                                   \
    auto __status = message.ReplyFileDescriptor(push_fd);                \
    ALOGE_IF(__status < 0,                                               \
             PDX_ERROR_PREFIX " Failed to reply to message because: %s", \
             __status.GetErrorMessage().c_str());                        \
    return __VA_ARGS__;                                                  \
  } while (0)

}  // namespace pdx
}  // namespace android

#endif  // ANDROID_PDX_SERVICE_H_