€•¤OŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ,/translations/zh_CN/i2c/gpio-fault-injection”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ,/translations/zh_TW/i2c/gpio-fault-injection”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ,/translations/it_IT/i2c/gpio-fault-injection”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ,/translations/ja_JP/i2c/gpio-fault-injection”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ,/translations/ko_KR/i2c/gpio-fault-injection”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ,/translations/sp_SP/i2c/gpio-fault-injection”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒLinux I2C fault injection”h]”hŒLinux I2C fault injection”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒF/var/lib/git/docbuild/linux/Documentation/i2c/gpio-fault-injection.rst”h KubhŒ paragraph”“”)”}”(hXQThe GPIO based I2C bus master driver can be configured to provide fault injection capabilities. It is then meant to be connected to another I2C bus which is driven by the I2C bus master driver under test. The GPIO fault injection driver can create special states on the bus which the other I2C bus master driver should handle gracefully.”h]”hXQThe GPIO based I2C bus master driver can be configured to provide fault injection capabilities. It is then meant to be connected to another I2C bus which is driven by the I2C bus master driver under test. The GPIO fault injection driver can create special states on the bus which the other I2C bus master driver should handle gracefully.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hXzOnce the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an 'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO driven I2C bus. Each subdirectory will contain files to trigger the fault injection. They will be described now along with their intended use-cases.”h]”hX~Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an ‘i2c-fault-injector’ subdirectory in the Kernel debugfs filesystem, usually mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO driven I2C bus. Each subdirectory will contain files to trigger the fault injection. They will be described now along with their intended use-cases.”…””}”(hhÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K hh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒ Wire states”h]”hŒ Wire states”…””}”(hhØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhÕhžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ"scl"”h]”hŒ “scl—…””}”(hhéhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhæhžhhŸh¶h Kubh¸)”}”(hX„By reading this file, you get the current state of SCL. By writing, you can change its state to either force it low or to release it again. So, by using "echo 0 > scl" you force SCL low and thus, no communication will be possible because the bus master under test will not be able to clock. It should detect the condition of SCL being unresponsive and report an error to the upper layers.”h]”hXˆBy reading this file, you get the current state of SCL. By writing, you can change its state to either force it low or to release it again. So, by using “echo 0 > scl†you force SCL low and thus, no communication will be possible because the bus master under test will not be able to clock. It should detect the condition of SCL being unresponsive and report an error to the upper layers.”…””}”(hh÷hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khhæhžhubeh}”(h]”Œscl”ah ]”h"]”Œ"scl"”ah$]”h&]”uh1h¡hhÕhžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ"sda"”h]”hŒ “sda—…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj hžhhŸh¶h Kubh¸)”}”(hX˜By reading this file, you get the current state of SDA. By writing, you can change its state to either force it low or to release it again. So, by using "echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus master under test should detect this condition and trigger a bus recovery (see I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C core (see 'struct bus_recovery_info'). However, the bus recovery will not succeed because SDA is still pinned low until you manually release it again with "echo 1 > sda". A test with an automatic release can be done with the "incomplete transfers" class of fault injectors.”h]”hX¨By reading this file, you get the current state of SDA. By writing, you can change its state to either force it low or to release it again. So, by using “echo 0 > sda†you force SDA low and thus, data cannot be transmitted. The bus master under test should detect this condition and trigger a bus recovery (see I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C core (see ‘struct bus_recovery_info’). However, the bus recovery will not succeed because SDA is still pinned low until you manually release it again with “echo 1 > sdaâ€. A test with an automatic release can be done with the “incomplete transfers†class of fault injectors.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K!hj hžhubeh}”(h]”Œsda”ah ]”h"]”Œ"sda"”ah$]”h&]”uh1h¡hhÕhžhhŸh¶h Kubeh}”(h]”Œ wire-states”ah ]”h"]”Œ wire states”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒIncomplete transfers”h]”hŒIncomplete transfers”…””}”(hj?hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj<hžhhŸh¶h K,ubh¸)”}”(hXdThe following fault injectors create situations where SDA will be held low by a device. Bus recovery should be able to fix these situations. But please note: there are I2C client devices which detect a stuck SDA on their side and release it on their own after a few milliseconds. Also, there might be an external device deglitching and monitoring the I2C bus. It could also detect a stuck SDA and will init a bus recovery on its own. If you want to implement bus recovery in a bus master driver, make sure you checked your hardware setup for such devices before. And always verify with a scope or logic analyzer!”h]”hXdThe following fault injectors create situations where SDA will be held low by a device. Bus recovery should be able to fix these situations. But please note: there are I2C client devices which detect a stuck SDA on their side and release it on their own after a few milliseconds. Also, there might be an external device deglitching and monitoring the I2C bus. It could also detect a stuck SDA and will init a bus recovery on its own. If you want to implement bus recovery in a bus master driver, make sure you checked your hardware setup for such devices before. And always verify with a scope or logic analyzer!”…””}”(hjMhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K.hj<hžhubh¢)”}”(hhh]”(h§)”}”(hŒ"incomplete_address_phase"”h]”hŒ“incomplete_address_phase—…””}”(hj^hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj[hžhhŸh¶h K8ubh¸)”}”(hX/This file is write only and you need to write the address of an existing I2C client device to it. Then, a read transfer to this device will be started, but it will stop at the ACK phase after the address of the client has been transmitted. Because the device will ACK its presence, this results in SDA being pulled low by the device while SCL is high. So, similar to the "sda" file above, the bus master under test should detect this condition and try a bus recovery. This time, however, it should succeed and the device should release SDA after toggling SCL.”h]”hX3This file is write only and you need to write the address of an existing I2C client device to it. Then, a read transfer to this device will be started, but it will stop at the ACK phase after the address of the client has been transmitted. Because the device will ACK its presence, this results in SDA being pulled low by the device while SCL is high. So, similar to the “sda†file above, the bus master under test should detect this condition and try a bus recovery. This time, however, it should succeed and the device should release SDA after toggling SCL.”…””}”(hjlhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K:hj[hžhubeh}”(h]”Œincomplete-address-phase”ah ]”h"]”Œ"incomplete_address_phase"”ah$]”h&]”uh1h¡hj<hžhhŸh¶h K8ubh¢)”}”(hhh]”(h§)”}”(hŒ"incomplete_write_byte"”h]”hŒ“incomplete_write_byte—…””}”(hj…hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj‚hžhhŸh¶h KDubh¸)”}”(hŒsSimilar to above, this file is write only and you need to write the address of an existing I2C client device to it.”h]”hŒsSimilar to above, this file is write only and you need to write the address of an existing I2C client device to it.”…””}”(hj“hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KFhj‚hžhubh¸)”}”(hŒ·The injector will again stop at one ACK phase, so the device will keep SDA low because it acknowledges data. However, there are two differences compared to 'incomplete_address_phase':”h]”hŒ»The injector will again stop at one ACK phase, so the device will keep SDA low because it acknowledges data. However, there are two differences compared to ‘incomplete_address_phase’:”…””}”(hj¡hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KIhj‚hžhubhŒenumerated_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hŒ,the message sent out will be a write message”h]”h¸)”}”(hj¸h]”hŒ,the message sent out will be a write message”…””}”(hjºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KMhj¶ubah}”(h]”h ]”h"]”h$]”h&]”uh1j´hj±hžhhŸh¶h Nubjµ)”}”(hŒLafter the address byte, a 0x00 byte will be transferred. Then, stop at ACK. ”h]”h¸)”}”(hŒKafter the address byte, a 0x00 byte will be transferred. Then, stop at ACK.”h]”hŒKafter the address byte, a 0x00 byte will be transferred. Then, stop at ACK.”…””}”(hjÑhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KNhjÍubah}”(h]”h ]”h"]”h$]”h&]”uh1j´hj±hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œ loweralpha”Œprefix”hŒsuffix”Œ)”uh1j¯hj‚hžhhŸh¶h KMubh¸)”}”(hXXThis is a highly delicate state, the device is set up to write any data to register 0x00 (if it has registers) when further clock pulses happen on SCL. This is why bus recovery (up to 9 clock pulses) must either check SDA or send additional STOP conditions to ensure the bus has been released. Otherwise random data will be written to a device!”h]”hXXThis is a highly delicate state, the device is set up to write any data to register 0x00 (if it has registers) when further clock pulses happen on SCL. This is why bus recovery (up to 9 clock pulses) must either check SDA or send additional STOP conditions to ensure the bus has been released. Otherwise random data will be written to a device!”…””}”(hjðhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KPhj‚hžhubeh}”(h]”Œincomplete-write-byte”ah ]”h"]”Œ"incomplete_write_byte"”ah$]”h&]”uh1h¡hj<hžhhŸh¶h KDubeh}”(h]”Œincomplete-transfers”ah ]”h"]”Œincomplete transfers”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K,ubh¢)”}”(hhh]”(h§)”}”(hŒLost arbitration”h]”hŒLost arbitration”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjhžhhŸh¶h KWubh¸)”}”(hŒHere, we want to simulate the condition where the master under test loses the bus arbitration against another master in a multi-master setup.”h]”hŒHere, we want to simulate the condition where the master under test loses the bus arbitration against another master in a multi-master setup.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KYhjhžhubh¢)”}”(hhh]”(h§)”}”(hŒ"lose_arbitration"”h]”hŒ“lose_arbitration—…””}”(hj0hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj-hžhhŸh¶h K]ubh¸)”}”(hŒáThis file is write only and you need to write the duration of the arbitration interference (in µs, maximum is 100ms). The calling process will then sleep and wait for the next bus clock. The process is interruptible, though.”h]”hŒáThis file is write only and you need to write the duration of the arbitration interference (in µs, maximum is 100ms). The calling process will then sleep and wait for the next bus clock. The process is interruptible, though.”…””}”(hj>hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K_hj-hžhubh¸)”}”(hXyArbitration lost is achieved by waiting for SCL going down by the master under test and then pulling SDA low for some time. So, the I2C address sent out should be corrupted and that should be detected properly. That means that the address sent out should have a lot of '1' bits to be able to detect corruption. There doesn't need to be a device at this address because arbitration lost should be detected beforehand. Also note, that SCL going down is monitored using interrupts, so the interrupt latency might cause the first bits to be not corrupted. A good starting point for using this fault injector on an otherwise idle bus is::”h]”hX~Arbitration lost is achieved by waiting for SCL going down by the master under test and then pulling SDA low for some time. So, the I2C address sent out should be corrupted and that should be detected properly. That means that the address sent out should have a lot of ‘1’ bits to be able to detect corruption. There doesn’t need to be a device at this address because arbitration lost should be detected beforehand. Also note, that SCL going down is monitored using interrupts, so the interrupt latency might cause the first bits to be not corrupted. A good starting point for using this fault injector on an otherwise idle bus is:”…””}”(hjLhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kchj-hžhubhŒ literal_block”“”)”}”(hŒ># echo 200 > lose_arbitration & # i2cget -y 0x3f”h]”hŒ># echo 200 > lose_arbitration & # i2cget -y 0x3f”…””}”hj\sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1jZhŸh¶h Kmhj-hžhubeh}”(h]”Œlose-arbitration”ah ]”h"]”Œ"lose_arbitration"”ah$]”h&]”uh1h¡hjhžhhŸh¶h K]ubeh}”(h]”Œlost-arbitration”ah ]”h"]”Œlost arbitration”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KWubh¢)”}”(hhh]”(h§)”}”(hŒPanic during transfer”h]”hŒPanic during transfer”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj|hžhhŸh¶h Kqubh¸)”}”(hX;This fault injector will create a Kernel panic once the master under test started a transfer. This usually means that the state machine of the bus master driver will be ungracefully interrupted and the bus may end up in an unusual state. Use this to check if your shutdown/reboot/boot code can handle this scenario.”h]”hX;This fault injector will create a Kernel panic once the master under test started a transfer. This usually means that the state machine of the bus master driver will be ungracefully interrupted and the bus may end up in an unusual state. Use this to check if your shutdown/reboot/boot code can handle this scenario.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kshj|hžhubh¢)”}”(hhh]”(h§)”}”(hŒ"inject_panic"”h]”hŒ“inject_panic—…””}”(hjžhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj›hžhhŸh¶h Kzubh¸)”}”(hXThis file is write only and you need to write the delay between the detected start of a transmission and the induced Kernel panic (in µs, maximum is 100ms). The calling process will then sleep and wait for the next bus clock. The process is interruptible, though.”h]”hXThis file is write only and you need to write the delay between the detected start of a transmission and the induced Kernel panic (in µs, maximum is 100ms). The calling process will then sleep and wait for the next bus clock. The process is interruptible, though.”…””}”(hj¬hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K|hj›hžhubh¸)”}”(hŒ‘Start of a transfer is detected by waiting for SCL going down by the master under test. A good starting point for using this fault injector is::”h]”hŒStart of a transfer is detected by waiting for SCL going down by the master under test. A good starting point for using this fault injector is:”…””}”(hjºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj›hžhubj[)”}”(hŒB# echo 0 > inject_panic & # i2cget -y ”h]”hŒB# echo 0 > inject_panic & # i2cget -y ”…””}”hjÈsbah}”(h]”h ]”h"]”h$]”h&]”jjjkuh1jZhŸh¶h K„hj›hžhubh¸)”}”(hŒNote that there doesn't need to be a device listening to the address you are using. Results may vary depending on that, though.”h]”hŒNote that there doesn’t need to be a device listening to the address you are using. Results may vary depending on that, though.”…””}”(hjÖhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K‡hj›hžhubeh}”(h]”Œ inject-panic”ah ]”h"]”Œ"inject_panic"”ah$]”h&]”uh1h¡hj|hžhhŸh¶h Kzubeh}”(h]”Œpanic-during-transfer”ah ]”h"]”Œpanic during transfer”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kqubeh}”(h]”Œlinux-i2c-fault-injection”ah ]”h"]”Œlinux i2c fault injection”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jùjöj9j6j jj1j.j jjj|jjjyjvjqjnjñjîjéjæuŒ nametypes”}”(jù‰j9‰j ‰j1‰j ‰j‰j‰jy‰jq‰jñ‰jé‰uh}”(jöh£j6hÕjhæj.j jj<j|j[jj‚jvjjnj-jîj|jæj›uŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œ transformer”NŒ include_log”]”Œ decoration”Nhžhub.