thunderbolt: Update switch.c function documentation

+102 -38

1 changed file

expand all

drivers

thunderbolt

switch.c

+102 -38

drivers/thunderbolt/switch.c

··· 290 290 * @size: Size of the buffer in bytes 291 291 * 292 292 * Reads from router NVM and returns the requested data in @buf. Locking 293 - * is up to the caller. Returns %0 in success and negative errno in case 294 - * of failure. 293 + * is up to the caller. 294 + * 295 + * Return: %0 on success, negative errno otherwise. 295 296 */ 296 297 int tb_switch_nvm_read(struct tb_switch *sw, unsigned int address, void *buf, 297 298 size_t size) ··· 465 464 * 466 465 * The port must have a TB_CAP_PHY (i.e. it should be a real port). 467 466 * 468 - * Return: Returns an enum tb_port_state on success or an error code on failure. 467 + * Return: &enum tb_port_state or negative error code on failure. 469 468 */ 470 469 int tb_port_state(struct tb_port *port) 471 470 { ··· 492 491 * switch resume). Otherwise we only wait if a device is registered but the link 493 492 * has not yet been established. 494 493 * 495 - * Return: Returns an error code on failure. Returns 0 if the port is not 496 - * connected or failed to reach state TB_PORT_UP within one second. Returns 1 497 - * if the port is connected and in state TB_PORT_UP. 494 + * Return: 495 + * * %0 - If the port is not connected or failed to reach 496 + * state %TB_PORT_UP within one second. 497 + * * %1 - If the port is connected and in state %TB_PORT_UP. 498 + * * Negative errno - An error occurred. 498 499 */ 499 500 int tb_wait_for_port(struct tb_port *port, bool wait_if_unplugged) 500 501 { ··· 565 562 * Change the number of NFC credits allocated to @port by @credits. To remove 566 563 * NFC credits pass a negative amount of credits. 567 564 * 568 - * Return: Returns 0 on success or an error code on failure. 565 + * Return: %0 on success, negative errno otherwise. 569 566 */ 570 567 int tb_port_add_nfc_credits(struct tb_port *port, int credits) 571 568 { ··· 602 599 * @port: Port whose counters to clear 603 600 * @counter: Counter index to clear 604 601 * 605 - * Return: Returns 0 on success or an error code on failure. 602 + * Return: %0 on success, negative errno otherwise. 606 603 */ 607 604 int tb_port_clear_counter(struct tb_port *port, int counter) 608 605 { ··· 617 614 * 618 615 * Needed for USB4 but can be called for any CIO/USB4 ports. Makes the 619 616 * downstream router accessible for CM. 617 + * 618 + * Return: %0 on success, negative errno otherwise. 620 619 */ 621 620 int tb_port_unlock(struct tb_port *port) 622 621 { ··· 664 659 * @port: Port to enable (can be %NULL) 665 660 * 666 661 * This is used for lane 0 and 1 adapters to enable it. 662 + * 663 + * Return: %0 on success, negative errno otherwise. 667 664 */ 668 665 int tb_port_enable(struct tb_port *port) 669 666 { ··· 677 670 * @port: Port to disable (can be %NULL) 678 671 * 679 672 * This is used for lane 0 and 1 adapters to disable it. 673 + * 674 + * Return: %0 on success, negative errno otherwise. 680 675 */ 681 676 int tb_port_disable(struct tb_port *port) 682 677 { ··· 698 689 * This is a helper method for tb_switch_alloc. Does not check or initialize 699 690 * any downstream switches. 700 691 * 701 - * Return: Returns 0 on success or an error code on failure. 692 + * Return: %0 on success, negative errno otherwise. 702 693 */ 703 694 static int tb_init_port(struct tb_port *port) 704 695 { ··· 856 847 * link port, the function follows that link and returns another end on 857 848 * that same link. 858 849 * 859 - * If the @end port has been reached, return %NULL. 860 - * 861 850 * Domain tb->lock must be held when this function is called. 851 + * 852 + * Return: Pointer to &struct tb_port, %NULL if the @end port has been reached. 862 853 */ 863 854 struct tb_port *tb_next_port_on_path(struct tb_port *start, struct tb_port *end, 864 855 struct tb_port *prev) ··· 903 894 * tb_port_get_link_speed() - Get current link speed 904 895 * @port: Port to check (USB4 or CIO) 905 896 * 906 - * Returns link speed in Gb/s or negative errno in case of failure. 897 + * Return: Link speed in Gb/s or negative errno in case of failure. 907 898 */ 908 899 int tb_port_get_link_speed(struct tb_port *port) 909 900 { ··· 935 926 * tb_port_get_link_generation() - Returns link generation 936 927 * @port: Lane adapter 937 928 * 938 - * Returns link generation as number or negative errno in case of 939 - * failure. Does not distinguish between Thunderbolt 1 and Thunderbolt 2 940 - * links so for those always returns 2. 929 + * Return: Link generation as a number or negative errno in case of 930 + * failure. 931 + * 932 + * Does not distinguish between Thunderbolt 1 and Thunderbolt 2 933 + * links so for those always returns %2. 941 934 */ 942 935 int tb_port_get_link_generation(struct tb_port *port) 943 936 { ··· 963 952 * tb_port_get_link_width() - Get current link width 964 953 * @port: Port to check (USB4 or CIO) 965 954 * 966 - * Returns link width. Return the link width as encoded in &enum 967 - * tb_link_width or negative errno in case of failure. 955 + * Return: Link width encoded in &enum tb_link_width or 956 + * negative errno in case of failure. 968 957 */ 969 958 int tb_port_get_link_width(struct tb_port *port) 970 959 { ··· 990 979 * @width: Widths to check (bitmask) 991 980 * 992 981 * Can be called to any lane adapter. Checks if given @width is 993 - * supported by the hardware and returns %true if it is. 982 + * supported by the hardware. 983 + * 984 + * Return: %true if link width is supported, %false otherwise. 994 985 */ 995 986 bool tb_port_width_supported(struct tb_port *port, unsigned int width) 996 987 { ··· 1029 1016 * Sets the target link width of the lane adapter to @width. Does not 1030 1017 * enable/disable lane bonding. For that call tb_port_set_lane_bonding(). 1031 1018 * 1032 - * Return: %0 in case of success and negative errno in case of error 1019 + * Return: %0 on success, negative errno otherwise. 1033 1020 */ 1034 1021 int tb_port_set_link_width(struct tb_port *port, enum tb_link_width width) 1035 1022 { ··· 1083 1070 * cases one should use tb_port_lane_bonding_enable() instead to enable 1084 1071 * lane bonding. 1085 1072 * 1086 - * Return: %0 in case of success and negative errno in case of error 1073 + * Return: %0 on success, negative errno otherwise. 1087 1074 */ 1088 1075 static int tb_port_set_lane_bonding(struct tb_port *port, bool bonding) 1089 1076 { ··· 1117 1104 * tb_port_wait_for_link_width() before enabling any paths through the 1118 1105 * link to make sure the link is in expected state. 1119 1106 * 1120 - * Return: %0 in case of success and negative errno in case of error 1107 + * Return: %0 on success, negative errno otherwise. 1121 1108 */ 1122 1109 int tb_port_lane_bonding_enable(struct tb_port *port) 1123 1110 { ··· 1194 1181 * 1195 1182 * Should be used after both ends of the link have been bonded (or 1196 1183 * bonding has been disabled) to wait until the link actually reaches 1197 - * the expected state. Returns %-ETIMEDOUT if the width was not reached 1198 - * within the given timeout, %0 if it did. Can be passed a mask of 1199 - * expected widths and succeeds if any of the widths is reached. 1184 + * the expected state. 1185 + * 1186 + * Can be passed a mask of expected widths. 1187 + * 1188 + * Return: 1189 + * * %0 - If link reaches any of the specified widths. 1190 + * * %-ETIMEDOUT - If link does not reach specified width. 1191 + * * Negative errno - Another error occurred. 1200 1192 */ 1201 1193 int tb_port_wait_for_link_width(struct tb_port *port, unsigned int width, 1202 1194 int timeout_msec) ··· 1266 1248 * After the link is bonded (or bonding was disabled) the port total 1267 1249 * credits may change, so this function needs to be called to re-read 1268 1250 * the credits. Updates also the second lane adapter. 1251 + * 1252 + * Return: %0 on success, negative errno otherwise. 1269 1253 */ 1270 1254 int tb_port_update_credits(struct tb_port *port) 1271 1255 { ··· 1323 1303 /** 1324 1304 * tb_port_is_enabled() - Is the adapter port enabled 1325 1305 * @port: Port to check 1306 + * 1307 + * Return: %true if port is enabled, %false otherwise. 1326 1308 */ 1327 1309 bool tb_port_is_enabled(struct tb_port *port) 1328 1310 { ··· 1349 1327 /** 1350 1328 * tb_usb3_port_is_enabled() - Is the USB3 adapter port enabled 1351 1329 * @port: USB3 adapter port to check 1330 + * 1331 + * Return: %true if port is enabled, %false otherwise. 1352 1332 */ 1353 1333 bool tb_usb3_port_is_enabled(struct tb_port *port) 1354 1334 { ··· 1367 1343 * tb_usb3_port_enable() - Enable USB3 adapter port 1368 1344 * @port: USB3 adapter port to enable 1369 1345 * @enable: Enable/disable the USB3 adapter 1346 + * 1347 + * Return: %0 on success, negative errno otherwise. 1370 1348 */ 1371 1349 int tb_usb3_port_enable(struct tb_port *port, bool enable) 1372 1350 { ··· 1384 1358 /** 1385 1359 * tb_pci_port_is_enabled() - Is the PCIe adapter port enabled 1386 1360 * @port: PCIe port to check 1361 + * 1362 + * Return: %true if port is enabled, %false otherwise. 1387 1363 */ 1388 1364 bool tb_pci_port_is_enabled(struct tb_port *port) 1389 1365 { ··· 1402 1374 * tb_pci_port_enable() - Enable PCIe adapter port 1403 1375 * @port: PCIe port to enable 1404 1376 * @enable: Enable/disable the PCIe adapter 1377 + * 1378 + * Return: %0 on success, negative errno otherwise. 1405 1379 */ 1406 1380 int tb_pci_port_enable(struct tb_port *port, bool enable) 1407 1381 { ··· 1419 1389 * @port: DP out port to check 1420 1390 * 1421 1391 * Checks if the DP OUT adapter port has HPD bit already set. 1392 + * 1393 + * Return: %1 if HPD is active, %0 otherwise. 1422 1394 */ 1423 1395 int tb_dp_port_hpd_is_active(struct tb_port *port) 1424 1396 { ··· 1440 1408 * @port: Port to clear HPD 1441 1409 * 1442 1410 * If the DP IN port has HPD set, this function can be used to clear it. 1411 + * 1412 + * Return: %0 on success, negative errno otherwise. 1443 1413 */ 1444 1414 int tb_dp_port_hpd_clear(struct tb_port *port) 1445 1415 { ··· 1468 1434 * Programs specified Hop IDs for DP IN/OUT port. Can be called for USB4 1469 1435 * router DP adapters too but does not program the values as the fields 1470 1436 * are read-only. 1437 + * 1438 + * Return: %0 on success, negative errno otherwise. 1471 1439 */ 1472 1440 int tb_dp_port_set_hops(struct tb_port *port, unsigned int video, 1473 1441 unsigned int aux_tx, unsigned int aux_rx) ··· 1502 1466 /** 1503 1467 * tb_dp_port_is_enabled() - Is DP adapter port enabled 1504 1468 * @port: DP adapter port to check 1469 + * 1470 + * Return: %true if DP port is enabled, %false otherwise. 1505 1471 */ 1506 1472 bool tb_dp_port_is_enabled(struct tb_port *port) 1507 1473 { ··· 1523 1485 * 1524 1486 * Once Hop IDs are programmed DP paths can be enabled or disabled by 1525 1487 * calling this function. 1488 + * 1489 + * Return: %0 on success, negative errno otherwise. 1526 1490 */ 1527 1491 int tb_dp_port_enable(struct tb_port *port, bool enable) 1528 1492 { ··· 1674 1634 * 1675 1635 * If the router is not enumerated does nothing. 1676 1636 * 1677 - * Returns %0 on success or negative errno in case of failure. 1637 + * Return: %0 on success, negative errno otherwise. 1678 1638 */ 1679 1639 int tb_switch_reset(struct tb_switch *sw) 1680 1640 { ··· 1710 1670 * @timeout_msec: Timeout in ms how long to wait 1711 1671 * 1712 1672 * Wait till the specified bits in specified offset reach specified value. 1713 - * Returns %0 in case of success, %-ETIMEDOUT if the @value was not reached 1714 - * within the given timeout or a negative errno in case of failure. 1673 + * 1674 + * Return: 1675 + * * %0 - On success. 1676 + * * %-ETIMEDOUT - If the @value was not reached within 1677 + * the given timeout. 1678 + * * Negative errno - In case of failure. 1715 1679 */ 1716 1680 int tb_switch_wait_for_bit(struct tb_switch *sw, u32 offset, u32 bit, 1717 1681 u32 value, int timeout_msec) ··· 1744 1700 * 1745 1701 * Also configures a sane plug_events_delay of 255ms. 1746 1702 * 1747 - * Return: Returns 0 on success or an error code on failure. 1703 + * Return: %0 on success, negative errno otherwise. 1748 1704 */ 1749 1705 static int tb_plug_events_active(struct tb_switch *sw, bool active) 1750 1706 { ··· 2450 2406 * separately. The returned switch should be released by calling 2451 2407 * tb_switch_put(). 2452 2408 * 2453 - * Return: Pointer to the allocated switch or ERR_PTR() in case of 2454 - * failure. 2409 + * Return: Pointer to &struct tb_switch or ERR_PTR() in case of failure. 2455 2410 */ 2456 2411 struct tb_switch *tb_switch_alloc(struct tb *tb, struct device *parent, 2457 2412 u64 route) ··· 2569 2526 * 2570 2527 * The returned switch must be released by calling tb_switch_put(). 2571 2528 * 2572 - * Return: Pointer to the allocated switch or ERR_PTR() in case of failure 2529 + * Return: Pointer to &struct tb_switch or ERR_PTR() in case of failure. 2573 2530 */ 2574 2531 struct tb_switch * 2575 2532 tb_switch_alloc_safe_mode(struct tb *tb, struct device *parent, u64 route) ··· 2605 2562 * connection manager to use. Can be called to the switch again after 2606 2563 * resume from low power states to re-initialize it. 2607 2564 * 2608 - * Return: %0 in case of success and negative errno in case of failure 2565 + * Return: %0 on success, negative errno otherwise. 2609 2566 */ 2610 2567 int tb_switch_configure(struct tb_switch *sw) 2611 2568 { ··· 2668 2625 * Needs to be called before any tunnels can be setup through the 2669 2626 * router. Can be called to any router. 2670 2627 * 2671 - * Returns %0 in success and negative errno otherwise. 2628 + * Return: %0 on success, negative errno otherwise. 2672 2629 */ 2673 2630 int tb_switch_configuration_valid(struct tb_switch *sw) 2674 2631 { ··· 2943 2900 * Connection manager can call this function to enable lane bonding of a 2944 2901 * switch. If conditions are correct and both switches support the feature, 2945 2902 * lanes are bonded. It is safe to call this to any switch. 2903 + * 2904 + * Return: %0 on success, negative errno otherwise. 2946 2905 */ 2947 2906 static int tb_switch_lane_bonding_enable(struct tb_switch *sw) 2948 2907 { ··· 2995 2950 * 2996 2951 * Disables lane bonding between @sw and parent. This can be called even 2997 2952 * if lanes were not bonded originally. 2953 + * 2954 + * Return: %0 on success, negative errno otherwise. 2998 2955 */ 2999 2956 static int tb_switch_lane_bonding_disable(struct tb_switch *sw) 3000 2957 { ··· 3121 3074 * 3122 3075 * Does nothing for host router. 3123 3076 * 3124 - * Returns %0 in case of success, negative errno otherwise. 3077 + * Return: %0 on success, negative errno otherwise. 3125 3078 */ 3126 3079 int tb_switch_set_link_width(struct tb_switch *sw, enum tb_link_width width) 3127 3080 { ··· 3192 3145 * 3193 3146 * It is recommended that this is called after lane bonding is enabled. 3194 3147 * 3195 - * Returns %0 on success and negative errno in case of error. 3148 + * Return: %0 on success and negative errno otherwise. 3196 3149 */ 3197 3150 int tb_switch_configure_link(struct tb_switch *sw) 3198 3151 { ··· 3292 3245 * exposed to the userspace when this function successfully returns. To 3293 3246 * remove and release the switch, call tb_switch_remove(). 3294 3247 * 3295 - * Return: %0 in case of success and negative errno in case of failure 3248 + * Return: %0 on success, negative errno otherwise. 3296 3249 */ 3297 3250 int tb_switch_add(struct tb_switch *sw) 3298 3251 { ··· 3514 3467 * suspend. If this is resume from system sleep, notifies PM core about the 3515 3468 * wakes occurred during suspend. Disables all wakes, except USB4 wake of 3516 3469 * upstream port for USB4 routers that shall be always enabled. 3470 + * 3471 + * Return: %0 on success, negative errno otherwise. 3517 3472 */ 3518 3473 int tb_switch_resume(struct tb_switch *sw, bool runtime) 3519 3474 { ··· 3666 3617 * @in: DP IN port 3667 3618 * 3668 3619 * Queries availability of DP resource for DP tunneling using switch 3669 - * specific means. Returns %true if resource is available. 3620 + * specific means. 3621 + * 3622 + * Return: %true if resource is available, %false otherwise. 3670 3623 */ 3671 3624 bool tb_switch_query_dp_resource(struct tb_switch *sw, struct tb_port *in) 3672 3625 { ··· 3684 3633 * 3685 3634 * Allocates DP resource for DP tunneling. The resource must be 3686 3635 * available for this to succeed (see tb_switch_query_dp_resource()). 3687 - * Returns %0 in success and negative errno otherwise. 3636 + * 3637 + * Return: %0 on success, negative errno otherwise. 3688 3638 */ 3689 3639 int tb_switch_alloc_dp_resource(struct tb_switch *sw, struct tb_port *in) 3690 3640 { ··· 3770 3718 * 3771 3719 * Returned switch has reference count increased so the caller needs to 3772 3720 * call tb_switch_put() when done with the switch. 3721 + * 3722 + * Return: Pointer to &struct tb_switch, %NULL if not found. 3773 3723 */ 3774 3724 struct tb_switch *tb_switch_find_by_link_depth(struct tb *tb, u8 link, u8 depth) 3775 3725 { ··· 3797 3743 * 3798 3744 * Returned switch has reference count increased so the caller needs to 3799 3745 * call tb_switch_put() when done with the switch. 3746 + * 3747 + * Return: Pointer to &struct tb_switch, %NULL if not found. 3800 3748 */ 3801 3749 struct tb_switch *tb_switch_find_by_uuid(struct tb *tb, const uuid_t *uuid) 3802 3750 { ··· 3823 3767 * 3824 3768 * Returned switch has reference count increased so the caller needs to 3825 3769 * call tb_switch_put() when done with the switch. 3770 + * 3771 + * Return: Pointer to &struct tb_switch, %NULL if not found. 3826 3772 */ 3827 3773 struct tb_switch *tb_switch_find_by_route(struct tb *tb, u64 route) 3828 3774 { ··· 3849 3791 * tb_switch_find_port() - return the first port of @type on @sw or NULL 3850 3792 * @sw: Switch to find the port from 3851 3793 * @type: Port type to look for 3794 + * 3795 + * Return: Pointer to &struct tb_port, %NULL if not found. 3852 3796 */ 3853 3797 struct tb_port *tb_switch_find_port(struct tb_switch *sw, 3854 3798 enum tb_port_type type) ··· 3919 3859 * entry to PCIe L1 state. Shall be called after the upstream PCIe tunnel 3920 3860 * was configured. Due to Intel platforms limitation, shall be called only 3921 3861 * for first hop switch. 3862 + * 3863 + * Return: %0 on success, negative errno otherwise. 3922 3864 */ 3923 3865 int tb_switch_pcie_l1_enable(struct tb_switch *sw) 3924 3866 { ··· 3955 3893 * connected to the type-C port. Call only after PCIe tunnel has been 3956 3894 * established. The function only does the connect if not done already 3957 3895 * so can be called several times for the same router. 3896 + * 3897 + * Return: %0 on success, negative errno otherwise. 3958 3898 */ 3959 3899 int tb_switch_xhci_connect(struct tb_switch *sw) 3960 3900 {

Configure Feed

Configure Feed