include/linux/surface_aggregator/serial_hub.h

/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * Surface Serial Hub (SSH) protocol and communication interface.
 *
 * Lower-level communication layers and SSH protocol definitions for the
 * Surface System Aggregator Module (SSAM). Provides the interface for basic
 * packet- and request-based communication with the SSAM EC via SSH.
 *
 * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
 */

#ifndef _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H
#define _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H

#include <linux/crc-itu-t.h>
#include <linux/kref.h>
#include <linux/ktime.h>
#include <linux/list.h>
#include <linux/types.h>


/* -- Data structures for SAM-over-SSH communication. ----------------------- */

/**
 * enum ssh_frame_type - Frame types for SSH frames.
 *
 * @SSH_FRAME_TYPE_DATA_SEQ:
 *	Indicates a data frame, followed by a payload with the length specified
 *	in the ``struct ssh_frame.len`` field. This frame is sequenced, meaning
 *	that an ACK is required.
 *
 * @SSH_FRAME_TYPE_DATA_NSQ:
 *	Same as %SSH_FRAME_TYPE_DATA_SEQ, but unsequenced, meaning that the
 *	message does not have to be ACKed.
 *
 * @SSH_FRAME_TYPE_ACK:
 *	Indicates an ACK message.
 *
 * @SSH_FRAME_TYPE_NAK:
 *	Indicates an error response for previously sent frame. In general, this
 *	means that the frame and/or payload is malformed, e.g. a CRC is wrong.
 *	For command-type payloads, this can also mean that the command is
 *	invalid.
 */
enum ssh_frame_type {
	SSH_FRAME_TYPE_DATA_SEQ = 0x80,
	SSH_FRAME_TYPE_DATA_NSQ = 0x00,
	SSH_FRAME_TYPE_ACK      = 0x40,
	SSH_FRAME_TYPE_NAK      = 0x04,
};

/**
 * struct ssh_frame - SSH communication frame.
 * @type: The type of the frame. See &enum ssh_frame_type.
 * @len:  The length of the frame payload directly following the CRC for this
 *        frame. Does not include the final CRC for that payload.
 * @seq:  The sequence number for this message/exchange.
 */
struct ssh_frame {
	u8 type;
	__le16 len;
	u8 seq;
} __packed;

static_assert(sizeof(struct ssh_frame) == 4);

/*
 * SSH_FRAME_MAX_PAYLOAD_SIZE - Maximum SSH frame payload length in bytes.
 *
 * This is the physical maximum length of the protocol. Implementations may
 * set a more constrained limit.
 */
#define SSH_FRAME_MAX_PAYLOAD_SIZE	U16_MAX

/**
 * enum ssh_payload_type - Type indicator for the SSH payload.
 * @SSH_PLD_TYPE_CMD: The payload is a command structure with optional command
 *                    payload.
 */
enum ssh_payload_type {
	SSH_PLD_TYPE_CMD = 0x80,
};

/**
 * struct ssh_command - Payload of a command-type frame.
 * @type: The type of the payload. See &enum ssh_payload_type. Should be
 *        SSH_PLD_TYPE_CMD for this struct.
 * @tc:   Command target category.
 * @tid:  Target ID. Indicates the target of the message.
 * @sid:  Source ID. Indicates the source of the message.
 * @iid:  Instance ID.
 * @rqid: Request ID. Used to match requests with responses and differentiate
 *        between responses and events.
 * @cid:  Command ID.
 */
struct ssh_command {
	u8 type;
	u8 tc;
	u8 tid;
	u8 sid;
	u8 iid;
	__le16 rqid;
	u8 cid;
} __packed;

static_assert(sizeof(struct ssh_command) == 8);

/*
 * SSH_COMMAND_MAX_PAYLOAD_SIZE - Maximum SSH command payload length in bytes.
 *
 * This is the physical maximum length of the protocol. Implementations may
 * set a more constrained limit.
 */
#define SSH_COMMAND_MAX_PAYLOAD_SIZE \
	(SSH_FRAME_MAX_PAYLOAD_SIZE - sizeof(struct ssh_command))

/*
 * SSH_MSG_LEN_BASE - Base-length of a SSH message.
 *
 * This is the minimum number of bytes required to form a message. The actual
 * message length is SSH_MSG_LEN_BASE plus the length of the frame payload.
 */
#define SSH_MSG_LEN_BASE	(sizeof(struct ssh_frame) + 3ull * sizeof(u16))

/*
 * SSH_MSG_LEN_CTRL - Length of a SSH control message.
 *
 * This is the length of a SSH control message, which is equal to a SSH
 * message without any payload.
 */
#define SSH_MSG_LEN_CTRL	SSH_MSG_LEN_BASE

/**
 * SSH_MESSAGE_LENGTH() - Compute length of SSH message.
 * @payload_size: Length of the payload inside the SSH frame.
 *
 * Return: Returns the length of a SSH message with payload of specified size.
 */
#define SSH_MESSAGE_LENGTH(payload_size) (SSH_MSG_LEN_BASE + (payload_size))

/**
 * SSH_COMMAND_MESSAGE_LENGTH() - Compute length of SSH command message.
 * @payload_size: Length of the command payload.
 *
 * Return: Returns the length of a SSH command message with command payload of
 * specified size.
 */
#define SSH_COMMAND_MESSAGE_LENGTH(payload_size) \
	SSH_MESSAGE_LENGTH(sizeof(struct ssh_command) + (payload_size))

/**
 * SSH_MSGOFFSET_FRAME() - Compute offset in SSH message to specified field in
 * frame.
 * @field: The field for which the offset should be computed.
 *
 * Return: Returns the offset of the specified &struct ssh_frame field in the
 * raw SSH message data as. Takes SYN bytes (u16) preceding the frame into
 * account.
 */
#define SSH_MSGOFFSET_FRAME(field) \
	(sizeof(u16) + offsetof(struct ssh_frame, field))

/**
 * SSH_MSGOFFSET_COMMAND() - Compute offset in SSH message to specified field
 * in command.
 * @field: The field for which the offset should be computed.
 *
 * Return: Returns the offset of the specified &struct ssh_command field in
 * the raw SSH message data. Takes SYN bytes (u16) preceding the frame and the
 * frame CRC (u16) between frame and command into account.
 */
#define SSH_MSGOFFSET_COMMAND(field) \
	(2ull * sizeof(u16) + sizeof(struct ssh_frame) \
		+ offsetof(struct ssh_command, field))

/*
 * SSH_MSG_SYN - SSH message synchronization (SYN) bytes as u16.
 */
#define SSH_MSG_SYN		((u16)0x55aa)

/**
 * ssh_crc() - Compute CRC for SSH messages.
 * @buf: The pointer pointing to the data for which the CRC should be computed.
 * @len: The length of the data for which the CRC should be computed.
 *
 * Return: Returns the CRC computed on the provided data, as used for SSH
 * messages.
 */
static inline u16 ssh_crc(const u8 *buf, size_t len)
{
	return crc_itu_t(0xffff, buf, len);
}

/*
 * SSH_NUM_EVENTS - The number of reserved event IDs.
 *
 * The number of reserved event IDs, used for registering an SSH event
 * handler. Valid event IDs are numbers below or equal to this value, with
 * exception of zero, which is not an event ID. Thus, this is also the
 * absolute maximum number of event handlers that can be registered.
 */
#define SSH_NUM_EVENTS		38

/*
 * SSH_NUM_TARGETS - The number of communication targets used in the protocol.
 */
#define SSH_NUM_TARGETS		2

/**
 * ssh_rqid_next_valid() - Return the next valid request ID.
 * @rqid: The current request ID.
 *
 * Return: Returns the next valid request ID, following the current request ID
 * provided to this function. This function skips any request IDs reserved for
 * events.
 */
static inline u16 ssh_rqid_next_valid(u16 rqid)
{
	return rqid > 0 ? rqid + 1u : rqid + SSH_NUM_EVENTS + 1u;
}

/**
 * ssh_rqid_to_event() - Convert request ID to its corresponding event ID.
 * @rqid: The request ID to convert.
 */
static inline u16 ssh_rqid_to_event(u16 rqid)
{
	return rqid - 1u;
}

/**
 * ssh_rqid_is_event() - Check if given request ID is a valid event ID.
 * @rqid: The request ID to check.
 */
static inline bool ssh_rqid_is_event(u16 rqid)
{
	return ssh_rqid_to_event(rqid) < SSH_NUM_EVENTS;
}

/**
 * ssh_tc_to_rqid() - Convert target category to its corresponding request ID.
 * @tc: The target category to convert.
 */
static inline u16 ssh_tc_to_rqid(u8 tc)
{
	return tc;
}

/**
 * ssh_tid_to_index() - Convert target ID to its corresponding target index.
 * @tid: The target ID to convert.
 */
static inline u8 ssh_tid_to_index(u8 tid)
{
	return tid - 1u;
}

/**
 * ssh_tid_is_valid() - Check if target ID is valid/supported.
 * @tid: The target ID to check.
 */
static inline bool ssh_tid_is_valid(u8 tid)
{
	return ssh_tid_to_index(tid) < SSH_NUM_TARGETS;
}

/**
 * struct ssam_span - Reference to a buffer region.
 * @ptr: Pointer to the buffer region.
 * @len: Length of the buffer region.
 *
 * A reference to a (non-owned) buffer segment, consisting of pointer and
 * length. Use of this struct indicates non-owned data, i.e. data of which the
 * life-time is managed (i.e. it is allocated/freed) via another pointer.
 */
struct ssam_span {
	u8    *ptr;
	size_t len;
};

/**
 * enum ssam_ssh_tid - Target/source IDs for Serial Hub messages.
 * @SSAM_SSH_TID_HOST:     We as the kernel Serial Hub driver.
 * @SSAM_SSH_TID_SAM:      The Surface Aggregator EC.
 * @SSAM_SSH_TID_KIP:      Keyboard and perihperal controller.
 * @SSAM_SSH_TID_DEBUG:    Debug connector.
 * @SSAM_SSH_TID_SURFLINK: SurfLink connector.
 */
enum ssam_ssh_tid {
	SSAM_SSH_TID_HOST     = 0x00,
	SSAM_SSH_TID_SAM      = 0x01,
	SSAM_SSH_TID_KIP      = 0x02,
	SSAM_SSH_TID_DEBUG    = 0x03,
	SSAM_SSH_TID_SURFLINK = 0x04,
};

/*
 * Known SSH/EC target categories.
 *
 * List of currently known target category values; "Known" as in we know they
 * exist and are valid on at least some device/model. Detailed functionality
 * or the full category name is only known for some of these categories and
 * is detailed in the respective comment below.
 *
 * These values and abbreviations have been extracted from strings inside the
 * Windows driver.
 */
enum ssam_ssh_tc {
				  /* Category 0x00 is invalid for EC use. */
	SSAM_SSH_TC_SAM  = 0x01,  /* Generic system functionality, real-time clock. */
	SSAM_SSH_TC_BAT  = 0x02,  /* Battery/power subsystem. */
	SSAM_SSH_TC_TMP  = 0x03,  /* Thermal subsystem. */
	SSAM_SSH_TC_PMC  = 0x04,
	SSAM_SSH_TC_FAN  = 0x05,
	SSAM_SSH_TC_PoM  = 0x06,
	SSAM_SSH_TC_DBG  = 0x07,
	SSAM_SSH_TC_KBD  = 0x08,  /* Legacy keyboard (Laptop 1/2). */
	SSAM_SSH_TC_FWU  = 0x09,
	SSAM_SSH_TC_UNI  = 0x0a,
	SSAM_SSH_TC_LPC  = 0x0b,
	SSAM_SSH_TC_TCL  = 0x0c,
	SSAM_SSH_TC_SFL  = 0x0d,
	SSAM_SSH_TC_KIP  = 0x0e,  /* Manages detachable peripherals (Pro X/8 keyboard cover) */
	SSAM_SSH_TC_EXT  = 0x0f,
	SSAM_SSH_TC_BLD  = 0x10,
	SSAM_SSH_TC_BAS  = 0x11,  /* Detachment system (Surface Book 2/3). */
	SSAM_SSH_TC_SEN  = 0x12,
	SSAM_SSH_TC_SRQ  = 0x13,
	SSAM_SSH_TC_MCU  = 0x14,
	SSAM_SSH_TC_HID  = 0x15,  /* Generic HID input subsystem. */
	SSAM_SSH_TC_TCH  = 0x16,
	SSAM_SSH_TC_BKL  = 0x17,
	SSAM_SSH_TC_TAM  = 0x18,
	SSAM_SSH_TC_ACC0 = 0x19,
	SSAM_SSH_TC_UFI  = 0x1a,
	SSAM_SSH_TC_USC  = 0x1b,
	SSAM_SSH_TC_PEN  = 0x1c,
	SSAM_SSH_TC_VID  = 0x1d,
	SSAM_SSH_TC_AUD  = 0x1e,
	SSAM_SSH_TC_SMC  = 0x1f,
	SSAM_SSH_TC_KPD  = 0x20,
	SSAM_SSH_TC_REG  = 0x21,  /* Extended event registry. */
	SSAM_SSH_TC_SPT  = 0x22,
	SSAM_SSH_TC_SYS  = 0x23,
	SSAM_SSH_TC_ACC1 = 0x24,
	SSAM_SSH_TC_SHB  = 0x25,
	SSAM_SSH_TC_POS  = 0x26,  /* For obtaining Laptop Studio screen position. */
};


/* -- Packet transport layer (ptl). ----------------------------------------- */

/**
 * enum ssh_packet_base_priority - Base priorities for &struct ssh_packet.
 * @SSH_PACKET_PRIORITY_FLUSH: Base priority for flush packets.
 * @SSH_PACKET_PRIORITY_DATA:  Base priority for normal data packets.
 * @SSH_PACKET_PRIORITY_NAK:   Base priority for NAK packets.
 * @SSH_PACKET_PRIORITY_ACK:   Base priority for ACK packets.
 */
enum ssh_packet_base_priority {
	SSH_PACKET_PRIORITY_FLUSH = 0,	/* same as DATA to sequence flush */
	SSH_PACKET_PRIORITY_DATA  = 0,
	SSH_PACKET_PRIORITY_NAK   = 1,
	SSH_PACKET_PRIORITY_ACK   = 2,
};

/*
 * Same as SSH_PACKET_PRIORITY() below, only with actual values.
 */
#define __SSH_PACKET_PRIORITY(base, try) \
	(((base) << 4) | ((try) & 0x0f))

/**
 * SSH_PACKET_PRIORITY() - Compute packet priority from base priority and
 * number of tries.
 * @base: The base priority as suffix of &enum ssh_packet_base_priority, e.g.
 *        ``FLUSH``, ``DATA``, ``ACK``, or ``NAK``.
 * @try:  The number of tries (must be less than 16).
 *
 * Compute the combined packet priority. The combined priority is dominated by
 * the base priority, whereas the number of (re-)tries decides the precedence
 * of packets with the same base priority, giving higher priority to packets
 * that already have more tries.
 *
 * Return: Returns the computed priority as value fitting inside a &u8. A
 * higher number means a higher priority.
 */
#define SSH_PACKET_PRIORITY(base, try) \
	__SSH_PACKET_PRIORITY(SSH_PACKET_PRIORITY_##base, (try))

/**
 * ssh_packet_priority_get_try() - Get number of tries from packet priority.
 * @priority: The packet priority.
 *
 * Return: Returns the number of tries encoded in the specified packet
 * priority.
 */
static inline u8 ssh_packet_priority_get_try(u8 priority)
{
	return priority & 0x0f;
}

/**
 * ssh_packet_priority_get_base - Get base priority from packet priority.
 * @priority: The packet priority.
 *
 * Return: Returns the base priority encoded in the given packet priority.
 */
static inline u8 ssh_packet_priority_get_base(u8 priority)
{
	return (priority & 0xf0) >> 4;
}

enum ssh_packet_flags {
	/* state flags */
	SSH_PACKET_SF_LOCKED_BIT,
	SSH_PACKET_SF_QUEUED_BIT,
	SSH_PACKET_SF_PENDING_BIT,
	SSH_PACKET_SF_TRANSMITTING_BIT,
	SSH_PACKET_SF_TRANSMITTED_BIT,
	SSH_PACKET_SF_ACKED_BIT,
	SSH_PACKET_SF_CANCELED_BIT,
	SSH_PACKET_SF_COMPLETED_BIT,

	/* type flags */
	SSH_PACKET_TY_FLUSH_BIT,
	SSH_PACKET_TY_SEQUENCED_BIT,
	SSH_PACKET_TY_BLOCKING_BIT,

	/* mask for state flags */
	SSH_PACKET_FLAGS_SF_MASK =
		  BIT(SSH_PACKET_SF_LOCKED_BIT)
		| BIT(SSH_PACKET_SF_QUEUED_BIT)
		| BIT(SSH_PACKET_SF_PENDING_BIT)
		| BIT(SSH_PACKET_SF_TRANSMITTING_BIT)
		| BIT(SSH_PACKET_SF_TRANSMITTED_BIT)
		| BIT(SSH_PACKET_SF_ACKED_BIT)
		| BIT(SSH_PACKET_SF_CANCELED_BIT)
		| BIT(SSH_PACKET_SF_COMPLETED_BIT),

	/* mask for type flags */
	SSH_PACKET_FLAGS_TY_MASK =
		  BIT(SSH_PACKET_TY_FLUSH_BIT)
		| BIT(SSH_PACKET_TY_SEQUENCED_BIT)
		| BIT(SSH_PACKET_TY_BLOCKING_BIT),
};

struct ssh_ptl;
struct ssh_packet;

/**
 * struct ssh_packet_ops - Callback operations for a SSH packet.
 * @release:  Function called when the packet reference count reaches zero.
 *            This callback must be relied upon to ensure that the packet has
 *            left the transport system(s).
 * @complete: Function called when the packet is completed, either with
 *            success or failure. In case of failure, the reason for the
 *            failure is indicated by the value of the provided status code
 *            argument. This value will be zero in case of success. Note that
 *            a call to this callback does not guarantee that the packet is
 *            not in use by the transport system any more.
 */
struct ssh_packet_ops {
	void (*release)(struct ssh_packet *p);
	void (*complete)(struct ssh_packet *p, int status);
};

/**
 * struct ssh_packet - SSH transport packet.
 * @ptl:      Pointer to the packet transport layer. May be %NULL if the packet
 *            (or enclosing request) has not been submitted yet.
 * @refcnt:   Reference count of the packet.
 * @priority: Priority of the packet. Must be computed via
 *            SSH_PACKET_PRIORITY(). Must only be accessed while holding the
 *            queue lock after first submission.
 * @data:     Raw message data.
 * @data.len: Length of the raw message data.
 * @data.ptr: Pointer to the raw message data buffer.
 * @state:    State and type flags describing current packet state (dynamic)
 *            and type (static). See &enum ssh_packet_flags for possible
 *            options.
 * @timestamp: Timestamp specifying when the latest transmission of a
 *            currently pending packet has been started. May be %KTIME_MAX
 *            before or in-between transmission attempts. Used for the packet
 *            timeout implementation. Must only be accessed while holding the
 *            pending lock after first submission.
 * @queue_node:	The list node for the packet queue.
 * @pending_node: The list node for the set of pending packets.
 * @ops:      Packet operations.
 */
struct ssh_packet {
	struct ssh_ptl *ptl;
	struct kref refcnt;

	u8 priority;

	struct {
		size_t len;
		u8 *ptr;
	} data;

	unsigned long state;
	ktime_t timestamp;

	struct list_head queue_node;
	struct list_head pending_node;

	const struct ssh_packet_ops *ops;
};

struct ssh_packet *ssh_packet_get(struct ssh_packet *p);
void ssh_packet_put(struct ssh_packet *p);

/**
 * ssh_packet_set_data() - Set raw message data of packet.
 * @p:   The packet for which the message data should be set.
 * @ptr: Pointer to the memory holding the message data.
 * @len: Length of the message data.
 *
 * Sets the raw message data buffer of the packet to the provided memory. The
 * memory is not copied. Instead, the caller is responsible for management
 * (i.e. allocation and deallocation) of the memory. The caller must ensure
 * that the provided memory is valid and contains a valid SSH message,
 * starting from the time of submission of the packet until the ``release``
 * callback has been called. During this time, the memory may not be altered
 * in any way.
 */
static inline void ssh_packet_set_data(struct ssh_packet *p, u8 *ptr, size_t len)
{
	p->data.ptr = ptr;
	p->data.len = len;
}


/* -- Request transport layer (rtl). ---------------------------------------- */

enum ssh_request_flags {
	/* state flags */
	SSH_REQUEST_SF_LOCKED_BIT,
	SSH_REQUEST_SF_QUEUED_BIT,
	SSH_REQUEST_SF_PENDING_BIT,
	SSH_REQUEST_SF_TRANSMITTING_BIT,
	SSH_REQUEST_SF_TRANSMITTED_BIT,
	SSH_REQUEST_SF_RSPRCVD_BIT,
	SSH_REQUEST_SF_CANCELED_BIT,
	SSH_REQUEST_SF_COMPLETED_BIT,

	/* type flags */
	SSH_REQUEST_TY_FLUSH_BIT,
	SSH_REQUEST_TY_HAS_RESPONSE_BIT,

	/* mask for state flags */
	SSH_REQUEST_FLAGS_SF_MASK =
		  BIT(SSH_REQUEST_SF_LOCKED_BIT)
		| BIT(SSH_REQUEST_SF_QUEUED_BIT)
		| BIT(SSH_REQUEST_SF_PENDING_BIT)
		| BIT(SSH_REQUEST_SF_TRANSMITTING_BIT)
		| BIT(SSH_REQUEST_SF_TRANSMITTED_BIT)
		| BIT(SSH_REQUEST_SF_RSPRCVD_BIT)
		| BIT(SSH_REQUEST_SF_CANCELED_BIT)
		| BIT(SSH_REQUEST_SF_COMPLETED_BIT),

	/* mask for type flags */
	SSH_REQUEST_FLAGS_TY_MASK =
		  BIT(SSH_REQUEST_TY_FLUSH_BIT)
		| BIT(SSH_REQUEST_TY_HAS_RESPONSE_BIT),
};

struct ssh_rtl;
struct ssh_request;

/**
 * struct ssh_request_ops - Callback operations for a SSH request.
 * @release:  Function called when the request's reference count reaches zero.
 *            This callback must be relied upon to ensure that the request has
 *            left the transport systems (both, packet an request systems).
 * @complete: Function called when the request is completed, either with
 *            success or failure. The command data for the request response
 *            is provided via the &struct ssh_command parameter (``cmd``),
 *            the command payload of the request response via the &struct
 *            ssh_span parameter (``data``).
 *
 *            If the request does not have any response or has not been
 *            completed with success, both ``cmd`` and ``data`` parameters will
 *            be NULL. If the request response does not have any command
 *            payload, the ``data`` span will be an empty (zero-length) span.
 *
 *            In case of failure, the reason for the failure is indicated by
 *            the value of the provided status code argument (``status``). This
 *            value will be zero in case of success and a regular errno
 *            otherwise.
 *
 *            Note that a call to this callback does not guarantee that the
 *            request is not in use by the transport systems any more.
 */
struct ssh_request_ops {
	void (*release)(struct ssh_request *rqst);
	void (*complete)(struct ssh_request *rqst,
			 const struct ssh_command *cmd,
			 const struct ssam_span *data, int status);
};

/**
 * struct ssh_request - SSH transport request.
 * @packet: The underlying SSH transport packet.
 * @node:   List node for the request queue and pending set.
 * @state:  State and type flags describing current request state (dynamic)
 *          and type (static). See &enum ssh_request_flags for possible
 *          options.
 * @timestamp: Timestamp specifying when we start waiting on the response of
 *          the request. This is set once the underlying packet has been
 *          completed and may be %KTIME_MAX before that, or when the request
 *          does not expect a response. Used for the request timeout
 *          implementation.
 * @ops:    Request Operations.
 */
struct ssh_request {
	struct ssh_packet packet;
	struct list_head node;

	unsigned long state;
	ktime_t timestamp;

	const struct ssh_request_ops *ops;
};

/**
 * to_ssh_request() - Cast a SSH packet to its enclosing SSH request.
 * @p: The packet to cast.
 *
 * Casts the given &struct ssh_packet to its enclosing &struct ssh_request.
 * The caller is responsible for making sure that the packet is actually
 * wrapped in a &struct ssh_request.
 *
 * Return: Returns the &struct ssh_request wrapping the provided packet.
 */
static inline struct ssh_request *to_ssh_request(struct ssh_packet *p)
{
	return container_of(p, struct ssh_request, packet);
}

/**
 * ssh_request_get() - Increment reference count of request.
 * @r: The request to increment the reference count of.
 *
 * Increments the reference count of the given request by incrementing the
 * reference count of the underlying &struct ssh_packet, enclosed in it.
 *
 * See also ssh_request_put(), ssh_packet_get().
 *
 * Return: Returns the request provided as input.
 */
static inline struct ssh_request *ssh_request_get(struct ssh_request *r)
{
	return r ? to_ssh_request(ssh_packet_get(&r->packet)) : NULL;
}

/**
 * ssh_request_put() - Decrement reference count of request.
 * @r: The request to decrement the reference count of.
 *
 * Decrements the reference count of the given request by decrementing the
 * reference count of the underlying &struct ssh_packet, enclosed in it. If
 * the reference count reaches zero, the ``release`` callback specified in the
 * request's &struct ssh_request_ops, i.e. ``r->ops->release``, will be
 * called.
 *
 * See also ssh_request_get(), ssh_packet_put().
 */
static inline void ssh_request_put(struct ssh_request *r)
{
	if (r)
		ssh_packet_put(&r->packet);
}

/**
 * ssh_request_set_data() - Set raw message data of request.
 * @r:   The request for which the message data should be set.
 * @ptr: Pointer to the memory holding the message data.
 * @len: Length of the message data.
 *
 * Sets the raw message data buffer of the underlying packet to the specified
 * buffer. Does not copy the actual message data, just sets the buffer pointer
 * and length. Refer to ssh_packet_set_data() for more details.
 */
static inline void ssh_request_set_data(struct ssh_request *r, u8 *ptr, size_t len)
{
	ssh_packet_set_data(&r->packet, ptr, len);
}

#endif /* _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H */