Orange Pi5 kernel

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