1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3 .. _cec_pin_error_inj:
4
5 CEC Pin Framework Error Injection
6 =================================
7
8 The CEC Pin Framework is a core CEC framework for CEC hardware that only
9 has low-level support for the CEC bus. Most hardware today will have
10 high-level CEC support where the hardware deals with driving the CEC bus,
11 but some older devices aren't that fancy. However, this framework also
12 allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and
13 you have now made a CEC adapter.
14
15 What makes doing this so interesting is that since we have full control
16 over the bus it is easy to support error injection. This is ideal to
17 test how well CEC adapters can handle error conditions.
18
19 Currently only the cec-gpio driver (when the CEC line is directly
20 connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver
21 support this framework.
22
23 If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available
24 through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is
25 now an ``error-inj`` file.
26
27 .. note::
28
29 The error injection commands are not a stable ABI and may change in the
30 future.
31
32 With ``cat error-inj`` you can see both the possible commands and the current
33 error injection status::
34
35 $ cat /sys/kernel/debug/cec/cec0/error-inj
36 # Clear error injections:
37 # clear clear all rx and tx error injections
38 # rx-clear clear all rx error injections
39 # tx-clear clear all tx error injections
40 # <op> clear clear all rx and tx error injections for <op>
41 # <op> rx-clear clear all rx error injections for <op>
42 # <op> tx-clear clear all tx error injections for <op>
43 #
44 # RX error injection:
45 # <op>[,<mode>] rx-nack NACK the message instead of sending an ACK
46 # <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position
47 # <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message
48 # <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message
49 # any[,<mode>] rx-arb-lost [<poll>] generate a POLL message to trigger an arbitration lost
50 #
51 # TX error injection settings:
52 # tx-ignore-nack-until-eom ignore early NACKs until EOM
53 # tx-custom-low-usecs <usecs> define the 'low' time for the custom pulse
54 # tx-custom-high-usecs <usecs> define the 'high' time for the custom pulse
55 # tx-custom-pulse transmit the custom pulse once the bus is idle
56 #
57 # TX error injection:
58 # <op>[,<mode>] tx-no-eom don't set the EOM bit
59 # <op>[,<mode>] tx-early-eom set the EOM bit one byte too soon
60 # <op>[,<mode>] tx-add-bytes <num> append <num> (1-255) spurious bytes to the message
61 # <op>[,<mode>] tx-remove-byte drop the last byte from the message
62 # <op>[,<mode>] tx-short-bit <bit> make this bit shorter than allowed
63 # <op>[,<mode>] tx-long-bit <bit> make this bit longer than allowed
64 # <op>[,<mode>] tx-custom-bit <bit> send the custom pulse instead of this bit
65 # <op>[,<mode>] tx-short-start send a start pulse that's too short
66 # <op>[,<mode>] tx-long-start send a start pulse that's too long
67 # <op>[,<mode>] tx-custom-start send the custom pulse instead of the start pulse
68 # <op>[,<mode>] tx-last-bit <bit> stop sending after this bit
69 # <op>[,<mode>] tx-low-drive <bit> force a low-drive condition at this bit position
70 #
71 # <op> CEC message opcode (0-255) or 'any'
72 # <mode> 'once' (default), 'always', 'toggle' or 'off'
73 # <bit> CEC message bit (0-159)
74 # 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK
75 # <poll> CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f)
76 # <usecs> microseconds (0-10000000, default 1000)
77
78 clear
79
80 You can write error injection commands to ``error-inj`` using
81 ``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj``
82 output contains the current error commands. You can save the output to a file
83 and use it as an input to ``error-inj`` later.
84
85 Basic Syntax
86 ------------
87
88 Leading spaces/tabs are ignored. If the next character is a ``#`` or the end
89 of the line was reached, then the whole line is ignored. Otherwise a command
90 is expected.
91
92 The error injection commands fall in two main groups: those relating to
93 receiving CEC messages and those relating to transmitting CEC messages. In
94 addition, there are commands to clear existing error injection commands and
95 to create custom pulses on the CEC bus.
96
97 Most error injection commands can be executed for specific CEC opcodes or for
98 all opcodes (``any``). Each command also has a 'mode' which can be ``off``
99 (can be used to turn off an existing error injection command), ``once``
100 (the default) which will trigger the error injection only once for the next
101 received or transmitted message, ``always`` to always trigger the error
102 injection and ``toggle`` to toggle the error injection on or off for every
103 transmit or receive.
104
105 So '``any rx-nack``' will NACK the next received CEC message,
106 '``any,always rx-nack``' will NACK all received CEC messages and
107 '``0x82,toggle rx-nack``' will only NACK if an Active Source message was
108 received and do that only for every other received message.
109
110 After an error was injected with mode ``once`` the error injection command
111 is cleared automatically, so ``once`` is a one-time deal.
112
113 All combinations of ``<op>`` and error injection commands can co-exist. So
114 this is fine::
115
116 0x9e tx-add-bytes 1
117 0x9e tx-early-eom
118 0x9f tx-add-bytes 2
119 any rx-nack
120
121 All four error injection commands will be active simultaneously.
122
123 However, if the same ``<op>`` and command combination is specified,
124 but with different arguments::
125
126 0x9e tx-add-bytes 1
127 0x9e tx-add-bytes 2
128
129 Then the second will overwrite the first.
130
131 Clear Error Injections
132 ----------------------
133
134 ``clear``
135 Clear all error injections.
136
137 ``rx-clear``
138 Clear all receive error injections
139
140 ``tx-clear``
141 Clear all transmit error injections
142
143 ``<op> clear``
144 Clear all error injections for the given opcode.
145
146 ``<op> rx-clear``
147 Clear all receive error injections for the given opcode.
148
149 ``<op> tx-clear``
150 Clear all transmit error injections for the given opcode.
151
152 Receive Messages
153 ----------------
154
155 ``<op>[,<mode>] rx-nack``
156 NACK broadcast messages and messages directed to this CEC adapter.
157 Every byte of the message will be NACKed in case the transmitter
158 keeps transmitting after the first byte was NACKed.
159
160 ``<op>[,<mode>] rx-low-drive <bit>``
161 Force a Low Drive condition at this bit position. If <op> specifies
162 a specific CEC opcode then the bit position must be at least 18,
163 otherwise the opcode hasn't been received yet. This tests if the
164 transmitter can handle the Low Drive condition correctly and reports
165 the error correctly. Note that a Low Drive in the first 4 bits can also
166 be interpreted as an Arbitration Lost condition by the transmitter.
167 This is implementation dependent.
168
169 ``<op>[,<mode>] rx-add-byte``
170 Add a spurious 0x55 byte to the received CEC message, provided
171 the message was 15 bytes long or less. This is useful to test
172 the high-level protocol since spurious bytes should be ignored.
173
174 ``<op>[,<mode>] rx-remove-byte``
175 Remove the last byte from the received CEC message, provided it
176 was at least 2 bytes long. This is useful to test the high-level
177 protocol since messages that are too short should be ignored.
178
179 ``<op>[,<mode>] rx-arb-lost <poll>``
180 Generate a POLL message to trigger an Arbitration Lost condition.
181 This command is only allowed for ``<op>`` values of ``next`` or ``all``.
182 As soon as a start bit has been received the CEC adapter will switch
183 to transmit mode and it will transmit a POLL message. By default this is
184 0x0f, but it can also be specified explicitly via the ``<poll>`` argument.
185
186 This command can be used to test the Arbitration Lost condition in
187 the remote CEC transmitter. Arbitration happens when two CEC adapters
188 start sending a message at the same time. In that case the initiator
189 with the most leading zeroes wins and the other transmitter has to
190 stop transmitting ('Arbitration Lost'). This is very hard to test,
191 except by using this error injection command.
192
193 This does not work if the remote CEC transmitter has logical address
194 0 ('TV') since that will always win.
195
196 Transmit Messages
197 -----------------
198
199 ``tx-ignore-nack-until-eom``
200 This setting changes the behavior of transmitting CEC messages. Normally
201 as soon as the receiver NACKs a byte the transmit will stop, but the
202 specification also allows that the full message is transmitted and only
203 at the end will the transmitter look at the ACK bit. This is not
204 recommended behavior since there is no point in keeping the CEC bus busy
205 for longer than is strictly needed. Especially given how slow the bus is.
206
207 This setting can be used to test how well a receiver deals with
208 transmitters that ignore NACKs until the very end of the message.
209
210 ``<op>[,<mode>] tx-no-eom``
211 Don't set the EOM bit. Normally the last byte of the message has the EOM
212 (End-Of-Message) bit set. With this command the transmit will just stop
213 without ever sending an EOM. This can be used to test how a receiver
214 handles this case. Normally receivers have a time-out after which
215 they will go back to the Idle state.
216
217 ``<op>[,<mode>] tx-early-eom``
218 Set the EOM bit one byte too soon. This obviously only works for messages
219 of two bytes or more. The EOM bit will be set for the second-to-last byte
220 and not for the final byte. The receiver should ignore the last byte in
221 this case. Since the resulting message is likely to be too short for this
222 same reason the whole message is typically ignored. The receiver should be
223 in Idle state after the last byte was transmitted.
224
225 ``<op>[,<mode>] tx-add-bytes <num>``
226 Append ``<num>`` (1-255) spurious bytes to the message. The extra bytes
227 have the value of the byte position in the message. So if you transmit a
228 two byte message (e.g. a Get CEC Version message) and add 2 bytes, then
229 the full message received by the remote CEC adapter is
230 ``0x40 0x9f 0x02 0x03``.
231
232 This command can be used to test buffer overflows in the receiver. E.g.
233 what does it do when it receives more than the maximum message size of 16
234 bytes.
235
236 ``<op>[,<mode>] tx-remove-byte``
237 Drop the last byte from the message, provided the message is at least
238 two bytes long. The receiver should ignore messages that are too short.
239
240 ``<op>[,<mode>] tx-short-bit <bit>``
241 Make this bit period shorter than allowed. The bit position cannot be
242 an Ack bit. If <op> specifies a specific CEC opcode then the bit position
243 must be at least 18, otherwise the opcode hasn't been received yet.
244 Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
245 With this command the period of this bit is 1.8 milliseconds, this is
246 done by reducing the time the CEC bus is high. This bit period is less
247 than is allowed and the receiver should respond with a Low Drive
248 condition.
249
250 This command is ignored for 0 bits in bit positions 0 to 3. This is
251 because the receiver also looks for an Arbitration Lost condition in
252 those first four bits and it is undefined what will happen if it
253 sees a too-short 0 bit.
254
255 ``<op>[,<mode>] tx-long-bit <bit>``
256 Make this bit period longer than is valid. The bit position cannot be
257 an Ack bit. If <op> specifies a specific CEC opcode then the bit position
258 must be at least 18, otherwise the opcode hasn't been received yet.
259 Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
260 With this command the period of this bit is 2.9 milliseconds, this is
261 done by increasing the time the CEC bus is high.
262
263 Even though this bit period is longer than is valid it is undefined what
264 a receiver will do. It might just accept it, or it might time out and
265 return to Idle state. Unfortunately the CEC specification is silent about
266 this.
267
268 This command is ignored for 0 bits in bit positions 0 to 3. This is
269 because the receiver also looks for an Arbitration Lost condition in
270 those first four bits and it is undefined what will happen if it
271 sees a too-long 0 bit.
272
273 ``<op>[,<mode>] tx-short-start``
274 Make this start bit period shorter than allowed. Normally the period of
275 a start bit is between 4.3 and 4.7 milliseconds. With this command the
276 period of the start bit is 4.1 milliseconds, this is done by reducing
277 the time the CEC bus is high. This start bit period is less than is
278 allowed and the receiver should return to Idle state when this is detected.
279
280 ``<op>[,<mode>] tx-long-start``
281 Make this start bit period longer than is valid. Normally the period of
282 a start bit is between 4.3 and 4.7 milliseconds. With this command the
283 period of the start bit is 5 milliseconds, this is done by increasing
284 the time the CEC bus is high. This start bit period is more than is
285 valid and the receiver should return to Idle state when this is detected.
286
287 Even though this start bit period is longer than is valid it is undefined
288 what a receiver will do. It might just accept it, or it might time out and
289 return to Idle state. Unfortunately the CEC specification is silent about
290 this.
291
292 ``<op>[,<mode>] tx-last-bit <bit>``
293 Just stop transmitting after this bit. If <op> specifies a specific CEC
294 opcode then the bit position must be at least 18, otherwise the opcode
295 hasn't been received yet. This command can be used to test how the receiver
296 reacts when a message just suddenly stops. It should time out and go back
297 to Idle state.
298
299 ``<op>[,<mode>] tx-low-drive <bit>``
300 Force a Low Drive condition at this bit position. If <op> specifies a
301 specific CEC opcode then the bit position must be at least 18, otherwise
302 the opcode hasn't been received yet. This can be used to test how the
303 receiver handles Low Drive conditions. Note that if this happens at bit
304 positions 0-3 the receiver can interpret this as an Arbitration Lost
305 condition. This is implementation dependent.
306
307 Custom Pulses
308 -------------
309
310 ``tx-custom-low-usecs <usecs>``
311 This defines the duration in microseconds that the custom pulse pulls
312 the CEC line low. The default is 1000 microseconds.
313
314 ``tx-custom-high-usecs <usecs>``
315 This defines the duration in microseconds that the custom pulse keeps the
316 CEC line high (unless another CEC adapter pulls it low in that time).
317 The default is 1000 microseconds. The total period of the custom pulse is
318 ``tx-custom-low-usecs + tx-custom-high-usecs``.
319
320 ``<op>[,<mode>] tx-custom-bit <bit>``
321 Send the custom bit instead of a regular data bit. The bit position cannot
322 be an Ack bit. If <op> specifies a specific CEC opcode then the bit
323 position must be at least 18, otherwise the opcode hasn't been received yet.
324
325 ``<op>[,<mode>] tx-custom-start``
326 Send the custom bit instead of a regular start bit.
327
328 ``tx-custom-pulse``
329 Transmit a single custom pulse as soon as the CEC bus is idle.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.