€•z@      Œ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/virt/acrn/io-request”Œ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/virt/acrn/io-request”Œ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/virt/acrn/io-request”Œ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/virt/acrn/io-request”Œ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/virt/acrn/io-request”Œ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/virt/acrn/io-request”Œ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Œcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒB/var/lib/git/docbuild/linux/Documentation/virt/acrn/io-request.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒI/O request handling”h]”hŒI/O request handling”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hX
  An I/O request of a User VM, which is constructed by the hypervisor, is
distributed by the ACRN Hypervisor Service Module to an I/O client
corresponding to the address range of the I/O request. Details of I/O request
handling are described in the following sections.”h]”hX
  An I/O request of a User VM, which is constructed by the hypervisor, is
distributed by the ACRN Hypervisor Service Module to an I/O client
corresponding to the address range of the I/O request. Details of I/O request
handling are described in the following sections.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒ1. I/O request”h]”hŒ1. I/O request”…””}”(hhÜhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÙhžhhŸh³h KubhÊ)”}”(hXK  For each User VM, there is a shared 4-KByte memory region used for I/O requests
communication between the hypervisor and Service VM. An I/O request is a
256-byte structure buffer, which is 'struct acrn_io_request', that is filled by
an I/O handler of the hypervisor when a trapped I/O access happens in a User
VM. ACRN userspace in the Service VM first allocates a 4-KByte page and passes
the GPA (Guest Physical Address) of the buffer to the hypervisor. The buffer is
used as an array of 16 I/O request slots with each I/O request slot being 256
bytes. This array is indexed by vCPU ID.”h]”hXO  For each User VM, there is a shared 4-KByte memory region used for I/O requests
communication between the hypervisor and Service VM. An I/O request is a
256-byte structure buffer, which is â€˜struct acrn_io_requestâ€™, that is filled by
an I/O handler of the hypervisor when a trapped I/O access happens in a User
VM. ACRN userspace in the Service VM first allocates a 4-KByte page and passes
the GPA (Guest Physical Address) of the buffer to the hypervisor. The buffer is
used as an array of 16 I/O request slots with each I/O request slot being 256
bytes. This array is indexed by vCPU ID.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhÙhžhubeh}”(h]”Œi-o-request”ah ]”h"]”Œ1. i/o request”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ2. I/O clients”h]”hŒ2. I/O clients”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj   hžhhŸh³h KubhÊ)”}”(hX‹  An I/O client is responsible for handling User VM I/O requests whose accessed
GPA falls in a certain range. Multiple I/O clients can be associated with each
User VM. There is a special client associated with each User VM, called the
default client, that handles all I/O requests that do not fit into the range of
any other clients. The ACRN userspace acts as the default client for each User
VM.”h]”hX‹  An I/O client is responsible for handling User VM I/O requests whose accessed
GPA falls in a certain range. Multiple I/O clients can be associated with each
User VM. There is a special client associated with each User VM, called the
default client, that handles all I/O requests that do not fit into the range of
any other clients. The ACRN userspace acts as the default client for each User
VM.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj   hžhubhÊ)”}”(hŒkBelow illustration shows the relationship between I/O requests shared buffer,
I/O requests and I/O clients.”h]”hŒkBelow illustration shows the relationship between I/O requests shared buffer,
I/O requests and I/O clients.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K!hj   hžhubhŒliteral_block”“”)”}”(hX	  +------------------------------------------------------+
|                                       Service VM     |
|+--------------------------------------------------+  |
||      +----------------------------------------+  |  |
||      | shared page            ACRN userspace  |  |  |
||      |    +-----------------+  +------------+ |  |  |
||   +----+->| acrn_io_request |<-+  default   | |  |  |
||   |  | |  +-----------------+  | I/O client | |  |  |
||   |  | |  |       ...       |  +------------+ |  |  |
||   |  | |  +-----------------+                 |  |  |
||   |  +-|--------------------------------------+  |  |
||---|----|-----------------------------------------|  |
||   |    |                             kernel      |  |
||   |    |            +----------------------+     |  |
||   |    |            | +-------------+  HSM |     |  |
||   |    +--------------+             |      |     |  |
||   |                 | | I/O clients |      |     |  |
||   |                 | |             |      |     |  |
||   |                 | +-------------+      |     |  |
||   |                 +----------------------+     |  |
|+---|----------------------------------------------+  |
+----|-------------------------------------------------+
     |
+----|-------------------------------------------------+
|  +-+-----------+                                     |
|  | I/O handler |              ACRN Hypervisor        |
|  +-------------+                                     |
+------------------------------------------------------+”h]”hX	  +------------------------------------------------------+
|                                       Service VM     |
|+--------------------------------------------------+  |
||      +----------------------------------------+  |  |
||      | shared page            ACRN userspace  |  |  |
||      |    +-----------------+  +------------+ |  |  |
||   +----+->| acrn_io_request |<-+  default   | |  |  |
||   |  | |  +-----------------+  | I/O client | |  |  |
||   |  | |  |       ...       |  +------------+ |  |  |
||   |  | |  +-----------------+                 |  |  |
||   |  +-|--------------------------------------+  |  |
||---|----|-----------------------------------------|  |
||   |    |                             kernel      |  |
||   |    |            +----------------------+     |  |
||   |    |            | +-------------+  HSM |     |  |
||   |    +--------------+             |      |     |  |
||   |                 | | I/O clients |      |     |  |
||   |                 | |             |      |     |  |
||   |                 | +-------------+      |     |  |
||   |                 +----------------------+     |  |
|+---|----------------------------------------------+  |
+----|-------------------------------------------------+
     |
+----|-------------------------------------------------+
|  +-+-----------+                                     |
|  | I/O handler |              ACRN Hypervisor        |
|  +-------------+                                     |
+------------------------------------------------------+”…””}”hj/  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j-  hŸh³h K&hj   hžhubeh}”(h]”Œi-o-clients”ah ]”h"]”Œ2. i/o clients”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ3. I/O request state transition”h]”hŒ3. I/O request state transition”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjE  hžhhŸh³h KDubhÊ)”}”(hŒ<The state transitions of an ACRN I/O request are as follows.”h]”hŒ<The state transitions of an ACRN I/O request are as follows.”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KFhjE  hžhubj.  )”}”(hŒ8FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...”h]”hŒ8FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...”…””}”hjd  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j-  hŸh³h KJhjE  hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ$FREE: this I/O request slot is empty”h]”hÊ)”}”(hj{  h]”hŒ$FREE: this I/O request slot is empty”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KLhjy  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hjt  hžhhŸh³h Nubjx  )”}”(hŒ4PENDING: a valid I/O request is pending in this slot”h]”hÊ)”}”(hj’  h]”hŒ4PENDING: a valid I/O request is pending in this slot”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KMhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hjt  hžhhŸh³h Nubjx  )”}”(hŒ.PROCESSING: the I/O request is being processed”h]”hÊ)”}”(hj©  h]”hŒ.PROCESSING: the I/O request is being processed”…””}”(hj«  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KNhj§  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hjt  hžhhŸh³h Nubjx  )”}”(hŒ-COMPLETE: the I/O request has been processed
”h]”hÊ)”}”(hŒ,COMPLETE: the I/O request has been processed”h]”hŒ,COMPLETE: the I/O request has been processed”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KOhj¾  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hjt  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jr  hŸh³h KLhjE  hžhubhÊ)”}”(hŒƒAn I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
ACRN userspace are in charge of processing the others.”h]”hŒƒAn I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
ACRN userspace are in charge of processing the others.”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KQhjE  hžhubeh}”(h]”Œi-o-request-state-transition”ah ]”h"]”Œ3. i/o request state transition”ah$]”h&]”uh1h´hh¶hžhhŸh³h KDubhµ)”}”(hhh]”(hº)”}”(hŒ"4. Processing flow of I/O requests”h]”hŒ"4. Processing flow of I/O requests”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjô  hžhhŸh³h KUubhŒenumerated_list”“”)”}”(hhh]”(jx  )”}”(hŒ}The I/O handler of the hypervisor will fill an I/O request with PENDING
state when a trapped I/O access happens in a User VM.”h]”hÊ)”}”(hŒ}The I/O handler of the hypervisor will fill an I/O request with PENDING
state when a trapped I/O access happens in a User VM.”h]”hŒ}The I/O handler of the hypervisor will fill an I/O request with PENDING
state when a trapped I/O access happens in a User VM.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KWhj
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hj  hžhhŸh³h Nubjx  )”}”(hŒUThe hypervisor makes an upcall, which is a notification interrupt, to
the Service VM.”h]”hÊ)”}”(hŒUThe hypervisor makes an upcall, which is a notification interrupt, to
the Service VM.”h]”hŒUThe hypervisor makes an upcall, which is a notification interrupt, to
the Service VM.”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KYhj"  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hj  hžhhŸh³h Nubjx  )”}”(hŒ?The upcall handler schedules a worker to dispatch I/O requests.”h]”hÊ)”}”(hj<  h]”hŒ?The upcall handler schedules a worker to dispatch I/O requests.”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K[hj:  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hj  hžhhŸh³h Nubjx  )”}”(hŒÙThe worker looks for the PENDING I/O requests, assigns them to different
registered clients based on the address of the I/O accesses, updates
their state to PROCESSING, and notifies the corresponding client to handle.”h]”hÊ)”}”(hŒÙThe worker looks for the PENDING I/O requests, assigns them to different
registered clients based on the address of the I/O accesses, updates
their state to PROCESSING, and notifies the corresponding client to handle.”h]”hŒÙThe worker looks for the PENDING I/O requests, assigns them to different
registered clients based on the address of the I/O accesses, updates
their state to PROCESSING, and notifies the corresponding client to handle.”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K\hjQ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hj  hžhhŸh³h Nubjx  )”}”(hŒ6The notified client handles the assigned I/O requests.”h]”hÊ)”}”(hjk  h]”hŒ6The notified client handles the assigned I/O requests.”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K_hji  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hj  hžhhŸh³h Nubjx  )”}”(hŒmThe HSM updates I/O requests states to COMPLETE and notifies the hypervisor
of the completion via hypercalls.”h]”hÊ)”}”(hŒmThe HSM updates I/O requests states to COMPLETE and notifies the hypervisor
of the completion via hypercalls.”h]”hŒmThe HSM updates I/O requests states to COMPLETE and notifies the hypervisor
of the completion via hypercalls.”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K`hj€  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jw  hj  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œ
loweralpha”Œprefix”hŒsuffix”Œ.”uh1j  hjô  hžhhŸh³h KWubeh}”(h]”Œprocessing-flow-of-i-o-requests”ah ]”h"]”Œ"4. processing flow of i/o requests”ah$]”h&]”uh1h´hh¶hžhhŸh³h KUubeh}”(h]”Œi-o-request-handling”ah ]”h"]”Œi/o request handling”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­  hýhújB  j?  jñ  jî  j¨  j¥  uŒ	nametypes”}”(j°  ‰hý‰jB  ‰jñ  ‰j¨  ‰uh}”(j­  h¶húhÙj?  j   jî  jE  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.