1 /*
2 * Copyright (c) 2017, NVIDIA CORPORATION. All rights reserved.
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20 * OTHER DEALINGS IN THE SOFTWARE.
21 *
22 */
23
24 #ifndef __NVKM_CORE_FALCON_MSGQUEUE_H
25 #define __NVKM_CORE_FALCON_MSGQUEUE_H
26
27 #include <core/msgqueue.h>
28
29 /*
30 * The struct nvkm_msgqueue (named so for lack of better candidate) manages
31 * a firmware (typically, NVIDIA signed firmware) running under a given falcon.
32 *
33 * Such firmwares expect to receive commands (through one or several command
34 * queues) and will reply to such command by sending messages (using one
35 * message queue).
36 *
37 * Each firmware can support one or several units - ACR for managing secure
38 * falcons, PMU for power management, etc. A unit can be seen as a class to
39 * which command can be sent.
40 *
41 * One usage example would be to send a command to the SEC falcon to ask it to
42 * reset a secure falcon. The SEC falcon will receive the command, process it,
43 * and send a message to signal success or failure. Only when the corresponding
44 * message is received can the requester assume the request has been processed.
45 *
46 * Since we expect many variations between the firmwares NVIDIA will release
47 * across GPU generations, this library is built in a very modular way. Message
48 * formats and queues details (such as number of usage) are left to
49 * specializations of struct nvkm_msgqueue, while the functions in msgqueue.c
50 * take care of posting commands and processing messages in a fashion that is
51 * universal.
52 *
53 */
54
55 enum msgqueue_msg_priority {
56 MSGQUEUE_MSG_PRIORITY_HIGH,
57 MSGQUEUE_MSG_PRIORITY_LOW,
58 };
59
60 /**
61 * struct nvkm_msgqueue_hdr - header for all commands/messages
62 * @unit_id: id of firmware using receiving the command/sending the message
63 * @size: total size of command/message
64 * @ctrl_flags: type of command/message
65 * @seq_id: used to match a message from its corresponding command
66 */
67 struct nvkm_msgqueue_hdr {
68 u8 unit_id;
69 u8 size;
70 u8 ctrl_flags;
71 u8 seq_id;
72 };
73
74 /**
75 * struct nvkm_msgqueue_msg - base message.
76 *
77 * This is just a header and a message (or command) type. Useful when
78 * building command-specific structures.
79 */
80 struct nvkm_msgqueue_msg {
81 struct nvkm_msgqueue_hdr hdr;
82 u8 msg_type;
83 };
84
85 struct nvkm_msgqueue;
86 typedef void
87 (*nvkm_msgqueue_callback)(struct nvkm_msgqueue *, struct nvkm_msgqueue_hdr *);
88
89 /**
90 * struct nvkm_msgqueue_init_func - msgqueue functions related to initialization
91 *
92 * @gen_cmdline: build the commandline into a pre-allocated buffer
93 * @init_callback: called to process the init message
94 */
95 struct nvkm_msgqueue_init_func {
96 void (*gen_cmdline)(struct nvkm_msgqueue *, void *);
97 int (*init_callback)(struct nvkm_msgqueue *, struct nvkm_msgqueue_hdr *);
98 };
99
100 /**
101 * struct nvkm_msgqueue_acr_func - msgqueue functions related to ACR
102 *
103 * @boot_falcon: build and send the command to reset a given falcon
104 * @boot_multiple_falcons: build and send the command to reset several falcons
105 */
106 struct nvkm_msgqueue_acr_func {
107 int (*boot_falcon)(struct nvkm_msgqueue *, enum nvkm_secboot_falcon);
108 int (*boot_multiple_falcons)(struct nvkm_msgqueue *, unsigned long);
109 };
110
111 struct nvkm_msgqueue_func {
112 const struct nvkm_msgqueue_init_func *init_func;
113 const struct nvkm_msgqueue_acr_func *acr_func;
114 void (*dtor)(struct nvkm_msgqueue *);
115 struct nvkm_msgqueue_queue *(*cmd_queue)(struct nvkm_msgqueue *,
116 enum msgqueue_msg_priority);
117 void (*recv)(struct nvkm_msgqueue *queue);
118 };
119
120 /**
121 * struct nvkm_msgqueue_queue - information about a command or message queue
122 *
123 * The number of queues is firmware-dependent. All queues must have their
124 * information filled by the init message handler.
125 *
126 * @mutex_lock: to be acquired when the queue is being used
127 * @index: physical queue index
128 * @offset: DMEM offset where this queue begins
129 * @size: size allocated to this queue in DMEM (in bytes)
130 * @position: current write position
131 * @head_reg: address of the HEAD register for this queue
132 * @tail_reg: address of the TAIL register for this queue
133 */
134 struct nvkm_msgqueue_queue {
135 struct mutex mutex;
136 u32 index;
137 u32 offset;
138 u32 size;
139 u32 position;
140
141 u32 head_reg;
142 u32 tail_reg;
143 };
144
145 /**
146 * struct nvkm_msgqueue_seq - keep track of ongoing commands
147 *
148 * Every time a command is sent, a sequence is assigned to it so the
149 * corresponding message can be matched. Upon receiving the message, a callback
150 * can be called and/or a completion signaled.
151 *
152 * @id: sequence ID
153 * @state: current state
154 * @callback: callback to call upon receiving matching message
155 * @completion: completion to signal after callback is called
156 */
157 struct nvkm_msgqueue_seq {
158 u16 id;
159 enum {
160 SEQ_STATE_FREE = 0,
161 SEQ_STATE_PENDING,
162 SEQ_STATE_USED,
163 SEQ_STATE_CANCELLED
164 } state;
165 nvkm_msgqueue_callback callback;
166 struct completion *completion;
167 };
168
169 /*
170 * We can have an arbitrary number of sequences, but realistically we will
171 * probably not use that much simultaneously.
172 */
173 #define NVKM_MSGQUEUE_NUM_SEQUENCES 16
174
175 /**
176 * struct nvkm_msgqueue - manage a command/message based FW on a falcon
177 *
178 * @falcon: falcon to be managed
179 * @func: implementation of the firmware to use
180 * @init_msg_received: whether the init message has already been received
181 * @init_done: whether all init is complete and commands can be processed
182 * @seq_lock: protects seq and seq_tbl
183 * @seq: sequences to match commands and messages
184 * @seq_tbl: bitmap of sequences currently in use
185 */
186 struct nvkm_msgqueue {
187 struct nvkm_falcon *falcon;
188 const struct nvkm_msgqueue_func *func;
189 u32 fw_version;
190 bool init_msg_received;
191 struct completion init_done;
192
193 struct mutex seq_lock;
194 struct nvkm_msgqueue_seq seq[NVKM_MSGQUEUE_NUM_SEQUENCES];
195 unsigned long seq_tbl[BITS_TO_LONGS(NVKM_MSGQUEUE_NUM_SEQUENCES)];
196 };
197
198 void nvkm_msgqueue_ctor(const struct nvkm_msgqueue_func *, struct nvkm_falcon *,
199 struct nvkm_msgqueue *);
200 int nvkm_msgqueue_post(struct nvkm_msgqueue *, enum msgqueue_msg_priority,
201 struct nvkm_msgqueue_hdr *, nvkm_msgqueue_callback,
202 struct completion *, bool);
203 void nvkm_msgqueue_process_msgs(struct nvkm_msgqueue *,
204 struct nvkm_msgqueue_queue *);
205
206 int msgqueue_0137c63d_new(struct nvkm_falcon *, const struct nvkm_secboot *,
207 struct nvkm_msgqueue **);
208 int msgqueue_0137bca5_new(struct nvkm_falcon *, const struct nvkm_secboot *,
209 struct nvkm_msgqueue **);
210 int msgqueue_0148cdec_new(struct nvkm_falcon *, const struct nvkm_secboot *,
211 struct nvkm_msgqueue **);
212
213 #endif