xref: /linux/Documentation/userspace-api/fwctl/pds_fwctl.rst (revision 4f9786035f9e519db41375818e1d0b5f20da2f10)
1*40325707SShannon Nelson.. SPDX-License-Identifier: GPL-2.0
2*40325707SShannon Nelson
3*40325707SShannon Nelson================
4*40325707SShannon Nelsonfwctl pds driver
5*40325707SShannon Nelson================
6*40325707SShannon Nelson
7*40325707SShannon Nelson:Author: Shannon Nelson
8*40325707SShannon Nelson
9*40325707SShannon NelsonOverview
10*40325707SShannon Nelson========
11*40325707SShannon Nelson
12*40325707SShannon NelsonThe PDS Core device makes a fwctl service available through an
13*40325707SShannon Nelsonauxiliary_device named pds_core.fwctl.N.  The pds_fwctl driver binds to
14*40325707SShannon Nelsonthis device and registers itself with the fwctl subsystem.  The resulting
15*40325707SShannon Nelsonuserspace interface is used by an application that is a part of the
16*40325707SShannon NelsonAMD Pensando software package for the Distributed Service Card (DSC).
17*40325707SShannon Nelson
18*40325707SShannon NelsonThe pds_fwctl driver has little knowledge of the firmware's internals.
19*40325707SShannon NelsonIt only knows how to send commands through pds_core's message queue to the
20*40325707SShannon Nelsonfirmware for fwctl requests.  The set of fwctl operations available
21*40325707SShannon Nelsondepends on the firmware in the DSC, and the userspace application
22*40325707SShannon Nelsonversion must match the firmware so that they can talk to each other.
23*40325707SShannon Nelson
24*40325707SShannon NelsonWhen a connection is created the pds_fwctl driver requests from the
25*40325707SShannon Nelsonfirmware a list of firmware object endpoints, and for each endpoint the
26*40325707SShannon Nelsondriver requests a list of operations for that endpoint.
27*40325707SShannon Nelson
28*40325707SShannon NelsonEach operation description includes a firmware defined command attribute
29*40325707SShannon Nelsonthat maps to the FWCTL scope levels.  The driver translates those firmware
30*40325707SShannon Nelsonvalues into the FWCTL scope values which can then be used for filtering the
31*40325707SShannon Nelsonscoped user requests.
32*40325707SShannon Nelson
33*40325707SShannon Nelsonpds_fwctl User API
34*40325707SShannon Nelson==================
35*40325707SShannon Nelson
36*40325707SShannon NelsonEach RPC request includes the target endpoint and the operation id, and in
37*40325707SShannon Nelsonand out buffer lengths and pointers.  The driver verifies the existence
38*40325707SShannon Nelsonof the requested endpoint and operations, then checks the request scope
39*40325707SShannon Nelsonagainst the required scope of the operation.  The request is then put
40*40325707SShannon Nelsontogether with the request data and sent through pds_core's message queue
41*40325707SShannon Nelsonto the firmware, and the results are returned to the caller.
42*40325707SShannon Nelson
43*40325707SShannon NelsonThe RPC endpoints, operations, and buffer contents are defined by the
44*40325707SShannon Nelsonparticular firmware package in the device, which varies across the
45*40325707SShannon Nelsonavailable product configurations.  The details are available in the
46*40325707SShannon Nelsonspecific product SDK documentation.
47