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