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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-ID: <20250607162304.1765430-1-alok.a.tiwari@oracle.com>
Date: Sat,  7 Jun 2025 09:22:56 -0700
From: Alok Tiwari <alok.a.tiwari@...cle.com>
To: corbet@....net, linux-doc@...r.kernel.org, linux-scsi@...r.kernel.org,
        martin.petersen@...cle.com
Cc: alok.a.tiwari@...cle.com, himanshu.madhani@...cle.com,
        darren.kenny@...cle.com, linux-kernel@...r.kernel.org
Subject: [PATCH] scsi: docs: scsi_fc_transport: 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@...cle.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