Merge pull request #966 from davidhedlund/patch-10

docs/controller-autoconfiguration.md: Added a new "Controller name scheme" section

Author: fpscan

docs/guides/controller-autoconfiguration.md

@@ -157,7 +157,56 @@ Here's how to set up a default-off configuration:
 3. Do not add "(default-off)" to the values of the input_device_display_name and input_driver variables in the config file. The default-off status is already indicated by the filename, so these variables should remain unmodified for clarity.
 
 This approach allows users to manually enable the configuration when needed, preventing automatic application that could interfere with common devices, and helps ensure a smoother experience for users while still providing the necessary configuration options for those who require them.
- 
+
+### Controller name scheme
+
+In RetroArch, the management of controller configurations is essential for ensuring proper functionality across various systems. This guide outlines how controller names are generated and how they can vary based on the Linux kernel version in GNU/Linux distributions.
+
+#### Understanding controller names
+
+When you save a controller profile (**Settings > Input > RetroPad Binds > Port 1 Controls > Save Controller Profile**), RetroArch generates a controller name (e.g., "Foo"). This name serves two purposes:
+
+1. It becomes part of the configuration file name (e.g., "udev/Foo.cfg").
+2. It's used as the value for the `input_device` variable within the configuration file (e.g., `input_device = "Foo"`).
+
+Importantly, this name remains consistent across various controller drivers, such as udev, sdl2, and linuxraw, as specified in **Settings > Drivers > Controller**.
+
+#### Variability of controller names
+
+The controller name may change depending on the version of the system, particularly the Linux kernel version. To ensure compatibility, we utilize the most recent controller name that is supported by the system.
+
+#### Example: Nintendo Switch Pro Controller on GNU/Linux
+
+The following table illustrates how the controller name for the Nintendo Switch Pro Controller varies across different Linux kernel versions, along with its HID support and corresponding autoconfig file names. As a side-note, the notation "(default-off)" indicates that the configuration is disabled by default to avoid 
+
+| Linux Kernel Version | Controller Name in RetroArch              | Nintendo Switch Pro Controller HID Support | Selected controller name for the autoconfiguration file                          |
+|----------------------|-------------------------------------------|-------------------------------------------|----------------------------------------------|
+| 5.15                 | Pro Controller                            | No                                        | Pro Controller             |
+| 5.19                 | Nintendo Switch Pro Controller            | Yes                                       |                                              |
+| 6.2.0                | Nintendo Switch Pro Controller            | Yes                                       |                                              |
+| 6.8.0                | Nintendo Co., Ltd. Pro Controller         | Yes                                       | Nintendo Co.,Ltd. Pro Controller         |
+
+##### Configuration file examples
+
+###### Pro Controller (default-off).cfg
+```
+# This file uses the legacy controller name "Pro Controller" (generated by RetroArch on Linux 5.15)
+# "(default-off)" was added to the file name to indicate that the autoconfig file is not active by default. See comments for input_vendor_id and input_product_id.
+input_device = "Pro Controller"
+# Due to the uncommon nature of this device, the autoconfig file is not active by default. This precaution is taken to avoid potential conflicts with the widely-used Nintendo Switch Pro Controller (nintendo-hid version) file. Button layouts are not compatible. To activate this configuration:
+#   1) Comment out the input_vendor_id and input_product_id lines in the "Nintendo Co.,Ltd. Pro Controller.cfg" file.
+#   2) Uncomment the input_vendor_id and input_product_id lines below:
+# input_vendor_id = "1406"
+# input_product_id = "8201"
+```
+
+###### Nintendo Co.,Ltd. Pro Controller.cfg
+```
+input_device = "Nintendo Co.,Ltd. Pro Controller"
+input_vendor_id = "1406"
+input_product_id = "8201"
+```
+
 ## Troubleshooting
 If your joypad is not configured properly, you should [generate a RetroArch log](/docs/guides/generating-retroarch-logs.md). Your log will show if a profile has been matched for your pad and the path of the corresponding profile.
 
@@ -227,8 +276,9 @@ input_menu_toggle_btn = "8"
 
 ### Input descriptors
 
-The third part are *input descriptors* used by RetroArch to display the labels of the buttons as they are written on your joypad. So if you are using a DualShock pad, RetroArch will refer to the buttons as Cross, Circle, Square and Triangle.
+The third part are *input descriptors* used by RetroArch to display the labels of the buttons as they are written on your joypad.
 
+Generic input descriptors:
 ```
 input_b_btn_label = "A"
 input_y_btn_label = "X"
@@ -256,3 +306,34 @@ input_r_y_plus_axis_label = "Right Analog Y+ (down)"
 input_r_y_minus_axis_label = "Right Analog Y- (up)"
 input_menu_toggle_btn_label = "Guide"
 ```
+
+#### Sony PlayStation controllers
+
+So if you are using a Sony PlayStation controllers, RetroArch will refer to the buttons as Cross, Circle, Square and Triangle:
+```
+input_b_btn_label = "Cross"
+input_y_btn_label = "Square"
+input_select_btn_label = "Create"
+input_start_btn_label = "Options"
+input_up_btn_label = "D-Pad Up"
+input_down_btn_label = "D-Pad Down"
+input_left_btn_label = "D-Pad Left"
+input_right_btn_label = "D-Pad Right"
+input_a_btn_label = "Circle"
+input_x_btn_label = "Triangle"
+input_l_btn_label = "L1"
+input_r_btn_label = "R1"
+input_l2_axis_label = "L2"
+input_r2_axis_label = "R2"
+input_l3_btn_label = "L3"
+input_r3_btn_label = "R3"
+input_l_x_plus_axis_label = "Left Analog X+ (right)"
+input_l_x_minus_axis_label = "Left Analog X- (left)"
+input_l_y_plus_axis_label = "Left Analog Y+ (down)"
+input_l_y_minus_axis_label = "Left Analog Y- (up)"
+input_r_x_plus_axis_label = "Right Analog X+ (right)"
+input_r_x_minus_axis_label = "Right Analog X- (left)"
+input_r_y_plus_axis_label = "Right Analog Y+ (down)"
+input_r_y_minus_axis_label = "Right Analog Y- (up)"
+input_menu_toggle_btn_label = "PS"
+```