€•S      Œ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/misc-devices/uacce”Œ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/misc-devices/uacce”Œ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/misc-devices/uacce”Œ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/misc-devices/uacce”Œ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/misc-devices/uacce”Œ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/misc-devices/uacce”Œ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ŸŒ@/var/lib/git/docbuild/linux/Documentation/misc-devices/uacce.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒIntroduction of Uacce”h]”hŒIntroduction of Uacce”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hXd  Uacce (Unified/User-space-access-intended Accelerator Framework) targets to
provide Shared Virtual Addressing (SVA) between accelerators and processes.
So accelerator can access any data structure of the main cpu.
This differs from the data sharing between cpu and io device, which share
only data content rather than address.
Because of the unified address, hardware and user space of process can
share the same virtual address in the communication.
Uacce takes the hardware accelerator as a heterogeneous processor, while
IOMMU share the same CPU page tables and as a result the same translation
from va to pa.”h]”hXd  Uacce (Unified/User-space-access-intended Accelerator Framework) targets to
provide Shared Virtual Addressing (SVA) between accelerators and processes.
So accelerator can access any data structure of the main cpu.
This differs from the data sharing between cpu and io device, which share
only data content rather than address.
Because of the unified address, hardware and user space of process can
share the same virtual address in the communication.
Uacce takes the hardware accelerator as a heterogeneous processor, while
IOMMU share the same CPU page tables and as a result the same translation
from va to pa.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒliteral_block”“”)”}”(hXÅ   __________________________       __________________________
|                          |     |                          |
|  User application (CPU)  |     |   Hardware Accelerator   |
|__________________________|     |__________________________|

             |                                 |
             | va                              | va
             V                                 V
         __________                        __________
        |          |                      |          |
        |   MMU    |                      |  IOMMU   |
        |__________|                      |__________|
             |                                 |
             |                                 |
             V pa                              V pa
         _______________________________________
        |                                       |
        |              Memory                   |
        |_______________________________________|”h]”hXÅ   __________________________       __________________________
|                          |     |                          |
|  User application (CPU)  |     |   Hardware Accelerator   |
|__________________________|     |__________________________|

             |                                 |
             | va                              | va
             V                                 V
         __________                        __________
        |          |                      |          |
        |   MMU    |                      |  IOMMU   |
        |__________|                      |__________|
             |                                 |
             |                                 |
             V pa                              V pa
         _______________________________________
        |                                       |
        |              Memory                   |
        |_______________________________________|”…””}”hhÛsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1hÙhŸh³h Khh¶hžhubeh}”(h]”Œintroduction-of-uacce”ah ]”h"]”Œintroduction of uacce”ah$]”h&]”uh1h´hhhžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒArchitecture”h]”hŒArchitecture”…””}”(hhôhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhñhžhhŸh³h K*ubhÊ)”}”(hŒ|Uacce is the kernel module, taking charge of iommu and address sharing.
The user drivers and libraries are called WarpDrive.”h]”hŒ|Uacce is the kernel module, taking charge of iommu and address sharing.
The user drivers and libraries are called WarpDrive.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K,hhñhžhubhÊ)”}”(hŒvThe uacce device, built around the IOMMU SVA API, can access multiple
address spaces, including the one without PASID.”h]”hŒvThe uacce device, built around the IOMMU SVA API, can access multiple
address spaces, including the one without PASID.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K/hhñhžhubhÊ)”}”(hŒ·A virtual concept, queue, is used for the communication. It provides a
FIFO-like interface. And it maintains a unified address space between the
application and all involved hardware.”h]”hŒ·A virtual concept, queue, is used for the communication. It provides a
FIFO-like interface. And it maintains a unified address space between the
application and all involved hardware.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K2hhñhžhubhÚ)”}”(hX‹                           ___________________                  ________________
                        |                   |   user API     |                |
                        | WarpDrive library | ------------>  |  user driver   |
                        |___________________|                |________________|
                                 |                                    |
                                 |                                    |
                                 | queue fd                           |
                                 |                                    |
                                 |                                    |
                                 v                                    |
 ___________________         _________                                |
|                   |       |         |                               | mmap memory
| Other framework   |       |  uacce  |                               | r/w interface
| crypto/nic/others |       |_________|                               |
|___________________|                                                 |
         |                       |                                    |
         | register              | register                           |
         |                       |                                    |
         |                       |                                    |
         |                _________________       __________          |
         |               |                 |     |          |         |
          -------------  |  Device Driver  |     |  IOMMU   |         |
                         |_________________|     |__________|         |
                                 |                                    |
                                 |                                    V
                                 |                            ___________________
                                 |                           |                   |
                                 --------------------------  |  Device(Hardware) |
                                                             |___________________|”h]”hX‹                           ___________________                  ________________
                        |                   |   user API     |                |
                        | WarpDrive library | ------------>  |  user driver   |
                        |___________________|                |________________|
                                 |                                    |
                                 |                                    |
                                 | queue fd                           |
                                 |                                    |
                                 |                                    |
                                 v                                    |
 ___________________         _________                                |
|                   |       |         |                               | mmap memory
| Other framework   |       |  uacce  |                               | r/w interface
| crypto/nic/others |       |_________|                               |
|___________________|                                                 |
         |                       |                                    |
         | register              | register                           |
         |                       |                                    |
         |                       |                                    |
         |                _________________       __________          |
         |               |                 |     |          |         |
          -------------  |  Device Driver  |     |  IOMMU   |         |
                         |_________________|     |__________|         |
                                 |                                    |
                                 |                                    V
                                 |                            ___________________
                                 |                           |                   |
                                 --------------------------  |  Device(Hardware) |
                                                             |___________________|”…””}”hj,  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1hÙhŸh³h K8hhñhžhubeh}”(h]”Œarchitecture”ah ]”h"]”Œarchitecture”ah$]”h&]”uh1h´hhhžhhŸh³h K*ubhµ)”}”(hhh]”(hº)”}”(hŒHow does it work”h]”hŒHow does it work”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjB  hžhhŸh³h KXubhÊ)”}”(hŒ,Uacce uses mmap and IOMMU to play the trick.”h]”hŒ,Uacce uses mmap and IOMMU to play the trick.”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KZhjB  hžhubhÊ)”}”(hXˆ  Uacce creates a chrdev for every device registered to it. New queue is
created when user application open the chrdev. The file descriptor is used
as the user handle of the queue.
The accelerator device present itself as an Uacce object, which exports as
a chrdev to the user space. The user application communicates with the
hardware by ioctl (as control path) or share memory (as data path).”h]”hXˆ  Uacce creates a chrdev for every device registered to it. New queue is
created when user application open the chrdev. The file descriptor is used
as the user handle of the queue.
The accelerator device present itself as an Uacce object, which exports as
a chrdev to the user space. The user application communicates with the
hardware by ioctl (as control path) or share memory (as data path).”…””}”(hja  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K\hjB  hžhubhÊ)”}”(hŒjThe control path to the hardware is via file operation, while data path is
via mmap space of the queue fd.”h]”hŒjThe control path to the hardware is via file operation, while data path is
via mmap space of the queue fd.”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KchjB  hžhubhÊ)”}”(hŒThe queue file address space:”h]”hŒThe queue file address space:”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KfhjB  hžhubhÚ)”}”(hŒÉ /**
 * enum uacce_qfrt: qfrt type
 * @UACCE_QFRT_MMIO: device mmio region
 * @UACCE_QFRT_DUS: device user share region
 */
enum uacce_qfrt {
        UACCE_QFRT_MMIO = 0,
        UACCE_QFRT_DUS = 1,
};”h]”hŒÉ /**
 * enum uacce_qfrt: qfrt type
 * @UACCE_QFRT_MMIO: device mmio region
 * @UACCE_QFRT_DUS: device user share region
 */
enum uacce_qfrt {
        UACCE_QFRT_MMIO = 0,
        UACCE_QFRT_DUS = 1,
};”…””}”hj‹  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1hÙhŸh³h KjhjB  hžhubhÊ)”}”(hŒ~All regions are optional and differ from device type to type.
Each region can be mmapped only once, otherwise -EEXIST returns.”h]”hŒ~All regions are optional and differ from device type to type.
Each region can be mmapped only once, otherwise -EEXIST returns.”…””}”(hj™  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KthjB  hžhubhÊ)”}”(hŒ¬The device mmio region is mapped to the hardware mmio space. It is generally
used for doorbell or other notification to the hardware. It is not fast enough
as data channel.”h]”hŒ¬The device mmio region is mapped to the hardware mmio space. It is generally
used for doorbell or other notification to the hardware. It is not fast enough
as data channel.”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KwhjB  hžhubhÊ)”}”(hŒ[The device user share region is used for share data buffer between user process
and device.”h]”hŒ[The device user share region is used for share data buffer between user process
and device.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K{hjB  hžhubeh}”(h]”Œhow-does-it-work”ah ]”h"]”Œhow does it work”ah$]”h&]”uh1h´hhhžhhŸh³h KXubhµ)”}”(hhh]”(hº)”}”(hŒThe Uacce register API”h]”hŒThe Uacce register API”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjË  hžhhŸh³h K€ubhÊ)”}”(hŒ'The register API is defined in uacce.h.”h]”hŒ'The register API is defined in uacce.h.”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K‚hjË  hžhubhÚ)”}”(hŒrstruct uacce_interface {
  char name[UACCE_MAX_NAME_SIZE];
  unsigned int flags;
  const struct uacce_ops *ops;
};”h]”hŒrstruct uacce_interface {
  char name[UACCE_MAX_NAME_SIZE];
  unsigned int flags;
  const struct uacce_ops *ops;
};”…””}”hjê  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1hÙhŸh³h K†hjË  hžhubhÊ)”}”(hŒ@According to the IOMMU capability, uacce_interface flags can be:”h]”hŒ@According to the IOMMU capability, uacce_interface flags can be:”…””}”(hjø  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŒhjË  hžhubhÚ)”}”(hX²  /**
 * UACCE Device flags:
 * UACCE_DEV_SVA: Shared Virtual Addresses
 *              Support PASID
 *              Support device page faults (PCI PRI or SMMU Stall)
 */
#define UACCE_DEV_SVA               BIT(0)

struct uacce_device *uacce_alloc(struct device *parent,
                                 struct uacce_interface *interface);
int uacce_register(struct uacce_device *uacce);
void uacce_remove(struct uacce_device *uacce);”h]”hX²  /**
 * UACCE Device flags:
 * UACCE_DEV_SVA: Shared Virtual Addresses
 *              Support PASID
 *              Support device page faults (PCI PRI or SMMU Stall)
 */
#define UACCE_DEV_SVA               BIT(0)

struct uacce_device *uacce_alloc(struct device *parent,
                                 struct uacce_interface *interface);
int uacce_register(struct uacce_device *uacce);
void uacce_remove(struct uacce_device *uacce);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1hÙhŸh³h KhjË  hžhubhÊ)”}”(hŒuacce_register results can be:”h]”hŒuacce_register results can be:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhjË  hžhubhŒenumerated_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ2If uacce module is not compiled, ERR_PTR(-ENODEV)
”h]”hÊ)”}”(hŒ1If uacce module is not compiled, ERR_PTR(-ENODEV)”h]”hŒ1If uacce module is not compiled, ERR_PTR(-ENODEV)”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KŸhj)  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j'  hj$  hžhhŸh³h Nubj(  )”}”(hŒSucceed with the desired flags
”h]”hÊ)”}”(hŒSucceed with the desired flags”h]”hŒSucceed with the desired flags”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¡hjA  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j'  hj$  hžhhŸh³h Nubj(  )”}”(hŒ/Succeed with the negotiated flags, for example
”h]”hÊ)”}”(hŒ.Succeed with the negotiated flags, for example”h]”hŒ.Succeed with the negotiated flags, for example”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K£hjY  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j'  hj$  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œ
loweralpha”Œprefix”hŒsuffix”Œ.”uh1j"  hjË  hžhhŸh³h KŸubhŒblock_quote”“”)”}”(hŒ™uacce_interface.flags = UACCE_DEV_SVA but uacce->flags = ~UACCE_DEV_SVA

So user driver need check return value as well as the negotiated uacce->flags.

”h]”(hÊ)”}”(hŒGuacce_interface.flags = UACCE_DEV_SVA but uacce->flags = ~UACCE_DEV_SVA”h]”hŒGuacce_interface.flags = UACCE_DEV_SVA but uacce->flags = ~UACCE_DEV_SVA”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¥hj~  ubhÊ)”}”(hŒNSo user driver need check return value as well as the negotiated uacce->flags.”h]”hŒNSo user driver need check return value as well as the negotiated uacce->flags.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K§hj~  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j|  hŸh³h K¥hjË  hžhubeh}”(h]”Œthe-uacce-register-api”ah ]”h"]”Œthe uacce register api”ah$]”h&]”uh1h´hhhžhhŸh³h K€ubhµ)”}”(hhh]”(hº)”}”(hŒThe user driver”h]”hŒThe user driver”…””}”(hj¯  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¬  hžhhŸh³h K«ubhÊ)”}”(hŒûThe queue file mmap space will need a user driver to wrap the communication
protocol. Uacce provides some attributes in sysfs for the user driver to
match the right accelerator accordingly.
More details in Documentation/ABI/testing/sysfs-driver-uacce.”h]”hŒûThe queue file mmap space will need a user driver to wrap the communication
protocol. Uacce provides some attributes in sysfs for the user driver to
match the right accelerator accordingly.
More details in Documentation/ABI/testing/sysfs-driver-uacce.”…””}”(hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K­hj¬  hžhubeh}”(h]”Œthe-user-driver”ah ]”h"]”Œthe user driver”ah$]”h&]”uh1h´hhhžhhŸh³h K«ubeh}”(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”}”(hîhëj?  j<  jÈ  jÅ  j©  j¦  jÐ  jÍ  uŒ	nametypes”}”(hî‰j?  ‰jÈ  ‰j©  ‰jÐ  ‰uh}”(hëh¶j<  hñjÅ  jB  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.