1/* SPDX-License-Identifier: GPL-2.0-only WITH Linux-syscall-note */
2/*
3 * Userspace interface for AMD Dynamic Boost Control (DBC)
4 *
5 * Copyright (C) 2023 Advanced Micro Devices, Inc.
6 *
7 * Author: Mario Limonciello <mario.limonciello@amd.com>
8 */
9
10#ifndef __PSP_DBC_USER_H__
11#define __PSP_DBC_USER_H__
12
13#include <linux/types.h>
14
15/**
16 * DOC: AMD Dynamic Boost Control (DBC) interface
17 */
18
19#define DBC_NONCE_SIZE		16
20#define DBC_SIG_SIZE		32
21#define DBC_UID_SIZE		16
22
23/**
24 * struct dbc_user_nonce - Nonce exchange structure (input/output).
25 * @auth_needed: Whether the PSP should authenticate this request (input).
26 *               0: no authentication, PSP will return single use nonce.
27 *               1: authentication: PSP will return multi-use nonce.
28 * @nonce:       8 byte value used for future authentication (output).
29 * @signature:   Optional 32 byte signature created by software using a
30 *               previous nonce (input).
31 */
32struct dbc_user_nonce {
33	__u32	auth_needed;
34	__u8	nonce[DBC_NONCE_SIZE];
35	__u8	signature[DBC_SIG_SIZE];
36} __packed;
37
38/**
39 * struct dbc_user_setuid - UID exchange structure (input).
40 * @uid:       16 byte value representing software identity
41 * @signature: 32 byte signature created by software using a previous nonce
42 */
43struct dbc_user_setuid {
44	__u8	uid[DBC_UID_SIZE];
45	__u8	signature[DBC_SIG_SIZE];
46} __packed;
47
48/**
49 * struct dbc_user_param - Parameter exchange structure (input/output).
50 * @msg_index: Message indicating what parameter to set or get (input)
51 * @param:     4 byte parameter, units are message specific. (input/output)
52 * @signature: 32 byte signature.
53 *             - When sending a message this is to be created by software
54 *               using a previous nonce (input)
55 *             - For interpreting results, this signature is updated by the
56 *               PSP to allow software to validate the authenticity of the
57 *               results.
58 */
59struct dbc_user_param {
60	__u32	msg_index;
61	__u32	param;
62	__u8	signature[DBC_SIG_SIZE];
63} __packed;
64
65/**
66 * Dynamic Boost Control (DBC) IOC
67 *
68 * possible return codes for all DBC IOCTLs:
69 *  0:          success
70 *  -EINVAL:    invalid input
71 *  -E2BIG:     excess data passed
72 *  -EFAULT:    failed to copy to/from userspace
73 *  -EBUSY:     mailbox in recovery or in use
74 *  -ENODEV:    driver not bound with PSP device
75 *  -EACCES:    request isn't authorized
76 *  -EINVAL:    invalid parameter
77 *  -ETIMEDOUT: request timed out
78 *  -EAGAIN:    invalid request for state machine
79 *  -ENOENT:    not implemented
80 *  -ENFILE:    overflow
81 *  -EPERM:     invalid signature
82 *  -EIO:       unknown error
83 */
84#define DBC_IOC_TYPE	'D'
85
86/**
87 * DBCIOCNONCE - Fetch a nonce from the PSP for authenticating commands.
88 *               If a nonce is fetched without authentication it can only
89 *               be utilized for one command.
90 *               If a nonce is fetched with authentication it can be used
91 *               for multiple requests.
92 */
93#define DBCIOCNONCE	_IOWR(DBC_IOC_TYPE, 0x1, struct dbc_user_nonce)
94
95/**
96 * DBCIOCUID - Set the user ID (UID) of a calling process.
97 *             The user ID is 8 bytes long. It must be programmed using a
98 *             32 byte signature built using the nonce fetched from
99 *             DBCIOCNONCE.
100 *             The UID can only be set once until the system is rebooted.
101 */
102#define DBCIOCUID	_IOW(DBC_IOC_TYPE, 0x2, struct dbc_user_setuid)
103
104/**
105 * DBCIOCPARAM - Set or get a parameter from the PSP.
106 *               This request will only work after DBCIOCUID has successfully
107 *               set the UID of the calling process.
108 *               Whether the parameter is set or get is controlled by the
109 *               message ID in the request.
110 *               This command must be sent using a 32 byte signature built
111 *               using the nonce fetched from DBCIOCNONCE.
112 *               When the command succeeds, the 32 byte signature will be
113 *               updated by the PSP for software to authenticate the results.
114 */
115#define DBCIOCPARAM	_IOWR(DBC_IOC_TYPE, 0x3, struct dbc_user_param)
116
117/**
118 * enum dbc_cmd_msg - Messages utilized by DBCIOCPARAM
119 * @PARAM_GET_FMAX_CAP:		Get frequency cap (MHz)
120 * @PARAM_SET_FMAX_CAP:		Set frequency cap (MHz)
121 * @PARAM_GET_PWR_CAP:		Get socket power cap (mW)
122 * @PARAM_SET_PWR_CAP:		Set socket power cap (mW)
123 * @PARAM_GET_GFX_MODE:		Get graphics mode (0/1)
124 * @PARAM_SET_GFX_MODE:		Set graphics mode (0/1)
125 * @PARAM_GET_CURR_TEMP:	Get current temperature (degrees C)
126 * @PARAM_GET_FMAX_MAX:		Get maximum allowed value for frequency (MHz)
127 * @PARAM_GET_FMAX_MIN:		Get minimum allowed value for frequency (MHz)
128 * @PARAM_GET_SOC_PWR_MAX:	Get maximum allowed value for SoC power (mw)
129 * @PARAM_GET_SOC_PWR_MIN:	Get minimum allowed value for SoC power (mw)
130 * @PARAM_GET_SOC_PWR_CUR:	Get current value for SoC Power (mW)
131 */
132enum dbc_cmd_msg {
133	PARAM_GET_FMAX_CAP	= 0x3,
134	PARAM_SET_FMAX_CAP	= 0x4,
135	PARAM_GET_PWR_CAP	= 0x5,
136	PARAM_SET_PWR_CAP	= 0x6,
137	PARAM_GET_GFX_MODE	= 0x7,
138	PARAM_SET_GFX_MODE	= 0x8,
139	PARAM_GET_CURR_TEMP	= 0x9,
140	PARAM_GET_FMAX_MAX	= 0xA,
141	PARAM_GET_FMAX_MIN	= 0xB,
142	PARAM_GET_SOC_PWR_MAX	= 0xC,
143	PARAM_GET_SOC_PWR_MIN	= 0xD,
144	PARAM_GET_SOC_PWR_CUR	= 0xE,
145};
146
147#endif /* __PSP_DBC_USER_H__ */
148