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