€•Ï1      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ*/translations/zh_CN/i2c/dma-considerations”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/zh_TW/i2c/dma-considerations”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/it_IT/i2c/dma-considerations”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/ja_JP/i2c/dma-considerations”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/ko_KR/i2c/dma-considerations”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ*/translations/sp_SP/i2c/dma-considerations”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒLinux I2C and DMA”h]”hŒLinux I2C and DMA”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒD/var/lib/git/docbuild/linux/Documentation/i2c/dma-considerations.rst”h KubhŒ	paragraph”“”)”}”(hXo  Given that I2C is a low-speed bus, over which the majority of messages
transferred are small, it is not considered a prime user of DMA access. At this
time of writing, only 10% of I2C bus master drivers have DMA support
implemented. And the vast majority of transactions are so small that setting up
DMA for it will likely add more overhead than a plain PIO transfer.”h]”hXo  Given that I2C is a low-speed bus, over which the majority of messages
transferred are small, it is not considered a prime user of DMA access. At this
time of writing, only 10% of I2C bus master drivers have DMA support
implemented. And the vast majority of transactions are so small that setting up
DMA for it will likely add more overhead than a plain PIO transfer.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hX  Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
It does not seem reasonable to apply additional burdens when the feature is so
rarely used. However, it is recommended to use a DMA-safe buffer if your
message size is likely applicable for DMA. Most drivers have this threshold
around 8 bytes (as of today, this is mostly an educated guess, however). For
any message of 16 byte or larger, it is probably a really good idea. Please
note that other subsystems you use might add requirements. E.g., if your
I2C bus master driver is using USB as a bridge, then you need to have DMA
safe buffers always, because USB requires it.”h]”(hŒTherefore, it is ”…””}”(hhÇhžhhŸNh NubhŒemphasis”“”)”}”(hŒ*not*”h]”hŒnot”…””}”(hhÑhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÏhhÇubhXw   mandatory that the buffer of an I2C message is DMA safe.
It does not seem reasonable to apply additional burdens when the feature is so
rarely used. However, it is recommended to use a DMA-safe buffer if your
message size is likely applicable for DMA. Most drivers have this threshold
around 8 bytes (as of today, this is mostly an educated guess, however). For
any message of 16 byte or larger, it is probably a really good idea. Please
note that other subsystems you use might add requirements. E.g., if your
I2C bus master driver is using USB as a bridge, then you need to have DMA
safe buffers always, because USB requires it.”…””}”(hhÇhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒClients”h]”hŒClients”…””}”(hhìhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhéhžhhŸh¶h Kubh¸)”}”(hXû  For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
flag with it. Then, the I2C core and drivers know they can safely operate DMA
on it. Note that using this flag is optional. I2C host drivers which are not
updated to use this flag will work like before. And like before, they risk
using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
more and more clients and host drivers is the planned way forward. Note also
that setting this flag makes only sense in kernel space. User space data is
copied into kernel space anyhow. The I2C core makes sure the destination
buffers in kernel space are always DMA capable. Also, when the core emulates
SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
know their buffers are DMA safe. Users of i2c_transfer() must set the
I2C_M_DMA_SAFE flag manually.”h]”hXû  For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
flag with it. Then, the I2C core and drivers know they can safely operate DMA
on it. Note that using this flag is optional. I2C host drivers which are not
updated to use this flag will work like before. And like before, they risk
using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
more and more clients and host drivers is the planned way forward. Note also
that setting this flag makes only sense in kernel space. User space data is
copied into kernel space anyhow. The I2C core makes sure the destination
buffers in kernel space are always DMA capable. Also, when the core emulates
SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
know their buffers are DMA safe. Users of i2c_transfer() must set the
I2C_M_DMA_SAFE flag manually.”…””}”(hhúhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khhéhžhubeh}”(h]”Œclients”ah ]”h"]”Œclients”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒMasters”h]”hŒMasters”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K(ubh¸)”}”(hŒ¸Bus master drivers wishing to implement safe DMA can use helper functions from
the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
certain threshold is met::”h]”hŒ·Bus master drivers wishing to implement safe DMA can use helper functions from
the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
certain threshold is met:”…””}”(hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K*hj  hžhubhŒliteral_block”“”)”}”(hŒ;dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);”h]”hŒ;dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);”…””}”hj1  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1j/  hŸh¶h K.hj  hžhubh¸)”}”(hX#  If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
bounce buffer. But you don't need to care about that detail, just use the
returned buffer. If NULL is returned, the threshold was not met or a bounce
buffer could not be allocated. Fall back to PIO in that case.”h]”hX%  If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
bounce buffer. But you donâ€™t need to care about that detail, just use the
returned buffer. If NULL is returned, the threshold was not met or a bounce
buffer could not be allocated. Fall back to PIO in that case.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K0hj  hžhubh¸)”}”(hŒ‹In any case, a buffer obtained from above needs to be released. Another helper
function ensures a potentially used bounce buffer is freed::”h]”hŒŠIn any case, a buffer obtained from above needs to be released. Another helper
function ensures a potentially used bounce buffer is freed:”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K5hj  hžhubj0  )”}”(hŒ0i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);”h]”hŒ0i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);”…””}”hj]  sbah}”(h]”h ]”h"]”h$]”h&]”j?  j@  uh1j/  hŸh¶h K8hj  hžhubh¸)”}”(hŒµThe last argument 'xferred' controls if the buffer is synced back to the
message or not. No syncing is needed in cases setting up DMA had an error and
there was no data transferred.”h]”hŒ¹The last argument â€˜xferredâ€™ controls if the buffer is synced back to the
message or not. No syncing is needed in cases setting up DMA had an error and
there was no data transferred.”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K:hj  hžhubh¸)”}”(hŒàThe bounce buffer handling from the core is generic and simple. It will always
allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
reusing pre-allocated buffers), you are free to implement your own.”h]”hŒàThe bounce buffer handling from the core is generic and simple. It will always
allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
reusing pre-allocated buffers), you are free to implement your own.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K>hj  hžhubh¸)”}”(hŒ”Please also check the in-kernel documentation for details. The i2c-sh_mobile
driver can be used as a reference example how to use the above helpers.”h]”hŒ”Please also check the in-kernel documentation for details. The i2c-sh_mobile
driver can be used as a reference example how to use the above helpers.”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KBhj  hžhubh¸)”}”(hŒÞFinal note: If you plan to use DMA with I2C (or with anything else, actually)
make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
you find various issues which can be complex to debug otherwise.”h]”hŒÞFinal note: If you plan to use DMA with I2C (or with anything else, actually)
make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
you find various issues which can be complex to debug otherwise.”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KEhj  hžhubeh}”(h]”Œmasters”ah ]”h"]”Œmasters”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K(ubeh}”(h]”Œlinux-i2c-and-dma”ah ]”h"]”Œlinux i2c and dma”ah$]”h&]”uh1h¡hhhž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­  j  j
  j¨  j¥  uŒ	nametypes”}”(j°  ‰j  ‰j¨  ‰uh}”(j­  h£j
  hé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.