9sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget-/translations/zh_CN/userspace-api/fwctl/fwctlmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget-/translations/zh_TW/userspace-api/fwctl/fwctlmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget-/translations/it_IT/userspace-api/fwctl/fwctlmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget-/translations/ja_JP/userspace-api/fwctl/fwctlmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget-/translations/ko_KR/userspace-api/fwctl/fwctlmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget-/translations/sp_SP/userspace-api/fwctl/fwctlmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhG/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl.rsthKubhsection)}(hhh](htitle)}(hfwctl subsystemh]hfwctl subsystem}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh field_list)}(hhh]hfield)}(hhh](h field_name)}(hAuthorh]hAuthor}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh field_body)}(hJason Gunthorpe h]h paragraph)}(hJason Gunthorpeh]hJason Gunthorpe}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hOverviewh]hOverview}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhK ubh)}(hX[Modern devices contain extensive amounts of FW, and in many cases, are largely software-defined pieces of hardware. The evolution of this approach is largely a reaction to Moore's Law where a chip tape out is now highly expensive, and the chip design is extremely large. Replacing fixed HW logic with a flexible and tightly coupled FW/HW combination is an effective risk mitigation against chip respin. Problems in the HW design can be counteracted in device FW. This is especially true for devices which present a stable and backwards compatible interface to the operating system driver (such as NVMe).h]hX]Modern devices contain extensive amounts of FW, and in many cases, are largely software-defined pieces of hardware. The evolution of this approach is largely a reaction to Moore’s Law where a chip tape out is now highly expensive, and the chip design is extremely large. Replacing fixed HW logic with a flexible and tightly coupled FW/HW combination is an effective risk mitigation against chip respin. Problems in the HW design can be counteracted in device FW. This is especially true for devices which present a stable and backwards compatible interface to the operating system driver (such as NVMe).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hj hhubh)}(hThe FW layer in devices has grown to incredible size and devices frequently integrate clusters of fast processors to run it. For example, mlx5 devices have over 30MB of FW code, and big configurations operate with over 1GB of FW managed runtime state.h]hThe FW layer in devices has grown to incredible size and devices frequently integrate clusters of fast processors to run it. For example, mlx5 devices have over 30MB of FW code, and big configurations operate with over 1GB of FW managed runtime state.}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hXThe availability of such a flexible layer has created quite a variety in the industry where single pieces of silicon are now configurable software-defined devices and can operate in substantially different ways depending on the need. Further, we often see cases where specific sites wish to operate devices in ways that are highly specialized and require applications that have been tailored to their unique configuration.h]hXThe availability of such a flexible layer has created quite a variety in the industry where single pieces of silicon are now configurable software-defined devices and can operate in substantially different ways depending on the need. Further, we often see cases where specific sites wish to operate devices in ways that are highly specialized and require applications that have been tailored to their unique configuration.}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX9Further, devices have become multi-functional and integrated to the point they no longer fit neatly into the kernel's division of subsystems. Modern multi-functional devices have drivers, such as bnxt/ice/mlx5/pds, that span many subsystems while sharing the underlying hardware using the auxiliary device system.h]hX;Further, devices have become multi-functional and integrated to the point they no longer fit neatly into the kernel’s division of subsystems. Modern multi-functional devices have drivers, such as bnxt/ice/mlx5/pds, that span many subsystems while sharing the underlying hardware using the auxiliary device system.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hj hhubh)}(hXAll together this creates a challenge for the operating system, where devices have an expansive FW environment that needs robust device-specific debugging support, and FW-driven functionality that is not well suited to “generic” interfaces. fwctl seeks to allow access to the full device functionality from user space in the areas of debuggability, management, and first-boot/nth-boot provisioning.h]hXAll together this creates a challenge for the operating system, where devices have an expansive FW environment that needs robust device-specific debugging support, and FW-driven functionality that is not well suited to “generic” interfaces. fwctl seeks to allow access to the full device functionality from user space in the areas of debuggability, management, and first-boot/nth-boot provisioning.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hj hhubh)}(hXfwctl is aimed at the common device design pattern where the OS and FW communicate via an RPC message layer constructed with a queue or mailbox scheme. In this case the driver will typically have some layer to deliver RPC messages and collect RPC responses from device FW. The in-kernel subsystem drivers that operate the device for its primary purposes will use these RPCs to build their drivers, but devices also usually have a set of ancillary RPCs that don't really fit into any specific subsystem. For example, a HW RAID controller is primarily operated by the block layer but also comes with a set of RPCs to administer the construction of drives within the HW RAID.h]hXfwctl is aimed at the common device design pattern where the OS and FW communicate via an RPC message layer constructed with a queue or mailbox scheme. In this case the driver will typically have some layer to deliver RPC messages and collect RPC responses from device FW. The in-kernel subsystem drivers that operate the device for its primary purposes will use these RPCs to build their drivers, but devices also usually have a set of ancillary RPCs that don’t really fit into any specific subsystem. For example, a HW RAID controller is primarily operated by the block layer but also comes with a set of RPCs to administer the construction of drives within the HW RAID.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hj hhubh)}(hX(In the past when devices were more single function, individual subsystems would grow different approaches to solving some of these common problems. For instance monitoring device health, manipulating its FLASH, debugging the FW, provisioning, all have various unique interfaces across the kernel.h]hX(In the past when devices were more single function, individual subsystems would grow different approaches to solving some of these common problems. For instance monitoring device health, manipulating its FLASH, debugging the FW, provisioning, all have various unique interfaces across the kernel.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hj hhubh)}(hXfwctl's purpose is to define a common set of limited rules, described below, that allow user space to securely construct and execute RPCs inside device FW. The rules serve as an agreement between the operating system and FW on how to correctly design the RPC interface. As a uAPI the subsystem provides a thin layer of discovery and a generic uAPI to deliver the RPCs and collect the response. It supports a system of user space libraries and tools which will use this interface to control the device using the device native protocols.h]hXfwctl’s purpose is to define a common set of limited rules, described below, that allow user space to securely construct and execute RPCs inside device FW. The rules serve as an agreement between the operating system and FW on how to correctly design the RPC interface. As a uAPI the subsystem provides a thin layer of discovery and a generic uAPI to deliver the RPCs and collect the response. It supports a system of user space libraries and tools which will use this interface to control the device using the device native protocols.}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK=hj hhubh)}(hhh](h)}(hScope of Actionh]hScope of Action}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKFubh)}(hfwctl drivers are strictly restricted to being a way to operate the device FW. It is not an avenue to access random kernel internals, or other operating system SW states.h]hfwctl drivers are strictly restricted to being a way to operate the device FW. It is not an avenue to access random kernel internals, or other operating system SW states.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjhhubh)}(hX(fwctl instances must operate on a well-defined device function, and the device should have a well-defined security model for what scope within the physical device the function is permitted to access. For instance, the most complex PCIe device today may broadly have several function-level scopes:h]hX(fwctl instances must operate on a well-defined device function, and the device should have a well-defined security model for what scope within the physical device the function is permitted to access. For instance, the most complex PCIe device today may broadly have several function-level scopes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjhhubh block_quote)}(h1. A privileged function with full access to the on-device global state and configuration 2. Multiple hypervisor functions with control over itself and child functions used with VMs 3. Multiple VM functions tightly scoped within the VM h]henumerated_list)}(hhh](h list_item)}(hWA privileged function with full access to the on-device global state and configuration h]h)}(hVA privileged function with full access to the on-device global state and configurationh]hVA privileged function with full access to the on-device global state and configuration}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hYMultiple hypervisor functions with control over itself and child functions used with VMs h]h)}(hXMultiple hypervisor functions with control over itself and child functions used with VMsh]hXMultiple hypervisor functions with control over itself and child functions used with VMs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h3Multiple VM functions tightly scoped within the VM h]h)}(h2Multiple VM functions tightly scoped within the VMh]h2Multiple VM functions tightly scoped within the VM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKWhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhKQhjhhubh)}(hXJThe device may create a logical parent/child relationship between these scopes. For instance a child VM's FW may be within the scope of the hypervisor FW. It is quite common in the VFIO world that the hypervisor environment has a complex provisioning/profiling/configuration responsibility for the function VFIO assigns to the VM.h]hXLThe device may create a logical parent/child relationship between these scopes. For instance a child VM’s FW may be within the scope of the hypervisor FW. It is quite common in the VFIO world that the hypervisor environment has a complex provisioning/profiling/configuration responsibility for the function VFIO assigns to the VM.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKYhjhhubh)}(hFurther, within the function, devices often have RPC commands that fall within some general scopes of action (see enum fwctl_rpc_scope):h]hFurther, within the function, devices often have RPC commands that fall within some general scopes of action (see enum fwctl_rpc_scope):}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hjhhubj)}(hXz1. Access to function & child configuration, FLASH, etc. that becomes live at a function reset. Access to function & child runtime configuration that is transparent or non-disruptive to any driver or VM. 2. Read-only access to function debug information that may report on FW objects in the function & child, including FW objects owned by other kernel subsystems. 3. Write access to function & child debug information strictly compatible with the principles of kernel lockdown and kernel integrity protection. Triggers a kernel Taint. 4. Full debug device access. Triggers a kernel Taint, requires CAP_SYS_RAWIO. h]j)}(hhh](j)}(hAccess to function & child configuration, FLASH, etc. that becomes live at a function reset. Access to function & child runtime configuration that is transparent or non-disruptive to any driver or VM. h]h)}(hAccess to function & child configuration, FLASH, etc. that becomes live at a function reset. Access to function & child runtime configuration that is transparent or non-disruptive to any driver or VM.h]hAccess to function & child configuration, FLASH, etc. that becomes live at a function reset. Access to function & child runtime configuration that is transparent or non-disruptive to any driver or VM.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjBubah}(h]h ]h"]h$]h&]uh1jhj?ubj)}(hRead-only access to function debug information that may report on FW objects in the function & child, including FW objects owned by other kernel subsystems. h]h)}(hRead-only access to function debug information that may report on FW objects in the function & child, including FW objects owned by other kernel subsystems.h]hRead-only access to function debug information that may report on FW objects in the function & child, including FW objects owned by other kernel subsystems.}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKfhjZubah}(h]h ]h"]h$]h&]uh1jhj?ubj)}(hWrite access to function & child debug information strictly compatible with the principles of kernel lockdown and kernel integrity protection. Triggers a kernel Taint. h]h)}(hWrite access to function & child debug information strictly compatible with the principles of kernel lockdown and kernel integrity protection. Triggers a kernel Taint.h]hWrite access to function & child debug information strictly compatible with the principles of kernel lockdown and kernel integrity protection. Triggers a kernel Taint.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjrubah}(h]h ]h"]h$]h&]uh1jhj?ubj)}(hKFull debug device access. Triggers a kernel Taint, requires CAP_SYS_RAWIO. h]h)}(hJFull debug device access. Triggers a kernel Taint, requires CAP_SYS_RAWIO.h]hJFull debug device access. Triggers a kernel Taint, requires CAP_SYS_RAWIO.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjubah}(h]h ]h"]h$]h&]uh1jhj?ubeh}(h]h ]h"]h$]h&]jjjhjjuh1jhj;ubah}(h]h ]h"]h$]h&]uh1jhhhKbhjhhubh)}(hUser space will provide a scope label on each RPC and the kernel must enforce the above CAPs and taints based on that scope. A combination of kernel and FW can enforce that RPCs are placed in the correct scope by user space.h]hUser space will provide a scope label on each RPC and the kernel must enforce the above CAPs and taints based on that scope. A combination of kernel and FW can enforce that RPCs are placed in the correct scope by user space.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKphjhhubeh}(h]scope-of-actionah ]h"]scope of actionah$]h&]uh1hhj hhhhhKFubh)}(hhh](h)}(hDenied behaviorh]hDenied behavior}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKuubh)}(hThere are many things this interface must not allow user space to do (without a Taint or CAP), broadly derived from the principles of kernel lockdown. Some examples:h]hThere are many things this interface must not allow user space to do (without a Taint or CAP), broadly derived from the principles of kernel lockdown. Some examples:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKwhjhhubj)}(hX1. DMA to/from arbitrary memory, hang the system, compromise FW integrity with untrusted code, or otherwise compromise device or system security and integrity. 2. Provide an abnormal “back door” to kernel drivers. No manipulation of kernel objects owned by kernel drivers. 3. Directly configure or otherwise control kernel drivers. A subsystem kernel driver can react to the device configuration at function reset/driver load time, but otherwise must not be coupled to fwctl. 4. Operate the HW in a way that overlaps with the core purpose of another primary kernel subsystem, such as read/write to LBAs, send/receive of network packets, or operate an accelerator's data plane. h]j)}(hhh](j)}(hDMA to/from arbitrary memory, hang the system, compromise FW integrity with untrusted code, or otherwise compromise device or system security and integrity. h]h)}(hDMA to/from arbitrary memory, hang the system, compromise FW integrity with untrusted code, or otherwise compromise device or system security and integrity.h]hDMA to/from arbitrary memory, hang the system, compromise FW integrity with untrusted code, or otherwise compromise device or system security and integrity.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK{hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hrProvide an abnormal “back door” to kernel drivers. No manipulation of kernel objects owned by kernel drivers. h]h)}(hqProvide an abnormal “back door” to kernel drivers. No manipulation of kernel objects owned by kernel drivers.h]hqProvide an abnormal “back door” to kernel drivers. No manipulation of kernel objects owned by kernel drivers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hDirectly configure or otherwise control kernel drivers. A subsystem kernel driver can react to the device configuration at function reset/driver load time, but otherwise must not be coupled to fwctl. h]h)}(hDirectly configure or otherwise control kernel drivers. A subsystem kernel driver can react to the device configuration at function reset/driver load time, but otherwise must not be coupled to fwctl.h]hDirectly configure or otherwise control kernel drivers. A subsystem kernel driver can react to the device configuration at function reset/driver load time, but otherwise must not be coupled to fwctl.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hOperate the HW in a way that overlaps with the core purpose of another primary kernel subsystem, such as read/write to LBAs, send/receive of network packets, or operate an accelerator's data plane. h]h)}(hOperate the HW in a way that overlaps with the core purpose of another primary kernel subsystem, such as read/write to LBAs, send/receive of network packets, or operate an accelerator's data plane.h]hOperate the HW in a way that overlaps with the core purpose of another primary kernel subsystem, such as read/write to LBAs, send/receive of network packets, or operate an accelerator’s data plane.}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj2ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjjhjjuh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhK{hjhhubh)}(hRfwctl is not a replacement for device direct access subsystems like uacce or VFIO.h]hRfwctl is not a replacement for device direct access subsystems like uacce or VFIO.}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXOperations exposed through fwctl's non-taining interfaces should be fully sharable with other users of the device. For instance exposing a RPC through fwctl should never prevent a kernel subsystem from also concurrently using that same RPC or hardware unit down the road. In such cases fwctl will be less important than proper kernel subsystems that eventually emerge. Mistakes in this area resulting in clashes will be resolved in favour of a kernel implementation.h]hXOperations exposed through fwctl’s non-taining interfaces should be fully sharable with other users of the device. For instance exposing a RPC through fwctl should never prevent a kernel subsystem from also concurrently using that same RPC or hardware unit down the road. In such cases fwctl will be less important than proper kernel subsystems that eventually emerge. Mistakes in this area resulting in clashes will be resolved in favour of a kernel implementation.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]denied-behaviorah ]h"]denied behaviorah$]h&]uh1hhj hhhhhKuubeh}(h]overviewah ]h"]overviewah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hfwctl User APIh]hfwctl User API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubhtarget)}(h.. _General ioctl format:h]h}(h]h ]h"]h$]h&]refidgeneral-ioctl-formatuh1jhKhjhhhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hubh)}(h**General ioctl format**h]hstrong)}(hjh]hGeneral ioctl format}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]jah ]h"]general ioctl formatah$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjhhexpect_referenced_by_name}jjsexpect_referenced_by_id}jjsubh)}(hXxThe ioctl interface follows a general format to allow for extensibility. Each ioctl is passed a structure pointer as the argument providing the size of the structure in the first u32. The kernel checks that any structure space beyond what it understands is 0. This allows userspace to use the backward compatible portion while consistently using the newer, larger, structures.h]hXxThe ioctl interface follows a general format to allow for extensibility. Each ioctl is passed a structure pointer as the argument providing the size of the structure in the first u32. The kernel checks that any structure space beyond what it understands is 0. This allows userspace to use the backward compatible portion while consistently using the newer, larger, structures.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK hjhhubh)}(h0ioctls use a standard meaning for common errnos:h]h0ioctls use a standard meaning for common errnos:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjhhubj)}(hX- ENOTTY: The IOCTL number itself is not supported at all - E2BIG: The IOCTL number is supported, but the provided structure has non-zero in a part the kernel does not understand. - EOPNOTSUPP: The IOCTL number is supported, and the structure is understood, however a known field has a value the kernel does not understand or support. - EINVAL: Everything about the IOCTL was understood, but a field is not correct. - ENOMEM: Out of memory. - ENODEV: The underlying device has been hot-unplugged and the FD is orphaned. h]h bullet_list)}(hhh](j)}(h7ENOTTY: The IOCTL number itself is not supported at allh]h)}(hjh]h7ENOTTY: The IOCTL number itself is not supported at all}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hwE2BIG: The IOCTL number is supported, but the provided structure has non-zero in a part the kernel does not understand.h]h)}(hwE2BIG: The IOCTL number is supported, but the provided structure has non-zero in a part the kernel does not understand.h]hwE2BIG: The IOCTL number is supported, but the provided structure has non-zero in a part the kernel does not understand.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hEOPNOTSUPP: The IOCTL number is supported, and the structure is understood, however a known field has a value the kernel does not understand or support.h]h)}(hEOPNOTSUPP: The IOCTL number is supported, and the structure is understood, however a known field has a value the kernel does not understand or support.h]hEOPNOTSUPP: The IOCTL number is supported, and the structure is understood, however a known field has a value the kernel does not understand or support.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hNEINVAL: Everything about the IOCTL was understood, but a field is not correct.h]h)}(hNEINVAL: Everything about the IOCTL was understood, but a field is not correct.h]hNEINVAL: Everything about the IOCTL was understood, but a field is not correct.}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhj2ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hENOMEM: Out of memory.h]h)}(hjMh]hENOMEM: Out of memory.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjKubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hUENODEV: The underlying device has been hot-unplugged and the FD is orphaned. h]hdefinition_list)}(hhh]hdefinition_list_item)}(hMENODEV: The underlying device has been hot-unplugged and the FD is orphaned. h](hterm)}(hBENODEV: The underlying device has been hot-unplugged and the FD ish]hBENODEV: The underlying device has been hot-unplugged and the FD is}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjnubh definition)}(hhh]h)}(h orphaned.h]h orphaned.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjnubeh}(h]h ]h"]h$]h&]uh1jlhjhKhjiubah}(h]h ]h"]h$]h&]uh1jghjcubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet-uh1jhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjhKhjhhubh)}(h5As well as additional errnos, within specific ioctls.h]h5As well as additional errnos, within specific ioctls.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK!hjhhubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](singlefwctl_info (C struct) c.fwctl_infohNtauh1jhjhhhjhNubhdesc)}(hhh](hdesc_signature)}(h fwctl_infoh]hdesc_signature_line)}(hstruct fwctl_infoh](hdesc_sig_keyword)}(hstructh]hstruct}(hjhhhNhNubah}(h]h ]kah"]h$]h&]uh1jhjhhhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK%ubhdesc_sig_space)}(h h]h }(hjhhhNhNubah}(h]h ]wah"]h$]h&]uh1jhjhhhjhK%ubh desc_name)}(h fwctl_infoh]h desc_sig_name)}(hjh]h fwctl_info}(hjhhhNhNubah}(h]h ]nah"]h$]h&]uh1jhjubah}(h]h ](sig-namedescnameeh"]h$]h&]hhuh1jhjhhhjhK%ubeh}(h]h ]h"]h$]h&]hh add_permalinkuh1jsphinx_line_type declaratorhjhhhjhK%ubah}(h]jah ](sig sig-objecteh"]h$]h&] is_multiline _toc_parts) _toc_namehuh1jhjhK%hjhhubh desc_content)}(hhh]h)}(hioctl(FWCTL_INFO)h]hioctl(FWCTL_INFO)}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK3hjDhhubah}(h]h ]h"]h$]h&]uh1jBhjhhhjhK%ubeh}(h]h ](cstructeh"]h$]h&]domainj_objtypej`desctypej`noindex noindexentrynocontentsentryuh1jhhhjhjhNubh container)}(hX**Definition**:: struct fwctl_info { __u32 size; __u32 flags; __u32 out_device_type; __u32 device_data_len; __aligned_u64 out_device_data; }; **Members** ``size`` sizeof(struct fwctl_info) ``flags`` Must be 0 ``out_device_type`` Returns the type of the device from enum fwctl_device_type ``device_data_len`` On input the length of the out_device_data memory. On output the size of the kernel's device_data which may be larger or smaller than the input. Maybe 0 on input. ``out_device_data`` Pointer to a memory of device_data_len bytes. Kernel will fill the entire memory, zeroing as required.h](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1jhjpubh:}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK7hjlubh literal_block)}(hstruct fwctl_info { __u32 size; __u32 flags; __u32 out_device_type; __u32 device_data_len; __aligned_u64 out_device_data; };h]hstruct fwctl_info { __u32 size; __u32 flags; __u32 out_device_type; __u32 device_data_len; __aligned_u64 out_device_data; };}hjsbah}(h]h ]h"]h$]h&]hhuh1jhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK9hjlubh)}(h **Members**h]j)}(hjh]hMembers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKAhjlubjh)}(hhh](jm)}(h#``size`` sizeof(struct fwctl_info) h](js)}(h``size``h]hliteral)}(hjh]hsize}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK5hjubj)}(hhh]h)}(hsizeof(struct fwctl_info)h]hsizeof(struct fwctl_info)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK5hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK5hjubjm)}(h``flags`` Must be 0 h](js)}(h ``flags``h]j)}(hjh]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK6hjubj)}(hhh]h)}(h Must be 0h]h Must be 0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK6hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK6hjubjm)}(hO``out_device_type`` Returns the type of the device from enum fwctl_device_type h](js)}(h``out_device_type``h]j)}(hj3h]hout_device_type}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj1ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK7hj-ubj)}(hhh]h)}(h:Returns the type of the device from enum fwctl_device_typeh]h:Returns the type of the device from enum fwctl_device_type}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHhK7hjIubah}(h]h ]h"]h$]h&]uh1jhj-ubeh}(h]h ]h"]h$]h&]uh1jlhjHhK7hjubjm)}(h``device_data_len`` On input the length of the out_device_data memory. On output the size of the kernel's device_data which may be larger or smaller than the input. Maybe 0 on input. h](js)}(h``device_data_len``h]j)}(hjlh]hdevice_data_len}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK:hjfubj)}(hhh]h)}(hOn input the length of the out_device_data memory. On output the size of the kernel's device_data which may be larger or smaller than the input. Maybe 0 on input.h]hOn input the length of the out_device_data memory. On output the size of the kernel’s device_data which may be larger or smaller than the input. Maybe 0 on input.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK8hjubah}(h]h ]h"]h$]h&]uh1jhjfubeh}(h]h ]h"]h$]h&]uh1jlhjhK:hjubjm)}(hz``out_device_data`` Pointer to a memory of device_data_len bytes. Kernel will fill the entire memory, zeroing as required.h](js)}(h``out_device_data``h]j)}(hjh]hout_device_data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK;hjubj)}(hhh]h)}(hfPointer to a memory of device_data_len bytes. Kernel will fill the entire memory, zeroing as required.h]hfPointer to a memory of device_data_len bytes. Kernel will fill the entire memory, zeroing as required.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK;hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK;hjubeh}(h]h ]h"]h$]h&]uh1jghjlubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhjhNubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK?hjhhubh)}(h}Returns basic information about this fwctl instance, particularly what driver is being used to define the device_data format.h]h}Returns basic information about this fwctl instance, particularly what driver is being used to define the device_data format.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK=hjhhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_rpc_scope (C enum)c.fwctl_rpc_scopehNtauh1jhjhhhjhNubj)}(hhh](j)}(hfwctl_rpc_scopeh]j)}(henum fwctl_rpc_scopeh](j)}(henumh]henum}(hj&hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj"hhhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKCubj)}(h h]h }(hj5hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhj"hhhj4hKCubj)}(hfwctl_rpc_scopeh]j)}(hj h]hfwctl_rpc_scope}(hjGhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjCubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhj"hhhj4hKCubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjhhhj4hKCubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhj4hKChjhhubjC)}(hhh]h)}(hScope of access for the RPCh]hScope of access for the RPC}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKJhjfhhubah}(h]h ]h"]h$]h&]uh1jBhjhhhj4hKCubeh}(h]h ](j_enumeh"]h$]h&]jdj_jejjfjjgjhjiuh1jhhhjhjhNubjk)}(hX,**Constants** ``FWCTL_RPC_CONFIGURATION`` Device configuration access scope Read/write access to device configuration. When configuration is written to the device it remains in a fully supported state. ``FWCTL_RPC_DEBUG_READ_ONLY`` Read only access to debug information Readable debug information. Debug information is compatible with kernel lockdown, and does not disclose any sensitive information. For instance exposing any encryption secrets from this information is forbidden. ``FWCTL_RPC_DEBUG_WRITE`` Writable access to lockdown compatible debug information Allows write access to data in the device which may leave a fully supported state. This is intended to permit intensive and possibly invasive debugging. This scope will taint the kernel. ``FWCTL_RPC_DEBUG_WRITE_FULL`` Write access to all debug information Allows read/write access to everything. Requires CAP_SYS_RAW_IO, so it is not required to follow lockdown principals. If in doubt debugging should be placed in this scope. This scope will taint the kernel.h](h)}(h **Constants**h]j)}(hjh]h Constants}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKNhjubjh)}(hhh](jm)}(h``FWCTL_RPC_CONFIGURATION`` Device configuration access scope Read/write access to device configuration. When configuration is written to the device it remains in a fully supported state. h](js)}(h``FWCTL_RPC_CONFIGURATION``h]j)}(hjh]hFWCTL_RPC_CONFIGURATION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKThjubj)}(hhh](h)}(h!Device configuration access scopeh]h!Device configuration access scope}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKQhjubh)}(h}Read/write access to device configuration. When configuration is written to the device it remains in a fully supported state.h]h}Read/write access to device configuration. When configuration is written to the device it remains in a fully supported state.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKShjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhKThjubjm)}(hX``FWCTL_RPC_DEBUG_READ_ONLY`` Read only access to debug information Readable debug information. Debug information is compatible with kernel lockdown, and does not disclose any sensitive information. For instance exposing any encryption secrets from this information is forbidden. h](js)}(h``FWCTL_RPC_DEBUG_READ_ONLY``h]j)}(hjh]hFWCTL_RPC_DEBUG_READ_ONLY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK\hjubj)}(hhh](h)}(h%Read only access to debug informationh]h%Read only access to debug information}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKWhj ubh)}(hReadable debug information. Debug information is compatible with kernel lockdown, and does not disclose any sensitive information. For instance exposing any encryption secrets from this information is forbidden.h]hReadable debug information. Debug information is compatible with kernel lockdown, and does not disclose any sensitive information. For instance exposing any encryption secrets from this information is forbidden.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKYhj ubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK\hjubjm)}(hX``FWCTL_RPC_DEBUG_WRITE`` Writable access to lockdown compatible debug information Allows write access to data in the device which may leave a fully supported state. This is intended to permit intensive and possibly invasive debugging. This scope will taint the kernel. h](js)}(h``FWCTL_RPC_DEBUG_WRITE``h]j)}(hj<h]hFWCTL_RPC_DEBUG_WRITE}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj:ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKchj6ubj)}(hhh](h)}(h8Writable access to lockdown compatible debug informationh]h8Writable access to lockdown compatible debug information}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK_hjRubh)}(hAllows write access to data in the device which may leave a fully supported state. This is intended to permit intensive and possibly invasive debugging. This scope will taint the kernel.h]hAllows write access to data in the device which may leave a fully supported state. This is intended to permit intensive and possibly invasive debugging. This scope will taint the kernel.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKahjRubeh}(h]h ]h"]h$]h&]uh1jhj6ubeh}(h]h ]h"]h$]h&]uh1jlhjQhKchjubjm)}(hX``FWCTL_RPC_DEBUG_WRITE_FULL`` Write access to all debug information Allows read/write access to everything. Requires CAP_SYS_RAW_IO, so it is not required to follow lockdown principals. If in doubt debugging should be placed in this scope. This scope will taint the kernel.h](js)}(h``FWCTL_RPC_DEBUG_WRITE_FULL``h]j)}(hjh]hFWCTL_RPC_DEBUG_WRITE_FULL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKjhjubj)}(hhh](h)}(h%Write access to all debug informationh]h%Write access to all debug information}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKfhjubh)}(hAllows read/write access to everything. Requires CAP_SYS_RAW_IO, so it is not required to follow lockdown principals. If in doubt debugging should be placed in this scope. This scope will taint the kernel.h]hAllows read/write access to everything. Requires CAP_SYS_RAW_IO, so it is not required to follow lockdown principals. If in doubt debugging should be placed in this scope. This scope will taint the kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhKjhjubeh}(h]h ]h"]h$]h&]uh1jghjubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhjhNubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKnhjhhubh)}(hBRefer to fwctl.rst for a more detailed discussion of these scopes.h]hBRefer to fwctl.rst for a more detailed discussion of these scopes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKKhjhhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_rpc (C struct) c.fwctl_rpchNtauh1jhjhhhjhNubj)}(hhh](j)}(h fwctl_rpch]j)}(hstruct fwctl_rpch](j)}(hjh]hstruct}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKPubj)}(h h]h }(hj# hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhj hhhj" hKPubj)}(h fwctl_rpch]j)}(hj h]h fwctl_rpc}(hj5 hhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhj1 ubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhj hhhj" hKPubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hj hhhj" hKPubah}(h]j ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhj" hKPhj hhubjC)}(hhh]h)}(hioctl(FWCTL_RPC)h]hioctl(FWCTL_RPC)}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKshjT hhubah}(h]h ]h"]h$]h&]uh1jBhj hhhj" hKPubeh}(h]h ](j_structeh"]h$]h&]jdj_jejo jfjo jgjhjiuh1jhhhjhjhNubjk)}(hX**Definition**:: struct fwctl_rpc { __u32 size; __u32 scope; __u32 in_len; __u32 out_len; __aligned_u64 in; __aligned_u64 out; }; **Members** ``size`` sizeof(struct fwctl_rpc) ``scope`` One of enum fwctl_rpc_scope, required scope for the RPC ``in_len`` Length of the in memory ``out_len`` Length of the out memory ``in`` Request message in device specific format ``out`` Response message in device specific formath](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjw ubh:}(hjw hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKwhjs ubj)}(hstruct fwctl_rpc { __u32 size; __u32 scope; __u32 in_len; __u32 out_len; __aligned_u64 in; __aligned_u64 out; };h]hstruct fwctl_rpc { __u32 size; __u32 scope; __u32 in_len; __u32 out_len; __aligned_u64 in; __aligned_u64 out; };}hj sbah}(h]h ]h"]h$]h&]hhuh1jhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKyhjs ubh)}(h **Members**h]j)}(hj h]hMembers}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjs ubjh)}(hhh](jm)}(h"``size`` sizeof(struct fwctl_rpc) h](js)}(h``size``h]j)}(hj h]hsize}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKuhj ubj)}(hhh]h)}(hsizeof(struct fwctl_rpc)h]hsizeof(struct fwctl_rpc)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKuhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jlhj hKuhj ubjm)}(hB``scope`` One of enum fwctl_rpc_scope, required scope for the RPC h](js)}(h ``scope``h]j)}(hj h]hscope}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKvhj ubj)}(hhh]h)}(h7One of enum fwctl_rpc_scope, required scope for the RPCh]h7One of enum fwctl_rpc_scope, required scope for the RPC}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKvhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jlhj hKvhj ubjm)}(h#``in_len`` Length of the in memory h](js)}(h ``in_len``h]j)}(hj6 h]hin_len}(hj8 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj4 ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKwhj0 ubj)}(hhh]h)}(hLength of the in memoryh]hLength of the in memory}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjK hKwhjL ubah}(h]h ]h"]h$]h&]uh1jhj0 ubeh}(h]h ]h"]h$]h&]uh1jlhjK hKwhj ubjm)}(h%``out_len`` Length of the out memory h](js)}(h ``out_len``h]j)}(hjo h]hout_len}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjm ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKxhji ubj)}(hhh]h)}(hLength of the out memoryh]hLength of the out memory}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKxhj ubah}(h]h ]h"]h$]h&]uh1jhji ubeh}(h]h ]h"]h$]h&]uh1jlhj hKxhj ubjm)}(h1``in`` Request message in device specific format h](js)}(h``in``h]j)}(hj h]hin}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKyhj ubj)}(hhh]h)}(h)Request message in device specific formath]h)Request message in device specific format}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hKyhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jlhj hKyhj ubjm)}(h2``out`` Response message in device specific formath](js)}(h``out``h]j)}(hj h]hout}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jrhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKyhj ubj)}(hhh]h)}(h*Response message in device specific formath]h*Response message in device specific format}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKzhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jlhj hKyhj ubeh}(h]h ]h"]h$]h&]uh1jghjs ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhjhNubh)}(h**Description**h]j)}(hj$ h]h Description}(hj& hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj" ubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK}hjhhubh)}(hX9Deliver a Remote Procedure Call to the device FW and return the response. The call's parameters and return are marshaled into linear buffers of memory. Any errno indicates that delivery of the RPC to the device failed. Return status originating in the device during a successful delivery must be encoded into out.h]hX;Deliver a Remote Procedure Call to the device FW and return the response. The call’s parameters and return are marshaled into linear buffers of memory. Any errno indicates that delivery of the RPC to the device failed. Return status originating in the device during a successful delivery must be encoded into out.}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhK{hjhhubh)}(hFThe format of the buffers matches the out_device_type from FWCTL_INFO.h]hFThe format of the buffers matches the out_device_type from FWCTL_INFO.}(hjI hhhNhNubah}(h]h ]h"]h$]h&]uh1hhe/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:151: ./include/uapi/fwctl/fwctl.hhKhjhhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_info_mlx5 (C struct)c.fwctl_info_mlx5hNtauh1jhjhhhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhNubj)}(hhh](j)}(hfwctl_info_mlx5h]j)}(hstruct fwctl_info_mlx5h](j)}(hjh]hstruct}(hjr hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjn hhhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKubj)}(h h]h }(hj hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjn hhhj hKubj)}(hfwctl_info_mlx5h]j)}(hjl h]hfwctl_info_mlx5}(hj hhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhj ubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjn hhhj hKubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjj hhhj hKubah}(h]jd ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhj hKhjg hhubjC)}(hhh]h)}(h!ioctl(FWCTL_INFO) out_device_datah]h!ioctl(FWCTL_INFO) out_device_data}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhj hhubah}(h]h ]h"]h$]h&]uh1jBhjg hhhj hKubeh}(h]h ](j_structeh"]h$]h&]jdj_jej jfj jgjhjiuh1jhhhjhjf hNubjk)}(hX**Definition**:: struct fwctl_info_mlx5 { __u32 uid; __u32 uctx_caps; }; **Members** ``uid`` The FW UID this FD is bound to. Each command header will force this value. ``uctx_caps`` The FW capabilities that are enabled for the uid.h](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhj ubj)}(h?struct fwctl_info_mlx5 { __u32 uid; __u32 uctx_caps; };h]h?struct fwctl_info_mlx5 { __u32 uid; __u32 uctx_caps; };}hj sbah}(h]h ]h"]h$]h&]hhuh1jhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhj ubh)}(h **Members**h]j)}(hj h]hMembers}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhK#hj ubjh)}(hhh](jm)}(hS``uid`` The FW UID this FD is bound to. Each command header will force this value. h](js)}(h``uid``h]j)}(hj! h]huid}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jrhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhj ubj)}(hhh]h)}(hJThe FW UID this FD is bound to. Each command header will force this value.h]hJThe FW UID this FD is bound to. Each command header will force this value.}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhj7 ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jlhj6 hKhj ubjm)}(h?``uctx_caps`` The FW capabilities that are enabled for the uid.h](js)}(h ``uctx_caps``h]j)}(hj[ h]h uctx_caps}(hj] hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjY ubah}(h]h ]h"]h$]h&]uh1jrhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhjU ubj)}(hhh]h)}(h1The FW capabilities that are enabled for the uid.h]h1The FW capabilities that are enabled for the uid.}(hjt hhhNhNubah}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhjq ubah}(h]h ]h"]h$]h&]uh1jhjU ubeh}(h]h ]h"]h$]h&]uh1jlhjp hKhj ubeh}(h]h ]h"]h$]h&]uh1jghj ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhjf hNubh)}(h**Description**h]j)}(hj h]h Description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhjhhubh)}(h:Return basic information about the FW interface available.h]h:Return basic information about the FW interface available.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhd/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:152: ./include/uapi/fwctl/mlx5.hhKhjhhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_info_pds (C struct)c.fwctl_info_pdshNtauh1jhjhhhNhNubj)}(hhh](j)}(hfwctl_info_pdsh]j)}(hstruct fwctl_info_pdsh](j)}(hjh]hstruct}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKubj)}(h h]h }(hj hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhj hhhj hKubj)}(hfwctl_info_pdsh]j)}(hj h]hfwctl_info_pds}(hj hhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhj ubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhj hhhj hKubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hj hhhj hKubah}(h]j ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhj hKhj hhubjC)}(hhh]h}(h]h ]h"]h$]h&]uh1jBhj hhhj hKubeh}(h]h ](j_structeh"]h$]h&]jdj_jej' jfj' jgjhjiuh1jhhhjhNhNubjk)}(h**Definition**:: struct fwctl_info_pds { __u32 uctx_caps; }; **Members** ``uctx_caps`` bitmap of firmware capabilitiesh](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj/ ubh:}(hj/ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhj+ ubj)}(h/struct fwctl_info_pds { __u32 uctx_caps; };h]h/struct fwctl_info_pds { __u32 uctx_caps; };}hjL sbah}(h]h ]h"]h$]h&]hhuh1jhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhj+ ubh)}(h **Members**h]j)}(hj] h]hMembers}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj[ ubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhj+ ubjh)}(hhh]jm)}(h-``uctx_caps`` bitmap of firmware capabilitiesh](js)}(h ``uctx_caps``h]j)}(hj| h]h uctx_caps}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjz ubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhjv ubj)}(hhh]h)}(hbitmap of firmware capabilitiesh]hbitmap of firmware capabilities}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhj ubah}(h]h ]h"]h$]h&]uh1jhjv ubeh}(h]h ]h"]h$]h&]uh1jlhj hKhjs ubah}(h]h ]h"]h$]h&]uh1jghj+ ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhNhNubh)}(h**Description**h]j)}(hj h]h Description}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhjhhubh)}(h:Return basic information about the FW interface available.h]h:Return basic information about the FW interface available.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhjhhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jpds_fwctl_capabilities (C enum)c.pds_fwctl_capabilitieshNtauh1jhjhhhNhNubj)}(hhh](j)}(hpds_fwctl_capabilitiesh]j)}(henum pds_fwctl_capabilitiesh](j)}(hj(h]henum}(hj hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhj hhhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKubj)}(h h]h }(hj hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhj hhhj hKubj)}(hpds_fwctl_capabilitiesh]j)}(hj h]hpds_fwctl_capabilities}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhj hhhj hKubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hj hhhj hKubah}(h]j ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhj hKhj hhubjC)}(hhh]h}(h]h ]h"]h$]h&]uh1jBhj hhhj hKubeh}(h]h ](j_enumeh"]h$]h&]jdj_jejHjfjHjgjhjiuh1jhhhjhNhNubjk)}(h**Constants** ``PDS_FWCTL_QUERY_CAP`` firmware can be queried for information ``PDS_FWCTL_SEND_CAP`` firmware can be sent commandsh](h)}(h **Constants**h]j)}(hjRh]h Constants}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jhjPubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhjLubjh)}(hhh](jm)}(h@``PDS_FWCTL_QUERY_CAP`` firmware can be queried for information h](js)}(h``PDS_FWCTL_QUERY_CAP``h]j)}(hjqh]hPDS_FWCTL_QUERY_CAP}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jhjoubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhKhjkubj)}(hhh]h)}(h'firmware can be queried for informationh]h'firmware can be queried for information}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubah}(h]h ]h"]h$]h&]uh1jhjkubeh}(h]h ]h"]h$]h&]uh1jlhjhKhjhubjm)}(h4``PDS_FWCTL_SEND_CAP`` firmware can be sent commandsh](js)}(h``PDS_FWCTL_SEND_CAP``h]j)}(hjh]hPDS_FWCTL_SEND_CAP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK hjubj)}(hhh]h)}(hfirmware can be sent commandsh]hfirmware can be sent commands}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK!hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK hjhubeh}(h]h ]h"]h$]h&]uh1jghjLubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhNhNubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_rpc_pds (C struct)c.fwctl_rpc_pdshNtauh1jhjhhhNhNubj)}(hhh](j)}(h fwctl_rpc_pdsh]j)}(hstruct fwctl_rpc_pdsh](j)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjhhhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK'ubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjhhhjhK'ubj)}(h fwctl_rpc_pdsh]j)}(hjh]h fwctl_rpc_pds}(hj$hhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhj ubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjhhhjhK'ubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjhhhjhK'ubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhjhK'hjhhubjC)}(hhh]h}(h]h ]h"]h$]h&]uh1jBhjhhhjhK'ubeh}(h]h ](j_structeh"]h$]h&]jdj_jejOjfjOjgjhjiuh1jhhhjhNhNubjk)}(hX**Definition**:: struct fwctl_rpc_pds { struct { __u32 op; __u32 ep; __u32 rsvd; __u32 len; __aligned_u64 payload; } in; struct { __u32 retval; __u32 rsvd[2]; __u32 len; __aligned_u64 payload; } out; }; **Members** ``in`` rpc in parameters ``in.op`` requested operation code ``in.ep`` firmware endpoint to operate on ``in.rsvd`` reserved ``in.len`` length of payload data ``in.payload`` address of payload buffer ``out`` rpc out parameters ``out.retval`` operation result value ``out.rsvd`` reserved ``out.len`` length of result data buffer ``out.payload`` address of payload data bufferh](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjWubh:}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK%hjSubj)}(hXstruct fwctl_rpc_pds { struct { __u32 op; __u32 ep; __u32 rsvd; __u32 len; __aligned_u64 payload; } in; struct { __u32 retval; __u32 rsvd[2]; __u32 len; __aligned_u64 payload; } out; };h]hXstruct fwctl_rpc_pds { struct { __u32 op; __u32 ep; __u32 rsvd; __u32 len; __aligned_u64 payload; } in; struct { __u32 retval; __u32 rsvd[2]; __u32 len; __aligned_u64 payload; } out; };}hjtsbah}(h]h ]h"]h$]h&]hhuh1jhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK'hjSubh)}(h **Members**h]j)}(hjh]hMembers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK7hjSubjh)}(hhh](jm)}(h``in`` rpc in parameters h](js)}(h``in``h]j)}(hjh]hin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK)hjubj)}(hhh]h)}(hrpc in parametersh]hrpc in parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK)hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK)hjubjm)}(h#``in.op`` requested operation code h](js)}(h ``in.op``h]j)}(hjh]hin.op}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK$hjubj)}(hhh]h)}(hrequested operation codeh]hrequested operation code}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK$hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK$hjubjm)}(h*``in.ep`` firmware endpoint to operate on h](js)}(h ``in.ep``h]j)}(hjh]hin.ep}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK%hjubj)}(hhh]h)}(hfirmware endpoint to operate onh]hfirmware endpoint to operate on}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+hK%hj,ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhj+hK%hjubjm)}(h``in.rsvd`` reserved h](js)}(h ``in.rsvd``h]j)}(hjOh]hin.rsvd}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK&hjIubj)}(hhh]h)}(hreservedh]hreserved}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjdhK&hjeubah}(h]h ]h"]h$]h&]uh1jhjIubeh}(h]h ]h"]h$]h&]uh1jlhjdhK&hjubjm)}(h"``in.len`` length of payload data h](js)}(h ``in.len``h]j)}(hjh]hin.len}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK'hjubj)}(hhh]h)}(hlength of payload datah]hlength of payload data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK'hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK'hjubjm)}(h)``in.payload`` address of payload buffer h](js)}(h``in.payload``h]j)}(hjh]h in.payload}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK(hjubj)}(hhh]h)}(haddress of payload bufferh]haddress of payload buffer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK(hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK(hjubjm)}(h``out`` rpc out parameters h](js)}(h``out``h]j)}(hjh]hout}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK.hjubj)}(hhh]h)}(hrpc out parametersh]hrpc out parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK.hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK.hjubjm)}(h&``out.retval`` operation result value h](js)}(h``out.retval``h]j)}(hj3h]h out.retval}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj1ubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK*hj-ubj)}(hhh]h)}(hoperation result valueh]hoperation result value}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHhK*hjIubah}(h]h ]h"]h$]h&]uh1jhj-ubeh}(h]h ]h"]h$]h&]uh1jlhjHhK*hjubjm)}(h``out.rsvd`` reserved h](js)}(h ``out.rsvd``h]j)}(hjlh]hout.rsvd}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK+hjfubj)}(hhh]h)}(hreservedh]hreserved}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK+hjubah}(h]h ]h"]h$]h&]uh1jhjfubeh}(h]h ]h"]h$]h&]uh1jlhjhK+hjubjm)}(h)``out.len`` length of result data buffer h](js)}(h ``out.len``h]j)}(hjh]hout.len}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK,hjubj)}(hhh]h)}(hlength of result data bufferh]hlength of result data buffer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK,hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK,hjubjm)}(h.``out.payload`` address of payload data bufferh](js)}(h``out.payload``h]j)}(hjh]h out.payload}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK,hjubj)}(hhh]h)}(haddress of payload data bufferh]haddress of payload data buffer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhc/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:153: ./include/uapi/fwctl/pds.hhK-hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK,hjubeh}(h]h ]h"]h$]h&]uh1jghjSubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhjhhhNhNubh)}(hhh](h)}(h sysfs Classh]h sysfs Class}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hfwctl has a sysfs class (/sys/class/fwctl/fwctlNN/) and character devices (/dev/fwctl/fwctlNN) with a simple numbered scheme. The character device operates the iotcl uAPI described above.h]hfwctl has a sysfs class (/sys/class/fwctl/fwctlNN/) and character devices (/dev/fwctl/fwctlNN) with a simple numbered scheme. The character device operates the iotcl uAPI described above.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hUfwctl devices can be related to driver components in other subsystems through sysfs::h]hTfwctl devices can be related to driver components in other subsystems through sysfs:}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h$ ls /sys/class/fwctl/fwctl0/device/infiniband/ ibp0s10f0 $ ls /sys/class/infiniband/ibp0s10f0/device/fwctl/ fwctl0/ $ ls /sys/devices/pci0000:00/0000:00:0a.0/fwctl/fwctl0 dev device power subsystem ueventh]h$ ls /sys/class/fwctl/fwctl0/device/infiniband/ ibp0s10f0 $ ls /sys/class/infiniband/ibp0s10f0/device/fwctl/ fwctl0/ $ ls /sys/devices/pci0000:00/0000:00:0a.0/fwctl/fwctl0 dev device power subsystem uevent}hjLsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubeh}(h] sysfs-classah ]h"] sysfs classah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hUser space Communityh]hUser space Community}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhjbhhhhhKubh)}(hDrawing inspiration from nvme-cli, participating in the kernel side must come with a user space in a common TBD git tree, at a minimum to usefully operate the kernel driver. Providing such an implementation is a pre-condition to merging a kernel driver.h]hDrawing inspiration from nvme-cli, participating in the kernel side must come with a user space in a common TBD git tree, at a minimum to usefully operate the kernel driver. Providing such an implementation is a pre-condition to merging a kernel driver.}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(hThe goal is to build user space community around some of the shared problems we all have, and ideally develop some common user space programs with some starting themes of:h]hThe goal is to build user space community around some of the shared problems we all have, and ideally develop some common user space programs with some starting themes of:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubj)}(h- Device in-field debugging - HW provisioning - VFIO child device profiling before VM boot - Confidential Compute topics (attestation, secure provisioning) h]j)}(hhh](j)}(hDevice in-field debugging h]h)}(hDevice in-field debuggingh]hDevice in-field debugging}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hHW provisioning h]h)}(hHW provisioningh]hHW provisioning}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h+VFIO child device profiling before VM boot h]h)}(h*VFIO child device profiling before VM booth]h*VFIO child device profiling before VM boot}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h?Confidential Compute topics (attestation, secure provisioning) h]h)}(h>Confidential Compute topics (attestation, secure provisioning)h]h>Confidential Compute topics (attestation, secure provisioning)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjbhhubh)}(hthat stretch across all subsystems in the kernel. fwupd is a great example of how an excellent user space experience can emerge out of kernel-side diversity.h]hthat stretch across all subsystems in the kernel. fwupd is a great example of how an excellent user space experience can emerge out of kernel-side diversity.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubeh}(h]user-space-communityah ]h"]user space communityah$]h&]uh1hhjhhhhhKubeh}(h]fwctl-user-apiah ]h"]fwctl user apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hfwctl Kernel APIh]hfwctl Kernel API}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_register (C function)c.fwctl_registerhNtauh1jhj hhhNhNubj)}(hhh](j)}(h/int fwctl_register (struct fwctl_device *fwctl)h]j)}(h.int fwctl_register(struct fwctl_device *fwctl)h](hdesc_sig_keyword_type)}(hinth]hint}(hjLhhhNhNubah}(h]h ]ktah"]h$]h&]uh1jJhjFhhh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chM^ubj)}(h h]h }(hj\hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjFhhhj[hM^ubj)}(hfwctl_registerh]j)}(hfwctl_registerh]hfwctl_register}(hjnhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjFhhhj[hM^ubhdesc_parameterlist)}(h(struct fwctl_device *fwctl)h]hdesc_parameter)}(hstruct fwctl_device *fwctlh](j)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjubh)}(hhh]j)}(h fwctl_deviceh]h fwctl_device}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&] refdomainj_reftype identifier reftargetjmodnameN classnameN c:parent_keysphinx.domains.c LookupKey)}data]j ASTIdentifier)}jjpsbc.fwctl_registerasbuh1hhjubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjubhdesc_sig_punctuation)}(h*h]h*}(hjhhhNhNubah}(h]h ]pah"]h$]h&]uh1jhjubj)}(hfwctlh]hfwctl}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjFhhhj[hM^ubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjBhhhj[hM^ubah}(h]j=ah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhj[hM^hj?hhubjC)}(hhh]h)}(h&Register a new device to the subsystemh]h&Register a new device to the subsystem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMXhjhhubah}(h]h ]h"]h$]h&]uh1jBhj?hhhj[hM^ubeh}(h]h ](j_functioneh"]h$]h&]jdj_jej5jfj5jgjhjiuh1jhhhj hNhNubjk)}(h**Parameters** ``struct fwctl_device *fwctl`` Previously allocated fwctl_device **Description** On return the device is visible through sysfs and /dev, driver ops may be called.h](h)}(h**Parameters**h]j)}(hj?h]h Parameters}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj=ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chM\hj9ubjh)}(hhh]jm)}(hA``struct fwctl_device *fwctl`` Previously allocated fwctl_device h](js)}(h``struct fwctl_device *fwctl``h]j)}(hj^h]hstruct fwctl_device *fwctl}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj\ubah}(h]h ]h"]h$]h&]uh1jrh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMYhjXubj)}(hhh]h)}(h!Previously allocated fwctl_deviceh]h!Previously allocated fwctl_device}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjshMYhjtubah}(h]h ]h"]h$]h&]uh1jhjXubeh}(h]h ]h"]h$]h&]uh1jlhjshMYhjUubah}(h]h ]h"]h$]h&]uh1jghj9ubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chM[hj9ubh)}(hQOn return the device is visible through sysfs and /dev, driver ops may be called.h]hQOn return the device is visible through sysfs and /dev, driver ops may be called.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chM[hj9ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj hhhNhNubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_unregister (C function)c.fwctl_unregisterhNtauh1jhj hhhNhNubj)}(hhh](j)}(h2void fwctl_unregister (struct fwctl_device *fwctl)h]j)}(h1void fwctl_unregister(struct fwctl_device *fwctl)h](jK)}(hvoidh]hvoid}(hjhhhNhNubah}(h]h ]jWah"]h$]h&]uh1jJhjhhh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMtubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjhhhjhMtubj)}(hfwctl_unregisterh]j)}(hfwctl_unregisterh]hfwctl_unregister}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjhhhjhMtubj)}(h(struct fwctl_device *fwctl)h]j)}(hstruct fwctl_device *fwctlh](j)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(h h]h }(hj(hhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjubh)}(hhh]j)}(h fwctl_deviceh]h fwctl_device}(hj9hhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhj6ubah}(h]h ]h"]h$]h&] refdomainj_reftypej reftargetj;modnameN classnameNjj)}j]j)}jjsbc.fwctl_unregisterasbuh1hhjubj)}(h h]h }(hjYhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjubj)}(hjh]h*}(hjghhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjubj)}(hfwctlh]hfwctl}(hjthhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]noemphhhuh1jhjubah}(h]h ]h"]h$]h&]hhuh1jhjhhhjhMtubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjhhhjhMtubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhjhMthjhhubjC)}(hhh]h)}(h&Unregister a device from the subsystemh]h&Unregister a device from the subsystem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMehjhhubah}(h]h ]h"]h$]h&]uh1jBhjhhhjhMtubeh}(h]h ](j_functioneh"]h$]h&]jdj_jejjfjjgjhjiuh1jhhhj hNhNubjk)}(hX**Parameters** ``struct fwctl_device *fwctl`` Previously allocated and registered fwctl_device **Description** Undoes fwctl_register(). On return no driver ops will be called. The caller must still call fwctl_put() to free the fwctl. Unregister will return even if userspace still has file descriptors open. This will call ops->close_uctx() on any open FDs and after return no driver op will be called. The FDs remain open but all fops will return -ENODEV. The design of fwctl allows this sort of disassociation of the driver from the subsystem primarily by keeping memory allocations owned by the core subsytem. The fwctl_device and fwctl_uctx can both be freed without requiring a driver callback. This allows the module to remain unlocked while FDs are open.h](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMihjubjh)}(hhh]jm)}(hP``struct fwctl_device *fwctl`` Previously allocated and registered fwctl_device h](js)}(h``struct fwctl_device *fwctl``h]j)}(hjh]hstruct fwctl_device *fwctl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMfhjubj)}(hhh]h)}(h0Previously allocated and registered fwctl_deviceh]h0Previously allocated and registered fwctl_device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMfhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhMfhjubah}(h]h ]h"]h$]h&]uh1jghjubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMhhjubh)}(hzUndoes fwctl_register(). On return no driver ops will be called. The caller must still call fwctl_put() to free the fwctl.h]hzUndoes fwctl_register(). On return no driver ops will be called. The caller must still call fwctl_put() to free the fwctl.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMhhjubh)}(hUnregister will return even if userspace still has file descriptors open. This will call ops->close_uctx() on any open FDs and after return no driver op will be called. The FDs remain open but all fops will return -ENODEV.h]hUnregister will return even if userspace still has file descriptors open. This will call ops->close_uctx() on any open FDs and after return no driver op will be called. The FDs remain open but all fops will return -ENODEV.}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMkhjubh)}(hX0The design of fwctl allows this sort of disassociation of the driver from the subsystem primarily by keeping memory allocations owned by the core subsytem. The fwctl_device and fwctl_uctx can both be freed without requiring a driver callback. This allows the module to remain unlocked while FDs are open.h]hX0The design of fwctl allows this sort of disassociation of the driver from the subsystem primarily by keeping memory allocations owned by the core subsytem. The fwctl_device and fwctl_uctx can both be freed without requiring a driver callback. This allows the module to remain unlocked while FDs are open.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:200: ./drivers/fwctl/main.chMohjubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj hhhNhNubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_ops (C struct) c.fwctl_opshNtauh1jhj hhh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhNubj)}(hhh](j)}(h fwctl_opsh]j)}(hstruct fwctl_opsh](j)}(hjh]hstruct}(hj~hhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjzhhh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjzhhhjhKubj)}(h fwctl_opsh]j)}(hjxh]h fwctl_ops}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjzhhhjhKubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjvhhhjhKubah}(h]jpah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhjhKhjshhubjC)}(hhh]h)}(hDriver provided operationsh]hDriver provided operations}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhjhhubah}(h]h ]h"]h$]h&]uh1jBhjshhhjhKubeh}(h]h ](j_structeh"]h$]h&]jdj_jejjfjjgjhjiuh1jhhhj hjrhNubjk)}(hX6**Definition**:: struct fwctl_ops { enum fwctl_device_type device_type; size_t uctx_size; int (*open_uctx)(struct fwctl_uctx *uctx); void (*close_uctx)(struct fwctl_uctx *uctx); void *(*info)(struct fwctl_uctx *uctx, size_t *length); void *(*fw_rpc)(struct fwctl_uctx *uctx, enum fwctl_rpc_scope scope, void *rpc_in, size_t in_len, size_t *out_len); }; **Members** ``device_type`` The drivers assigned device_type number. This is uABI. ``uctx_size`` The size of the fwctl_uctx struct to allocate. The first bytes of this memory will be a fwctl_uctx. The driver can use the remaining bytes as its private memory. ``open_uctx`` Called when a file descriptor is opened before the uctx is ever used. ``close_uctx`` Called when the uctx is destroyed, usually when the FD is closed. ``info`` Implement FWCTL_INFO. Return a kmalloc() memory that is copied to out_device_data. On input length indicates the size of the user buffer on output it indicates the size of the memory. The driver can ignore length on input, the core code will handle everything. ``fw_rpc`` Implement FWCTL_RPC. Deliver rpc_in/in_len to the FW and return the response and set out_len. rpc_in can be returned as the response pointer. Otherwise the returned pointer is freed with kvfree().h](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhjubj)}(hXgstruct fwctl_ops { enum fwctl_device_type device_type; size_t uctx_size; int (*open_uctx)(struct fwctl_uctx *uctx); void (*close_uctx)(struct fwctl_uctx *uctx); void *(*info)(struct fwctl_uctx *uctx, size_t *length); void *(*fw_rpc)(struct fwctl_uctx *uctx, enum fwctl_rpc_scope scope, void *rpc_in, size_t in_len, size_t *out_len); };h]hXgstruct fwctl_ops { enum fwctl_device_type device_type; size_t uctx_size; int (*open_uctx)(struct fwctl_uctx *uctx); void (*close_uctx)(struct fwctl_uctx *uctx); void *(*info)(struct fwctl_uctx *uctx, size_t *length); void *(*fw_rpc)(struct fwctl_uctx *uctx, enum fwctl_rpc_scope scope, void *rpc_in, size_t in_len, size_t *out_len); };}hjsbah}(h]h ]h"]h$]h&]hhuh1jh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhjubh)}(h **Members**h]j)}(hjh]hMembers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhjubjh)}(hhh](jm)}(hG``device_type`` The drivers assigned device_type number. This is uABI. h](js)}(h``device_type``h]j)}(hj-h]h device_type}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj+ubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj'ubj)}(hhh]h)}(h6The drivers assigned device_type number. This is uABI.h]h6The drivers assigned device_type number. This is uABI.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBhKhjCubah}(h]h ]h"]h$]h&]uh1jhj'ubeh}(h]h ]h"]h$]h&]uh1jlhjBhKhj$ubjm)}(h``uctx_size`` The size of the fwctl_uctx struct to allocate. The first bytes of this memory will be a fwctl_uctx. The driver can use the remaining bytes as its private memory. h](js)}(h ``uctx_size``h]j)}(hjfh]h uctx_size}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjdubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj`ubj)}(hhh]h)}(hThe size of the fwctl_uctx struct to allocate. The first bytes of this memory will be a fwctl_uctx. The driver can use the remaining bytes as its private memory.h]hThe size of the fwctl_uctx struct to allocate. The first bytes of this memory will be a fwctl_uctx. The driver can use the remaining bytes as its private memory.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj|ubah}(h]h ]h"]h$]h&]uh1jhj`ubeh}(h]h ]h"]h$]h&]uh1jlhj{hKhj$ubjm)}(hT``open_uctx`` Called when a file descriptor is opened before the uctx is ever used. h](js)}(h ``open_uctx``h]j)}(hjh]h open_uctx}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK$hjubj)}(hhh]h)}(hECalled when a file descriptor is opened before the uctx is ever used.h]hECalled when a file descriptor is opened before the uctx is ever used.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK#hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK$hj$ubjm)}(hQ``close_uctx`` Called when the uctx is destroyed, usually when the FD is closed. h](js)}(h``close_uctx``h]j)}(hjh]h close_uctx}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK)hjubj)}(hhh]h)}(hACalled when the uctx is destroyed, usually when the FD is closed.h]hACalled when the uctx is destroyed, usually when the FD is closed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK(hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK)hj$ubjm)}(hX``info`` Implement FWCTL_INFO. Return a kmalloc() memory that is copied to out_device_data. On input length indicates the size of the user buffer on output it indicates the size of the memory. The driver can ignore length on input, the core code will handle everything. h](js)}(h``info``h]j)}(hjh]hinfo}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK0hjubj)}(hhh]h)}(hXImplement FWCTL_INFO. Return a kmalloc() memory that is copied to out_device_data. On input length indicates the size of the user buffer on output it indicates the size of the memory. The driver can ignore length on input, the core code will handle everything.h]hXImplement FWCTL_INFO. Return a kmalloc() memory that is copied to out_device_data. On input length indicates the size of the user buffer on output it indicates the size of the memory. The driver can ignore length on input, the core code will handle everything.}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK-hj*ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhj)hK0hj$ubjm)}(h``fw_rpc`` Implement FWCTL_RPC. Deliver rpc_in/in_len to the FW and return the response and set out_len. rpc_in can be returned as the response pointer. Otherwise the returned pointer is freed with kvfree().h](js)}(h ``fw_rpc``h]j)}(hjNh]hfw_rpc}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjLubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK6hjHubj)}(hhh]h)}(hImplement FWCTL_RPC. Deliver rpc_in/in_len to the FW and return the response and set out_len. rpc_in can be returned as the response pointer. Otherwise the returned pointer is freed with kvfree().h]hImplement FWCTL_RPC. Deliver rpc_in/in_len to the FW and return the response and set out_len. rpc_in can be returned as the response pointer. Otherwise the returned pointer is freed with kvfree().}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK4hjdubah}(h]h ]h"]h$]h&]uh1jhjHubeh}(h]h ]h"]h$]h&]uh1jlhjchK6hj$ubeh}(h]h ]h"]h$]h&]uh1jghjubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj hhhjrhNubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK:hj hhubh)}(hfwctl_unregister() will wait until all excuting ops are completed before it returns. Drivers should be mindful to not let their ops run for too long as it will block device hot unplug and module unloading.h]hfwctl_unregister() will wait until all excuting ops are completed before it returns. Drivers should be mindful to not let their ops run for too long as it will block device hot unplug and module unloading.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj hhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_device (C struct)c.fwctl_devicehNtauh1jhj hhhjrhNubj)}(hhh](j)}(h fwctl_deviceh]j)}(hstruct fwctl_deviceh](j)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjhhh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjhhhjhKubj)}(h fwctl_deviceh]j)}(hjh]h fwctl_device}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjhhhjhKubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjhhhjhKubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhjhKhjhhubjC)}(hhh]h)}(hPer-driver registration structh]hPer-driver registration struct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK=hjhhubah}(h]h ]h"]h$]h&]uh1jBhjhhhjhKubeh}(h]h ](j_structeh"]h$]h&]jdj_jej)jfj)jgjhjiuh1jhhhj hjrhNubjk)}(h**Definition**:: struct fwctl_device { struct device dev; }; **Members** ``dev`` The sysfs (class/fwctl/fwctlXX) deviceh](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj1ubh:}(hj1hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKAhj-ubj)}(h/struct fwctl_device { struct device dev; };h]h/struct fwctl_device { struct device dev; };}hjNsbah}(h]h ]h"]h$]h&]hhuh1jh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKChj-ubh)}(h **Members**h]j)}(hj_h]hMembers}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jhj]ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKGhj-ubjh)}(hhh]jm)}(h.``dev`` The sysfs (class/fwctl/fwctlXX) deviceh](js)}(h``dev``h]j)}(hj~h]hdev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj|ubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK>hjxubj)}(hhh]h)}(h&The sysfs (class/fwctl/fwctlXX) deviceh]h&The sysfs (class/fwctl/fwctlXX) device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK?hjubah}(h]h ]h"]h$]h&]uh1jhjxubeh}(h]h ]h"]h$]h&]uh1jlhjhK>hjuubah}(h]h ]h"]h$]h&]uh1jghj-ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj hhhjrhNubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKBhj hhubh)}(hEach driver instance will have one of these structs with the driver private data following immediately after. This struct is refcounted, it is freed by calling fwctl_put().h]hEach driver instance will have one of these structs with the driver private data following immediately after. This struct is refcounted, it is freed by calling fwctl_put().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK@hj hhubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_alloc_device (C macro)c.fwctl_alloc_devicehNtauh1jhj hhhjrhNubj)}(hhh](j)}(hfwctl_alloc_deviceh]j)}(hfwctl_alloc_deviceh]j)}(hfwctl_alloc_deviceh]j)}(hjh]hfwctl_alloc_device}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjhhh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKbubah}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjhhhjhKbubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhjhKbhjhhubjC)}(hhh]h}(h]h ]h"]h$]h&]uh1jBhjhhhjhKbubeh}(h]h ](j_macroeh"]h$]h&]jdj_jej/jfj/jgjhjiuh1jhhhj hjrhNubh)}(h8``fwctl_alloc_device (parent, ops, drv_struct, member)``h]j)}(hj5h]h4fwctl_alloc_device (parent, ops, drv_struct, member)}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKdhj hhubj)}(hAllocate a fwctl h]h)}(hAllocate a fwctlh]hAllocate a fwctl}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKXhjKubah}(h]h ]h"]h$]h&]uh1jhj]hKXhj hhubjk)}(hX**Parameters** ``parent`` Physical device that provides the FW interface ``ops`` Driver ops to register ``drv_struct`` 'struct driver_fwctl' that holds the struct fwctl_device ``member`` Name of the struct fwctl_device in **drv_struct** **Description** This allocates and initializes the fwctl_device embedded in the drv_struct. Upon success the pointer must be freed via fwctl_put(). Returns a 'drv_struct \*' on success, NULL on error.h](h)}(h**Parameters**h]j)}(hjjh]h Parameters}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK\hjdubjh)}(hhh](jm)}(h:``parent`` Physical device that provides the FW interface h](js)}(h ``parent``h]j)}(hjh]hparent}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKYhjubj)}(hhh]h)}(h.Physical device that provides the FW interfaceh]h.Physical device that provides the FW interface}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKYhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhKYhjubjm)}(h``ops`` Driver ops to register h](js)}(h``ops``h]j)}(hjh]hops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKZhjubj)}(hhh]h)}(hDriver ops to registerh]hDriver ops to register}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKZhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhKZhjubjm)}(hH``drv_struct`` 'struct driver_fwctl' that holds the struct fwctl_device h](js)}(h``drv_struct``h]j)}(hjh]h drv_struct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK[hjubj)}(hhh]h)}(h8'struct driver_fwctl' that holds the struct fwctl_deviceh]h<‘struct driver_fwctl’ that holds the struct fwctl_device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK[hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jlhjhK[hjubjm)}(h=``member`` Name of the struct fwctl_device in **drv_struct** h](js)}(h ``member``h]j)}(hj4h]hmember}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj2ubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK\hj.ubj)}(hhh]h)}(h1Name of the struct fwctl_device in **drv_struct**h](h#Name of the struct fwctl_device in }(hjMhhhNhNubj)}(h**drv_struct**h]h drv_struct}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjMubeh}(h]h ]h"]h$]h&]uh1hhjIhK\hjJubah}(h]h ]h"]h$]h&]uh1jhj.ubeh}(h]h ]h"]h$]h&]uh1jlhjIhK\hjubeh}(h]h ]h"]h$]h&]uh1jghjdubh)}(h**Description**h]j)}(hj}h]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj{ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK^hjdubh)}(hThis allocates and initializes the fwctl_device embedded in the drv_struct. Upon success the pointer must be freed via fwctl_put(). Returns a 'drv_struct \*' on success, NULL on error.h]hThis allocates and initializes the fwctl_device embedded in the drv_struct. Upon success the pointer must be freed via fwctl_put(). Returns a ‘drv_struct *’ on success, NULL on error.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK^hjdubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj hhhjrhNubj)}(hhh]h}(h]h ]h"]h$]h&]entries](jfwctl_uctx (C struct) c.fwctl_uctxhNtauh1jhj hhhjrhNubj)}(hhh](j)}(h fwctl_uctxh]j)}(hstruct fwctl_uctxh](j)}(hjh]hstruct}(hjhhhNhNubah}(h]h ]jah"]h$]h&]uh1jhjhhh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKeubj)}(h h]h }(hjhhhNhNubah}(h]h ]j ah"]h$]h&]uh1jhjhhhjhKeubj)}(h fwctl_uctxh]j)}(hjh]h fwctl_uctx}(hjhhhNhNubah}(h]h ]j"ah"]h$]h&]uh1jhjubah}(h]h ](j)j*eh"]h$]h&]hhuh1jhjhhhjhKeubeh}(h]h ]h"]h$]h&]hhj4uh1jj5j6hjhhhjhKeubah}(h]jah ](j:j;eh"]h$]h&]j?j@)jAhuh1jhjhKehjhhubjC)}(hhh]h)}(hPer user FD contexth]hPer user FD context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKzhjhhubah}(h]h ]h"]h$]h&]uh1jBhjhhhjhKeubeh}(h]h ](j_structeh"]h$]h&]jdj_jejjfjjgjhjiuh1jhhhj hjrhNubjk)}(h**Definition**:: struct fwctl_uctx { struct fwctl_device *fwctl; }; **Members** ``fwctl`` fwctl instance that owns the contexth](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj$ubh:}(hj$hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK~hj ubj)}(h6struct fwctl_uctx { struct fwctl_device *fwctl; };h]h6struct fwctl_uctx { struct fwctl_device *fwctl; };}hjAsbah}(h]h ]h"]h$]h&]hhuh1jh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj ubh)}(h **Members**h]j)}(hjRh]hMembers}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jhjPubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj ubjh)}(hhh]jm)}(h.``fwctl`` fwctl instance that owns the contexth](js)}(h ``fwctl``h]j)}(hjqh]hfwctl}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jhjoubah}(h]h ]h"]h$]h&]uh1jrh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK{hjkubj)}(hhh]h)}(h$fwctl instance that owns the contexth]h$fwctl instance that owns the context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK|hjubah}(h]h ]h"]h$]h&]uh1jhjkubeh}(h]h ]h"]h$]h&]uh1jlhjhK{hjhubah}(h]h ]h"]h$]h&]uh1jghj ubeh}(h]h ] kernelindentah"]h$]h&]uh1jjhj hhhjrhNubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhKhj hhubh)}(hyEvery FD opened by userspace will get a unique context allocation. Any driver private data will follow immediately after.h]hyEvery FD opened by userspace will get a unique context allocation. Any driver private data will follow immediately after.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/userspace-api/fwctl/fwctl:202: ./include/linux/fwctl.hhK}hj hhubh)}(hhh](h)}(hfwctl Driver designh]hfwctl Driver design}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXkIn many cases a fwctl driver is going to be part of a larger cross-subsystem device possibly using the auxiliary_device mechanism. In that case several subsystems are going to be sharing the same device and FW interface layer so the device design must already provide for isolation and cooperation between kernel subsystems. fwctl should fit into that same model.h]hXkIn many cases a fwctl driver is going to be part of a larger cross-subsystem device possibly using the auxiliary_device mechanism. In that case several subsystems are going to be sharing the same device and FW interface layer so the device design must already provide for isolation and cooperation between kernel subsystems. fwctl should fit into that same model.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXPart of the driver should include a description of how its scope restrictions and security model work. The driver and FW together must ensure that RPCs provided by user space are mapped to the appropriate scope. If the validation is done in the driver then the validation can read a 'command effects' report from the device, or hardwire the enforcement. If the validation is done in the FW, then the driver should pass the fwctl_rpc_scope to the FW along with the command.h]hXPart of the driver should include a description of how its scope restrictions and security model work. The driver and FW together must ensure that RPCs provided by user space are mapped to the appropriate scope. If the validation is done in the driver then the validation can read a ‘command effects’ report from the device, or hardwire the enforcement. If the validation is done in the FW, then the driver should pass the fwctl_rpc_scope to the FW along with the command.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXEThe driver and FW must cooperate to ensure that either fwctl cannot allocate any FW resources, or any resources it does allocate are freed on FD closure. A driver primarily constructed around FW RPCs may find that its core PCI function and RPC layer belongs under fwctl with auxiliary devices connecting to other subsystems.h]hXEThe driver and FW must cooperate to ensure that either fwctl cannot allocate any FW resources, or any resources it does allocate are freed on FD closure. A driver primarily constructed around FW RPCs may find that its core PCI function and RPC layer belongs under fwctl with auxiliary devices connecting to other subsystems.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXQEach device type must be mindful of Linux's philosophy for stable ABI. The FW RPC interface does not have to meet a strictly stable ABI, but it does need to meet an expectation that userspace tools that are deployed and in significant use don't needlessly break. FW upgrade and kernel upgrade should keep widely deployed tooling working.h]hXUEach device type must be mindful of Linux’s philosophy for stable ABI. The FW RPC interface does not have to meet a strictly stable ABI, but it does need to meet an expectation that userspace tools that are deployed and in significant use don’t needlessly break. FW upgrade and kernel upgrade should keep widely deployed tooling working.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXWDevelopment and debugging focused RPCs under more permissive scopes can have less stabilitiy if the tools using them are only run under exceptional circumstances and not for every day use of the device. Debugging tools may even require exact version matching as they may require something similar to DWARF debug information from the FW binary.h]hXWDevelopment and debugging focused RPCs under more permissive scopes can have less stabilitiy if the tools using them are only run under exceptional circumstances and not for every day use of the device. Debugging tools may even require exact version matching as they may require something similar to DWARF debug information from the FW binary.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]fwctl-driver-designah ]h"]fwctl driver designah$]h&]uh1hhj hhhhhKubeh}(h]fwctl-kernel-apiah ]h"]fwctl kernel apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hSecurity Responseh]hSecurity Response}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@hhhhhKubh)}(hX.The kernel remains the gatekeeper for this interface. If violations of the scopes, security or isolation principles are found, we have options to let devices fix them with a FW update, push a kernel patch to parse and block RPC commands or push a kernel patch to block entire firmware versions/devices.h]hX.The kernel remains the gatekeeper for this interface. If violations of the scopes, security or isolation principles are found, we have options to let devices fix them with a FW update, push a kernel patch to parse and block RPC commands or push a kernel patch to block entire firmware versions/devices.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj@hhubh)}(hWhile the kernel can always directly parse and restrict RPCs, it is expected that the existing kernel pattern of allowing drivers to delegate validation to FW to be a useful design.h]hWhile the kernel can always directly parse and restrict RPCs, it is expected that the existing kernel pattern of allowing drivers to delegate validation to FW to be a useful design.}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj@hhubeh}(h]security-responseah ]h"]security responseah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hExisting Similar Examplesh]hExisting Similar Examples}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhKubh)}(hXkThe approach described in this document is not a new idea. Direct, or near direct device access has been offered by the kernel in different areas for decades. With more devices wanting to follow this design pattern it is becoming clear that it is not entirely well understood and, more importantly, the security considerations are not well defined or agreed upon.h]hXkThe approach described in this document is not a new idea. Direct, or near direct device access has been offered by the kernel in different areas for decades. With more devices wanting to follow this design pattern it is becoming clear that it is not entirely well understood and, more importantly, the security considerations are not well defined or agreed upon.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjuhhubh)}(hSome examples:h]hSome examples:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjuhhubj)}(hX- HW RAID controllers. This includes RPCs to do things like compose drives into a RAID volume, configure RAID parameters, monitor the HW and more. - Baseboard managers. RPCs for configuring settings in the device and more - NVMe vendor command capsules. nvme-cli provides access to some monitoring functions that different products have defined, but more exist. - CXL also has a NVMe-like vendor command system. - DRM allows user space drivers to send commands to the device via kernel mediation - RDMA allows user space drivers to directly push commands to the device without kernel involvement - Various “raw” APIs, raw HID (SDL2), raw USB, NVMe Generic Interface, etc. h]j)}(hhh](j)}(hHW RAID controllers. This includes RPCs to do things like compose drives into a RAID volume, configure RAID parameters, monitor the HW and more. h]h)}(hHW RAID controllers. This includes RPCs to do things like compose drives into a RAID volume, configure RAID parameters, monitor the HW and more.h]hHW RAID controllers. This includes RPCs to do things like compose drives into a RAID volume, configure RAID parameters, monitor the HW and more.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hIBaseboard managers. RPCs for configuring settings in the device and more h]h)}(hHBaseboard managers. RPCs for configuring settings in the device and moreh]hHBaseboard managers. RPCs for configuring settings in the device and more}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hNVMe vendor command capsules. nvme-cli provides access to some monitoring functions that different products have defined, but more exist. h]h)}(hNVMe vendor command capsules. nvme-cli provides access to some monitoring functions that different products have defined, but more exist.h]hNVMe vendor command capsules. nvme-cli provides access to some monitoring functions that different products have defined, but more exist.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h0CXL also has a NVMe-like vendor command system. h]h)}(h/CXL also has a NVMe-like vendor command system.h]h/CXL also has a NVMe-like vendor command system.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hRDRM allows user space drivers to send commands to the device via kernel mediation h]h)}(hQDRM allows user space drivers to send commands to the device via kernel mediationh]hQDRM allows user space drivers to send commands to the device via kernel mediation}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhjubjt)}(hbRDMA allows user space drivers to directly push commands to the device without kernel involvement h]h)}(haRDMA allows user space drivers to directly push commands to the device without kernel involvementh]haRDMA allows user space drivers to directly push commands to the device without kernel involvement}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj!ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hNVarious “raw” APIs, raw HID (SDL2), raw USB, NVMe Generic Interface, etc. h]h)}(hMVarious “raw” APIs, raw HID (SDL2), raw USB, NVMe Generic Interface, etc.h]hMVarious “raw” APIs, raw HID (SDL2), raw USB, NVMe Generic Interface, etc.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj9ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhhMhjuhhubh)}(hThe first 4 are examples of areas that fwctl intends to cover. The latter three are examples of denied behavior as they fully overlap with the primary purpose of a kernel subsystem.h]hThe first 4 are examples of areas that fwctl intends to cover. The latter three are examples of denied behavior as they fully overlap with the primary purpose of a kernel subsystem.}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjuhhubh)}(hX-Some key lessons learned from these past efforts are the importance of having a common user space project to use as a pre-condition for obtaining a kernel driver. Developing good community around useful software in user space is key to getting companies to fund participation to enable their products.h]hX-Some key lessons learned from these past efforts are the importance of having a common user space project to use as a pre-condition for obtaining a kernel driver. Developing good community around useful software in user space is key to getting companies to fund participation to enable their products.}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjuhhubeh}(h]existing-similar-examplesah ]h"]existing similar examplesah$]h&]uh1hhhhhhhhKubeh}(h]fwctl-subsystemah ]h"]fwctl subsystemah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}j]jasnameids}(jjjj|jjjwjtjjjjj_j\jjj=j:j5j2jrjoj~j{u nametypes}(jjjjwjjj_jj=j5jrj~uh}(jhj|j jjjtjjjjjjjjjj j jd jj j j j j jjj\jjjbj:j j=jBjjjpjvjjjjjjj2jjoj@j{juu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h:Hyperlink target "general-ioctl-format" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcejlineKuh1juba transformerN include_log] decorationNhhub.