docs(hipFile): Create new guides for setting up storage targets#8897
docs(hipFile): Create new guides for setting up storage targets#8897riley-dixon wants to merge 3 commits into
Conversation
riley-dixon
added
documentation
✅ All Policy Checks Passed
📖 Need help? See the Policy FAQ for details on every check and how to fix failures. |
e935d55 to
eec5a5c
Compare
|
Note: this PR is based on top of #7790 |
There was a problem hiding this comment.
Pull request overview
Adds and refines hipFile documentation to help users set up supported storage targets (local NVMe, NVMeoF, and NFS-over-RDMA) and centralizes install instructions in the published docs site.
Changes:
- Replaces the in-repo
INSTALL.mdcontent with a pointer to the official hipFile install docs. - Adds new install guides for local NVMe setup, NVMeoF target/initiator setup, and NFSoRDMA setup.
- Updates reference/troubleshooting docs around ROCm requirements and NFSoRDMA behavior (
HIPFILE_UNSUPPORTED_FILE_SYSTEMS).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| projects/hipfile/INSTALL.md | Replaces lengthy install/build instructions with a link to the official docs site. |
| projects/hipfile/docs/troubleshooting/troubleshooting.rst | Updates the documented ROCm minimum version for fastpath prerequisites. |
| projects/hipfile/docs/reference/hipFile-io-backends.rst | Adds an explicit note about HIPFILE_UNSUPPORTED_FILE_SYSTEMS when using NFSoRDMA. |
| projects/hipfile/docs/reference/hipFile-environment-variables.rst | Documents the NFSoRDMA requirement for HIPFILE_UNSUPPORTED_FILE_SYSTEMS. |
| projects/hipfile/docs/install/setup-nvmeof.rst | New NVMeoF target/initiator setup and verification walkthrough. |
| projects/hipfile/docs/install/setup-nfsordma.rst | New NFS-over-RDMA export/mount and verification walkthrough. |
| projects/hipfile/docs/install/setup-local-nvme.rst | New local NVMe partition/format/mount and verification walkthrough. |
| projects/hipfile/docs/install/install.rst | Updates ROCm doc link reference and adds a note about experimental NVMeoF/NFSoRDMA support. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
eec5a5c to
25f4641
Compare
gaoikawa
changed the title
| utilities that can be used instead. Before you begin, make sure hipFile is | ||
| installed. See :doc:`./install` for package options or :doc:`./build-from-source` | ||
| to build from source. | ||
|
|
There was a problem hiding this comment.
I feel like we should add the couple of limitations we have, like the fact that we don't support lvm volumes (yet!) and mdraid. Only because the lvm volume issue seems to come up a lot.
| the transfer is fully zero-copy end-to-end depends on the NFS server's own | ||
| RDMA support for its storage backend; consult your NFS server documentation. | ||
|
|
||
| Configure the InfiniBand interface |
There was a problem hiding this comment.
I suggest replacing 'Infiniband' with 'RDMA' so it's more generic.
| .. code:: shell | ||
|
|
||
| sudo mkdir /mnt/nfs | ||
| sudo mount -o rdma,port=20049 <server_ip>:<export_path> /mnt/nfs |
There was a problem hiding this comment.
Curious if here we want to talk about any tuning options, like 'nconnect'? @kurtmcmillan maybe has some direct experience with this.
| - Version 31.40 or newer of the ``amdgpu-dkms`` driver | ||
| - ``nvme-cli`` installed on the initiator (client) system | ||
| - Network or fabric connectivity to an NVMeoF target. This guide's examples | ||
| use RDMA; TCP is also supported. |
There was a problem hiding this comment.
'TCP is also supported' -> is that actually true? I thought we needed RDMA for actual hipFile fastpath to work.
| $ sudo journalctl -k | grep nvmet | ||
| nvmet_rdma: enabling port 1 (<target_ip>:<target_port>) | ||
|
|
||
| .. warning:: |
There was a problem hiding this comment.
Can we make this stick out more, somehow - like a surrounded in a yellow box or something like that?
Perhaps @spolifroni-amd has a suggestion.
Motivation
Adds guides for setting up a local NVMe, remote NVMeoF, and remote NFSoRDMA storage target to run hipFile against.
Technical Details
Adds three new install guides under docs/install/: setup-local-nvme.rst, setup-nvmeof.rst, and setup-nfsordma.rst, covering local NVMe partitioning, NVMeoF target/initiator setup, and NFS-over-RDMA export/mount respectively. Each follows the existing install-guide structure (prerequisites, numbered setup steps, verification) and is cross-linked from install.rst.
Issue Tracking
JIRA ID: AIHIPFILE-236 AIROCDOC-4110
Test Plan
N/A
Test Result
N/A
Submission Checklist