sim/ppc/device.h

   1 /*  This file is part of the program psim.
   2
   3     Copyright (C) 1994-1995, Andrew Cagney <cagney@highland.com.au>
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18
  19     */
  20
  21
  22 #ifndef _DEVICE_TREE_H_
  23 #define _DEVICE_TREE_H_
  24
  25 #ifndef INLINE_DEVICE
  26 #define INLINE_DEVICE
  27 #endif
  28
  29
  30
  31 /* declared in basics.h, this object is used everywhere */
  32 /* typedef struct _device device; */
  33
  34
  35
  36 \f
  37 /* Device Tree:
  38
  39    All the devices in this model live in a tree. The following allow
  40    the location/manipulation of this tree */
  41
  42 device INLINE_DEVICE *device_parent
  43 (device *me);
  44
  45 const char INLINE_DEVICE *device_name
  46 (device *me);
  47
  48 void INLINE_DEVICE *device_data
  49 (device *me);
  50
  51
  52 /* Grow the device tree adding either a specific device or
  53    alternativly a device found in the device table */
  54
  55 device INLINE_DEVICE *device_tree_add_device
  56 (device *root,
  57  const char *prefix,
  58  device *new_sub_tree);
  59
  60 device INLINE_DEVICE *device_tree_add_found
  61 (device *root,
  62  const char *prefix,
  63  const char *name);
  64
  65 device INLINE_DEVICE *device_tree_add_found_c
  66 (device *root,
  67  const char *prefix,
  68  const char *name,
  69  const char *c1);
  70
  71 device INLINE_DEVICE *device_tree_add_found_c_uw
  72 (device *root,
  73  const char *prefix,
  74  const char *name,
  75  const char *c1,
  76  unsigned_word uw2);
  77
  78 device INLINE_DEVICE *device_tree_add_found_uw_u
  79 (device *root,
  80  const char *prefix,
  81  const char *name,
  82  unsigned_word uw1,
  83  unsigned u2);
  84
  85 device INLINE_DEVICE *device_tree_add_found_uw_u_u
  86 (device *root,
  87  const char *prefix,
  88  const char *name,
  89  unsigned_word uw1,
  90  unsigned u2,
  91  unsigned u3);
  92
  93 device INLINE_DEVICE *device_tree_add_found_uw_u_u_c
  94 (device *root,
  95  const char *prefix,
  96  const char *name,
  97  unsigned_word uw1,
  98  unsigned u2,
  99  unsigned u3,
 100  const char *c4);
 101
 102 device INLINE_DEVICE *device_tree_add_found_uw_uw_u_u_c
 103 (device *root,
 104  const char *prefix,
 105  const char *name,
 106  unsigned_word uw1,
 107  unsigned_word uw2,
 108  unsigned u3,
 109  unsigned u4,
 110  const char *c5);
 111
 112 device INLINE_DEVICE *device_tree_add_found_uw_uw_u_u_u
 113 (device *root,
 114  const char *prefix,
 115  const char *name,
 116  unsigned_word uw1,
 117  unsigned_word uw2,
 118  unsigned u3,
 119  unsigned u4,
 120  unsigned u5);
 121
 122
 123 /* Query the device tree, null is returned if the specified device is
 124    not found */
 125
 126 device INLINE_DEVICE *device_tree_find_device
 127 (device *root,
 128  const char *path);
 129
 130
 131 /* traverse the device tree visiting all notes (either pre or post
 132    fix) */
 133
 134 typedef void (device_tree_traverse_function)
 135      (device *device,
 136       void *data);
 137
 138 void INLINE_DEVICE device_tree_traverse
 139 (device *root,
 140  device_tree_traverse_function *prefix,
 141  device_tree_traverse_function *postfix,
 142  void *data);
 143
 144
 145 /* dump a node, this can be passed to the device_tree_traverse()
 146    function to dump out the entire device tree */
 147
 148 void INLINE_DEVICE device_tree_dump
 149 (device *device,
 150  void *ignore_data_argument);
 151
 152
 153
 154 \f
 155 /* Device Properties:
 156
 157    Attached to a device (typically by open boot firmware) are
 158    properties that profile the devices features.  The below allow the
 159    manipulation of device properties */
 160
 161 /* Each device can have associated properties.  Internal to
 162    psim those properties are strictly typed.  Within the simulation,
 163    no such control exists */
 164
 165 typedef enum {
 166   integer_property,
 167   boolean_property,
 168   string_property,
 169   array_property,
 170   null_property,
 171 } device_property_type;
 172
 173 typedef struct _device_property device_property;
 174 struct _device_property {
 175   device *owner;
 176   device_property_type type;
 177   unsigned sizeof_array;
 178   const void *array;
 179 };
 180
 181
 182 /* Basic operations used by software */
 183
 184 const char INLINE_DEVICE *device_find_next_property
 185 (device *me,
 186  const char *previous);
 187
 188 /* INLINE_DEVICE void device_add_property
 189    No such external function, all properties, when added are explictly
 190    typed */
 191
 192 void INLINE_DEVICE device_add_array_property
 193 (device *me,
 194  const char *property,
 195  const void *array,
 196  int sizeof_array);
 197
 198 void INLINE_DEVICE device_add_integer_property
 199 (device *me,
 200  const char *property,
 201  signed_word integer);
 202
 203 void INLINE_DEVICE device_add_boolean_property
 204 (device *me,
 205  const char *property,
 206  int bool);
 207
 208 void INLINE_DEVICE device_add_null_property
 209 (device *me,
 210  const char *property);
 211
 212 void INLINE_DEVICE device_add_string_property
 213 (device *me,
 214  const char *property,
 215  const char *string);
 216
 217
 218 /* Locate a property returning its description.  Return NULL if the
 219    named property is not found */
 220
 221 const device_property INLINE_DEVICE *device_find_property
 222 (device *me,
 223  const char *property);
 224
 225
 226 /* Process all properties attached to the named device */
 227
 228 typedef void (device_traverse_property_function)
 229      (device *me,
 230       const char *name,
 231       void *data);
 232
 233 void INLINE_DEVICE device_traverse_properties
 234 (device *me,
 235  device_traverse_property_function *traverse,
 236  void *data);
 237
 238
 239 /* Similar to above except that the property *must* be in the device
 240    tree and *must* be of the specified type. */
 241
 242 const device_property INLINE_DEVICE *device_find_array_property
 243 (device *me,
 244  const char *property);
 245
 246 signed_word INLINE_DEVICE device_find_integer_property
 247 (device *me,
 248  const char *property);
 249
 250 const char INLINE_DEVICE *device_find_string_property
 251 (device *me,
 252  const char *property);
 253
 254 int INLINE_DEVICE device_find_boolean_property
 255 (device *me,
 256  const char *property);
 257
 258
 259 \f
 260 /* Device Hardware:
 261
 262    A device principaly is modeling real hardware that a processor can
 263    directly interact with via load/stores dma's and interrupts.  The
 264    interface below is used by the hardware side of the device
 265    model. */
 266
 267 /* Address access attributes that can be attached to a devices address
 268    range */
 269 typedef enum _access_type {
 270   access_invalid = 0,
 271   access_read = 1,
 272   access_write = 2,
 273   access_read_write = 3,
 274   access_exec = 4,
 275   access_read_exec = 5,
 276   access_write_exec = 6,
 277   access_read_write_exec = 7,
 278 } access_type;
 279
 280
 281 /* Address attachement types */
 282 typedef enum _attach_type {
 283   attach_invalid,
 284   attach_callback,
 285   attach_default,
 286   attach_raw_memory,
 287 } attach_type;
 288
 289
 290 /* Initialization:
 291
 292    A device is made fully functional in two stages.
 293
 294    1. It is created. A device is created _before_ it is entered into
 295    the device tree.  During creation any permenant structures needed
 296    by the device should be created/initialized.
 297
 298    2. It is initialized.  Before a simulation run, each device in the
 299    device tree is initialized in prefix order.  As part of this
 300    initialization, a device should (re)attach its self to its parent
 301    as needed.
 302
 303    */
 304
 305 device INLINE_DEVICE *device_create
 306 (const char *name,
 307  device *parent);
 308
 309 /* some external functions want to create things */
 310 typedef struct _device_callbacks device_callbacks;
 311
 312 device INLINE_DEVICE *device_create_from
 313 (const char *name,
 314  void *data,
 315  const device_callbacks *callbacks,
 316  device *parent);
 317
 318 void INLINE_DEVICE device_init
 319 (device *me,
 320  psim *system);
 321
 322 /* initialize the entire tree */
 323
 324 void INLINE_DEVICE device_tree_init
 325 (device *root,
 326  psim *system);
 327
 328
 329 /* Data transfers:
 330
 331    A device may permit the reading/writing (IO) of its registers in
 332    one or more address spaces.  For instance, a PCI device may have
 333    config registers in its config space and control registers in both
 334    the io and memory spaces of a PCI bus.
 335
 336    Similarly, a device may initiate a data transfer (DMA) by passing
 337    such a request up to its parent.
 338
 339    Init:
 340
 341    As part of its initialization (not creation) and possibly also as a
 342    consequence of IO a device may attach its self to one or more of
 343    the address spaces of its parent device.
 344
 345    For instance, a PCI device, during initialization would attach its
 346    config registers (space=0?, base=0, nr_bytes=64) to its parent PCI
 347    bridge.  Later, due to a write to this config space, the same
 348    device may in turn find it necessary to also attach its self to
 349    it's parent's `memory' or `io' space.
 350
 351    To perform these operations, a device will call upon its parent
 352    using either device_attach_address or device_detach_address.
 353
 354    * Any address specified is according to what the device expects to
 355    see.
 356
 357    * Any detach operation must exactly match a previous attach.
 358
 359    * included with the attach or detach is the devices name, the
 360    parent may use this as part of determining how to map map between a
 361    child's address + space and its own.
 362
 363    * at any time, at most one device can have a default mapping
 364    registered.
 365
 366
 367    IO:
 368
 369    A device receives requests to perform reads/writes to its registers
 370    or memory either A. from a processor or B. from a parent device.
 371
 372    The device may then in turn either A. resolve the IO request
 373    locally by processing the data or trigering an exception or
 374    B. re-mapping the access onto one of its local address spaces and
 375    then in turn passing that on to one of its children.
 376
 377    * Any address passed is relative to the local device.  Eg for PCI
 378    config registers, the address would (normally) be in the range of 0
 379    to 63.
 380
 381    * Any exception situtation triggered by an IO operation (processor
 382    != NULL) is handled in one of the following ways: 1. Machine check
 383    (and similar): issued immediatly by restarting the cpu; 2. External
 384    exception: issue delayed (using events.h) until the current
 385    instruction execution cycle is completed; 3. Slave device (and
 386    similar): the need for the interrupt is passed on to the devices
 387    parent (which being an interrupt control unit will in turn take one
 388    of the actions described here); 4. Forget it.
 389
 390    * Any exception situtation trigered by a non IO operation
 391    (processor == NULL) is handled buy returning 0.
 392
 393    * Transfers of size <= 8 and of a power of 2 *must* be correctly
 394    aligned and should be treated as a `single cycle' transfer.
 395
 396    DMA:
 397
 398    A device initiates a DMA transfer by calling its parent with the
 399    request.  At the top level (if not done earlier) this is reflected
 400    back down the tree as io read/writes to the target device.
 401
 402    This function is subject to change ...
 403
 404    */
 405
 406 void INLINE_DEVICE device_attach_address
 407 (device *me,
 408  const char *name,
 409  attach_type attach,
 410  int space,
 411  unsigned_word addr,
 412  unsigned nr_bytes,
 413  access_type access,
 414  device *who); /*callback/default*/
 415
 416 void INLINE_DEVICE device_detach_address
 417 (device *me,
 418  const char *name,
 419  attach_type attach,
 420  int space,
 421  unsigned_word addr,
 422  unsigned nr_bytes,
 423  access_type access,
 424  device *who); /*callback/default*/
 425
 426 unsigned INLINE_DEVICE device_io_read_buffer
 427 (device *me,
 428  void *dest,
 429  int space,
 430  unsigned_word addr,
 431  unsigned nr_bytes,
 432  cpu *processor,
 433  unsigned_word cia);
 434
 435 unsigned INLINE_DEVICE device_io_write_buffer
 436 (device *me,
 437  const void *source,
 438  int space,
 439  unsigned_word addr,
 440  unsigned nr_bytes,
 441  cpu *processor,
 442  unsigned_word cia);
 443
 444 unsigned INLINE_DEVICE device_dma_read_buffer
 445 (device *me,
 446  void *dest,
 447  int space,
 448  unsigned_word addr,
 449  unsigned nr_bytes);
 450
 451 unsigned INLINE_DEVICE device_dma_write_buffer
 452 (device *me,
 453  const void *source,
 454  int space,
 455  unsigned_word addr,
 456  unsigned nr_bytes,
 457  int violate_read_only_section);
 458
 459
 460 /* Interrupts:
 461
 462    As mentioned above.  Instead of handling an interrupt directly, a
 463    device may instead pass the need to interrupt on to its parent.
 464
 465    Init:
 466
 467    Before passing interrupts up to is parent, a device must first
 468    attach its interrupt lines to the parent device.  To do this, the
 469    device uses the parents attach/detach calls.
 470
 471    Interrupts:
 472
 473    A child notifies a parent of a change in an interrupt lines status
 474    using the interrupt call.  Similarly, a parent may notify a child
 475    of any `interrupt ack' sequence using the interrupt_ack call.
 476
 477    */
 478
 479 void INLINE_DEVICE device_attach_interrupt
 480 (device *me,
 481  device *who,
 482  int interrupt_line,
 483  const char *name);
 484
 485 void INLINE_DEVICE device_detach_interrupt
 486 (device *me,
 487  device *who,
 488  int interrupt_line,
 489  const char *name);
 490
 491 void INLINE_DEVICE device_interrupt
 492 (device *me,
 493  device *who,
 494  int interrupt_line,
 495  int interrupt_status,
 496  cpu *processor,
 497  unsigned_word cia);
 498
 499 void INLINE_DEVICE device_interrupt_ack
 500 (device *me,
 501  int interrupt_line,
 502  int interrupt_status);
 503
 504
 505 /* IOCTL:
 506
 507    Very simply, a catch all for any thing that turns up that until now
 508    either hasn't been thought of or doesn't justify an extra function. */
 509
 510 void EXTERN_DEVICE device_ioctl
 511 (device *me,
 512  psim *system,
 513  cpu *processor,
 514  unsigned_word cia,
 515  ...);
 516
 517
 518 \f
 519 /* Device software - the instance
 520
 521    Under development
 522
 523    In addition to the processor directly manipulating a device via
 524    read/write operations.  A program may manipulate a device
 525    indirectly via OpenBoot calls.  The following provide a higher
 526    level software interface to the devices */
 527
 528 #if 0
 529 device_instance INLINE_DEVICE *device_instance_open
 530 (device *me,
 531  const char *device_specifier);
 532
 533 void INLINE_DEVICE device_instance_close
 534 (device_instance *instance);
 535
 536 int INLINE_DEVICE device_instance_read
 537 (device_instance *instance,
 538  void *addr,
 539  unsigned_word len);
 540
 541 int INLINE_DEVICE device_instance_write
 542 (device_instance *instance,
 543  const void *addr,
 544  unsigned_word len);
 545
 546 int INLINE_DEVICE device_instance_seek
 547 (device_instance *instance,
 548  unsigned_word pos_hi,
 549  unsigned_word pos_lo);
 550
 551 device INLINE_DEVICE *device_instance_device
 552 (device_instance *instance);
 553
 554 const char INLINE_DEVICE *device_instance_name
 555 (device_instance *instance);
 556 #endif
 557
 558
 559
 560 \f
 561 /* Device dregs... */
 562
 563 /* Parse a device name */
 564
 565 void INLINE_DEVICE device_tree_parse_name
 566 (const char *name,
 567  const char **driver_name,
 568  const char **unit_address,
 569  const char **device_arguments,
 570  const char **end);
 571
 572
 573 /* Parse a device name, various formats:
 574
 575    uw: unsigned_word
 576    u: unsigned
 577    c: string */
 578
 579 int INLINE_DEVICE scand_c
 580 (const char *name,
 581  char *c1,
 582  unsigned c1size);
 583
 584 int INLINE_DEVICE scand_c_uw_u
 585 (const char *name,
 586  char *c1,
 587  unsigned c1size,
 588  unsigned_word *uw2,
 589  unsigned *u3);
 590
 591 int INLINE_DEVICE scand_uw
 592 (const char *name,
 593  unsigned_word *uw1);
 594
 595 int INLINE_DEVICE scand_uw_c
 596 (const char *name,
 597  unsigned_word *uw1,
 598  char *c2,
 599  unsigned c2size);
 600
 601 int INLINE_DEVICE scand_uw_u
 602 (const char *name,
 603  unsigned_word *uw1,
 604  unsigned *u2);
 605
 606 int INLINE_DEVICE scand_uw_u_u
 607 (const char *name,
 608  unsigned_word *uw1,
 609  unsigned *u2,
 610  unsigned *u3);
 611
 612 int INLINE_DEVICE scand_uw_u_u_c
 613 (const char *name,
 614  unsigned_word *uw1,
 615  unsigned *u2,
 616  unsigned *u3,
 617  char *c4,
 618  unsigned c4size);
 619
 620 int INLINE_DEVICE scand_uw_uw
 621 (const char *name,
 622  unsigned_word *uw1,
 623  unsigned_word *uw2);
 624
 625 int INLINE_DEVICE scand_uw_uw_u
 626 (const char *name,
 627  unsigned_word *uw1,
 628  unsigned_word *uw2,
 629  unsigned *u3);
 630
 631 int INLINE_DEVICE scand_uw_uw_u_u_c
 632 (const char *name,
 633  unsigned_word *uw1,
 634  unsigned_word *uw2,
 635  unsigned *u3,
 636  unsigned *u4,
 637  char *c5,
 638  unsigned c5size);
 639
 640 int INLINE_DEVICE scand_uw_uw_u_u_u
 641 (const char *name,
 642  unsigned_word *uw1,
 643  unsigned_word *uw2,
 644  unsigned *u3,
 645  unsigned *u4,
 646  unsigned *u5);
 647
 648 #endif /* _DEVICE_TREE_H_ */