[linux.git] / Documentation / scsi / megaraid.rst

.. SPDX-License-Identifier: GPL-2.0

=================================
Megaraid Common 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 ([email protected]), 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, ([email protected]), 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.
Commit	Line	Data
a756185d	1	.. SPDX-License-Identifier: GPL-2.0
1da177e4	2
0176d339 RD	3	=================================
	4	Megaraid Common Management Module
	5	=================================
a756185d MCC	6
a756185d MCC	7	Overview
1da177e4 LT	8	--------
1da177e4 LT	9
2fe0ae78	10	Different classes of controllers from LSI Logic accept and respond to the
1da177e4 LT	11	user applications in a similar way. They understand the same firmware control
	12	commands. Furthermore, the applications also can treat different classes of
	13	the controllers uniformly. Hence it is logical to have a single module that
2fe0ae78	14	interfaces with the applications on one side and all the low level drivers
1da177e4 LT	15	on the other.
	16
	17	The advantages, though obvious, are listed for completeness:
	18
	19	i. Avoid duplicate code from the low level drivers.
	20	ii. Unburden the low level drivers from having to export the
	21	character node device and related handling.
	22	iii. Implement any policy mechanisms in one place.
	23	iv. Applications have to interface with only module instead of
	24	multiple low level drivers.
	25
	26	Currently this module (called Common Management Module) is used only to issue
	27	ioctl commands. But this module is envisioned to handle all user space level
	28	interactions. So any 'proc', 'sysfs' implementations will be localized in this
	29	common module.
	30
a756185d	31	Credits
1da177e4 LT	32	-------
1da177e4 LT	33
a756185d MCC	34	::
	35
	36	"Shared code in a third module, a "library module", is an acceptable
	37	solution. modprobe automatically loads dependent modules, so users
	38	running "modprobe driver1" or "modprobe driver2" would automatically
	39	load the shared library module."
	40
	41	- Jeff Garzik ([email protected]), 02.25.2004 LKML
1da177e4	42
a756185d	43	::
1da177e4	44
a756185d MCC	45	"As Jeff hinted, if your userspace<->driver API is consistent between
	46	your new MPT-based RAID controllers and your existing megaraid driver,
	47	then perhaps you need a single small helper module (lsiioctl or some
	48	better name), loaded by both mptraid and megaraid automatically, which
	49	handles registering the /dev/megaraid node dynamically. In this case,
	50	both mptraid and megaraid would register with lsiioctl for each
	51	adapter discovered, and lsiioctl would essentially be a switch,
	52	redirecting userspace tool ioctls to the appropriate driver."
1da177e4	53
a756185d	54	- Matt Domsch, ([email protected]), 02.25.2004 LKML
1da177e4	55
a756185d	56	Design
1da177e4 LT	57	------
	58
	59	The Common Management Module is implemented in megaraid_mm.[ch] files. This
	60	module acts as a registry for low level hba drivers. The low level drivers
	61	(currently only megaraid) register each controller with the common module.
	62
	63	The applications interface with the common module via the character device
	64	node exported by the module.
	65
	66	The lower level drivers now understand only a new improved ioctl packet called
	67	uioc_t. The management module converts the older ioctl packets from the older
	68	applications into uioc_t. After driver handles the uioc_t, the common module
	69	will convert that back into the old format before returning to applications.
	70
a756185d	71	As new applications evolve and replace the old ones, the old packet format
1da177e4 LT	72	will be retired.
	73
	74	Common module dedicates one uioc_t packet to each controller registered. This
	75	can easily be more than one. But since megaraid is the only low level driver
	76	today, and it can handle only one ioctl, there is no reason to have more. But
	77	as new controller classes get added, this will be tuned appropriately.