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