/* 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 <[email protected]> */ #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 { … }; /** * 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 { … } __packed; static_assert(…); /* * 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 … /** * 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 { … }; /** * 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 { … } __packed; static_assert(…); /* * 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_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 … /* * 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_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_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_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) … /** * 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) … /* * SSH_MSG_SYN - SSH message synchronization (SYN) bytes as u16. */ #define SSH_MSG_SYN … /** * 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) { … } /* * 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 … /* * SSH_NUM_TARGETS - The number of communication targets used in the protocol. */ #define SSH_NUM_TARGETS … /** * 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) { … } /** * 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) { … } /** * 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) { … } /** * 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) { … } /** * 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) { … } /** * 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) { … } /** * 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 { … }; /** * 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 { … }; /* * 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 { … }; /* -- 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 { … }; /* * Same as SSH_PACKET_PRIORITY() below, only with actual values. */ #define __SSH_PACKET_PRIORITY(base, try) … /** * 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_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) { … } /** * 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) { … } enum ssh_packet_flags { … }; 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 { … }; /** * 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_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) { … } /* -- Request transport layer (rtl). ---------------------------------------- */ enum ssh_request_flags { … }; 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 { … }; /** * 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 { … }; /** * 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) { … } /** * 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) { … } /** * 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) { … } /** * 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) { … } #endif /* _LINUX_SURFACE_AGGREGATOR_SERIAL_HUB_H */
Codebase Browser
linux