Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | /* |
2 | * ========== Copyright Header Begin ========================================== | |
3 | * | |
4 | * OpenSPARC T2 Processor File: mmi.h | |
5 | * Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. | |
6 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES. | |
7 | * | |
8 | * The above named program is free software; you can redistribute it and/or | |
9 | * modify it under the terms of the GNU General Public | |
10 | * License version 2 as published by the Free Software Foundation. | |
11 | * | |
12 | * The above named program is distributed in the hope that it will be | |
13 | * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | * General Public License for more details. | |
16 | * | |
17 | * You should have received a copy of the GNU General Public | |
18 | * License along with this work; if not, write to the Free Software | |
19 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. | |
20 | * | |
21 | * ========== Copyright Header End ============================================ | |
22 | */ | |
23 | /* | |
24 | * mmi.h | |
25 | * SAM device-model API | |
26 | * | |
27 | * Copyright (C) 2001-2005 Sun Microsystems, Inc. | |
28 | * All rights reserved. | |
29 | */ | |
30 | #ifndef _SAM_MMI_H | |
31 | #define _SAM_MMI_H | |
32 | ||
33 | #pragma ident "@(#)1.26 03/12/05 SAM-mmi.h" | |
34 | ||
35 | #include <sys/types.h> | |
36 | ||
37 | #ifdef __cplusplus | |
38 | extern "C" { | |
39 | #endif | |
40 | #if 0 | |
41 | } | |
42 | #endif | |
43 | ||
44 | ||
45 | /* opaque type definitions for MMI device models */ | |
46 | typedef void * mmi_instance_t; | |
47 | typedef void * mmi_module_t; | |
48 | ||
49 | typedef enum {mmi_false=0, mmi_true=1} mmi_bool_t; | |
50 | ||
51 | typedef uint64_t SAM_DeviceId; | |
52 | ||
53 | ||
54 | /* device operation in SAM | |
55 | * | |
56 | * 1. The simulator reads in the simulation configuration file containing "sysconf" lines at startup | |
57 | * 2. Each sysconf line specifies a module-type name, an instance name and a set of properties in the form name=value | |
58 | * For example: | |
59 | * sysconf mydev dev0 baseaddr=0xffc00040 parent=bus0 debug=true logfile=mydev.0.log | |
60 | * 3. The sysconf parser loads the mydev.so object (unless it is already loaded) | |
61 | * 4. The sysconf parser calls the instance creator function in mydev.so to create the "dev0" instance | |
62 | * 5. The dev0 instance creator retrieves its sysconf arguments using mmi_argc and mmi_argv calls and processes them | |
63 | * 6. The dev0 instance creator maps its device registers into the SAM address space using mmi_map_physio | |
64 | */ | |
65 | ||
66 | /* An MMI device model is a shared object loaded using dlopen(). | |
67 | * In SAM, this mechanism requires an _init function in the shared object: | |
68 | * | |
69 | * extern "C" void _init() | |
70 | * | |
71 | * This function must be defined. For example: | |
72 | * | |
73 | * extern "C" void _init() { | |
74 | * // mmi initialization code goes here | |
75 | * } | |
76 | ||
77 | * There are alternative means of automatically invoking an initialization function in a shared object | |
78 | * For example, the constructor of a static object in the shared object written using C++ | |
79 | * | |
80 | * In any event, SAM does not explicitly call a function in the shared object after dlopen(). | |
81 | * The _init() function is implicitly invoked by dlopen(). | |
82 | */ | |
83 | ||
84 | /* Functions returning mmi_bool_t return an SUCCESS status (true=no error). | |
85 | * An error typically indicates invalid arguments are being passed | |
86 | */ | |
87 | ||
88 | /* Devices are instantiated by SAM when specified in the config file. | |
89 | * For each device instance, the device model needs to provide an INSTANCE CREATOR function | |
90 | * which performs the instantiation. | |
91 | * | |
92 | * The instance creator function is invoked from SAM | |
93 | * with the modname (device class name) and the instance-name | |
94 | */ | |
95 | ||
96 | typedef void (*mmi_instance_creator) (const char *modname, const char *instance_name); | |
97 | ||
98 | mmi_bool_t mmi_register_instance_creator(const char * modname, mmi_instance_creator creatorfn); | |
99 | ||
100 | /* the instance_creator function can retrieve its own handle (mmi_instance_t) by calling the mmi_register_instance | |
101 | * function. In addition, the device-model can register it's implementation-specific instance data. This can be | |
102 | * retrieved (eg in the modinfo, config and interface callbacks) using the mmi_get_instance_data call. | |
103 | * The help string is displayed in response to UI commands for listing all device nodes. | |
104 | * | |
105 | * Putting the mmi_instance_t handle in the instance_data structure can be convenient | |
106 | */ | |
107 | ||
108 | mmi_instance_t mmi_register_instance(const char * modname, const char * instancename, void * instance_data, const char * short_help); | |
109 | ||
110 | void * mmi_get_instance_data(mmi_instance_t instance); | |
111 | ||
112 | ||
113 | ||
114 | /* Register a function that can respond to the modinfo UI command by printing out relevant module instance information */ | |
115 | typedef void (*mmi_modinfo_cb) (mmi_instance_t cb_instance); | |
116 | ||
117 | mmi_bool_t mmi_register_modinfo_cb(mmi_instance_t this_instance, mmi_modinfo_cb modinfo_fn); | |
118 | ||
119 | ||
120 | ||
121 | /* These calls use the mmi_instance_t handle provided by the mmi_register_instance function above. | |
122 | * They return the arguments specified on the sysconf line for this device instance | |
123 | */ | |
124 | int mmi_argc(mmi_instance_t this_instance); | |
125 | char * mmi_argv(mmi_instance_t this_instance, int index); | |
126 | ||
127 | ||
128 | ||
129 | /* A function of type mmi_access needs to be provided by the device model to handle accesses (load/store) to | |
130 | * device registers in response to instructions executed by the simulated CPU. | |
131 | * | |
132 | * The mmi_map_physio function is used to register this function with the simulator. The device-model provides a pointer | |
133 | * to user data which is returned in the call to the access function. This function should return an error indication (0 for success, some non-zero value for failure | |
134 | */ | |
135 | typedef int (*mmi_access) (uint32_t cpuid, void* obj, uint64_t paddr, mmi_bool_t wr, uint32_t size, uint64_t* buf, uint8_t bytemask); | |
136 | ||
137 | /* These calls lets the instance map/unmap its registers onto the physical address space of the simulated CPUs */ | |
138 | int mmi_map_physio (uint64_t base, uint64_t size, void* obj, mmi_access access_fn); | |
139 | void mmi_unmap_physio(uint64_t base, uint64_t size, void* obj); | |
140 | ||
141 | ||
142 | ||
143 | /* Memory access functions for devices: devices can do block read/write into simulated memory using mmi_memread and mmi_memwrite calls */ | |
144 | void mmi_memread(uint64_t paddr, uint8_t * data, uint64_t size,SAM_DeviceId sam_id = 0); | |
145 | void mmi_memwrite(uint64_t paddr, const uint8_t * data, uint64_t size,SAM_DeviceId sam_id = 0); | |
146 | ||
147 | ||
148 | /* interrupts: interrupts are not directly delivered to CPUs by devices. Instead, | |
149 | * they are passed on up the device hierarchy through a bus and/or a bridge. The bridge model | |
150 | * implements interrupt delivery to the appropriate CPU. We do not address this in MMI | |
151 | */ | |
152 | ||
153 | ||
154 | ||
155 | /* start/stop functions | |
156 | * device operation can be synchronous (in response to a sparc-cpu action and within a cpu simulation thread) | |
157 | * or asynchronous (within a separate thread). A network controller thread listening on a socket for simulated | |
158 | * network connections is an example of an asynchronous device model. | |
159 | * | |
160 | * When a run or stop command is issued at the UI prompt, an asynchronous thread needs to start/stop in response | |
161 | * (eg start=>create thread; stop=>kill thread). | |
162 | * The start/stop functions provide a way for SAM to communicate these changes in run state to asynchronous devices | |
163 | * | |
164 | * These functions are not needed for synchronous devices (devices that do not create their own simulation threads) | |
165 | */ | |
166 | typedef void (*mmi_start_stop_cb) (void * userdata); | |
167 | void mmi_register_start_stop(mmi_start_stop_cb start_action, mmi_start_stop_cb stop_action, void * userdata); | |
168 | ||
169 | ||
170 | /* checkpointing functions | |
171 | * SAM has a checkpointing feature (dump/restore) which allows a user to dump current simulator state | |
172 | * or to restore (at init-time) from a previous checkpoint. | |
173 | * A module needs to register dump and restore functions with SAM to respond to dump/restore UI actions. | |
174 | * SAM calls the dump and restore functions with the directory in which the device instance should create/find | |
175 | * its state dump. The name of the dump file is <instancename>.dmp | |
176 | * These functions should return a success indication (true=success, false=failure) | |
177 | */ | |
178 | typedef mmi_bool_t (*mmi_dump_cb)(void * userdata, const char * dirname); | |
179 | typedef mmi_bool_t (*mmi_restore_cb)(void * userdata, const char * dirname); | |
180 | ||
181 | mmi_bool_t mmi_register_dump_restore( const char *name, mmi_dump_cb dump_fn, mmi_restore_cb restore_fn, void * userdata); | |
182 | ||
183 | ||
184 | ||
185 | /* time-related functions | |
186 | * A device may want to model a delay or a periodic process (eg device latency or device internal clock) | |
187 | * | |
188 | * SAM and the MMI interface support a delayed event callback mechanism. The chosen unit of time is | |
189 | * microseconds of simulated time. | |
190 | * | |
191 | * The device model | |
192 | * defines a callback function (void function with two void * parameters) | |
193 | * gets the current time using the mmi_get_time() function. | |
194 | * adds the desired delay to the current time | |
195 | * registers a delayed callback using the mmi_register_event function | |
196 | * | |
197 | * For periodic processes, the event callback function should register itself at time=current+period | |
198 | */ | |
199 | typedef void (*mmi_event_cb) (void * userdata1, void * userdata2); | |
200 | int64_t mmi_get_time(); // current simulated time in microseconds since reboot | |
201 | mmi_bool_t mmi_register_event(int64_t when, mmi_event_cb event_fn, void * userdata1, void * userdata2); | |
202 | ||
203 | ||
204 | /* Interacting with other devices */ | |
205 | ||
206 | /* | |
207 | * When a device is instantiated/deleted in response to a sysconf directive, | |
208 | * a device module can receive about this config change by registering a config callback | |
209 | * function. | |
210 | * | |
211 | * A config event can be of the type: instance-added, instance-deleted and config-init-done | |
212 | * config-init-done refers to simulated system being initialized and ready to execute instructions. | |
213 | * instance_deleted is deprecated and obsolete. Simulator should not delete a device instance. | |
214 | ||
215 | * registering a config callback results in the callback function | |
216 | * being called for config events that have occurred in the past as | |
217 | * well as those that occur subsequently. | |
218 | */ | |
219 | ||
220 | typedef enum {MMI_CONFIG_NEW_MODULE, MMI_CONFIG_DELETE_MODULE, MMI_CONFIG_INIT_DONE} mmi_config_t; | |
221 | typedef void (*mmi_config_cb) (void *callback_data, mmi_instance_t target, const char * target_name, mmi_config_t); | |
222 | mmi_bool_t mmi_register_config_cb(mmi_instance_t this_instance, mmi_config_cb config_fn); | |
223 | ||
224 | // get a device-instance handle by name | |
225 | mmi_instance_t mmi_get_instance(const char * instancename); | |
226 | ||
227 | // register a call-back function with the simulator to respond to mmi_get_interface calls from other modules | |
228 | typedef void* (*mmi_interface_cb) (void *callback_data, const char *name); | |
229 | mmi_bool_t mmi_register_interface_cb(mmi_instance_t this_instance, mmi_interface_cb); | |
230 | ||
231 | // get a named interface from another device instance (eg pcie_device from pcie_bus). | |
232 | // the return value should be typecast to the mutually-agreed-upon interface type | |
233 | void * mmi_get_interface(mmi_instance_t instance, const char * interface_name); | |
234 | ||
235 | ||
236 | ||
237 | ||
238 | /* for non-peripheral "devices" that implement ASIs */ | |
239 | /* register call back functions for asi load/store for a particular asi */ | |
240 | typedef int (*mmi_ld_asi_action) (void *cbd, uint32_t asi, uint64_t vaddr, uint64_t *buf, int size,uint32_t cpuid); | |
241 | typedef int (*mmi_st_asi_action) (void *cbd, uint32_t asi, uint64_t vaddr, uint64_t buf, int size,uint32_t cpuid); | |
242 | void mmi_register_asi_action (mmi_instance_t instance, uint32_t asi, mmi_ld_asi_action ld_handler, mmi_st_asi_action st_handler); | |
243 | ||
244 | /* register the call back data that will passed thro' the asi load/store callback function (eg: the object pointer that handles the asi) */ | |
245 | mmi_bool_t mmi_register_asi_cb_data (mmi_instance_t instance, void *cb_data); | |
246 | ||
247 | ||
248 | /* UI commands in MMI objects | |
249 | * A user interface command can be module-specific or instance-specific | |
250 | * A module writer can choose to implement module-specific or instance-specific commands (or both) | |
251 | * A module-specific command has the module name as its first word, while the instance-specific command | |
252 | * starts with the instance-name as its first word. For example, if the simulator is configured with 2 | |
253 | * instances of a device called mydev: | |
254 | * | |
255 | * sysconf mydev dev1 ... | |
256 | * sysconf mydev dev2 ... | |
257 | * | |
258 | * Then a module-specific ui command might look like this: | |
259 | * | |
260 | * mydev show-flags | |
261 | * | |
262 | * while an instance-specific ui command might look like this: | |
263 | * | |
264 | * dev1 report-stats -all | |
265 | * | |
266 | * At instantiation, a module (or instance) registers its UI command handler with the simulation framework | |
267 | * A UI command is intercepted by the simulator, and the module/instance function corresponding to the | |
268 | * command is called. | |
269 | * | |
270 | * When the instance function is called, it is passed the | |
271 | * instance-data pointer that was provided by the instance creator to | |
272 | * the mmi_register_instance() function. | |
273 | * | |
274 | * The handler functions should return an error code (0 if no error). | |
275 | * NOTE: the error code is currently not read by SAM | |
276 | */ | |
277 | ||
278 | typedef int (*mmi_module_cmd_fn) (void * nullptr, int argc, char **argv); | |
279 | void mmi_register_module_cmd(mmi_module_t mod, const char * helpstring, mmi_module_cmd_fn fn); | |
280 | ||
281 | typedef int (*mmi_instance_cmd_fn) (void * instancedata, int argc, char **argv); | |
282 | void mmi_register_instance_cmd(mmi_instance_t instance, const char * helpstring, mmi_instance_cmd_fn fn); | |
283 | ||
284 | ||
285 | ||
286 | ||
287 | /* old mmi functions (for backwards compatibility - eg the SN sync-device model) */ | |
288 | mmi_bool_t mmi_unregister_instance_creator(mmi_instance_t instance); | |
289 | ||
290 | /* these have been deprecated in favor of mmi_map_physio (see above) */ | |
291 | ||
292 | ||
293 | typedef int (*mmi_io_action) (void *cb_data, uint64_t paddr, uint64_t *buf, int size, uint8_t bytemask, void *cpuptr); | |
294 | int mmi_register_io_action (mmi_module_t *module, mmi_io_action ld_handler, mmi_io_action st_handler); | |
295 | ||
296 | ||
297 | /* interrupt functions - these are described in the MMI documentation */ | |
298 | #if 0 // this wont work for io devices.!... | |
299 | int mmi_interrupt_packet (int dest_cpuid, void *src, int src_iscpu, uint64_t *idata); | |
300 | #else | |
301 | int mmi_interrupt_packet (int dst_aid, int src_aid, uint64_t *idata); | |
302 | //int mmi_interrupt_packet (int dest_cpuid, void *src, int src_iscpu, uint64_t *idata); | |
303 | #endif | |
304 | int mmi_interrupt_vector (int dest_cpuid, void *src, int src_iscpu, uint32_t vnum, int traptype); | |
305 | ||
306 | typedef void (*mmi_event_cycle)(void * instance_data, uint64_t repeat); | |
307 | void* mmi_register_cb_cycle (mmi_instance_t instance, mmi_event_cycle handler, uint64_t repeat); | |
308 | void mmi_unregister_cb_cycle(mmi_instance_t instance, void * intf); | |
309 | int mmi_disable_cb_cycle (void * intf); | |
310 | int mmi_enable_cb_cycle (void * intf, uint64_t repeat); | |
311 | ||
312 | ||
313 | uint64_t mmi_get_cpufreq(); | |
314 | ||
315 | #if 0 | |
316 | { | |
317 | #endif | |
318 | #ifdef __cplusplus | |
319 | } // extern "C" | |
320 | #endif | |
321 | ||
322 | ||
323 | #endif // _SAM_MMI_H |