[PATCH] scsi: docs: scsi_fc_transport: Add documentation for FC Remote Ports

[PATCH] scsi: docs: scsi_fc_transport: Add documentation for FC Remote Ports

[Alok Tiwari]

This patch updates the scsi_fc_transport.rst documentation by
replacing the outdated << To Be Supplied >> placeholder under
the "FC Remote Ports (rports)" section with a detailed explanation
of remote port functionality in the Fibre Channel (FC) transport class.

The new documentation covers:
What rports are and their role in FC-based SCSI communication
Their representation in sysfs (/sys/class/fc_remote_ports/)
Common sysfs attributes such as (port_id, port_name, node_name,
and port_state).
Their typical lifecycle (creation and removal)
Guidance for driver developers on using fc_remote_port_add() and
fc_remote_port_delete()

This change improves the completeness and usefulness of the
FC transport documentation for developers and users interacting
with Fibre Channel drivers in the Linux SCSI subsystem

Signed-off-by: Alok Tiwari <alok.a.tiwari@oracle.com>
---
 Documentation/scsi/scsi_fc_transport.rst | 35 +++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/Documentation/scsi/scsi_fc_transport.rst b/Documentation/scsi/scsi_fc_transport.rst
index e3ddcfb7f8fd..5ef75575924e 100644
--- a/Documentation/scsi/scsi_fc_transport.rst
+++ b/Documentation/scsi/scsi_fc_transport.rst
@@ -30,7 +30,40 @@ This file is found at Documentation/scsi/scsi_fc_transport.rst
 
 FC Remote Ports (rports)
 ========================
-<< To Be Supplied >>
+
+  In the Fibre Channel (FC) subsystem, a remote port (rport) refers to a
+  remote Fibre Channel node that the local port can communicate with.
+  These are typically storage targets (e.g., arrays, tapes) that respond
+  to SCSI commands over FC transport.
+
+  In Linux, rports are managed by the FC transport class and are
+  represented in sysfs under:
+
+    /sys/class/fc_remote_ports/
+
+  Each rport directory contains attributes describing the remote port,
+  such as port ID, node name, port state, and link speed.
+
+  rports are typically created by the FC transport when a new device is
+  discovered during a fabric login or scan, and they persist until the
+  device is removed or the link is lost.
+
+  Common attributes:
+  - node_name: World Wide Node Name (WWNN).
+  - port_name: World Wide Port Name (WWPN).
+  - port_id: FC address of the remote port.
+  - roles: Indicates if the port is an initiator, target, or both.
+  - port_state: Shows the current operational state.
+
+  After discovering a remote port, the driver typically populates a
+  fc_rport_identifiers structure and invokes fc_remote_port_add() to
+  create and register the remote port with the SCSI subsystem via the
+  Fibre Channel (FC) transport class.
+
+  rports are also visible via sysfs as children of the FC host adapter.
+
+  For developers: use fc_remote_port_add() and fc_remote_port_delete() when
+  implementing a driver that interacts with the FC transport class.
 
 
 FC Virtual Ports (vports)
-- 
2.47.1

Re: [PATCH] scsi: docs: scsi_fc_transport: Add documentation for FC Remote Ports

[Martin K. Petersen]

Alok,

> This patch updates the scsi_fc_transport.rst documentation by
> replacing the outdated << To Be Supplied >> placeholder under the "FC
> Remote Ports (rports)" section with a detailed explanation of remote
> port functionality in the Fibre Channel (FC) transport class.

Applied to 6.17/scsi-staging, thanks!

-- 
Martin K. Petersen