linux/surface_aggregator/serial_hub.h

1 /* SPDX-License-Identifier: GPL-2.0+ */
5  * Lower-level communication layers and SSH protocol definitions for the
7  * packet- and request-based communication with the SSAM EC via SSH.
9  * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
15 #include <linux/crc-itu-t.h>
22 /* -- Data structures for SAM-over-SSH communication. ----------------------- */
25  * enum ssh_frame_type - Frame types for SSH frames.
42  *	For command-type payloads, this can also mean that the command is
53  * struct ssh_frame - SSH communication frame.
68  * SSH_FRAME_MAX_PAYLOAD_SIZE - Maximum SSH frame payload length in bytes.
76  * enum ssh_payload_type - Type indicator for the SSH payload.
85  * struct ssh_command - Payload of a command-type frame.
109  * SSH_COMMAND_MAX_PAYLOAD_SIZE - Maximum SSH command payload length in bytes.
115 	(SSH_FRAME_MAX_PAYLOAD_SIZE - sizeof(struct ssh_command))
118  * SSH_MSG_LEN_BASE - Base-length of a SSH message.
126  * SSH_MSG_LEN_CTRL - Length of a SSH control message.
134  * SSH_MESSAGE_LENGTH() - Compute length of SSH message.
142  * SSH_COMMAND_MESSAGE_LENGTH() - Compute length of SSH command message.
152  * SSH_MSGOFFSET_FRAME() - Compute offset in SSH message to specified field in
154  * @field: The field for which the offset should be computed.
156  * Return: Returns the offset of the specified &struct ssh_frame field in the
164  * SSH_MSGOFFSET_COMMAND() - Compute offset in SSH message to specified field
166  * @field: The field for which the offset should be computed.
168  * Return: Returns the offset of the specified &struct ssh_command field in
177  * SSH_MSG_SYN - SSH message synchronization (SYN) bytes as u16.
182  * ssh_crc() - Compute CRC for SSH messages.
195  * SSH_NUM_EVENTS - The number of reserved event IDs.
205  * SSH_NUM_TARGETS - The number of communication targets used in the protocol.
210  * ssh_rqid_next_valid() - Return the next valid request ID.
223  * ssh_rqid_to_event() - Convert request ID to its corresponding event ID.
228 	return rqid - 1u;  in ssh_rqid_to_event()
232  * ssh_rqid_is_event() - Check if given request ID is a valid event ID.
241  * ssh_tc_to_rqid() - Convert target category to its corresponding request ID.
250  * ssh_tid_to_index() - Convert target ID to its corresponding target index.
255 	return tid - 1u;  in ssh_tid_to_index()
259  * ssh_tid_is_valid() - Check if target ID is valid/supported.
268  * struct ssam_span - Reference to a buffer region.
272  * A reference to a (non-owned) buffer segment, consisting of pointer and
273  * length. Use of this struct indicates non-owned data, i.e. data of which the
274  * life-time is managed (i.e. it is allocated/freed) via another pointer.
282  * enum ssam_ssh_tid - Target/source IDs for Serial Hub messages.
310 	SSAM_SSH_TC_SAM  = 0x01,  /* Generic system functionality, real-time clock. */
351 /* -- Packet transport layer (ptl). ----------------------------------------- */
354  * enum ssh_packet_base_priority - Base priorities for &struct ssh_packet.
355  * @SSH_PACKET_PRIORITY_FLUSH: Base priority for flush packets.
356  * @SSH_PACKET_PRIORITY_DATA:  Base priority for normal data packets.
357  * @SSH_PACKET_PRIORITY_NAK:   Base priority for NAK packets.
358  * @SSH_PACKET_PRIORITY_ACK:   Base priority for ACK packets.
370 #define __SSH_PACKET_PRIORITY(base, try) \  argument
371 	(((base) << 4) | ((try) & 0x0f))
374  * SSH_PACKET_PRIORITY() - Compute packet priority from base priority and
376  * @base: The base priority as suffix of &enum ssh_packet_base_priority, e.g.
381  * the base priority, whereas the number of (re-)tries decides the precedence
382  * of packets with the same base priority, giving higher priority to packets
388 #define SSH_PACKET_PRIORITY(base, try) \  argument
389 	__SSH_PACKET_PRIORITY(SSH_PACKET_PRIORITY_##base, (try))
392  * ssh_packet_priority_get_try() - Get number of tries from packet priority.
404  * ssh_packet_priority_get_base - Get base priority from packet priority.
407  * Return: Returns the base priority encoded in the given packet priority.
452  * struct ssh_packet_ops - Callback operations for a SSH packet.
469  * struct ssh_packet - SSH transport packet.
470  * @ptl:      Pointer to the packet transport layer. May be %NULL if the packet
484  *            before or in-between transmission attempts. Used for the packet
515  * ssh_packet_set_data() - Set raw message data of packet.
530 	p->data.ptr = ptr;  in ssh_packet_set_data()
531 	p->data.len = len;  in ssh_packet_set_data()
535 /* -- Request transport layer (rtl). ---------------------------------------- */
573  * struct ssh_request_ops - Callback operations for a SSH request.
586  *            payload, the ``data`` span will be an empty (zero-length) span.
604  * struct ssh_request - SSH transport request.
628  * to_ssh_request() - Cast a SSH packet to its enclosing SSH request.
643  * ssh_request_get() - Increment reference count of request.
655 	return r ? to_ssh_request(ssh_packet_get(&r->packet)) : NULL;  in ssh_request_get()
659  * ssh_request_put() - Decrement reference count of request.
665  * request's &struct ssh_request_ops, i.e. ``r->ops->release``, will be
673 		ssh_packet_put(&r->packet);  in ssh_request_put()
677  * ssh_request_set_data() - Set raw message data of request.
688 	ssh_packet_set_data(&r->packet, ptr, len);  in ssh_request_set_data()