About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / cec.txt

Custom Search

Based on kernel version 4.8. Page generated on 2016-10-06 23:10 EST.

1	CEC Kernel Support
2	==================
4	The CEC framework provides a unified kernel interface for use with HDMI CEC
5	hardware. It is designed to handle a multiple types of hardware (receivers,
6	transmitters, USB dongles). The framework also gives the option to decide
7	what to do in the kernel driver and what should be handled by userspace
8	applications. In addition it integrates the remote control passthrough
9	feature into the kernel's remote control framework.
12	The CEC Protocol
13	----------------
15	The CEC protocol enables consumer electronic devices to communicate with each
16	other through the HDMI connection. The protocol uses logical addresses in the
17	communication. The logical address is strictly connected with the functionality
18	provided by the device. The TV acting as the communication hub is always
19	assigned address 0. The physical address is determined by the physical
20	connection between devices.
22	The CEC framework described here is up to date with the CEC 2.0 specification.
23	It is documented in the HDMI 1.4 specification with the new 2.0 bits documented
24	in the HDMI 2.0 specification. But for most of the features the freely available
25	HDMI 1.3a specification is sufficient:
27	http://www.microprocessor.org/HDMISpecification13a.pdf
30	The Kernel Interface
31	====================
33	CEC Adapter
34	-----------
36	The struct cec_adapter represents the CEC adapter hardware. It is created by
37	calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
39	struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops,
40		       void *priv, const char *name, u32 caps, u8 available_las,
41		       struct device *parent);
42	void cec_delete_adapter(struct cec_adapter *adap);
44	To create an adapter you need to pass the following information:
46	ops: adapter operations which are called by the CEC framework and that you
47	have to implement.
49	priv: will be stored in adap->priv and can be used by the adapter ops.
51	name: the name of the CEC adapter. Note: this name will be copied.
53	caps: capabilities of the CEC adapter. These capabilities determine the
54		capabilities of the hardware and which parts are to be handled
55		by userspace and which parts are handled by kernelspace. The
56		capabilities are returned by CEC_ADAP_G_CAPS.
58	available_las: the number of simultaneous logical addresses that this
59		adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
61	parent: the parent device.
64	To register the /dev/cecX device node and the remote control device (if
65	CEC_CAP_RC is set) you call:
67	int cec_register_adapter(struct cec_adapter *adap);
69	To unregister the devices call:
71	void cec_unregister_adapter(struct cec_adapter *adap);
73	Note: if cec_register_adapter() fails, then call cec_delete_adapter() to
74	clean up. But if cec_register_adapter() succeeded, then only call
75	cec_unregister_adapter() to clean up, never cec_delete_adapter(). The
76	unregister function will delete the adapter automatically once the last user
77	of that /dev/cecX device has closed its file handle.
80	Implementing the Low-Level CEC Adapter
81	--------------------------------------
83	The following low-level adapter operations have to be implemented in
84	your driver:
86	struct cec_adap_ops {
87		/* Low-level callbacks */
88		int (*adap_enable)(struct cec_adapter *adap, bool enable);
89		int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
90		int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
91		int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
92				     u32 signal_free_time, struct cec_msg *msg);
93		void (*adap_log_status)(struct cec_adapter *adap);
95		/* High-level callbacks */
96		...
97	};
99	The three low-level ops deal with various aspects of controlling the CEC adapter
100	hardware:
103	To enable/disable the hardware:
105		int (*adap_enable)(struct cec_adapter *adap, bool enable);
107	This callback enables or disables the CEC hardware. Enabling the CEC hardware
108	means powering it up in a state where no logical addresses are claimed. This
109	op assumes that the physical address (adap->phys_addr) is valid when enable is
110	true and will not change while the CEC adapter remains enabled. The initial
111	state of the CEC adapter after calling cec_allocate_adapter() is disabled.
113	Note that adap_enable must return 0 if enable is false.
116	To enable/disable the 'monitor all' mode:
118		int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
120	If enabled, then the adapter should be put in a mode to also monitor messages
121	that not for us. Not all hardware supports this and this function is only
122	called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
123	(some hardware may always be in 'monitor all' mode).
125	Note that adap_monitor_all_enable must return 0 if enable is false.
128	To program a new logical address:
130		int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
132	If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
133	are to be erased. Otherwise the given logical address should be programmed.
134	If the maximum number of available logical addresses is exceeded, then it
135	should return -ENXIO. Once a logical address is programmed the CEC hardware
136	can receive directed messages to that address.
138	Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.
141	To transmit a new message:
143		int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
144				     u32 signal_free_time, struct cec_msg *msg);
146	This transmits a new message. The attempts argument is the suggested number of
147	attempts for the transmit.
149	The signal_free_time is the number of data bit periods that the adapter should
150	wait when the line is free before attempting to send a message. This value
151	depends on whether this transmit is a retry, a message from a new initiator or
152	a new message for the same initiator. Most hardware will handle this
153	automatically, but in some cases this information is needed.
155	The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
156	microseconds (one data bit period is 2.4 ms).
159	To log the current CEC hardware status:
161		void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
163	This optional callback can be used to show the status of the CEC hardware.
164	The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status
167	Your adapter driver will also have to react to events (typically interrupt
168	driven) by calling into the framework in the following situations:
170	When a transmit finished (successfully or otherwise):
172	void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
173			       u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
175	The status can be one of:
177	CEC_TX_STATUS_OK: the transmit was successful.
178	CEC_TX_STATUS_ARB_LOST: arbitration was lost: another CEC initiator
179	took control of the CEC line and you lost the arbitration.
180	CEC_TX_STATUS_NACK: the message was nacked (for a directed message) or
181	acked (for a broadcast message). A retransmission is needed.
182	CEC_TX_STATUS_LOW_DRIVE: low drive was detected on the CEC bus. This
183	indicates that a follower detected an error on the bus and requested a
184	retransmission.
185	CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of
186	the previous two if the hardware cannot differentiate or something else
187	entirely.
188	CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after
189	trying multiple times. Should only be set by the driver if it has hardware
190	support for retrying messages. If set, then the framework assumes that it
191	doesn't have to make another attempt to transmit the message since the
192	hardware did that already.
194	The *_cnt arguments are the number of error conditions that were seen.
195	This may be 0 if no information is available. Drivers that do not support
196	hardware retry can just set the counter corresponding to the transmit error
197	to 1, if the hardware does support retry then either set these counters to
198	0 if the hardware provides no feedback of which errors occurred and how many
199	times, or fill in the correct values as reported by the hardware.
201	When a CEC message was received:
203	void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
205	Speaks for itself.
207	Implementing the High-Level CEC Adapter
208	---------------------------------------
210	The low-level operations drive the hardware, the high-level operations are
211	CEC protocol driven. The following high-level callbacks are available:
213	struct cec_adap_ops {
214		/* Low-level callbacks */
215		...
217		/* High-level CEC message callback */
218		int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
219	};
221	The received() callback allows the driver to optionally handle a newly
222	received CEC message
224		int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
226	If the driver wants to process a CEC message, then it can implement this
227	callback. If it doesn't want to handle this message, then it should return
228	-ENOMSG, otherwise the CEC framework assumes it processed this message and
229	it will not no anything with it.
232	CEC framework functions
233	-----------------------
235	CEC Adapter drivers can call the following CEC framework functions:
237	int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
238			     bool block);
240	Transmit a CEC message. If block is true, then wait until the message has been
241	transmitted, otherwise just queue it and return.
243	void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block);
245	Change the physical address. This function will set adap->phys_addr and
246	send an event if it has changed. If cec_s_log_addrs() has been called and
247	the physical address has become valid, then the CEC framework will start
248	claiming the logical addresses. If block is true, then this function won't
249	return until this process has finished.
251	When the physical address is set to a valid value the CEC adapter will
252	be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
253	then the CEC adapter will be disabled. If you change a valid physical address
254	to another valid physical address, then this function will first set the
255	address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
257	int cec_s_log_addrs(struct cec_adapter *adap,
258			    struct cec_log_addrs *log_addrs, bool block);
260	Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
261	is set. If block is true, then wait until the logical addresses have been
262	claimed, otherwise just queue it and return. To unconfigure all logical
263	addresses call this function with log_addrs set to NULL or with
264	log_addrs->num_log_addrs set to 0. The block argument is ignored when
265	unconfiguring. This function will just return if the physical address is
266	invalid. Once the physical address becomes valid, then the framework will
267	attempt to claim these logical addresses.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.