path: root/include/uapi/linux/cec.h

/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */
/*
 * cec - HDMI Consumer Electronics Control public header
 *
 * Copyright 2016 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
 */

#ifndef _CEC_UAPI_H
#define _CEC_UAPI_H

#include <linux/types.h>
#include <linux/string.h>

#define CEC_MAX_MSG_SIZE	16

/**
 * struct cec_msg - CEC message structure.
 * @tx_ts:	Timestamp in nanoseconds using CLOCK_MONOTONIC. Set by the
 *		driver when the message transmission has finished.
 * @rx_ts:	Timestamp in nanoseconds using CLOCK_MONOTONIC. Set by the
 *		driver when the message was received.
 * @len:	Length in bytes of the message.
 * @timeout:	The timeout (in ms) that is used to timeout CEC_RECEIVE.
 *		Set to 0 if you want to wait forever. This timeout can also be
 *		used with CEC_TRANSMIT as the timeout for waiting for a reply.
 *		If 0, then it will use a 1 second timeout instead of waiting
 *		forever as is done with CEC_RECEIVE.
 * @sequence:	The framework assigns a sequence number to messages that are
 *		sent. This can be used to track replies to previously sent
 *		messages.
 * @flags:	Set to 0.
 * @msg:	The message payload.
 * @reply:	This field is ignored with CEC_RECEIVE and is only used by
 *		CEC_TRANSMIT. If non-zero, then wait for a reply with this
 *		opcode. Set to CEC_MSG_FEATURE_ABORT if you want to wait for
 *		a possible ABORT reply. If there was an error when sending the
 *		msg or FeatureAbort was returned, then reply is set to 0.
 *		If reply is non-zero upon return, then len/msg are set to
 *		the received message.
 *		If reply is zero upon return and status has the
 *		CEC_TX_STATUS_FEATURE_ABORT bit set, then len/msg are set to
 *		the received feature abort message.
 *		If reply is zero upon return and status has the
 *		CEC_TX_STATUS_MAX_RETRIES bit set, then no reply was seen at
 *		all. If reply is non-zero for CEC_TRANSMIT and the message is a
 *		broadcast, then -EINVAL is returned.
 *		if reply is non-zero, then timeout is set to 1000 (the required
 *		maximum response time).
 * @rx_status:	The message receive status bits. Set by the driver.
 * @tx_status:	The message transmit status bits. Set by the driver.
 * @tx_arb_lost_cnt: The number of 'Arbitration Lost' events. Set by the driver.
 * @tx_nack_cnt: The number of 'Not Acknowledged' events. Set by the driver.
 * @tx_low_drive_cnt: The number of 'Low Drive Detected' events. Set by the
 *		driver.
 * @tx_error_cnt: The number of 'Error' events. Set by the driver.
 */
struct cec_msg {
	__u64 tx_ts;
	__u64 rx_ts;
	__u32 len;
	__u32 timeout;
	__u32 sequence;
	__u32 flags;
	__u8 msg[CEC_MAX_MSG_SIZE];
	__u8 reply;
	__u8 rx_status;
	__u8 tx_status;
	__u8 tx_arb_lost_cnt;
	__u8 tx_nack_cnt;
	__u8 tx_low_drive_cnt;
	__u8 tx_error_cnt;
};

/**
 * cec_msg_initiator - return the initiator's logical address.
 * @msg:	the message structure
 */
static inline __u8 cec_msg_initiator(const struct cec_msg *msg)
{
	return msg->msg[0] >> 4;
}

/**
 * cec_msg_destination - return the destination's logical address.
 * @msg:	the message structure
 */
static inline __u8 cec_msg_destination(const struct cec_msg *msg)
{
	return msg->msg[0] & 0xf;
}

/**
 * cec_msg_opcode - return the opcode of the message, -1 for poll
 * @msg:	the message structure
 */
static inline int cec_msg_opcode(const struct cec_msg *msg)
{
	return msg->len > 1 ? msg->msg[1] : -1;
}

/**
 * cec_msg_is_broadcast - return true if this is a broadcast message.
 * @msg:	the message structure
 */
static inline int cec_msg_is_broadcast(const struct cec_msg *msg)
{
	return (msg->msg[0] & 0xf) == 0xf;
}

/**
 * cec_msg_init - initialize the message structure.
 * @msg:	the message structure
 * @initiator:	the logical address of the initiator
 * @destination:the logical address of the destination (0xf for broadcast)
 *
 * The whole structure is zeroed, the len field is set to 1 (i.e. a poll
 * message) and the initiator and destination are filled in.
 */
static inline void cec_msg_init(struct cec_msg *msg,
				__u8 initiator, __u8 destination)
{
	memset(msg, 0, sizeof(*msg));
	msg->msg[0] = (initiator << 4) | destination;
	msg->len = 1;
}

/**
 * cec_msg_set_reply_to - fill in destination/initiator in a reply message.
 * @msg:	the message structure for the reply
 * @orig:	the original message structure
 *
 * Set the msg destination to the orig initiator and the msg initiator to the
 * orig destination. Note that msg and orig may be the same pointer, in which
 * case the change is done in place.
 *
 * It also zeroes the reply, timeout and flags fields.
 */
static inline void cec_msg_set_reply_to(struct cec_msg *msg,
					struct cec_msg *orig)
{
	/* The destination becomes the initiator and vice versa */
	msg->msg[0] = (cec_msg_destination(orig) << 4) |
		      cec_msg_initiator(orig);
	msg->reply = 0;
	msg->timeout = 0;
	msg->flags = 0;
}

/**
 * cec_msg_recv_is_tx_result - return true if this message contains the
 *			       result of an earlier non-blocking transmit
 * @msg:	the message structure from CEC_RECEIVE
 */
static inline int cec_msg_recv_is_tx_result(const struct cec_msg *msg)
{
	return msg->sequence && msg->tx_status && !msg->rx_status;
}

/**
 * cec_msg_recv_is_rx_result - return true if this message contains the
 *			       reply of an earlier non-blocking transmit
 * @msg:	the message structure from CEC_RECEIVE
 */
static inline int cec_msg_recv_is_rx_result(const struct cec_msg *msg)
{
	return msg->sequence && !msg->tx_status && msg->rx_status;
}

/* cec_msg flags field */
#define CEC_MSG_FL_REPLY_TO_FOLLOWERS	(1 << 0)
#define