1/* The common simulator framework for GDB, the GNU Debugger. 2 3 Copyright 2002, 2007 Free Software Foundation, Inc. 4 5 Contributed by Andrew Cagney and Red Hat. 6 7 This file is part of GDB. 8 9 This program is free software; you can redistribute it and/or modify 10 it under the terms of the GNU General Public License as published by 11 the Free Software Foundation; either version 3 of the License, or 12 (at your option) any later version. 13 14 This program is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU General Public License for more details. 18 19 You should have received a copy of the GNU General Public License 20 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 21 22 23#ifndef HW_DEVICE_H 24#define HW_DEVICE_H 25 26/* declared in sim-basics.h, this object is used everywhere */ 27/* typedef struct _device device; */ 28 29 30/* Introduction: 31 32 As explained in earlier sections, the device, device instance, 33 property and ports lie at the heart of PSIM's device model. 34 35 In the below a synopsis of the device object and the operations it 36 supports are given. 37 */ 38 39 40/* Creation: 41 42 The devices are created using a sequence of steps. In particular: 43 44 o A tree framework is created. 45 46 At this point, properties can be modified and extra 47 devices inserted (or removed?). 48 49#if LATER 50 51 Any properties that have a run-time value (eg ihandle 52 or device instance pointer properties) are entered 53 into the device tree using a named reference to the 54 corresponding runtime object that is to be created. 55 56#endif 57 58 o Real devices are created for all the dummy devices. 59 60 A device can assume that all of its parents have been 61 initialized. 62 63 A device can assume that all non run-time properties 64 have been initialized. 65 66 As part of being created, the device normally attaches 67 itself to its parent bus. 68 69#if LATER 70 71 Device instance data is initialized. 72 73#endif 74 75#if LATER 76 77 o Any run-time properties are created. 78 79#endif 80 81#if MUCH_MUCH_LATER 82 83 o Some devices, as part of their initialization 84 might want to refer to ihandle properties 85 in the device tree. 86 87#endif 88 89 NOTES: 90 91 o It is important to separate the creation 92 of an actual device from the creation 93 of the tree. The alternative creating 94 the device in two stages: As a separate 95 entity and then as a part of the tree. 96 97#if LATER 98 o Run-time properties can not be created 99 until after the devices in the tree 100 have been created. Hence an extra pass 101 for handling them. 102#endif 103 104 */ 105 106/* Relationships: 107 108 A device is able to determine its relationship to other devices 109 within the tree. Operations include querying for a devices parent, 110 sibling, child, name, and path (from the root). 111 112 */ 113 114 115#define hw_parent(hw) ((hw)->parent_of_hw + 0) 116 117#define hw_sibling(hw) ((hw)->sibling_of_hw + 0) 118 119#define hw_child(hw) ((hw)->child_of_hw + 0) 120 121 122 123/* Herritage: 124 125 */ 126 127#define hw_family(hw) ((hw)->family_of_hw + 0) 128 129#define hw_name(hw) ((hw)->name_of_hw + 0) 130 131#define hw_args(hw) ((hw)->args_of_hw + 0) 132 133#define hw_path(hw) ((hw)->path_of_hw + 0) 134 135 136 137/* Short cut to the root node of the tree */ 138 139#define hw_root(hw) ((hw)->root_of_hw + 0) 140 141/* Short cut back to the simulator object */ 142 143#define hw_system(hw) ((hw)->system_of_hw) 144 145/* For requests initiated by a CPU the cpu that initiated the request */ 146 147struct _sim_cpu *hw_system_cpu (struct hw *hw); 148 149 150/* Device private data */ 151 152#define hw_data(hw) ((hw)->data_of_hw) 153 154#define set_hw_data(hw, value) \ 155((hw)->data_of_hw = (value)) 156 157 158 159/* Perform a soft reset of the device */ 160 161typedef unsigned (hw_reset_method) 162 (struct hw *me); 163 164#define hw_reset(hw) ((hw)->to_reset (hw)) 165 166#define set_hw_reset(hw, method) \ 167((hw)->to_reset = method) 168 169 170/* Hardware operations: 171 172 Connecting a parent to its children is a common bus. The parent 173 node is described as the bus owner and is responisble for 174 co-ordinating bus operations. On the bus, a SPACE:ADDR pair is used 175 to specify an address. A device that is both a bus owner (parent) 176 and bus client (child) are referred to as a bridging device. 177 178 A child performing a data (DMA) transfer will pass its request to 179 the bus owner (the devices parent). The bus owner will then either 180 reflect the request to one of the other devices attached to the bus 181 (a child of the bus owner) or bridge the request up the tree to the 182 next bus. */ 183 184 185/* Children attached to a bus can register (attach) themselves to 186 specific addresses on their attached bus. 187 188 (A device may also be implicitly attached to certain bus 189 addresses). 190 191 The SPACE:ADDR pair specify an address on the common bus that 192 connects the parent and child devices. */ 193 194typedef void (hw_attach_address_method) 195 (struct hw *me, 196 int level, 197 int space, 198 address_word addr, 199 address_word nr_bytes, 200 struct hw *client); /*callback/default*/ 201 202#define hw_attach_address(me, level, space, addr, nr_bytes, client) \ 203((me)->to_attach_address (me, level, space, addr, nr_bytes, client)) 204 205#define set_hw_attach_address(hw, method) \ 206((hw)->to_attach_address = (method)) 207 208typedef void (hw_detach_address_method) 209 (struct hw *me, 210 int level, 211 int space, 212 address_word addr, 213 address_word nr_bytes, 214 struct hw *client); /*callback/default*/ 215 216#define hw_detach_address(me, level, space, addr, nr_bytes, client) \ 217((me)->to_detach_address (me, level, space, addr, nr_bytes, client)) 218 219#define set_hw_detach_address(hw, method) \ 220((hw)->to_detach_address = (method)) 221 222 223/* An IO operation from a parent to a child via the conecting bus. 224 225 The SPACE:ADDR pair specify an address on the bus shared between 226 the parent and child devices. */ 227 228typedef unsigned (hw_io_read_buffer_method) 229 (struct hw *me, 230 void *dest, 231 int space, 232 unsigned_word addr, 233 unsigned nr_bytes); 234 235#define hw_io_read_buffer(hw, dest, space, addr, nr_bytes) \ 236((hw)->to_io_read_buffer (hw, dest, space, addr, nr_bytes)) 237 238#define set_hw_io_read_buffer(hw, method) \ 239((hw)->to_io_read_buffer = (method)) 240 241typedef unsigned (hw_io_write_buffer_method) 242 (struct hw *me, 243 const void *source, 244 int space, 245 unsigned_word addr, 246 unsigned nr_bytes); 247 248#define hw_io_write_buffer(hw, src, space, addr, nr_bytes) \ 249((hw)->to_io_write_buffer (hw, src, space, addr, nr_bytes)) 250 251#define set_hw_io_write_buffer(hw, method) \ 252((hw)->to_io_write_buffer = (method)) 253 254 255/* Conversly, the device pci1000,1@1 may need to perform a dma transfer 256 into the cpu/memory core. Just as I/O moves towards the leaves, 257 dma transfers move towards the core via the initiating devices 258 parent nodes. The root device (special) converts the DMA transfer 259 into reads/writes to memory. 260 261 The SPACE:ADDR pair specify an address on the common bus connecting 262 the parent and child devices. */ 263 264typedef unsigned (hw_dma_read_buffer_method) 265 (struct hw *bus, 266 void *dest, 267 int space, 268 unsigned_word addr, 269 unsigned nr_bytes); 270 271#define hw_dma_read_buffer(bus, dest, space, addr, nr_bytes) \ 272((bus)->to_dma_read_buffer (bus, dest, space, addr, nr_bytes)) 273 274#define set_hw_dma_read_buffer(me, method) \ 275((me)->to_dma_read_buffer = (method)) 276 277typedef unsigned (hw_dma_write_buffer_method) 278 (struct hw *bus, 279 const void *source, 280 int space, 281 unsigned_word addr, 282 unsigned nr_bytes, 283 int violate_read_only_section); 284 285#define hw_dma_write_buffer(bus, src, space, addr, nr_bytes, violate_ro) \ 286((bus)->to_dma_write_buffer (bus, src, space, addr, nr_bytes, violate_ro)) 287 288#define set_hw_dma_write_buffer(me, method) \ 289((me)->to_dma_write_buffer = (method)) 290 291/* Address/size specs for devices are encoded following a convention 292 similar to that used by OpenFirmware. In particular, an 293 address/size is packed into a sequence of up to four cell words. 294 The number of words determined by the number of {address,size} 295 cells attributes of the device. */ 296 297typedef struct _hw_unit { 298 int nr_cells; 299 unsigned_cell cells[4]; /* unused cells are zero */ 300} hw_unit; 301 302 303/* For the given bus, the number of address and size cells used in a 304 hw_unit. */ 305 306#define hw_unit_nr_address_cells(bus) ((bus)->nr_address_cells_of_hw_unit + 0) 307 308#define hw_unit_nr_size_cells(bus) ((bus)->nr_size_cells_of_hw_unit + 0) 309 310 311/* For the given device, its identifying hw_unit address. 312 313 Each device has an identifying hw_unit address. That address is 314 used when identifying one of a number of identical devices on a 315 common controller bus. ex fd0&fd1. */ 316 317const hw_unit *hw_unit_address 318(struct hw *me); 319 320 321/* Convert between a textual and the internal representation of a 322 hw_unit address/size. 323 324 NOTE: A device asks its parent to translate between a hw_unit and 325 textual representation. This is because the textual address of a 326 device is specified using the parent busses notation. */ 327 328typedef int (hw_unit_decode_method) 329 (struct hw *bus, 330 const char *encoded, 331 hw_unit *unit); 332 333#define hw_unit_decode(bus, encoded, unit) \ 334((bus)->to_unit_decode (bus, encoded, unit)) 335 336#define set_hw_unit_decode(hw, method) \ 337((hw)->to_unit_decode = (method)) 338 339typedef int (hw_unit_encode_method) 340 (struct hw *bus, 341 const hw_unit *unit, 342 char *encoded, 343 int sizeof_buf); 344 345#define hw_unit_encode(bus, unit, encoded, sizeof_encoded) \ 346((bus)->to_unit_encode (bus, unit, encoded, sizeof_encoded)) 347 348#define set_hw_unit_encode(hw, method) \ 349((hw)->to_unit_encode = (method)) 350 351 352/* As the bus that the device is attached too, to translate a devices 353 hw_unit address/size into a form suitable for an attach address 354 call. 355 356 Return a zero result if the address should be ignored when looking 357 for attach addresses. */ 358 359typedef int (hw_unit_address_to_attach_address_method) 360 (struct hw *bus, 361 const hw_unit *unit_addr, 362 int *attach_space, 363 unsigned_word *attach_addr, 364 struct hw *client); 365 366#define hw_unit_address_to_attach_address(bus, unit_addr, attach_space, attach_addr, client) \ 367((bus)->to_unit_address_to_attach_address (bus, unit_addr, attach_space, attach_addr, client)) 368 369#define set_hw_unit_address_to_attach_address(hw, method) \ 370((hw)->to_unit_address_to_attach_address = (method)) 371 372typedef int (hw_unit_size_to_attach_size_method) 373 (struct hw *bus, 374 const hw_unit *unit_size, 375 unsigned *attach_size, 376 struct hw *client); 377 378#define hw_unit_size_to_attach_size(bus, unit_size, attach_size, client) \ 379((bus)->to_unit_size_to_attach_size (bus, unit_size, attach_size, client)) 380 381#define set_hw_unit_size_to_attach_size(hw, method) \ 382((hw)->to_unit_size_to_attach_size = (method)) 383 384 385extern char *hw_strdup (struct hw *me, const char *str); 386 387 388/* Utilities: 389 390 */ 391 392/* IOCTL:: 393 394 Often devices require `out of band' operations to be performed. 395 For instance a pal device may need to notify a PCI bridge device 396 that an interrupt ack cycle needs to be performed on the PCI bus. 397 Within PSIM such operations are performed by using the generic 398 ioctl call <<hw_ioctl()>>. 399 400 */ 401 402typedef enum { 403 hw_ioctl_break, /* unsigned_word requested_break */ 404 hw_ioctl_set_trace, /* void */ 405 hw_ioctl_create_stack, /* unsigned_word *sp, char **argv, char **envp */ 406 hw_ioctl_change_media, /* const char *new_image (possibly NULL) */ 407 nr_hw_ioctl_requests, 408} hw_ioctl_request; 409 410typedef int (hw_ioctl_method) 411 (struct hw *me, 412 hw_ioctl_request request, 413 va_list ap); 414 415int hw_ioctl 416(struct hw *me, 417 hw_ioctl_request request, 418 ...); 419 420 421/* Error reporting:: 422 423 So that errors originating from devices appear in a consistent 424 format, the <<hw_abort()>> function can be used. Formats and 425 outputs the error message before aborting the simulation 426 427 Devices should use this function to abort the simulation except 428 when the abort reason leaves the simulation in a hazardous 429 condition (for instance a failed malloc). 430 431 */ 432 433void hw_abort 434(struct hw *me, 435 const char *fmt, 436 ...) __attribute__ ((format (printf, 2, 3))); 437 438void hw_vabort 439(struct hw *me, 440 const char *fmt, 441 va_list ap); 442 443void hw_halt 444(struct hw *me, 445 int reason, 446 int status); 447 448 449#define hw_trace_p(hw) ((hw)->trace_of_hw_p + 0) 450 451void hw_trace 452(struct hw *me, 453 const char *fmt, 454 ...) __attribute__ ((format (printf, 2, 3))); 455 456#define HW_TRACE(ARGS) \ 457do { \ 458 if (hw_trace_p (me)) \ 459 { \ 460 hw_trace ARGS; \ 461 } \ 462} while (0) 463 464 465/* Some of the related functions require specific types */ 466 467struct hw_property_data; 468struct hw_port_data; 469struct hw_base_data; 470struct hw_alloc_data; 471struct hw_event_data; 472struct hw_handle_data; 473struct hw_instance_data; 474 475/* Finally the hardware device - keep your grubby little mits off of 476 these internals! :-) */ 477 478struct hw { 479 480 /* our relatives */ 481 struct hw *parent_of_hw; 482 struct hw *sibling_of_hw; 483 struct hw *child_of_hw; 484 485 /* our identity */ 486 const char *name_of_hw; 487 const char *family_of_hw; 488 const char *args_of_hw; 489 const char *path_of_hw; 490 491 /* our data */ 492 void *data_of_hw; 493 494 /* hot links */ 495 struct hw *root_of_hw; 496 struct sim_state *system_of_hw; 497 498 /* identifying data */ 499 hw_unit unit_address_of_hw; 500 int nr_address_cells_of_hw_unit; 501 int nr_size_cells_of_hw_unit; 502 503 /* Soft reset */ 504 hw_reset_method *to_reset; 505 506 /* Basic callbacks */ 507 hw_io_read_buffer_method *to_io_read_buffer; 508 hw_io_write_buffer_method *to_io_write_buffer; 509 hw_dma_read_buffer_method *to_dma_read_buffer; 510 hw_dma_write_buffer_method *to_dma_write_buffer; 511 hw_attach_address_method *to_attach_address; 512 hw_detach_address_method *to_detach_address; 513 514 /* More complicated callbacks */ 515 hw_ioctl_method *to_ioctl; 516 int trace_of_hw_p; 517 518 /* address callbacks */ 519 hw_unit_decode_method *to_unit_decode; 520 hw_unit_encode_method *to_unit_encode; 521 hw_unit_address_to_attach_address_method *to_unit_address_to_attach_address; 522 hw_unit_size_to_attach_size_method *to_unit_size_to_attach_size; 523 524 /* related data */ 525 struct hw_property_data *properties_of_hw; 526 struct hw_port_data *ports_of_hw; 527 struct hw_base_data *base_of_hw; 528 struct hw_alloc_data *alloc_of_hw; 529 struct hw_event_data *events_of_hw; 530 struct hw_handle_data *handles_of_hw; 531 struct hw_instance_data *instances_of_hw; 532 533}; 534 535 536#endif 537