0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 CEC Pin Framework Error Injection
0004 =================================
0005
0006 The CEC Pin Framework is a core CEC framework for CEC hardware that only
0007 has low-level support for the CEC bus. Most hardware today will have
0008 high-level CEC support where the hardware deals with driving the CEC bus,
0009 but some older devices aren't that fancy. However, this framework also
0010 allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and
0011 you have now made a CEC adapter.
0012
0013 What makes doing this so interesting is that since we have full control
0014 over the bus it is easy to support error injection. This is ideal to
0015 test how well CEC adapters can handle error conditions.
0016
0017 Currently only the cec-gpio driver (when the CEC line is directly
0018 connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver
0019 support this framework.
0020
0021 If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available
0022 through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is
0023 now an ``error-inj`` file.
0024
0025 .. note::
0026
0027 The error injection commands are not a stable ABI and may change in the
0028 future.
0029
0030 With ``cat error-inj`` you can see both the possible commands and the current
0031 error injection status::
0032
0033 $ cat /sys/kernel/debug/cec/cec0/error-inj
0034 # Clear error injections:
0035 # clear clear all rx and tx error injections
0036 # rx-clear clear all rx error injections
0037 # tx-clear clear all tx error injections
0038 # <op> clear clear all rx and tx error injections for <op>
0039 # <op> rx-clear clear all rx error injections for <op>
0040 # <op> tx-clear clear all tx error injections for <op>
0041 #
0042 # RX error injection:
0043 # <op>[,<mode>] rx-nack NACK the message instead of sending an ACK
0044 # <op>[,<mode>] rx-low-drive <bit> force a low-drive condition at this bit position
0045 # <op>[,<mode>] rx-add-byte add a spurious byte to the received CEC message
0046 # <op>[,<mode>] rx-remove-byte remove the last byte from the received CEC message
0047 # any[,<mode>] rx-arb-lost [<poll>] generate a POLL message to trigger an arbitration lost
0048 #
0049 # TX error injection settings:
0050 # tx-ignore-nack-until-eom ignore early NACKs until EOM
0051 # tx-custom-low-usecs <usecs> define the 'low' time for the custom pulse
0052 # tx-custom-high-usecs <usecs> define the 'high' time for the custom pulse
0053 # tx-custom-pulse transmit the custom pulse once the bus is idle
0054 #
0055 # TX error injection:
0056 # <op>[,<mode>] tx-no-eom don't set the EOM bit
0057 # <op>[,<mode>] tx-early-eom set the EOM bit one byte too soon
0058 # <op>[,<mode>] tx-add-bytes <num> append <num> (1-255) spurious bytes to the message
0059 # <op>[,<mode>] tx-remove-byte drop the last byte from the message
0060 # <op>[,<mode>] tx-short-bit <bit> make this bit shorter than allowed
0061 # <op>[,<mode>] tx-long-bit <bit> make this bit longer than allowed
0062 # <op>[,<mode>] tx-custom-bit <bit> send the custom pulse instead of this bit
0063 # <op>[,<mode>] tx-short-start send a start pulse that's too short
0064 # <op>[,<mode>] tx-long-start send a start pulse that's too long
0065 # <op>[,<mode>] tx-custom-start send the custom pulse instead of the start pulse
0066 # <op>[,<mode>] tx-last-bit <bit> stop sending after this bit
0067 # <op>[,<mode>] tx-low-drive <bit> force a low-drive condition at this bit position
0068 #
0069 # <op> CEC message opcode (0-255) or 'any'
0070 # <mode> 'once' (default), 'always', 'toggle' or 'off'
0071 # <bit> CEC message bit (0-159)
0072 # 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK
0073 # <poll> CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f)
0074 # <usecs> microseconds (0-10000000, default 1000)
0075
0076 clear
0077
0078 You can write error injection commands to ``error-inj`` using
0079 ``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj``
0080 output contains the current error commands. You can save the output to a file
0081 and use it as an input to ``error-inj`` later.
0082
0083 Basic Syntax
0084 ------------
0085
0086 Leading spaces/tabs are ignored. If the next character is a ``#`` or the end
0087 of the line was reached, then the whole line is ignored. Otherwise a command
0088 is expected.
0089
0090 The error injection commands fall in two main groups: those relating to
0091 receiving CEC messages and those relating to transmitting CEC messages. In
0092 addition, there are commands to clear existing error injection commands and
0093 to create custom pulses on the CEC bus.
0094
0095 Most error injection commands can be executed for specific CEC opcodes or for
0096 all opcodes (``any``). Each command also has a 'mode' which can be ``off``
0097 (can be used to turn off an existing error injection command), ``once``
0098 (the default) which will trigger the error injection only once for the next
0099 received or transmitted message, ``always`` to always trigger the error
0100 injection and ``toggle`` to toggle the error injection on or off for every
0101 transmit or receive.
0102
0103 So '``any rx-nack``' will NACK the next received CEC message,
0104 '``any,always rx-nack``' will NACK all received CEC messages and
0105 '``0x82,toggle rx-nack``' will only NACK if an Active Source message was
0106 received and do that only for every other received message.
0107
0108 After an error was injected with mode ``once`` the error injection command
0109 is cleared automatically, so ``once`` is a one-time deal.
0110
0111 All combinations of ``<op>`` and error injection commands can co-exist. So
0112 this is fine::
0113
0114 0x9e tx-add-bytes 1
0115 0x9e tx-early-eom
0116 0x9f tx-add-bytes 2
0117 any rx-nack
0118
0119 All four error injection commands will be active simultaneously.
0120
0121 However, if the same ``<op>`` and command combination is specified,
0122 but with different arguments::
0123
0124 0x9e tx-add-bytes 1
0125 0x9e tx-add-bytes 2
0126
0127 Then the second will overwrite the first.
0128
0129 Clear Error Injections
0130 ----------------------
0131
0132 ``clear``
0133 Clear all error injections.
0134
0135 ``rx-clear``
0136 Clear all receive error injections
0137
0138 ``tx-clear``
0139 Clear all transmit error injections
0140
0141 ``<op> clear``
0142 Clear all error injections for the given opcode.
0143
0144 ``<op> rx-clear``
0145 Clear all receive error injections for the given opcode.
0146
0147 ``<op> tx-clear``
0148 Clear all transmit error injections for the given opcode.
0149
0150 Receive Messages
0151 ----------------
0152
0153 ``<op>[,<mode>] rx-nack``
0154 NACK broadcast messages and messages directed to this CEC adapter.
0155 Every byte of the message will be NACKed in case the transmitter
0156 keeps transmitting after the first byte was NACKed.
0157
0158 ``<op>[,<mode>] rx-low-drive <bit>``
0159 Force a Low Drive condition at this bit position. If <op> specifies
0160 a specific CEC opcode then the bit position must be at least 18,
0161 otherwise the opcode hasn't been received yet. This tests if the
0162 transmitter can handle the Low Drive condition correctly and reports
0163 the error correctly. Note that a Low Drive in the first 4 bits can also
0164 be interpreted as an Arbitration Lost condition by the transmitter.
0165 This is implementation dependent.
0166
0167 ``<op>[,<mode>] rx-add-byte``
0168 Add a spurious 0x55 byte to the received CEC message, provided
0169 the message was 15 bytes long or less. This is useful to test
0170 the high-level protocol since spurious bytes should be ignored.
0171
0172 ``<op>[,<mode>] rx-remove-byte``
0173 Remove the last byte from the received CEC message, provided it
0174 was at least 2 bytes long. This is useful to test the high-level
0175 protocol since messages that are too short should be ignored.
0176
0177 ``<op>[,<mode>] rx-arb-lost <poll>``
0178 Generate a POLL message to trigger an Arbitration Lost condition.
0179 This command is only allowed for ``<op>`` values of ``next`` or ``all``.
0180 As soon as a start bit has been received the CEC adapter will switch
0181 to transmit mode and it will transmit a POLL message. By default this is
0182 0x0f, but it can also be specified explicitly via the ``<poll>`` argument.
0183
0184 This command can be used to test the Arbitration Lost condition in
0185 the remote CEC transmitter. Arbitration happens when two CEC adapters
0186 start sending a message at the same time. In that case the initiator
0187 with the most leading zeroes wins and the other transmitter has to
0188 stop transmitting ('Arbitration Lost'). This is very hard to test,
0189 except by using this error injection command.
0190
0191 This does not work if the remote CEC transmitter has logical address
0192 0 ('TV') since that will always win.
0193
0194 Transmit Messages
0195 -----------------
0196
0197 ``tx-ignore-nack-until-eom``
0198 This setting changes the behavior of transmitting CEC messages. Normally
0199 as soon as the receiver NACKs a byte the transmit will stop, but the
0200 specification also allows that the full message is transmitted and only
0201 at the end will the transmitter look at the ACK bit. This is not
0202 recommended behavior since there is no point in keeping the CEC bus busy
0203 for longer than is strictly needed. Especially given how slow the bus is.
0204
0205 This setting can be used to test how well a receiver deals with
0206 transmitters that ignore NACKs until the very end of the message.
0207
0208 ``<op>[,<mode>] tx-no-eom``
0209 Don't set the EOM bit. Normally the last byte of the message has the EOM
0210 (End-Of-Message) bit set. With this command the transmit will just stop
0211 without ever sending an EOM. This can be used to test how a receiver
0212 handles this case. Normally receivers have a time-out after which
0213 they will go back to the Idle state.
0214
0215 ``<op>[,<mode>] tx-early-eom``
0216 Set the EOM bit one byte too soon. This obviously only works for messages
0217 of two bytes or more. The EOM bit will be set for the second-to-last byte
0218 and not for the final byte. The receiver should ignore the last byte in
0219 this case. Since the resulting message is likely to be too short for this
0220 same reason the whole message is typically ignored. The receiver should be
0221 in Idle state after the last byte was transmitted.
0222
0223 ``<op>[,<mode>] tx-add-bytes <num>``
0224 Append ``<num>`` (1-255) spurious bytes to the message. The extra bytes
0225 have the value of the byte position in the message. So if you transmit a
0226 two byte message (e.g. a Get CEC Version message) and add 2 bytes, then
0227 the full message received by the remote CEC adapter is
0228 ``0x40 0x9f 0x02 0x03``.
0229
0230 This command can be used to test buffer overflows in the receiver. E.g.
0231 what does it do when it receives more than the maximum message size of 16
0232 bytes.
0233
0234 ``<op>[,<mode>] tx-remove-byte``
0235 Drop the last byte from the message, provided the message is at least
0236 two bytes long. The receiver should ignore messages that are too short.
0237
0238 ``<op>[,<mode>] tx-short-bit <bit>``
0239 Make this bit period shorter than allowed. The bit position cannot be
0240 an Ack bit. If <op> specifies a specific CEC opcode then the bit position
0241 must be at least 18, otherwise the opcode hasn't been received yet.
0242 Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
0243 With this command the period of this bit is 1.8 milliseconds, this is
0244 done by reducing the time the CEC bus is high. This bit period is less
0245 than is allowed and the receiver should respond with a Low Drive
0246 condition.
0247
0248 This command is ignored for 0 bits in bit positions 0 to 3. This is
0249 because the receiver also looks for an Arbitration Lost condition in
0250 those first four bits and it is undefined what will happen if it
0251 sees a too-short 0 bit.
0252
0253 ``<op>[,<mode>] tx-long-bit <bit>``
0254 Make this bit period longer than is valid. The bit position cannot be
0255 an Ack bit. If <op> specifies a specific CEC opcode then the bit position
0256 must be at least 18, otherwise the opcode hasn't been received yet.
0257 Normally the period of a data bit is between 2.05 and 2.75 milliseconds.
0258 With this command the period of this bit is 2.9 milliseconds, this is
0259 done by increasing the time the CEC bus is high.
0260
0261 Even though this bit period is longer than is valid it is undefined what
0262 a receiver will do. It might just accept it, or it might time out and
0263 return to Idle state. Unfortunately the CEC specification is silent about
0264 this.
0265
0266 This command is ignored for 0 bits in bit positions 0 to 3. This is
0267 because the receiver also looks for an Arbitration Lost condition in
0268 those first four bits and it is undefined what will happen if it
0269 sees a too-long 0 bit.
0270
0271 ``<op>[,<mode>] tx-short-start``
0272 Make this start bit period shorter than allowed. Normally the period of
0273 a start bit is between 4.3 and 4.7 milliseconds. With this command the
0274 period of the start bit is 4.1 milliseconds, this is done by reducing
0275 the time the CEC bus is high. This start bit period is less than is
0276 allowed and the receiver should return to Idle state when this is detected.
0277
0278 ``<op>[,<mode>] tx-long-start``
0279 Make this start bit period longer than is valid. Normally the period of
0280 a start bit is between 4.3 and 4.7 milliseconds. With this command the
0281 period of the start bit is 5 milliseconds, this is done by increasing
0282 the time the CEC bus is high. This start bit period is more than is
0283 valid and the receiver should return to Idle state when this is detected.
0284
0285 Even though this start bit period is longer than is valid it is undefined
0286 what a receiver will do. It might just accept it, or it might time out and
0287 return to Idle state. Unfortunately the CEC specification is silent about
0288 this.
0289
0290 ``<op>[,<mode>] tx-last-bit <bit>``
0291 Just stop transmitting after this bit. If <op> specifies a specific CEC
0292 opcode then the bit position must be at least 18, otherwise the opcode
0293 hasn't been received yet. This command can be used to test how the receiver
0294 reacts when a message just suddenly stops. It should time out and go back
0295 to Idle state.
0296
0297 ``<op>[,<mode>] tx-low-drive <bit>``
0298 Force a Low Drive condition at this bit position. If <op> specifies a
0299 specific CEC opcode then the bit position must be at least 18, otherwise
0300 the opcode hasn't been received yet. This can be used to test how the
0301 receiver handles Low Drive conditions. Note that if this happens at bit
0302 positions 0-3 the receiver can interpret this as an Arbitration Lost
0303 condition. This is implementation dependent.
0304
0305 Custom Pulses
0306 -------------
0307
0308 ``tx-custom-low-usecs <usecs>``
0309 This defines the duration in microseconds that the custom pulse pulls
0310 the CEC line low. The default is 1000 microseconds.
0311
0312 ``tx-custom-high-usecs <usecs>``
0313 This defines the duration in microseconds that the custom pulse keeps the
0314 CEC line high (unless another CEC adapter pulls it low in that time).
0315 The default is 1000 microseconds. The total period of the custom pulse is
0316 ``tx-custom-low-usecs + tx-custom-high-usecs``.
0317
0318 ``<op>[,<mode>] tx-custom-bit <bit>``
0319 Send the custom bit instead of a regular data bit. The bit position cannot
0320 be an Ack bit. If <op> specifies a specific CEC opcode then the bit
0321 position must be at least 18, otherwise the opcode hasn't been received yet.
0322
0323 ``<op>[,<mode>] tx-custom-start``
0324 Send the custom bit instead of a regular start bit.
0325
0326 ``tx-custom-pulse``
0327 Transmit a single custom pulse as soon as the CEC bus is idle.
