thunderbolt: Update usb4.c function documentation

+229 -104

1 changed file

expand all

drivers

thunderbolt

usb4.c

+229 -104

drivers/thunderbolt/usb4.c

··· 237 237 * 238 238 * This does not set the configuration valid bit of the router. To do 239 239 * that call usb4_switch_configuration_valid(). 240 + * 241 + * Return: %0 on success, negative errno otherwise. 240 242 */ 241 243 int usb4_switch_setup(struct tb_switch *sw) 242 244 { ··· 306 304 * usb4_switch_setup() has been called. Can be called to host and device 307 305 * routers (does nothing for the latter). 308 306 * 309 - * Returns %0 in success and negative errno otherwise. 307 + * Return: %0 on success, negative errno otherwise. 310 308 */ 311 309 int usb4_switch_configuration_valid(struct tb_switch *sw) 312 310 { ··· 336 334 * @uid: UID is stored here 337 335 * 338 336 * Reads 64-bit UID from USB4 router config space. 337 + * 338 + * Return: %0 on success, negative errno otherwise. 339 339 */ 340 340 int usb4_switch_read_uid(struct tb_switch *sw, u64 *uid) 341 341 { ··· 375 371 * Uses USB4 router operations to read router DROM. For devices this 376 372 * should always work but for hosts it may return %-EOPNOTSUPP in which 377 373 * case the host router does not have DROM. 374 + * 375 + * Return: %0 on success, negative errno otherwise. 378 376 */ 379 377 int usb4_switch_drom_read(struct tb_switch *sw, unsigned int address, void *buf, 380 378 size_t size) ··· 391 385 * 392 386 * Checks whether conditions are met so that lane bonding can be 393 387 * established with the upstream router. Call only for device routers. 388 + * 389 + * Return: %true if lane bonding is possible, %false otherwise. 394 390 */ 395 391 bool usb4_switch_lane_bonding_possible(struct tb_switch *sw) 396 392 { ··· 415 407 * @runtime: Wake is being programmed during system runtime 416 408 * 417 409 * Enables/disables router to wake up from sleep. 410 + * 411 + * Return: %0 on success, negative errno otherwise. 418 412 */ 419 413 int usb4_switch_set_wake(struct tb_switch *sw, unsigned int flags, bool runtime) 420 414 { ··· 494 484 * usb4_switch_set_sleep() - Prepare the router to enter sleep 495 485 * @sw: USB4 router 496 486 * 497 - * Sets sleep bit for the router. Returns when the router sleep ready 487 + * Sets sleep bit for the router and waits until router sleep ready 498 488 * bit has been asserted. 489 + * 490 + * Return: %0 on success, negative errno otherwise. 499 491 */ 500 492 int usb4_switch_set_sleep(struct tb_switch *sw) 501 493 { ··· 523 511 * usb4_switch_nvm_sector_size() - Return router NVM sector size 524 512 * @sw: USB4 router 525 513 * 526 - * If the router supports NVM operations this function returns the NVM 527 - * sector size in bytes. If NVM operations are not supported returns 528 - * %-EOPNOTSUPP. 514 + * Return: 515 + * * NVM sector size in bytes if router supports NVM operations. 516 + * * %-EOPNOTSUPP - If router does not support NVM operations. 517 + * * Negative errno - Another error occurred. 529 518 */ 530 519 int usb4_switch_nvm_sector_size(struct tb_switch *sw) 531 520 { ··· 573 560 * @buf: Read data is placed here 574 561 * @size: How many bytes to read 575 562 * 576 - * Reads NVM contents of the router. If NVM is not supported returns 577 - * %-EOPNOTSUPP. 563 + * Reads NVM contents of the router. 564 + * 565 + * Return: 566 + * * %0 - Read completed successfully. 567 + * * %-EOPNOTSUPP - NVM not supported. 568 + * * Negative errno - Another error occurred. 578 569 */ 579 570 int usb4_switch_nvm_read(struct tb_switch *sw, unsigned int address, void *buf, 580 571 size_t size) ··· 595 578 * Explicitly sets NVM write offset. Normally when writing to NVM this 596 579 * is done automatically by usb4_switch_nvm_write(). 597 580 * 598 - * Returns %0 in success and negative errno if there was a failure. 581 + * Return: %0 on success, negative errno otherwise. 599 582 */ 600 583 int usb4_switch_nvm_set_offset(struct tb_switch *sw, unsigned int address) 601 584 { ··· 637 620 * @buf: Pointer to the data to write 638 621 * @size: Size of @buf in bytes 639 622 * 640 - * Writes @buf to the router NVM using USB4 router operations. If NVM 641 - * write is not supported returns %-EOPNOTSUPP. 623 + * Writes @buf to the router NVM using USB4 router operations. 624 + * 625 + * Return: 626 + * * %0 - Write completed successfully. 627 + * * %-EOPNOTSUPP - NVM write not supported. 628 + * * Negative errno - Another error occurred. 642 629 */ 643 630 int usb4_switch_nvm_write(struct tb_switch *sw, unsigned int address, 644 631 const void *buf, size_t size) ··· 664 643 * After the new NVM has been written via usb4_switch_nvm_write(), this 665 644 * function triggers NVM authentication process. The router gets power 666 645 * cycled and if the authentication is successful the new NVM starts 667 - * running. In case of failure returns negative errno. 646 + * running. 668 647 * 669 648 * The caller should call usb4_switch_nvm_authenticate_status() to read 670 649 * the status of the authentication after power cycle. It should be the 671 650 * first router operation to avoid the status being lost. 651 + * 652 + * Return: %0 on success, negative errno otherwise. 672 653 */ 673 654 int usb4_switch_nvm_authenticate(struct tb_switch *sw) 674 655 { ··· 698 675 * @status: Status code of the operation 699 676 * 700 677 * The function checks if there is status available from the last NVM 701 - * authenticate router operation. If there is status then %0 is returned 702 - * and the status code is placed in @status. Returns negative errno in case 703 - * of failure. 678 + * authenticate router operation. 704 679 * 705 680 * Must be called before any other router operation. 681 + * 682 + * Return: 683 + * * %0 - If there is status. Status code is placed in @status. 684 + * * Negative errno - Failure occurred. 706 685 */ 707 686 int usb4_switch_nvm_authenticate_status(struct tb_switch *sw, u32 *status) 708 687 { ··· 748 723 * allocation fields accordingly. Specifically @sw->credits_allocation 749 724 * is set to %true if these parameters can be used in tunneling. 750 725 * 751 - * Returns %0 on success and negative errno otherwise. 726 + * Return: %0 on success, negative errno otherwise. 752 727 */ 753 728 int usb4_switch_credits_init(struct tb_switch *sw) 754 729 { ··· 887 862 * @in: DP IN adapter 888 863 * 889 864 * For DP tunneling this function can be used to query availability of 890 - * DP IN resource. Returns true if the resource is available for DP 891 - * tunneling, false otherwise. 865 + * DP IN resource. 866 + * 867 + * Return: %true if the resource is available for DP tunneling, %false 868 + * otherwise. 892 869 */ 893 870 bool usb4_switch_query_dp_resource(struct tb_switch *sw, struct tb_port *in) 894 871 { ··· 918 891 * @in: DP IN adapter 919 892 * 920 893 * Allocates DP IN resource for DP tunneling using USB4 router 921 - * operations. If the resource was allocated returns %0. Otherwise 922 - * returns negative errno, in particular %-EBUSY if the resource is 923 - * already allocated. 894 + * operations. 895 + * 896 + * Return: 897 + * * %0 - Resource allocated successfully. 898 + * * %-EBUSY - Resource is already allocated. 899 + * * Negative errno - Other failure occurred. 924 900 */ 925 901 int usb4_switch_alloc_dp_resource(struct tb_switch *sw, struct tb_port *in) 926 902 { ··· 947 917 * @in: DP IN adapter 948 918 * 949 919 * Releases the previously allocated DP IN resource. 920 + * 921 + * Return: %0 on success, negative errno otherwise. 950 922 */ 951 923 int usb4_switch_dealloc_dp_resource(struct tb_switch *sw, struct tb_port *in) 952 924 { ··· 1004 972 * downstream adapters where the PCIe topology is extended. This 1005 973 * function returns the corresponding downstream PCIe adapter or %NULL 1006 974 * if no such mapping was possible. 975 + * 976 + * Return: Pointer to &struct tb_port or %NULL if not found. 1007 977 */ 1008 978 struct tb_port *usb4_switch_map_pcie_down(struct tb_switch *sw, 1009 979 const struct tb_port *port) ··· 1037 1003 * downstream adapters where the USB 3.x topology is extended. This 1038 1004 * function returns the corresponding downstream USB 3.x adapter or 1039 1005 * %NULL if no such mapping was possible. 1006 + * 1007 + * Return: Pointer to &struct tb_port or %NULL if not found. 1040 1008 */ 1041 1009 struct tb_port *usb4_switch_map_usb3_down(struct tb_switch *sw, 1042 1010 const struct tb_port *port) ··· 1068 1032 * For USB4 router finds all USB4 ports and registers devices for each. 1069 1033 * Can be called to any router. 1070 1034 * 1071 - * Return %0 in case of success and negative errno in case of failure. 1035 + * Return: %0 on success, negative errno otherwise. 1072 1036 */ 1073 1037 int usb4_switch_add_ports(struct tb_switch *sw) 1074 1038 { ··· 1121 1085 * 1122 1086 * Unlocks USB4 downstream port so that the connection manager can 1123 1087 * access the router below this port. 1088 + * 1089 + * Return: %0 on success, negative errno otherwise. 1124 1090 */ 1125 1091 int usb4_port_unlock(struct tb_port *port) 1126 1092 { ··· 1143 1105 * 1144 1106 * Enables hot plug events on a given port. This is only intended 1145 1107 * to be used on lane, DP-IN, and DP-OUT adapters. 1108 + * 1109 + * Return: %0 on success, negative errno otherwise. 1146 1110 */ 1147 1111 int usb4_port_hotplug_enable(struct tb_port *port) 1148 1112 { ··· 1164 1124 * @port: USB4 port to reset 1165 1125 * 1166 1126 * Issues downstream port reset to @port. 1127 + * 1128 + * Return: %0 on success, negative errno otherwise. 1167 1129 */ 1168 1130 int usb4_port_reset(struct tb_port *port) 1169 1131 { ··· 1227 1185 * @port: USB4 router 1228 1186 * 1229 1187 * Sets the USB4 link to be configured for power management purposes. 1188 + * 1189 + * Return: %0 on success, negative errno otherwise. 1230 1190 */ 1231 1191 int usb4_port_configure(struct tb_port *port) 1232 1192 { ··· 1240 1196 * @port: USB4 router 1241 1197 * 1242 1198 * Sets the USB4 link to be unconfigured for power management purposes. 1199 + * 1200 + * Return: %0 on success, negative errno otherwise. 1243 1201 */ 1244 1202 void usb4_port_unconfigure(struct tb_port *port) 1245 1203 { ··· 1276 1230 * @xd: XDomain that is connected to the port 1277 1231 * 1278 1232 * Marks the USB4 port as being connected to another host and updates 1279 - * the link type. Returns %0 in success and negative errno in failure. 1233 + * the link type. 1234 + * 1235 + * Return: %0 on success, negative errno otherwise. 1280 1236 */ 1281 1237 int usb4_port_configure_xdomain(struct tb_port *port, struct tb_xdomain *xd) 1282 1238 { ··· 1348 1300 * @size: Size of @buf 1349 1301 * 1350 1302 * Reads data from sideband register @reg and copies it into @buf. 1351 - * Returns %0 in case of success and negative errno in case of failure. 1303 + * 1304 + * Return: %0 on success, negative errno otherwise. 1352 1305 */ 1353 1306 int usb4_port_sb_read(struct tb_port *port, enum usb4_sb_target target, u8 index, 1354 1307 u8 reg, void *buf, u8 size) ··· 1400 1351 * @buf: Data to write 1401 1352 * @size: Size of @buf 1402 1353 * 1403 - * Writes @buf to sideband register @reg. Returns %0 in case of success 1404 - * and negative errno in case of failure. 1354 + * Writes @buf to sideband register @reg. 1355 + * 1356 + * Return: %0 on success, negative errno otherwise. 1405 1357 */ 1406 1358 int usb4_port_sb_write(struct tb_port *port, enum usb4_sb_target target, 1407 1359 u8 index, u8 reg, const void *buf, u8 size) ··· 1519 1469 * port does not react on hotplug events anymore. This needs to be 1520 1470 * called before retimer access is done when the USB4 links is not up. 1521 1471 * 1522 - * Returns %0 in case of success and negative errno if there was an 1523 - * error. 1472 + * Return: %0 on success, negative errno otherwise. 1524 1473 */ 1525 1474 int usb4_port_router_offline(struct tb_port *port) 1526 1475 { ··· 1531 1482 * @port: USB4 port 1532 1483 * 1533 1484 * Makes the USB4 port functional again. 1485 + * 1486 + * Return: %0 on success, negative errno otherwise. 1534 1487 */ 1535 1488 int usb4_port_router_online(struct tb_port *port) 1536 1489 { ··· 1544 1493 * @port: USB4 port 1545 1494 * 1546 1495 * This forces the USB4 port to send broadcast RT transaction which 1547 - * makes the retimers on the link to assign index to themselves. Returns 1548 - * %0 in case of success and negative errno if there was an error. 1496 + * makes the retimers on the link assign index to themselves. 1497 + * 1498 + * Return: %0 on success, negative errno otherwise. 1549 1499 */ 1550 1500 int usb4_port_enumerate_retimers(struct tb_port *port) 1551 1501 { ··· 1563 1511 * 1564 1512 * PORT_CS_18_CPS bit reflects if the link supports CLx including 1565 1513 * active cables (if connected on the link). 1514 + * 1515 + * Return: %true if Clx is supported, %false otherwise. 1566 1516 */ 1567 1517 bool usb4_port_clx_supported(struct tb_port *port) 1568 1518 { ··· 1583 1529 * usb4_port_asym_supported() - If the port supports asymmetric link 1584 1530 * @port: USB4 port 1585 1531 * 1586 - * Checks if the port and the cable supports asymmetric link and returns 1587 - * %true in that case. 1532 + * Checks if the port and the cable support asymmetric link. 1533 + * 1534 + * Return: %true if asymmetric link is supported, %false otherwise. 1588 1535 */ 1589 1536 bool usb4_port_asym_supported(struct tb_port *port) 1590 1537 { ··· 1607 1552 * 1608 1553 * Sets USB4 port link width to @width. Can be called for widths where 1609 1554 * usb4_port_asym_width_supported() returned @true. 1555 + * 1556 + * Return: %0 on success, negative errno otherwise. 1610 1557 */ 1611 1558 int usb4_port_asym_set_link_width(struct tb_port *port, enum tb_link_width width) 1612 1559 { ··· 1653 1596 * (according to what was previously set in tb_port_set_link_width(). 1654 1597 * Wait for completion of the change. 1655 1598 * 1656 - * Returns %0 in case of success, %-ETIMEDOUT if case of timeout or 1657 - * a negative errno in case of a failure. 1599 + * Return: 1600 + * * %0 - Symmetry change was successful. 1601 + * * %-ETIMEDOUT - Timeout occurred. 1602 + * * Negative errno - Other failure occurred. 1658 1603 */ 1659 1604 int usb4_port_asym_start(struct tb_port *port) 1660 1605 { ··· 1700 1641 * @ncaps: Number of elements in the caps array 1701 1642 * 1702 1643 * Reads the USB4 port lane margining capabilities into @caps. 1644 + * 1645 + * Return: %0 on success, negative errno otherwise. 1703 1646 */ 1704 1647 int usb4_port_margining_caps(struct tb_port *port, enum usb4_sb_target target, 1705 1648 u8 index, u32 *caps, size_t ncaps) ··· 1728 1667 * 1729 1668 * Runs hardware lane margining on USB4 port and returns the result in 1730 1669 * @results. 1670 + * 1671 + * Return: %0 on success, negative errno otherwise. 1731 1672 */ 1732 1673 int usb4_port_hw_margin(struct tb_port *port, enum usb4_sb_target target, 1733 1674 u8 index, const struct usb4_port_margining_params *params, ··· 1774 1711 * @results: Data word for the operation completion data 1775 1712 * 1776 1713 * Runs software lane margining on USB4 port. Read back the error 1777 - * counters by calling usb4_port_sw_margin_errors(). Returns %0 in 1778 - * success and negative errno otherwise. 1714 + * counters by calling usb4_port_sw_margin_errors(). 1715 + * 1716 + * Return: %0 on success, negative errno otherwise. 1779 1717 */ 1780 1718 int usb4_port_sw_margin(struct tb_port *port, enum usb4_sb_target target, 1781 1719 u8 index, const struct usb4_port_margining_params *params, ··· 1823 1759 * @errors: Error metadata is copied here. 1824 1760 * 1825 1761 * This reads back the software margining error counters from the port. 1826 - * Returns %0 in success and negative errno otherwise. 1762 + * 1763 + * Return: %0 on success, negative errno otherwise. 1827 1764 */ 1828 1765 int usb4_port_sw_margin_errors(struct tb_port *port, enum usb4_sb_target target, 1829 1766 u8 index, u32 *errors) ··· 1855 1790 * 1856 1791 * Enables sideband channel transations on SBTX. Can be used when USB4 1857 1792 * link does not go up, for example if there is no device connected. 1793 + * 1794 + * Return: %0 on success, negative errno otherwise. 1858 1795 */ 1859 1796 int usb4_port_retimer_set_inbound_sbtx(struct tb_port *port, u8 index) 1860 1797 { ··· 1884 1817 * 1885 1818 * Disables sideband channel transations on SBTX. The reverse of 1886 1819 * usb4_port_retimer_set_inbound_sbtx(). 1820 + * 1821 + * Return: %0 on success, negative errno otherwise. 1887 1822 */ 1888 1823 int usb4_port_retimer_unset_inbound_sbtx(struct tb_port *port, u8 index) 1889 1824 { ··· 1898 1829 * @port: USB4 port 1899 1830 * @index: Retimer index 1900 1831 * 1901 - * If the retimer at @index is last one (connected directly to the 1902 - * Type-C port) this function returns %1. If it is not returns %0. If 1903 - * the retimer is not present returns %-ENODEV. Otherwise returns 1904 - * negative errno. 1832 + * Return: 1833 + * * %1 - Retimer at @index is the last one (connected directly to the 1834 + * Type-C port). 1835 + * * %0 - Retimer at @index is not the last one. 1836 + * * %-ENODEV - Retimer is not present. 1837 + * * Negative errno - Other failure occurred. 1905 1838 */ 1906 1839 int usb4_port_retimer_is_last(struct tb_port *port, u8 index) 1907 1840 { ··· 1925 1854 * @port: USB4 port 1926 1855 * @index: Retimer index 1927 1856 * 1928 - * If the retimer at @index is last cable retimer this function returns 1929 - * %1 and %0 if it is on-board retimer. In case a retimer is not present 1930 - * at @index returns %-ENODEV. Otherwise returns negative errno. 1857 + * Return: 1858 + * * %1 - Retimer at @index is the last cable retimer. 1859 + * * %0 - Retimer at @index is on-board retimer. 1860 + * * %-ENODEV - Retimer is not present. 1861 + * * Negative errno - Other failure occurred. 1931 1862 */ 1932 1863 int usb4_port_retimer_is_cable(struct tb_port *port, u8 index) 1933 1864 { ··· 1953 1880 * 1954 1881 * Reads NVM sector size (in bytes) of a retimer at @index. This 1955 1882 * operation can be used to determine whether the retimer supports NVM 1956 - * upgrade for example. Returns sector size in bytes or negative errno 1957 - * in case of error. Specifically returns %-ENODEV if there is no 1958 - * retimer at @index. 1883 + * upgrade for example. 1884 + * 1885 + * Return: 1886 + * * Sector size in bytes. 1887 + * * %-ENODEV - If there is no retimer at @index. 1888 + * * Negative errno - In case of an error. 1959 1889 */ 1960 1890 int usb4_port_retimer_nvm_sector_size(struct tb_port *port, u8 index) 1961 1891 { ··· 1984 1908 * Exlicitly sets NVM write offset. Normally when writing to NVM this is 1985 1909 * done automatically by usb4_port_retimer_nvm_write(). 1986 1910 * 1987 - * Returns %0 in success and negative errno if there was a failure. 1911 + * Return: %0 on success, negative errno otherwise. 1988 1912 */ 1989 1913 int usb4_port_retimer_nvm_set_offset(struct tb_port *port, u8 index, 1990 1914 unsigned int address) ··· 2037 1961 * @size: Size in bytes how much to write 2038 1962 * 2039 1963 * Writes @size bytes from @buf to the retimer NVM. Used for NVM 2040 - * upgrade. Returns %0 if the data was written successfully and negative 2041 - * errno in case of failure. Specifically returns %-ENODEV if there is 2042 - * no retimer at @index. 1964 + * upgrade. 1965 + * 1966 + * Return: 1967 + * * %0 - If the data was written successfully. 1968 + * * %-ENODEV - If there is no retimer at @index. 1969 + * * Negative errno - In case of an error. 2043 1970 */ 2044 1971 int usb4_port_retimer_nvm_write(struct tb_port *port, u8 index, unsigned int address, 2045 1972 const void *buf, size_t size) ··· 2068 1989 * successful the retimer restarts with the new NVM and may not have the 2069 1990 * index set so one needs to call usb4_port_enumerate_retimers() to 2070 1991 * force index to be assigned. 1992 + * 1993 + * Return: %0 on success, negative errno otherwise. 2071 1994 */ 2072 1995 int usb4_port_retimer_nvm_authenticate(struct tb_port *port, u8 index) 2073 1996 { ··· 2094 2013 * This can be called after usb4_port_retimer_nvm_authenticate() and 2095 2014 * usb4_port_enumerate_retimers() to fetch status of the NVM upgrade. 2096 2015 * 2097 - * Returns %0 if the authentication status was successfully read. The 2016 + * Return: %0 if the authentication status was successfully read. The 2098 2017 * completion metadata (the result) is then stored into @status. If 2099 - * reading the status fails, returns negative errno. 2018 + * status read fails, returns negative errno. 2100 2019 */ 2101 2020 int usb4_port_retimer_nvm_authenticate_status(struct tb_port *port, u8 index, 2102 2021 u32 *status) ··· 2164 2083 * @buf: Data read from NVM is stored here 2165 2084 * @size: Number of bytes to read 2166 2085 * 2167 - * Reads retimer NVM and copies the contents to @buf. Returns %0 if the 2168 - * read was successful and negative errno in case of failure. 2169 - * Specifically returns %-ENODEV if there is no retimer at @index. 2086 + * Reads retimer NVM and copies the contents to @buf. 2087 + * 2088 + * Return: 2089 + * * %0 - If the read was successful. 2090 + * * %-ENODEV - If there is no retimer at @index. 2091 + * * Negative errno - In case of an error. 2170 2092 */ 2171 2093 int usb4_port_retimer_nvm_read(struct tb_port *port, u8 index, 2172 2094 unsigned int address, void *buf, size_t size) ··· 2193 2109 * usb4_usb3_port_max_link_rate() - Maximum support USB3 link rate 2194 2110 * @port: USB3 adapter port 2195 2111 * 2196 - * Return maximum supported link rate of a USB3 adapter in Mb/s. 2197 - * Negative errno in case of error. 2112 + * Return: Maximum supported link rate of a USB3 adapter in Mb/s. 2113 + * Negative errno in case of an error. 2198 2114 */ 2199 2115 int usb4_usb3_port_max_link_rate(struct tb_port *port) 2200 2116 { ··· 2312 2228 * @downstream_bw: Allocated downstream bandwidth is stored here 2313 2229 * 2314 2230 * Stores currently allocated USB3 bandwidth into @upstream_bw and 2315 - * @downstream_bw in Mb/s. Returns %0 in case of success and negative 2316 - * errno in failure. 2231 + * @downstream_bw in Mb/s. 2232 + * 2233 + * Return: %0 on success, negative errno otherwise. 2317 2234 */ 2318 2235 int usb4_usb3_port_allocated_bandwidth(struct tb_port *port, int *upstream_bw, 2319 2236 int *downstream_bw) ··· 2416 2331 * cannot be taken away by CM). The actual new values are returned in 2417 2332 * @upstream_bw and @downstream_bw. 2418 2333 * 2419 - * Returns %0 in case of success and negative errno if there was a 2420 - * failure. 2334 + * Return: %0 on success, negative errno otherwise. 2421 2335 */ 2422 2336 int usb4_usb3_port_allocate_bandwidth(struct tb_port *port, int *upstream_bw, 2423 2337 int *downstream_bw) ··· 2458 2374 * Releases USB3 allocated bandwidth down to what is actually consumed. 2459 2375 * The new bandwidth is returned in @upstream_bw and @downstream_bw. 2460 2376 * 2461 - * Returns 0% in success and negative errno in case of failure. 2377 + * Return: %0 on success, negative errno otherwise. 2462 2378 */ 2463 2379 int usb4_usb3_port_release_bandwidth(struct tb_port *port, int *upstream_bw, 2464 2380 int *downstream_bw) ··· 2510 2426 * @port: DP IN adapter 2511 2427 * @cm_id: CM ID to assign 2512 2428 * 2513 - * Sets CM ID for the @port. Returns %0 on success and negative errno 2514 - * otherwise. Speficially returns %-EOPNOTSUPP if the @port does not 2515 - * support this. 2429 + * Sets CM ID for the @port. 2430 + * 2431 + * Return: 2432 + * * %0 - On success. 2433 + * * %-EOPNOTSUPP - If the @port does not support this. 2434 + * * Negative errno - Another error occurred. 2516 2435 */ 2517 2436 int usb4_dp_port_set_cm_id(struct tb_port *port, int cm_id) 2518 2437 { ··· 2542 2455 * supported 2543 2456 * @port: DP IN adapter to check 2544 2457 * 2545 - * Can be called to any DP IN adapter. Returns true if the adapter 2546 - * supports USB4 bandwidth allocation mode, false otherwise. 2458 + * Can be called to any DP IN adapter. 2459 + * 2460 + * Return: %true if the adapter supports USB4 bandwidth allocation mode, 2461 + * %false otherwise. 2547 2462 */ 2548 2463 bool usb4_dp_port_bandwidth_mode_supported(struct tb_port *port) 2549 2464 { ··· 2568 2479 * enabled 2569 2480 * @port: DP IN adapter to check 2570 2481 * 2571 - * Can be called to any DP IN adapter. Returns true if the bandwidth 2572 - * allocation mode has been enabled, false otherwise. 2482 + * Can be called to any DP IN adapter. 2483 + * 2484 + * Return: %true if the bandwidth allocation mode has been enabled, 2485 + * %false otherwise. 2573 2486 */ 2574 2487 bool usb4_dp_port_bandwidth_mode_enabled(struct tb_port *port) 2575 2488 { ··· 2596 2505 * @supported: Does the CM support bandwidth allocation mode 2597 2506 * 2598 2507 * Can be called to any DP IN adapter. Sets or clears the CM support bit 2599 - * of the DP IN adapter. Returns %0 in success and negative errno 2600 - * otherwise. Specifically returns %-OPNOTSUPP if the passed in adapter 2601 - * does not support this. 2508 + * of the DP IN adapter. 2509 + * 2510 + * * Return: 2511 + * * %0 - On success. 2512 + * * %-EOPNOTSUPP - If the passed IN adapter does not support this. 2513 + * * Negative errno - Another error occurred. 2602 2514 */ 2603 2515 int usb4_dp_port_set_cm_bandwidth_mode_supported(struct tb_port *port, 2604 2516 bool supported) ··· 2631 2537 * @port: DP IN adapter 2632 2538 * 2633 2539 * Reads bandwidth allocation Group ID from the DP IN adapter and 2634 - * returns it. If the adapter does not support setting Group_ID 2635 - * %-EOPNOTSUPP is returned. 2540 + * returns it. 2541 + * 2542 + * Return: 2543 + * * Group ID assigned to adapter @port. 2544 + * * %-EOPNOTSUPP - If adapter does not support setting GROUP_ID. 2545 + * * Negative errno - Another error occurred. 2636 2546 */ 2637 2547 int usb4_dp_port_group_id(struct tb_port *port) 2638 2548 { ··· 2660 2562 * @group_id: Group ID for the adapter 2661 2563 * 2662 2564 * Sets bandwidth allocation mode Group ID for the DP IN adapter. 2663 - * Returns %0 in case of success and negative errno otherwise. 2664 - * Specifically returns %-EOPNOTSUPP if the adapter does not support 2665 - * this. 2565 + * 2566 + * Return: 2567 + * * %0 - On success. 2568 + * * %-EOPNOTSUPP - If the adapter does not support this. 2569 + * * Negative errno - Another error occurred. 2666 2570 */ 2667 2571 int usb4_dp_port_set_group_id(struct tb_port *port, int group_id) 2668 2572 { ··· 2692 2592 * @rate: Non-reduced rate in Mb/s is placed here 2693 2593 * @lanes: Non-reduced lanes are placed here 2694 2594 * 2695 - * Reads the non-reduced rate and lanes from the DP IN adapter. Returns 2696 - * %0 in success and negative errno otherwise. Specifically returns 2697 - * %-EOPNOTSUPP if the adapter does not support this. 2595 + * Reads the non-reduced rate and lanes from the DP IN adapter. 2596 + * 2597 + * Return: 2598 + * * %0 - On success. 2599 + * * %-EOPNOTSUPP - If the adapter does not support this. 2600 + * * Negative errno - Another error occurred. 2698 2601 */ 2699 2602 int usb4_dp_port_nrd(struct tb_port *port, int *rate, int *lanes) 2700 2603 { ··· 2750 2647 * @rate: Non-reduced rate in Mb/s 2751 2648 * @lanes: Non-reduced lanes 2752 2649 * 2753 - * Before the capabilities reduction this function can be used to set 2754 - * the non-reduced values for the DP IN adapter. Returns %0 in success 2755 - * and negative errno otherwise. If the adapter does not support this 2756 - * %-EOPNOTSUPP is returned. 2650 + * Before the capabilities reduction, this function can be used to set 2651 + * the non-reduced values for the DP IN adapter. 2652 + * 2653 + * Return: 2654 + * * %0 - On success. 2655 + * * %-EOPNOTSUPP - If the adapter does not support this. 2656 + * * Negative errno - Another error occurred. 2757 2657 */ 2758 2658 int usb4_dp_port_set_nrd(struct tb_port *port, int rate, int lanes) 2759 2659 { ··· 2815 2709 * usb4_dp_port_granularity() - Return granularity for the bandwidth values 2816 2710 * @port: DP IN adapter 2817 2711 * 2818 - * Reads the programmed granularity from @port. If the DP IN adapter does 2819 - * not support bandwidth allocation mode returns %-EOPNOTSUPP and negative 2820 - * errno in other error cases. 2712 + * Reads the programmed granularity from @port. 2713 + * 2714 + * Return: 2715 + * * Granularity value of a @port. 2716 + * * %-EOPNOTSUPP - If the DP IN adapter does not support bandwidth 2717 + * allocation mode. 2718 + * * Negative errno - Another error occurred. 2821 2719 */ 2822 2720 int usb4_dp_port_granularity(struct tb_port *port) 2823 2721 { ··· 2857 2747 * @granularity: Granularity in Mb/s. Supported values: 1000, 500 and 250. 2858 2748 * 2859 2749 * Sets the granularity used with the estimated, allocated and requested 2860 - * bandwidth. Returns %0 in success and negative errno otherwise. If the 2861 - * adapter does not support this %-EOPNOTSUPP is returned. 2750 + * bandwidth. 2751 + * 2752 + * Return: 2753 + * * %0 - On success. 2754 + * * %-EOPNOTSUPP - If the adapter does not support this. 2755 + * * Negative errno - Another error occurred. 2862 2756 */ 2863 2757 int usb4_dp_port_set_granularity(struct tb_port *port, int granularity) 2864 2758 { ··· 2903 2789 * @bw: Estimated bandwidth in Mb/s. 2904 2790 * 2905 2791 * Sets the estimated bandwidth to @bw. Set the granularity by calling 2906 - * usb4_dp_port_set_granularity() before calling this. The @bw is round 2907 - * down to the closest granularity multiplier. Returns %0 in success 2908 - * and negative errno otherwise. Specifically returns %-EOPNOTSUPP if 2909 - * the adapter does not support this. 2792 + * usb4_dp_port_set_granularity() before calling this. The @bw is rounded 2793 + * down to the closest granularity multiplier. 2794 + * 2795 + * Return: 2796 + * * %0 - On success. 2797 + * * %-EOPNOTSUPP - If the adapter does not support this. 2798 + * * Negative errno - Another error occurred. 2910 2799 */ 2911 2800 int usb4_dp_port_set_estimated_bandwidth(struct tb_port *port, int bw) 2912 2801 { ··· 2940 2823 * usb4_dp_port_allocated_bandwidth() - Return allocated bandwidth 2941 2824 * @port: DP IN adapter 2942 2825 * 2943 - * Reads and returns allocated bandwidth for @port in Mb/s (taking into 2944 - * account the programmed granularity). Returns negative errno in case 2945 - * of error. 2826 + * Reads the allocated bandwidth for @port in Mb/s (taking into account 2827 + * the programmed granularity). 2828 + * 2829 + * Return: Allocated bandwidth in Mb/s or negative errno in case of an error. 2946 2830 */ 2947 2831 int usb4_dp_port_allocated_bandwidth(struct tb_port *port) 2948 2832 { ··· 3038 2920 * @bw: New allocated bandwidth in Mb/s 3039 2921 * 3040 2922 * Communicates the new allocated bandwidth with the DPCD (graphics 3041 - * driver). Takes into account the programmed granularity. Returns %0 in 3042 - * success and negative errno in case of error. 2923 + * driver). Takes into account the programmed granularity. 2924 + * 2925 + * Return: %0 on success, negative errno otherwise. 3043 2926 */ 3044 2927 int usb4_dp_port_allocate_bandwidth(struct tb_port *port, int bw) 3045 2928 { ··· 3080 2961 * @port: DP IN adapter 3081 2962 * 3082 2963 * Reads the DPCD (graphics driver) requested bandwidth and returns it 3083 - * in Mb/s. Takes the programmed granularity into account. In case of 3084 - * error returns negative errno. Specifically returns %-EOPNOTSUPP if 3085 - * the adapter does not support bandwidth allocation mode, and %ENODATA 3086 - * if there is no active bandwidth request from the graphics driver. 2964 + * in Mb/s. Takes the programmed granularity into account. 2965 + * 2966 + * Return: 2967 + * * Requested bandwidth in Mb/s - On success. 2968 + * * %-EOPNOTSUPP - If the adapter does not support bandwidth allocation 2969 + * mode. 2970 + * * %ENODATA - If there is no active bandwidth request from the graphics 2971 + * driver. 2972 + * * Negative errno - On failure. 3087 2973 */ 3088 2974 int usb4_dp_port_requested_bandwidth(struct tb_port *port) 3089 2975 { ··· 3120 2996 * @enable: Enable/disable extended encapsulation 3121 2997 * 3122 2998 * Enables or disables extended encapsulation used in PCIe tunneling. Caller 3123 - * needs to make sure both adapters support this before enabling. Returns %0 on 3124 - * success and negative errno otherwise. 2999 + * needs to make sure both adapters support this before enabling. 3000 + * 3001 + * Return: %0 on success, negative errno otherwise. 3125 3002 */ 3126 3003 int usb4_pci_port_set_ext_encapsulation(struct tb_port *port, bool enable) 3127 3004 {

Configure Feed

Configure Feed