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