cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

cec-pin-error-inj.rst (15267B)


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