Documentation/media/uapi/cec/cec-pin-error-inj.rst

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