Note that this case is closed approved automatic and has been approved by
the DTrace OpenSolaris community. As noted, the stability is Committed and
binding is Patch.
Adam
On Thu, May 07, 2009 at 01:09:12PM -0700, Adam Leventhal wrote:
>
> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
> This information is Copyright 2009 Sun Microsystems
> 1. Introduction
> 1.1. Project/Component Working Name:
> DTrace COMSTAR Fibre Channel Target Provider
> 1.2. Name of Document Author/Supplier:
> Author: Sam Cramer
> 1.3 Date of This Document:
> 07 May, 2009
> 4. Technical Description
> Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
> This information is Copyright 2009 Sun Microsystems
> 1. Introduction
> 1.1. Project/Component Working Name:
> DTrace COMSTAR Fibre Channel Target Provider
> 1.2. Name of Document Author/Supplier:
> Author: Sam Cramer
> 1.3 Date of This Document:
> 07 May, 2009
> 4. Technical Description
>
> The following specification describes the COMSTAR Fibre Channel Target
> provider for DTrace. It has been reviewed and approved by the DTrace
> community; the PSARC case is closed approved automatic to record the
> interface. The stability is Committed and the binding is Patch.
>
> The fc provider provides probes for tracing fibre channel port provider
> activity.
>
> This is a kernel provider built into the COMSTAR fc target port provider.
>
> FC Provider
>
> 4.1 Probes overview
>
> Fibre Channel Event Type Probes
> ------------------------ ------
> Link events fc:::link-up
> fc:::link-down
>
> Remote Port login/logout fc:::rport-login-start
> fc:::rport-login-end
> fc:::rport-logout-start
> fc:::rport-logout-end
>
> Fabric login fc:::fabric-login-start
> fc:::fabric-login-end
>
> SCSI command/response fc:::scsi-command
> fc:::scsi-response
>
> Data transfer fc:::xfer-start
> fc:::xfer-done
>
> 4.2 Probe argument commonality
>
> 4.2.1 Arguments common to all probes
>
> All FC probes have the first argument in common:
>
> args[0] conninfo_t * fc connection information
>
> The conninfo_t structure is already used by the iSCSI target provider (iscsi),
> and is intended for use by all provider which are providing some higher
> level protocol (e.g. iscsi, nfs, http, ftp).
>
> typedef struct conninfo {
> string ci_local; /* local host address (port WWN) */
> string ci_remote; /* remote host address (port WWN) */
> string ci_protocol; /* protocol (fc) */
> } conninfo_t;
>
>
> 4.2.2 Arguments common to all probes save for link event probes
>
> All FC event probes other than link event probes have their second argument
> in common:
>
> args[1] fc_port_info_t * local port information
>
> The fc_port_info_t structure contains detailed information about a Fibre
> Channel port:
>
> typedef struct fc_port_info {
> string fcp_node_wwn; /* node WWN */
> string fcp_sym_node_name; /* node symbolic name */
> string fcp_sym_port_name; /* port symbolic name */
> uint32_t fcp_port_hard_address; /* port hard address */
> } fc_port_info_t;
>
> 4.2.3 Arguments common to SCSI command and data transfer probes
>
> FC SCSI command and data transfer probes have their third and fourth
> arguments in common:
>
> args[2] scsicmd_t * SCSI command block (cdb)
> args[3] fc_port_info_t * remote port information
>
> The scsicmd_t structure contains information about SCSI command blocks:
>
> typedef struct scsicmd {
> uint64_t ic_len; /* CDB length */
> uint8_t *ic_cdb; /* CDB data */
> } scsicmd_t;
>
> 4.2.4 Arguments common to data transfer probes
>
> FC data transfer probes have their fifth argument in common:
>
> args[4] fc_xferinfo_t * data transfer information
>
> The fc_xferinfo_t structure contains information about the data transfer:
>
> typedef struct fc_xferinfo {
> uint32_t fcx_len; /* transfer length */
> uint32_t fcx_offset; /* transfer offset */
> uint16_t fcx_flags; /* db_flags as defined in sys/stmf.h
> */
> } fc_xferinfo_t;
>
>
> 4.3 Detailed probes specification
>
> 4.3.1 Link Event Probes
>
> fc:::link-up and fc:::link-down trace Fibre Channel link-up and link-down
> events.
>
> Remote port information (ci_remote) is unavailable for both probes.
>
> Probes Variable Type Description
> ------ -------- ---- -----------
> fc:::link-up, args[0] conninfo_t * connection info
> fc:::link-down
>
> 4.3.2 Remote Port Login/Logout Event Probes
>
> Probes Variable Type Description
> ------ -------- ---- -----------
> fc:::rport-login-start, args[0] conninfo_t * connection info
> fc:::rport-login-end, args[1] fc_port_info_t * local port info
> fc:::rport-logout-start, args[2] fc_port_info_t * remote port info
> fc:::rport-logout-end args[3] int solicited login
> flag
>
> args[3] is 0 if the login or logout is unsolicited (inbound) and is
> non-zero if solicited (outbound).
>
> 4.3.3 Fabric Login Event Probes
>
> Probes Variable Type Description
> ------ -------- ---- -----------
> fc:::fabric-login-start, args[0] conninfo_t * connection info
> fc:::fabric-login-end,
>
> fc:::fabric-login-end args[1] fc_port_info_t * local port info
>
> Fabric login applies only to the local port, since that's the entity that
> logs into the fabric. Note that there's no explicit fabric logout. Detailed
> local port information is only known at the end of fabric login.
>
> 4.3.4 SCSI Command Event Probes
>
> Probes Variable Type Description
> ------ -------- ---- -----------
> fc:::scsi-command, args[0] conninfo_t * connection info
> fc:::scsi-response args[1] fc_port_info_t * local port info
> args[2] scsi_cmd_t * SCSI command block
> args[3] fc_port_info_t * remote port info
>
> 4.3.5 Data Transfer Event Probes
>
> Probes Variable Type Description
> ------ -------- ---- -----------
> fc:::xfer-start, args[0] conninfo_t * connection info
> fc:::xfer-done args[1] fc_port_info_t * local port info
> args[2] scsi_cmd_t * SCSI command block
> args[3] fc_port_info_t * remote port info
> args[4] fc_xferinfo_t * data transfer info
>
>
> Documentation and examples can be found here:
>
> http://wikis.sun.com/display/DTrace/fibre+channel+Provider
>
> The table below describes the DTrace stability levels
>
> | Name Data Class
>
> -------------+-------------------------------------------
>
> Provider | Evolving Evolving ISA
>
> Module | Private Private Unknown
>
> Function | Private Private Unknown
>
> Name | Evolving Evolving ISA
>
> Arguments | Evolving Evolving ISA
>
>
> 6. Resources and Schedule
> 6.4. Steering Committee requested information
> 6.4.1. Consolidation C-team Name:
> OS/Net
> 6.5. ARC review type: FastTrack
> 6.6. ARC Exposure: open
>
>
> 6. Resources and Schedule
> 6.4. Steering Committee requested information
> 6.4.1. Consolidation C-team Name:
> OS/Net
> 6.5. ARC review type: FastTrack
> 6.6. ARC Exposure: open
>
--
Adam Leventhal, Fishworks http://blogs.sun.com/ahl
