From a756185de6792278bb5c7d286c9a6fa22722b319 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:55 +0100 Subject: scsi: docs: convert megaraid.txt to ReST Link: https://lore.kernel.org/r/b7ee59230c5a33ff6d60edba0d0bcf3e2aeaa88f.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/megaraid.rst | 77 +++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/megaraid.txt | 70 ------------------------------------- MAINTAINERS | 2 +- 4 files changed, 79 insertions(+), 71 deletions(-) create mode 100644 Documentation/scsi/megaraid.rst delete mode 100644 Documentation/scsi/megaraid.txt diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 22427511e227..37be1fc9d128 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -26,5 +26,6 @@ Linux SCSI Subsystem libsas link_power_management_policy lpfc + megaraid scsi_transport_srp/figures diff --git a/Documentation/scsi/megaraid.rst b/Documentation/scsi/megaraid.rst new file mode 100644 index 000000000000..22b75a86ba72 --- /dev/null +++ b/Documentation/scsi/megaraid.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +Notes on Management Module +========================== + +Overview +-------- + +Different classes of controllers from LSI Logic accept and respond to the +user applications in a similar way. They understand the same firmware control +commands. Furthermore, the applications also can treat different classes of +the controllers uniformly. Hence it is logical to have a single module that +interfaces with the applications on one side and all the low level drivers +on the other. + +The advantages, though obvious, are listed for completeness: + + i. Avoid duplicate code from the low level drivers. + ii. Unburden the low level drivers from having to export the + character node device and related handling. + iii. Implement any policy mechanisms in one place. + iv. Applications have to interface with only module instead of + multiple low level drivers. + +Currently this module (called Common Management Module) is used only to issue +ioctl commands. But this module is envisioned to handle all user space level +interactions. So any 'proc', 'sysfs' implementations will be localized in this +common module. + +Credits +------- + +:: + + "Shared code in a third module, a "library module", is an acceptable + solution. modprobe automatically loads dependent modules, so users + running "modprobe driver1" or "modprobe driver2" would automatically + load the shared library module." + +- Jeff Garzik (jgarzik@pobox.com), 02.25.2004 LKML + +:: + + "As Jeff hinted, if your userspace<->driver API is consistent between + your new MPT-based RAID controllers and your existing megaraid driver, + then perhaps you need a single small helper module (lsiioctl or some + better name), loaded by both mptraid and megaraid automatically, which + handles registering the /dev/megaraid node dynamically. In this case, + both mptraid and megaraid would register with lsiioctl for each + adapter discovered, and lsiioctl would essentially be a switch, + redirecting userspace tool ioctls to the appropriate driver." + +- Matt Domsch, (Matt_Domsch@dell.com), 02.25.2004 LKML + +Design +------ + +The Common Management Module is implemented in megaraid_mm.[ch] files. This +module acts as a registry for low level hba drivers. The low level drivers +(currently only megaraid) register each controller with the common module. + +The applications interface with the common module via the character device +node exported by the module. + +The lower level drivers now understand only a new improved ioctl packet called +uioc_t. The management module converts the older ioctl packets from the older +applications into uioc_t. After driver handles the uioc_t, the common module +will convert that back into the old format before returning to applications. + +As new applications evolve and replace the old ones, the old packet format +will be retired. + +Common module dedicates one uioc_t packet to each controller registered. This +can easily be more than one. But since megaraid is the only low level driver +today, and it can handle only one ioctl, there is no reason to have more. But +as new controller classes get added, this will be tuned appropriately. diff --git a/Documentation/scsi/megaraid.txt b/Documentation/scsi/megaraid.txt deleted file mode 100644 index 3c7cea51e687..000000000000 --- a/Documentation/scsi/megaraid.txt +++ /dev/null @@ -1,70 +0,0 @@ - Notes on Management Module - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Overview: --------- - -Different classes of controllers from LSI Logic accept and respond to the -user applications in a similar way. They understand the same firmware control -commands. Furthermore, the applications also can treat different classes of -the controllers uniformly. Hence it is logical to have a single module that -interfaces with the applications on one side and all the low level drivers -on the other. - -The advantages, though obvious, are listed for completeness: - - i. Avoid duplicate code from the low level drivers. - ii. Unburden the low level drivers from having to export the - character node device and related handling. - iii. Implement any policy mechanisms in one place. - iv. Applications have to interface with only module instead of - multiple low level drivers. - -Currently this module (called Common Management Module) is used only to issue -ioctl commands. But this module is envisioned to handle all user space level -interactions. So any 'proc', 'sysfs' implementations will be localized in this -common module. - -Credits: -------- - -"Shared code in a third module, a "library module", is an acceptable -solution. modprobe automatically loads dependent modules, so users -running "modprobe driver1" or "modprobe driver2" would automatically -load the shared library module." - - - Jeff Garzik (jgarzik@pobox.com), 02.25.2004 LKML - -"As Jeff hinted, if your userspace<->driver API is consistent between -your new MPT-based RAID controllers and your existing megaraid driver, -then perhaps you need a single small helper module (lsiioctl or some -better name), loaded by both mptraid and megaraid automatically, which -handles registering the /dev/megaraid node dynamically. In this case, -both mptraid and megaraid would register with lsiioctl for each -adapter discovered, and lsiioctl would essentially be a switch, -redirecting userspace tool ioctls to the appropriate driver." - - - Matt Domsch, (Matt_Domsch@dell.com), 02.25.2004 LKML - -Design: ------- - -The Common Management Module is implemented in megaraid_mm.[ch] files. This -module acts as a registry for low level hba drivers. The low level drivers -(currently only megaraid) register each controller with the common module. - -The applications interface with the common module via the character device -node exported by the module. - -The lower level drivers now understand only a new improved ioctl packet called -uioc_t. The management module converts the older ioctl packets from the older -applications into uioc_t. After driver handles the uioc_t, the common module -will convert that back into the old format before returning to applications. - -As new applications evolve and replace the old ones, the old packet format -will be retired. - -Common module dedicates one uioc_t packet to each controller registered. This -can easily be more than one. But since megaraid is the only low level driver -today, and it can handle only one ioctl, there is no reason to have more. But -as new controller classes get added, this will be tuned appropriately. diff --git a/MAINTAINERS b/MAINTAINERS index 51cc884037f2..a2e497f95012 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -10639,7 +10639,7 @@ L: megaraidlinux.pdl@broadcom.com L: linux-scsi@vger.kernel.org W: http://www.avagotech.com/support/ S: Maintained -F: Documentation/scsi/megaraid.txt +F: Documentation/scsi/megaraid.rst F: drivers/scsi/megaraid.* F: drivers/scsi/megaraid/ -- cgit v1.2.3-70-g09d2