aboutsummaryrefslogtreecommitdiffstats
path: root/utils/cec-compliance/cec-compliance.1.in
blob: fa96fb01b1e9b0198d73548b3edf5aca23ce97e3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
.TH "CEC-COMPLIANCE" "1" "August 2016" "v4l-utils @PACKAGE_VERSION@" "User Commands"
.SH NAME
cec-compliance - An application to verify remote CEC devices
.SH SYNOPSIS
.B cec-compliance
[\fI-h\fR] [\fI-d <dev>\fR] [other options]
.SH DESCRIPTION
The cec-compliance utility can be used to test how well remote CEC devices
comply with the CEC specification. It can also be used to test the local
CEC adapter (with the \fI-A\fR option).

By default it will run through all tests, but if one or more of the feature
test options is given, then only those tests will be performed. A set of core
tests is always run.

The CEC adapter needs to be configured before it is used to run tests with
\fBcec-compliance\fR. Use \fBcec-ctl\fR for configuration.

If the CEC adapter has claimed several logical addresses, the test set is run
from each logical address in succession. The remote device needs to report a
valid physical address in order to run tests on it.

When running compliance tests, \fBcec-follower\fR should be run on the same
adapter. \fBcec-follower\fR will reply to messages that are not handled by
\fBcec-compliance\fR. \fBcec-follower\fR will also monitor the device under test
for behaviors that are not compliant with the specification. Before each test-run
\fBcec-follower\fR should be restarted if it is already running, to initialize
the emulated device with a clean and known initial state.

Some tests require interactive mode (with the \fI-i\fR option) to confirm that
the test passed. When in interactive mode, the user is asked to observe or
perform actions on the remote device. Some tests also give conclusive test
results when run in interactive mode.

When testing the local CEC adapter's compliance with the CEC API, there must be
at least one remote device present in order to test transmitting and receiving.

The compliance tests can have several possible outcomes besides passing and
failing:

    OK                  The test passed.

    OK (Unexpected)     The test passed, but it was unexpected for the device
                        under test to support it. This might for example occur
                        when a TV replies to messages in the Deck Control
                        feature.

    OK (Not Supported)  The feature that was tested is not supported by the
                        device under test, and that feature was not mandatory for
                        the device to pass.

    OK (Presumed)       Nothing went wrong during the test, but the test cannot
                        positively verify that the required effects of the test
                        occurred. The test runner should verify that the test
                        passed by manually observing the device under test. This
                        is typically the test result for tests that send
                        messages that are not replied to, but which induce some
                        side effect on the device under test, such as a TV
                        switching to another input or sending a Remote Control
                        command.

    OK (Refused)        The device supports the feature or message being tested,
                        but responded <Feature Abort> ["Refused"] to indicate
                        that it cannot perform the given operation. This might
                        for example occur when trying to test the One Touch
                        Record feature on a TV with copy protection enabled.

    FAIL                The test failed and was expected to pass on the device.

Some tests depend on other tests being successful. These are not run if the
tests they depend on failed, and they will not be shown in the test listing.
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-device\fR \fI<dev>\fR
Use device <dev> as the CEC device. If <dev> is a number, then /dev/cec<dev> is used.
.TP
\fB\-D\fR, \fB\-\-driver\fR \fI<drv>\fR
Use a cec device that has driver name \fI<drv>\fR, as returned by the CEC_ADAP_G_CAPS ioctl.
This option can be combined with \fB\-a\fR to uniquely identify a CEC device without
having to rely on the device node number.
.TP
\fB\-a\fR, \fB\-\-adapter\fR \fI<adap-name>\fR
Use a cec device that has adapter name \fI<adap-name>\fR, as returned by the CEC_ADAP_G_CAPS ioctl.
This option can be combined with \fB\-D\fR to uniquely identify a CEC device without
having to rely on the device node number.
.TP
\fB\-E\fR, \fB\-\-exit\-on\-fail\fR
Exit this application when the first failure occurs instead of continuing
with a possible inconsistent state.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Turn on verbose reporting.
.TP
\fB\-w\fR, \fB\-\-wall\-clock\fR
Show timestamps as wall-clock time. This also turns on verbose reporting. 
.TP
\fB\-T\fR, \fB\-\-trace\fR
Trace all called ioctls. Useful for debugging.
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints the help message.
.TP
\fB\-W\fR, \fB\-\-exit\-on\-warn\fR
Exit this application when the first warning occurs instead of continuing.
.TP
\fB\-s\fR, \fB\-\-skip\-info\fR
Skip the Driver Info output section.
.TP
\fB\-C\fR, \fB\-\-color\fR \fI<when>\fR
Highlight OK/warn/fail/FAIL strings with colors. OK is marked green, warn is
marked bold, and fail/FAIL are marked bright red if enabled. \fI<when>\fR can
be \fIalways\fR, \fInever\fR, or \fIauto\fR (the default).
.TP
\fB\-n\fR, \fB\-\-no\-warnings\fR
Turn off warning messages.
.TP
\fB\-r\fR, \fB\-\-remote\fR \fI<la>\fR
As initiator test the remote logical address <la> or all LAs if no LA was given.
.TP
\fB\-i\fR, \fB\-\-interactive\fR
Interactive mode when doing remote tests.
.TP
\fB\-R\fR, \fB\-\-reply\-threshold\fR \fI<timeout>\fR
Warn if replies take longer than this threshold (default 1000ms).
.TP
\fB\-t\fR, \fB\-\-timeout\fR \fI<secs>\fR
Set the standby/resume timeout to the given number of seconds. Default is 60s.
.TP
\fB\-A\fR, \fB\-\-test\-adapter\fR
Test the CEC adapter API
.TP
\fB\-\-test\-core\fR
Test the core functionality
.TP
\fB\-\-test\-audio\-rate\-control\fR
Test the Audio Rate Control feature
.TP
\fB\-\-test\-audio\-return\-channel\-control\fR
Test the Audio Return Channel Control feature
.TP
\fB\-\-test\-capability\-discovery\-and\-control\fR
Test the Capability Discovery and Control feature
.TP
\fB\-\-test\-deck\-control\fR
Test the Deck Control feature
.TP
\fB\-\-test\-device\-menu\-control\fR
Test the Device Menu Control feature
.TP
\fB\-\-test\-device\-osd\-transfer\fR
Test the Device OSD Transfer feature
.TP
\fB\-\-test\-dynamic\-audio\-lipsync\fR
Test the Dynamic Audio Lipsync feature
.TP
\fB\-\-test\-osd\-display\fR
Test the OSD Display feature
.TP
\fB\-\-test\-one\-touch\-play\fR
Test the One Touch Play feature
.TP
\fB\-\-test\-one\-touch\-record\fR
Test the One Touch Record feature
.TP
\fB\-\-test\-power\-status\fR
Test the Power Status feature
.TP
\fB\-\-test\-remote\-control\-passthrough\fR
Test the Remote Control Passthrough feature
.TP
\fB\-\-test\-routing\-control\fR
Test the Routing Control feature
.TP
\fB\-\-test\-system\-audio\-control\fR
Test the System Audio Control feature
.TP
\fB\-\-test\-system\-information\fR
Test the System Information feature
.TP
\fB\-\-test\-timer\-programming\fR
Test the Timer Programming feature
.TP
\fB\-\-test\-tuner\-control\fR
Test the Tuner Control feature
.TP
\fB\-\-test\-vendor\-specific\-commands\fR
Test the Vendor Specific Commands feature
.TP
\fB\-\-test\-standby\-resume\fR
Test standby and resume functionality. This will activate
testing of Standby, Give Device Power Status and One Touch Play.

.SH EXIT STATUS
On success, it returns 0. Otherwise, it will return the error code.
.SH EXAMPLE
We want to test the compliance of a TV when it is interacting with a Playback
device. The device node of the CEC adapter which the TV is connected to is
/dev/cec1.

The local CEC adapter first needs to be configured as a Playback device, and it
must have an appropriate physical address. It is important that the physical
address is correct, so as to not confuse the device under test. For example, if
the CEC adapter is connected to the first input of the TV, the physical address
1.0.0.0 should generally be used.

    cec-ctl -d1 --playback --phys-addr 1.0.0.0

Most CEC adapters will automatically detect the physical address, and for those
adapters the \fI--phys-addr\fR option is not needed.

Next, \fBcec-follower\fR also has to be started on the same device:

    cec-follower -d1

\fBcec-compliance\fR can now be run towards the TV by supplying the \fI-r\fR
option with the logical address 0:

    cec-compliance -d1 -r0
.SH BUGS
This manual page is a work in progress.

Bug reports or questions about this utility should be sent to the linux-media@vger.kernel.org
mailinglist.
.SH SEE ALSO
\fBcec-follower\fR(1), \fBcec-ctl\fR(1)

Privacy Policy