On Sat, Nov 02, 2024 at 07:54:36PM -0700, anish kumar wrote:
> The Extcon (External Connector) subsystem driver lacked proper
> documentation. This commit adds comprehensive documentation
> explaining the purpose, key components, and usage of the Extcon
> framework.
"Document the external connector subsystem. This includes ..."
> +Real-world examples:
> +
> +1. Smartphone USB-C port:
> + A single USB-C port on a smartphone can serve multiple functions. Extcon
> + can manage the different states of this port, such as:
> + - USB data connection
> + - Charging (various types like fast charging, USB Power Delivery)
> + - Audio output (USB-C headphones)
> + - Video output (USB-C to HDMI adapter)
> +
> +2. Laptop docking station:
> + When a laptop is connected to a docking station, multiple connections are
> + made simultaneously. Extcon can handle the state changes for:
> + - Power delivery
> + - External displays
> + - USB hub connections
> + - Ethernet connectivity
> +
> +3. Wireless charging pad:
> + Extcon can manage the state of a wireless charging connection, allowing
> + the system to respond appropriately when a device is placed on or removed
> + from the charging pad.
> +
> +4. Smart TV HDMI ports:
> + In a smart TV, Extcon can manage multiple HDMI ports, detecting when
> + devices are connected or disconnected, and potentially identifying the
> + type of device (e.g., gaming console, set-top box, Blu-ray player).
List items are outputted as long-running paragraphs instead, so I have to
add appropriate blank line separators:
---- >8 ----
diff --git a/Documentation/driver-api/extcon.rst b/Documentation/driver-api/extcon.rst
index d3217b9cdcd575..9e36dc5c1b66c0 100644
--- a/Documentation/driver-api/extcon.rst
+++ b/Documentation/driver-api/extcon.rst
@@ -23,27 +23,33 @@ types of connectors, including:
Real-world examples:
1. Smartphone USB-C port:
+
A single USB-C port on a smartphone can serve multiple functions. Extcon
can manage the different states of this port, such as:
+
- USB data connection
- Charging (various types like fast charging, USB Power Delivery)
- Audio output (USB-C headphones)
- Video output (USB-C to HDMI adapter)
2. Laptop docking station:
+
When a laptop is connected to a docking station, multiple connections are
made simultaneously. Extcon can handle the state changes for:
+
- Power delivery
- External displays
- USB hub connections
- Ethernet connectivity
3. Wireless charging pad:
+
Extcon can manage the state of a wireless charging connection, allowing
the system to respond appropriately when a device is placed on or removed
from the charging pad.
4. Smart TV HDMI ports:
+
In a smart TV, Extcon can manage multiple HDMI ports, detecting when
devices are connected or disconnected, and potentially identifying the
type of device (e.g., gaming console, set-top box, Blu-ray player).
> +Usage Example
> +-------------
> +
> +.. code-block:: c
> +
> + #include <linux/module.h>
> + #include <linux/platform_device.h>
> + #include <linux/extcon.h>
> +
> + struct my_extcon_data {
> + struct extcon_dev *edev;
> + struct device *dev;
> + };
> +
> + static const unsigned int my_extcon_cable[] = {
> + EXTCON_USB,
> + EXTCON_USB_HOST,
> + EXTCON_NONE,
> + };
> +
> + static int my_extcon_probe(struct platform_device *pdev)
> + {
> + struct my_extcon_data *data;
> + int ret;
> +
> + data = devm_kzalloc(&pdev->dev, sizeof(*data), GFP_KERNEL);
> + if (!data)
> + return -ENOMEM;
> +
> + data->dev = &pdev->dev;
> +
> + /* Initialize extcon device */
> + data->edev = devm_extcon_dev_allocate(data->dev, my_extcon_cable);
> + if (IS_ERR(data->edev)) {
> + dev_err(data->dev, "Failed to allocate extcon device\n");
> + return PTR_ERR(data->edev);
> + }
> +
> + /* Register extcon device */
> + ret = devm_extcon_dev_register(data->dev, data->edev);
> + if (ret < 0) {
> + dev_err(data->dev, "Failed to register extcon device\n");
> + return ret;
> + }
> +
> + platform_set_drvdata(pdev, data);
> +
> + /* Example: Set initial state */
> + extcon_set_state_sync(data->edev, EXTCON_USB, true);
> +
> + dev_info(data->dev, "My extcon driver probed successfully\n");
> + return 0;
> + }
> +
> + static int my_extcon_remove(struct platform_device *pdev)
> + {
> + struct my_extcon_data *data = platform_get_drvdata(pdev);
> +
> + /* Example: Clear state before removal */
> + extcon_set_state_sync(data->edev, EXTCON_USB, false);
> +
> + dev_info(data->dev, "My extcon driver removed\n");
> + return 0;
> + }
> +
> + static const struct of_device_id my_extcon_of_match[] = {
> + { .compatible = "my,extcon-device", },
> + { },
> + };
> + MODULE_DEVICE_TABLE(of, my_extcon_of_match);
> +
> + static struct platform_driver my_extcon_driver = {
> + .driver = {
> + .name = "my-extcon-driver",
> + .of_match_table = my_extcon_of_match,
> + },
> + .probe = my_extcon_probe,
> + .remove = my_extcon_remove,
> + };
> +
> + module_platform_driver(my_extcon_driver);
> +
> +This example demonstrates:
> +---------------------------
> +
> +- Defining supported cable types (USB and USB Host in this case).
> +- Allocating and registering an extcon device.
> +- Setting an initial state for a cable (USB connected in this example).
> +- Clearing the state when the driver is removed.
Can you explain in detail steps on the usage example above?
Thanks.
--
An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
