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