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

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