All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v7 00/16] RFC Support hot device unplug in amdgpu
@ 2021-05-12 14:26 ` Andrey Grodzovsky
  0 siblings, 0 replies; 193+ messages in thread
From: Andrey Grodzovsky @ 2021-05-12 14:26 UTC (permalink / raw)
  To: dri-devel, amd-gfx, linux-pci, ckoenig.leichtzumerken,
	daniel.vetter, Harry.Wentland
  Cc: ppaalanen, Alexander.Deucher, gregkh, helgaas, Felix.Kuehling,
	Andrey Grodzovsky

Until now extracting a card either by physical extraction (e.g. eGPU with 
thunderbolt connection or by emulation through  sysfs -> /sys/bus/pci/devices/device_id/remove) 
would cause random crashes in user apps. The random crashes in apps were 
mostly due to the app having mapped a device backed BO into its address 
space and was still trying to access the BO while the backing device was gone.
To answer this first problem Christian suggested fixing the handling of mapped 
memory in the clients when the device goes away by forcibly unmapping all buffers the 
user processes have by clearing their respective VMAs mapping the device BOs.
Then when the VMAs try to fill in the page tables again we check in the fault 
handler if the device is removed and if so, return an error. This will generate a 
SIGBUS to the application which can then cleanly terminate. This indeed was done 
but this in turn created a problem of kernel OOPs where the OOPSes were due to the 
fact that while the app was terminating because of the SIGBUS it would trigger use 
after free in the driver by calling to access device structures that were already
released from the pci remove sequence. This was handled by introducing a 'flush' 
sequence during device removal where we wait for drm file reference to drop to 0 
meaning all user clients directly using this device terminated.

v2:
Based on discussions in the mailing list with Daniel and Pekka [1] and based on the document 
produced by Pekka from those discussions [2] the whole approach with returning SIGBUS and 
waiting for all user clients having CPU mapping of device BOs to die was dropped. 
Instead as per the document suggestion the device structures are kept alive until 
the last reference to the device is dropped by user client and in the meanwhile all existing and new CPU mappings of the BOs 
belonging to the device directly or by dma-buf import are rerouted to per user 
process dummy rw page.Also, I skipped the 'Requirements for KMS UAPI' section of [2] 
since i am trying to get the minimal set of requirements that still give useful solution 
to work and this is the'Requirements for Render and Cross-Device UAPI' section and so my 
test case is removing a secondary device, which is render only and is not involved 
in KMS.

v3:
More updates following comments from v2 such as removing loop to find DRM file when rerouting 
page faults to dummy page,getting rid of unnecessary sysfs handling refactoring and moving 
prevention of GPU recovery post device unplug from amdgpu to scheduler layer. 
On top of that added unplug support for the IOMMU enabled system.

v4:
Drop last sysfs hack and use sysfs default attribute.
Guard against write accesses after device removal to avoid modifying released memory.
Update dummy pages handling to on demand allocation and release through drm managed framework.
Add return value to scheduler job TO handler (by Luben Tuikov) and use this in amdgpu for prevention 
of GPU recovery post device unplug
Also rebase on top of drm-misc-mext instead of amd-staging-drm-next

v5:
The most significant in this series is the improved protection from kernel driver accessing MMIO ranges that were allocated
for the device once the device is gone. To do this, first a patch 'drm/amdgpu: Unmap all MMIO mappings' is introduced.
This patch unamps all MMIO mapped into the kernel address space in the form of BARs and kernel BOs with CPU visible VRAM mappings.
This way it helped to discover multiple such access points because a page fault would be immediately generated on access. Most of them
were solved by moving HW fini code into pci_remove stage (patch drm/amdgpu: Add early fini callback) and for some who 
were harder to unwind drm_dev_enter/exit scoping was used. In addition all the IOCTLs and all background work and timers 
are now protected with drm_dev_enter/exit at their root in an attempt that after drm_dev_unplug is finished none of them 
run anymore and the pci_remove thread is the only thread executing which might touch the HW. To prevent deadlocks in such 
case against threads stuck on various HW or SW fences patches 'drm/amdgpu: Finalise device fences on device remove'  
and drm/amdgpu: Add rw_sem to pushing job into sched queue' take care of force signaling all such existing fences 
and rejecting any newly added ones.

v6:
Drop using drm_dev_enter/exit in conjunction with signalling HW fences before setting drm_dev_unplug.
We need to devise a more robust cros DRM approach to the problem of dma fence waits falling
inside drm_dev_enter/exit scopes -> move to TODO.

v7:
Small cosmetic changes after V6 comments.
Added back the patch which invalidates MMIO mappings in the driver (register, doorbell and VRAM). While
waterproof protection from MMIO accessing from V5 was dropped until a more generic approach was developed I
do believe that it's better to cause kernel panic once such access happens and then fix it then let those go
unnoticed.

With these patches I am able to gracefully remove the secondary card using sysfs remove hook while glxgears is running off of secondary 
card (DRI_PRIME=1) without kernel oopses or hangs and keep working with the primary card or soft reset the device without hangs or oopses.
Also as per Daniel's comment I added 3 tests to IGT [4] to core_hotunplug test suite - remove device while commands are submitted, 
exported BO and exported fence (not pushed yet).
Also now it's possible to plug back the device after unplug 
Also some users now can successfully use those patches with eGPU boxes[3].

TODOs for followup work:
Convert AMDGPU code to use devm (for hw stuff) and drmm (for sw stuff and allocations) (Daniel)
Add support for 'Requirements for KMS UAPI' section of [2] - unplugging primary, display connected card.
Annotate drm_dev_enter/exit against dma_fence_waits as first in deciding where to use drm_dev_enter/exit
in code for device unplug.

[1] - Discussions during v6 of the patchset https://lore.kernel.org/amd-gfx/20210510163625.407105-1-andrey.grodzovsky@amd.com/#r
[2] - drm/doc: device hot-unplug for userspace https://www.spinics.net/lists/dri-devel/msg259755.html
[3] - Related gitlab ticket https://gitlab.freedesktop.org/drm/amd/-/issues/1081
[4] - Related IGT tests https://gitlab.freedesktop.org/agrodzov/igt-gpu-tools/-/commits/master

Andrey Grodzovsky (16):
  drm/ttm: Remap all page faults to per process dummy page.
  drm/amdgpu: Split amdgpu_device_fini into early and late
  drm/amdkfd: Split kfd suspend from device exit
  drm/amdgpu: Add early fini callback
  drm/amdgpu: Handle IOMMU enabled case.
  drm/amdgpu: Remap all page faults to per process dummy page.
  PCI: Add support for dev_groups to struct pci_driver
  drm/amdgpu: Convert driver sysfs attributes to static attributes
  drm/amdgpu: Guard against write accesses after device removal
  drm/sched: Make timeout timer rearm conditional.
  drm/amdgpu: Prevent any job recoveries after device is unplugged.
  drm/amdgpu: Fix hang on device removal.
  drm/scheduler: Fix hang when sched_entity released
  drm/amd/display: Remove superfluous drm_mode_config_cleanup
  drm/amdgpu: Verify DMA opearations from device are done
  drm/amdgpu: Unmap all MMIO mappings

 drivers/gpu/drm/amd/amdgpu/amdgpu.h           |   6 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd.c    |   2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd.h    |   2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c  |  17 +--
 drivers/gpu/drm/amd/amdgpu/amdgpu_device.c    | 121 +++++++++++++-----
 drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c       |  26 +++-
 drivers/gpu/drm/amd/amdgpu/amdgpu_fence.c     |  31 ++++-
 drivers/gpu/drm/amd/amdgpu/amdgpu_gart.c      |  14 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_gart.h      |   2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_gmc.c       |   9 ++
 drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c   |  25 ++--
 drivers/gpu/drm/amd/amdgpu/amdgpu_ih.c        |   6 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c       |  31 +++--
 drivers/gpu/drm/amd/amdgpu/amdgpu_irq.h       |   3 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_job.c       |  19 ++-
 drivers/gpu/drm/amd/amdgpu/amdgpu_kms.c       |  12 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_object.c    |   1 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_psp.c       |  63 +++++----
 drivers/gpu/drm/amd/amdgpu/amdgpu_psp.h       |   2 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c       |   1 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h      |   3 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_ttm.c       |  25 ++--
 drivers/gpu/drm/amd/amdgpu/amdgpu_uvd.c       |  31 +++--
 drivers/gpu/drm/amd/amdgpu/amdgpu_vce.c       |  11 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vcn.c       |  22 +++-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c        |   7 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c  |  14 +-
 drivers/gpu/drm/amd/amdgpu/cik_ih.c           |   3 +-
 drivers/gpu/drm/amd/amdgpu/cz_ih.c            |   3 +-
 drivers/gpu/drm/amd/amdgpu/gmc_v10_0.c        |   1 -
 drivers/gpu/drm/amd/amdgpu/gmc_v6_0.c         |   1 -
 drivers/gpu/drm/amd/amdgpu/gmc_v7_0.c         |   1 -
 drivers/gpu/drm/amd/amdgpu/gmc_v8_0.c         |   1 -
 drivers/gpu/drm/amd/amdgpu/gmc_v9_0.c         |   1 -
 drivers/gpu/drm/amd/amdgpu/iceland_ih.c       |   3 +-
 drivers/gpu/drm/amd/amdgpu/navi10_ih.c        |   6 +-
 drivers/gpu/drm/amd/amdgpu/psp_v11_0.c        |  44 +++----
 drivers/gpu/drm/amd/amdgpu/psp_v12_0.c        |   8 +-
 drivers/gpu/drm/amd/amdgpu/psp_v3_1.c         |   8 +-
 drivers/gpu/drm/amd/amdgpu/si_ih.c            |   3 +-
 drivers/gpu/drm/amd/amdgpu/tonga_ih.c         |   3 +-
 drivers/gpu/drm/amd/amdgpu/vce_v4_0.c         |  26 ++--
 drivers/gpu/drm/amd/amdgpu/vcn_v3_0.c         |  22 ++--
 drivers/gpu/drm/amd/amdgpu/vega10_ih.c        |   6 +-
 drivers/gpu/drm/amd/amdgpu/vega20_ih.c        |   6 +-
 drivers/gpu/drm/amd/amdkfd/kfd_device.c       |   3 +-
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c |  13 +-
 drivers/gpu/drm/amd/include/amd_shared.h      |   2 +
 drivers/gpu/drm/scheduler/sched_entity.c      |   3 +-
 drivers/gpu/drm/scheduler/sched_main.c        |  35 ++++-
 drivers/gpu/drm/ttm/ttm_bo_vm.c               |  54 +++++++-
 drivers/pci/pci-driver.c                      |   1 +
 include/drm/ttm/ttm_bo_api.h                  |   2 +
 include/linux/pci.h                           |   3 +
 54 files changed, 514 insertions(+), 254 deletions(-)

-- 
2.25.1


^ permalink raw reply	[flat|nested] 193+ messages in thread

end of thread, other threads:[~2021-05-20  3:58 UTC | newest]

Thread overview: 193+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-12 14:26 [PATCH v7 00/16] RFC Support hot device unplug in amdgpu Andrey Grodzovsky
2021-05-12 14:26 ` Andrey Grodzovsky
2021-05-12 14:26 ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 01/16] drm/ttm: Remap all page faults to per process dummy page Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 02/16] drm/amdgpu: Split amdgpu_device_fini into early and late Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 03/16] drm/amdkfd: Split kfd suspend from device exit Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 20:33   ` Felix Kuehling
2021-05-12 20:33     ` Felix Kuehling
2021-05-12 20:33     ` Felix Kuehling
2021-05-12 20:38     ` Andrey Grodzovsky
2021-05-12 20:38       ` Andrey Grodzovsky
2021-05-12 20:38       ` Andrey Grodzovsky
2021-05-20  3:20     ` [PATCH] drm/amdgpu: Add early fini callback Andrey Grodzovsky
2021-05-20  3:20       ` Andrey Grodzovsky
2021-05-20  3:20       ` Andrey Grodzovsky
2021-05-20  3:29       ` Felix Kuehling
2021-05-20  3:29         ` Felix Kuehling
2021-05-20  3:29         ` Felix Kuehling
2021-05-20  3:58         ` Andrey Grodzovsky
2021-05-20  3:58           ` Andrey Grodzovsky
2021-05-20  3:58           ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 04/16] " Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 05/16] drm/amdgpu: Handle IOMMU enabled case Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-14 14:41   ` Andrey Grodzovsky
2021-05-14 14:41     ` Andrey Grodzovsky
2021-05-14 14:41     ` Andrey Grodzovsky
2021-05-14 16:25     ` Felix Kuehling
2021-05-14 16:25       ` Felix Kuehling
2021-05-14 16:26       ` Andrey Grodzovsky
2021-05-14 16:26         ` Andrey Grodzovsky
2021-05-14 16:26         ` Andrey Grodzovsky
2021-05-17 14:38       ` [PATCH] " Andrey Grodzovsky
2021-05-17 14:38         ` Andrey Grodzovsky
2021-05-17 14:38         ` Andrey Grodzovsky
2021-05-17 14:48         ` Felix Kuehling
2021-05-17 14:48           ` Felix Kuehling
2021-05-17 14:48           ` Felix Kuehling
2021-05-12 14:26 ` [PATCH v7 06/16] drm/amdgpu: Remap all page faults to per process dummy page Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 07/16] PCI: Add support for dev_groups to struct pci_driver Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 08/16] drm/amdgpu: Convert driver sysfs attributes to static attributes Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 09/16] drm/amdgpu: Guard against write accesses after device removal Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 20:17   ` Alex Deucher
2021-05-12 20:17     ` Alex Deucher
2021-05-12 20:17     ` Alex Deucher
2021-05-12 20:30     ` Andrey Grodzovsky
2021-05-12 20:30       ` Andrey Grodzovsky
2021-05-12 20:30       ` Andrey Grodzovsky
2021-05-12 20:50       ` Alex Deucher
2021-05-12 20:50         ` Alex Deucher
2021-05-12 20:50         ` Alex Deucher
2021-05-13 14:47         ` Andrey Grodzovsky
2021-05-13 14:47           ` Andrey Grodzovsky
2021-05-13 14:47           ` Andrey Grodzovsky
2021-05-13 14:54           ` Alex Deucher
2021-05-13 14:54             ` Alex Deucher
2021-05-13 14:54             ` Alex Deucher
2021-05-12 14:26 ` [PATCH v7 10/16] drm/sched: Make timeout timer rearm conditional Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 11/16] drm/amdgpu: Prevent any job recoveries after device is unplugged Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 12/16] drm/amdgpu: Fix hang on device removal Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-14 14:42   ` Andrey Grodzovsky
2021-05-14 14:42     ` Andrey Grodzovsky
2021-05-14 14:42     ` Andrey Grodzovsky
2021-05-17 14:40     ` Andrey Grodzovsky
2021-05-17 14:40       ` Andrey Grodzovsky
2021-05-17 14:40       ` Andrey Grodzovsky
2021-05-17 17:39       ` Alex Deucher
2021-05-17 17:39         ` Alex Deucher
2021-05-17 17:39         ` Alex Deucher
2021-05-17 19:39       ` Christian König
2021-05-17 19:39         ` Christian König
2021-05-17 19:39         ` Christian König
2021-05-17 19:46         ` Andrey Grodzovsky
2021-05-17 19:46           ` Andrey Grodzovsky
2021-05-17 19:46           ` Andrey Grodzovsky
2021-05-17 19:54           ` Christian König
2021-05-17 19:54             ` Christian König
2021-05-17 19:54             ` Christian König
2021-05-12 14:26 ` [PATCH v7 13/16] drm/scheduler: Fix hang when sched_entity released Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-18 14:07   ` Christian König
2021-05-18 14:07     ` Christian König
2021-05-18 14:07     ` Christian König
2021-05-18 15:03     ` Andrey Grodzovsky
2021-05-18 15:03       ` Andrey Grodzovsky
2021-05-18 15:03       ` Andrey Grodzovsky
2021-05-18 15:15       ` Christian König
2021-05-18 15:15         ` Christian König
2021-05-18 15:15         ` Christian König
2021-05-18 16:17         ` Andrey Grodzovsky
2021-05-18 16:17           ` Andrey Grodzovsky
2021-05-18 16:17           ` Andrey Grodzovsky
2021-05-18 16:33           ` Christian König
2021-05-18 16:33             ` Christian König
2021-05-18 16:33             ` Christian König
2021-05-18 17:43             ` Andrey Grodzovsky
2021-05-18 17:43               ` Andrey Grodzovsky
2021-05-18 17:43               ` Andrey Grodzovsky
2021-05-18 18:02               ` Christian König
2021-05-18 18:02                 ` Christian König
2021-05-18 18:02                 ` Christian König
2021-05-18 18:09                 ` Andrey Grodzovsky
2021-05-18 18:09                   ` Andrey Grodzovsky
2021-05-18 18:09                   ` Andrey Grodzovsky
2021-05-18 18:13                   ` Christian König
2021-05-18 18:13                     ` Christian König
2021-05-18 18:13                     ` Christian König
2021-05-18 18:48                     ` Andrey Grodzovsky
2021-05-18 18:48                       ` Andrey Grodzovsky
2021-05-18 18:48                       ` Andrey Grodzovsky
2021-05-18 20:56                       ` Andrey Grodzovsky
2021-05-18 20:56                         ` Andrey Grodzovsky
2021-05-18 20:56                         ` Andrey Grodzovsky
2021-05-19 10:57                       ` Christian König
2021-05-19 10:57                         ` Christian König
2021-05-19 10:57                         ` Christian König
2021-05-19 11:03                         ` Andrey Grodzovsky
2021-05-19 11:03                           ` Andrey Grodzovsky
2021-05-19 11:03                           ` Andrey Grodzovsky
2021-05-19 11:46                           ` Christian König
2021-05-19 11:46                             ` Christian König
2021-05-19 11:46                             ` Christian König
2021-05-19 11:51                             ` Andrey Grodzovsky
2021-05-19 11:51                               ` Andrey Grodzovsky
2021-05-19 11:51                               ` Andrey Grodzovsky
2021-05-19 11:56                               ` Christian König
2021-05-19 11:56                                 ` Christian König
2021-05-19 11:56                                 ` Christian König
2021-05-19 14:14                                 ` [PATCH] drm/sched: Avoid data corruptions Andrey Grodzovsky
2021-05-19 14:14                                   ` Andrey Grodzovsky
2021-05-19 14:14                                   ` Andrey Grodzovsky
2021-05-19 14:15                                   ` Christian König
2021-05-19 14:15                                     ` Christian König
2021-05-19 14:15                                     ` Christian König
2021-05-12 14:26 ` [PATCH v7 14/16] drm/amd/display: Remove superfluous drm_mode_config_cleanup Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 15/16] drm/amdgpu: Verify DMA opearations from device are done Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26 ` [PATCH v7 16/16] drm/amdgpu: Unmap all MMIO mappings Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-12 14:26   ` Andrey Grodzovsky
2021-05-14 14:42   ` Andrey Grodzovsky
2021-05-14 14:42     ` Andrey Grodzovsky
2021-05-14 14:42     ` Andrey Grodzovsky
2021-05-17 14:41     ` Andrey Grodzovsky
2021-05-17 14:41       ` Andrey Grodzovsky
2021-05-17 14:41       ` Andrey Grodzovsky
2021-05-17 17:43   ` Alex Deucher
2021-05-17 17:43     ` Alex Deucher
2021-05-17 17:43     ` Alex Deucher
2021-05-17 18:46     ` Andrey Grodzovsky
2021-05-17 18:46       ` Andrey Grodzovsky
2021-05-17 18:46       ` Andrey Grodzovsky
2021-05-17 18:56       ` Alex Deucher
2021-05-17 18:56         ` Alex Deucher
2021-05-17 18:56         ` Alex Deucher
2021-05-17 19:22         ` Andrey Grodzovsky
2021-05-17 19:22           ` Andrey Grodzovsky
2021-05-17 19:22           ` Andrey Grodzovsky
2021-05-17 19:31     ` [PATCH] " Andrey Grodzovsky
2021-05-17 19:31       ` Andrey Grodzovsky
2021-05-17 19:31       ` Andrey Grodzovsky
2021-05-18 14:01       ` Andrey Grodzovsky
2021-05-18 14:01         ` Andrey Grodzovsky
2021-05-18 14:01         ` Andrey Grodzovsky
2021-05-18 14:02         ` Deucher, Alexander
2021-05-18 14:02           ` Deucher, Alexander

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.