€•˜À      Œ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/target/tcmu-design”Œ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/target/tcmu-design”Œ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/target/tcmu-design”Œ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/target/tcmu-design”Œ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/target/tcmu-design”Œ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/target/tcmu-design”Œ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ŒTCM Userspace Design”h]”hŒTCM Userspace Design”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒ@/var/lib/git/docbuild/linux/Documentation/target/tcmu-design.rst”h KubhŒcomment”“”)”}”(hX”  Contents:

1) Design
  a) Background
  b) Benefits
  c) Design constraints
  d) Implementation overview
     i. Mailbox
     ii. Command ring
     iii. Data Area
  e) Device discovery
  f) Device events
  g) Other contingencies
2) Writing a user pass-through handler
  a) Discovering and configuring TCMU uio devices
  b) Waiting for events on the device(s)
  c) Managing the command ring
3) A final note”h]”hX”  Contents:

1) Design
  a) Background
  b) Benefits
  c) Design constraints
  d) Implementation overview
     i. Mailbox
     ii. Command ring
     iii. Data Area
  e) Device discovery
  f) Device events
  g) Other contingencies
2) Writing a user pass-through handler
  a) Discovering and configuring TCMU uio devices
  b) Waiting for events on the device(s)
  c) Managing the command ring
3) A final note”…””}”hh¹sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h·hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒDesign”h]”hŒDesign”…””}”(hhÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhÉhžhhŸh¶h KubhŒ	paragraph”“”)”}”(hŒéTCM is another name for LIO, an in-kernel iSCSI target (server).
Existing TCM targets run in the kernel.  TCMU (TCM in Userspace)
allows userspace programs to be written which act as iSCSI targets.
This document describes the design.”h]”hŒéTCM is another name for LIO, an in-kernel iSCSI target (server).
Existing TCM targets run in the kernel.  TCMU (TCM in Userspace)
allows userspace programs to be written which act as iSCSI targets.
This document describes the design.”…””}”(hhÜhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KhhÉhžhubhÛ)”}”(hXK  The existing kernel provides modules for different SCSI transport
protocols.  TCM also modularizes the data storage.  There are existing
modules for file, block device, RAM or using another SCSI device as
storage.  These are called "backstores" or "storage engines".  These
built-in modules are implemented entirely as kernel code.”h]”hXS  The existing kernel provides modules for different SCSI transport
protocols.  TCM also modularizes the data storage.  There are existing
modules for file, block device, RAM or using another SCSI device as
storage.  These are called â€œbackstoresâ€ or â€œstorage enginesâ€.  These
built-in modules are implemented entirely as kernel code.”…””}”(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Œ
Background”h]”hŒ
Background”…””}”(hhûhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhøhžhhŸh¶h K)ubhÛ)”}”(hXÓ  In addition to modularizing the transport protocol used for carrying
SCSI commands ("fabrics"), the Linux kernel target, LIO, also modularizes
the actual data storage as well. These are referred to as "backstores"
or "storage engines". The target comes with backstores that allow a
file, a block device, RAM, or another SCSI device to be used for the
local storage needed for the exported SCSI LUN. Like the rest of LIO,
these are implemented entirely as kernel code.”h]”hXß  In addition to modularizing the transport protocol used for carrying
SCSI commands (â€œfabricsâ€), the Linux kernel target, LIO, also modularizes
the actual data storage as well. These are referred to as â€œbackstoresâ€
or â€œstorage enginesâ€. The target comes with backstores that allow a
file, a block device, RAM, or another SCSI device to be used for the
local storage needed for the exported SCSI LUN. Like the rest of LIO,
these are implemented entirely as kernel code.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K+hhøhžhubhÛ)”}”(hX‚  These backstores cover the most common use cases, but not all. One new
use case that other non-kernel target solutions, such as tgt, are able
to support is using Gluster's GLFS or Ceph's RBD as a backstore. The
target then serves as a translator, allowing initiators to store data
in these non-traditional networked storage systems, while still only
using standard protocols themselves.”h]”hX†  These backstores cover the most common use cases, but not all. One new
use case that other non-kernel target solutions, such as tgt, are able
to support is using Glusterâ€™s GLFS or Cephâ€™s RBD as a backstore. The
target then serves as a translator, allowing initiators to store data
in these non-traditional networked storage systems, while still only
using standard protocols themselves.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K3hhøhžhubhÛ)”}”(hŒÎIf the target is a userspace process, supporting these is easy. tgt,
for example, needs only a small adapter module for each, because the
modules just use the available userspace libraries for RBD and GLFS.”h]”hŒÎIf the target is a userspace process, supporting these is easy. tgt,
for example, needs only a small adapter module for each, because the
modules just use the available userspace libraries for RBD and GLFS.”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K:hhøhžhubhÛ)”}”(hX'  Adding support for these backstores in LIO is considerably more
difficult, because LIO is entirely kernel code. Instead of undertaking
the significant work to port the GLFS or RBD APIs and protocols to the
kernel, another approach is to create a userspace pass-through
backstore for LIO, "TCMU".”h]”hX+  Adding support for these backstores in LIO is considerably more
difficult, because LIO is entirely kernel code. Instead of undertaking
the significant work to port the GLFS or RBD APIs and protocols to the
kernel, another approach is to create a userspace pass-through
backstore for LIO, â€œTCMUâ€.”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K>hhøhžhubeh}”(h]”Œ
background”ah ]”h"]”Œ
background”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h K)ubh¢)”}”(hhh]”(h§)”}”(hŒBenefits”h]”hŒBenefits”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjI  hžhhŸh¶h KFubhÛ)”}”(hX2  In addition to allowing relatively easy support for RBD and GLFS, TCMU
will also allow easier development of new backstores. TCMU combines
with the LIO loopback fabric to become something similar to FUSE
(Filesystem in Userspace), but at the SCSI layer instead of the
filesystem layer. A SUSE, if you will.”h]”hX2  In addition to allowing relatively easy support for RBD and GLFS, TCMU
will also allow easier development of new backstores. TCMU combines
with the LIO loopback fabric to become something similar to FUSE
(Filesystem in Userspace), but at the SCSI layer instead of the
filesystem layer. A SUSE, if you will.”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KHhjI  hžhubhÛ)”}”(hŒÈThe disadvantage is there are more distinct components to configure, and
potentially to malfunction. This is unavoidable, but hopefully not
fatal if we're careful to keep things as simple as possible.”h]”hŒÊThe disadvantage is there are more distinct components to configure, and
potentially to malfunction. This is unavoidable, but hopefully not
fatal if weâ€™re careful to keep things as simple as possible.”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KNhjI  hžhubeh}”(h]”Œbenefits”ah ]”h"]”Œbenefits”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h KFubh¢)”}”(hhh]”(h§)”}”(hŒDesign constraints”h]”hŒDesign constraints”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj~  hžhhŸh¶h KSubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ.Good performance: high throughput, low latency”h]”hÛ)”}”(hj˜  h]”hŒ.Good performance: high throughput, low latency”…””}”(hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KUhj–  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj‘  hžhhŸh¶h Nubj•  )”}”(hŒSCleanly handle if userspace:

 1) never attaches
 2) hangs
 3) dies
 4) misbehaves
”h]”(hÛ)”}”(hŒCleanly handle if userspace:”h]”hŒCleanly handle if userspace:”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KVhj­  ubhŒblock_quote”“”)”}”(hŒ11) never attaches
2) hangs
3) dies
4) misbehaves
”h]”hŒenumerated_list”“”)”}”(hhh]”(j•  )”}”(hŒnever attaches”h]”hÛ)”}”(hjÌ  h]”hŒnever attaches”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KXhjÊ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjÇ  ubj•  )”}”(hŒhangs”h]”hÛ)”}”(hjã  h]”hŒhangs”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KYhjá  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjÇ  ubj•  )”}”(hŒdies”h]”hÛ)”}”(hjú  h]”hŒdies”…””}”(hjü  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KZhjø  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjÇ  ubj•  )”}”(hŒmisbehaves
”h]”hÛ)”}”(hŒ
misbehaves”h]”hŒ
misbehaves”…””}”(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Ç  ubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ)”uh1jÅ  hjÁ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¿  hŸh¶h KXhj­  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj‘  hžhhŸh¶h Nubj•  )”}”(hŒ9Allow future flexibility in user & kernel implementations”h]”hÛ)”}”(hj@  h]”hŒ9Allow future flexibility in user & kernel implementations”…””}”(hjB  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ŒBe reasonably memory-efficient”h]”hÛ)”}”(hjW  h]”hŒBe reasonably memory-efficient”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K^hjU  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj‘  hžhhŸh¶h Nubj•  )”}”(hŒSimple to configure & run”h]”hÛ)”}”(hjn  h]”hŒSimple to configure & run”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K_hjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj‘  hžhhŸh¶h Nubj•  )”}”(hŒ%Simple to write a userspace backend

”h]”hÛ)”}”(hŒ#Simple to write a userspace backend”h]”hŒ#Simple to write a userspace backend”…””}”(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 Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j  hŸh¶h KUhj~  hžhubeh}”(h]”Œdesign-constraints”ah ]”h"]”Œdesign constraints”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h KSubh¢)”}”(hhh]”(h§)”}”(hŒImplementation overview”h]”hŒImplementation overview”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj«  hžhhŸh¶h KdubhÛ)”}”(hX  The core of the TCMU interface is a memory region that is shared
between kernel and userspace. Within this region is: a control area
(mailbox); a lockless producer/consumer circular buffer for commands
to be passed up, and status returned; and an in/out data buffer area.”h]”hX  The core of the TCMU interface is a memory region that is shared
between kernel and userspace. Within this region is: a control area
(mailbox); a lockless producer/consumer circular buffer for commands
to be passed up, and status returned; and an in/out data buffer area.”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kfhj«  hžhubhÛ)”}”(hX°  TCMU uses the pre-existing UIO subsystem. UIO allows device driver
development in userspace, and this is conceptually very close to the
TCMU use case, except instead of a physical device, TCMU implements a
memory-mapped layout designed for SCSI commands. Using UIO also
benefits TCMU by handling device introspection (e.g. a way for
userspace to determine how large the shared region is) and signaling
mechanisms in both directions.”h]”hX°  TCMU uses the pre-existing UIO subsystem. UIO allows device driver
development in userspace, and this is conceptually very close to the
TCMU use case, except instead of a physical device, TCMU implements a
memory-mapped layout designed for SCSI commands. Using UIO also
benefits TCMU by handling device introspection (e.g. a way for
userspace to determine how large the shared region is) and signaling
mechanisms in both directions.”…””}”(hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kkhj«  hžhubhÛ)”}”(hX  There are no embedded pointers in the memory region. Everything is
expressed as an offset from the region's starting address. This allows
the ring to still work if the user process dies and is restarted with
the region mapped at a different virtual address.”h]”hX  There are no embedded pointers in the memory region. Everything is
expressed as an offset from the regionâ€™s starting address. This allows
the ring to still work if the user process dies and is restarted with
the region mapped at a different virtual address.”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kshj«  hžhubhÛ)”}”(hŒ2See target_core_user.h for the struct definitions.”h]”hŒ2See target_core_user.h for the struct definitions.”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kxhj«  hžhubeh}”(h]”Œimplementation-overview”ah ]”h"]”Œimplementation overview”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h Kdubh¢)”}”(hhh]”(h§)”}”(hŒThe Mailbox”h]”hŒThe Mailbox”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjü  hžhhŸh¶h K{ubhÛ)”}”(hX3  The mailbox is always at the start of the shared memory region, and
contains a version, details about the starting offset and size of the
command ring, and head and tail pointers to be used by the kernel and
userspace (respectively) to put commands on the ring, and indicate
when the commands are completed.”h]”hX3  The mailbox is always at the start of the shared memory region, and
contains a version, details about the starting offset and size of the
command ring, and head and tail pointers to be used by the kernel and
userspace (respectively) to put commands on the ring, and indicate
when the commands are completed.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K}hjü  hžhubhÛ)”}”(hŒ1version - 1 (userspace should abort if otherwise)”h]”hŒ1version - 1 (userspace should abort if otherwise)”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kƒhjü  hžhubhŒdefinition_list”“”)”}”(hhh]”(hŒdefinition_list_item”“”)”}”(hŒflags:
- TCMU_MAILBOX_FLAG_CAP_OOOC:
    indicates out-of-order completion is supported.
    See "The Command Ring" for details.
”h]”(hŒterm”“”)”}”(hŒflags:”h]”hŒflags:”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4  hŸh¶h Kˆhj0  ubhŒ
definition”“”)”}”(hhh]”j  )”}”(hhh]”j•  )”}”(hŒtTCMU_MAILBOX_FLAG_CAP_OOOC:
  indicates out-of-order completion is supported.
  See "The Command Ring" for details.
”h]”j*  )”}”(hhh]”j/  )”}”(hŒpTCMU_MAILBOX_FLAG_CAP_OOOC:
indicates out-of-order completion is supported.
See "The Command Ring" for details.
”h]”(j5  )”}”(hŒTCMU_MAILBOX_FLAG_CAP_OOOC:”h]”hŒTCMU_MAILBOX_FLAG_CAP_OOOC:”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4  hŸh¶h KˆhjS  ubjE  )”}”(hhh]”hÛ)”}”(hŒSindicates out-of-order completion is supported.
See "The Command Ring" for details.”h]”hŒWindicates out-of-order completion is supported.
See â€œThe Command Ringâ€ for details.”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K‡hje  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jD  hjS  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j.  hŸh¶h KˆhjP  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j)  hjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjI  ubah}”(h]”h ]”h"]”h$]”h&]”j¡  j¢  uh1j  hŸh¶h K†hjF  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jD  hj0  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j.  hŸh¶h Kˆhj+  ubj/  )”}”(hŒzcmdr_off
The offset of the start of the command ring from the start
of the memory region, to account for the mailbox size.”h]”(j5  )”}”(hŒcmdr_off”h]”hŒcmdr_off”…””}”(hj¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4  hŸh¶h K‹hj   ubjE  )”}”(hhh]”hÛ)”}”(hŒqThe offset of the start of the command ring from the start
of the memory region, to account for the mailbox size.”h]”hŒqThe offset of the start of the command ring from the start
of the memory region, to account for the mailbox size.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K‹hj²  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jD  hj   ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j.  hŸh¶h K‹hj+  hžhubj/  )”}”(hŒRcmdr_size
The size of the command ring. This does *not* need to be a
power of two.”h]”(j5  )”}”(hŒ	cmdr_size”h]”hŒ	cmdr_size”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4  hŸh¶h KŽhjÏ  ubjE  )”}”(hhh]”hÛ)”}”(hŒHThe size of the command ring. This does *not* need to be a
power of two.”h]”(hŒ(The size of the command ring. This does ”…””}”(hjä  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*not*”h]”hŒnot”…””}”(hjî  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jì  hjä  ubhŒ need to be a
power of two.”…””}”(hjä  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KŽhjá  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jD  hjÏ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j.  hŸh¶h KŽhj+  hžhubj/  )”}”(hŒWcmd_head
Modified by the kernel to indicate when a command has been
placed on the ring.”h]”(j5  )”}”(hŒcmd_head”h]”hŒcmd_head”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4  hŸh¶h K‘hj  ubjE  )”}”(hhh]”hÛ)”}”(hŒNModified by the kernel to indicate when a command has been
placed on the ring.”h]”hŒNModified by the kernel to indicate when a command has been
placed on the ring.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K‘hj$  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jD  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j.  hŸh¶h K‘hj+  hžhubj/  )”}”(hŒZcmd_tail
Modified by userspace to indicate when it has completed
processing of a command.
”h]”(j5  )”}”(hŒcmd_tail”h]”hŒcmd_tail”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j4  hŸh¶h K•hjA  ubjE  )”}”(hhh]”hÛ)”}”(hŒPModified by userspace to indicate when it has completed
processing of a command.”h]”hŒPModified by userspace to indicate when it has completed
processing of a command.”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K”hjS  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jD  hjA  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j.  hŸh¶h K•hj+  hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1j)  hjü  hžhhŸNh Nubeh}”(h]”Œthe-mailbox”ah ]”h"]”Œthe mailbox”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h K{ubh¢)”}”(hhh]”(h§)”}”(hŒThe Command Ring”h]”hŒThe Command Ring”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj~  hžhhŸh¶h K˜ubhÛ)”}”(hX¡  Commands are placed on the ring by the kernel incrementing
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
then signaling userspace via uio_event_notify(). Once the command is
completed, userspace updates mailbox.cmd_tail in the same way and
signals the kernel via a 4-byte write(). When cmd_head equals
cmd_tail, the ring is empty -- no commands are currently waiting to be
processed by userspace.”h]”hX¡  Commands are placed on the ring by the kernel incrementing
mailbox.cmd_head by the size of the command, modulo cmdr_size, and
then signaling userspace via uio_event_notify(). Once the command is
completed, userspace updates mailbox.cmd_tail in the same way and
signals the kernel via a 4-byte write(). When cmd_head equals
cmd_tail, the ring is empty -- no commands are currently waiting to be
processed by userspace.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kšhj~  hžhubhÛ)”}”(hX  TCMU commands are 8-byte aligned. They start with a common header
containing "len_op", a 32-bit value that stores the length, as well as
the opcode in the lowest unused bits. It also contains cmd_id and
flags fields for setting by the kernel (kflags) and userspace
(uflags).”h]”hX  TCMU commands are 8-byte aligned. They start with a common header
containing â€œlen_opâ€, a 32-bit value that stores the length, as well as
the opcode in the lowest unused bits. It also contains cmd_id and
flags fields for setting by the kernel (kflags) and userspace
(uflags).”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K¢hj~  hžhubhÛ)”}”(hŒDCurrently only two opcodes are defined, TCMU_OP_CMD and TCMU_OP_PAD.”h]”hŒDCurrently only two opcodes are defined, TCMU_OP_CMD and TCMU_OP_PAD.”…””}”(hj«  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K¨hj~  hžhubhÛ)”}”(hX»  When the opcode is CMD, the entry in the command ring is a struct
tcmu_cmd_entry. Userspace finds the SCSI CDB (Command Data Block) via
tcmu_cmd_entry.req.cdb_off. This is an offset from the start of the
overall shared memory region, not the entry. The data in/out buffers
are accessible via the req.iov[] array. iov_cnt contains the number of
entries in iov[] needed to describe either the Data-In or Data-Out
buffers. For bidirectional commands, iov_cnt specifies how many iovec
entries cover the Data-Out area, and iov_bidi_cnt specifies how many
iovec entries immediately after that in iov[] cover the Data-In
area. Just like other fields, iov.iov_base is an offset from the start
of the region.”h]”hX»  When the opcode is CMD, the entry in the command ring is a struct
tcmu_cmd_entry. Userspace finds the SCSI CDB (Command Data Block) via
tcmu_cmd_entry.req.cdb_off. This is an offset from the start of the
overall shared memory region, not the entry. The data in/out buffers
are accessible via the req.iov[] array. iov_cnt contains the number of
entries in iov[] needed to describe either the Data-In or Data-Out
buffers. For bidirectional commands, iov_cnt specifies how many iovec
entries cover the Data-Out area, and iov_bidi_cnt specifies how many
iovec entries immediately after that in iov[] cover the Data-In
area. Just like other fields, iov.iov_base is an offset from the start
of the region.”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kªhj~  hžhubhÛ)”}”(hŒþWhen completing a command, userspace sets rsp.scsi_status, and
rsp.sense_buffer if necessary. Userspace then increments
mailbox.cmd_tail by entry.hdr.length (mod cmdr_size) and signals the
kernel via the UIO method, a 4-byte write to the file descriptor.”h]”hŒþWhen completing a command, userspace sets rsp.scsi_status, and
rsp.sense_buffer if necessary. Userspace then increments
mailbox.cmd_tail by entry.hdr.length (mod cmdr_size) and signals the
kernel via the UIO method, a 4-byte write to the file descriptor.”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K¶hj~  hžhubhÛ)”}”(hX  If TCMU_MAILBOX_FLAG_CAP_OOOC is set for mailbox->flags, kernel is
capable of handling out-of-order completions. In this case, userspace can
handle command in different order other than original. Since kernel would
still process the commands in the same order it appeared in the command
ring, userspace need to update the cmd->id when completing the
command(a.k.a steal the original command's entry).”h]”hX’  If TCMU_MAILBOX_FLAG_CAP_OOOC is set for mailbox->flags, kernel is
capable of handling out-of-order completions. In this case, userspace can
handle command in different order other than original. Since kernel would
still process the commands in the same order it appeared in the command
ring, userspace need to update the cmd->id when completing the
command(a.k.a steal the original commandâ€™s entry).”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h K»hj~  hžhubhÛ)”}”(hŒ²When the opcode is PAD, userspace only updates cmd_tail as above --
it's a no-op. (The kernel inserts PAD entries to ensure each CMD entry
is contiguous within the command ring.)”h]”hŒ´When the opcode is PAD, userspace only updates cmd_tail as above --
itâ€™s a no-op. (The kernel inserts PAD entries to ensure each CMD entry
is contiguous within the command ring.)”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KÂhj~  hžhubhÛ)”}”(hŒÚMore opcodes may be added in the future. If userspace encounters an
opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in
hdr.uflags, update cmd_tail, and proceed with processing additional
commands, if any.”h]”hŒÚMore opcodes may be added in the future. If userspace encounters an
opcode it does not handle, it must set UNKNOWN_OP bit (bit 0) in
hdr.uflags, update cmd_tail, and proceed with processing additional
commands, if any.”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KÆhj~  hžhubeh}”(h]”Œthe-command-ring”ah ]”h"]”Œthe command ring”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h K˜ubh¢)”}”(hhh]”(h§)”}”(hŒThe Data Area”h]”hŒThe Data Area”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KÌubhÛ)”}”(hŒ¾This is shared-memory space after the command ring. The organization
of this area is not defined in the TCMU interface, and userspace
should access only the parts referenced by pending iovs.”h]”hŒ¾This is shared-memory space after the command ring. The organization
of this area is not defined in the TCMU interface, and userspace
should access only the parts referenced by pending iovs.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KÎhj  hžhubeh}”(h]”Œthe-data-area”ah ]”h"]”Œthe data area”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h KÌubh¢)”}”(hhh]”(h§)”}”(hŒDevice Discovery”h]”hŒDevice Discovery”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj.  hžhhŸh¶h KÔubhÛ)”}”(hX  Other devices may be using UIO besides TCMU. Unrelated user processes
may also be handling different sets of TCMU devices. TCMU userspace
processes must find their devices by scanning sysfs
class/uio/uio*/name. For TCMU devices, these names will be of the
format::”h]”hX  Other devices may be using UIO besides TCMU. Unrelated user processes
may also be handling different sets of TCMU devices. TCMU userspace
processes must find their devices by scanning sysfs
class/uio/uio*/name. For TCMU devices, these names will be of the
format:”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KÖhj.  hžhubhŒliteral_block”“”)”}”(hŒ1tcm-user/<hba_num>/<device_name>/<subtype>/<path>”h]”hŒ1tcm-user/<hba_num>/<device_name>/<subtype>/<path>”…””}”hjO  sbah}”(h]”h ]”h"]”h$]”h&]”hÇhÈuh1jM  hŸh¶h KÜhj.  hžhubhÛ)”}”(hŒØwhere "tcm-user" is common for all TCMU-backed UIO devices. <hba_num>
and <device_name> allow userspace to find the device's path in the
kernel target's configfs tree. Assuming the usual mount point, it is
found at::”h]”hŒßwhere â€œtcm-userâ€ is common for all TCMU-backed UIO devices. <hba_num>
and <device_name> allow userspace to find the deviceâ€™s path in the
kernel targetâ€™s configfs tree. Assuming the usual mount point, it is
found at:”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KÞhj.  hžhubjN  )”}”(hŒ;/sys/kernel/config/target/core/user_<hba_num>/<device_name>”h]”hŒ;/sys/kernel/config/target/core/user_<hba_num>/<device_name>”…””}”hjk  sbah}”(h]”h ]”h"]”h$]”h&]”hÇhÈuh1jM  hŸh¶h Kãhj.  hžhubhÛ)”}”(hŒnThis location contains attributes such as "hw_block_size", that
userspace needs to know for correct operation.”h]”hŒrThis location contains attributes such as â€œhw_block_sizeâ€, that
userspace needs to know for correct operation.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kåhj.  hžhubhÛ)”}”(hX&  <subtype> will be a userspace-process-unique string to identify the
TCMU device as expecting to be backed by a certain handler, and <path>
will be an additional handler-specific string for the user process to
configure the device, if needed. The name cannot contain ':', due to
LIO limitations.”h]”hX*  <subtype> will be a userspace-process-unique string to identify the
TCMU device as expecting to be backed by a certain handler, and <path>
will be an additional handler-specific string for the user process to
configure the device, if needed. The name cannot contain â€˜:â€™, due to
LIO limitations.”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kèhj.  hžhubhÛ)”}”(hŒRFor all devices so discovered, the user handler opens /dev/uioX and
calls mmap()::”h]”hŒQFor all devices so discovered, the user handler opens /dev/uioX and
calls mmap():”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kîhj.  hžhubjN  )”}”(hŒ9mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)”h]”hŒ9mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0)”…””}”hj£  sbah}”(h]”h ]”h"]”h$]”h&]”hÇhÈuh1jM  hŸh¶h Kñhj.  hžhubhÛ)”}”(hŒSwhere size must be equal to the value read from
/sys/class/uio/uioX/maps/map0/size.”h]”hŒSwhere size must be equal to the value read from
/sys/class/uio/uioX/maps/map0/size.”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Kóhj.  hžhubeh}”(h]”Œdevice-discovery”ah ]”h"]”Œdevice discovery”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h KÔubh¢)”}”(hhh]”(h§)”}”(hŒDevice Events”h]”hŒDevice Events”…””}”(hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÇ  hžhhŸh¶h KøubhÛ)”}”(hXÊ  If a new device is added or removed, a notification will be broadcast
over netlink, using a generic netlink family name of "TCM-USER" and a
multicast group named "config". This will include the UIO name as
described in the previous section, as well as the UIO minor
number. This should allow userspace to identify both the UIO device and
the LIO device, so that after determining the device is supported
(based on subtype) it can take the appropriate action.”h]”hXÒ  If a new device is added or removed, a notification will be broadcast
over netlink, using a generic netlink family name of â€œTCM-USERâ€ and a
multicast group named â€œconfigâ€. This will include the UIO name as
described in the previous section, as well as the UIO minor
number. This should allow userspace to identify both the UIO device and
the LIO device, so that after determining the device is supported
(based on subtype) it can take the appropriate action.”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h KúhjÇ  hžhubeh}”(h]”Œdevice-events”ah ]”h"]”Œdevice events”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h Køubh¢)”}”(hhh]”(h§)”}”(hŒOther contingencies”h]”hŒOther contingencies”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjî  hžhhŸh¶h MubhÛ)”}”(hŒ)Userspace handler process never attaches:”h]”hŒ)Userspace handler process never attaches:”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhjî  hžhubj  )”}”(hhh]”j•  )”}”(hŒRTCMU will post commands, and then abort them after a timeout period
(30 seconds.)
”h]”hÛ)”}”(hŒQTCMU will post commands, and then abort them after a timeout period
(30 seconds.)”h]”hŒQTCMU will post commands, and then abort them after a timeout period
(30 seconds.)”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”j¡  j¢  uh1j  hŸh¶h Mhjî  hžhubhÛ)”}”(hŒ$Userspace handler process is killed:”h]”hŒ$Userspace handler process is killed:”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhjî  hžhubj  )”}”(hhh]”j•  )”}”(hŒ£It is still possible to restart and re-connect to TCMU
devices. Command ring is preserved. However, after the timeout period,
the kernel will abort pending tasks.
”h]”hÛ)”}”(hŒ¢It is still possible to restart and re-connect to TCMU
devices. Command ring is preserved. However, after the timeout period,
the kernel will abort pending tasks.”h]”hŒ¢It is still possible to restart and re-connect to TCMU
devices. Command ring is preserved. However, after the timeout period,
the kernel will abort pending tasks.”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhj?  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj<  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”j¡  j¢  uh1j  hŸh¶h Mhjî  hžhubhÛ)”}”(hŒ Userspace handler process hangs:”h]”hŒ Userspace handler process hangs:”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhjî  hžhubj  )”}”(hhh]”j•  )”}”(hŒ<The kernel will abort pending tasks after a timeout period.
”h]”hÛ)”}”(hŒ;The kernel will abort pending tasks after a timeout period.”h]”hŒ;The kernel will abort pending tasks after a timeout period.”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhjn  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjk  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”j¡  j¢  uh1j  hŸh¶h Mhjî  hžhubhÛ)”}”(hŒ'Userspace handler process is malicious:”h]”hŒ'Userspace handler process is malicious:”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhjî  hžhubj  )”}”(hhh]”j•  )”}”(hŒ–The process can trivially break the handling of devices it controls,
but should not be able to access kernel memory outside its shared
memory areas.

”h]”hÛ)”}”(hŒ”The process can trivially break the handling of devices it controls,
but should not be able to access kernel memory outside its shared
memory areas.”h]”hŒ”The process can trivially break the handling of devices it controls,
but should not be able to access kernel memory outside its shared
memory areas.”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h Mhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjš  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”j¡  j¢  uh1j  hŸh¶h Mhjî  hžhubeh}”(h]”Œother-contingencies”ah ]”h"]”Œother contingencies”ah$]”h&]”uh1h¡hhÉhžhhŸh¶h Mubeh}”(h]”Œdesign”ah ]”h"]”Œdesign”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ7Writing a user pass-through handler (with example code)”h]”hŒ7Writing a user pass-through handler (with example code)”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjË  hžhhŸh¶h MubhÛ)”}”(hŒ@A user process handing a TCMU device must support the following:”h]”hŒ@A user process handing a TCMU device must support the following:”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h MhjË  hžhubjÆ  )”}”(hhh]”(j•  )”}”(hŒ,Discovering and configuring TCMU uio devices”h]”hÛ)”}”(hjï  h]”hŒ,Discovering and configuring TCMU uio devices”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M!hjí  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjê  hžhhŸh¶h Nubj•  )”}”(hŒ#Waiting for events on the device(s)”h]”hÛ)”}”(hj  h]”hŒ#Waiting for events on the device(s)”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M"hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjê  hžhhŸh¶h Nubj•  )”}”(hŒàManaging the command ring: Parsing operations and commands,
performing work as needed, setting response fields (scsi_status and
possibly sense_buffer), updating cmd_tail, and notifying the kernel
that work has been finished
”h]”hÛ)”}”(hŒßManaging the command ring: Parsing operations and commands,
performing work as needed, setting response fields (scsi_status and
possibly sense_buffer), updating cmd_tail, and notifying the kernel
that work has been finished”h]”hŒßManaging the command ring: Parsing operations and commands,
performing work as needed, setting response fields (scsi_status and
possibly sense_buffer), updating cmd_tail, and notifying the kernel
that work has been finished”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M#hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjê  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j-  Œ
loweralpha”j/  hj0  j1  uh1jÅ  hjË  hžhhŸh¶h M!ubhÛ)”}”(hŒ‘First, consider instead writing a plugin for tcmu-runner. tcmu-runner
implements all of this, and provides a higher-level API for plugin
authors.”h]”hŒ‘First, consider instead writing a plugin for tcmu-runner. tcmu-runner
implements all of this, and provides a higher-level API for plugin
authors.”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M(hjË  hžhubhÛ)”}”(hŒ¶TCMU is designed so that multiple unrelated processes can manage TCMU
devices separately. All handlers should make sure to only open their
devices, based opon a known subtype string.”h]”hŒ¶TCMU is designed so that multiple unrelated processes can manage TCMU
devices separately. All handlers should make sure to only open their
devices, based opon a known subtype string.”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M,hjË  hžhubjÆ  )”}”(hhh]”j•  )”}”(hX  Discovering and configuring TCMU UIO devices::

   /* error checking omitted for brevity */

   int fd, dev_fd;
   char buf[256];
   unsigned long long map_len;
   void *map;

   fd = open("/sys/class/uio/uio0/name", O_RDONLY);
   ret = read(fd, buf, sizeof(buf));
   close(fd);
   buf[ret-1] = '\0'; /* null-terminate and chop off the \n */

   /* we only want uio devices whose name is a format we expect */
   if (strncmp(buf, "tcm-user", 8))
     exit(-1);

   /* Further checking for subtype also needed here */

   fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
   ret = read(fd, buf, sizeof(buf));
   close(fd);
   str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */

   map_len = strtoull(buf, NULL, 0);

   dev_fd = open("/dev/uio0", O_RDWR);
   map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);


   b) Waiting for events on the device(s)

   while (1) {
     char buf[4];

     int ret = read(dev_fd, buf, 4); /* will block */

     handle_device_events(dev_fd, map);
   }

”h]”(hÛ)”}”(hŒ.Discovering and configuring TCMU UIO devices::”h]”hŒ-Discovering and configuring TCMU UIO devices:”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M0hjY  ubjN  )”}”(hXƒ  /* error checking omitted for brevity */

int fd, dev_fd;
char buf[256];
unsigned long long map_len;
void *map;

fd = open("/sys/class/uio/uio0/name", O_RDONLY);
ret = read(fd, buf, sizeof(buf));
close(fd);
buf[ret-1] = '\0'; /* null-terminate and chop off the \n */

/* we only want uio devices whose name is a format we expect */
if (strncmp(buf, "tcm-user", 8))
  exit(-1);

/* Further checking for subtype also needed here */

fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
ret = read(fd, buf, sizeof(buf));
close(fd);
str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */

map_len = strtoull(buf, NULL, 0);

dev_fd = open("/dev/uio0", O_RDWR);
map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);


b) Waiting for events on the device(s)

while (1) {
  char buf[4];

  int ret = read(dev_fd, buf, 4); /* will block */

  handle_device_events(dev_fd, map);
}”h]”hXƒ  /* error checking omitted for brevity */

int fd, dev_fd;
char buf[256];
unsigned long long map_len;
void *map;

fd = open("/sys/class/uio/uio0/name", O_RDONLY);
ret = read(fd, buf, sizeof(buf));
close(fd);
buf[ret-1] = '\0'; /* null-terminate and chop off the \n */

/* we only want uio devices whose name is a format we expect */
if (strncmp(buf, "tcm-user", 8))
  exit(-1);

/* Further checking for subtype also needed here */

fd = open(/sys/class/uio/%s/maps/map0/size, O_RDONLY);
ret = read(fd, buf, sizeof(buf));
close(fd);
str_buf[ret-1] = '\0'; /* null-terminate and chop off the \n */

map_len = strtoull(buf, NULL, 0);

dev_fd = open("/dev/uio0", O_RDWR);
map = mmap(NULL, map_len, PROT_READ|PROT_WRITE, MAP_SHARED, dev_fd, 0);


b) Waiting for events on the device(s)

while (1) {
  char buf[4];

  int ret = read(dev_fd, buf, 4); /* will block */

  handle_device_events(dev_fd, map);
}”…””}”hjk  sbah}”(h]”h ]”h"]”h$]”h&]”hÇhÈuh1jM  hŸh¶h M2hjY  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j”  hjV  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”j-  j9  j/  hj0  j1  uh1jÅ  hjË  hžhhŸh¶h M0ubjÆ  )”}”(hhh]”j•  )”}”(hXû  Managing the command ring::

   #include <linux/target_core_user.h>

   int handle_device_events(int fd, void *map)
   {
     struct tcmu_mailbox *mb = map;
     struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
     int did_some_work = 0;

     /* Process events from cmd ring until we catch up with cmd_head */
     while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {

       if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
         uint8_t *cdb = (void *)mb + ent->req.cdb_off;
         bool success = true;

         /* Handle command here. */
         printf("SCSI opcode: 0x%x\n", cdb[0]);

         /* Set response fields */
         if (success)
           ent->rsp.scsi_status = SCSI_NO_SENSE;
         else {
           /* Also fill in rsp->sense_buffer here */
           ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
         }
       }
       else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
         /* Tell the kernel we didn't handle unknown opcodes */
         ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
       }
       else {
         /* Do nothing for PAD entries except update cmd_tail */
       }

       /* update cmd_tail */
       mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
       ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
       did_some_work = 1;
     }

     /* Notify the kernel that work has been finished */
     if (did_some_work) {
       uint32_t buf = 0;

       write(fd, &buf, 4);
     }

     return 0;
   }

”h]”(hÛ)”}”(hŒManaging the command ring::”h]”hŒManaging the command ring:”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h MZhjˆ  ubjN  )”}”(hXd  #include <linux/target_core_user.h>

int handle_device_events(int fd, void *map)
{
  struct tcmu_mailbox *mb = map;
  struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
  int did_some_work = 0;

  /* Process events from cmd ring until we catch up with cmd_head */
  while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {

    if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
      uint8_t *cdb = (void *)mb + ent->req.cdb_off;
      bool success = true;

      /* Handle command here. */
      printf("SCSI opcode: 0x%x\n", cdb[0]);

      /* Set response fields */
      if (success)
        ent->rsp.scsi_status = SCSI_NO_SENSE;
      else {
        /* Also fill in rsp->sense_buffer here */
        ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
      }
    }
    else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
      /* Tell the kernel we didn't handle unknown opcodes */
      ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
    }
    else {
      /* Do nothing for PAD entries except update cmd_tail */
    }

    /* update cmd_tail */
    mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
    ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
    did_some_work = 1;
  }

  /* Notify the kernel that work has been finished */
  if (did_some_work) {
    uint32_t buf = 0;

    write(fd, &buf, 4);
  }

  return 0;
}”h]”hXd  #include <linux/target_core_user.h>

int handle_device_events(int fd, void *map)
{
  struct tcmu_mailbox *mb = map;
  struct tcmu_cmd_entry *ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
  int did_some_work = 0;

  /* Process events from cmd ring until we catch up with cmd_head */
  while (ent != (void *)mb + mb->cmdr_off + mb->cmd_head) {

    if (tcmu_hdr_get_op(ent->hdr.len_op) == TCMU_OP_CMD) {
      uint8_t *cdb = (void *)mb + ent->req.cdb_off;
      bool success = true;

      /* Handle command here. */
      printf("SCSI opcode: 0x%x\n", cdb[0]);

      /* Set response fields */
      if (success)
        ent->rsp.scsi_status = SCSI_NO_SENSE;
      else {
        /* Also fill in rsp->sense_buffer here */
        ent->rsp.scsi_status = SCSI_CHECK_CONDITION;
      }
    }
    else if (tcmu_hdr_get_op(ent->hdr.len_op) != TCMU_OP_PAD) {
      /* Tell the kernel we didn't handle unknown opcodes */
      ent->hdr.uflags |= TCMU_UFLAG_UNKNOWN_OP;
    }
    else {
      /* Do nothing for PAD entries except update cmd_tail */
    }

    /* update cmd_tail */
    mb->cmd_tail = (mb->cmd_tail + tcmu_hdr_get_len(&ent->hdr)) % mb->cmdr_size;
    ent = (void *) mb + mb->cmdr_off + mb->cmd_tail;
    did_some_work = 1;
  }

  /* Notify the kernel that work has been finished */
  if (did_some_work) {
    uint32_t buf = 0;

    write(fd, &buf, 4);
  }

  return 0;
}”…””}”hjš  sbah}”(h]”h ]”h"]”h$]”h&]”hÇhÈuh1jM  hŸh¶h M\hjˆ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j”  hj…  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”j-  j9  j/  hj0  j1  Œstart”Kuh1jÅ  hjË  hžhhŸh¶h MZubeh}”(h]”Œ5writing-a-user-pass-through-handler-with-example-code”ah ]”h"]”Œ7writing a user pass-through handler (with example code)”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Mubh¢)”}”(hhh]”(h§)”}”(hŒA final note”h]”hŒA final note”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj½  hžhhŸh¶h MubhÛ)”}”(hŒÎPlease be careful to return codes as defined by the SCSI
specifications. These are different than some values defined in the
scsi/scsi.h include file. For example, CHECK CONDITION's status code
is 2, not 1.”h]”hŒÐPlease be careful to return codes as defined by the SCSI
specifications. These are different than some values defined in the
scsi/scsi.h include file. For example, CHECK CONDITIONâ€™s status code
is 2, not 1.”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh¶h M’hj½  hžhubeh}”(h]”Œa-final-note”ah ]”h"]”Œa final note”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Mubeh}”(h]”Œtcm-userspace-design”ah ]”h"]”Œtcm userspace design”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Å  jF  jC  j{  jx  j¨  j¥  jù  jö  j{  jx  j  j  j+  j(  jÄ  jÁ  jë  jè  jÀ  j½  jº  j·  já  jÞ  uŒ	nametypes”}”(jé  ‰jÈ  ‰jF  ‰j{  ‰j¨  ‰jù  ‰j{  ‰j  ‰j+  ‰jÄ  ‰jë  ‰jÀ  ‰jº  ‰já  ‰uh}”(jæ  h£jÅ  hÉjC  højx  jI  j¥  j~  jö  j«  jx  jü  j  j~  j(  j  jÁ  j.  jè  jÇ  j½  jî  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”]”hŒsystem_message”“”)”}”(hhh]”hÛ)”}”(hŒ:Enumerated list start value not ordinal-1: "c" (ordinal 3)”h]”hŒ>Enumerated list start value not ordinal-1: â€œcâ€ (ordinal 3)”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhjs  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h¶Œline”Kuh1jq  hjË  hžhhŸh¶h MZubaŒtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.