€•Ï      Œ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/gpu/xe/xe_migrate”Œ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/gpu/xe/xe_migrate”Œ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/gpu/xe/xe_migrate”Œ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/gpu/xe/xe_migrate”Œ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/gpu/xe/xe_migrate”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/pt_BR/gpu/xe/xe_migrate”Œ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/gpu/xe/xe_migrate”Œ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+ OR MIT)”h]”hŒ*SPDX-License-Identifier: (GPL-2.0+ OR MIT)”…””}”hh·sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1hµhhh²hh³Œ?/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate.rst”h´KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒMigrate Layer”h]”hŒMigrate Layer”…””}”(hhÏh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhhÊh²hh³hÇh´KubhŒ	paragraph”“”)”}”(hŒØThe Xe migrate layer is used generate jobs which can copy memory (eviction),
clear memory, or program tables (binds). This layer exists in every GT, has
a migrate engine, and uses a special VM for all generated jobs.”h]”hŒØThe Xe migrate layer is used generate jobs which can copy memory (eviction),
clear memory, or program tables (binds). This layer exists in every GT, has
a migrate engine, and uses a special VM for all generated jobs.”…””}”(hhßh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K
hhÊh²hubhÉ)”}”(hhh]”(hÎ)”}”(hŒSpecial VM details”h]”hŒSpecial VM details”…””}”(hhñh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhhîh³Nh´NubhÞ)”}”(hŒêThe special VM is configured with a page structure where we can dynamically
map BOs which need to be copied and cleared, dynamically map other VM's page
table BOs for updates, and identity map the entire device's VRAM with 1 GB
pages.”h]”hŒîThe special VM is configured with a page structure where we can dynamically
map BOs which need to be copied and cleared, dynamically map other VMâ€™s page
table BOs for updates, and identity map the entire deviceâ€™s VRAM with 1 GB
pages.”…””}”(hhÿh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KhhîubhÞ)”}”(hXE  Currently the page structure consists of 32 physical pages with 16 being
reserved for BO mapping during copies and clear, 1 reserved for kernel binds,
several pages are needed to setup the identity mappings (exact number based
on how many bits of address space the device has), and the rest are reserved
user bind operations.”h]”hXE  Currently the page structure consists of 32 physical pages with 16 being
reserved for BO mapping during copies and clear, 1 reserved for kernel binds,
several pages are needed to setup the identity mappings (exact number based
on how many bits of address space the device has), and the rest are reserved
user bind operations.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KhhîubhÞ)”}”(hŒTODO: Diagram of layout”h]”hŒTODO: Diagram of layout”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´Khhîubeh}”(h]”Œspecial-vm-details”ah ]”h"]”Œspecial vm details”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒ	Bind jobs”h]”hŒ	Bind jobs”…””}”(hj7  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj4  h³Nh´NubhÞ)”}”(hŒ·A bind job consist of two batches and runs either on the migrate engine
(kernel binds) or the bind engine passed in (user binds). In both cases the
VM of the engine is the migrate VM.”h]”hŒ·A bind job consist of two batches and runs either on the migrate engine
(kernel binds) or the bind engine passed in (user binds). In both cases the
VM of the engine is the migrate VM.”…””}”(hjE  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K!hj4  ubhÞ)”}”(hXo  The first batch is used to update the migration VM page structure to point to
the bind VM page table BOs which need to be updated. A physical page is
required for this. If it is a user bind, the page is allocated from pool of
pages reserved user bind operations with drm_suballoc managing this pool. If
it is a kernel bind, the page reserved for kernel binds is used.”h]”hXo  The first batch is used to update the migration VM page structure to point to
the bind VM page table BOs which need to be updated. A physical page is
required for this. If it is a user bind, the page is allocated from pool of
pages reserved user bind operations with drm_suballoc managing this pool. If
it is a kernel bind, the page reserved for kernel binds is used.”…””}”(hjT  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K%hj4  ubhÞ)”}”(hŒ¢The first batch is only required for devices without VRAM as when the device
has VRAM the bind VM page table BOs are in VRAM and the identity mapping can
be used.”h]”hŒ¢The first batch is only required for devices without VRAM as when the device
has VRAM the bind VM page table BOs are in VRAM and the identity mapping can
be used.”…””}”(hjc  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K+hj4  ubhÞ)”}”(hŒÆThe second batch is used to program page table updated in the bind VM. Why
not just one batch? Well the TLBs need to be invalidated between these two
batches and that only can be done from the ring.”h]”hŒÆThe second batch is used to program page table updated in the bind VM. Why
not just one batch? Well the TLBs need to be invalidated between these two
batches and that only can be done from the ring.”…””}”(hjr  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K/hj4  ubhÞ)”}”(hŒÙWhen the bind job complete, the page allocated is returned the pool of pages
reserved for user bind operations if a user bind. No need do this for kernel
binds as the reserved kernel page is serially used by each job.”h]”hŒÙWhen the bind job complete, the page allocated is returned the pool of pages
reserved for user bind operations if a user bind. No need do this for kernel
binds as the reserved kernel page is serially used by each job.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K3hj4  ubeh}”(h]”Œ	bind-jobs”ah ]”h"]”Œ	bind jobs”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒCopy / clear jobs”h]”hŒCopy / clear jobs”…””}”(hj›  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj˜  h³Nh´NubhÞ)”}”(hŒJA copy or clear job consist of two batches and runs on the migrate engine.”h]”hŒJA copy or clear job consist of two batches and runs on the migrate engine.”…””}”(hj©  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K:hj˜  ubhÞ)”}”(hXy  Like binds, the first batch is used update the migration VM page structure.
In copy jobs, we need to map the source and destination of the BO into page
the structure. In clear jobs, we just need to add 1 mapping of BO into the
page structure. We use the 16 reserved pages in migration VM for mappings,
this gives us a maximum copy size of 16 MB and maximum clear size of 32 MB.”h]”hXy  Like binds, the first batch is used update the migration VM page structure.
In copy jobs, we need to map the source and destination of the BO into page
the structure. In clear jobs, we just need to add 1 mapping of BO into the
page structure. We use the 16 reserved pages in migration VM for mappings,
this gives us a maximum copy size of 16 MB and maximum clear size of 32 MB.”…””}”(hj¸  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´K<hj˜  ubhÞ)”}”(hŒ¯The second batch is used do either do the copy or clear. Again similar to
binds, two batches are required as the TLBs need to be invalidated from the
ring between the batches.”h]”hŒ¯The second batch is used do either do the copy or clear. Again similar to
binds, two batches are required as the TLBs need to be invalidated from the
ring between the batches.”…””}”(hjÇ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KBhj˜  ubhÞ)”}”(hŒWMore than one job will be generated if the BO is larger than maximum copy /
clear size.”h]”hŒWMore than one job will be generated if the BO is larger than maximum copy /
clear size.”…””}”(hjÖ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KFhj˜  ubeh}”(h]”Œcopy-clear-jobs”ah ]”h"]”Œcopy / clear jobs”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒFuture work”h]”hŒFuture work”…””}”(hjð  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjí  h³Nh´NubhÞ)”}”(hŒ7Update copy and clear code to use identity mapped VRAM.”h]”hŒ7Update copy and clear code to use identity mapped VRAM.”…””}”(hjþ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KLhjí  ubhÞ)”}”(hŒSCan we rework the use of the pages async binds to use all the entries in each
page?”h]”hŒSCan we rework the use of the pages async binds to use all the entries in each
page?”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KNhjí  ubhÞ)”}”(hŒ&Using large pages for sysmem mappings.”h]”hŒ&Using large pages for sysmem mappings.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KQhjí  ubhÞ)”}”(hŒBIs it possible to identity map the sysmem? We should explore this.”h]”hŒBIs it possible to identity map the sysmem? We should explore this.”…””}”(hj+  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œd/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:7: ./drivers/gpu/drm/xe/xe_migrate_doc.h”h´KShjí  ubeh}”(h]”Œfuture-work”ah ]”h"]”Œfuture work”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÞ)”}”(hXh  Migration jobs issued on behalf of GPU page faults and SVM prefetches sit
directly in the critical path of a stalled GPU workload. The dominant cost
of such a job is not the copy or clear itself but the submission latency:
the H2G round trip to GuC, the GuC scheduling decision, and the hardware
context switch required to place the migration LRC on an engine.”h]”hXh  Migration jobs issued on behalf of GPU page faults and SVM prefetches sit
directly in the critical path of a stalled GPU workload. The dominant cost
of such a job is not the copy or clear itself but the submission latency:
the H2G round trip to GuC, the GuC scheduling decision, and the hardware
context switch required to place the migration LRC on an engine.”…””}”(hjB  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K4hhÊh²hubhÞ)”}”(hXÜ  ULLS removes that cost by keeping the migration context resident and
*running* on the hardware engine across jobs. Instead of the ring going
empty and the context being switched out between jobs, the tail of every
ULLS job parks the engine on a semaphore wait for the *next* job's
semaphore, and then advances the ring tail itself. Submitting the next job
therefore costs the CPU a single write to signal that semaphore - no H2G,
no GuC round trip, no context switch, no MMIO.”h]”(hŒEULLS removes that cost by keeping the migration context resident and
”…””}”(hjQ  h²hh³Nh´NubhŒemphasis”“”)”}”(hŒ	*running*”h]”hŒrunning”…””}”(hj[  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hjQ  ubhŒ¾ on the hardware engine across jobs. Instead of the ring going
empty and the context being switched out between jobs, the tail of every
ULLS job parks the engine on a semaphore wait for the ”…””}”(hjQ  h²hh³Nh´NubjZ  )”}”(hŒ*next*”h]”hŒnext”…””}”(hjm  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hjQ  ubhŒÌ jobâ€™s
semaphore, and then advances the ring tail itself. Submitting the next job
therefore costs the CPU a single write to signal that semaphore - no H2G,
no GuC round trip, no context switch, no MMIO.”…””}”(hjQ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K:hhÊh²hubhÉ)”}”(hhh]”(hÎ)”}”(hŒRequirements”h]”hŒRequirements”…””}”(hj‰  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj†  h³Nh´NubhÞ)”}”(hŒâULLS is only used on dGFX platforms with USM support, where a hardware
engine is reserved exclusively for migration jobs. Because the engine
spins on a semaphore while ULLS is active, it cannot be shared with
user submissions.”h]”hŒâULLS is only used on dGFX platforms with USM support, where a hardware
engine is reserved exclusively for migration jobs. Because the engine
spins on a semaphore while ULLS is active, it cannot be shared with
user submissions.”…””}”(hj—  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KEhj†  ubhÞ)”}”(hŒ¼ULLS can be disabled by setting the ``migrate_ulls_period_ms`` configfs
attribute to 0. Otherwise, the same attribute controls how long ULLS
remains active before exiting, in milliseconds.”h]”(hŒ$ULLS can be disabled by setting the ”…””}”(hj¦  h²hh³Nh´NubhŒliteral”“”)”}”(hŒ``migrate_ulls_period_ms``”h]”hŒmigrate_ulls_period_ms”…””}”(hj°  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j®  hj¦  ubhŒ~ configfs
attribute to 0. Otherwise, the same attribute controls how long ULLS
remains active before exiting, in milliseconds.”…””}”(hj¦  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KJhj†  ubeh}”(h]”Œrequirements”ah ]”h"]”Œrequirements”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒFixed size jobs”h]”hŒFixed size jobs”…””}”(hjÔ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjÑ  h³Nh´NubhÞ)”}”(hXC  A job updates the ring tail to cover its successor, but it is emitted long
before that successor exists, so it can not know how much ring the
successor will occupy. Every ULLS job is therefore padded out to exactly
ULLS_JOB_SIZE_BYTES, which lets the next tail be computed arithmetically
from where the current job started.”h]”hXC  A job updates the ring tail to cover its successor, but it is emitted long
before that successor exists, so it can not know how much ring the
successor will occupy. Every ULLS job is therefore padded out to exactly
ULLS_JOB_SIZE_BYTES, which lets the next tail be computed arithmetically
from where the current job started.”…””}”(hjâ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KQhjÑ  ubhÞ)”}”(hX-  This is why the shorter jobs still have to reach the same size: the "last"
job skips the batch buffers and the postamble, and pads the difference with
MI_NOOP. The "first" job is not covered by any predecessor's tail update
and so is unconstrained, but is padded anyway to keep the arithmetic
uniform.”h]”hX7  This is why the shorter jobs still have to reach the same size: the â€œlastâ€
job skips the batch buffers and the postamble, and pads the difference with
MI_NOOP. The â€œfirstâ€ job is not covered by any predecessorâ€™s tail update
and so is unconstrained, but is padded anyway to keep the arithmetic
uniform.”…””}”(hjñ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KWhjÑ  ubhÞ)”}”(hŒ˜Leaving ULLS mode always goes through a "last" job, which emits no tail
update, so an ordinary variable length migration job never follows a
prediction.”h]”hŒœLeaving ULLS mode always goes through a â€œlastâ€ job, which emits no tail
update, so an ordinary variable length migration job never follows a
prediction.”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K]hjÑ  ubeh}”(h]”Œfixed-size-jobs”ah ]”h"]”Œfixed size jobs”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒ
Semaphores”h]”hŒ
Semaphores”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj  h³Nh´NubhÞ)”}”(hXú  The semaphores live in the driver-defined portion of the migration LRC's
PPHWSP (see LRC_ULLS_PPHWSP_OFFSET, mutually exclusive with the parallel
submission area). There are LRC_MIGRATION_ULLS_SEMAPHORE_COUNT of them and
a job's semaphore is selected by ``seqno % COUNT``, so the semaphore ring
wraps with the job seqnos. To guarantee a job can never overwrite the
semaphore of a job still in flight, the GuC backend caps the migration
queue's scheduler job count at LRC_MIGRATION_ULLS_SEMAPHORE_COUNT - 1.”h]”(hX  The semaphores live in the driver-defined portion of the migration LRCâ€™s
PPHWSP (see LRC_ULLS_PPHWSP_OFFSET, mutually exclusive with the parallel
submission area). There are LRC_MIGRATION_ULLS_SEMAPHORE_COUNT of them and
a jobâ€™s semaphore is selected by ”…””}”(hj(  h²hh³Nh´Nubj¯  )”}”(hŒ``seqno % COUNT``”h]”hŒseqno % COUNT”…””}”(hj0  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j®  hj(  ubhŒí, so the semaphore ring
wraps with the job seqnos. To guarantee a job can never overwrite the
semaphore of a job still in flight, the GuC backend caps the migration
queueâ€™s scheduler job count at LRC_MIGRATION_ULLS_SEMAPHORE_COUNT - 1.”…””}”(hj(  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´Kdhj  ubeh}”(h]”Œ
semaphores”ah ]”h"]”Œ
semaphores”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒRing layout of a ULLS job”h]”hŒRing layout of a ULLS job”…””}”(hjT  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjQ  h³Nh´NubhÞ)”}”(hŒ8Emitted by emit_migration_job_gen12() in xe_ring_ops.c::”h]”hŒ7Emitted by emit_migration_job_gen12() in xe_ring_ops.c:”…””}”(hjb  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KohjQ  ubhŒliteral_block”“”)”}”(hXË  preamble:       clear semaphore[seqno]  (reuse for a later wrap)
<copy timestamp, start seqno store>
<batch buffer start(s)>                 (skipped on first/last job)
<seqno write + user interrupt>
postamble:      wait on semaphore[seqno + 1]
                SDI saved ring tail = end of next job
                LRI RING_TAIL = end of next job
                                        (skipped on the last job)
pad:            MI_NOOP up to ULLS_JOB_SIZE_DW”h]”hXË  preamble:       clear semaphore[seqno]  (reuse for a later wrap)
<copy timestamp, start seqno store>
<batch buffer start(s)>                 (skipped on first/last job)
<seqno write + user interrupt>
postamble:      wait on semaphore[seqno + 1]
                SDI saved ring tail = end of next job
                LRI RING_TAIL = end of next job
                                        (skipped on the last job)
pad:            MI_NOOP up to ULLS_JOB_SIZE_DW”…””}”hjs  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jq  h³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KqhjQ  ubhÞ)”}”(hXì  The preamble clears the current job's semaphore so it can be reused once
the seqno space wraps. The postamble is what keeps the engine busy: it
blocks on the next job's semaphore, which is only signaled when that job is
actually submitted, and then advances the ring tail over it. It advances
the saved tail as well as the tail register, keeping the two in step
without any help from the CPU, so a context save and restore can not rewind
the tail behind work which has already been published.”h]”hXð  The preamble clears the current jobâ€™s semaphore so it can be reused once
the seqno space wraps. The postamble is what keeps the engine busy: it
blocks on the next jobâ€™s semaphore, which is only signaled when that job is
actually submitted, and then advances the ring tail over it. It advances
the saved tail as well as the tail register, keeping the two in step
without any help from the CPU, so a context save and restore can not rewind
the tail behind work which has already been published.”…””}”(hj‚  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K{hjQ  ubhÞ)”}”(hX¥  The tail register write must be non-posted, i.e. it must not carry
MI_LRI_FORCE_POSTED. Posted, the new tail is free to land after the command
streamer has already drained the rest of the job, at which point the command
streamer sees head == the old tail and parks as though the ring were empty.
A parked context can be switched off the hardware, and the fast path below
has no H2G with which to ask GuC to bring it back.”h]”hX¥  The tail register write must be non-posted, i.e. it must not carry
MI_LRI_FORCE_POSTED. Posted, the new tail is free to land after the command
streamer has already drained the rest of the job, at which point the command
streamer sees head == the old tail and parks as though the ring were empty.
A parked context can be switched off the hardware, and the fast path below
has no H2G with which to ask GuC to bring it back.”…””}”(hj‘  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KƒhjQ  ubhÞ)”}”(hX¬  The tail must be published after the semaphore wait, not before it. The
command streamer fetches ring contents up to the tail while it is parked,
so a tail published ahead of the wait lets it fetch the next job's slot
before the CPU has written the job there. Once released it then executes
the MI_NOOPs it fetched instead of the job, that job's fence never signals,
and the engine drains and idles with nothing left to wake it.”h]”hX°  The tail must be published after the semaphore wait, not before it. The
command streamer fetches ring contents up to the tail while it is parked,
so a tail published ahead of the wait lets it fetch the next jobâ€™s slot
before the CPU has written the job there. Once released it then executes
the MI_NOOPs it fetched instead of the job, that jobâ€™s fence never signals,
and the engine drains and idles with nothing left to wake it.”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KŠhjQ  ubeh}”(h]”Œring-layout-of-a-ulls-job”ah ]”h"]”Œring layout of a ulls job”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒSubmission fast path”h]”hŒSubmission fast path”…””}”(hjº  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj·  h³Nh´NubhÞ)”}”(hŒ[In submit_exec_queue() (xe_guc_submit.c), a ULLS job that is not the first
one reduces to::”h]”hŒZIn submit_exec_queue() (xe_guc_submit.c), a ULLS job that is not the first
one reduces to:”…””}”(hjÈ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K”hj·  ubjr  )”}”(hŒDxe_lrc_set_ulls_semaphore(lrc, seqno);          release previous job”h]”hŒDxe_lrc_set_ulls_semaphore(lrc, seqno);          release previous job”…””}”hj×  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jq  h³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K—hj·  ubhÞ)”}”(hXb  The XE_GUC_ACTION_SCHED_CONTEXT H2G is suppressed, and so is the write of
the saved ring tail: the previous job's postamble is parked on this job's
semaphore and publishes this job's tail, both in the tail register and in
the context image, as soon as it is released. The semaphore signal is all
that is left, and the engine walks straight into this job.”h]”hXh  The XE_GUC_ACTION_SCHED_CONTEXT H2G is suppressed, and so is the write of
the saved ring tail: the previous jobâ€™s postamble is parked on this jobâ€™s
semaphore and publishes this jobâ€™s tail, both in the tail register and in
the context image, as soon as it is released. The semaphore signal is all
that is left, and the engine walks straight into this job.”…””}”(hjæ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K™hj·  ubhÞ)”}”(hX  This does assume the context stays resident for as long as ULLS mode is
active. Nothing else is scheduled on the reserved engine, so the only ways
off the hardware are the "last" job below, or a reset - and a migration job
failing already wedges the device.”h]”hX  This does assume the context stays resident for as long as ULLS mode is
active. Nothing else is scheduled on the reserved engine, so the only ways
off the hardware are the â€œlastâ€ job below, or a reset - and a migration job
failing already wedges the device.”…””}”(hjõ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KŸhj·  ubeh}”(h]”Œsubmission-fast-path”ah ]”h"]”Œsubmission fast path”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒEnter / exit”h]”hŒEnter / exit”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj  h³Nh´NubhÞ)”}”(hXô  xe_migrate_ulls_enter() is called from the page fault handler and from the
SVM prefetch path, i.e. exactly where low latency migration matters. It
takes a PM runtime reference (the device must not suspend while the engine
spins), then submits a "first" ULLS job. That first job carries no batch
buffer; it exists only to get the context onto the hardware through the
normal GuC path and to leave the engine waiting on the next semaphore,
pipelining the GuC/HW context switch out of the critical path.”h]”hXø  xe_migrate_ulls_enter() is called from the page fault handler and from the
SVM prefetch path, i.e. exactly where low latency migration matters. It
takes a PM runtime reference (the device must not suspend while the engine
spins), then submits a â€œfirstâ€ ULLS job. That first job carries no batch
buffer; it exists only to get the context onto the hardware through the
normal GuC path and to leave the engine waiting on the next semaphore,
pipelining the GuC/HW context switch out of the critical path.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K§hj  ubhÞ)”}”(hŒÛNo forcewake reference is required. Nothing in the fast path touches MMIO,
and the engine keeps itself awake for as long as it is executing the ring.
Not needing host MMIO access is also what lets ULLS run on SRIOV VFs.”h]”hŒÛNo forcewake reference is required. Nothing in the fast path touches MMIO,
and the engine keeps itself awake for as long as it is executing the ring.
Not needing host MMIO access is also what lets ULLS run on SRIOV VFs.”…””}”(hj,  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K¯hj  ubhÞ)”}”(hX
  Keeping an engine spinning costs power, so ULLS is not left enabled
indefinitely. Every enter and every ULLS job submission re-arms
**xe_migrate.ulls.exit_work** with a ULLS_EXIT_JIFFIES delay. When it fires
with the queue idle, it submits a "last" ULLS job - again with no batch
buffer and, crucially, with no postamble semaphore wait or tail update -
which lets the ring drain so the context can be switched off the hardware.
The PM reference is then dropped. If the queue was not idle, the worker
simply re-arms itself.”h]”(hŒ„Keeping an engine spinning costs power, so ULLS is not left enabled
indefinitely. Every enter and every ULLS job submission re-arms
”…””}”(hj;  h²hh³Nh´NubhŒstrong”“”)”}”(hŒ**xe_migrate.ulls.exit_work**”h]”hŒxe_migrate.ulls.exit_work”…””}”(hjE  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hj;  ubhXm   with a ULLS_EXIT_JIFFIES delay. When it fires
with the queue idle, it submits a â€œlastâ€ ULLS job - again with no batch
buffer and, crucially, with no postamble semaphore wait or tail update -
which lets the ring drain so the context can be switched off the hardware.
The PM reference is then dropped. If the queue was not idle, the worker
simply re-arms itself.”…””}”(hj;  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K³hj  ubeh}”(h]”Œ
enter-exit”ah ]”h"]”Œenter / exit”ah$]”h&]”uh1hÈhhÊh²hh³Nh´NubhÉ)”}”(hhh]”(hÎ)”}”(hŒ	Job state”h]”hŒ	Job state”…””}”(hji  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjf  h³Nh´NubhÞ)”}”(hŒ~The state above is communicated to the ring ops and GuC backend via
**xe_sched_job.ulls**, set under **xe_migrate.job_mutex**:”h]”(hŒDThe state above is communicated to the ring ops and GuC backend via
”…””}”(hjw  h²hh³Nh´NubjD  )”}”(hŒ**xe_sched_job.ulls**”h]”hŒxe_sched_job.ulls”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hjw  ubhŒ, set under ”…””}”(hjw  h²hh³Nh´NubjD  )”}”(hŒ**xe_migrate.job_mutex**”h]”hŒxe_migrate.job_mutex”…””}”(hj‘  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jC  hjw  ubhŒ:”…””}”(hjw  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´K¿hjf  ubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ1``ULLS_NONE``: job submitted outside of ULLS mode”h]”hÞ)”}”(hj³  h]”(j¯  )”}”(hŒ``ULLS_NONE``”h]”hŒ	ULLS_NONE”…””}”(hj¸  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j®  hjµ  ubhŒ$: job submitted outside of ULLS mode”…””}”(hjµ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KÂhj±  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¯  hj¬  ubj°  )”}”(hŒ)``ULLS_ENTER``: job that enters ULLS mode”h]”hÞ)”}”(hjÙ  h]”(j¯  )”}”(hŒ``ULLS_ENTER``”h]”hŒ
ULLS_ENTER”…””}”(hjÞ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j®  hjÛ  ubhŒ: job that enters ULLS mode”…””}”(hjÛ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KÃhj×  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¯  hj¬  ubj°  )”}”(hŒ1``ULLS_ACTIVE``: job submitted while in ULLS mode”h]”hÞ)”}”(hjÿ  h]”(j¯  )”}”(hŒ``ULLS_ACTIVE``”h]”hŒULLS_ACTIVE”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j®  hj  ubhŒ": job submitted while in ULLS mode”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KÄhjý  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¯  hj¬  ubj°  )”}”(hŒ)``ULLS_EXIT``: job that exits ULLS mode

”h]”hÞ)”}”(hŒ'``ULLS_EXIT``: job that exits ULLS mode”h]”(j¯  )”}”(hŒ``ULLS_EXIT``”h]”hŒ	ULLS_EXIT”…””}”(hj+  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j®  hj'  ubhŒ: job that exits ULLS mode”…””}”(hj'  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³Œa/var/lib/git/docbuild/linux/Documentation/gpu/xe/xe_migrate:10: ./drivers/gpu/drm/xe/xe_migrate.c”h´KÅhj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¯  hj¬  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jª  h³jÐ  h´KÂhjf  ubeh}”(h]”Œ	job-state”ah ]”h"]”Œ	job state”ah$]”h&]”uh1hÈhhÊh²hh³Nh´Nubeh}”(h]”Œmigrate-layer”ah ]”h"]”Œmigrate layer”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”}”(j_  j\  j1  j.  j•  j’  jê  jç  j?  j<  jÎ  jË  j  j  jN  jK  j´  j±  j	  j  jc  j`  jW  jT  uŒ	nametypes”}”(j_  ‰j1  ‰j•  ‰jê  ‰j?  ‰jÎ  ‰j  ‰jN  ‰j´  ‰j	  ‰jc  ‰jW  ‰uh}”(j\  hÊj.  hîj’  j4  jç  j˜  j<  jí  jË  j†  j  jÑ  jK  j  j±  jQ  j  j·  j`  j  jT  jf  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.