[PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2nd try)

[PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2nd try)

[Jing Huang]

From: Jing Huang <huangj@brocade.com>

This patch contains document of brocade specific sysfs interface.
It is created using 2.6.27-rc7 kernel.

Signed-off-by: Jing Huang <huangj@brocade.com>
---
 Documentation/ABI/testing/sysfs-devices-bfa |  600 ++++++++++++++++++++++++++++
 1 files changed, 600 insertions(+)

diff -urpN orig/Documentation/ABI/testing/sysfs-devices-bfa patch/Documentation/ABI/testing/sysfs-devices-bfa
--- orig/Documentation/ABI/testing/sysfs-devices-bfa	1969-12-31 16:00:00.000000000 -0800
+++ patch/Documentation/ABI/testing/sysfs-devices-bfa	2008-09-24 12:08:25.000000000 -0700
@@ -0,0 +1,600 @@
+What:		/sys/devices/<Brocade HBA PCI path>/bfa
+Date:		July 2008
+Contact:	Jing Huang <huangj@brocade.com>
+Description:
+		The /sys/devices/<Brocade HBA device path>/bfa will contain
+		files and subdirectories to display internal states and
+		statistics of Brocade HBA. It also provides a configuration and
+		management interface for each HBA instance.
+
+What:		/sys/devices/<Brocade HBA PCI path>/bfa/ioc
+Date:		July 2008
+Contact:	Jing Huang <huangj@brocade.com>
+Description:
+		The /sys/devices/<Brocade HBA device path>/ioc will contain
+		files and directories to display ioc level attributes
+		and statistics of the HBA.
+
+Files and directories under /sys/devices/<Brocade HBA PCI path>/bfa/ioc:
+------------------------------------------------------------------------
+
+bios_ver
+
+	 BIOS version
+
+chip_rev		
+
+	Chip version
+
+fw_ver
+	Firmware version
+
+hw_name
+
+	Hardware name or pci path
+
+hw_ver
+
+	Hardware version
+
+intr
+	Interrupt coalescing setting 
+
+manufacturer
+
+	Manufacturer info
+
+model_desc
+	
+	Model description
+
+mpiomode
+
+	mpio mode setting of IOC
+
+name
+	Name of the driver
+
+nwwn
+	World Wide Node Name
+
+optrom_ver
+
+	Option Rom version
+
+port_count
+
+	Port count of the HBA
+
+power
+
+	IOC power state
+
+pwwn
+
+	World Wide Node Name
+
+serial_num
+
+	Serial number
+
+statistics/
+	
+	Contains following files for IOC level statistics:
+
+	disable_replies
+		
+		Number of IOC disable replies
+
+	disable_requests
+
+		Number of IOC disable requests
+
+	enable_replies
+
+		Number of IOC Enable replies
+
+	enable_requests
+
+		Number of IOC Enable requests
+
+	heartbeat_count
+
+		Number of heartbeat count 
+
+	reset
+
+		Write to reset the IOC statistics.
+
+
+What:		/sys/devices/<Brocade HBA PCI path>/bfa/pport
+Date:		July 2008
+Contact:	Jing Huang <huangj@brocade.com>
+Description:
+		The /sys/devices/<Brocade HBA device path>/pport will contain
+		files and directories to display pport (physical port) level
+		attributes and statistics of the HBA.
+
+Files and directories under /sys/devices/<Brocade HBA PCI path>/bfa/pport:
+--------------------------------------------------------------------------
+
+enable
+
+	Eenable/disable the pport.
+
+maxfrmi
+ 	Maximum frame size
+	
+media	 	
+	SFP 
+
+nwwn
+	
+	World wide node name
+
+port_id
+
+	Fibre Channel port ID
+
+port_type
+
+	Port type
+
+pwwn
+
+	World wide port name
+
+recv_bb_credits
+
+	Receive buffer credits
+
+speed_config
+
+	Configured port speed.
+
+speed_current
+
+	Current port speed
+
+state
+
+	Port state 
+	
+supported_classes
+
+	Supported classes of services
+
+symbolic_name
+
+	Symbolic name of the pport
+
+topology_config
+
+	Configured topology
+
+topology_current
+
+	Current topology
+
+statistics/
+
+	Contains following files for pport level statistic:
+
+	dropped_frames
+
+		Number of frames that were lost due to lack of host buffers
+		available
+
+	error_frames
+		
+		Number of frames that have been received in error
+
+	invalid_crcs
+
+		Number of frames that received with invalid CRC
+
+	invalid_ordered_set
+		
+		Number of invalid ordered that have received
+		
+	link_failures
+
+		Number of times that a link error has occurred
+
+	lip_count
+
+		Number of LIP events that have occurred.
+
+	loss_of_signals
+
+		Number of times loss of signal has occurred
+	
+	loss_of_syncs
+
+		Number of times loss of sync has occurred
+
+	nos_count
+
+		Number of NOS events that have occurred on the switched fabric
+
+	primitive_seq_errs
+
+		Number of primitive sequence protocol errors
+
+	rx_frames
+
+		Number of total received Fibre Channle frames across all
+		protocols and classes
+
+	rx_words
+
+		Number of total received Fibre Channle words across all
+		protocols and classes
+
+	secs_since_reset
+
+		Number of seconds since the statistics were last reset
+
+	tx_frames
+
+		Number of total transmitted Fibre Channle frames across all
+		protocols and classes
+
+	tx_words
+	
+		Number of total transmitted Fibre Channle words across all
+		protocols and classes
+	
+	reset
+
+		Write to reset the pport statistics
+
+
+What:		/sys/devices/<Brocade HBA PCI path>/bfa/lport
+Date:		July 2008
+Contact:	Jing Huang <huangj@brocade.com>
+Description:	
+		The /sys/devices/<Brocade HBA device path>/lport will contain
+		files and directories to display lport (logical port) level
+		attributes and statistics of the HBA.
+
+Files and directories under /sys/devices/<Brocade HBA PCI path>/bfa/lport:
+--------------------------------------------------------------------------
+
+nwwn
+	
+	World wide node name 
+
+port_id
+
+	Fibre Channel port ID
+
+pwwn
+
+	World wide port name
+
+refresh_rports
+
+	Read to this file will show number of remote port (rport) connected to
+	the logical port, and will also creat a rp-<wwpn> directory for each 
+	rport.
+
+role
+
+	Role of the lport
+
+state
+
+	State of the lport
+
+symbolic_name
+
+	Symbolic name of the lport
+
+type
+
+	lport type
+
+statistics/
+
+	Contains following files for lport level statistics:
+
+	ns_gidft_accepts
+
+		Number of GID_FT requests that have been accepted by the name
+		server
+
+	ns_gidft_alloc_wait
+
+		Number of GID_FT requests that have fcxp allocation failure
+		and been put in the wait queue. 
+
+	ns_gidft_rejects
+
+		Number of GID_FT requests that have been rejected by the name
+		server
+
+	ns_gidft_rsp_err
+
+		Number of GID_FT requests that have completed with response
+		error 
+
+	ns_gidft_sent
+
+		Number of GID_FT requests that have been sent 
+
+	ns_gidft_unknown_rsp
+
+		Number of GID_FT requests that have completed with unknown 
+		response code
+
+	ns_plogi_accepts
+
+		Number of PLOGI requests that have been accepted by the name
+		server
+
+	ns_plogi_acc_err
+
+		Number of PLOGI requests that have been accepted by the name
+		server but with wrong response length
+
+	ns_plogi_alloc_wait
+
+		Number of PLOGI  requests that have fcxp allocation failure
+		and been put in the wait queue. 
+
+	ns_plogi_rejects
+
+		Number of PLOGI requests that have been rejected by the name
+		server
+
+	ns_plogi_rsp_err
+
+		Number of PLOGI requests that have completed with response
+		error 
+
+	ns_plogi_sent
+
+		Number of name server PLOGI requests that have been sent 
+
+	ns_plogi_unknown_rsp
+
+		Number of plogi requests that have completed with unknown 
+		response code
+
+	ns_retries
+		
+		Number of name server command retries
+
+	ns_rftid_accepts
+
+		Number of RFT_ID requests that have been accepted by the name
+		server
+
+	ns_rftid_alloc_wait
+
+		Number of RFT_ID requests that have fcxp allocation failure
+                and been put in the wait queue
+
+	ns_rftid_rejects
+
+		Number of RFT_ID requests that have been rejected by the name
+                server
+
+	ns_rftid_rsp_err
+
+		Number of RFT_ID requests that have completed with response
+                error
+
+	ns_rftid_sent
+
+		Number of RFT_ID requests that have been sent
+
+	ns_rspnid_accepts
+
+		Number of RSPN_ID requests that have been accepted by the name
+		server
+
+	ns_rspnid_alloc_wait
+		Number of RSPN_ID requests that have fcxp allocation failure
+		and been put in the wait queue.
+
+	ns_rspnid_rejects
+
+		Number of RSPN_ID requests that have been rejected by the name
+                server
+
+	ns_rspnid_rsp_err
+
+		Number of RSPN_ID requests that have completed with response
+                error
+		
+	ns_rspnid_sent
+
+		Number of RSPN_ID requests that have been sent
+
+	ns_timeouts
+
+		Number of name server command timeouts
+
+	num_portid_rscn
+
+		Number of Port ID RSCN received
+
+	num_rscn
+
+		Number of RSCN received
+
+	reset
+
+		Write to reset lport statistics
+
+
+What:		/sys/devices/<Brocade HBA PCI path>/bfa/lport/rp-<pwwn>
+Date:		July 2008
+Contact:	Jing Huang <huangj@brocade.com>
+Description:	
+		The /sys/devices/<Brocade HBA device path>/lport/rp-<pwwn>
+		will contain files and directories to display attributes and
+		statistics of a rport (remote port, identified by its world
+		wide port name) of lport. 
+
+Files and directories under /sys/devices/<...>/bfa/lport/rp-<pwwn>:
+-------------------------------------------------------------------
+
+cisc
+	CISC capable device
+
+class_of_service
+
+	Fibre Channel classes of services
+
+data_field_size
+
+	Maximum payload size
+
+nwwn
+	
+	Rport world wide node name
+
+port_id
+
+	Rport FC port ID
+
+pwwn
+
+	Rport world wide port name
+
+qos_priority
+
+	Rport Qos priority
+
+speed
+
+	Rport speed
+
+state
+
+	Rport state
+
+symbolic_name
+
+	Rport symbolic name
+
+statistics/
+
+	Contains following files for rport statistics:
+
+	logo_accepts
+
+		Number LOGO accepts from the rport
+
+	logo_sent
+		
+		Number of LOGOs sent to the rport 
+
+	offlines
+
+		Number of rport offlines
+
+	onlines
+
+		Number of rport onlines
+
+	plogi_accepts
+
+		Number of PLOGI accepts from the rport
+
+	plogi_failed
+
+		Number of PLOGI failures to the rport 
+
+	plogi_rcvd
+
+		Number of PLOGIs received from rport
+
+	plogi_rejects
+
+		Number of PLOGI rejects from the rport
+
+	plogi_sent
+
+		Number of PLOGIs sent to the rport. 
+
+	plogi_timeouts
+
+		Number of PLOGI timeouts to the rport. 
+
+	prli_rcvd
+
+		Number of PRLIs received from the rport. 
+
+	rscns
+
+		Number of RSCNs that affect the rport
+
+	reset
+		
+		Write to reset rport statistics
+
+
+What:		/sys/devices/<Brocade HBA PCI path>/bfa/lport/rp-<pwwn>/itnim
+Date:		July 2008
+Contact:	Jing Huang <huangj@brocade.com>
+Description:	
+		The /sys/devices/<Brocade HBA device path>/lport/rp-<pwwn>
+		/itnim will contain files and directories to display attributes
+		and statistics of an itnim (initiator and target nexus) associated
+		with a rport.
+
+Files and directories under /sys/devices/<...>/bfa/lport/rp-<pwwn>/itnim:
+-------------------------------------------------------------------------
+
+state
+
+	itnim state
+
+statistics/
+
+	Contains following files for itnim statistics:
+
+	fcxp_alloc_wait
+
+		Number of PRLI requests that have failed fcxp allocation failure
+		and been put in the wait queue.
+
+	initiator_mode
+
+		Is the rport in initiator mode
+
+	offlines
+
+		Number of offlines
+
+	onlines
+
+		Number of onlines
+
+	prli_rsp_acc
+
+		Number of PRLI accepts
+
+	prli_rsp_err
+
+		Number of PRLI failures
+
+	prli_rsp_parse_err
+
+		Number of PRLI response with parse error
+
+	prli_sent
+		
+		Number of PRLI sent to the itnim
+
+	second_level_error_recovery
+
+		Number of second level error recovery notifications
+
+	reset
+
+		Write to reset itnim statistics

Re: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2nd try)

[Greg KH]

On Thu, Sep 25, 2008 at 06:06:00PM -0700, Jing Huang wrote:
> From: Jing Huang <huangj@brocade.com>
> 
> This patch contains document of brocade specific sysfs interface.
> It is created using 2.6.27-rc7 kernel.

What about my question for the need for all of these files and using
debugfs instead?

thanks,

greg k-h

RE: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2ndtry)

[Jing Huang]

The reason we creating our own sysfs directory under /sys/devices path
was we felt the fc transport and scsi host attributes are not enough for
all the HBA management features we want to have. We have ioctl in our
non opensource driver, and we want to have something to emulate all/most
of the IOCTL functionality we have in the opensource driver. We provide
multi-level of driver/fw statistics info to the user, and we want to put
those info under a separate directory instead of throw them all under
scsi_host. I just didn't know how to create a subdirectory under scsi/fc
host. Currently, we only implement a small portion of all the IOCTL
functionalities. We want to know if this is acceptable in the upstream
kernel. 

I agree that there are a lot of redundancy with the attributes we
created under scsi_host. We will clean them up.

Jing

-----Original Message-----
From: Greg KH [mailto:greg@kroah.com] 
Sent: Thursday, September 25, 2008 7:55 PM
To: Jing Huang
Cc: James.Bottomley@HansenPartnership.com; linux-kernel@vger.kernel.org;
linux-scsi@vger.kernel.org; Ramkumar Vadivelu; Srikanth Rayas (CW);
Vinodh Ravindran
Subject: Re: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission
(2ndtry)

On Thu, Sep 25, 2008 at 06:06:00PM -0700, Jing Huang wrote:
> From: Jing Huang <huangj@brocade.com>
> 
> This patch contains document of brocade specific sysfs interface.
> It is created using 2.6.27-rc7 kernel.

What about my question for the need for all of these files and using
debugfs instead?

thanks,

greg k-h

RE: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2ndtry)

[James Bottomley]

On Thu, 2008-09-25 at 21:49 -0700, Jing Huang wrote:
> The reason we creating our own sysfs directory under /sys/devices path
> was we felt the fc transport and scsi host attributes are not enough for
> all the HBA management features we want to have.

This isn't really a valid reason.  We use the fc transport class to
share infrastructure and provide a common interface for users.  If you
need more, we can discuss adding features to the fc transport class if
they would be useful to fibre drivers in general.  If they're not useful
to other drivers, then you can add pieces specific to your driver for
them, but the functionality that's already in the fc transport shouldn't
be duplicated by that.

>  We have ioctl in our
> non opensource driver, and we want to have something to emulate all/most
> of the IOCTL functionality we have in the opensource driver. We provide
> multi-level of driver/fw statistics info to the user, and we want to put
> those info under a separate directory instead of throw them all under
> scsi_host.

That's how the fc transport class currently operates.  It's statistics
all appear in a "statistics" directory under the host.  If you use it
(and add the ones you need that are missing) everyone will be happy and
you won't need to worry about creating the directories.

>  I just didn't know how to create a subdirectory under scsi/fc
> host. Currently, we only implement a small portion of all the IOCTL
> functionalities. We want to know if this is acceptable in the upstream
> kernel. 
> 
> I agree that there are a lot of redundancy with the attributes we
> created under scsi_host. We will clean them up.

James

RE: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2ndtry)

[Jing Huang]

Hi James,

It is encouraging to know that we can discuss and add new feature into
existing fc transport. I guess this is opensource all about. I didn't
have linux opensource experience before, so I was not quite sure how
easy to request new features in fc transport such as mechanism to create
multiple subdirectories for different level of statistics info in
addition to the snia fc statitistics we already have, and other features
such as CT/SCSI passthru and asynchronous event notification etc.

Thanks

Jing 


-----Original Message-----
From: James Bottomley [mailto:James.Bottomley@HansenPartnership.com] 
Sent: Thursday, September 25, 2008 11:02 PM
To: Jing Huang
Cc: Greg KH; linux-kernel@vger.kernel.org; linux-scsi@vger.kernel.org;
Ramkumar Vadivelu; Srikanth Rayas (CW); Vinodh Ravindran
Subject: RE: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission
(2ndtry)

On Thu, 2008-09-25 at 21:49 -0700, Jing Huang wrote:
> The reason we creating our own sysfs directory under /sys/devices path
> was we felt the fc transport and scsi host attributes are not enough
for
> all the HBA management features we want to have.

This isn't really a valid reason.  We use the fc transport class to
share infrastructure and provide a common interface for users.  If you
need more, we can discuss adding features to the fc transport class if
they would be useful to fibre drivers in general.  If they're not useful
to other drivers, then you can add pieces specific to your driver for
them, but the functionality that's already in the fc transport shouldn't
be duplicated by that.

>  We have ioctl in our
> non opensource driver, and we want to have something to emulate
all/most
> of the IOCTL functionality we have in the opensource driver. We
provide
> multi-level of driver/fw statistics info to the user, and we want to
put
> those info under a separate directory instead of throw them all under
> scsi_host.

That's how the fc transport class currently operates.  It's statistics
all appear in a "statistics" directory under the host.  If you use it
(and add the ones you need that are missing) everyone will be happy and
you won't need to worry about creating the directories.

>  I just didn't know how to create a subdirectory under scsi/fc
> host. Currently, we only implement a small portion of all the IOCTL
> functionalities. We want to know if this is acceptable in the upstream
> kernel. 
> 
> I agree that there are a lot of redundancy with the attributes we
> created under scsi_host. We will clean them up.

James

Re: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2ndtry)

[James Smart]

We are finally finishing up CT/ELS passthru in the FC transport; SCSI 
passthru exists, but via the scsi_generic driver (so it's not part of 
the transport or LLDD); and async event notification is already present 
in the fc transport.

-- james s

Jing Huang wrote:
> Hi James,
> 
> It is encouraging to know that we can discuss and add new feature into
> existing fc transport. I guess this is opensource all about. I didn't
> have linux opensource experience before, so I was not quite sure how
> easy to request new features in fc transport such as mechanism to create
> multiple subdirectories for different level of statistics info in
> addition to the snia fc statitistics we already have, and other features
> such as CT/SCSI passthru and asynchronous event notification etc.
> 
> Thanks
> 
> Jing

RE: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2ndtry)

[Jing Huang]

Thanks James. I guess I need to follow up all the updates on this front,
and will change our management tools accordingly.

Jing

-----Original Message-----
From: James Smart [mailto:James.Smart@Emulex.Com] 
Sent: Friday, September 26, 2008 4:08 AM
To: Jing Huang
Cc: James Bottomley; Greg KH; linux-kernel@vger.kernel.org;
linux-scsi@vger.kernel.org; Ramkumar Vadivelu; Srikanth Rayas (CW);
Vinodh Ravindran
Subject: Re: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission
(2ndtry)

We are finally finishing up CT/ELS passthru in the FC transport; SCSI 
passthru exists, but via the scsi_generic driver (so it's not part of 
the transport or LLDD); and async event notification is already present 
in the fc transport.

-- james s

Jing Huang wrote:
> Hi James,
> 
> It is encouraging to know that we can discuss and add new feature into
> existing fc transport. I guess this is opensource all about. I didn't
> have linux opensource experience before, so I was not quite sure how
> easy to request new features in fc transport such as mechanism to
create
> multiple subdirectories for different level of statistics info in
> addition to the snia fc statitistics we already have, and other
features
> such as CT/SCSI passthru and asynchronous event notification etc.
> 
> Thanks
> 
> Jing

RE: [PATCH 5/6] bfa: Brocade BFA FC SCSI driver submission (2ndtry)

[James Bottomley]

On Thu, 2008-09-25 at 23:30 -0700, Jing Huang wrote:
> It is encouraging to know that we can discuss and add new feature into
> existing fc transport. I guess this is opensource all about. I didn't
> have linux opensource experience before, so I was not quite sure how
> easy to request new features in fc transport such as mechanism to create
> multiple subdirectories for different level of statistics info in
> addition to the snia fc statitistics we already have, and other features
> such as CT/SCSI passthru and asynchronous event notification etc.

Well, this is open source ... you don't get to request new features; you
get to implement them, so if you need something that SCSI or the FC
transport doesn't provide, you just add it (rather than coding either a
fix or an enhancement for your driver alone).

However, you're quite lucky.  So far, as James Smart said, I haven't
seen you ask for any features that we don't either provide or are in
process of agreeing the implementation of.

James