520.61.05

src/nvidia/inc/kernel/rmapi/control.h

@@ -132,28 +132,141 @@ NV_STATUS embeddedParamCopyOut(RMAPI_PARAM_COPY  *pParamCopy, RmCtrlParams *pRmC
         !RMCFG_FEATURE_PHYSICAL_RM                        \
     )
 
-// per-rmcontrol flags values
+//
+// 'FLAGS' Attribute
+// -----------------
+//
+// RMCTRL_FLAGS is used to specify per-command state.
+//
+
 #define RMCTRL_FLAGS_NONE                                     0x000000000
-#define RMCTRL_FLAGS_NO_STATIC                                0x000000000 // internal to chip-config. TODO -- delete
-#define RMCTRL_FLAGS_ONLY_IF_CMD_DEFINED                      0x000000000 // internal to chip-config. TODO -- delete
+
+//
+// If the KERNEL_PRIVILEGED flag is specified, the call will only be allowed
+// for kernel mode callers (such as other kernel drivers) using a privileged
+// kernel RM client (CliCheckIsKernelClient() returning true). Otherwise,
+// NV_ERR_INSUFFICIENT_PERMISSIONS is returned.
+//
 #define RMCTRL_FLAGS_KERNEL_PRIVILEGED                        0x000000000
+
+//
+// The resman rmcontrol handler will not grab the "gpus lock"
+// before executing the implementing function.
+//
+// Please be sure you know what you're doing before using this!
+//
 #define RMCTRL_FLAGS_NO_GPUS_LOCK                             0x000000001
+
+//
+// Indicate to resman that this rmcontrol does not access any gpu
+// resources and can therefore run even when the gpu is powered down.
+//
+// Please be sure you know what you're doing before using this!
+//
 #define RMCTRL_FLAGS_NO_GPUS_ACCESS                           0x000000002
+
+//
+// If the PRIVILEGED flag is specified, the call will only be allowed for
+//  a) user contexts with admin privleges (osIsAdministrator() returning true), or
+//  b) kernel mode callers, such as other kernel drivers.
+// Otherwise, NV_ERR_INSUFFICIENT_PERMISSIONS is returned.
+//
 #define RMCTRL_FLAGS_PRIVILEGED                               0x000000004
-#define RMCTRL_FLAGS_HACK_USED_ON_MULTIPLE_CLASSES            0x000000008
+
+//
+// If the NON_PRIVILEGED flag is specified, the call will be allowed from any
+// client.
+//
 #define RMCTRL_FLAGS_NON_PRIVILEGED                           0x000000010
-#define RMCTRL_FLAGS_BIG_PAYLOAD                              0x000000020
+
+//
+// The resman rmcontrol handler will grab the per-device lock instead
+// of the "gpus lock" before executing the implementing function.
+//
+// Please be sure you know what you're doing before using this!
+//
 #define RMCTRL_FLAGS_GPU_LOCK_DEVICE_ONLY                     0x000000040
+
+//
+// This flag is equivalent to PRIVILEGED when the RM access rights
+// implementation is disabled. Otherwise, it has no effect.
+//
+// The purpose of this flag is to aid in the transition to the access rights
+// system, so that access rights can be used for control calls that were
+// previously PRIVILEGED. Once access rights are enabled, this flag will no
+// longer be necessary.
+//
 #define RMCTRL_FLAGS_PRIVILEGED_IF_RS_ACCESS_DISABLED         0x000000100 // for Resserv Access Rights migration
+
+//
+// This flag specifies that the control shall be directly forwarded to the
+// physical object if called on the CPU-RM kernel.
+//
 #define RMCTRL_FLAGS_ROUTE_TO_PHYSICAL                        0x000000200
+
+//
+// If the INTERNAL flag is specified, the call will only be allowed
+// to be issued from RM itself. Otherwise, NV_ERR_NOT_SUPPORTED is returned.
+//
 #define RMCTRL_FLAGS_INTERNAL                                 0x000000400
+
+//
+//  If the API_LOCK_READONLY flag is specified, the call will acquire the
+//  read-only API lock and may run concurrently with other operations that have
+//  also taken the read-only API lock. This flag is ignored if read-only API
+//  locking is disabled in RM.
+//
 #define RMCTRL_FLAGS_API_LOCK_READONLY                        0x000000800
+
+//
+//  If the :GPU_LOCK_READONLY flag is specified, the call will acquire a
+//  read-only GPU lock and may run concurrently with other operations that have
+//  also taken a read-only GPU lock. This flag is ignored if read-only GPU
+//  locking is disabled in RM.
+//
 #define RMCTRL_FLAGS_GPU_LOCK_READONLY                        0x000001000
+
+//
+// This flag specifies that the control shall be directly forwarded to the
+// the VGPU host if called from a guest (where IS_VIRTUAL() is true)
+//
 #define RMCTRL_FLAGS_ROUTE_TO_VGPU_HOST                       0x000002000
+
+//
+// This flag specifies that the control output does not depend on the input
+// parameters and can be cached on the receiving end.
+// The cache is transparent and may not exist on all platforms.
+//
 #define RMCTRL_FLAGS_CACHEABLE                                0x000004000
+
+//
+// This flag specifies that the control parameters will be
+// copied out back to the caller even if the control call fails.
+//
 #define RMCTRL_FLAGS_COPYOUT_ON_ERROR                         0x000008000
+
+// ??
 #define RMCTRL_FLAGS_ALLOW_WITHOUT_SYSMEM_ACCESS              0x000010000
 
+
+//
+//  'ACCESS_RIGHTS' Attribute
+//  ------------------------
+//
+//    Used to specify a set of access rights that the client must hold on the
+//    target resource to execute this control call. Note that this can only check
+//    access rights on the target object; for other objects, such as those
+//    specified by handles in parameter structs, checks must be done manually.
+//
+//    The definition of each access right and its meaning is provided in the
+//    README located at drivers/common/shared/accessrights/README. The prefix
+//    "RS_ACCESS" is appended to each entry in the control call definition;
+//    for example, :NICE -> RS_ACCESS_NICE.
+//
+//    This attribute only has an effect when the RM access rights implementation
+//    is enabled; see g_bRsAccessEnabled.
+//
+
 #endif // _CONTROL_H_