Commit ee7f3e2b authored by Kurt Borja's avatar Kurt Borja Committed by Ilpo Järvinen
Browse files

ACPI: platform_profile: Add documentation 



Add kerneldoc and sysfs class documentation.

Reviewed-by: default avatarMario Limonciello <mario.limonciello@amd.com>
Signed-off-by: default avatarKurt Borja <kuurtb@gmail.com>
Reviewed-by: default avatarMark Pearson <mpearson-lenovo@squebb.ca>
Tested-by: default avatarMark Pearson <mpearson-lenovo@squebb.ca>
Link: https://lore.kernel.org/r/20250116002721.75592-19-kuurtb@gmail.com


Reviewed-by: default avatarIlpo Järvinen <ilpo.jarvinen@linux.intel.com>
Signed-off-by: default avatarIlpo Järvinen <ilpo.jarvinen@linux.intel.com>
parent c4f7d255

Documentation/ABI/testing/sysfs-class-platform-profile

0 → 100644
+48 −0
Original line number Diff line number Diff line 
What:		/sys/class/platform-profile/platform-profile-X/name

Date:		March 2025

KernelVersion:	6.14

Description:	Name of the class device given by the driver.



		RO



What:		/sys/class/platform-profile/platform-profile-X/choices

Date:		March 2025

KernelVersion:	6.14

Description:	This file contains a space-separated list of profiles supported

		for this device.



		Drivers must use the following standard profile-names:



		====================	========================================

		low-power		Low power consumption

		cool			Cooler operation

		quiet			Quieter operation

		balanced		Balance between low power consumption

					and performance

		balanced-performance	Balance between performance and low

					power consumption with a slight bias

					towards performance

		performance		High performance operation

		custom			Driver defined custom profile

		====================	========================================



		RO



What:		/sys/class/platform-profile/platform-profile-X/profile

Date:		March 2025

KernelVersion:	6.14

Description:	Reading this file gives the current selected profile for this

		device. Writing this file with one of the strings from

		platform_profile_choices changes the profile to the new value.



		This file can be monitored for changes by polling for POLLPRI,

		POLLPRI will be signaled on any changes, independent of those

		changes coming from a userspace write; or coming from another

		source such as e.g. a hotkey triggered profile change handled

		either directly by the embedded-controller or fully handled

		inside the kernel.



		This file may also emit the string 'custom' to indicate

		that the driver is using a driver defined custom profile.



		RW

drivers/acpi/platform_profile.c

+33 −0
Original line number Diff line number Diff line
@@ -425,6 +425,10 @@ static const struct attribute_group platform_profile_group = { 
	.is_visible = profile_class_is_visible,

};



/**

 * platform_profile_notify - Notify class device and legacy sysfs interface

 * @dev: The class device

 */

void platform_profile_notify(struct device *dev)

{

	scoped_cond_guard(mutex_intr, return, &profile_lock) {
@@ -434,6 +438,11 @@ void platform_profile_notify(struct device *dev) 
}

EXPORT_SYMBOL_GPL(platform_profile_notify);



/**

 * platform_profile_cycle - Cycles profiles available on all registered class devices

 *

 * Return: 0 on success, -errno on failure

 */

int platform_profile_cycle(void)

{

	enum platform_profile_option next = PLATFORM_PROFILE_LAST;
@@ -477,6 +486,15 @@ int platform_profile_cycle(void) 
}

EXPORT_SYMBOL_GPL(platform_profile_cycle);



/**

 * platform_profile_register - Creates and registers a platform profile class device

 * @dev: Parent device

 * @name: Name of the class device

 * @drvdata: Driver data that will be attached to the class device

 * @ops: Platform profile's mandatory operations

 *

 * Return: pointer to the new class device on success, ERR_PTR on failure

 */

struct device *platform_profile_register(struct device *dev, const char *name,

					 void *drvdata,

					 const struct platform_profile_ops *ops)
@@ -546,6 +564,12 @@ struct device *platform_profile_register(struct device *dev, const char *name, 
}

EXPORT_SYMBOL_GPL(platform_profile_register);



/**

 * platform_profile_remove - Unregisters a platform profile class device

 * @dev: Class device

 *

 * Return: 0

 */

int platform_profile_remove(struct device *dev)

{

	struct platform_profile_handler *pprof = to_pprof_handler(dev);
@@ -571,6 +595,15 @@ static void devm_platform_profile_release(struct device *dev, void *res) 
	platform_profile_remove(*ppdev);

}



/**

 * devm_platform_profile_register - Device managed version of platform_profile_register

 * @dev: Parent device

 * @name: Name of the class device

 * @drvdata: Driver data that will be attached to the class device

 * @ops: Platform profile's mandatory operations

 *

 * Return: pointer to the new class device on success, ERR_PTR on failure

 */

struct device *devm_platform_profile_register(struct device *dev, const char *name,

					      void *drvdata,

					      const struct platform_profile_ops *ops)

include/linux/platform_profile.h

+10 −0
Original line number Diff line number Diff line
@@ -28,6 +28,16 @@ enum platform_profile_option { 
	PLATFORM_PROFILE_LAST, /*must always be last */

};



/**

 * struct platform_profile_ops - platform profile operations

 * @probe: Callback to setup choices available to the new class device. These

 *	   choices will only be enforced when setting a new profile, not when

 *	   getting the current one.

 * @profile_get: Callback that will be called when showing the current platform

 *		 profile in sysfs.

 * @profile_set: Callback that will be called when storing a new platform

 *		 profile in sysfs.

 */

struct platform_profile_ops {

	int (*probe)(void *drvdata, unsigned long *choices);

	int (*profile_get)(struct device *dev, enum platform_profile_option *profile);