Message-based devices¶

Fusion message devices¶

u8 mpt_register(MPT_CALLBACK cbfunc, MPT_DRIVER_CLASS dclass, char *func_name)¶: Register protocol-specific main callback handler.

Parameters

MPT_CALLBACK cbfunc

callback function pointer

MPT_DRIVER_CLASS dclass

Protocol driver’s class (MPT_DRIVER_CLASS enum value)

char *func_name

call function’s name

This routine is called by a protocol-specific driver (SCSI host, LAN, SCSI target) to register its reply callback routine. Each protocol-specific driver must do this before it will be able to use any IOC resources, such as obtaining request frames.

NOTES

The SCSI protocol driver currently calls this routine thrice

in order to register separate callbacks; one for “normal” SCSI IO; one for MptScsiTaskMgmt requests; one for Scan/DV requests.

Returns u8 valued “handle” in the range (and S.O.D. order) {N,…,7,6,5,…,1} if successful. A return value of MPT_MAX_PROTOCOL_DRIVERS (including zero!) should be considered an error by the caller.

void mpt_deregister(u8 cb_idx)¶: Deregister a protocol drivers resources.

Parameters

u8 cb_idx

previously registered callback handle

Each protocol-specific driver should call this routine when its module is unloaded.

int mpt_event_register(u8 cb_idx, MPT_EVHANDLER ev_cbfunc)¶: Register protocol-specific event callback handler.

Parameters

u8 cb_idx

previously registered (via mpt_register) callback handle

MPT_EVHANDLER ev_cbfunc

callback function

This routine can be called by one or more protocol-specific drivers if/when they choose to be notified of MPT events.

Returns 0 for success.

void mpt_event_deregister(u8 cb_idx)¶: Deregister protocol-specific event callback handler

Parameters

u8 cb_idx

previously registered callback handle

Each protocol-specific driver should call this routine when it does not (or can no longer) handle events, or when its module is unloaded.

int mpt_reset_register(u8 cb_idx, MPT_RESETHANDLER reset_func)¶: Register protocol-specific IOC reset handler.

Parameters

u8 cb_idx

previously registered (via mpt_register) callback handle

MPT_RESETHANDLER reset_func

reset function

This routine can be called by one or more protocol-specific drivers if/when they choose to be notified of IOC resets.

Returns 0 for success.

void mpt_reset_deregister(u8 cb_idx)¶: Deregister protocol-specific IOC reset handler.

Parameters

u8 cb_idx

previously registered callback handle

Each protocol-specific driver should call this routine when it does not (or can no longer) handle IOC reset handling, or when its module is unloaded.

int mpt_device_driver_register(struct mpt_pci_driver * dd_cbfunc, u8 cb_idx)¶: Register device driver hooks

Parameters

struct mpt_pci_driver * dd_cbfunc: driver callbacks struct
u8 cb_idx: MPT protocol driver index

void mpt_device_driver_deregister(u8 cb_idx)¶: DeRegister device driver hooks

Parameters

u8 cb_idx: MPT protocol driver index

MPT_FRAME_HDR* mpt_get_msg_frame(u8 cb_idx, MPT_ADAPTER *ioc)¶: Obtain an MPT request frame from the pool

Parameters

u8 cb_idx

Handle of registered MPT protocol driver

MPT_ADAPTER *ioc

Pointer to MPT adapter structure

Obtain an MPT request frame from the pool (of 1024) that are allocated per MPT adapter.

Returns pointer to a MPT request frame or NULL if none are available or IOC is not active.

void mpt_put_msg_frame(u8 cb_idx, MPT_ADAPTER *ioc, MPT_FRAME_HDR *mf)¶: Send a protocol-specific MPT request frame to an IOC

Parameters

u8 cb_idx

Handle of registered MPT protocol driver

MPT_ADAPTER *ioc

Pointer to MPT adapter structure

MPT_FRAME_HDR *mf

Pointer to MPT request frame

This routine posts an MPT request frame to the request post FIFO of a specific MPT adapter.

void mpt_put_msg_frame_hi_pri(u8 cb_idx, MPT_ADAPTER *ioc, MPT_FRAME_HDR *mf)¶: Send a hi-pri protocol-specific MPT request frame

Parameters

u8 cb_idx

Handle of registered MPT protocol driver

MPT_ADAPTER *ioc

Pointer to MPT adapter structure

MPT_FRAME_HDR *mf

Pointer to MPT request frame

Send a protocol-specific MPT request frame to an IOC using hi-priority request queue.

This routine posts an MPT request frame to the request post FIFO of a specific MPT adapter.

void mpt_free_msg_frame(MPT_ADAPTER *ioc, MPT_FRAME_HDR *mf)¶: Place MPT request frame back on FreeQ.

Parameters

MPT_ADAPTER *ioc

Pointer to MPT adapter structure

MPT_FRAME_HDR *mf

Pointer to MPT request frame

This routine places a MPT request frame back on the MPT adapter’s FreeQ.

int mpt_send_handshake_request(u8 cb_idx, MPT_ADAPTER *ioc, int reqBytes, u32 *req, int sleepFlag)¶: Send MPT request via doorbell handshake method.

Parameters

u8 cb_idx

Handle of registered MPT protocol driver

MPT_ADAPTER *ioc

Pointer to MPT adapter structure

int reqBytes

Size of the request in bytes

u32 *req

Pointer to MPT request frame

int sleepFlag

Use schedule if CAN_SLEEP else use udelay.

This routine is used exclusively to send MptScsiTaskMgmt requests since they are required to be sent via doorbell handshake.

NOTE

It is the callers responsibility to byte-swap fields in the

request which are greater than 1 byte in size.

Returns 0 for success, non-zero for failure.

int mpt_verify_adapter(int iocid, MPT_ADAPTER **iocpp)¶: Given IOC identifier, set pointer to its adapter structure.

Parameters

int iocid

IOC unique identifier (integer)

MPT_ADAPTER **iocpp

Pointer to pointer to IOC adapter

Given a unique IOC identifier, set pointer to the associated MPT adapter structure.

Returns iocid and sets iocpp if iocid is found. Returns -1 if iocid is not found.

int mpt_attach(struct pci_dev *pdev, const struct pci_device_id *id)¶: Install a PCI intelligent MPT adapter.

Parameters

struct pci_dev *pdev

Pointer to pci_dev structure

const struct pci_device_id *id

PCI device ID information

This routine performs all the steps necessary to bring the IOC of a MPT adapter to a OPERATIONAL state. This includes registering memory regions, registering the interrupt, and allocating request and reply memory pools.

This routine also pre-fetches the LAN MAC address of a Fibre Channel MPT adapter.

Returns 0 for success, non-zero for failure.

TODO: Add support for polled controllers

void mpt_detach(struct pci_dev *pdev)¶: Remove a PCI intelligent MPT adapter.

Parameters

struct pci_dev *pdev: Pointer to pci_dev structure

int mpt_suspend(struct pci_dev *pdev, pm_message_t state)¶: Fusion MPT base driver suspend routine.

Parameters

struct pci_dev *pdev: Pointer to pci_dev structure
pm_message_t state: new state to enter

int mpt_resume(struct pci_dev *pdev)¶: Fusion MPT base driver resume routine.

Parameters

struct pci_dev *pdev: Pointer to pci_dev structure

u32 mpt_GetIocState(MPT_ADAPTER *ioc, int cooked)¶: Get the current state of a MPT adapter.

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

int cooked

Request raw or cooked IOC state

Returns all IOC Doorbell register bits if cooked==0, else just the Doorbell bits in MPI_IOC_STATE_MASK.

int mpt_alloc_fw_memory(MPT_ADAPTER *ioc, int size)¶: allocate firmware memory

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

int size

total FW bytes

If memory has already been allocated, the same (cached) value is returned.

Return 0 if successful, or non-zero for failure

void mpt_free_fw_memory(MPT_ADAPTER *ioc)¶: free firmware memory

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

If alt_img is NULL, delete from ioc structure. Else, delete a secondary image in same format.

int mptbase_sas_persist_operation(MPT_ADAPTER *ioc, u8 persist_opcode)¶: Perform operation on SAS Persistent Table

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

u8 persist_opcode

see below

MPI_SAS_OP_CLEAR_NOT_PRESENT	Free all persist TargetID mappings for devices not currently present.
MPI_SAS_OP_CLEAR_ALL_PERSISTENT	Clear al persist TargetID mappings

NOTE

Don’t use not this function during interrupt time.

Returns 0 for success, non-zero error

int mpt_raid_phys_disk_pg0(MPT_ADAPTER *ioc, u8 phys_disk_num, RaidPhysDiskPage0_t *phys_disk)¶: returns phys disk page zero

Parameters

MPT_ADAPTER *ioc: Pointer to a Adapter Structure
u8 phys_disk_num: io unit unique phys disk num generated by the ioc
RaidPhysDiskPage0_t *phys_disk: requested payload data returned

Return

0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed

int mpt_raid_phys_disk_get_num_paths(MPT_ADAPTER *ioc, u8 phys_disk_num)¶: returns number paths associated to this phys_num

Parameters

MPT_ADAPTER *ioc: Pointer to a Adapter Structure
u8 phys_disk_num: io unit unique phys disk num generated by the ioc

Return

returns number paths

int mpt_raid_phys_disk_pg1(MPT_ADAPTER *ioc, u8 phys_disk_num, RaidPhysDiskPage1_t *phys_disk)¶: returns phys disk page 1

Parameters

MPT_ADAPTER *ioc: Pointer to a Adapter Structure
u8 phys_disk_num: io unit unique phys disk num generated by the ioc
RaidPhysDiskPage1_t *phys_disk: requested payload data returned

Return

0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed

int mpt_findImVolumes(MPT_ADAPTER *ioc)¶: Identify IDs of hidden disks and RAID Volumes

Parameters

MPT_ADAPTER *ioc: Pointer to a Adapter Strucutre

Return

0 on success -EFAULT if read of config page header fails or data pointer not NULL -ENOMEM if pci_alloc failed

int mpt_config(MPT_ADAPTER *ioc, CONFIGPARMS *pCfg)¶: Generic function to issue config message

Parameters

MPT_ADAPTER *ioc: Pointer to an adapter structure
CONFIGPARMS *pCfg: Pointer to a configuration structure. Struct contains action, page address, direction, physical address and pointer to a configuration page header Page header is updated.

Returns 0 for success -EAGAIN if no msg frames currently available -EFAULT for non-successful reply or no reply (timeout)

void mpt_print_ioc_summary(MPT_ADAPTER *ioc, char *buffer, int *size, int len, int showlan)¶: Write ASCII summary of IOC to a buffer.

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

char *buffer

Pointer to buffer where IOC summary info should be written

int *size

Pointer to number of bytes we wrote (set by this routine)

int len

Offset at which to start writing in buffer

int showlan

Display LAN stuff?

This routine writes (english readable) ASCII text, which represents a summary of IOC information, to a buffer.

int mpt_set_taskmgmt_in_progress_flag(MPT_ADAPTER *ioc)¶: set flags associated with task management

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

Returns 0 for SUCCESS or -1 if FAILED.

If -1 is return, then it was not possible to set the flags

void mpt_clear_taskmgmt_in_progress_flag(MPT_ADAPTER *ioc)¶: clear flags associated with task management

Parameters

MPT_ADAPTER *ioc: Pointer to MPT_ADAPTER structure

void mpt_halt_firmware(MPT_ADAPTER *ioc)¶: Halts the firmware if it is operational and panic the kernel

Parameters

MPT_ADAPTER *ioc: Pointer to MPT_ADAPTER structure

int mpt_Soft_Hard_ResetHandler(MPT_ADAPTER *ioc, int sleepFlag)¶: Try less expensive reset

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

int sleepFlag

Indicates if sleep or schedule must be called.

Returns 0 for SUCCESS or -1 if FAILED. Try for softreset first, only if it fails go for expensive HardReset.

int mpt_HardResetHandler(MPT_ADAPTER *ioc, int sleepFlag)¶: Generic reset handler

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

int sleepFlag

Indicates if sleep or schedule must be called.

Issues SCSI Task Management call based on input arg values. If TaskMgmt fails, returns associated SCSI request.

Remark: _HardResetHandler can be invoked from an interrupt thread (timer) or a non-interrupt thread. In the former, must not call schedule().

Note

A return of -1 is a FATAL error case, as it means a

FW reload/initialization failed.

Returns 0 for SUCCESS or -1 if FAILED.

const char * mptscsih_info(struct Scsi_Host *SChost)¶: Return information about MPT adapter

Parameters

struct Scsi_Host *SChost

Pointer to Scsi_Host structure

(linux scsi_host_template.info routine)

Returns pointer to buffer where information was written.

int mptscsih_qcmd(struct scsi_cmnd *SCpnt)¶: Primary Fusion MPT SCSI initiator IO start routine.

Parameters

struct scsi_cmnd *SCpnt

Pointer to scsi_cmnd structure

(linux scsi_host_template.queuecommand routine) This is the primary SCSI IO start routine. Create a MPI SCSIIORequest from a linux scsi_cmnd request and send it to the IOC.

Returns 0. (rtn value discarded by linux scsi mid-layer)

int mptscsih_IssueTaskMgmt(MPT_SCSI_HOST *hd, u8 type, u8 channel, u8 id, u64 lun, int ctx2abort, ulong timeout)¶: Generic send Task Management function.

Parameters

MPT_SCSI_HOST *hd

Pointer to MPT_SCSI_HOST structure

u8 type

Task Management type

u8 channel

channel number for task management

u8 id

Logical Target ID for reset (if appropriate)

u64 lun

Logical Unit for reset (if appropriate)

int ctx2abort

Context for the task to be aborted (if appropriate)

ulong timeout

timeout for task management control

Remark: _HardResetHandler can be invoked from an interrupt thread (timer) or a non-interrupt thread. In the former, must not call schedule().

Not all fields are meaningfull for all task types.

Returns 0 for SUCCESS, or FAILED.

int mptscsih_abort(struct scsi_cmnd * SCpnt)¶: Abort linux scsi_cmnd routine, new_eh variant

Parameters

struct scsi_cmnd * SCpnt

Pointer to scsi_cmnd structure, IO to be aborted

(linux scsi_host_template.eh_abort_handler routine)

Returns SUCCESS or FAILED.

int mptscsih_dev_reset(struct scsi_cmnd * SCpnt)¶: Perform a SCSI TARGET_RESET! new_eh variant

Parameters

struct scsi_cmnd * SCpnt

Pointer to scsi_cmnd structure, IO which reset is due to

(linux scsi_host_template.eh_dev_reset_handler routine)

Returns SUCCESS or FAILED.

int mptscsih_bus_reset(struct scsi_cmnd * SCpnt)¶: Perform a SCSI BUS_RESET! new_eh variant

Parameters

struct scsi_cmnd * SCpnt

Pointer to scsi_cmnd structure, IO which reset is due to

(linux scsi_host_template.eh_bus_reset_handler routine)

Returns SUCCESS or FAILED.

int mptscsih_host_reset(struct scsi_cmnd *SCpnt)¶: Perform a SCSI host adapter RESET (new_eh variant)

Parameters

struct scsi_cmnd *SCpnt

Pointer to scsi_cmnd structure, IO which reset is due to

(linux scsi_host_template.eh_host_reset_handler routine)

Returns SUCCESS or FAILED.

int mptscsih_taskmgmt_complete(MPT_ADAPTER *ioc, MPT_FRAME_HDR *mf, MPT_FRAME_HDR *mr)¶: Registered with Fusion MPT base driver

Parameters

MPT_ADAPTER *ioc

Pointer to MPT_ADAPTER structure

MPT_FRAME_HDR *mf

Pointer to SCSI task mgmt request frame

MPT_FRAME_HDR *mr

Pointer to SCSI task mgmt reply frame

This routine is called from mptbase.c::mpt_interrupt() at the completion of any SCSI task management request. This routine is registered with the MPT (base) driver at driver load/init time via the mpt_register() API call.

Returns 1 indicating alloc’d request frame ptr should be freed.

struct scsi_cmnd * mptscsih_get_scsi_lookup(MPT_ADAPTER *ioc, int i)¶: retrieves scmd entry

Parameters

MPT_ADAPTER *ioc: Pointer to MPT_ADAPTER structure
int i: index into the array

Description

Returns the scsi_cmd pointer