Content-type: text/html Man page of HBA_SendCTPassThru

HBA_SendCTPassThru

Section: Common Fibre Channel HBA Information Library Functions (3HBAAPI)
Updated: 1 Sep 2003
Index Return to Main Contents
 

NAME

HBA_SendCTPassThru, HBA_SendCTPassThruV2 - end a Fibre Channel Common Transport request to a Fabric  

SYNOPSIS

cc [ flag... ] file... -lHBAAPI [ library... ]
#include <hbaapi.h>

HBA_STATUS HBA_SendCTPassThru(HBA_HANDLE handle, void *pReqBuffer, HBA_UINT32 ReqBufferSize, void *pRspBuffer, HBA_UINT32 RspBufferSize);

HBA_STATUS HBA_SendCTPassThruV2(HBA_HANDLE handle, HBA_WWN hbaPortWWN, void *pReqBuffer, HBA_UINT32 ReqBufferSize, void *pRspBuffer, HBA_UINT32 *RspBufferSize);  

PARAMETERS

handle an open handle returned from HBA_OpenAdapter(3HBAAPI)

hbaPortWWN the Port Name of the local HBA Port through which the caller is issuing the CT request

pReqBuffer a pointer to a CT_IU request. The contents of the buffer must be in big-endian byte order

ReqBufferSize the length of the CT_IU request buffer pReqBuffer

pRspBuffer a pointer to a CT_IU response buffer. The response received from the fabric is copied into this buffer in big-endian byte order. Success of the function need not imply success of the command. The CT_IU Command/Response field should be checked for the Accept Response code.

RspBufferSize

HBA_SendCTPassThru()

the length of the CT_IU accept response buffer pRspBuffer.

HBA_SendCTPassThruV2()

a Pointer to the length of the CT_IU accept response buffer pRspBuffer.

 

DESCRIPTION

The HBA_SendCTPassThru() and HBA_SendCTPassThruV2() functions provide access to the standard in-band fabric management interface. The pReqBuffer argument is interpreted as a CT_IU request, as defined by the T11 specification FC-GS-3, and is routed in the fabric based on the GS_TYPE field.  

RETURN VALUES

Upon successful transport and receipt of a CT_IU response, HBA_SendCTPassThru() returns HBA_STATUS_OK. The CT_IU payload indicates whether the command was accepted by the fabric based on the Command/Response code returned. Otherwise, an error value is returned from the underlying VSL and the values in pRspBuffer are undefined.

Upon successful transport and receipt of a CT_IU response, HBA_SendCTPassThruV2() returns HBA_STATUS_OK. The CT_IU payload indicates whether the command was accepted by the fabric based on the Command/Response code returned. Otherwise, an error code is returned from the underlying VSL, and the values in pRspBuffer are undefined. The HBA_SendCTPassThruV2() function returns the following values:

HBA_STATUS_ERROR_ILLEGAL_WWN

The value of hbaPortWWN is not a valid port WWN on the specified HBA.

HBA_STATUS_ERROR

An error occurred.

 

ERRORS

See libhbaapi(3LIB) for general error status values.  

EXAMPLES

Example 1: Data structures for the GIEL command.

struct ct_iu_preamble {
    uint32_t  ct_rev        : 8,
              ct_inid       : 24;
    uint32_t  ct_fcstype    : 8,
              ct_fcssubtype : 8,
              ct_options    : 8,
              ct_reserved1  : 8;
    uint32_t  ct_cmdrsp     : 16,
              ct_aiusize    : 16;
    uint32_t  ct_reserved2  : 8,
              ct_reason     : 8,
              ct_expln      : 8,
              ct_vendor     : 8;
};
struct gs_ms_ic_elem {
    uchar_t   elem_name[8];
    uint32_t  reserved1   : 24,
              elem_type   : 8;
};
struct gs_ms_giel_rsp {
    struct ct_iu_preamble  ct_header;
    uint32_t               num_elems;
struct gs_ms_ic_elem   elem_list[1];
};
#define MAX_PAYLOAD_LEN 65536 /* 64K */

Example 2: Send an GIEL Management Service command through the given HBA handle.

The following example sends an GIEL Management Service command through the given HBA handle.

req.ct_rev        = 0x01;
req.ct_fcstype    = 0xFA;   /* Management Service */
req.ct_fcssubtype = 0x01;   /* Config server */
req.ct_cmdrsp     = 0x0101; /* GIEL command */
req.ct_aiusize    = MAX_PAYLOAD_LEN / 4 -
         sizeof (struct ct_iu_preamble) / 4;
if ((status = HBA_SendCTPassThru(handle, &req, sizeof (req),
        rsp, MAX_PAYLOAD_LEN)) != HBA_STATUS_OK) {
    fprintf(stderr, "Unable to issue CT command on         " for reason %d, adaptername, status);
} else {
    giel = (struct gs_ms_giel_rsp *)rsp;
    if (giel->ct_header.ct_cmdrsp != 0x8002) {
        fprintf(stderr, "CT command rejected on HBA "
            "    } else {
        for (cntr = 0; cntr < giel->num_elems; cntr++) {
        memcpy(&wwn, giel->elem_list[cntr].elem_name, 8);
        printf(" Fabric element name: %016llx, wwn);
        }
    }
}

 

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
Interface Stability Standard: FC-MI 1.92 (API version 1)
Standard: FC-HBA Version 4 (API version 2)
MT-LevelSafe

 

SEE ALSO

HBA_OpenAdapter(3HBAAPI), libhbaapi(3LIB), attributes(5)

T11 FC-MI Specification  

BUGS

The HBA_SendCTPassThru() function does not take a portindex to define through which port of a multi-ported HBA to send the command. The behavior on multi-ported HBAs is vendor specific, and can result in the command always being sent on port 0 of the HBA.
 SNIA version 2 defines HBA_SendCTPassThruV2() which takes a Port WWN as an argument.  This fixes the bug with multi-ported HBAs in HBA_SendCTPassThru().


 

Index

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
RETURN VALUES
ERRORS
EXAMPLES
ATTRIBUTES
SEE ALSO
BUGS

This document was created by man2html, using the manual pages.
Time: 02:39:51 GMT, October 02, 2010