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
|
// IBM_PROLOG_BEGIN_TAG
// This is an automatically generated prolog.
//
// $Source: src/include/usr/hwpf/fapi/fapiUtil.H $
//
// IBM CONFIDENTIAL
//
// COPYRIGHT International Business Machines Corp. 2011
//
// p1
//
// Object Code Only (OCO) source materials
// Licensed Internal Code Source Materials
// IBM HostBoot Licensed Internal Code
//
// The source code for this program is not published or other-
// wise divested of its trade secrets, irrespective of what has
// been deposited with the U.S. Copyright Office.
//
// Origin: 30
//
// IBM_PROLOG_END
/**
* @file fapiUtil.H
*
* @brief Defines utility functions that the platform code must implement.
*/
/*
* Change Log ******************************************************************
* Flag Defect/Feature User Date Description
* ------ -------------- ---------- ----------- ----------------------------
* mjjones 04/13/2011 Created.
* camvanng 05/31/2011 Removed fapiOutputx macros
* mjjones 06/30/2011 Removed #include
* mjjones 07/05/2011 Removed rogue tab
* camvanng 09/06/2011 Added fapiLogError
* mjjones 09/14/2011 Prepended fapi to delay
* mjjones 10/05/2011 Added fapiCheckType
* mjjones 10/13/2011 Added extern "C" to functions
* camvanng 10/14/2011 Added fapiLoadInitFile &
* fapiUnloadInitFile
*/
#ifndef FAPIUTIL_H_
#define FAPIUTIL_H_
#include <stdint.h>
#include <stddef.h>
#include <fapiReturnCode.H>
// It is an eCMD requirement that these functions have a "C" symbol
// because they may be used from a dynamically linked shared library
extern "C"
{
/**
* @brief Assert that an expression is true. Aborting the process if false.
*
* @note Implemented by platform code
*
* @param[in] i_expression If not true then process should be aborted
*/
void fapiAssert(bool i_expression);
/**
* @brief Delay this thread. Hostboot will use the nanoseconds parameter
* and make a syscall to nanosleep. While in the syscall, the hostboot
* kernel will continue to consume CPU cycles as it looks for a runnable
* task. When the delay time expires, the task becomes runnable and will soon
* return from the syscall. Callers of delay() in the hostboot environment
* will likely have to know the mHz clock speed they are running on and
* compute a non-zero value for i_nanoSeconds.
*
* On the FSP, it was sometimes acceptable to just provide zero for the
* sleep delay time, causing the task to yield its time slice. By the
* time the calling task could run again, it was pretty certain enough
* host cycles had past. This is probably not acceptable in
* the hostboot environment. Callers should calculate and provide a
* sleep value in nanoseconds relative to host clock speed.
*
* On FSP when VBU is the target, then the i_simCycles parameter will be
* used instead. The FSP needs to use the simdispatcher client/server
* API and issue a command to the awan to advance the simulation the
* specified number of cycles.
*
* @param[in] i_nanoSeconds nanoseconds to sleep
* @param[in] i_simCycles count of Awan cycles to advance
*
* @return ReturnCode. Zero on success, else platform specified error.
*/
fapi::ReturnCode fapiDelay(uint64_t i_nanoSeconds, uint64_t i_simCycles);
/**
* @brief Log an error.
*
* This function can be called by HWP to log an error.
*
* @note Implemented by platform code
*
* @param[io] Reference to ReturnCode (Any references to data and error
* target are removed and rc value is set to success after
* function ends.)
*
* Example usage:
* fapi::ReturnCode l_rc;
* FAPI_EXEC_HWP(l_rc, function1, i_target);
* if (!l_rc)
* {
* fapiLogError(l_rc);
* }
*
* FAPI_EXEC_HWP(l_rc, function2, i_target)
* return rc;
*/
void fapiLogError(fapi::ReturnCode & io_rc);
/** @brief This function answers the question, is scand tracing turned on?
* The implementation of this function is specific to the platform.
*
* @returns Boolean indication
*/
bool platIsScanTraceEnabled();
/** @brief Alter the state of scand tracing.
* The implementation of this function is specific to the platform.
*
* @param[in] True to enable or false to disable scan trace.
* @return void
*/
void platSetScanTrace(bool i_enable);
/** @brief Load the initfile
*
* This function can be called by a HWP to load an initfile.
*
* @note Implemented by platform code. Platform code is
* responsible for allocating any memory needed to load
* the initfile.
*
* @param[in] the .if filename: <initfile>.if
* @param[out] address in memory where initfile is loaded
* @param[out] size of memory allocated for initfile
*
* @return ReturnCode. Zero on success, else platform specified error.
*/
fapi::ReturnCode fapiLoadInitFile(const char * i_file, const char *& o_addr,
size_t & o_size);
/** @brief Unload the initfile
*
* This function can be called by a HWP to unload an initfile.
*
* @note Implemented by platform code. Platform code is
* responsible for deleting any allocated memory.
*
* @param[in] the .if filename: <initfile>.if
* @param[in,out] address in memory where initfile is loaded
* set to NULL on exit
* @param[in,out] size of memory allocated for initfile
* set to 0 on exit
*
* @return ReturnCode. Zero on success, else platform specified error.
*/
fapi::ReturnCode fapiUnloadInitFile(const char * i_file, const char *& io_addr,
size_t & io_size);
}
namespace fapi
{
/**
* @brief Check the type of a variable
*
* This function can be called to check that a variable type is as expected
*/
template<typename T>
void fapiCheckType(const T &) {}
}
#endif // FAPIUTIL_H_
|
