Documentation/userspace-api/media/cec/cec-pin-error-inj.rst

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