diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index f0f8f521f65bcf70959f275b1a192c8a26b55420..f2c5d67d47e96e797d21d7513ea75797122727f7 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -115,6 +115,7 @@ available subsections can be seen below. hte/index wmi crypto/index + ub/index .. only:: subproject and html diff --git a/Documentation/driver-api/ub/index.rst b/Documentation/driver-api/ub/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..b4f8fdc580a8d1940940e40941b7c6ea8b375c6f --- /dev/null +++ b/Documentation/driver-api/ub/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Copyright: |copy| 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +============================================= +The Linux UnifiedBus implementer's API guide +============================================= + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 1 + + ubase diff --git a/Documentation/driver-api/ub/ubase.rst b/Documentation/driver-api/ub/ubase.rst new file mode 100644 index 0000000000000000000000000000000000000000..f2ba1c1bd9ca3a213ac67bd87a3534d3ee1fa182 --- /dev/null +++ b/Documentation/driver-api/ub/ubase.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +:Copyright: |copy| 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +UBASE Driver Support Library +----------------------------- + +.. kernel-doc:: include/ub/ubase/ubase_comm_cmd.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_ctrlq.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_debugfs.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_dev.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_eq.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_hw.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_mbx.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_qos.h + :functions: + +.. kernel-doc:: include/ub/ubase/ubase_comm_stats.h + :functions: + +.. kernel-doc:: drivers/ub/ubase/ubase_cmd.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_ctrlq.c + :export: + +.. kernel-doc:: drivers/ub/ubase/debugfs/ubase_debugfs.c + :export: + +.. kernel-doc:: drivers/ub/ubase/debugfs/ubase_ctx_debugfs.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_dev.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_pmem.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_eq.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_mailbox.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_qos_hw.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_stats.c + :export: + +.. kernel-doc:: drivers/ub/ubase/ubase_hw.c + :export: diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 7a356dc40ca2e7fa18f412b0211a6453a10302e8..113a049289000dd8311f3771d5a6325a1aff5930 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -115,6 +115,7 @@ Contents: tproxy tuntap udplite + ub/index vrf vxlan x25 diff --git a/Documentation/networking/ub/index.rst b/Documentation/networking/ub/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..a494d7c04c01e973ca1c8b4907b112b310164e73 --- /dev/null +++ b/Documentation/networking/ub/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: + +:Copyright: |copy| 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +=============================== +The UB Networking documentation +=============================== + +.. toctree:: + :maxdepth: 1 + + UB Link Layer + UNIC Driver diff --git a/Documentation/networking/ub/ubl.rst b/Documentation/networking/ub/ubl.rst new file mode 100644 index 0000000000000000000000000000000000000000..67abc16ba052fcf19e961fd4888860b0e27c2207 --- /dev/null +++ b/Documentation/networking/ub/ubl.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Copyright (c) 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +============= +UB Link Layer +============= + +Overview +======== +The ubl module implements core UB (UnifiedBus) networking functionality that +serves as the foundation for all UB networking device drivers. This module +provides essential UB link protocol handling, device setup utilities, and +standard operations that are shared across different UB networking hardware +implementations. + +UB is a new interconnection protocol that defines its own Layer 2 protocol +when integrating into the networking stack for the Linux kernel, see more +in the UB spec . + +The format of a complete UB packet is as follows: +UB Link header (UBL HDR) includes UB LINK, CC and NPI. +UB Network header consists of CC, NPI, and traditional network packet headers. + +.. code-block:: none + + <-------- UBL HDR -----------> + +--------------+------+------+---------+----------+ + | UB LINK | CC | NPI | Network | Payload | + +--------------+------+------+---------+----------+ + <------ UB Network -----> + + UB LINK: Data link layer defined by UB protocol. + CC: Congestion Control. + NPI: Network Partition Identifier. + Network: Traditional L3 header, like IPv4, IPv6 or the network control header + defined in UB. + +What the ubl module sees is as follows, as the 'cfg' field is carried through +BD (Buffer Description) for hw to construct UB LINK, the 'sw_ctype' is used +in ubl module, which corresponds to the 'cfg' field defined in UB LINK, +indicating which kind of network packet is encapsulated. + +.. kernel-doc:: include/net/ub/ubl.h + :identifiers: ublhdr + +API interface +============= +Before registering `struct net_device` to the networking stack, a UB networking +driver is supposed to allocate and set up a `struct net_device` by calling +alloc_ubldev_mqs(). + +Before passing a skb to the driver for sending, networking stack will insert the +necessary UB link layer by calling ubl_create_header() through create ops in +struct header_ops. + +Also, the driver is supposed to call ubl_type_trans() to set up the skb +correctly when it receives a packet. + +.. kernel-doc:: drivers/net/ub/dev/ubl.c + :identifiers: alloc_ubldev_mqs ubl_create_header ubl_type_trans + +An example of using the above API is the unic driver, see more detail using in +:ref:`Documentation/networking/ub/unic.rst` + +Technical Discussion +==================== +If there is any technical question about UB link layer, please start a technical +discussion by sending a mail to . diff --git a/Documentation/networking/ub/unic.rst b/Documentation/networking/ub/unic.rst new file mode 100644 index 0000000000000000000000000000000000000000..902a81c17d7f645ac3b38d5cf223a20b34353acc --- /dev/null +++ b/Documentation/networking/ub/unic.rst @@ -0,0 +1,281 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Copyright (c) 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +=========== +UNIC Driver +=========== + +Overview +======== +unic is a UB (UnifiedBus) networking driver based on ubase driver's auxiliary +device through auxiliary bus, supporting both ethernet and UB link layer. +See :ref:`Documentation/ub/ubase/ubase.rst` for more information about ubase +driver and :ref:`Documentation/networking/ub/ubl.rst` for more information about +UB link layer. + +.. code-block:: none + + +---------------------------------------------------------------+ + | networking stack | + +---------------------------------------------------------------+ + ^ ^ ^ + | | | + | | | + v | v + +----------------+ | +---------------+ + | Ethernet Layer | | | UB Link Layer | + +----------------+ | +---------------+ + ^ | ^ + | | | + | | | + v v v + +---------------------------------------------------------------+ + | | + | unic | + | | + | +------+ +-----+ +--------+ +---------+ +-------+ +---------+ | + | | main | | dev | | netdev | | ethtool | | dcbnl | | tx & rx | | + | +------+ +-----+ +--------+ +---------+ +-------+ +---------+ | + | +---------+ +-----------+ +-----+ +---------+ +-------+ | + | | channel | | comm_addr | | crq | | rack_ip | | reset | | + | +---------+ +-----------+ +-----+ +---------+ +-------+. | + | +----+ +--------+ +-------+ +-------+ +------+ | + | | hw | | qos_hw | | event | | stats | | guid | | + | +----+ +--------+ +-------+ +-------+ +------+ | + +---------------------------------------------------------------+ + ^ ^ + | | + | | + v | + +-------------------------------+ | + | auxiliary_bus | | + +-------------------------------+ | + ^ | + | | + | | + v v + +---------------------------------------------------------------+ + | ubase | + +---------------------------------------------------------------+ + +The main submodules in unic driver: + +:: + + main + implement module_init(), module_exit() and 'struct auxiliary_driver' for + the auxiliary device of ubase driver. + + dev + implement init & uninit function and periodic task handling for unic's + netdev. + + netdev + implement 'struct net_device_ops' for unic's netdev. + + ethtool + implement 'struct ethtool_ops' for unic's netdev. + + dcbnl + implement 'dcbnl_rtnl_ops' for unic's netdev. + + tx & rx + implement packet send and receive handling. + + channel + implement channel handling for unic's netdev. + + comm_addr & rack_ip + implement the ip address handling in UB mode. + + reset + implement the entity reset handling. + + crq + implement link status change handling through ctrl (Control) receive queue. + + hw & qos_hw + implement generic hw and qos related configuration access function. + + stats + implement hw statistics collecting funciton. + + event + implement asynchronous event reporting interface. + + guid + implement the GUI (Globally Unique Identifier) querying in UB mode. + +Hardware Supported +================== + +This driver is compatible with below UB devices: + +.. code-block:: none + + +--------------+--------------+ + | Vendor ID | Device ID | + +==============+==============+ + | 0xCC08 | 0xA001 | + +--------------+--------------+ + | 0xCC08 | 0xD802 | + +--------------+--------------+ + | 0xCC08 | 0xD80B | + +--------------+--------------+ + +Note 'lsub' from ubutils package can be used to tell if the above device is +available in the system, see : + +:: + + # lsub + <00009> UB network controller <0002>: Huawei Technologies Co., Ltd. URMA management ub entity : + +Additional Features and Configurations +====================================== + +UB Link +------- +UB Link is a link layer defined by UB, which has the same layer of the existing +ethernet, and firmware will report the mode of the hardware port to the driver +through hardware capability reporting, UB_Link or ETH_MAC. + +In UB mode, the link layer is UB and its L2 address is the GUID as below +example: + +:: + + # ip -s addr + 1: ublc0d0e2: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000 + link/ub cc:08:d8:02:d2:0a:00:00:00:00:00:00:00:00:00:01 peer 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 + +Note: port speed auto-negotiation is not supported in UB mode. + + +IP Address Configuration +------------------------ +IP address configuration must be performed by the management software, after +receiving the IP address configuration through crq event, the driver will +update the IP address configuration to networking stack using the netlink API. + +ELR support +----------- +ELR (Entity Level Reset) is the error recovery defined in UB, which can be +triggered by packet transmiting timeout, see unic_tx_timeout() or using the +below cmd to trigger ELR manually: + +:: + + # ethtool --reset dedicated + # echo 1 > /sys/class/net//device/reset + +Debugging +========= + +module parameters +----------------- +Enable more verbose unic driver specific debug message log by setting **debug** +to non-zero, and enable network interface debug message log by configuring +**netif_debug**, for example: + +:: + + # insmod unic.ko debug=1 netif_debug=0xFFFFF + +Debugfs Interface +----------------- +When CONFIG_DEBUG_FS is enabed, below debug info is accessible through +/sys/kernel/debug/ubase/$dev_id/unic/: + +.. code-block:: none + + ├── clear_link_status_record: clear the link status record by reading + ├── link_status_record: show the link status record debug info + ├── promisc_cfg_hw: show the promisc configuration in hardware + ├── rss_cfg_hw: show the rss configuration in hardware + ├── page_pool_info: show the rx page_pool buffer debug info + ├── caps_info: show the capability debug info + ├── dev_info: show the device info, such as max MTU + ├── qos/: show the qos related debug info + ├── vport/: show the UE (UB Entity) debug info of MUE (Management UB Entity) + ├── context/: show object context debug info, such as JFS (Jetty For Send) + ├── ip_tbl/: show the IP address configuration debug info + +Note, the bus-info in the output of below cmd can be used to query the device id +for a unic driver's netdev, which has a device id of "00002" as below example: + +:: + + # ethtool -i + driver: unic + version: 1.0 + firmware-version: 1.0 + expansion-rom-version: + bus-info: 00002 + supports-statistics: yes + supports-test: yes + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +Register Dumping +---------------- +Dump the hardware registers and report the dumpping log through vendor's support +channel using below cmd: + +:: + + # ethtool -d + +Performance tuning +================== +For different workload, the interrupt for the driver may have different cpu +pinnig policy, the below cmd can be used to set cpu pinnig policy for unic +driver's ceq (Completion Event Queue) interrupt, which is used to notify +the driver about the arrival of rx packet and completion of tx packet: + +:: + + # irq_num_list=$(cat /proc/interrupts | grep "ubase$dev_id" | grep ceq) + # echo $cpu_num > /proc/irq/$irq_num/smp_affinity_list + +CPU Intensive Workload +---------------------- +It is recommended to pin different cores to unic driver's interrupt and service +process, adjust interrupt coalesce parameters appropriately to limit interrupts +for lower CPU utilization: + +:: + + # ethtool -C rx-usecs XXX tx-usecs XXX + +Note, the **max_int_gl** in '/sys/kernel/debug/ubase/$dev_id/unic/caps_info' is +the max value of coalesce parameter. + +Latency-sensitive Workload +-------------------------- +It is recommended to pin the same core to unic driver's interrupt and service +process, disable unic driver's interrupt coalesce feature to ensure that +interrupt is triggered as soon as possible: + +:: + + # ethtool -C rx-usecs 0 tx-usecs 0 + +Manage Software +=============== +There is a manage software for UB, QOS & object context & IP address which are +related to unic driver depend on the configuration from that manage software, +refer to below debugfs for more detail on the configuration: + +:: + + QOS: /sys/kernel/debug/ubase/$dev_id/unic/qos/ + Object Context: /sys/kernel/debug/ubase/$dev_id/unic/context + IP address: /sys/kernel/debug/ubase/$dev_id/unic/ip_tbl/ip_tbl_list + +Support +======= +If there is any issue or question, please email the specific information related +to the issue or question to or vendor's support channel. diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index 90a0535a932ac6138989b96947f9227caa919d80..e2b286b797012a9c1f6780f5d79d9714ae13ea9b 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -86,3 +86,4 @@ Storage interfaces misc-devices/index peci/index wmi/index + ub/index diff --git a/Documentation/ub/index.rst b/Documentation/ub/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..34fd8d871f19f94e09f53b75a14a10bcf2325ef5 --- /dev/null +++ b/Documentation/ub/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. include:: + +:Copyright: |copy| 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +===================== +UnifiedBus Subsystem +===================== + +.. toctree:: + :maxdepth: 2 + + ubase/index \ No newline at end of file diff --git a/Documentation/ub/ubase/index.rst b/Documentation/ub/ubase/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..5fcc9347e1e96d2d02c9481266ebfbf930a597ab --- /dev/null +++ b/Documentation/ub/ubase/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. include:: + +:Copyright: |copy| 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +============= +UBASE Driver +============= + +.. toctree:: + :maxdepth: 2 + :numbered: + + ubase \ No newline at end of file diff --git a/Documentation/ub/ubase/ubase.rst b/Documentation/ub/ubase/ubase.rst new file mode 100644 index 0000000000000000000000000000000000000000..5ac46c8ba0e7d8f8b44ae61b5b82c1732d06271f --- /dev/null +++ b/Documentation/ub/ubase/ubase.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Copyright (c) 2025 HiSilicon Technologies Co., Ltd. All rights reserved. + +============================== +UNIFIEDBUS BASE DRIVER (UBASE) +============================== + +UB is a new interconnection protocol and architecture designed for computing +systems, see more on the UB spec . + +This document will introduce the composition of the UBASE Driver and how to +write a UB auxiliary device driver under the Auxiliary Bus framework of UBASE, +also include related debugging information. + +Overview +======== + +UBASE driver is one of the base driver for UB network, based on UB hardware +interface, providing public resource management and abstraction of common +interfaces for the upper layer UB device drivers such as unic, udma, cdma, fwctl, +pmu and uvb, which are auxiliary devcie drivers. UBASE driver also offers +device-driver matching interfaces for the upper-layer drivers based on auxiliary +bus, isolating different auxiliary device drivers, like udma driver using urma +core and unic driver with TCP/IP stack. And ubase has the ability of extending +auxiliary device list to transfer the UB hardware for further use and richer +features. + +UBASE includes the functionalities of ubus device management, resource management, +auxiliary device management, entity management, query the specific capabilities +of the device and so on. It's also the base of other auxiliary device drivers +which must be loaded before them. + +.. code-block:: none + + +----------+ +----------+ +----------+ +---------+ +-----------+ +---------+ + | unic | | udma | | cdma | | pmu | | ubctl | | uvb | + +----------+ +----------+ +----------+ +---------+ +-----------+ +---------+ + ^ ^ ^ ^ ^ ^ + | | | | | | + v v v v v v + +--------------------------------------------------------------------------+ + | auxiliary bus | + +--------------------------------------------------------------------------+ + ^ + | + v + +--------------------------------------------------------------------------+ + | ubase | + | +-----+ +------+ +---------+ +-------+ +----+ +-----+ +-----+ +------+ | + | | dev | | main | | debugfs | | ctrlq | | eq | | arq | | ras | | ubus | | + | +-----+ +------+ +---------+ +-------+ +----+ +-----+ +-----+ +------+ | + | +-----+ +----+ +---------+ +------+ +-----+ +-------+ +----+ +-------+ | + | | cmd | | hw | | mailbox | | pmem | | qos | | reset | | tp | | stats | | + | +-----+ +----+ +---------+ +------+ +-----+ +-------+ +----+ +-------+ | + +--------------------------------------------------------------------------+ + ^ ^ ^ + | | | + | v v + | +------------------+ +------------------+ + | | ubus | | ummu | + | +------------------+ +------------------+ + | ^ ^ + | | | + v v v + +--------------------------------------------------------------------------+ + | firmware | + +--------------------------------------------------------------------------+ + +Below is the summary for the submodules in ubase driver: + + - 1) main: implement module_init/exit(). + - 2) dev: implement auxiliary bus init/uninit function, resource creating and + auxiliary device enable/disable. + - 3) cmd: implement 'command queue' to interact with firmware. + - 4) ctrlq: implement 'control queue' to interact with management software. + - 5) mailbox: implement 'mailbox' configuration to interact with hardware + through `cmdq`. + - 6) hw: implement interaction with firmware and hardware for functions. + - 7) reset: implement hardware reset handling for ubase driver. + - 8) tp: implement tp layer context BA and context creation. + - 9) debugfs: implement kernel debugfs to obtain debugging information. + - 10) qos: implement quality of service for upper communication modules. + - 11) ras: implement hardware error handler. + - 12) ubus: implement interaction with module `ubus`. + - 13) eq: event queue including asynchronous and completion event. + +Supported Hardware +================== + +UBUS vendor/device pairs: + +========= =========== ====================================== +Vendor ID Device ID Description +========= =========== ====================================== +0xCC08 0xA001 Kunpeng URMA MUE (Management UB Entity) +0xCC08 0xA002 Kunpeng URMA UE (UB Entity) +0xCC08 0xA003 Kunpeng CDMA MUE (Management UB Entity) +0xCC08 0xA004 Kunpeng CDMA UE (UB Entity) +0xCC08 0xA005 Kunpeng PMU MUE (Management UB Entity) +0xCC08 0xA006 Kunpeng PMU UE (UB Entity) +0xCC08 0xD802 Ascend URMA MUE (Management UB Entity) +0xCC08 0xD803 Ascend URMA UE (UB Entity) +0xCC08 0xD804 Ascend CDMA MUE (Management UB Entity) +0xCC08 0xD805 Ascend CDMA UE (UB Entity) +0xCC08 0xD806 Ascend PMU MUE (Management UB Entity) +0xCC08 0xD807 Ascend PMU UE (UB Entity) +0xCC08 0xD80B Ascend UBOE MUE (Management UB Entity) +0xCC08 0xD80C Ascend UBOE UE (UB Entity) +========= =========== ====================================== + +Supported Auxiliary device +========================== + +UB Auxiliary bus device/driver pairs: + +========= ==== ==== ==== ===== === === +Device ID unic udma cdma fwctl pmu uvb +========= ==== ==== ==== ===== === === +0xA001 O O X X X O +0xA002 X O X X X O +0xA003 X X O X X X +0xA004 X X O X X X +0xA005 X X X O O X +0xA006 X X X O O X +0xD802 O O X X X O +0xD803 X O X X X O +0xD804 X X O X X X +0xD805 X X O X X X +0xD806 X X X O O X +0xD807 X X X O O X +0xD80B O O X X X O +0xD80C X O X X X O +========= ==== ==== ==== ===== === === + +If anyone wants to support a new auxiliary device driver based on ubase, after +adding an specific device id matched with vendor id, extending the driver +list is necessary as follows:: + enum ubase_drv_type { + UBASE_DRV_UNIC, + UBASE_DRV_UDMA, + UBASE_DRV_CDMA, + UBASE_DRV_FWCTL, + UBASE_DRV_PMU, + UBASE_DRV_UVB, + UBASE_DRV_MAX, + }; + +Next, `struct ubase_adev_device` is supposed to be extended by the new device +driver with its name filled in `suffix` and supported capabilities function +hooking up to the handling named `is_supported`. Following is an example driver +`unic` in ``ubase_dev.c``:: + static struct ubase_adev_device { + const char *suffix; + bool (*is_supported)(struct ubase_dev *dev); + } ubase_adev_devices[UBASE_DRV_MAX] = { + [UBASE_DRV_UNIC] = { + .suffix = "unic", + .is_supported = &ubase_dev_unic_supported + }, + }; + +Then the new driver can fulfill `struct auxiliary_driver` ops allowing auxiliary +bus transfer handling `probe` to initialize the new driver and handling `remove` +to uninitialize it. + +Module parameters +================= +UBASE driver includes one module parameter for now as `debug`. The default +parameter can support full function of ubase and related drivers, but in some +special scene like locating problems, debug information is necessary. + +debug + +This parameter controls the print level of ubase driver, preventing printing +debug information like `UBUS ELR start` to locate the position of driver running, +which may be helpful when doing problem identification to clarify the line of +code where the problem occurs. + +This parameter is not supposed to set in loading driver but changed in a system +configuration file created by ubase, which set to be `0` means disable in default +as not showing all debug information. If the user wants to enable the debug printing, +the file `/sys/module/ubase/parameters/debug` can be set to an integer value +`except 0` as enable like `1` through the command `echo`, following line shows:: + echo 1 > /sys/module/ubase/parameters/debug + +Or set the insmod parameter `debug` to value `1`, like the following: + +.. code-block:: none + + insmod ubase.ko debug=1 + +Debugging +========= +UBASE driver supports to obtain debug related information for users through +`debug filesystem` set by Linux kernel, which helps a lot for problem locating +and quick overview of ubase driver. The ubase debugfs includes +`context querying in software and hardware`, `reset information`, +`capabilities information`, `activate record`, `qos information`, +`prealloc memory information`. + +Through debugfs interfaces when `CONFIG_DEBUG_FS` is enabled, the users can obtain +these information from the directory in system:: + /sys/kernel/debug/ubase// + +1) context querying + + UBASE driver supports to query the context created in ubase for all auxiliary + device drivers, including aeq, ceq, tp and tpg context stored in both software + and hardware to verify whether configuration satisfy using demand. Note, the + context ended with `hw` means hardware, like `aeq_context_hw`, and another one + without `hw` means that stored in software, such as `aeq_context`. + +2) reset information + + UBASE driver supports to query all kinds of reset implementation counts, + including ELR reset, port reset, himac reset, total finish count in software + and hardware, and failed count. + +3) capabilities information + + UBASE driver supports to query the capabilities information in self device, + which can be used for upper-layer drivers, and also resource size for creating. + +4) activate record + + UBASE driver supports to query activate record about the hardware, including + activate and deactivate counts and the exact time of these actions. + +5) qos information + + UBASE driver supports to query quality of service(qos) information configured + in hardware, about configuration set by ets, tm and `management software`, + including `tc &tc group`, `rqmt table`, `mapping in vl, sl and dscp`, + `tm port`, `tm priority`, `qset and queue information` and so on. + +6) prealloc memory information + + UBASE driver supports to query the hulk pages allocated by ubase for both + common use and udma use. + +Functionality dependencies +========================== +Some functions in ubase driver rely on configuration of `management software` as +the manager, the following shows dependencies of ubase: + - 1) Qos configuration: `management software` take the responsibility of + `entity creation and distribute TQMS queue` and `mapping from sl to vl`. + - 2) TP context: `management software` take the response of creating TP layer + context for common use, including tp context basic address (BA), + tp group(tpg) context BA, TP extdb buff, TP timer buff, CC context BA, + Dest address BA, Seid_upi BA, TPM BA and so on. + - 3) Reset: The reset process needs collaborative cooperation between ubase + driver and `management software`, including stop flow, resume flow, + reconstruct TP layer context and so on. + +Support +======= +If there is any issue or question, please email the specific information related +to the issue or question to or vendor's support channel. \ No newline at end of file diff --git a/drivers/net/ub/dev/ubl.c b/drivers/net/ub/dev/ubl.c index b3637476b1fbd154c47a238f1dbffcc1cab938fc..453e4a1c9ff52373a6c3aa54c38f5ac671c114f5 100644 --- a/drivers/net/ub/dev/ubl.c +++ b/drivers/net/ub/dev/ubl.c @@ -116,7 +116,7 @@ static const struct header_ops ubl_header_ops ____cacheline_aligned = { }; /** - * ubl_setup - setup ub link network device + * ubl_setup - set up a ubl netdev * @dev: network device * * Fill in the fields of the device structure with ubl-generic values. @@ -138,18 +138,17 @@ void ubl_setup(struct net_device *dev) EXPORT_SYMBOL(ubl_setup); /** - * alloc_ubldev_mqs - Allocates and sets up a ub-link device + * alloc_ubldev_mqs - allocate and set up a ubl netdev * @sizeof_priv: Size of additional driver-private structure to be allocated - * for this ubl device + * for this ubl netdev * @txqs: The number of TX queues this device has. * @rxqs: The number of RX queues this device has. * * Fill in the fields of the device structure with ubl-generic * values. Basically done everything except registering the device. * - * Constructs a new net device, completing with a private data area of - * size (sizeof_priv). A 32-byte (not bit) alignment is enforced for - * this private data area. + * Allocate a new net device, with a private data area of size (sizeof_priv). + * A 32-byte alignment is enforced for this private data area. */ struct net_device *alloc_ubldev_mqs(int sizeof_priv, unsigned int txqs, @@ -161,13 +160,13 @@ struct net_device *alloc_ubldev_mqs(int sizeof_priv, unsigned int txqs, EXPORT_SYMBOL(alloc_ubldev_mqs); /** - * ubl_type_trans - obtains skb->protocol and adds sw_ptype to the packet + * ubl_type_trans - obtain packet type and insert sw_ptype to the packet header * @skb: buffer to alter * @dev: source device * @type: packet type * - * Obtains the packet type and translates it to skb->protocol and adds sw_ptype - * to the packet data. + * Obtain the packet type, translate it to skb->protocol and insert sw_ptype + * to the packet header. */ __be16 ubl_type_trans(struct sk_buff *skb, struct net_device *dev, u8 type) { diff --git a/drivers/ub/ubase/debugfs/ubase_ctx_debugfs.c b/drivers/ub/ubase/debugfs/ubase_ctx_debugfs.c index 33221a90edd91a2a766c9348f1c3ca5dcf308a7e..63f27093aec12985340dfe01b53b1860455bc91e 100644 --- a/drivers/ub/ubase/debugfs/ubase_ctx_debugfs.c +++ b/drivers/ub/ubase/debugfs/ubase_ctx_debugfs.c @@ -252,6 +252,19 @@ static void __ubase_print_context_hw(struct seq_file *s, void *ctx_addr, } } +/** + * ubase_print_context_hw() - formatted the context output to seq file + * @s: seq_file + * @ctx_addr: context address + * @ctx_len: context length + * + * This function outputs the contents of `ctx_addr` to a seq_file according to + * the specified format. + * Each line in the file is 32 bits, and the number of lines is `ctx_len / sizeof(u32)`. + * If `ctx_len` is not an integer multiple of 4, there will be truncation at the end. + * + * Context: Any context. + */ void ubase_print_context_hw(struct seq_file *s, void *ctx_addr, u32 ctx_len) { if (!s || !ctx_addr) diff --git a/drivers/ub/ubase/debugfs/ubase_debugfs.c b/drivers/ub/ubase/debugfs/ubase_debugfs.c index 21fe4d1fa9b61d0d8731e70fb1fae33b7829d82a..9476cf17fa013d779f9cdbe7b1cd35616a7e41db 100644 --- a/drivers/ub/ubase/debugfs/ubase_debugfs.c +++ b/drivers/ub/ubase/debugfs/ubase_debugfs.c @@ -399,6 +399,18 @@ static bool __ubase_dbg_dentry_support(struct device *dev, u32 property) return false; } +/** + * ubase_dbg_dentry_support() - determine whether to create debugfs dentries and debugfs cmd files + * @adev: auxiliary device + * @property: property of debugfs dentry or debufs cmd file + * + * The function is used in the 'support' functions of 'struct ubase_dbg_cmd_info' + * and 'struct ubase_dbg_cmd_info‘ to determine whether to create debugfs dentries + * and debugfs cmd files. + * + * Context: Any context. + * Return: true or false + */ bool ubase_dbg_dentry_support(struct auxiliary_device *adev, u32 property) { if (!adev) @@ -426,6 +438,19 @@ static int __ubase_dbg_seq_file_init(struct device *dev, return 0; } +/** + * ubase_dbg_seq_file_init() - ubase init debugfs cmd file + * @dev: the device + * @dirs: ubase debugfs dentry information + * @dbgfs: ubase debugfs data structure + * @idx: index of dirs + * + * This function is used in the 'init' function within 'struct ubase_dbg_cmd_info' + * to create a ubase debugfs cmd file. + * + * Context: Any context. + * Return: 0 on success, negative error code otherwise + */ int ubase_dbg_seq_file_init(struct device *dev, struct ubase_dbg_dentry_info *dirs, struct ubase_dbgfs *dbgfs, u32 idx) @@ -714,6 +739,18 @@ static int ubase_dbg_create_file(struct device *dev, struct ubase_dbgfs *dbgfs, return 0; } +/** + * ubase_dbg_create_dentry() - ubase debugfs create dentry + * @dev: the device + * @dbgfs: ubase debugfs data structure + * @dirs: ubase debugfs dentry information + * @root_idx: index of the root dentry in dirs, and the root dentry must be the last one in the path + * + * This function is used to create a ubase debugfs cmd file. + * + * Context: Any context. + * Return: 0 on success, negative error code otherwise + */ int ubase_dbg_create_dentry(struct device *dev, struct ubase_dbgfs *dbgfs, struct ubase_dbg_dentry_info *dirs, u32 root_idx) { @@ -794,6 +831,15 @@ void ubase_dbg_unregister_debugfs(void) debugfs_remove_recursive(ubase_dbgfs_root); } +/** + * ubase_diag_debugfs_root() - get ubase debugfs root dentry + * @adev: auxiliary device + * + * This function is used to get ubase debugfs root dentry. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct dentry + */ struct dentry *ubase_diag_debugfs_root(struct auxiliary_device *adev) { if (!adev) @@ -803,6 +849,17 @@ struct dentry *ubase_diag_debugfs_root(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_diag_debugfs_root); +/** + * ubase_dbg_format_time() - formatted the time output to seq file + * @time: time value + * @s: seq_file + * + * The function outputs the time in the format of + * 'week month day hour:minute:second year' to seq_file. + * + * Context: Any context. + * Return: 0 on success, negative error code otherwise + */ int ubase_dbg_format_time(time64_t time, struct seq_file *s) { #define YEAR_OFFSET 1900 diff --git a/drivers/ub/ubase/ubase_cmd.c b/drivers/ub/ubase/ubase_cmd.c index 4eedb6eff530efd9cf87144cac8fb5f235412cf2..ab554343136f84b47e9c53ec23261425b3d7018e 100644 --- a/drivers/ub/ubase/ubase_cmd.c +++ b/drivers/ub/ubase/ubase_cmd.c @@ -777,9 +777,21 @@ int __ubase_cmd_send_in(struct ubase_dev *udev, struct ubase_cmd_buf *in) } /** - * When uninstalling, cmdq needs to be successfully sended as much as possible, - * but the cmd may be disabled during reset, this interface attempts to send cmd - * when it is enabled. + * ubase_cmd_send_inout_ex() - query(and write) cmd extension function + * @aux_dev: auxiliary device + * @in: the intput cmd buff + * @out: the output cmd buff + * @time_out: timeout duration, unit: ms + * + * When the timeout parameter is set to 0, this function behaves the same as + * 'ubase_cmd_send_inout'. When the timeout parameter is not 0, if the cmdq + * channel is disabled and it recovers within the timeout period, the cmdq can + * still process commands normally. + * This function is applicable to scenarios such as concurrent resets, where the + * cmdq channel is first set to be disabled and then restored to normal operation. + * + * Context: Process context. Takes and releases , BH-safe. May sleep. + * Return: 0 on success, negative error code otherwise */ int ubase_cmd_send_inout_ex(struct auxiliary_device *aux_dev, struct ubase_cmd_buf *in, struct ubase_cmd_buf *out, @@ -812,6 +824,22 @@ int ubase_cmd_send_inout_ex(struct auxiliary_device *aux_dev, } EXPORT_SYMBOL(ubase_cmd_send_inout_ex); +/** + * ubase_cmd_send_inout() - query(and write) cmd function + * @aux_dev: auxiliary device + * @in: the intput cmd buff + * @out: the output cmd buff + * + * The firmware determines the processing behavior based on 'in->opcode'. + * 'in->data_size' and 'in->data' represent the length of valid data and the + * address where the data is stored for interaction with the firmware. + * 'in->is_read' determines whether to read the query results. + * 'out->data_size' and 'out->data' represent the length of valid data and the + * address where the data is stored for the reading the query results. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_cmd_send_inout(struct auxiliary_device *aux_dev, struct ubase_cmd_buf *in, struct ubase_cmd_buf *out) @@ -823,6 +851,22 @@ int ubase_cmd_send_inout(struct auxiliary_device *aux_dev, } EXPORT_SYMBOL(ubase_cmd_send_inout); +/** + * ubase_cmd_send_in_ex() - write cmd extension function + * @aux_dev: auxiliary device + * @in: the intput cmd buff + * @time_out: timeout duration, unit: ms + * + * When the timeout parameter is set to 0, this function behaves the same as + * 'ubase_cmd_send_in'. When the timeout parameter is not 0, if the cmdq + * channel is disabled and it recovers within the timeout period, the cmdq can + * still process commands normally. + * This function is applicable to scenarios such as concurrent resets, where the + * cmdq channel is first set to disabled and then restored to normal operation. + * + * Context: Process context. Takes and releases , BH-safe. May sleep. + * Return: 0 on success, negative error code otherwise + */ int ubase_cmd_send_in_ex(struct auxiliary_device *aux_dev, struct ubase_cmd_buf *in, u32 time_out) { @@ -837,6 +881,19 @@ int ubase_cmd_send_in_ex(struct auxiliary_device *aux_dev, } EXPORT_SYMBOL(ubase_cmd_send_in_ex); +/** + * ubase_cmd_send_in() - write cmd function + * @aux_dev: auxiliary device + * @in: the intput cmd buff + * + * This function is only used for writing cmdq opcodes. 'in->is_read' must be + * false. The firmware determines the processing behavior based on 'in->opcode'. + * 'in->data_size' and 'in->data' represent the length of valid data and the + * address where the data is stored for interaction with the firmware. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_cmd_send_in(struct auxiliary_device *aux_dev, struct ubase_cmd_buf *in) { @@ -878,6 +935,19 @@ static int __ubase_cmd_get_data_size(struct ubase_dev *udev, u16 opcode, return 0; } +/** + * ubase_cmd_get_data_size() - obtain the valid data length from cmdq opcode + * @aux_dev: auxiliary device + * @opcode: cmdq opcode + * @data_size: Save the valid data length of cmdq opcode + * + * For each opcode, the firmware has a corresponding valid data length. + * This function queries the firmware to obtain the valid data length + * corresponding to the opcode. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_cmd_get_data_size(struct auxiliary_device *aux_dev, u16 opcode, u16 *data_size) { @@ -925,6 +995,18 @@ int __ubase_register_crq_event(struct ubase_dev *udev, return ret; } +/** + * ubase_register_crq_event() - register crq event processing function + * @aux_dev: auxiliary device + * @nb: the crq event notification block + * + * Register the crq handler function. When the firmware reports a crq event, + * if the opcode reported by the firmware matches the registered 'nb->opcode', + * the 'nb->crq_handler' function will be called to process it. + * + * Context: Any context. + * Return: 0 on success, negative error code otherwise + */ int ubase_register_crq_event(struct auxiliary_device *aux_dev, struct ubase_crq_event_nb *nb) { @@ -955,6 +1037,16 @@ void __ubase_unregister_crq_event(struct ubase_dev *udev, u16 opcode) mutex_unlock(&crq_table->lock); } +/** + * ubase_unregister_crq_event() - unregister crq event processing function + * @aux_dev: auxiliary device + * @opcode: cmdq crq opcode + * + * Unregisters the crq processing function. This function is called when user + * no longer want to handle the crq opcode events reported by the firmware. + * + * Context: Any context. + */ void ubase_unregister_crq_event(struct auxiliary_device *aux_dev, u16 opcode) { struct ubase_dev *udev; diff --git a/drivers/ub/ubase/ubase_ctrlq.c b/drivers/ub/ubase/ubase_ctrlq.c index 39deb9667f591124de9bacbd2a584e0c2205199d..2d3a2c81469e3f85987b1a09904a7051958ba57d 100644 --- a/drivers/ub/ubase/ubase_ctrlq.c +++ b/drivers/ub/ubase/ubase_ctrlq.c @@ -824,6 +824,28 @@ int __ubase_ctrlq_send(struct ubase_dev *udev, struct ubase_ctrlq_msg *msg, return ret; } +/** + * ubase_ctrlq_send_msg() - ctrlq message send function + * @aux_dev: auxiliary device + * @msg: the message to be sent + * + * The driver uses this function to send a ctrlq message to the management software. + * The management software determines the module responsible for processing the message + * based on 'msg->service_ver', 'msg->service_type', and 'msg->opcode'; + * it also retrieves the length and content of the data to be sent from + * 'msg->in_size' and 'msg->in'. + * When 'msg->is_resp' is set to 1, it indicates that the message is a response + * to a ctrlq message from the management software. 'msg->resp_seq' and 'msg->resp_ret' + * represent the sequence number and processing result of the ctrlq message from + * the management software. + * When 'msg->need_resp' is set to 1, it indicates that the management software needs + * to respond to the driver's ctrlq message. If 'msg->out_size' is not zero and + * 'msg->out' is not empty, this function will wait synchronously for the management + * software's response, and the response information will be stored in 'msg->out'. + * + * Context: Process context. Takes and releases , BH-safe. May sleep. + * Return: 0 on success, negative error code otherwise + */ int ubase_ctrlq_send_msg(struct auxiliary_device *aux_dev, struct ubase_ctrlq_msg *msg) { @@ -1159,6 +1181,19 @@ void ubase_ctrlq_clean_service_task(struct ubase_delay_work *ubase_work) spin_unlock_bh(&csq->lock); } + +/** + * ubase_ctrlq_register_crq_event() - register ctrlq crq event processing function + * @aux_dev: auxiliary device + * @nb: the ctrlq crq event notification block + * + * Register the ctrlq crq handler function. When the management software reports + * a ctrlq crq event, if the registered 'nb->opcode' and 'nb->service_type' match + * the crq, the 'nb->crq_handler' function will be called to process it. + * + * Context: Any context. + * Return: 0 on success, negative error code otherwise + */ int ubase_ctrlq_register_crq_event(struct auxiliary_device *aux_dev, struct ubase_ctrlq_event_nb *nb) { @@ -1193,6 +1228,17 @@ int ubase_ctrlq_register_crq_event(struct auxiliary_device *aux_dev, } EXPORT_SYMBOL(ubase_ctrlq_register_crq_event); +/** + * ubase_ctrlq_unregister_crq_event() - unregister ctrlq crq event processing function + * @aux_dev: auxiliary device + * @service_type: the ctrlq service type + * @opcode: the ctrlq opcode + * + * Unregisters the ctrlq crq processing function. This function is called when user + * no longer wants to handle the 'service_type' and 'opcode' ctrlq crq events. + * + * Context: Any context. + */ void ubase_ctrlq_unregister_crq_event(struct auxiliary_device *aux_dev, u8 service_type, u8 opcode) { diff --git a/drivers/ub/ubase/ubase_dev.c b/drivers/ub/ubase/ubase_dev.c index 9ea0d14a4d391364afdb50c274ebd9d4ed3958b4..d48582bf90a9f50f02f4f8f8b14bd8a398e7999c 100644 --- a/drivers/ub/ubase/ubase_dev.c +++ b/drivers/ub/ubase/ubase_dev.c @@ -882,6 +882,15 @@ void ubase_resume_aux_devices(struct ubase_dev *udev) mutex_unlock(&priv->uadev_lock); } +/** + * ubase_adev_ubl_supported() - determine whether ub link is supported + * @adev: auxiliary device + * + * This function is used to determine whether ub link is supported. + * + * Context: Any context. + * Return: true or false + */ bool ubase_adev_ubl_supported(struct auxiliary_device *adev) { if (!adev) @@ -891,6 +900,15 @@ bool ubase_adev_ubl_supported(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_adev_ubl_supported); +/** + * ubase_adev_ctrlq_supported() - determine whether to support ctrlq + * @adev: auxiliary device + * + * This function is used to determine whether to support ctrlq. + * + * Context: Any context. + * Return: true or false + */ bool ubase_adev_ctrlq_supported(struct auxiliary_device *adev) { if (!adev) @@ -900,6 +918,15 @@ bool ubase_adev_ctrlq_supported(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_adev_ctrlq_supported); +/** + * ubase_adev_eth_mac_supported() - determine whether eth link is supported + * @adev: auxiliary device + * + * This function is used to determine whether eth link is supported. + * + * Context: Any context. + * Return: true or false + */ bool ubase_adev_eth_mac_supported(struct auxiliary_device *adev) { if (!adev) @@ -909,6 +936,15 @@ bool ubase_adev_eth_mac_supported(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_adev_eth_mac_supported); +/** + * ubase_get_io_base() - get io space base address + * @adev: auxiliary device + * + * The function is used to get io space base address. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_resource_space + */ struct ubase_resource_space *ubase_get_io_base(struct auxiliary_device *adev) { if (!adev) @@ -918,6 +954,15 @@ struct ubase_resource_space *ubase_get_io_base(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_get_io_base); +/** + * ubase_get_mem_base() - get memory space base address + * @adev: auxiliary device + * + * The function is used to get memory space base address. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_resource_space + */ struct ubase_resource_space *ubase_get_mem_base(struct auxiliary_device *adev) { if (!adev) @@ -927,6 +972,15 @@ struct ubase_resource_space *ubase_get_mem_base(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_get_mem_base); +/** + * ubase_get_dev_caps() - get ubase capabilities + * @adev: auxiliary device + * + * The function is used to get ubase capabilities. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_caps + */ struct ubase_caps *ubase_get_dev_caps(struct auxiliary_device *adev) { if (!adev) @@ -936,6 +990,15 @@ struct ubase_caps *ubase_get_dev_caps(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_get_dev_caps); +/** + * ubase_get_udma_caps() - get udma auxiliary device capabilities + * @adev: udma auxiliary device pointer + * + * The function is used to get udma auxiliary device capabilities. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_adev_caps + */ struct ubase_adev_caps *ubase_get_udma_caps(struct auxiliary_device *adev) { struct ubase_dev *udev; @@ -949,12 +1012,30 @@ struct ubase_adev_caps *ubase_get_udma_caps(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_get_udma_caps); +/** + * ubase_get_cdma_caps() - get cdma auxiliary device capabilities + * @adev: cdma auxiliary device pointer + * + * The function is used to get cdma auxiliary device capabilities. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_adev_caps + */ struct ubase_adev_caps *ubase_get_cdma_caps(struct auxiliary_device *adev) { return ubase_get_udma_caps(adev); } EXPORT_SYMBOL(ubase_get_cdma_caps); +/** + * ubase_get_reset_stage() - get current reset stage + * @adev: auxiliary device + * + * The function is used to get current reset stage. + * + * Context: Any context. + * Return: enum ubase_reset_stage + */ enum ubase_reset_stage ubase_get_reset_stage(struct auxiliary_device *adev) { struct ubase_dev *udev; @@ -968,6 +1049,17 @@ enum ubase_reset_stage ubase_get_reset_stage(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_get_reset_stage); +/** + * ubase_virt_register() - register auxiliary device virtualization handling function + * @adev: auxiliary device + * @virt_handler: the function pointer to handle virtualization. adev: the same as the + * parameter 'adev', bus_ue_id: bus ub entity id, is_en: true - enable virtualization, + * false - disable virtualization. + * + * The function is used to register auxiliary device virtualization handling function. + * + * Context: Process context. Takes and releases . + */ void ubase_virt_register(struct auxiliary_device *adev, void (*virt_handler)(struct auxiliary_device *adev, u16 bus_ue_id, bool is_en)) @@ -986,6 +1078,14 @@ void ubase_virt_register(struct auxiliary_device *adev, } EXPORT_SYMBOL(ubase_virt_register); +/** + * ubase_virt_unregister() - unregister auxiliary device virtualization handling function + * @adev: auxiliary device + * + * The function is used to unregister auxiliary device virtualization handling function. + * + * Context: Process context. Takes and releases . + */ void ubase_virt_unregister(struct auxiliary_device *adev) { struct ubase_adev *uadev; @@ -1001,6 +1101,16 @@ void ubase_virt_unregister(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_virt_unregister); +/** + * ubase_port_register() - register auxiliary device port handling function + * @adev: auxiliary device + * @port_handler: the function pointer to port handling. adev: the same as the + * parameter 'adev', link_up: true - link up, false - link down. + * + * The function is used to register auxiliary device port handling function. + * + * Context: Process context. Takes and releases . + */ void ubase_port_register(struct auxiliary_device *adev, void (*port_handler)(struct auxiliary_device *adev, bool link_up)) @@ -1019,6 +1129,14 @@ void ubase_port_register(struct auxiliary_device *adev, } EXPORT_SYMBOL(ubase_port_register); +/** + * ubase_port_unregister() - unregister auxiliary device port handling function + * @adev: auxiliary device + * + * The function is used to unregister auxiliary device port handling function. + * + * Context: Process context. Takes and releases . + */ void ubase_port_unregister(struct auxiliary_device *adev) { struct ubase_adev *uadev; @@ -1034,6 +1152,16 @@ void ubase_port_unregister(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_port_unregister); +/** + * ubase_reset_register() - register auxiliary device reset function + * @adev: auxiliary device + * @reset_handler: the function pointer to reset. adev: the same as the parameter + * 'adev', stage: enum ubase_reset_stage. + * + * The function is used to register auxiliary device reset function. + * + * Context: Process context. Takes and releases . + */ void ubase_reset_register(struct auxiliary_device *adev, void (*reset_handler)(struct auxiliary_device *adev, enum ubase_reset_stage stage)) @@ -1052,6 +1180,14 @@ void ubase_reset_register(struct auxiliary_device *adev, } EXPORT_SYMBOL(ubase_reset_register); +/** + * ubase_reset_unregister() - unregister auxiliary device reset function + * @adev: auxiliary device + * + * The function is used to unregister auxiliary device reset function. + * + * Context: Process context. Takes and releases . + */ void ubase_reset_unregister(struct auxiliary_device *adev) { struct ubase_adev *uadev; @@ -1067,6 +1203,15 @@ void ubase_reset_unregister(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_reset_unregister); +/** + * ubase_get_unic_caps() - get unic auxiliary device capabilities + * @adev: unic auxiliary device pointer + * + * The function is used to get unic auxiliary device capabilities. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_adev_caps + */ struct ubase_adev_caps *ubase_get_unic_caps(struct auxiliary_device *adev) { struct ubase_dev *udev; @@ -1162,6 +1307,15 @@ bool ubase_dbg_default(void) return ubase_debug; } +/** + * ubase_get_adev_qos() - get auxiliary device qos information + * @adev: auxiliary device + * + * The function is used to get auxiliary device qos information. + * + * Context: Any context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_adev_qos + */ struct ubase_adev_qos *ubase_get_adev_qos(struct auxiliary_device *adev) { struct ubase_dev *udev; @@ -1199,6 +1353,16 @@ static void ubase_activate_notify(struct ubase_dev *udev, mutex_unlock(&udev->priv.uadev_lock); } +/** + * ubase_activate_register() - register auxiliary device activate handling function + * @adev: auxiliary device + * @activate_handler: the function pointer to activate handling. adev: the same + * as the parameter 'adev', activate: true - activate, false - deactivate. + * + * The function is used to register auxiliary device activate handling function. + * + * Context: Process context. Takes and releases . + */ void ubase_activate_register(struct auxiliary_device *adev, void (*activate_handler)(struct auxiliary_device *adev, bool activate)) @@ -1217,6 +1381,14 @@ void ubase_activate_register(struct auxiliary_device *adev, } EXPORT_SYMBOL(ubase_activate_register); +/** + * ubase_activate_unregister() - unregister auxiliary device activate handling function + * @adev: auxiliary device + * + * The function is used to unregister auxiliary device activate handling function. + * + * Context: Process context. Takes and releases . + */ void ubase_activate_unregister(struct auxiliary_device *adev) { struct ubase_adev *uadev; @@ -1325,6 +1497,17 @@ void ubase_flush_workqueue(struct ubase_dev *udev) flush_workqueue(udev->ubase_arq_wq); } +/** + * ubase_activate_dev() - activate device + * @adev: auxiliary device + * + * The auxiliary device actively initializes the activate device process. + * This function will call the activate handling functions registered by all + * auxiliary devices under the same ub entity. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_activate_dev(struct auxiliary_device *adev) { struct ubase_dev *udev; @@ -1358,6 +1541,17 @@ int ubase_activate_dev(struct auxiliary_device *adev) } EXPORT_SYMBOL(ubase_activate_dev); +/** + * ubase_deactivate_dev() - deactivate device + * @adev: auxiliary device + * + * The auxiliary device actively initializes the deactivate device process. + * This function will call the activate handling functions registered by all + * auxiliary devices under the same ub entity. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_deactivate_dev(struct auxiliary_device *adev) { struct ubase_dev *udev; @@ -1417,6 +1611,16 @@ static int __ubase_get_bus_eid(struct ubase_dev *udev, struct ubase_bus_eid *eid return ubase_query_bus_eid(udev, eid); } +/** + * ubase_get_bus_eid() - get bus entity id + * @adev: auxiliary device + * @eid: save the bus entity id + * + * The function is used to get bus entity id. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_get_bus_eid(struct auxiliary_device *adev, struct ubase_bus_eid *eid) { struct ubase_dev *udev; diff --git a/drivers/ub/ubase/ubase_eq.c b/drivers/ub/ubase/ubase_eq.c index 754f62011420d467d5021593e095214f17788e97..db1dc72f2caf9967179d72dd65668452599bc0a0 100644 --- a/drivers/ub/ubase/ubase_eq.c +++ b/drivers/ub/ubase/ubase_eq.c @@ -1003,6 +1003,19 @@ static int __ubase_event_register(struct ubase_dev *udev, return ret; } +/** + * ubase_event_register() - register asynchronous event processing function + * @adev: auxiliary device + * @cb: asynchronous event notification block + * + * This function uses `blocking_notifier_chain_register` to register the + * asynchronous event handling function. When the ubase driver receives an + * asynchronous event and matches it with the registered event notification + * block, it calls the registered function via `blocking_notifier_call_chain`. + * + * Context: Process context, Takes and releases the RCU lock. + * Return: 0 on success, negative error code otherwise + */ int ubase_event_register(struct auxiliary_device *adev, struct ubase_event_nb *cb) { @@ -1038,6 +1051,16 @@ static void __ubase_event_unregister(struct ubase_dev *udev, cb->event_type, ret); } +/** + * ubase_event_unregister() - unregister asynchronous event processing function + * @adev: auxiliary device + * @cb: ubase asynchronous event notification block + * + * This function uses `blocking_notifier_chain_unregister` to unregister the + * asynchronous event handling function. + * + * Context: Process context, Takes and releases the RCU lock. + */ void ubase_event_unregister(struct auxiliary_device *adev, struct ubase_event_nb *cb) { @@ -1048,6 +1071,20 @@ void ubase_event_unregister(struct auxiliary_device *adev, } EXPORT_SYMBOL(ubase_event_unregister); +/** + * ubase_comp_register() - register completion event processing function + * @adev: auxiliary device + * @comp_handler: completion event processing function. nb: struct notifier_block, + * jfcn: jfc index, data: self-defined data pointer. + * + * This function uses `atomic_notifier_chain_register` to register the + * completion event handling function. When the ubase driver receives a + * completion event that matches a registered auxiliary device, it calls the + * registered function via `atomic_notifier_call_chain`. + * + * Context: Process context, may sleep + * Return: 0 on success, negative error code otherwise + */ int ubase_comp_register(struct auxiliary_device *adev, int (*comp_handler)(struct notifier_block *nb, unsigned long jfcn, void *data)) @@ -1071,6 +1108,15 @@ int ubase_comp_register(struct auxiliary_device *adev, } EXPORT_SYMBOL(ubase_comp_register); +/** + * ubase_comp_unregister() - unregister completion event processing function + * @adev: auxiliary device + * + * This function uses `atomic_notifier_chain_unregister` to unregister the + * completion event handling function. + * + * Context: Process context, Takes and releases the RCU lock. + */ void ubase_comp_unregister(struct auxiliary_device *adev) { struct ubase_adev *uadev; diff --git a/drivers/ub/ubase/ubase_hw.c b/drivers/ub/ubase/ubase_hw.c index 290a03a74b0e48f97b87ef0d0c19e9bc5dc54000..2b68ba5884f51ca6bc815b51f4a41e86b53b7cf9 100644 --- a/drivers/ub/ubase/ubase_hw.c +++ b/drivers/ub/ubase/ubase_hw.c @@ -1007,6 +1007,22 @@ int __ubase_perf_stats(struct ubase_dev *udev, u64 port_bitmap, u32 period, return ret; } +/** + * ubase_perf_stats() - get ub port stats + * @adev: auxiliary device + * @port_bitmap: port bitmap + * @period: period, unit: ms + * @data: stats data + * @data_size: data size + * + * The function is used to query the port bandwidth and the bandwidth of each vl + * under the port. The bandwidth statistics collection duration is 'period'. + * The larger the 'period', the longer the time required, and the more accurate + * the bandwidth measurement. + * + * Context: Process context. Takes and releases , BH-safe. Sleep. + * Return: 0 on success, negative error code otherwise + */ int ubase_perf_stats(struct auxiliary_device *adev, u64 port_bitmap, u32 period, struct ubase_perf_stats_result *data, u32 data_size) { diff --git a/drivers/ub/ubase/ubase_mailbox.c b/drivers/ub/ubase/ubase_mailbox.c index ff3ff78ca513cc3617a6fb92f1de1f15c51bd3a5..a92993f5ac0bb1e568dc774441a04b8cdaadaa28 100644 --- a/drivers/ub/ubase/ubase_mailbox.c +++ b/drivers/ub/ubase/ubase_mailbox.c @@ -66,6 +66,15 @@ struct ubase_cmd_mailbox *__ubase_alloc_cmd_mailbox(struct ubase_dev *udev) return NULL; } +/** + * ubase_alloc_cmd_mailbox() - Alloc mailbox buffer + * @aux_dev: auxiliary device + * + * The function is used to alloc mailbox buffer. + * + * Context: Process context. + * Return: NULL if the adev is empty, otherwise the pointer to struct ubase_cmd_mailbox + */ struct ubase_cmd_mailbox *ubase_alloc_cmd_mailbox(struct auxiliary_device *aux_dev) { struct ubase_dev *udev; @@ -91,6 +100,15 @@ void __ubase_free_cmd_mailbox(struct ubase_dev *udev, kfree(mailbox); } +/** + * ubase_free_cmd_mailbox() - Free mailbox buffer + * @aux_dev: auxiliary device + * @mailbox: mailbox command address + * + * The function is used to free mailbox buffer. + * + * Context: Process context. + */ void ubase_free_cmd_mailbox(struct auxiliary_device *aux_dev, struct ubase_cmd_mailbox *mailbox) { @@ -523,6 +541,17 @@ int __ubase_hw_upgrade_ctx_ex(struct ubase_dev *udev, return ret; } +/** + * ubase_hw_upgrade_ctx_ex() - upgrade hardware context + * @aux_dev: auxiliary device + * @attr: the mailbox attribute pointer + * @mailbox: mailbox command address + * + * The function is used to upgrade hardware context. + * + * Context: Process context. Takes and releases , BH-safe. May sleep + * Return: 0 on success, negative error code otherwise + */ int ubase_hw_upgrade_ctx_ex(struct auxiliary_device *aux_dev, struct ubase_mbx_attr *attr, struct ubase_cmd_mailbox *mailbox) diff --git a/drivers/ub/ubase/ubase_pmem.c b/drivers/ub/ubase/ubase_pmem.c index a43f1c39c0be72afff58d361e8040c1e8403befc..71218dc25d94bb8d4d4a91e43ad7945c0725b099 100644 --- a/drivers/ub/ubase/ubase_pmem.c +++ b/drivers/ub/ubase/ubase_pmem.c @@ -336,6 +336,15 @@ void ubase_prealloc_mem_uninit(struct ubase_dev *udev) ubase_pmem_init_map[i].uninit(udev); } +/** + * ubase_adev_prealloc_supported() - determine whether to prealloc buffer + * @adev: auxiliary device + * + * This function is used to determine whether to prealloc buffer. + * + * Context: Any context. + * Return: true or false + */ bool ubase_adev_prealloc_supported(struct auxiliary_device *adev) { struct ubase_dev *udev; diff --git a/drivers/ub/ubase/ubase_qos_hw.c b/drivers/ub/ubase/ubase_qos_hw.c index 8145edc4401c46cdac22be229d4adad152575350..bb1a9db877d8940b15f15cfb9913e93015080841 100644 --- a/drivers/ub/ubase/ubase_qos_hw.c +++ b/drivers/ub/ubase/ubase_qos_hw.c @@ -436,6 +436,25 @@ static int ubase_check_sl_bitmap(struct ubase_dev *udev, unsigned long sl_bitmap return 0; } +/** + * ubase_check_qos_sch_param() - check qos schedule parameters + * @adev: auxiliary device + * @vl_bitmap: vl bitmap + * @vl_bw: vl bandwidth weight + * @vl_tsa: vl schedule mode + * @is_ets: is ETS flow control mode + * + * The function is used to check qos schedule parameters + * Obtain valid vls through 'vl_bitmap'. The vl scheduling mode 'vl_tsa' supports + * two types: dwrr and sp. The sum of the vl scheduling weights 'vl_bw' must be + * 100. When 'is_ets' is true, it indicates ETS flow control, and the scheduling + * weight for vls with sp scheduling mode must be 0; when 'is_ets' is false, it + * indicates TM flow control, and the scheduling weight for vls with sp + * scheduling mode cannot be 0. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_check_qos_sch_param(struct auxiliary_device *adev, u16 vl_bitmap, u8 *vl_bw, u8 *vl_tsa, bool is_ets) { @@ -451,6 +470,20 @@ int ubase_check_qos_sch_param(struct auxiliary_device *adev, u16 vl_bitmap, } EXPORT_SYMBOL(ubase_check_qos_sch_param); +/** + * ubase_config_tm_vl_sch() - configuring TM flow control scheduling + * @adev: auxiliary device + * @vl_bitmap: vl bitmap + * @vl_bw: vl bandwidth weight + * @vl_tsa: vl schedule mode + * + * The function is used to configure TM flow control scheduling. + * Configure the scheduling weight 'vl_bw' and scheduling mode 'vl_tsa' + * corresponding to the valid vl in 'vl_bitmap' to the TM flow control. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_config_tm_vl_sch(struct auxiliary_device *adev, u16 vl_bitmap, u8 *vl_bw, u8 *vl_tsa) { @@ -465,6 +498,25 @@ int ubase_config_tm_vl_sch(struct auxiliary_device *adev, u16 vl_bitmap, } EXPORT_SYMBOL(ubase_config_tm_vl_sch); +/** + * ubase_set_priqos_info() - set priority qos information + * @dev: device + * @sl_priqos: priority qos + * + * The function is used to set priority qos information. + * Through 'sl_priqos->sl_bitmap', obtain the valid priority sl, use sl as an + * index to get the corresponding bandwidth weight and scheduling mode from + * 'sl_priqos->weight' and 'sl_priqos->ch_mode', and configure them to the hardware. + * Specifically, when 'sl_priqos-> port_bitmap' is 0, it configures the TM flow + * control; when 'port_bitmap' is not 0, it configures the ETS flow control for + * the corresponding port. + * The SP scheduling weight for TM flow control cannot be 0; multiple SP traffic + * flows are scheduled according to their weights. For ETS flow control, the SP + * scheduling weight must be 0. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_set_priqos_info(struct device *dev, struct ubase_sl_priqos *sl_priqos) { struct ubase_dev *udev; @@ -484,6 +536,21 @@ int ubase_set_priqos_info(struct device *dev, struct ubase_sl_priqos *sl_priqos) } EXPORT_SYMBOL(ubase_set_priqos_info); +/** + * ubase_get_priqos_info() - get priority qos information + * @dev: device + * @sl_priqos: save the queried priority QoS information + * + * The function is used to get priority qos information. + * Obtain the priority sl available for the device, as well as the corresponding + * bandwidth weight and scheduling mode. + * When port_bitmap is 0, the obtained values are the bandwidth weight and + * scheduling mode for TM flow control; when port_bitmap is not 0, the obtained + * values are the bandwidth weight and scheduling mode for ETS flow control. + * + * Context: Process context. Takes and releases , BH-safe. + * Return: 0 on success, negative error code otherwise + */ int ubase_get_priqos_info(struct device *dev, struct ubase_sl_priqos *sl_priqos) { struct ubase_dev *udev; @@ -1088,6 +1155,17 @@ static bool ubase_is_udma_tp_vl(struct ubase_adev_qos *qos, u8 vl) return false; } +/** + * ubase_update_udma_dscp_vl() - update udma's dscp to vl mapping + * @adev: auxiliary device + * @dscp_vl: dscp to vl mapping + * @dscp_num: dscp number + * + * The function updates the dscp to vl mapping based on 'dscp_vl' and saves it + * to 'udma_dscp_vl' in 'truct ubase_adev_qos'. + * + * Context: Any context. + */ void ubase_update_udma_dscp_vl(struct auxiliary_device *adev, u8 *dscp_vl, u8 dscp_num) { diff --git a/drivers/ub/ubase/ubase_reset.c b/drivers/ub/ubase/ubase_reset.c index 7da51b02102690461e83a8d1d10159927912d503..b2fe6d9ef5599a8289d2af5ea98e90fdc587d50e 100644 --- a/drivers/ub/ubase/ubase_reset.c +++ b/drivers/ub/ubase/ubase_reset.c @@ -86,6 +86,15 @@ void __ubase_reset_event(struct ubase_dev *udev, } } +/** + * ubase_reset_event() - reset event processing + * @adev: auxiliary device + * @reset_type: reset type + * + * The function performs corresponding reset processing based on different 'reset_type'. + * + * Context: Any context. + */ void ubase_reset_event(struct auxiliary_device *adev, enum ubase_reset_type reset_type) { diff --git a/drivers/ub/ubase/ubase_stats.c b/drivers/ub/ubase/ubase_stats.c index 7f536e0cd537e9fd5ff326efa179d90fbe6576fd..4d6e4678686d9078d61e755da538f3523ee8667b 100644 --- a/drivers/ub/ubase/ubase_stats.c +++ b/drivers/ub/ubase/ubase_stats.c @@ -51,6 +51,17 @@ static int ubase_update_mac_stats(struct ubase_dev *udev, u16 port_id, u64 *data return ret; } +/** + * ubase_get_ub_port_stats() - get ub port stats + * @adev: auxiliary device + * @port_id: port id + * @data: ub date link layer stats + * + * The function is used to get ub port stats. + * + * Context: Process context. Takes and releases , BH-safe. Sleep. + * Return: 0 on success, negative error code otherwise + */ int ubase_get_ub_port_stats(struct auxiliary_device *adev, u16 port_id, struct ubase_ub_dl_stats *data) { diff --git a/include/ub/ubase/ubase_comm_cmd.h b/include/ub/ubase/ubase_comm_cmd.h index 7ae969c897b96dd97fd542d1c0e4d5381b4d85aa..cadc707a23e6ed23428bb1b48aa6c59583d11fbc 100644 --- a/include/ub/ubase/ubase_comm_cmd.h +++ b/include/ub/ubase/ubase_comm_cmd.h @@ -110,6 +110,23 @@ enum ubase_opcode_type { UBASE_OPC_ACTIVATE_RESP = 0xF010, }; +/** + * union ubase_mbox - ubase mailbox structure + * @in_param_l: input data storage address lower 32 bits + * @in_param_h: input data storage address high 32 bits + * @cmd: mailbox command + * @tag: queue id + * @seq_num: sequence number + * @event_en: 0-poll mode, 1-event mode + * @mbx_ue_id: mailbox ub entity id + * @rsv: reserved bits + * @status: mailbox command execution completion status, 0-success, 1-fail + * @hw_run: hardware running status, 0-not running, 1-running + * @rsv1: reserved bits + * @query_status:execution result of the mailbox query command, 0-success, 1-fail + * @query_hw_run: hardware running status of the mailbox query command, 0-not running, 1-running + * @query_rsv: reserved bits + */ union ubase_mbox { struct { /* MB 0 */ @@ -137,6 +154,13 @@ union ubase_mbox { }; }; +/** + * struct ubase_cmd_buf - ubase cmd buffer structure + * @opcode: cmdq opcode + * @is_read: read or write, true for read, false for write + * @data_size: valid length of data + * @data: data buffer + */ struct ubase_cmd_buf { u16 opcode; bool is_read; @@ -144,6 +168,13 @@ struct ubase_cmd_buf { void *data; }; +/** + * struct ubase_crq_event_nb - ubase crq event notification block structure + * @opcode: cmdq crq opcode + * @back: arbitrary registered pointer + * @crq_handler: cmdq crq handle function. dev: the struct member variable 'back', + * data: the crq message data, len: the crq message data length. + */ struct ubase_crq_event_nb { u16 opcode; void *back; diff --git a/include/ub/ubase/ubase_comm_ctrlq.h b/include/ub/ubase/ubase_comm_ctrlq.h index b1ee6552405261f4f7286039bd42bc416f92272a..3e08a5ab5a4f6f02e46782dae60a9fb38c1ced80 100644 --- a/include/ub/ubase/ubase_comm_ctrlq.h +++ b/include/ub/ubase/ubase_comm_ctrlq.h @@ -58,6 +58,21 @@ enum ubase_ctrlq_opc_type_dev_register { UBASE_CTRLQ_OPC_UE_RESET_CTRL = 0x15, }; +/** + * struct ubase_ctrlq_msg - ubase ctrlq msg structure + * @service_ver: ctrlq service version + * @service_type: ctrlq service type + * @opcode: ctrlq opcode + * @need_resp: whether the message need a response + * @is_resp: whether the message is a response + * @resv: reserved bits + * @resp_ret: the return value of response message + * @resp_seq: response message sequence + * @in_size: input data buffer size + * @out_size: output data buffer size + * @in: input data buffer + * @out: output data buffer + */ struct ubase_ctrlq_msg { enum ubase_ctrlq_ser_ver service_ver; enum ubase_ctrlq_ser_type service_type; @@ -74,6 +89,13 @@ struct ubase_ctrlq_msg { void *out; }; +/** + * struct ubase_ctrlq_event_nb - ubase ctrlq event notification block structure + * @service_type: ctrlq service type + * @opcode: ctrlq crq opcode + * @back: arbitrary registered pointer + * @crq_handler: ctrlq crq handle function + */ struct ubase_ctrlq_event_nb { u8 service_type; u8 opcode; @@ -84,7 +106,6 @@ struct ubase_ctrlq_event_nb { int ubase_ctrlq_send_msg(struct auxiliary_device *aux_dev, struct ubase_ctrlq_msg *msg); - int ubase_ctrlq_register_crq_event(struct auxiliary_device *aux_dev, struct ubase_ctrlq_event_nb *nb); void ubase_ctrlq_unregister_crq_event(struct auxiliary_device *aux_dev, diff --git a/include/ub/ubase/ubase_comm_debugfs.h b/include/ub/ubase/ubase_comm_debugfs.h index dc0bd30aa93bf2aa9b8bdfaf30da1d185115dd6e..4d17c98bdfba1dafb3c3ecf1404f730f3eb39e74 100644 --- a/include/ub/ubase/ubase_comm_debugfs.h +++ b/include/ub/ubase/ubase_comm_debugfs.h @@ -11,6 +11,14 @@ struct ubase_dbgfs; +/** + * struct ubase_dbg_dentry_info - ubase debugfs dentry information + * @name: dentry name + * @dentry: the dentry for this file + * @property: property supported by this dentry + * @support: function to determine whether to create this dentry. dev: struct device, + * property: the struct number variable 'property'. + */ struct ubase_dbg_dentry_info { const char *name; struct dentry *dentry; @@ -18,6 +26,18 @@ struct ubase_dbg_dentry_info { bool (*support)(struct device *dev, u32 property); }; +/** + * struct ubase_dbg_cmd_info - ubase debugfs cmd information + * @name: file name + * @dentry_index: dentry index + * @property: property supported by this file. + * @support: function to determine whether to create this file. dev: struct device, + * property: the struct number variable 'property. + * @init: init debugfs cmd file function. dev: struct device, dirs: struct + * ubase_dbg_dentry_info, dbgfs: struct ubase_dbgfs, idx: idxth file. + * @read_func: reading debugfs detailed implementation function. s: struct seq_file, + * data: data buffer + */ struct ubase_dbg_cmd_info { const char *name; int dentry_index; @@ -28,8 +48,14 @@ struct ubase_dbg_cmd_info { int (*read_func)(struct seq_file *s, void *data); }; +/** + * struct ubase_dbgfs - ubase debugfs data structure + * @dentry: debugfs root path + * @cmd_info: ubase debugfs cmd information + * @cmd_info_size: the size of cmd_info + */ struct ubase_dbgfs { - struct dentry *dentry; /* dbgfs root path */ + struct dentry *dentry; struct ubase_dbg_cmd_info *cmd_info; int cmd_info_size; }; diff --git a/include/ub/ubase/ubase_comm_dev.h b/include/ub/ubase/ubase_comm_dev.h index 35e0496ac01ddad08afdc3f34f916e865d6158f5..8dfbb2dc91bdb273609978db473e1a7af8176375 100644 --- a/include/ub/ubase/ubase_comm_dev.h +++ b/include/ub/ubase/ubase_comm_dev.h @@ -53,6 +53,46 @@ enum ubase_reset_stage { UBASE_RESET_STAGE_UP, }; +/** + * struct ubase_caps - ubase capabilities + * @num_ceq_vectors: completion event vectors number + * @num_aeq_vectors: asynchronous event vectors umber + * @num_misc_vectors: misc event vectors number + * @aeqe_depth: the depth of asynchronous event vector queue + * @ceqe_depth: the depth of completion event vector queue + * @aeqe_size: the size of asynchronous event vector queue element + * @ceqe_size: the size of completion event vector queue element + * @total_ue_num: ue number + * @public_jetty_cnt: public jetty count + * @vl_num: vl number + * @rsvd_jetty_cnt: reserved jetty count + * @req_vl: requested vl + * @resp_vl: response vl + * @packet_pattern_mode: packet pattern mode + * @ack_queue_num: ack queue number + * @oor_en: out of order receive, 0: disable 1: enable + * @reorder_queue_en: reorder queue enable, 0: disable 1: enable + * @on_flight_size: on flight packets size + * @reorder_cap: reorder capability + * @reorder_queue_shift: reorder queue shift + * @at_times: ack timeout + * @ue_num: the total number of ue and mue + * @mac_stats_num: mac stats number + * @logic_port_bitmap: logic port bitmap + * @ub_port_logic_id: ub port logic id + * @io_port_logic_id: io port logic id + * @io_port_id: io port id + * @nl_port_id: nl port id + * @chip_id: chip id + * @die_id: die id + * @ue_id: ub entity id + * @nl_id: nl id + * @tid: ub entity tid + * @eid: ub entity eid + * @upi: ub entity upi + * @ctl_no: ub controller id + * @fw_version: firmware version + */ struct ubase_caps { u16 num_ceq_vectors; u16 num_aeq_vectors; @@ -100,17 +140,47 @@ struct ubase_caps { u32 fw_version; }; +/** + * struct ubase_res_caps - ubase resource capbilities + * @max_cnt: the resource max count + * @start_idx: start index + * @reserved_cnt: reserved count + * @depth: the queue depth of the resource + */ struct ubase_res_caps { u32 max_cnt; u32 start_idx; u32 depth; }; +/** + * struct ubase_pmem_caps - ubase physical memory capabilities + * @dma_len: iova address sapce length + * @dma_addr: iova address + */ struct ubase_pmem_caps { u64 dma_len; dma_addr_t dma_addr; }; +/** + * struct ubase_adev_caps - ubase auxiliary device capabilities + * @jfs: jfs resource capabilities + * @jfr: jfr resource capabilities + * @jfc: jfc resource capabilities + * @tp: tp resource capabilities + * @tpg: tp group resource capabilities + * @pmem: physical memory capabilities + * @utp_port_bitmap: utp port bitmap + * @jtg_max_cnt: jetty group max count + * @rc_max_cnt: rc max count + * @rc_que_depth: rc queue depth + * @ccc_max_cnt: ccc max count + * @dest_addr_max_cnt: dest addr max count + * @seid_upi_max_cnt:seid upi max count + * @tpm_max_cnt: tpm max count + * @cqe_size: cqe size + */ struct ubase_adev_caps { struct ubase_res_caps jfs; struct ubase_res_caps jfr; @@ -125,6 +195,16 @@ struct ubase_adev_caps { u16 cqe_size; }; +/** + * struct ubase_ctx_buf_cap - ubase context buffer capabilities + * @dma_ctx_buf_ba: context buffer iova address + * @slot: iova slot + * @entry_size: context entry size + * @entry_cnt: context entry count + * @cnt_per_page_shift: context entry count per page shift + * @ctx_xa: context array + * @ctx_mutex: context mutex + */ struct ubase_ctx_buf_cap { dma_addr_t dma_ctx_buf_ba; /* pass to hw */ struct iova_slot *slot; @@ -135,6 +215,16 @@ struct ubase_ctx_buf_cap { struct mutex ctx_mutex; }; +/** + * struct ubase_ctx_buf - ubase context buffer information + * @jfs: jfs context buffer capability + * @jfr: jfr context buffer capability + * @jfc: jfc context buffer capability + * @jtg: jetty group context buffer capability + * @rc: rc context buffer capability + * @tp: tp context buffer capability + * @tpg: tp group context buffer capability + */ struct ubase_ctx_buf { struct ubase_ctx_buf_cap jfs; struct ubase_ctx_buf_cap jfr; @@ -147,16 +237,54 @@ struct ubase_ctx_buf { }; struct net_device; + +/** + * struct ubase_adev_com - ubase auxiliary device common information + * @adev: auxiliary device + * @netdev: network device + */ struct ubase_adev_com { struct auxiliary_device *adev; struct net_device *netdev; }; +/** + * struct ubase_resource_space - ubase resource space + * @addr_unmapped: unmapped address + * @addr: mapped address + */ struct ubase_resource_space { resource_size_t addr_unmapped; void __iomem *addr; }; +/** + * struct ubase_adev_qos - ubase auxiliary device qos information + * @rdma_vl_num: rdma vl number + * @rdma_tp_vl_num: rdma tp vl number + * @rdma_ctp_vl_num: rdma ctp vl number + * @rdma_tp_resp_vl_offset: rdma tp response vl offset, + * rdma_tp_resp_vl = rdma_ctp_resp_vl + rdma_tp_resp_vl_offset + * @rdma_ctp_resp_vl_offset: rdma ctp response vl offset, + * rdma_ctp_resp_vl = rdma_ctp_resp_vl + rdma_ctp_resp_vl_offset + * @max_vl: max vl number + * @resv: reserved bits + * @rdma_sl_num: rdma sl number + * @rdma_tp_sl_num: rdma tp sl number + * @rdma_ctp_sl_num: rdma ctp sl number + * @nic_sl_num: nic sl number + * @nic_vl_num: nic vl number + * @rdma_vl: rdma vl + * @rdma_tp_req_vl: rdma tp request vl + * @rdma_ctp_req_vl: rdma ctp request vl + * @rdma_sl: rdma sl + * @rdma_tp_sl: rdma tp sl + * @rdma_ctp_sl: rdma ctp sl + * @nic_sl: nic sl + * @nic_vl: nic vl + * @sl_vl: sl to vl mapping + * @rdma_dscp_vl: rdma dscp to vl mapping + */ struct ubase_adev_qos { /* udma/cdma resource */ u8 sl_num; @@ -189,6 +317,11 @@ struct ubase_adev_qos { u8 ue_sl_vl[UBASE_MAX_SL_NUM]; }; +/** + * struct ubase_ue_node - ubase ub entity list node + * @list: list head + * @bus_ue_id: bus ub entity id + */ struct ubase_ue_node { struct list_head list; u16 bus_ue_id; @@ -211,6 +344,11 @@ struct ubase_ue_caps { }; #define UBASE_BUS_EID_LEN 4 + +/** + * struct ubase_bus_eid - bus eid + * @eid: bus eid + */ struct ubase_bus_eid { u32 eid[UBASE_BUS_EID_LEN]; }; @@ -219,7 +357,6 @@ bool ubase_adev_ubl_supported(struct auxiliary_device *adev); bool ubase_adev_ctrlq_supported(struct auxiliary_device *adev); bool ubase_adev_eth_mac_supported(struct auxiliary_device *adev); bool ubase_adev_prealloc_supported(struct auxiliary_device *aux_dev); - struct ubase_resource_space *ubase_get_io_base(struct auxiliary_device *adev); struct ubase_resource_space *ubase_get_mem_base(struct auxiliary_device *adev); struct ubase_caps *ubase_get_dev_caps(struct auxiliary_device *adev); @@ -227,34 +364,27 @@ struct ubase_adev_caps *ubase_get_unic_caps(struct auxiliary_device *adev); struct ubase_adev_caps *ubase_get_udma_caps(struct auxiliary_device *adev); struct ubase_adev_caps *ubase_get_cdma_caps(struct auxiliary_device *adev); struct ubase_adev_qos *ubase_get_adev_qos(struct auxiliary_device *adev); - void ubase_reset_event(struct auxiliary_device *adev, enum ubase_reset_type reset_type); enum ubase_reset_stage ubase_get_reset_stage(struct auxiliary_device *adev); - void ubase_virt_register(struct auxiliary_device *adev, void (*virt_handler)(struct auxiliary_device *adev, u16 bus_ue_id, bool is_en)); void ubase_virt_unregister(struct auxiliary_device *adev); - void ubase_port_register(struct auxiliary_device *adev, void (*port_handler)(struct auxiliary_device *adev, bool link_up)); void ubase_port_unregister(struct auxiliary_device *adev); - void ubase_reset_register(struct auxiliary_device *adev, void (*reset_handler)(struct auxiliary_device *adev, enum ubase_reset_stage stage)); void ubase_reset_unregister(struct auxiliary_device *adev); - void ubase_activate_register(struct auxiliary_device *adev, void (*activate_handler)(struct auxiliary_device *adev, bool activate)); void ubase_activate_unregister(struct auxiliary_device *adev); - int ubase_activate_dev(struct auxiliary_device *adev); int ubase_deactivate_dev(struct auxiliary_device *adev); - int ubase_get_bus_eid(struct auxiliary_device *adev, struct ubase_bus_eid *eid); #endif diff --git a/include/ub/ubase/ubase_comm_eq.h b/include/ub/ubase/ubase_comm_eq.h index fe97de1dd1ac3baf58bd9b77335500ea688751e5..d1efad0a79b3a4f43b116ce2ac9e5c5aadf799f8 100644 --- a/include/ub/ubase/ubase_comm_eq.h +++ b/include/ub/ubase/ubase_comm_eq.h @@ -50,6 +50,13 @@ enum ubase_event_type { UBASE_EVENT_TYPE_MAX }; +/** + * struct ubase_event_nb - ubase event notification block + * @drv_type: auxiliary device driver type + * @event_type: event type + * @nb: notifier block + * @back: arbitrary registered pointer + */ struct ubase_event_nb { enum ubase_drv_type drv_type; u8 event_type; @@ -57,6 +64,20 @@ struct ubase_event_nb { void *back; }; +/** + * struct ubase_aeqe - asynchronous event interrupt queue elements + * @event_type: event type + * @sub_type: sub event type + * @rsv0: reserved bits + * @owner: owner bit + * @num: jfsn/jettyn/jfrn/jfcn/jtgn/tpn + * @rsv1: reserved bits + * @out_param: mailbox output parameter + * @seq_num: mailbox sequence number + * @status: mailbox status + * @event: aeqe event information + * @rsv: reserved bits + */ struct ubase_aeqe { u32 event_type : 8; u32 sub_type : 8; @@ -82,6 +103,12 @@ struct ubase_aeqe { u32 rsv[12]; }; +/** + * struct ubase_aeq_notify_info - aeq notification information + * @event_type: event type + * @sub_type: sub event type + * @aeqe: aeq elements + */ struct ubase_aeq_notify_info { u8 event_type; u8 sub_type; @@ -92,7 +119,6 @@ int ubase_event_register(struct auxiliary_device *adev, struct ubase_event_nb *cb); void ubase_event_unregister(struct auxiliary_device *adev, struct ubase_event_nb *cb); - int ubase_comp_register(struct auxiliary_device *adev, int (*comp_handler)(struct notifier_block *nb, unsigned long jfcn, void *data)); diff --git a/include/ub/ubase/ubase_comm_hw.h b/include/ub/ubase/ubase_comm_hw.h index ba3717fb16b377f9373e80be6df8d8550b4d5da8..2efac24e326856564ac7c2f8d8d3e3aa039f2406 100644 --- a/include/ub/ubase/ubase_comm_hw.h +++ b/include/ub/ubase/ubase_comm_hw.h @@ -19,6 +19,16 @@ #define UBASE_JTG_CTX_SIZE 8 #define UBASE_DESC_DATA_LEN 6 + +/** + * struct ubase_cmdq_desc - Command queue descriptor + * @opcode: Command opcode + * @flag: Command flag + * @bd_num: bd number. One bd is 32 bytes, and the first db is 24 bytes. + * @ret: Command return value + * @rsv: reserved + * @data: Command data + */ struct ubase_cmdq_desc { __le16 opcode; u8 flag; @@ -28,6 +38,16 @@ struct ubase_cmdq_desc { __le32 data[UBASE_DESC_DATA_LEN]; }; +/** + * struct ubase_cmdq_ring - Command ring queue information + * @ci: consumer indicator + * @pi: producer indicator + * @desc_num: descriptors number + * @tx_timeout: transmit timeout interval + * @desc_dma_addr: dma address of descriptors + * @desc: Command queue descriptor + * @lock: spinlock + */ struct ubase_cmdq_ring { u32 ci; u32 pi; @@ -38,11 +58,24 @@ struct ubase_cmdq_ring { spinlock_t lock; }; +/** + * struct ubase_cmdq - cmmand queue + * @csq: command send queue + * @crq: command receive queue + */ struct ubase_cmdq { struct ubase_cmdq_ring csq; struct ubase_cmdq_ring crq; }; +/** + * struct ubase_hw - hardware information + * @rs0_base: resource0 space base addr + * @io_base: io space base addr + * @mem_base: memory space base addr + * @cmdq: command queue + * @state: state of the hardware + */ struct ubase_hw { struct ubase_resource_space rs0_base; struct ubase_resource_space io_base; @@ -51,6 +84,13 @@ struct ubase_hw { unsigned long state; }; +/** + * struct ubase_mbx_event_context - mailbox event context + * @done: completion object to wait for event + * @result: mailbox execution result + * @out_param: mailbox output parameter + * @seq_num: mailbox sequence number + */ struct ubase_mbx_event_context { struct completion done; int result; diff --git a/include/ub/ubase/ubase_comm_mbx.h b/include/ub/ubase/ubase_comm_mbx.h index 26c625f80a778906eeedaa0e6c1f9b2f10b35ef3..9e7bbf1faf9ee47cca97852567c4bcf190e1b756 100644 --- a/include/ub/ubase/ubase_comm_mbx.h +++ b/include/ub/ubase/ubase_comm_mbx.h @@ -10,11 +10,23 @@ #include #include +/** + * struct ubase_cmd_mailbox - mailbox cmmand address + * @buf: virtual address + * @dma: dma address + */ struct ubase_cmd_mailbox { void *buf; dma_addr_t dma; }; +/** + * struct ubase_mbx_attr - mailbox attribute + * @tag: queue id + * @rsv: reserved bits + * @op: mailbox opcode + * @mbx_ue_id: mailbox ub entity id + */ struct ubase_mbx_attr { __le32 tag : 24; __le32 rsv : 8; @@ -78,11 +90,21 @@ enum ubase_mbox_opcode { struct ubase_cmd_mailbox *ubase_alloc_cmd_mailbox(struct auxiliary_device *aux_dev); void ubase_free_cmd_mailbox(struct auxiliary_device *aux_dev, struct ubase_cmd_mailbox *mailbox); - int ubase_hw_upgrade_ctx_ex(struct auxiliary_device *aux_dev, struct ubase_mbx_attr *attr, struct ubase_cmd_mailbox *mailbox); +/** + * ubase_fill_mbx_attr() - fill mailbox attribute + * @attr: mailbox attribute + * @tag: queue id + * @op: mailbox opcode + * @mbx_ue_id: mailbox ub entity id + * + * The function is used to assign 'tag', 'op', and 'mbx_ue_id' to 'struct ubase_mbx_attr'. + * + * Context: Process context. + */ static inline void ubase_fill_mbx_attr(struct ubase_mbx_attr *attr, u32 tag, u8 op, u8 mbx_ue_id) { diff --git a/include/ub/ubase/ubase_comm_qos.h b/include/ub/ubase/ubase_comm_qos.h index 01fc6942ca01d9d49c62b7ddde99eb3b56a75c56..daacd537658b3cea2b98c2a9752c3216a0dd9894 100644 --- a/include/ub/ubase/ubase_comm_qos.h +++ b/include/ub/ubase/ubase_comm_qos.h @@ -16,6 +16,13 @@ enum ubase_sl_sched_mode { UBASE_SL_DWRR = IEEE_8021QAZ_TSA_ETS, }; +/** + * struct ubase_sl_priqos - priority qos + * @port_bitmap: port bitmap + * @sl_bitmap: sl bitmap + * @weight: bandwidth weight + * @sch_mode: schedule mode + */ struct ubase_sl_priqos { u32 port_bitmap; u32 sl_bitmap; diff --git a/include/ub/ubase/ubase_comm_stats.h b/include/ub/ubase/ubase_comm_stats.h index fdafc18e6700ebb29104b264ef08cb6fb6c6c5f1..52a766e7bab0b754cd6b730e84f52d9235cfb2ea 100644 --- a/include/ub/ubase/ubase_comm_stats.h +++ b/include/ub/ubase/ubase_comm_stats.h @@ -210,6 +210,17 @@ struct ubase_eth_mac_stats { u64 rx_merge_frame_smd_error_pkts; }; +/** + * struct ubase_perf_stats_result - traffic bandwidth statistics results + * @valid: data valid flag, 0-invalid, 1-valid + * @resv0: reserved bits + * @port_id: port id + * @resv1: reserved bits + * @tx_port_bw: tx port bandwidth + * @rx_port_bw: rx port bandwidth + * @tx_vl_bw: tx vl bandwidth + * @rx_vl_bw: rx vl bandwidth + */ struct ubase_perf_stats_result { u8 valid : 1; u8 resv0 : 7;