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 Framework Error Injection
   4 =================================
   5
   6 The CEC Pin Framework is a core CEC framework for CEC hardware that only
   7 has low-level support for the CEC bus. Most hardware today will have
   8 high-level CEC support where the hardware deals with driving the CEC bus,
   9 but some older devices aren't that fancy. However, this framework also
  10 allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and
  11 you have now made a CEC adapter.
  12
  13 What makes doing this so interesting is that since we have full control
  14 over the bus it is easy to support error injection. This is ideal to
  15 test how well CEC adapters can handle error conditions.
  16
  17 Currently only the cec-gpio driver (when the CEC line is directly
  18 connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver
  19 support this framework.
  20
  21 If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available
  22 through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is
  23 now 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
  30 With ``cat error-inj`` you can see both the possible commands and the current
  31 error 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
  78 You can write error injection commands to ``error-inj`` using
  79 ``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj``
  80 output contains the current error commands. You can save the output to a file
  81 and use it as an input to ``error-inj`` later.
  82
  83 Basic Syntax
  84 ------------
  85
  86 Leading spaces/tabs are ignored. If the next character is a ``#`` or the end
  87 of the line was reached, then the whole line is ignored. Otherwise a command
  88 is expected.
  89
  90 The error injection commands fall in two main groups: those relating to
  91 receiving CEC messages and those relating to transmitting CEC messages. In
  92 addition, there are commands to clear existing error injection commands and
  93 to create custom pulses on the CEC bus.
  94
  95 Most error injection commands can be executed for specific CEC opcodes or for
  96 all 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
  99 received or transmitted message, ``always`` to always trigger the error
 100 injection and ``toggle`` to toggle the error injection on or off for every
 101 transmit or receive.
 102
 103 So '``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
 106 received and do that only for every other received message.
 107
 108 After an error was injected with mode ``once`` the error injection command
 109 is cleared automatically, so ``once`` is a one-time deal.
 110
 111 All combinations of ``<op>`` and error injection commands can co-exist. So
 112 this 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
 119 All four error injection commands will be active simultaneously.
 120
 121 However, if the same ``<op>`` and command combination is specified,
 122 but with different arguments::
 123
 124         0x9e tx-add-bytes 1
 125         0x9e tx-add-bytes 2
 126
 127 Then the second will overwrite the first.
 128
 129 Clear 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
 150 Receive 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
 194 Transmit 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
 305 Custom 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.