Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | /* |
2 | * mmi.h | |
3 | * SAM device-model API | |
4 | * | |
5 | * Copyright (C) 2001-2005 Sun Microsystems, Inc. | |
6 | * All rights reserved. | |
7 | */ | |
8 | #ifndef _SAM_MMI_H | |
9 | #define _SAM_MMI_H | |
10 | ||
11 | #pragma ident "@(#)1.26 03/12/05 SAM-mmi.h" | |
12 | ||
13 | #include <sys/types.h> | |
14 | ||
15 | #ifdef __cplusplus | |
16 | extern "C" { | |
17 | #endif | |
18 | #if 0 | |
19 | } | |
20 | #endif | |
21 | ||
22 | ||
23 | /* opaque type definitions for MMI device models */ | |
24 | typedef void * mmi_instance_t; | |
25 | typedef void * mmi_module_t; | |
26 | ||
27 | typedef enum {mmi_false=0, mmi_true=1} mmi_bool_t; | |
28 | ||
29 | /* device operation in SAM | |
30 | * | |
31 | * 1. The simulator reads in the simulation configuration file containing "sysconf" lines at startup | |
32 | * 2. Each sysconf line specifies a module-type name, an instance name and a set of properties in the form name=value | |
33 | * For example: | |
34 | * sysconf mydev dev0 baseaddr=0xffc00040 parent=bus0 debug=true logfile=mydev.0.log | |
35 | * 3. The sysconf parser loads the mydev.so object (unless it is already loaded) | |
36 | * 4. The sysconf parser calls the instance creator function in mydev.so to create the "dev0" instance | |
37 | * 5. The dev0 instance creator retrieves its sysconf arguments using mmi_argc and mmi_argv calls and processes them | |
38 | * 6. The dev0 instance creator maps its device registers into the SAM address space using mmi_map_physio | |
39 | */ | |
40 | ||
41 | /* An MMI device model is a shared object loaded using dlopen(). | |
42 | * In SAM, this mechanism requires an _init function in the shared object: | |
43 | * | |
44 | * extern "C" void _init() | |
45 | * | |
46 | * This function must be defined. For example: | |
47 | * | |
48 | * extern "C" void _init() { | |
49 | * // mmi initialization code goes here | |
50 | * } | |
51 | ||
52 | * There are alternative means of automatically invoking an initialization function in a shared object | |
53 | * For example, the constructor of a static object in the shared object written using C++ | |
54 | * | |
55 | * In any event, SAM does not explicitly call a function in the shared object after dlopen(). | |
56 | * The _init() function is implicitly invoked by dlopen(). | |
57 | */ | |
58 | ||
59 | /* Functions returning mmi_bool_t return an SUCCESS status (true=no error). | |
60 | * An error typically indicates invalid arguments are being passed | |
61 | */ | |
62 | ||
63 | /* Devices are instantiated by SAM when specified in the config file. | |
64 | * For each device instance, the device model needs to provide an INSTANCE CREATOR function | |
65 | * which performs the instantiation. | |
66 | * | |
67 | * The instance creator function is invoked from SAM | |
68 | * with the modname (device class name) and the instance-name | |
69 | */ | |
70 | ||
71 | typedef void (*mmi_instance_creator) (const char *modname, const char *instance_name); | |
72 | ||
73 | mmi_bool_t mmi_register_instance_creator(const char * modname, mmi_instance_creator creatorfn); | |
74 | ||
75 | /* the instance_creator function can retrieve its own handle (mmi_instance_t) by calling the mmi_register_instance | |
76 | * function. This function is also used to provide a help string specific to this instance. | |
77 | * This call is optional; the mmi_get_instance() call can be used to get the device's own handle. The help string is | |
78 | * set to the name of the instance by default. This not being too helpful, device models are encouraged to provide | |
79 | * a useful short help string. This help string is displayed in response to UI commands for listing all device nodes. | |
80 | */ | |
81 | mmi_instance_t mmi_register_instance(const char * modname, const char * instancename, const char * short_help); | |
82 | ||
83 | ||
84 | /* Register a function that can respond to the modinfo UI command by printing out relevant module instance information */ | |
85 | typedef void (*mmi_modinfo_cb) (mmi_instance_t cb_instance); | |
86 | /* this_instance can be obtained using the mmi_get_instance call | |
87 | * defined below, and the instance_name parameter of the instance | |
88 | * creator fn */ | |
89 | mmi_bool_t mmi_register_modinfo_cb(mmi_instance_t this_instance, mmi_modinfo_cb modinfo_fn); | |
90 | ||
91 | ||
92 | ||
93 | /* These calls use the mmi_instance_t handle provided by the mmi_register_instance function above. | |
94 | * They return the arguments specified on the sysconf line for this device instance | |
95 | */ | |
96 | int mmi_argc(mmi_instance_t this_instance); | |
97 | char * mmi_argv(mmi_instance_t this_instance, int index); | |
98 | ||
99 | ||
100 | ||
101 | /* A function of type mmi_access needs to be provided by the device model to handle accesses (load/store) to | |
102 | * device registers in response to instructions executed by the simulated CPU. | |
103 | * | |
104 | * The mmi_map_physio function is used to register this function with the simulator. The device-model provides a pointer | |
105 | * 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 | |
106 | */ | |
107 | 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); | |
108 | ||
109 | /* These calls lets the instance map/unmap its registers onto the physical address space of the simulated CPUs */ | |
110 | int mmi_map_physio (uint64_t base, uint64_t size, void* obj, mmi_access access_fn); | |
111 | void mmi_unmap_physio(uint64_t base, uint64_t size, void* obj); | |
112 | ||
113 | ||
114 | ||
115 | /* Memory access functions for devices: devices can do block read/write into simulated memory using mmi_memread and mmi_memwrite calls */ | |
116 | void mmi_memread(uint64_t paddr, uint8_t * data, uint64_t size); | |
117 | void mmi_memwrite(uint64_t paddr, const uint8_t * data, uint64_t size); | |
118 | ||
119 | ||
120 | /* interrupts: interrupts are not directly delivered to CPUs by devices. Instead, | |
121 | * they are passed on up the device hierarchy through a bus and/or a bridge. The bridge model | |
122 | * implements interrupt delivery to the appropriate CPU. We do not address this in MMI | |
123 | */ | |
124 | ||
125 | ||
126 | /* Interacting with other devices */ | |
127 | ||
128 | /* | |
129 | * When a device is instantiated/deleted in response to a sysconf directive, | |
130 | * a device module can receive about this config change by registering a config callback | |
131 | * function. | |
132 | * | |
133 | * A config event can be of the type: instance-added, instance-deleted and config-init-done | |
134 | * config-init-done refers to simulated system being initialized and ready to execute instructions. | |
135 | * instance_deleted is deprecated and obsolete. Simulator should not delete a device instance. | |
136 | ||
137 | * registering a config callback results in the callback function | |
138 | * being called for config events that have occurred in the past as | |
139 | * well as those that occur subsequently. | |
140 | */ | |
141 | ||
142 | typedef enum {MMI_CONFIG_NEW_MODULE, MMI_CONFIG_DELETE_MODULE, MMI_CONFIG_INIT_DONE} mmi_config_t; | |
143 | typedef void (*mmi_config_cb) (void *callback_data, mmi_instance_t target, const char * target_name, mmi_config_t); | |
144 | mmi_bool_t mmi_register_config_cb(mmi_instance_t this_instance, mmi_config_cb config_fn); | |
145 | ||
146 | // get a device-instance handle by name | |
147 | mmi_instance_t mmi_get_instance(const char * instancename); | |
148 | ||
149 | // register a call-back function with the simulator to respond to mmi_get_interface calls from other modules | |
150 | typedef void* (*mmi_interface_cb) (void *callback_data, const char *name); | |
151 | mmi_bool_t mmi_register_interface_cb(mmi_instance_t this_instance, mmi_interface_cb); | |
152 | ||
153 | // get a named interface from another device instance (eg pcie_device from pcie_bus). | |
154 | // the return value should be typecast to the mutually-agreed-upon interface type | |
155 | void * mmi_get_interface(mmi_instance_t instance, const char * interface_name); | |
156 | ||
157 | ||
158 | ||
159 | /* old mmi functions (for backwards compatibility - eg the SN sync-device model) */ | |
160 | mmi_bool_t mmi_unregister_instance_creator(mmi_instance_t instance); | |
161 | ||
162 | /* these have been deprecated in favor of mmi_map_physio (see above) */ | |
163 | ||
164 | ||
165 | typedef int (*mmi_io_action) (void *cb_data, uint64_t paddr, uint64_t *buf, int size, uint8_t bytemask, void *cpuptr); | |
166 | int mmi_register_io_action (mmi_module_t *module, mmi_io_action ld_handler, mmi_io_action st_handler); | |
167 | ||
168 | /* interrupt functions - these are described in the MMI documentation */ | |
169 | int mmi_interrupt_packet (int dest_cpuid, void *src, int src_iscpu, uint64_t *idata); | |
170 | int mmi_interrupt_vector (int dest_cpuid, void *src, int src_iscpu, uint32_t vnum, int traptype); | |
171 | ||
172 | ||
173 | #if 0 | |
174 | { | |
175 | #endif | |
176 | #ifdef __cplusplus | |
177 | } // extern "C" | |
178 | #endif | |
179 | ||
180 | ||
181 | #endif // _SAM_MMI_H |