# ZFCP HBA API Kernel Interfaces

## Introduction

ZFCP HBA API is an implementation of bib.fchba for the ZFCP device driver. The ZFCP device driver is a FCP device driver for Linux on zSeries. This documentation describes the ZFCP HBA API for Linux Kernel 2.4. ZFCP HBA API consists of the following parts.

- ZFCP HBA API Library - a shared library which provides the API defined in bib.fchba.

- The kernel module `zfcp_hbaapi` which provides a misc device with IO controls for communication between kernel and user space. The module registers callback functions in the ZFCP device driver and is able to use functionality provided by the ZFCP device driver. This module is the connection between ZFCP HBA API Library and the ZFCP devcie driver.

- Finally the ZFCP device driver contains hooks at which callback functions of the `zfcp_hbaapi` kernel module are invoked. Furthermore the device driver provides functionality which can be used by the `zfcp_hbaapi` kernel module.

This documentation describes the kernel parts of ZFCP HBA API. Separate documentation for ZFCP HBA API Library exists.

## Kernel Module `zfcp_hbaapi`

### Overview

The module `zfcp_hbaapi` is the interface between the ZFCP HBA API Library and the ZFCP device driver. It provides a misc device which is used for communication between kernel and user space. The module registers callback functions in the ZFCP device driver which are invoked when certain events occur. Furthermore it calls functions provided by the ZFCP device driver to collect data for the ZFCP HBA API Library.

### Device File

The module `zfcp_hbaapi` provides a misc device. The corresponding device node should be named `/dev/zfcp_hbaapi` - ZFCP HBA API Library expects this name for the device file. When the module is loaded the device node can be generated using the commands:

    #>minor=`cat /proc/misc | awk "\\$2==\\"zfcp_hbaapi\\" {print \\$1}"`
    #>mknod /dev/zfcp_hbaapi c 10 $minor

#### Module Paramters

The following parameters can be set for the module.

#### Module Parameters

Parameter | Description | Default Value
`maxshared` | Maximum number of events in the shared event queue. | `20`
`maxpolled` | Maximum number of events in the polled event queue. | `20`
`minor` | Minor number for the misc device to be registered. | MISC_DYNAMIC_MINOR

#### File Operations

The module `zfcp_hbaapi` defines the methods `open`, `read`, `release`, and `ioctl` for the misc device.

##### Reference

!Fdrivers/s390/scsi/zh_main.c zh_ioctl !Fdrivers/s390/scsi/zh_main.c zh_read !Fdrivers/s390/scsi/zh_main.c zh_release !Fdrivers/s390/scsi/zh_main.c zh_open

#### IO Controls

The next table gives an overview about IO controls of the misc device, the name of corresponding internal helper functions and argument types (if any).

#### IO Controls

Name | Helper Function, Argument Type
ZH_IOC_GET_ADAPTERATTRIBUTES | `zh_ioc_get_adapterattributes`, `struct zh_get_adapterattributes`
ZH_IOC_GET_PORTATTRIBUTES | `zh_ioc_get_portattributes`, `struct zh_get_portattributes`
ZH_IOC_GET_PORTSTATISTICS | `zh_ioc_get_portstatistics`, `struct zh_get_portstatistics`
ZH_IOC_GET_DPORTATTRIBUTES | `zh_ioc_get_dportattributes`, `struct zh_get_portattributes`
ZH_IOC_GET_RNID | `zh_ioc_get_rnid`, `struct zh_get_rnid`
ZH_IOC_SEND_RNID | `zh_ioc_send_rnid`, `struct zh_send_rnid`
ZH_IOC_SEND_CT | `zh_ioc_send_ct`, `struct zh_send_ct`
ZH_IOC_SCSI_INQUIRY | `zh_ioc_scsi_inquiry`, `struct zh_scsi_inquiry`
ZH_IOC_SCSI_READ_CAPACITY | `zh_ioc_scsi_read_capacity`, `struct zh_scsi_read_capacity`
ZH_IOC_SCSI_REPORT_LUNS | `zh_ioc_scsi_report_luns`, `struct zh_scsi_report_luns`
ZH_IOC_GET_EVENT_BUFFER | `zh_ioc_get_event_buffer`, `struct zh_get_event_buffer`
ZH_IOC_GET_CONFIG | `zh_ioc_get_config`, `struct zh_get_config`
ZH_IOC_CLEAR_CONFIG | `zh_ioc_clear_config`, `struct zh_clear_config`
ZH_IOC_EVENT_START | `zh_ioc_event_start`
ZH_IOC_EVENT_STOP | `zh_ioc_event_stop`
ZH_IOC_EVENT | `zh_ioc_event`, `struct zh_event`
ZH_IOC_EVENT_INSERT | `zh_ioc_event_insert`

If `zfcp_hbaapi` is compiled for 64 bit architecture, two additional IO controls exist. They are used for 32 bit IO control conversion:

#### IO Controls (on 64 bit architecture only)

Name | Helper Function, Argument Type
ZH_IOC_SEND_CT32 | `zh_ioc_send_ct32`, `struct zh_send_ct32`
ZH_IOC_SCSI_REPORT_LUNS32 | `zh_ioc_scsi_report_luns`, `struct zh_scsi_report_luns32`

#### Reference

!Fdrivers/s390/scsi/zh.h zh_get_adapterattributes !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_adapterattributes !Fdrivers/s390/scsi/zh.h zh_get_portattributes !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_portattributes !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_dportattributes !Fdrivers/s390/scsi/zh.h zh_get_portstatistics !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_portstatistics !Fdrivers/s390/scsi/zh.h zh_get_rnid !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_rnid !Fdrivers/s390/scsi/zh.h zh_send_rnid !Fdrivers/s390/scsi/zh_main.c zh_ioc_send_rnid !Fdrivers/s390/scsi/zh.h zh_send_ct !Fdrivers/s390/scsi/zh_main.c zh_ioc_send_ct !Fdrivers/s390/scsi/zh.h zh_scsi_inquiry !Fdrivers/s390/scsi/zh_main.c zh_ioc_scsi_inquiry !Fdrivers/s390/scsi/zh.h zh_scsi_read_capacity !Fdrivers/s390/scsi/zh_main.c zh_ioc_scsi_read_capacity !Fdrivers/s390/scsi/zh.h zh_scsi_report_luns !Fdrivers/s390/scsi/zh_main.c zh_ioc_scsi_report_luns !Fdrivers/s390/scsi/zh.h zh_get_event_buffer !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_event_buffer !Fdrivers/s390/scsi/zh.h zh_get_config !Fdrivers/s390/scsi/zh_main.c zh_ioc_get_config !Fdrivers/s390/scsi/zh_main.c zh_ioc_clear_config !Fdrivers/s390/scsi/zh_main.c zh_ioc_event_start !Fdrivers/s390/scsi/zh_main.c zh_ioc_event_stop !Fdrivers/s390/scsi/zh.h zh_event !Fdrivers/s390/scsi/zh_main.c zh_ioc_event !Fdrivers/s390/scsi/zh_main.c zh_ioc_event_insert

### Callback functions

For event notification `zfcp_hbaapi` registers a bunch of callback functions at the ZFCP device driver. In zfcp certain hooks exist where those callbacks are invoked.

#### Reference

!Fdrivers/s390/scsi/zh_main.c zh_cb_adapter_add !Fdrivers/s390/scsi/zh_main.c zh_cb_port_add !Fdrivers/s390/scsi/zh_main.c zh_cb_unit_add !Fdrivers/s390/scsi/zh_main.c zh_cb_incomming_els !Fdrivers/s390/scsi/zh_main.c zh_cb_link_down !Fdrivers/s390/scsi/zh_main.c zh_cb_link_up

## Kernel Module `zfcp`

The module `zfcp` provides (new) interfaces for ZFCP HBA API. Furthermore hooks are integrated at which callback functions for event notification are invoked.

### Intra-Kernel Interface

The ZFCP device driver exports the following functions

`zfcp_zh_callbacks_register`

Register callbacks for event handling. Called from `zh_init` - the init function of module `zfcp_hbaapi`.

`zfcp_zh_callbacks_unregister`

Unregister callbacks for event handling. Called from `zh_exit` - the exit function of module `zfcp_hbaapi`.

`zfcp_zh_get_config`

For each adapter, port and unit configured in module `zfcp` the corresponding callback function is called.

`zfcp_zh_get_adapter_attributes`

Collect attributes of an adapter.

`zfcp_zh_get_port_attributes`

Collect attributes of an adapter port. Calls FSF command `ExchangePortData`.

`zfcp_zh_port_statistics`

Collect statistics of an adapter port. Calls FSF command `ExchangePortData`.

`zfcp_zh_get_dport_attributes`

Collect attributes of a discovered port. Sends a FC-GS-2 request `GA_NXT` to the Name Server Directory Service.

`zfcp_zh_assert_fclun_zero`

Checks whether an unit with FC LUN `0x0` is configured in `zfcp` for a certain port. If not it creates a `zfcp` unit structure for FC LUN `0x0` for this port.

`zfcp_zh_send_scsi`

Send a SCSI command to a FC LUN.

`zfcp_zh_send_els`

Send ELS commands (according to FC-FS).

`zfcp_zh_send_ct`

Send Generic Service commands according to FC-GS-4).

In `zfcp_zh_send_ct` currently only requests to the Name Server Directory Service are supported.

#### Reference

!Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_callbacks_register !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_callbacks_unregister !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_get_config !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_get_adapter_attributes !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_get_port_attributes !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_get_port_statistics !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_get_dport_attributes !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_send_ct !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_send_els !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_send_scsi !Fdrivers/s390/scsi/zfcp_zh.c zfcp_zh_assert_fclun_zero

### Callbacks for Event Handling

To enable event delivery as required by bib.fchba, some callback functions of module `zfcp_hbaapi` must be called from module `zfcp`.

The following table gives an overview of the callbacks into module `zfcp_hbaapi` and their hooks in `zfcp`.

### Callbacks

Callback | Hook in module `zfcp`
`adapter_add` | `zfcp_fsf_exchange_config_data_handler`
`port_add` | `zfcp_port_enqueue`
`unit_add` | `zfcp_unit_enqueue`
`incoming_els` | `zfcp_fsf_incoming_els`
`link_down` | `zfcp_status_read_handler`, `zfcp_fsf_protstatus_eval`
`link_up` | `zfcp_status_read_handler`

## Working Draft. Information technology - Fibre Channel HBA API (FC-HBA)

The T11 Technical Committee