1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
|
/* IBM_PROLOG_BEGIN_TAG */
/* This is an automatically generated prolog. */
/* */
/* $Source: src/import/chips/p9/procedures/utils/stopreg/p9_stop_api.H $ */
/* */
/* OpenPOWER HostBoot Project */
/* */
/* Contributors Listed Below - COPYRIGHT 2015,2020 */
/* [+] International Business Machines Corp. */
/* */
/* */
/* Licensed under the Apache License, Version 2.0 (the "License"); */
/* you may not use this file except in compliance with the License. */
/* You may obtain a copy of the License at */
/* */
/* http://www.apache.org/licenses/LICENSE-2.0 */
/* */
/* Unless required by applicable law or agreed to in writing, software */
/* distributed under the License is distributed on an "AS IS" BASIS, */
/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or */
/* implied. See the License for the specific language governing */
/* permissions and limitations under the License. */
/* */
/* IBM_PROLOG_END_TAG */
#ifndef __P9_STOP_IMAGE_API_
#define __P9_STOP_IMAGE_API_
#include <stdint.h>
#ifdef __SKIBOOT__
#include <skiboot.h>
#endif
///
/// @file p9_stop_api.H
/// @brief describes STOP API which create/manipulate STOP image.
///
// *HWP HW Owner : Greg Still <stillgs@us.ibm.com>
// *HWP FW Owner : Prem Shanker Jha <premjha2@in.ibm.com>
// *HWP Team : PM
// *HWP Level : 2
// *HWP Consumed by : HB:HYP
#ifdef __cplusplus
namespace stopImageSection
{
#endif
/**
* @brief all SPRs and MSR for which register restore is to be supported.
* @note STOP API design has built in support to accomodate 8 register of
* scope core and thread each.
*/
typedef enum
{
P9_STOP_SPR_DAWR = 180, // thread register
P9_STOP_SPR_CIABR = 187, // thread register
P9_STOP_SPR_DAWRX = 188, // thread register
P9_STOP_SPR_HSPRG0 = 304, // thread register
P9_STOP_SPR_HRMOR = 313, // core register
P9_STOP_SPR_LPCR = 318, // thread register
P9_STOP_SPR_HMEER = 337, // core register
P9_STOP_SPR_PTCR = 464, // core register
P9_STOP_SPR_USPRG0 = 496, // thread register
P9_STOP_SPR_USPRG1 = 497, // thread register
P9_STOP_SPR_URMOR = 505, // core register
P9_STOP_SPR_SMFCTRL = 511, // thread register
P9_STOP_SPR_LDBAR = 850, // thread register
P9_STOP_SPR_PSSCR = 855, // thread register
P9_STOP_SPR_PMCR = 884, // core register
P9_STOP_SPR_HID = 1008, // core register
P9_STOP_SPR_MSR = 2000, // thread register
//enum members which are project agnostic
PROC_STOP_SPR_DAWR = 180, // thread register
PROC_STOP_SPR_CIABR = 187, // thread register
PROC_STOP_SPR_DAWRX = 188, // thread register
PROC_STOP_SPR_HSPRG0 = 304, // thread register
PROC_STOP_SPR_HRMOR = 313, // core register
PROC_STOP_SPR_LPCR = 318, // thread register
PROC_STOP_SPR_HMEER = 337, // core register
PROC_STOP_SPR_PTCR = 464, // core register
PROC_STOP_SPR_USPRG0 = 496, // thread register
PROC_STOP_SPR_USPRG1 = 497, // thread register
PROC_STOP_SPR_URMOR = 505, // core register
PROC_STOP_SPR_SMFCTRL = 511, // thread register
PROC_STOP_SPR_LDBAR = 850, // thread register
PROC_STOP_SPR_PSSCR = 855, // thread register
PROC_STOP_SPR_PMCR = 884, // core register
PROC_STOP_SPR_HID = 1008, // core register
PROC_STOP_SPR_MSR = 2000, // thread register
} CpuReg_t;
/**
* @brief lists all the bad error codes.
*/
typedef enum
{
STOP_SAVE_SUCCESS = 0,
STOP_SAVE_ARG_INVALID_IMG = 1,
STOP_SAVE_ARG_INVALID_REG = 2,
STOP_SAVE_ARG_INVALID_THREAD = 3,
STOP_SAVE_ARG_INVALID_MODE = 4,
STOP_SAVE_ARG_INVALID_CORE = 5,
STOP_SAVE_SPR_ENTRY_NOT_FOUND = 6,
STOP_SAVE_SPR_ENTRY_UPDATE_FAILED = 7,
STOP_SAVE_SCOM_INVALID_OPERATION = 8,
STOP_SAVE_SCOM_INVALID_SECTION = 9,
STOP_SAVE_SCOM_INVALID_ADDRESS = 10,
STOP_SAVE_SCOM_INVALID_CHIPLET = 11,
STOP_SAVE_SCOM_ENTRY_UPDATE_FAILED = 12,
STOP_SAVE_INVALID_FUSED_CORE_STATUS = 13,
STOP_SAVE_FAIL = 14, // for internal failure within firmware.
STOP_SAVE_SPR_ENTRY_MISSING = 15,
STOP_SAVE_SPR_BIT_POS_RESERVE = 16,
STOP_SAVE_API_IMG_INCOMPATIBLE = 18,
} StopReturnCode_t;
/**
* @brief summarizes all operations supported on scom entries of STOP image.
*/
typedef enum
{
P9_STOP_SCOM_OP_MIN = 0,
P9_STOP_SCOM_APPEND = 1,
P9_STOP_SCOM_REPLACE = 2,
P9_STOP_SCOM_OR = 3,
P9_STOP_SCOM_AND = 4,
P9_STOP_SCOM_NOOP = 5,
P9_STOP_SCOM_RESET = 6,
P9_STOP_SCOM_OR_APPEND = 7,
P9_STOP_SCOM_AND_APPEND = 8,
P9_STOP_SCOM_OP_MAX = 9,
//enum members which are project agnostic
PROC_STOP_SCOM_OP_MIN = 0,
PROC_STOP_SCOM_APPEND = 1,
PROC_STOP_SCOM_REPLACE = 2,
PROC_STOP_SCOM_OR = 3,
PROC_STOP_SCOM_AND = 4,
PROC_STOP_SCOM_NOOP = 5,
PROC_STOP_SCOM_RESET = 6,
PROC_STOP_SCOM_OR_APPEND = 7,
PROC_STOP_SCOM_AND_APPEND = 8,
PROC_STOP_SCOM_OP_MAX = 9,
} ScomOperation_t;
/**
* @brief All subsections that contain scom entries in a STOP image.
*/
typedef enum
{
P9_STOP_SECTION_MIN = 0,
P9_STOP_SECTION_CORE_SCOM = 1,
P9_STOP_SECTION_EQ_SCOM = 2,
P9_STOP_SECTION_L2 = 3,
P9_STOP_SECTION_L3 = 4,
P9_STOP_SECTION_MAX = 5,
//enum members which are project agnostic
PROC_STOP_SECTION_MIN = 0,
PROC_STOP_SECTION_CORE_SCOM = 1,
PROC_STOP_SECTION_EQ_SCOM = 2,
PROC_STOP_SECTION_L2 = 3,
PROC_STOP_SECTION_L3 = 4,
PROC_STOP_SECTION_MAX = 5,
} ScomSection_t;
/**
* @brief versions pertaining relvant to STOP API.
*/
typedef enum
{
STOP_API_VER = 0x00,
STOP_API_VER_CONTROL = 0x02,
} VersionList_t;
/**
* @brief Summarizes bit position allocated to SPRs in save bit mask vector.
*/
typedef enum
{
BIT_POS_CIABR = 0,
BIT_POS_DAWR = 1,
BIT_POS_DAWRX = 2,
BIT_POS_HSPRG0 = 3,
BIT_POS_LDBAR = 4,
BIT_POS_LPCR = 5,
BIT_POS_PSSCR = 6,
BIT_POS_MSR = 7,
BIT_POS_HID = 21,
BIT_POS_HMEER = 22,
BIT_POS_PMCR = 23,
BIT_POS_PTCR = 24,
BIT_POS_SMFCTRL = 28,
BIT_POS_USPRG0 = 29,
BIT_POS_USPRG1 = 30,
} SprBitPositionList_t;
/**
* @brief List of major incompatibilities between API version.
* @note STOP APIs assumes a specific HOMER layout, certain
* level of CME-SGPE hcode and certain version of self-save restore
* binary. A mismatch can break STOP function.
*/
typedef enum
{
SMF_SUPPORT_MISSING_IN_HOMER = 0x01,
SELF_SUPPORT_MISSING_FOR_LE_HYP = 0x02,
IPL_RUNTIME_CPU_SAVE_VER_MISMATCH = 0x04,
SELF_RESTORE_VER_MISMATCH = 0x08,
} VersionIncompList_t;
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Updates STOP image entry associated with CPU register.
* @param[in] i_pImage start address of homer image associated with processor.
* @param[in] i_regId id of SPR for which STOP image needs to be updated.
* @param[in] i_regData data to be restored in SPR register.
* @param[in] i_pir value of processor identification register (PIR)
* @return STOP_SAVE_SUCCESS SUCCESS if image is updated successfully, error
* code otherwise.
*/
StopReturnCode_t p9_stop_save_cpureg( void* const i_pImage,
const CpuReg_t i_regId,
const uint64_t i_regData,
const uint64_t i_pir );
/**
* @brief Updates STOP image entry associated with CPU register.
* @param[in] i_pImage start address of homer image associated with processor.
* @param[in] i_corePos physical core's relative position within processor chip.
* @return STOP_SAVE_SUCCESS SUCCESS if image is initialized successfully, error
* code otherwise.
* @note API is intended only for use case of HOMER build. There is no explicit
* effort to support any other use case.
*
*/
StopReturnCode_t p9_stop_init_cpureg( void* const i_pImage, const uint32_t i_corePos );
/**
* @brief Updates scom image entry associated with given core or cache in
* STOP section of homer image.
* @param[in] i_pImage start address of homer image of P9 chip.
* @param[in] i_scomAddress fully qualified address of SCOM register.
* @param[in] i_scomData data associated with SCOM register.
* @param[in] i_operation operation to be done on SCOM image entry.
* @param[in] i_section area to which given SCOM entry belongs.
* @return STOP_SAVE_SUCCESS if image is updated successfully, error code
* otherwise.
* @note API is intended to update SCOM image entry associated with given
* core or given part of a cache section. API doesn't validate if
* a given SCOM address really belongs to given section.
*/
StopReturnCode_t p9_stop_save_scom( void* const i_pImage,
const uint32_t i_scomAddress,
const uint64_t i_scomData,
const ScomOperation_t i_operation,
const ScomSection_t i_section );
/**
* @brief Facilitates self save and restore of a list of SPRs of a thread.
* @param[in] i_pImage points to the start of HOMER image of P9 chip.
* @param[in] i_pir PIR associated with thread
* @param[in] i_saveRegVector bit vector representing SPRs that needs to be restored.
* @return STOP_SAVE_SUCCESS if API succeeds, error code otherwise.
* @note SPR save vector is a bit vector. For each SPR supported,
* there is an associated bit position in the bit vector.Refer
* to definition of SprBitPositionList_t to determine bit position
* associated with a particular SPR.
*/
StopReturnCode_t
p9_stop_save_cpureg_control( void* i_pImage, const uint64_t i_pir,
const uint32_t i_saveRegVector );
/**
* @brief initializes self-save region with specific instruction.
* @param[in] i_pImage start address of homer image of P9 chip.
* @param[in] i_corePos physical core's relative position within processor chip.
* @return STOP_SAVE_SUCCESS if self-save is initialized successfully,
* error code otherwise.
* @note API is intended only for use case of HOMER build. There is no explicit
* effort to support any other use case.
*/
StopReturnCode_t p9_stop_init_self_save( void* const i_pImage, const uint32_t i_corePos );
/**
* @brief creates SCOM restore entry for a given scom adress in HOMER.
* @param i_pImage points to start address of HOMER image.
* @param i_scomAddress address associated with SCOM restore entry.
* @param i_scomData data associated with SCOM restore entry.
* @param i_operation operation type requested for API.
* @param i_section section of HOMER in which restore entry needs to be created.
* @return STOP_SAVE_SUCCESS if API succeeds, error code otherwise.
* @note It is an API for creating SCOM restore entry in HOMER. It is agnostic to
* generation of POWER processor.
*/
StopReturnCode_t proc_stop_save_scom( void* const i_pImage,
const uint32_t i_scomAddress,
const uint64_t i_scomData,
const ScomOperation_t i_operation,
const ScomSection_t i_section );
/**
* @brief initializes self save restore region of HOMER.
* @param[in] i_pImage points to base of HOMER image.
* @param[in] i_corePos position of the physical core.
* @return STOP_SAVE_SUCCESS if API succeeds, error code otherwise.
* @note It is an API for initializing self restore region in HOMER. It is agnostic to
* generation of POWER processor.
*/
StopReturnCode_t proc_stop_init_cpureg( void* const i_pImage, const uint32_t i_corePos );
/**
* @brief enables self save for a given set of SPRs
* @param[in] i_pImage points to start address of HOMER image.
* @param[in] i_pir PIR value associated with core and thread.
* @param[in] i_saveRegVector bit vector representing the SPRs that needs to be self saved.
* @return STOP_SAVE_SUCCESS if API succeeds, error code otherwise.
* @note It is an API for enabling self save of SPRs and it is agnostic to
* generation of POWER processor.
*/
StopReturnCode_t proc_stop_save_cpureg_control( void* i_pImage,
const uint64_t i_pir,
const uint32_t i_saveRegVector );
/**
* @brief creates an SPR restore entry in HOMER
* @param[in] i_pImage points to start address of HOMER image.
* @param[in] i_pir PIR value associated with core and thread.
* @param[in] i_saveRegVector bit vector representing the SPRs that needs to be self saved.
* @return STOP_SAVE_SUCCESS if API succeeds, error code otherwise.
* @note It is an API for enabling self save of SPRs and it is agnostic to
* generation of POWER processor.
*/
StopReturnCode_t proc_stop_save_cpureg( void* const i_pImage,
const CpuReg_t i_regId,
const uint64_t i_regData,
const uint64_t i_pir );
/**
* @brief initializes self-save region with specific instruction.
* @param[in] i_pImage start address of homer image.
* @param[in] i_corePos physical core's relative position within processor chip.
* @return STOP_SAVE_SUCCESS if self-save is initialized successfully,
* error code otherwise.
* @note API is project agnostic and is intended only for use case of HOMER build.
* There is no explicit effort to support any other use case.
*/
StopReturnCode_t proc_stop_init_self_save( void* const i_pImage, const uint32_t i_corePos );
/**
* @brief verifies if API is compatible of current HOMER image.
* @param[in] i_pImage points to the start of HOMER image of P9 chip.
* @param[out] o_inCompVector list of incompatibilities found.
* @return STOP_SAVE_SUCCESS if if API succeeds, error code otherwise.
*/
StopReturnCode_t proc_stop_api_discover_capability( void* const i_pImage, uint64_t* o_inCompVector );
#ifdef __cplusplus
} // extern "C"
}; // namespace stopImageSection ends
#endif //__cplusplus
#endif //__P9_STOP_IMAGE_API_
|