aboutsummaryrefslogtreecommitdiffstats
path: root/drivers/scsi/lpfc/lpfc_init.c
diff options
context:
space:
mode:
authorJames Smart <James.Smart@Emulex.Com>2008-08-24 21:49:00 -0400
committerJames Bottomley <James.Bottomley@HansenPartnership.com>2008-10-13 09:28:53 -0400
commite59058c44025d71c9b7f260076a932935d3bba95 (patch)
tree36cd4b31ac3b130849c5ad4d2c0cef035a7389dd /drivers/scsi/lpfc/lpfc_init.c
parent4a27446f3e39b06c28d1c8e31d33a5340826ed5c (diff)
[SCSI] lpfc 8.2.8 : Add kernel-doc function headers
Signed-off-by: James Smart <james.smart@emulex.com> Signed-off-by: James Bottomley <James.Bottomley@HansenPartnership.com>
Diffstat (limited to 'drivers/scsi/lpfc/lpfc_init.c')
-rw-r--r--drivers/scsi/lpfc/lpfc_init.c575
1 files changed, 453 insertions, 122 deletions
diff --git a/drivers/scsi/lpfc/lpfc_init.c b/drivers/scsi/lpfc/lpfc_init.c
index d51a2a4b43eb..b9d553c2ac4d 100644
--- a/drivers/scsi/lpfc/lpfc_init.c
+++ b/drivers/scsi/lpfc/lpfc_init.c
@@ -52,17 +52,20 @@ static struct scsi_transport_template *lpfc_transport_template = NULL;
52static struct scsi_transport_template *lpfc_vport_transport_template = NULL; 52static struct scsi_transport_template *lpfc_vport_transport_template = NULL;
53static DEFINE_IDR(lpfc_hba_index); 53static DEFINE_IDR(lpfc_hba_index);
54 54
55/************************************************************************/ 55/**
56/* */ 56 * lpfc_config_port_prep: Perform lpfc initialization prior to config port.
57/* lpfc_config_port_prep */ 57 * @phba: pointer to lpfc hba data structure.
58/* This routine will do LPFC initialization prior to the */ 58 *
59/* CONFIG_PORT mailbox command. This will be initialized */ 59 * This routine will do LPFC initialization prior to issuing the CONFIG_PORT
60/* as a SLI layer callback routine. */ 60 * mailbox command. It retrieves the revision information from the HBA and
61/* This routine returns 0 on success or -ERESTART if it wants */ 61 * collects the Vital Product Data (VPD) about the HBA for preparing the
62/* the SLI layer to reset the HBA and try again. Any */ 62 * configuration of the HBA.
63/* other return value indicates an error. */ 63 *
64/* */ 64 * Return codes:
65/************************************************************************/ 65 * 0 - success.
66 * -ERESTART - requests the SLI layer to reset the HBA and try again.
67 * Any other value - indicates an error.
68 **/
66int 69int
67lpfc_config_port_prep(struct lpfc_hba *phba) 70lpfc_config_port_prep(struct lpfc_hba *phba)
68{ 71{
@@ -214,7 +217,16 @@ out_free_mbox:
214 return 0; 217 return 0;
215} 218}
216 219
217/* Completion handler for config async event mailbox command. */ 220/**
221 * lpfc_config_async_cmpl: Completion handler for config async event mbox cmd.
222 * @phba: pointer to lpfc hba data structure.
223 * @pmboxq: pointer to the driver internal queue element for mailbox command.
224 *
225 * This is the completion handler for driver's configuring asynchronous event
226 * mailbox command to the device. If the mailbox command returns successfully,
227 * it will set internal async event support flag to 1; otherwise, it will
228 * set internal async event support flag to 0.
229 **/
218static void 230static void
219lpfc_config_async_cmpl(struct lpfc_hba * phba, LPFC_MBOXQ_t * pmboxq) 231lpfc_config_async_cmpl(struct lpfc_hba * phba, LPFC_MBOXQ_t * pmboxq)
220{ 232{
@@ -226,16 +238,19 @@ lpfc_config_async_cmpl(struct lpfc_hba * phba, LPFC_MBOXQ_t * pmboxq)
226 return; 238 return;
227} 239}
228 240
229/************************************************************************/ 241/**
230/* */ 242 * lpfc_config_port_post: Perform lpfc initialization after config port.
231/* lpfc_config_port_post */ 243 * @phba: pointer to lpfc hba data structure.
232/* This routine will do LPFC initialization after the */ 244 *
233/* CONFIG_PORT mailbox command. This will be initialized */ 245 * This routine will do LPFC initialization after the CONFIG_PORT mailbox
234/* as a SLI layer callback routine. */ 246 * command call. It performs all internal resource and state setups on the
235/* This routine returns 0 on success. Any other return value */ 247 * port: post IOCB buffers, enable appropriate host interrupt attentions,
236/* indicates an error. */ 248 * ELS ring timers, etc.
237/* */ 249 *
238/************************************************************************/ 250 * Return codes
251 * 0 - success.
252 * Any other value - error.
253 **/
239int 254int
240lpfc_config_port_post(struct lpfc_hba *phba) 255lpfc_config_port_post(struct lpfc_hba *phba)
241{ 256{
@@ -450,16 +465,17 @@ lpfc_config_port_post(struct lpfc_hba *phba)
450 return (0); 465 return (0);
451} 466}
452 467
453/************************************************************************/ 468/**
454/* */ 469 * lpfc_hba_down_prep: Perform lpfc uninitialization prior to HBA reset.
455/* lpfc_hba_down_prep */ 470 * @phba: pointer to lpfc HBA data structure.
456/* This routine will do LPFC uninitialization before the */ 471 *
457/* HBA is reset when bringing down the SLI Layer. This will be */ 472 * This routine will do LPFC uninitialization before the HBA is reset when
458/* initialized as a SLI layer callback routine. */ 473 * bringing down the SLI Layer.
459/* This routine returns 0 on success. Any other return value */ 474 *
460/* indicates an error. */ 475 * Return codes
461/* */ 476 * 0 - success.
462/************************************************************************/ 477 * Any other value - error.
478 **/
463int 479int
464lpfc_hba_down_prep(struct lpfc_hba *phba) 480lpfc_hba_down_prep(struct lpfc_hba *phba)
465{ 481{
@@ -481,15 +497,17 @@ lpfc_hba_down_prep(struct lpfc_hba *phba)
481 return 0; 497 return 0;
482} 498}
483 499
484/************************************************************************/ 500/**
485/* */ 501 * lpfc_hba_down_post: Perform lpfc uninitialization after HBA reset.
486/* lpfc_hba_down_post */ 502 * @phba: pointer to lpfc HBA data structure.
487/* This routine will do uninitialization after the HBA is reset */ 503 *
488/* when bringing down the SLI Layer. */ 504 * This routine will do uninitialization after the HBA is reset when bring
489/* This routine returns 0 on success. Any other return value */ 505 * down the SLI Layer.
490/* indicates an error. */ 506 *
491/* */ 507 * Return codes
492/************************************************************************/ 508 * 0 - sucess.
509 * Any other value - error.
510 **/
493int 511int
494lpfc_hba_down_post(struct lpfc_hba *phba) 512lpfc_hba_down_post(struct lpfc_hba *phba)
495{ 513{
@@ -548,7 +566,18 @@ lpfc_hba_down_post(struct lpfc_hba *phba)
548 return 0; 566 return 0;
549} 567}
550 568
551/* HBA heart beat timeout handler */ 569/**
570 * lpfc_hb_timeout: The HBA-timer timeout handler.
571 * @ptr: unsigned long holds the pointer to lpfc hba data structure.
572 *
573 * This is the HBA-timer timeout handler registered to the lpfc driver. When
574 * this timer fires, a HBA timeout event shall be posted to the lpfc driver
575 * work-port-events bitmap and the worker thread is notified. This timeout
576 * event will be used by the worker thread to invoke the actual timeout
577 * handler routine, lpfc_hb_timeout_handler. Any periodical operations will
578 * be performed in the timeout handler and the HBA timeout event bit shall
579 * be cleared by the worker thread after it has taken the event bitmap out.
580 **/
552static void 581static void
553lpfc_hb_timeout(unsigned long ptr) 582lpfc_hb_timeout(unsigned long ptr)
554{ 583{
@@ -568,6 +597,22 @@ lpfc_hb_timeout(unsigned long ptr)
568 return; 597 return;
569} 598}
570 599
600/**
601 * lpfc_hb_mbox_cmpl: The lpfc heart-beat mailbox command callback function.
602 * @phba: pointer to lpfc hba data structure.
603 * @pmboxq: pointer to the driver internal queue element for mailbox command.
604 *
605 * This is the callback function to the lpfc heart-beat mailbox command.
606 * If configured, the lpfc driver issues the heart-beat mailbox command to
607 * the HBA every LPFC_HB_MBOX_INTERVAL (current 5) seconds. At the time the
608 * heart-beat mailbox command is issued, the driver shall set up heart-beat
609 * timeout timer to LPFC_HB_MBOX_TIMEOUT (current 30) seconds and marks
610 * heart-beat outstanding state. Once the mailbox command comes back and
611 * no error conditions detected, the heart-beat mailbox command timer is
612 * reset to LPFC_HB_MBOX_INTERVAL seconds and the heart-beat outstanding
613 * state is cleared for the next heart-beat. If the timer expired with the
614 * heart-beat outstanding state set, the driver will put the HBA offline.
615 **/
571static void 616static void
572lpfc_hb_mbox_cmpl(struct lpfc_hba * phba, LPFC_MBOXQ_t * pmboxq) 617lpfc_hb_mbox_cmpl(struct lpfc_hba * phba, LPFC_MBOXQ_t * pmboxq)
573{ 618{
@@ -586,6 +631,22 @@ lpfc_hb_mbox_cmpl(struct lpfc_hba * phba, LPFC_MBOXQ_t * pmboxq)
586 return; 631 return;
587} 632}
588 633
634/**
635 * lpfc_hb_timeout_handler: The HBA-timer timeout handler.
636 * @phba: pointer to lpfc hba data structure.
637 *
638 * This is the actual HBA-timer timeout handler to be invoked by the worker
639 * thread whenever the HBA timer fired and HBA-timeout event posted. This
640 * handler performs any periodic operations needed for the device. If such
641 * periodic event has already been attended to either in the interrupt handler
642 * or by processing slow-ring or fast-ring events within the HBA-timer
643 * timeout window (LPFC_HB_MBOX_INTERVAL), this handler just simply resets
644 * the timer for the next timeout period. If lpfc heart-beat mailbox command
645 * is configured and there is no heart-beat mailbox command outstanding, a
646 * heart-beat mailbox is issued and timer set properly. Otherwise, if there
647 * has been a heart-beat mailbox command outstanding, the HBA shall be put
648 * to offline.
649 **/
589void 650void
590lpfc_hb_timeout_handler(struct lpfc_hba *phba) 651lpfc_hb_timeout_handler(struct lpfc_hba *phba)
591{ 652{
@@ -684,6 +745,13 @@ lpfc_hb_timeout_handler(struct lpfc_hba *phba)
684 } 745 }
685} 746}
686 747
748/**
749 * lpfc_offline_eratt: Bring lpfc offline on hardware error attention.
750 * @phba: pointer to lpfc hba data structure.
751 *
752 * This routine is called to bring the HBA offline when HBA hardware error
753 * other than Port Error 6 has been detected.
754 **/
687static void 755static void
688lpfc_offline_eratt(struct lpfc_hba *phba) 756lpfc_offline_eratt(struct lpfc_hba *phba)
689{ 757{
@@ -704,14 +772,16 @@ lpfc_offline_eratt(struct lpfc_hba *phba)
704 return; 772 return;
705} 773}
706 774
707/************************************************************************/ 775/**
708/* */ 776 * lpfc_handle_eratt: The HBA hardware error handler.
709/* lpfc_handle_eratt */ 777 * @phba: pointer to lpfc hba data structure.
710/* This routine will handle processing a Host Attention */ 778 *
711/* Error Status event. This will be initialized */ 779 * This routine is invoked to handle the following HBA hardware error
712/* as a SLI layer callback routine. */ 780 * conditions:
713/* */ 781 * 1 - HBA error attention interrupt
714/************************************************************************/ 782 * 2 - DMA ring index out of range
783 * 3 - Mailbox command came back as unknown
784 **/
715void 785void
716lpfc_handle_eratt(struct lpfc_hba *phba) 786lpfc_handle_eratt(struct lpfc_hba *phba)
717{ 787{
@@ -810,14 +880,13 @@ lpfc_handle_eratt(struct lpfc_hba *phba)
810 } 880 }
811} 881}
812 882
813/************************************************************************/ 883/**
814/* */ 884 * lpfc_handle_latt: The HBA link event handler.
815/* lpfc_handle_latt */ 885 * @phba: pointer to lpfc hba data structure.
816/* This routine will handle processing a Host Attention */ 886 *
817/* Link Status event. This will be initialized */ 887 * This routine is invoked from the worker thread to handle a HBA host
818/* as a SLI layer callback routine. */ 888 * attention link event.
819/* */ 889 **/
820/************************************************************************/
821void 890void
822lpfc_handle_latt(struct lpfc_hba *phba) 891lpfc_handle_latt(struct lpfc_hba *phba)
823{ 892{
@@ -898,12 +967,20 @@ lpfc_handle_latt_err_exit:
898 return; 967 return;
899} 968}
900 969
901/************************************************************************/ 970/**
902/* */ 971 * lpfc_parse_vpd: Parse VPD (Vital Product Data).
903/* lpfc_parse_vpd */ 972 * @phba: pointer to lpfc hba data structure.
904/* This routine will parse the VPD data */ 973 * @vpd: pointer to the vital product data.
905/* */ 974 * @len: length of the vital product data in bytes.
906/************************************************************************/ 975 *
976 * This routine parses the Vital Product Data (VPD). The VPD is treated as
977 * an array of characters. In this routine, the ModelName, ProgramType, and
978 * ModelDesc, etc. fields of the phba data structure will be populated.
979 *
980 * Return codes
981 * 0 - pointer to the VPD passed in is NULL
982 * 1 - success
983 **/
907static int 984static int
908lpfc_parse_vpd(struct lpfc_hba *phba, uint8_t *vpd, int len) 985lpfc_parse_vpd(struct lpfc_hba *phba, uint8_t *vpd, int len)
909{ 986{
@@ -1040,6 +1117,18 @@ lpfc_parse_vpd(struct lpfc_hba *phba, uint8_t *vpd, int len)
1040 return(1); 1117 return(1);
1041} 1118}
1042 1119
1120/**
1121 * lpfc_get_hba_model_desc: Retrieve HBA device model name and description.
1122 * @phba: pointer to lpfc hba data structure.
1123 * @mdp: pointer to the data structure to hold the derived model name.
1124 * @descp: pointer to the data structure to hold the derived description.
1125 *
1126 * This routine retrieves HBA's description based on its registered PCI device
1127 * ID. The @descp passed into this function points to an array of 256 chars. It
1128 * shall be returned with the model name, maximum speed, and the host bus type.
1129 * The @mdp passed into this function points to an array of 80 chars. When the
1130 * function returns, the @mdp will be filled with the model name.
1131 **/
1043static void 1132static void
1044lpfc_get_hba_model_desc(struct lpfc_hba *phba, uint8_t *mdp, uint8_t *descp) 1133lpfc_get_hba_model_desc(struct lpfc_hba *phba, uint8_t *mdp, uint8_t *descp)
1045{ 1134{
@@ -1190,14 +1279,18 @@ lpfc_get_hba_model_desc(struct lpfc_hba *phba, uint8_t *mdp, uint8_t *descp)
1190 m.name, m.max_speed, m.bus); 1279 m.name, m.max_speed, m.bus);
1191} 1280}
1192 1281
1193/**************************************************/ 1282/**
1194/* lpfc_post_buffer */ 1283 * lpfc_post_buffer: Post IOCB(s) with DMA buffer descriptor(s) to a IOCB ring.
1195/* */ 1284 * @phba: pointer to lpfc hba data structure.
1196/* This routine will post count buffers to the */ 1285 * @pring: pointer to a IOCB ring.
1197/* ring with the QUE_RING_BUF_CN command. This */ 1286 * @cnt: the number of IOCBs to be posted to the IOCB ring.
1198/* allows 3 buffers / command to be posted. */ 1287 *
1199/* Returns the number of buffers NOT posted. */ 1288 * This routine posts a given number of IOCBs with the associated DMA buffer
1200/**************************************************/ 1289 * descriptors specified by the cnt argument to the given IOCB ring.
1290 *
1291 * Return codes
1292 * The number of IOCBs NOT able to be posted to the IOCB ring.
1293 **/
1201int 1294int
1202lpfc_post_buffer(struct lpfc_hba *phba, struct lpfc_sli_ring *pring, int cnt) 1295lpfc_post_buffer(struct lpfc_hba *phba, struct lpfc_sli_ring *pring, int cnt)
1203{ 1296{
@@ -1287,12 +1380,17 @@ lpfc_post_buffer(struct lpfc_hba *phba, struct lpfc_sli_ring *pring, int cnt)
1287 return 0; 1380 return 0;
1288} 1381}
1289 1382
1290/************************************************************************/ 1383/**
1291/* */ 1384 * lpfc_post_rcv_buf: Post the initial receive IOCB buffers to ELS ring.
1292/* lpfc_post_rcv_buf */ 1385 * @phba: pointer to lpfc hba data structure.
1293/* This routine post initial rcv buffers to the configured rings */ 1386 *
1294/* */ 1387 * This routine posts initial receive IOCB buffers to the ELS ring. The
1295/************************************************************************/ 1388 * current number of initial IOCB buffers specified by LPFC_BUF_RING0 is
1389 * set to 64 IOCBs.
1390 *
1391 * Return codes
1392 * 0 - success (currently always success)
1393 **/
1296static int 1394static int
1297lpfc_post_rcv_buf(struct lpfc_hba *phba) 1395lpfc_post_rcv_buf(struct lpfc_hba *phba)
1298{ 1396{
@@ -1307,11 +1405,13 @@ lpfc_post_rcv_buf(struct lpfc_hba *phba)
1307 1405
1308#define S(N,V) (((V)<<(N))|((V)>>(32-(N)))) 1406#define S(N,V) (((V)<<(N))|((V)>>(32-(N))))
1309 1407
1310/************************************************************************/ 1408/**
1311/* */ 1409 * lpfc_sha_init: Set up initial array of hash table entries.
1312/* lpfc_sha_init */ 1410 * @HashResultPointer: pointer to an array as hash table.
1313/* */ 1411 *
1314/************************************************************************/ 1412 * This routine sets up the initial values to the array of hash table entries
1413 * for the LC HBAs.
1414 **/
1315static void 1415static void
1316lpfc_sha_init(uint32_t * HashResultPointer) 1416lpfc_sha_init(uint32_t * HashResultPointer)
1317{ 1417{
@@ -1322,11 +1422,16 @@ lpfc_sha_init(uint32_t * HashResultPointer)
1322 HashResultPointer[4] = 0xC3D2E1F0; 1422 HashResultPointer[4] = 0xC3D2E1F0;
1323} 1423}
1324 1424
1325/************************************************************************/ 1425/**
1326/* */ 1426 * lpfc_sha_iterate: Iterate initial hash table with the working hash table.
1327/* lpfc_sha_iterate */ 1427 * @HashResultPointer: pointer to an initial/result hash table.
1328/* */ 1428 * @HashWorkingPointer: pointer to an working hash table.
1329/************************************************************************/ 1429 *
1430 * This routine iterates an initial hash table pointed by @HashResultPointer
1431 * with the values from the working hash table pointeed by @HashWorkingPointer.
1432 * The results are putting back to the initial hash table, returned through
1433 * the @HashResultPointer as the result hash table.
1434 **/
1330static void 1435static void
1331lpfc_sha_iterate(uint32_t * HashResultPointer, uint32_t * HashWorkingPointer) 1436lpfc_sha_iterate(uint32_t * HashResultPointer, uint32_t * HashWorkingPointer)
1332{ 1437{
@@ -1374,22 +1479,29 @@ lpfc_sha_iterate(uint32_t * HashResultPointer, uint32_t * HashWorkingPointer)
1374 1479
1375} 1480}
1376 1481
1377/************************************************************************/ 1482/**
1378/* */ 1483 * lpfc_challenge_key: Create challenge key based on WWPN of the HBA.
1379/* lpfc_challenge_key */ 1484 * @RandomChallenge: pointer to the entry of host challenge random number array.
1380/* */ 1485 * @HashWorking: pointer to the entry of the working hash array.
1381/************************************************************************/ 1486 *
1487 * This routine calculates the working hash array referred by @HashWorking
1488 * from the challenge random numbers associated with the host, referred by
1489 * @RandomChallenge. The result is put into the entry of the working hash
1490 * array and returned by reference through @HashWorking.
1491 **/
1382static void 1492static void
1383lpfc_challenge_key(uint32_t * RandomChallenge, uint32_t * HashWorking) 1493lpfc_challenge_key(uint32_t * RandomChallenge, uint32_t * HashWorking)
1384{ 1494{
1385 *HashWorking = (*RandomChallenge ^ *HashWorking); 1495 *HashWorking = (*RandomChallenge ^ *HashWorking);
1386} 1496}
1387 1497
1388/************************************************************************/ 1498/**
1389/* */ 1499 * lpfc_hba_init: Perform special handling for LC HBA initialization.
1390/* lpfc_hba_init */ 1500 * @phba: pointer to lpfc hba data structure.
1391/* */ 1501 * @hbainit: pointer to an array of unsigned 32-bit integers.
1392/************************************************************************/ 1502 *
1503 * This routine performs the special handling for LC HBA initialization.
1504 **/
1393void 1505void
1394lpfc_hba_init(struct lpfc_hba *phba, uint32_t *hbainit) 1506lpfc_hba_init(struct lpfc_hba *phba, uint32_t *hbainit)
1395{ 1507{
@@ -1412,6 +1524,15 @@ lpfc_hba_init(struct lpfc_hba *phba, uint32_t *hbainit)
1412 kfree(HashWorking); 1524 kfree(HashWorking);
1413} 1525}
1414 1526
1527/**
1528 * lpfc_cleanup: Performs vport cleanups before deleting a vport.
1529 * @vport: pointer to a virtual N_Port data structure.
1530 *
1531 * This routine performs the necessary cleanups before deleting the @vport.
1532 * It invokes the discovery state machine to perform necessary state
1533 * transitions and to release the ndlps associated with the @vport. Note,
1534 * the physical port is treated as @vport 0.
1535 **/
1415void 1536void
1416lpfc_cleanup(struct lpfc_vport *vport) 1537lpfc_cleanup(struct lpfc_vport *vport)
1417{ 1538{
@@ -1498,6 +1619,14 @@ lpfc_cleanup(struct lpfc_vport *vport)
1498 return; 1619 return;
1499} 1620}
1500 1621
1622/**
1623 * lpfc_stop_vport_timers: Stop all the timers associated with a vport.
1624 * @vport: pointer to a virtual N_Port data structure.
1625 *
1626 * This routine stops all the timers associated with a @vport. This function
1627 * is invoked before disabling or deleting a @vport. Note that the physical
1628 * port is treated as @vport 0.
1629 **/
1501void 1630void
1502lpfc_stop_vport_timers(struct lpfc_vport *vport) 1631lpfc_stop_vport_timers(struct lpfc_vport *vport)
1503{ 1632{
@@ -1507,6 +1636,13 @@ lpfc_stop_vport_timers(struct lpfc_vport *vport)
1507 return; 1636 return;
1508} 1637}
1509 1638
1639/**
1640 * lpfc_stop_phba_timers: Stop all the timers associated with an HBA.
1641 * @phba: pointer to lpfc hba data structure.
1642 *
1643 * This routine stops all the timers associated with a HBA. This function is
1644 * invoked before either putting a HBA offline or unloading the driver.
1645 **/
1510static void 1646static void
1511lpfc_stop_phba_timers(struct lpfc_hba *phba) 1647lpfc_stop_phba_timers(struct lpfc_hba *phba)
1512{ 1648{
@@ -1519,6 +1655,16 @@ lpfc_stop_phba_timers(struct lpfc_hba *phba)
1519 return; 1655 return;
1520} 1656}
1521 1657
1658/**
1659 * lpfc_block_mgmt_io: Mark a HBA's management interface as blocked.
1660 * @phba: pointer to lpfc hba data structure.
1661 *
1662 * This routine marks a HBA's management interface as blocked. Once the HBA's
1663 * management interface is marked as blocked, all the user space access to
1664 * the HBA, whether they are from sysfs interface or libdfc interface will
1665 * all be blocked. The HBA is set to block the management interface when the
1666 * driver prepares the HBA interface for online or offline.
1667 **/
1522static void 1668static void
1523lpfc_block_mgmt_io(struct lpfc_hba * phba) 1669lpfc_block_mgmt_io(struct lpfc_hba * phba)
1524{ 1670{
@@ -1529,6 +1675,18 @@ lpfc_block_mgmt_io(struct lpfc_hba * phba)
1529 spin_unlock_irqrestore(&phba->hbalock, iflag); 1675 spin_unlock_irqrestore(&phba->hbalock, iflag);
1530} 1676}
1531 1677
1678/**
1679 * lpfc_online: Initialize and bring a HBA online.
1680 * @phba: pointer to lpfc hba data structure.
1681 *
1682 * This routine initializes the HBA and brings a HBA online. During this
1683 * process, the management interface is blocked to prevent user space access
1684 * to the HBA interfering with the driver initialization.
1685 *
1686 * Return codes
1687 * 0 - successful
1688 * 1 - failed
1689 **/
1532int 1690int
1533lpfc_online(struct lpfc_hba *phba) 1691lpfc_online(struct lpfc_hba *phba)
1534{ 1692{
@@ -1574,6 +1732,17 @@ lpfc_online(struct lpfc_hba *phba)
1574 return 0; 1732 return 0;
1575} 1733}
1576 1734
1735/**
1736 * lpfc_unblock_mgmt_io: Mark a HBA's management interface to be not blocked.
1737 * @phba: pointer to lpfc hba data structure.
1738 *
1739 * This routine marks a HBA's management interface as not blocked. Once the
1740 * HBA's management interface is marked as not blocked, all the user space
1741 * access to the HBA, whether they are from sysfs interface or libdfc
1742 * interface will be allowed. The HBA is set to block the management interface
1743 * when the driver prepares the HBA interface for online or offline and then
1744 * set to unblock the management interface afterwards.
1745 **/
1577void 1746void
1578lpfc_unblock_mgmt_io(struct lpfc_hba * phba) 1747lpfc_unblock_mgmt_io(struct lpfc_hba * phba)
1579{ 1748{
@@ -1584,6 +1753,14 @@ lpfc_unblock_mgmt_io(struct lpfc_hba * phba)
1584 spin_unlock_irqrestore(&phba->hbalock, iflag); 1753 spin_unlock_irqrestore(&phba->hbalock, iflag);
1585} 1754}
1586 1755
1756/**
1757 * lpfc_offline_prep: Prepare a HBA to be brought offline.
1758 * @phba: pointer to lpfc hba data structure.
1759 *
1760 * This routine is invoked to prepare a HBA to be brought offline. It performs
1761 * unregistration login to all the nodes on all vports and flushes the mailbox
1762 * queue to make it ready to be brought offline.
1763 **/
1587void 1764void
1588lpfc_offline_prep(struct lpfc_hba * phba) 1765lpfc_offline_prep(struct lpfc_hba * phba)
1589{ 1766{
@@ -1633,6 +1810,14 @@ lpfc_offline_prep(struct lpfc_hba * phba)
1633 lpfc_sli_flush_mbox_queue(phba); 1810 lpfc_sli_flush_mbox_queue(phba);
1634} 1811}
1635 1812
1813/**
1814 * lpfc_offline: Bring a HBA offline.
1815 * @phba: pointer to lpfc hba data structure.
1816 *
1817 * This routine actually brings a HBA offline. It stops all the timers
1818 * associated with the HBA, brings down the SLI layer, and eventually
1819 * marks the HBA as in offline state for the upper layer protocol.
1820 **/
1636void 1821void
1637lpfc_offline(struct lpfc_hba *phba) 1822lpfc_offline(struct lpfc_hba *phba)
1638{ 1823{
@@ -1670,12 +1855,17 @@ lpfc_offline(struct lpfc_hba *phba)
1670 lpfc_destroy_vport_work_array(phba, vports); 1855 lpfc_destroy_vport_work_array(phba, vports);
1671} 1856}
1672 1857
1673/****************************************************************************** 1858/**
1674* Function name: lpfc_scsi_free 1859 * lpfc_scsi_free: Free all the SCSI buffers and IOCBs from driver lists.
1675* 1860 * @phba: pointer to lpfc hba data structure.
1676* Description: Called from lpfc_pci_remove_one free internal driver resources 1861 *
1677* 1862 * This routine is to free all the SCSI buffers and IOCBs from the driver
1678******************************************************************************/ 1863 * list back to kernel. It is called from lpfc_pci_remove_one to free
1864 * the internal resources before the device is removed from the system.
1865 *
1866 * Return codes
1867 * 0 - successful (for now, it always returns 0)
1868 **/
1679static int 1869static int
1680lpfc_scsi_free(struct lpfc_hba *phba) 1870lpfc_scsi_free(struct lpfc_hba *phba)
1681{ 1871{
@@ -1704,6 +1894,22 @@ lpfc_scsi_free(struct lpfc_hba *phba)
1704 return 0; 1894 return 0;
1705} 1895}
1706 1896
1897/**
1898 * lpfc_create_port: Create an FC port.
1899 * @phba: pointer to lpfc hba data structure.
1900 * @instance: a unique integer ID to this FC port.
1901 * @dev: pointer to the device data structure.
1902 *
1903 * This routine creates a FC port for the upper layer protocol. The FC port
1904 * can be created on top of either a physical port or a virtual port provided
1905 * by the HBA. This routine also allocates a SCSI host data structure (shost)
1906 * and associates the FC port created before adding the shost into the SCSI
1907 * layer.
1908 *
1909 * Return codes
1910 * @vport - pointer to the virtual N_Port data structure.
1911 * NULL - port create failed.
1912 **/
1707struct lpfc_vport * 1913struct lpfc_vport *
1708lpfc_create_port(struct lpfc_hba *phba, int instance, struct device *dev) 1914lpfc_create_port(struct lpfc_hba *phba, int instance, struct device *dev)
1709{ 1915{
@@ -1777,6 +1983,13 @@ out:
1777 return NULL; 1983 return NULL;
1778} 1984}
1779 1985
1986/**
1987 * destroy_port: Destroy an FC port.
1988 * @vport: pointer to an lpfc virtual N_Port data structure.
1989 *
1990 * This routine destroys a FC port from the upper layer protocol. All the
1991 * resources associated with the port are released.
1992 **/
1780void 1993void
1781destroy_port(struct lpfc_vport *vport) 1994destroy_port(struct lpfc_vport *vport)
1782{ 1995{
@@ -1797,6 +2010,16 @@ destroy_port(struct lpfc_vport *vport)
1797 return; 2010 return;
1798} 2011}
1799 2012
2013/**
2014 * lpfc_get_instance: Get a unique integer ID.
2015 *
2016 * This routine allocates a unique integer ID from lpfc_hba_index pool. It
2017 * uses the kernel idr facility to perform the task.
2018 *
2019 * Return codes:
2020 * instance - a unique integer ID allocated as the new instance.
2021 * -1 - lpfc get instance failed.
2022 **/
1800int 2023int
1801lpfc_get_instance(void) 2024lpfc_get_instance(void)
1802{ 2025{
@@ -1810,11 +2033,21 @@ lpfc_get_instance(void)
1810 return instance; 2033 return instance;
1811} 2034}
1812 2035
1813/* 2036/**
1814 * Note: there is no scan_start function as adapter initialization 2037 * lpfc_scan_finished: method for SCSI layer to detect whether scan is done.
1815 * will have asynchronously kicked off the link initialization. 2038 * @shost: pointer to SCSI host data structure.
1816 */ 2039 * @time: elapsed time of the scan in jiffies.
1817 2040 *
2041 * This routine is called by the SCSI layer with a SCSI host to determine
2042 * whether the scan host is finished.
2043 *
2044 * Note: there is no scan_start function as adapter initialization will have
2045 * asynchronously kicked off the link initialization.
2046 *
2047 * Return codes
2048 * 0 - SCSI host scan is not over yet.
2049 * 1 - SCSI host scan is over.
2050 **/
1818int lpfc_scan_finished(struct Scsi_Host *shost, unsigned long time) 2051int lpfc_scan_finished(struct Scsi_Host *shost, unsigned long time)
1819{ 2052{
1820 struct lpfc_vport *vport = (struct lpfc_vport *) shost->hostdata; 2053 struct lpfc_vport *vport = (struct lpfc_vport *) shost->hostdata;
@@ -1858,6 +2091,13 @@ finished:
1858 return stat; 2091 return stat;
1859} 2092}
1860 2093
2094/**
2095 * lpfc_host_attrib_init: Initialize SCSI host attributes on a FC port.
2096 * @shost: pointer to SCSI host data structure.
2097 *
2098 * This routine initializes a given SCSI host attributes on a FC port. The
2099 * SCSI host can be either on top of a physical port or a virtual port.
2100 **/
1861void lpfc_host_attrib_init(struct Scsi_Host *shost) 2101void lpfc_host_attrib_init(struct Scsi_Host *shost)
1862{ 2102{
1863 struct lpfc_vport *vport = (struct lpfc_vport *) shost->hostdata; 2103 struct lpfc_vport *vport = (struct lpfc_vport *) shost->hostdata;
@@ -1906,6 +2146,25 @@ void lpfc_host_attrib_init(struct Scsi_Host *shost)
1906 spin_unlock_irq(shost->host_lock); 2146 spin_unlock_irq(shost->host_lock);
1907} 2147}
1908 2148
2149/**
2150 * lpfc_enable_msix: Enable MSI-X interrupt mode.
2151 * @phba: pointer to lpfc hba data structure.
2152 *
2153 * This routine is invoked to enable the MSI-X interrupt vectors. The kernel
2154 * function pci_enable_msix() is called to enable the MSI-X vectors. Note that
2155 * pci_enable_msix(), once invoked, enables either all or nothing, depending
2156 * on the current availability of PCI vector resources. The device driver is
2157 * responsible for calling the individual request_irq() to register each MSI-X
2158 * vector with a interrupt handler, which is done in this function. Note that
2159 * later when device is unloading, the driver should always call free_irq()
2160 * on all MSI-X vectors it has done request_irq() on before calling
2161 * pci_disable_msix(). Failure to do so results in a BUG_ON() and a device
2162 * will be left with MSI-X enabled and leaks its vectors.
2163 *
2164 * Return codes
2165 * 0 - sucessful
2166 * other values - error
2167 **/
1909static int 2168static int
1910lpfc_enable_msix(struct lpfc_hba *phba) 2169lpfc_enable_msix(struct lpfc_hba *phba)
1911{ 2170{
@@ -1935,6 +2194,13 @@ lpfc_enable_msix(struct lpfc_hba *phba)
1935 return error; 2194 return error;
1936} 2195}
1937 2196
2197/**
2198 * lpfc_disable_msix: Disable MSI-X interrupt mode.
2199 * @phba: pointer to lpfc hba data structure.
2200 *
2201 * This routine is invoked to release the MSI-X vectors and then disable the
2202 * MSI-X interrupt mode.
2203 **/
1938static void 2204static void
1939lpfc_disable_msix(struct lpfc_hba *phba) 2205lpfc_disable_msix(struct lpfc_hba *phba)
1940{ 2206{
@@ -1942,6 +2208,23 @@ lpfc_disable_msix(struct lpfc_hba *phba)
1942 pci_disable_msix(phba->pcidev); 2208 pci_disable_msix(phba->pcidev);
1943} 2209}
1944 2210
2211/**
2212 * lpfc_pci_probe_one: lpfc PCI probe func to register device to PCI subsystem.
2213 * @pdev: pointer to PCI device
2214 * @pid: pointer to PCI device identifier
2215 *
2216 * This routine is to be registered to the kernel's PCI subsystem. When an
2217 * Emulex HBA is presented in PCI bus, the kernel PCI subsystem looks at
2218 * PCI device-specific information of the device and driver to see if the
2219 * driver state that it can support this kind of device. If the match is
2220 * successful, the driver core invokes this routine. If this routine
2221 * determines it can claim the HBA, it does all the initialization that it
2222 * needs to do to handle the HBA properly.
2223 *
2224 * Return code
2225 * 0 - driver can claim the device
2226 * negative value - driver can not claim the device
2227 **/
1945static int __devinit 2228static int __devinit
1946lpfc_pci_probe_one(struct pci_dev *pdev, const struct pci_device_id *pid) 2229lpfc_pci_probe_one(struct pci_dev *pdev, const struct pci_device_id *pid)
1947{ 2230{
@@ -2262,6 +2545,14 @@ out:
2262 return error; 2545 return error;
2263} 2546}
2264 2547
2548/**
2549 * lpfc_pci_remove_one: lpfc PCI func to unregister device from PCI subsystem.
2550 * @pdev: pointer to PCI device
2551 *
2552 * This routine is to be registered to the kernel's PCI subsystem. When an
2553 * Emulex HBA is removed from PCI bus. It perform all the necessary cleanup
2554 * for the HBA device to be removed from the PCI subsystem properly.
2555 **/
2265static void __devexit 2556static void __devexit
2266lpfc_pci_remove_one(struct pci_dev *pdev) 2557lpfc_pci_remove_one(struct pci_dev *pdev)
2267{ 2558{
@@ -2336,13 +2627,21 @@ lpfc_pci_remove_one(struct pci_dev *pdev)
2336} 2627}
2337 2628
2338/** 2629/**
2339 * lpfc_io_error_detected - called when PCI error is detected 2630 * lpfc_io_error_detected: Driver method for handling PCI I/O error detected.
2340 * @pdev: Pointer to PCI device 2631 * @pdev: pointer to PCI device.
2341 * @state: The current pci conneection state 2632 * @state: the current PCI connection state.
2342 * 2633 *
2343 * This function is called after a PCI bus error affecting 2634 * This routine is registered to the PCI subsystem for error handling. This
2344 * this device has been detected. 2635 * function is called by the PCI subsystem after a PCI bus error affecting
2345 */ 2636 * this device has been detected. When this function is invoked, it will
2637 * need to stop all the I/Os and interrupt(s) to the device. Once that is
2638 * done, it will return PCI_ERS_RESULT_NEED_RESET for the PCI subsystem to
2639 * perform proper recovery as desired.
2640 *
2641 * Return codes
2642 * PCI_ERS_RESULT_NEED_RESET - need to reset before recovery
2643 * PCI_ERS_RESULT_DISCONNECT - device could not be recovered
2644 **/
2346static pci_ers_result_t lpfc_io_error_detected(struct pci_dev *pdev, 2645static pci_ers_result_t lpfc_io_error_detected(struct pci_dev *pdev,
2347 pci_channel_state_t state) 2646 pci_channel_state_t state)
2348{ 2647{
@@ -2376,10 +2675,21 @@ static pci_ers_result_t lpfc_io_error_detected(struct pci_dev *pdev,
2376} 2675}
2377 2676
2378/** 2677/**
2379 * lpfc_io_slot_reset - called after the pci bus has been reset. 2678 * lpfc_io_slot_reset: Restart a PCI device from scratch.
2380 * @pdev: Pointer to PCI device 2679 * @pdev: pointer to PCI device.
2680 *
2681 * This routine is registered to the PCI subsystem for error handling. This is
2682 * called after PCI bus has been reset to restart the PCI card from scratch,
2683 * as if from a cold-boot. During the PCI subsystem error recovery, after the
2684 * driver returns PCI_ERS_RESULT_NEED_RESET, the PCI subsystem will perform
2685 * proper error recovery and then call this routine before calling the .resume
2686 * method to recover the device. This function will initialize the HBA device,
2687 * enable the interrupt, but it will just put the HBA to offline state without
2688 * passing any I/O traffic.
2381 * 2689 *
2382 * Restart the card from scratch, as if from a cold-boot. 2690 * Return codes
2691 * PCI_ERS_RESULT_RECOVERED - the device has been recovered
2692 * PCI_ERS_RESULT_DISCONNECT - device could not be recovered
2383 */ 2693 */
2384static pci_ers_result_t lpfc_io_slot_reset(struct pci_dev *pdev) 2694static pci_ers_result_t lpfc_io_slot_reset(struct pci_dev *pdev)
2385{ 2695{
@@ -2440,11 +2750,13 @@ static pci_ers_result_t lpfc_io_slot_reset(struct pci_dev *pdev)
2440} 2750}
2441 2751
2442/** 2752/**
2443 * lpfc_io_resume - called when traffic can start flowing again. 2753 * lpfc_io_resume: Resume PCI I/O operation.
2444 * @pdev: Pointer to PCI device 2754 * @pdev: pointer to PCI device
2445 * 2755 *
2446 * This callback is called when the error recovery driver tells us that 2756 * This routine is registered to the PCI subsystem for error handling. It is
2447 * its OK to resume normal operation. 2757 * called when kernel error recovery tells the lpfc driver that it is ok to
2758 * resume normal PCI operation after PCI bus error recovery. After this call,
2759 * traffic can start to flow from this device again.
2448 */ 2760 */
2449static void lpfc_io_resume(struct pci_dev *pdev) 2761static void lpfc_io_resume(struct pci_dev *pdev)
2450{ 2762{
@@ -2540,6 +2852,18 @@ static struct pci_driver lpfc_driver = {
2540 .err_handler = &lpfc_err_handler, 2852 .err_handler = &lpfc_err_handler,
2541}; 2853};
2542 2854
2855/**
2856 * lpfc_init: lpfc module initialization routine.
2857 *
2858 * This routine is to be invoked when the lpfc module is loaded into the
2859 * kernel. The special kernel macro module_init() is used to indicate the
2860 * role of this routine to the kernel as lpfc module entry point.
2861 *
2862 * Return codes
2863 * 0 - successful
2864 * -ENOMEM - FC attach transport failed
2865 * all others - failed
2866 */
2543static int __init 2867static int __init
2544lpfc_init(void) 2868lpfc_init(void)
2545{ 2869{
@@ -2573,6 +2897,13 @@ lpfc_init(void)
2573 return error; 2897 return error;
2574} 2898}
2575 2899
2900/**
2901 * lpfc_exit: lpfc module removal routine.
2902 *
2903 * This routine is invoked when the lpfc module is removed from the kernel.
2904 * The special kernel macro module_exit() is used to indicate the role of
2905 * this routine to the kernel as lpfc module exit point.
2906 */
2576static void __exit 2907static void __exit
2577lpfc_exit(void) 2908lpfc_exit(void)
2578{ 2909{