1CEC Pin Framework Error Injection 2================================= 3 4The CEC Pin Framework is a core CEC framework for CEC hardware that only 5has low-level support for the CEC bus. Most hardware today will have 6high-level CEC support where the hardware deals with driving the CEC bus, 7but some older devices aren't that fancy. However, this framework also 8allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and 9you have now made a CEC adapter. 10 11What makes doing this so interesting is that since we have full control 12over the bus it is easy to support error injection. This is ideal to 13test how well CEC adapters can handle error conditions. 14 15Currently only the cec-gpio driver (when the CEC line is directly 16connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver 17support this framework. 18 19If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available 20through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is 21now an ``error-inj`` file. 22 23.. note:: 24 25 The error injection commands are not a stable ABI and may change in the 26 future. 27 28With ``cat error-inj`` you can see both the possible commands and the current 29error injection status:: 30 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> 39 # 40 # RX error injection: 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 46 # 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 52 # 53 # TX error injection: 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 66 # 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) 73 74 clear 75 76You can write error injection commands to ``error-inj`` using 77``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj`` 78output contains the current error commands. You can save the output to a file 79and use it as an input to ``error-inj`` later. 80 81Basic Syntax 82------------ 83 84Leading spaces/tabs are ignored. If the next character is a ``#`` or the end 85of the line was reached, then the whole line is ignored. Otherwise a command 86is expected. 87 88The error injection commands fall in two main groups: those relating to 89receiving CEC messages and those relating to transmitting CEC messages. In 90addition, there are commands to clear existing error injection commands and 91to create custom pulses on the CEC bus. 92 93Most error injection commands can be executed for specific CEC opcodes or for 94all 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 97received or transmitted message, ``always`` to always trigger the error 98injection and ``toggle`` to toggle the error injection on or off for every 99transmit or receive. 100 101So '``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 104received and do that only for every other received message. 105 106After an error was injected with mode ``once`` the error injection command 107is cleared automatically, so ``once`` is a one-time deal. 108 109All combinations of ``<op>`` and error injection commands can co-exist. So 110this is fine:: 111 112 0x9e tx-add-bytes 1 113 0x9e tx-early-eom 114 0x9f tx-add-bytes 2 115 any rx-nack 116 117All four error injection commands will be active simultaneously. 118 119However, if the same ``<op>`` and command combination is specified, 120but with different arguments:: 121 122 0x9e tx-add-bytes 1 123 0x9e tx-add-bytes 2 124 125Then the second will overwrite the first. 126 127Clear Error Injections 128---------------------- 129 130``clear`` 131 Clear all error injections. 132 133``rx-clear`` 134 Clear all receive error injections 135 136``tx-clear`` 137 Clear all transmit error injections 138 139``<op> clear`` 140 Clear all error injections for the given opcode. 141 142``<op> rx-clear`` 143 Clear all receive error injections for the given opcode. 144 145``<op> tx-clear`` 146 Clear all transmit error injections for the given opcode. 147 148Receive Messages 149---------------- 150 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. 155 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. 164 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. 169 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. 174 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. 181 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. 188 189 This does not work if the remote CEC transmitter has logical address 190 0 ('TV') since that will always win. 191 192Transmit Messages 193----------------- 194 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. 202 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. 205 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. 212 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. 220 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``. 227 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 230 bytes. 231 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. 235 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 244 condition. 245 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. 250 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. 258 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 262 this. 263 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. 268 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. 275 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. 282 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 286 this. 287 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 293 to Idle state. 294 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. 302 303Custom Pulses 304------------- 305 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. 309 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``. 315 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. 320 321``<op>[,<mode>] tx-custom-start`` 322 Send the custom bit instead of a regular start bit. 323 324``tx-custom-pulse`` 325 Transmit a single custom pulse as soon as the CEC bus is idle. 326
