scsi: fc_transport: docs: Add documentation for FC Remote Ports

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>
Link: https://lore.kernel.org/r/20250607162304.1765430-1-alok.a.tiwari@oracle.com
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>

diff --git a/Documentation/scsi/scsi_fc_transport.rst b/Documentation/scsi/scsi_fc_transport.rst
index e3ddcfb7f8fd3da573e1df94977f5e4f3c9afb57..5ef75575924e4a2db91ed18653e3b6ae359e7202 100644 (file)
--- 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)