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