doc/html/ref/pci-library-reference.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >PCI Library reference</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="The eCos PCI Library"
  23 HREF="ecos-pci-library.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="The eCos PCI Library"
  26 HREF="ecos-pci-library.html"><LINK
  27 REL="NEXT"
  28 TITLE="eCos POSIX compatibility layer"
  29 HREF="posix-compatibility.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="ecos-pci-library.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 30. The eCos PCI Library</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="posix-compatibility.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="PCI-LIBRARY-REFERENCE">PCI Library reference</H1
  86 ><P
  87 >This document defines the PCI Support Library for eCos.</P
  88 ><P
  89 >The PCI support library provides a set of routines for accessing
  90 the PCI bus configuration space in a portable manner. This is provided
  91 by two APIs. The high level API is used by device drivers, or other
  92 code, to access the PCI configuration space portably. The low level
  93 API is used by the PCI library itself to access the hardware in
  94 a platform-specific manner, and may also be used by device drivers
  95 to access the PCI configuration space directly.</P
  96 ><P
  97 >Underlying the low-level API is HAL support for the basic
  98 configuration space operations. These should not generally be used
  99 by any code other than the PCI library, and are present in the HAL
 100 to allow low level initialization of the PCI bus and devices to
 101 take place if necessary.</P
 102 ><DIV
 103 CLASS="SECT2"
 104 ><H2
 105 CLASS="SECT2"
 106 ><A
 107 NAME="AEN12801">PCI Library API</H2
 108 ><P
 109 >The PCI library provides the following routines and types
 110 for accessing the PCI configuration space.</P
 111 ><P
 112 >The API for the PCI library is found in the header file
 113 <TT
 114 CLASS="FILENAME"
 115 >&lt;cyg/io/pci.h&gt;</TT
 116 >.</P
 117 ></DIV
 118 ><DIV
 119 CLASS="SECT2"
 120 ><H2
 121 CLASS="SECT2"
 122 ><A
 123 NAME="AEN12806">Definitions</H2
 124 ><P
 125 >The header file contains definitions for the common configuration
 126 structure offsets and specimen values for device, vendor and class
 127 code.</P
 128 ></DIV
 129 ><DIV
 130 CLASS="SECT2"
 131 ><H2
 132 CLASS="SECT2"
 133 ><A
 134 NAME="AEN12809">Types and data structures</H2
 135 ><P
 136 >The following types are defined:</P
 137 ><TABLE
 138 BORDER="5"
 139 BGCOLOR="#E0E0F0"
 140 WIDTH="70%"
 141 ><TR
 142 ><TD
 143 ><PRE
 144 CLASS="PROGRAMLISTING"
 145 >typedef CYG_WORD32 cyg_pci_device_id;</PRE
 146 ></TD
 147 ></TR
 148 ></TABLE
 149 ><P
 150 >This is comprised of the bus number, device number and functional
 151 unit numbers packed into a single word. The macro <TT
 152 CLASS="FUNCTION"
 153 >CYG_PCI_DEV_MAKE_ID()</TT
 154 >, in conjunction with the <TT
 155 CLASS="FUNCTION"
 156 >CYG_PCI_DEV_MAKE_DEVFN()</TT
 157 >
 158 macro, may be used to construct a device id from the bus, device and functional
 159 unit numbers. Similarly the macros <TT
 160 CLASS="FUNCTION"
 161 >CYG_PCI_DEV_GET_BUS()</TT
 162 >,
 163 <TT
 164 CLASS="FUNCTION"
 165 >CYG_PCI_DEV_GET_DEVFN()</TT
 166 >,
 167 <TT
 168 CLASS="FUNCTION"
 169 >CYG_PCI_DEV_GET_DEV()</TT
 170 >, and
 171 <TT
 172 CLASS="FUNCTION"
 173 >CYG_PCI_DEV_GET_FN()</TT
 174 > may be used to extract the
 175 constituent parts of a device id. It should not be necessary to use these
 176 macros under normal circumstances. The following code fragment demonstrates
 177 how these macros may be used:</P
 178 ><TABLE
 179 BORDER="5"
 180 BGCOLOR="#E0E0F0"
 181 WIDTH="70%"
 182 ><TR
 183 ><TD
 184 ><PRE
 185 CLASS="PROGRAMLISTING"
 186 >  // Create a packed representation of device 1, function 0
 187   cyg_uint8 devfn = CYG_PCI_DEV_MAKE_DEVFN(1,0);
 188
 189   // Create a packed devid for that device on bus 2
 190   cyg_pci_device_id devid = CYG_PCI_DEV_MAKE_ID(2, devfn);
 191
 192   diag_printf("bus %d, dev %d, func %d\n",
 193               CYG_PCI_DEV_GET_BUS(devid),
 194               CYG_PCI_DEV_GET_DEV(CYG_PCI_DEV_GET_DEVFN(devid)),
 195               CYG_PCI_DEV_GET_FN(CYG_PCI_DEV_GET_DEVFN(devid));</PRE
 196 ></TD
 197 ></TR
 198 ></TABLE
 199 ><TABLE
 200 BORDER="5"
 201 BGCOLOR="#E0E0F0"
 202 WIDTH="70%"
 203 ><TR
 204 ><TD
 205 ><PRE
 206 CLASS="PROGRAMLISTING"
 207 >typedef struct cyg_pci_device;</PRE
 208 ></TD
 209 ></TR
 210 ></TABLE
 211 ><P
 212 >This structure is used to contain data read from a PCI device's
 213 configuration header by <TT
 214 CLASS="FUNCTION"
 215 >cyg_pci_get_device_info()</TT
 216 >.
 217 It is also used to record the resource allocations made to the device.</P
 218 ><TABLE
 219 BORDER="5"
 220 BGCOLOR="#E0E0F0"
 221 WIDTH="70%"
 222 ><TR
 223 ><TD
 224 ><PRE
 225 CLASS="PROGRAMLISTING"
 226 >typedef CYG_WORD64 CYG_PCI_ADDRESS64;
 227 typedef CYG_WORD32 CYG_PCI_ADDRESS32;</PRE
 228 ></TD
 229 ></TR
 230 ></TABLE
 231 ><P
 232 >Pointers in the PCI address space are 32 bit (IO space) or
 233 32/64 bit (memory space). In most platform and device configurations
 234 all of PCI memory will be linearly addressable using only 32 bit
 235 pointers as read from <TT
 236 CLASS="VARNAME"
 237 >base_map[]</TT
 238 >.</P
 239 ><P
 240 >The 64 bit type is used to allow handling 64 bit devices in
 241 the future, should it be necessary, without changing the library's
 242 API.</P
 243 ></DIV
 244 ><DIV
 245 CLASS="SECT2"
 246 ><H2
 247 CLASS="SECT2"
 248 ><A
 249 NAME="AEN12828">Functions</H2
 250 ><TABLE
 251 BORDER="5"
 252 BGCOLOR="#E0E0F0"
 253 WIDTH="70%"
 254 ><TR
 255 ><TD
 256 ><PRE
 257 CLASS="PROGRAMLISTING"
 258 >void cyg_pci_init(void);</PRE
 259 ></TD
 260 ></TR
 261 ></TABLE
 262 ><P
 263 >Initialize the PCI library and establish contact with the
 264 hardware. This function is idempotent and can be called either by
 265 all drivers in the system, or just from an application initialization
 266 function.</P
 267 ><TABLE
 268 BORDER="5"
 269 BGCOLOR="#E0E0F0"
 270 WIDTH="70%"
 271 ><TR
 272 ><TD
 273 ><PRE
 274 CLASS="PROGRAMLISTING"
 275 >cyg_bool cyg_pci_find_device( cyg_uint16 vendor,
 276                               cyg_uint16 device,
 277                               cyg_pci_device_id *devid );</PRE
 278 ></TD
 279 ></TR
 280 ></TABLE
 281 ><P
 282 >Searches the PCI bus configuration space for a device with
 283 the given <TT
 284 CLASS="PARAMETER"
 285 ><I
 286 >vendor</I
 287 ></TT
 288 > and <TT
 289 CLASS="PARAMETER"
 290 ><I
 291 >device</I
 292 ></TT
 293 >
 294 ids. The search starts at the device pointed to by <TT
 295 CLASS="PARAMETER"
 296 ><I
 297 >devid</I
 298 ></TT
 299 >,
 300 or at the first slot if it contains <TT
 301 CLASS="LITERAL"
 302 >CYG_PCI_NULL_DEVID</TT
 303 >.
 304 <TT
 305 CLASS="PARAMETER"
 306 ><I
 307 >*devid</I
 308 ></TT
 309 > will be updated with the ID of the next device
 310 found. Returns <TT
 311 CLASS="CONSTANT"
 312 >true</TT
 313 > if one is found and <TT
 314 CLASS="CONSTANT"
 315 >false</TT
 316 > if not.</P
 317 ><TABLE
 318 BORDER="5"
 319 BGCOLOR="#E0E0F0"
 320 WIDTH="70%"
 321 ><TR
 322 ><TD
 323 ><PRE
 324 CLASS="PROGRAMLISTING"
 325 >cyg_bool cyg_pci_find_class( cyg_uint32 dev_class,
 326                              cyg_pci_device_id *devid );</PRE
 327 ></TD
 328 ></TR
 329 ></TABLE
 330 ><P
 331 >Searches the PCI bus configuration space for a device with
 332 the given <TT
 333 CLASS="PARAMETER"
 334 ><I
 335 >dev_class</I
 336 ></TT
 337 > class code.  The search starts at the
 338 device pointed to by <TT
 339 CLASS="PARAMETER"
 340 ><I
 341 >devid</I
 342 ></TT
 343 >, or at the first slot if it
 344 contains <TT
 345 CLASS="LITERAL"
 346 >CYG_PCI_NULL_DEVID</TT
 347 >.</P
 348 ><P
 349 ><TT
 350 CLASS="PARAMETER"
 351 ><I
 352 >*devid</I
 353 ></TT
 354 > will be updated with the ID of the next
 355 device found. Returns <TT
 356 CLASS="CONSTANT"
 357 >true</TT
 358 > if one is found and
 359 <TT
 360 CLASS="CONSTANT"
 361 >false</TT
 362 > if not.</P
 363 ><TABLE
 364 BORDER="5"
 365 BGCOLOR="#E0E0F0"
 366 WIDTH="70%"
 367 ><TR
 368 ><TD
 369 ><PRE
 370 CLASS="PROGRAMLISTING"
 371 >cyg_bool cyg_pci_find_next( cyg_pci_device_id cur_devid,
 372                             cyg_pci_device_id *next_devid );</PRE
 373 ></TD
 374 ></TR
 375 ></TABLE
 376 ><P
 377 >Searches the PCI configuration space for the next valid device
 378 after <TT
 379 CLASS="PARAMETER"
 380 ><I
 381 >cur_devid</I
 382 ></TT
 383 >. If <TT
 384 CLASS="PARAMETER"
 385 ><I
 386 >cur_devid</I
 387 ></TT
 388 >
 389 is given the value <TT
 390 CLASS="LITERAL"
 391 >CYG_PCI_NULL_DEVID</TT
 392 >, then the search starts
 393 at the first slot. It is permitted for <TT
 394 CLASS="PARAMETER"
 395 ><I
 396 >next_devid</I
 397 ></TT
 398 > to
 399 point to <TT
 400 CLASS="PARAMETER"
 401 ><I
 402 >cur_devid</I
 403 ></TT
 404 >.  Returns <TT
 405 CLASS="CONSTANT"
 406 >true</TT
 407 >
 408 if another device is found and <TT
 409 CLASS="CONSTANT"
 410 >false</TT
 411 > if not.</P
 412 ><TABLE
 413 BORDER="5"
 414 BGCOLOR="#E0E0F0"
 415 WIDTH="70%"
 416 ><TR
 417 ><TD
 418 ><PRE
 419 CLASS="PROGRAMLISTING"
 420 >cyg_bool cyg_pci_find_matching( cyg_pci_match_func *matchp,
 421                                 void * match_callback_data,
 422                                 cyg_pci_device_id *devid );</PRE
 423 ></TD
 424 ></TR
 425 ></TABLE
 426 ><P
 427 >Searches the PCI bus configuration space for a device whose properties
 428 match those required by the caller supplied <TT
 429 CLASS="PARAMETER"
 430 ><I
 431 >cyg_pci_match_func</I
 432 ></TT
 433 >.
 434 The search starts at the device pointed to by <TT
 435 CLASS="PARAMETER"
 436 ><I
 437 >devid</I
 438 ></TT
 439 >, or
 440 at the first slot if it contains <TT
 441 CLASS="CONSTANT"
 442 >CYG_PCI_NULL_DEVID</TT
 443 >. The
 444 <TT
 445 CLASS="PARAMETER"
 446 ><I
 447 >devid</I
 448 ></TT
 449 > will be updated with the ID of the next device found.
 450 This function returns <TT
 451 CLASS="CONSTANT"
 452 >true</TT
 453 > if a matching device is found
 454 and <TT
 455 CLASS="CONSTANT"
 456 >false</TT
 457 > if not.</P
 458 ><P
 459 >The match_func has a type declared as:</P
 460 ><TABLE
 461 BORDER="5"
 462 BGCOLOR="#E0E0F0"
 463 WIDTH="70%"
 464 ><TR
 465 ><TD
 466 ><PRE
 467 CLASS="PROGRAMLISTING"
 468 >typedef cyg_bool (cyg_pci_match_func)( cyg_uint16 vendor,
 469                                        cyg_uint16 device,
 470                                        cyg_uint32 class,
 471                                        void *     user_data);</PRE
 472 ></TD
 473 ></TR
 474 ></TABLE
 475 ><P
 476 >The <TT
 477 CLASS="PARAMETER"
 478 ><I
 479 >vendor</I
 480 ></TT
 481 >, <TT
 482 CLASS="PARAMETER"
 483 ><I
 484 >device</I
 485 ></TT
 486 >, and
 487 <TT
 488 CLASS="PARAMETER"
 489 ><I
 490 >class</I
 491 ></TT
 492 > are from the device configuration space. The
 493 <TT
 494 CLASS="PARAMETER"
 495 ><I
 496 >user_data</I
 497 ></TT
 498 > is the callback data passed to <TT
 499 CLASS="FUNCTION"
 500 >cyg_pci_find_matching</TT
 501 >.</P
 502 ><TABLE
 503 BORDER="5"
 504 BGCOLOR="#E0E0F0"
 505 WIDTH="70%"
 506 ><TR
 507 ><TD
 508 ><PRE
 509 CLASS="PROGRAMLISTING"
 510 >void cyg_pci_get_device_info ( cyg_pci_device_id devid,
 511                                cyg_pci_device *dev_info );</PRE
 512 ></TD
 513 ></TR
 514 ></TABLE
 515 ><P
 516 >This function gets the PCI configuration information for the
 517 device indicated in <TT
 518 CLASS="PARAMETER"
 519 ><I
 520 >devid</I
 521 ></TT
 522 >. The common fields of the
 523 <SPAN
 524 CLASS="STRUCTNAME"
 525 >cyg_pci_device</SPAN
 526 > structure, and the appropriate fields
 527 of the relevant header union member are filled in from the device's
 528 configuration space.
 529 If the device has not been enabled, then this function will also fetch
 530 the size and type information from the base address registers and
 531 place it in the <TT
 532 CLASS="VARNAME"
 533 >base_size[]</TT
 534 > array.</P
 535 ><TABLE
 536 BORDER="5"
 537 BGCOLOR="#E0E0F0"
 538 WIDTH="70%"
 539 ><TR
 540 ><TD
 541 ><PRE
 542 CLASS="PROGRAMLISTING"
 543 >void cyg_pci_set_device_info ( cyg_pci_device_id devid,
 544                                cyg_pci_device *dev_info );</PRE
 545 ></TD
 546 ></TR
 547 ></TABLE
 548 ><P
 549 >This function sets the PCI configuration information for the
 550 device indicated in <TT
 551 CLASS="PARAMETER"
 552 ><I
 553 >devid</I
 554 ></TT
 555 >. Only the configuration space
 556 registers that are writable are actually written. Once all the fields have
 557 been written, the device info will be read back into <TT
 558 CLASS="PARAMETER"
 559 ><I
 560 >*dev_info</I
 561 ></TT
 562 >, so that it reflects the true state of the hardware.</P
 563 ><TABLE
 564 BORDER="5"
 565 BGCOLOR="#E0E0F0"
 566 WIDTH="70%"
 567 ><TR
 568 ><TD
 569 ><PRE
 570 CLASS="PROGRAMLISTING"
 571 >void cyg_pci_read_config_uint8(  cyg_pci_device_id devid,
 572                                  cyg_uint8 offset, cyg_uint8 *val );
 573 void cyg_pci_read_config_uint16( cyg_pci_device_id devid,
 574                                  cyg_uint8 offset, cyg_uint16 *val );
 575 void cyg_pci_read_config_uint32( cyg_pci_device_id devid,
 576                                  cyg_uint8 offset, cyg_uint32 *val );</PRE
 577 ></TD
 578 ></TR
 579 ></TABLE
 580 ><P
 581 >These functions read registers of the appropriate size from
 582 the configuration space of the given device. They should mainly
 583 be used to access registers that are device specific. General PCI
 584 registers are best accessed through <TT
 585 CLASS="FUNCTION"
 586 >cyg_pci_get_device_info()</TT
 587 >.</P
 588 ><TABLE
 589 BORDER="5"
 590 BGCOLOR="#E0E0F0"
 591 WIDTH="70%"
 592 ><TR
 593 ><TD
 594 ><PRE
 595 CLASS="PROGRAMLISTING"
 596 >void cyg_pci_write_config_uint8(  cyg_pci_device_id devid,
 597                                   cyg_uint8 offset, cyg_uint8 val );
 598 void cyg_pci_write_config_uint16( cyg_pci_device_id devid,
 599                                   cyg_uint8 offset, cyg_uint16 val );
 600 void cyg_pci_write_config_uint32( cyg_pci_device_id devid,
 601                                   cyg_uint8 offset, cyg_uint32 val );</PRE
 602 ></TD
 603 ></TR
 604 ></TABLE
 605 ><P
 606 >These functions write registers of the appropriate size to
 607 the configuration space of the given device. They should mainly
 608 be used to access registers that are device specific. General PCI
 609 registers are best accessed through <TT
 610 CLASS="FUNCTION"
 611 >cyg_pci_get_device_info()</TT
 612 >. Writing the general registers this way may render the contents of
 613 a <SPAN
 614 CLASS="STRUCTNAME"
 615 >cyg_pci_device</SPAN
 616 > structure invalid.</P
 617 ></DIV
 618 ><DIV
 619 CLASS="SECT2"
 620 ><H2
 621 CLASS="SECT2"
 622 ><A
 623 NAME="AEN12891">Resource allocation</H2
 624 ><P
 625 >These routines allocate memory and I/O space to PCI devices.</P
 626 ><TABLE
 627 BORDER="5"
 628 BGCOLOR="#E0E0F0"
 629 WIDTH="70%"
 630 ><TR
 631 ><TD
 632 ><PRE
 633 CLASS="PROGRAMLISTING"
 634 >cyg_bool cyg_pci_configure_device( cyg_pci_device *dev_info )</PRE
 635 ></TD
 636 ></TR
 637 ></TABLE
 638 ><P
 639 >Allocate memory and IO space to all base address registers
 640 using the current memory and IO base addresses in the library. The
 641 allocated base addresses, translated into directly usable values,
 642 will be put into the matching <TT
 643 CLASS="VARNAME"
 644 >base_map[]</TT
 645 > entries
 646 in <TT
 647 CLASS="PARAMETER"
 648 ><I
 649 >*dev_info</I
 650 ></TT
 651 >. If <TT
 652 CLASS="PARAMETER"
 653 ><I
 654 >*dev_info</I
 655 ></TT
 656 > does
 657 not contain valid <TT
 658 CLASS="VARNAME"
 659 >base_size[]</TT
 660 > entries, then the result is
 661 <TT
 662 CLASS="CONSTANT"
 663 >false</TT
 664 >. This function will also call <TT
 665 CLASS="FUNCTION"
 666 >cyg_pci_translate_interrupt()</TT
 667 > to put the interrupt vector into the
 668 HAL vector entry.</P
 669 ><TABLE
 670 BORDER="5"
 671 BGCOLOR="#E0E0F0"
 672 WIDTH="70%"
 673 ><TR
 674 ><TD
 675 ><PRE
 676 CLASS="PROGRAMLISTING"
 677 >cyg_bool cyg_pci_configure_bus( cyg_uint8 bus, cyg_uint8 *next_bus )</PRE
 678 ></TD
 679 ></TR
 680 ></TABLE
 681 ><P
 682 >Allocate memory and IO space to all base address registers on all devices
 683 on the given bus and all subordinate busses. If a PCI-PCI bridge is found on
 684 <TT
 685 CLASS="PARAMETER"
 686 ><I
 687 >bus</I
 688 ></TT
 689 >, this function will call itself recursively in order
 690 to configure the bus on the other side of the bridge. Because of the nature of
 691 bridge devices, all devices on the secondary side of a bridge must be allocated
 692 memory and IO space before the memory and IO windows on the bridge device can be
 693 properly configured. The <TT
 694 CLASS="PARAMETER"
 695 ><I
 696 >next_bus</I
 697 ></TT
 698 > argument points to the
 699 bus number to assign to the next subordinate bus found. The number will be
 700 incremented as new busses are discovered. If successful, <TT
 701 CLASS="CONSTANT"
 702 >true</TT
 703 >
 704 is returned. Otherwise, <TT
 705 CLASS="CONSTANT"
 706 >false</TT
 707 > is returned.</P
 708 ><TABLE
 709 BORDER="5"
 710 BGCOLOR="#E0E0F0"
 711 WIDTH="70%"
 712 ><TR
 713 ><TD
 714 ><PRE
 715 CLASS="PROGRAMLISTING"
 716 >cyg_bool cyg_pci_translate_interrupt( cyg_pci_device *dev_info,
 717                                       CYG_ADDRWORD *vec );</PRE
 718 ></TD
 719 ></TR
 720 ></TABLE
 721 ><P
 722 >Translate the device's PCI interrupt (INTA#-INTD#)
 723 to the associated HAL vector. This may also depend on which slot
 724 the device occupies. If the device may generate interrupts, the
 725 translated vector number will be stored in <TT
 726 CLASS="PARAMETER"
 727 ><I
 728 >vec</I
 729 ></TT
 730 > and the
 731 result is <TT
 732 CLASS="CONSTANT"
 733 >true</TT
 734 >. Otherwise the result is <TT
 735 CLASS="CONSTANT"
 736 >false</TT
 737 >.</P
 738 ><TABLE
 739 BORDER="5"
 740 BGCOLOR="#E0E0F0"
 741 WIDTH="70%"
 742 ><TR
 743 ><TD
 744 ><PRE
 745 CLASS="PROGRAMLISTING"
 746 >cyg_bool cyg_pci_allocate_memory( cyg_pci_device *dev_info,
 747                                   cyg_uint32 bar,
 748                                   CYG_PCI_ADDRESS64 *base );
 749 cyg_bool cyg_pci_allocate_io( cyg_pci_device *dev_info,
 750                               cyg_uint32 bar,
 751                               CYG_PCI_ADDRESS32 *base );</PRE
 752 ></TD
 753 ></TR
 754 ></TABLE
 755 ><P
 756 >These routines allocate memory or I/O space to the base address
 757 register indicated by <TT
 758 CLASS="PARAMETER"
 759 ><I
 760 >bar</I
 761 ></TT
 762 >. The base address in
 763 <TT
 764 CLASS="PARAMETER"
 765 ><I
 766 >*base</I
 767 ></TT
 768 > will be correctly aligned and the address of the
 769 next free location will be written back into it if the allocation succeeds. If
 770 the base address register is of the wrong type for this allocation, or
 771 <TT
 772 CLASS="PARAMETER"
 773 ><I
 774 >dev_info</I
 775 ></TT
 776 > does not contain valid <TT
 777 CLASS="VARNAME"
 778 >base_size[]</TT
 779 > entries, the result is <TT
 780 CLASS="CONSTANT"
 781 >false</TT
 782 >. These functions
 783 allow a device driver to set up its own mappings if it wants. Most devices
 784 should probably use <TT
 785 CLASS="FUNCTION"
 786 >cyg_pci_configure_device()</TT
 787 >.</P
 788 ><TABLE
 789 BORDER="5"
 790 BGCOLOR="#E0E0F0"
 791 WIDTH="70%"
 792 ><TR
 793 ><TD
 794 ><PRE
 795 CLASS="PROGRAMLISTING"
 796 >void cyg_pci_set_memory_base( CYG_PCI_ADDRESS64 base );
 797 void cyg_pci_set_io_base( CYG_PCI_ADDRESS32 base );</PRE
 798 ></TD
 799 ></TR
 800 ></TABLE
 801 ><P
 802 >These routines set the base addresses for memory and I/O mappings
 803 to be used by the memory allocation routines. Normally these base
 804 addresses will be set to default values based on the platform. These
 805 routines allow these to be changed by application code if necessary.</P
 806 ></DIV
 807 ><DIV
 808 CLASS="SECT2"
 809 ><H2
 810 CLASS="SECT2"
 811 ><A
 812 NAME="AEN12923">PCI Library Hardware API</H2
 813 ><P
 814 >This API is used by the PCI library to access the PCI bus
 815 configuration space. Although it should not normally be necessary,
 816 this API may also be used by device driver or application code to
 817 perform PCI bus operations not supported by the PCI library.</P
 818 ><TABLE
 819 BORDER="5"
 820 BGCOLOR="#E0E0F0"
 821 WIDTH="70%"
 822 ><TR
 823 ><TD
 824 ><PRE
 825 CLASS="PROGRAMLISTING"
 826 >void cyg_pcihw_init(void);</PRE
 827 ></TD
 828 ></TR
 829 ></TABLE
 830 ><P
 831 >Initialize the PCI hardware so that the configuration space
 832 may be accessed.</P
 833 ><TABLE
 834 BORDER="5"
 835 BGCOLOR="#E0E0F0"
 836 WIDTH="70%"
 837 ><TR
 838 ><TD
 839 ><PRE
 840 CLASS="PROGRAMLISTING"
 841 >void cyg_pcihw_read_config_uint8(  cyg_uint8 bus,
 842                cyg_uint8 devfn, cyg_uint8 offset, cyg_uint8 *val);
 843 void cyg_pcihw_read_config_uint16( cyg_uint8 bus,
 844                cyg_uint8 devfn, cyg_uint8 offset, cyg_uint16 *val);
 845 void cyg_pcihw_read_config_uint32( cyg_uint8 bus,
 846                cyg_uint8 devfn, cyg_uint8 offset, cyg_uint32 *val);</PRE
 847 ></TD
 848 ></TR
 849 ></TABLE
 850 ><P
 851 >These functions read a register of the appropriate size from
 852 the PCI configuration space at an address composed from the <TT
 853 CLASS="PARAMETER"
 854 ><I
 855 >bus</I
 856 ></TT
 857 >, <TT
 858 CLASS="PARAMETER"
 859 ><I
 860 >devfn</I
 861 ></TT
 862 > and <TT
 863 CLASS="PARAMETER"
 864 ><I
 865 >offset</I
 866 ></TT
 867 >
 868 arguments.</P
 869 ><TABLE
 870 BORDER="5"
 871 BGCOLOR="#E0E0F0"
 872 WIDTH="70%"
 873 ><TR
 874 ><TD
 875 ><PRE
 876 CLASS="PROGRAMLISTING"
 877 >void cyg_pcihw_write_config_uint8(  cyg_uint8 bus,
 878                 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint8 val);
 879 void cyg_pcihw_write_config_uint16( cyg_uint8 bus,
 880                 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint16 val);
 881 void cyg_pcihw_write_config_uint32( cyg_uint8 bus,
 882                 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint32 val);</PRE
 883 ></TD
 884 ></TR
 885 ></TABLE
 886 ><P
 887 >These functions write a register of the appropriate size to
 888 the PCI configuration space at an address composed from the
 889 <TT
 890 CLASS="PARAMETER"
 891 ><I
 892 >bus</I
 893 ></TT
 894 >, <TT
 895 CLASS="PARAMETER"
 896 ><I
 897 >devfn</I
 898 ></TT
 899 > and
 900 <TT
 901 CLASS="PARAMETER"
 902 ><I
 903 >offset</I
 904 ></TT
 905 > arguments.</P
 906 ><TABLE
 907 BORDER="5"
 908 BGCOLOR="#E0E0F0"
 909 WIDTH="70%"
 910 ><TR
 911 ><TD
 912 ><PRE
 913 CLASS="PROGRAMLISTING"
 914 >cyg_bool cyg_pcihw_translate_interrupt( cyg_uint8 bus,
 915                                         cyg_uint8 devfn,
 916                                         CYG_ADDRWORD *vec);</PRE
 917 ></TD
 918 ></TR
 919 ></TABLE
 920 ><P
 921 >This function interrogates the device and determines which
 922 HAL interrupt vector it is connected to.</P
 923 ></DIV
 924 ><DIV
 925 CLASS="SECT2"
 926 ><H2
 927 CLASS="SECT2"
 928 ><A
 929 NAME="AEN12940">HAL PCI support</H2
 930 ><P
 931 >HAL support consists of a set of C macros that provide the
 932 implementation of the low level PCI API.</P
 933 ><TABLE
 934 BORDER="5"
 935 BGCOLOR="#E0E0F0"
 936 WIDTH="70%"
 937 ><TR
 938 ><TD
 939 ><PRE
 940 CLASS="PROGRAMLISTING"
 941 >HAL_PCI_INIT()</PRE
 942 ></TD
 943 ></TR
 944 ></TABLE
 945 ><P
 946 >Initialize the PCI bus.</P
 947 ><TABLE
 948 BORDER="5"
 949 BGCOLOR="#E0E0F0"
 950 WIDTH="70%"
 951 ><TR
 952 ><TD
 953 ><PRE
 954 CLASS="PROGRAMLISTING"
 955 >HAL_PCI_READ_UINT8( bus, devfn, offset, val )
 956 HAL_PCI_READ_UINT16( bus, devfn, offset, val )
 957 HAL_PCI_READ_UINT32( bus, devfn, offset, val )</PRE
 958 ></TD
 959 ></TR
 960 ></TABLE
 961 ><P
 962 >Read a value from the PCI configuration space of the appropriate
 963 size at an address composed from the <TT
 964 CLASS="PARAMETER"
 965 ><I
 966 >bus</I
 967 ></TT
 968 >, <TT
 969 CLASS="PARAMETER"
 970 ><I
 971 >devfn</I
 972 ></TT
 973 > and <TT
 974 CLASS="PARAMETER"
 975 ><I
 976 >offset</I
 977 ></TT
 978 >.</P
 979 ><TABLE
 980 BORDER="5"
 981 BGCOLOR="#E0E0F0"
 982 WIDTH="70%"
 983 ><TR
 984 ><TD
 985 ><PRE
 986 CLASS="PROGRAMLISTING"
 987 >HAL_PCI_WRITE_UINT8( bus, devfn, offset, val )
 988 HAL_PCI_WRITE_UINT16( bus, devfn, offset, val )
 989 HAL_PCI_WRITE_UINT32( bus, devfn, offset, val )</PRE
 990 ></TD
 991 ></TR
 992 ></TABLE
 993 ><P
 994 >Write a value to the PCI configuration space of the appropriate
 995 size at an address composed from the <TT
 996 CLASS="PARAMETER"
 997 ><I
 998 >bus</I
 999 ></TT
1000 >, <TT
1001 CLASS="PARAMETER"
1002 ><I
1003 >devfn</I
1004 ></TT
1005 > and <TT
1006 CLASS="PARAMETER"
1007 ><I
1008 >offset</I
1009 ></TT
1010 >.</P
1011 ><TABLE
1012 BORDER="5"
1013 BGCOLOR="#E0E0F0"
1014 WIDTH="70%"
1015 ><TR
1016 ><TD
1017 ><PRE
1018 CLASS="PROGRAMLISTING"
1019 >HAL_PCI_TRANSLATE_INTERRUPT( bus, devfn, *vec, valid )</PRE
1020 ></TD
1021 ></TR
1022 ></TABLE
1023 ><P
1024 >Translate the device's interrupt line into a HAL
1025 interrupt vector.</P
1026 ><TABLE
1027 BORDER="5"
1028 BGCOLOR="#E0E0F0"
1029 WIDTH="70%"
1030 ><TR
1031 ><TD
1032 ><PRE
1033 CLASS="PROGRAMLISTING"
1034 >HAL_PCI_ALLOC_BASE_MEMORY
1035 HAL_PCI_ALLOC_BASE_IO</PRE
1036 ></TD
1037 ></TR
1038 ></TABLE
1039 ><P
1040 >These macros define the default base addresses used to initialize
1041 the memory and I/O allocation pointers.</P
1042 ><TABLE
1043 BORDER="5"
1044 BGCOLOR="#E0E0F0"
1045 WIDTH="70%"
1046 ><TR
1047 ><TD
1048 ><PRE
1049 CLASS="PROGRAMLISTING"
1050 >HAL_PCI_PHYSICAL_MEMORY_BASE
1051 HAL_PCI_PHYSICAL_IO_BASE</PRE
1052 ></TD
1053 ></TR
1054 ></TABLE
1055 ><P
1056 >PCI memory and IO range do not always correspond directly
1057 to physical memory or IO addresses. Frequently the PCI address spaces
1058 are windowed into the processor's address range at some
1059 offset. These macros define offsets to be added to the PCI base
1060 addresses to translate PCI bus addresses into physical memory addresses
1061 that can be used to access the allocated memory or IO space.</P
1062 ><DIV
1063 CLASS="NOTE"
1064 ><BLOCKQUOTE
1065 CLASS="NOTE"
1066 ><P
1067 ><B
1068 >Note: </B
1069 >The chunk of PCI memory space directly addressable though
1070 the window by the CPU may be smaller than the amount of PCI memory
1071 actually provided. In that case drivers will have to access PCI
1072 memory space in segments. Doing this will be platform specific and
1073 is currently beyond the scope of the HAL.</P
1074 ></BLOCKQUOTE
1075 ></DIV
1076 ><TABLE
1077 BORDER="5"
1078 BGCOLOR="#E0E0F0"
1079 WIDTH="70%"
1080 ><TR
1081 ><TD
1082 ><PRE
1083 CLASS="PROGRAMLISTING"
1084 >HAL_PCI_IGNORE_DEVICE( bus, dev, fn )</PRE
1085 ></TD
1086 ></TR
1087 ></TABLE
1088 ><P
1089 >This macro, if defined, may be used to limit the devices which are
1090 found by the bus scanning functions. This is sometimes necessary for
1091 devices which need special handling. If this macro evaluates to <TT
1092 CLASS="CONSTANT"
1093 >true</TT
1094 >, the given device will not be found by <TT
1095 CLASS="FUNCTION"
1096 >cyg_pci_find_next</TT
1097 > or other bus scanning functions.</P
1098 ></DIV
1099 ></DIV
1100 ><DIV
1101 CLASS="NAVFOOTER"
1102 ><HR
1103 ALIGN="LEFT"
1104 WIDTH="100%"><TABLE
1105 SUMMARY="Footer navigation table"
1106 WIDTH="100%"
1107 BORDER="0"
1108 CELLPADDING="0"
1109 CELLSPACING="0"
1110 ><TR
1111 ><TD
1112 WIDTH="33%"
1113 ALIGN="left"
1114 VALIGN="top"
1115 ><A
1116 HREF="ecos-pci-library.html"
1117 ACCESSKEY="P"
1118 >Prev</A
1119 ></TD
1120 ><TD
1121 WIDTH="34%"
1122 ALIGN="center"
1123 VALIGN="top"
1124 ><A
1125 HREF="ecos-ref.html"
1126 ACCESSKEY="H"
1127 >Home</A
1128 ></TD
1129 ><TD
1130 WIDTH="33%"
1131 ALIGN="right"
1132 VALIGN="top"
1133 ><A
1134 HREF="posix-compatibility.html"
1135 ACCESSKEY="N"
1136 >Next</A
1137 ></TD
1138 ></TR
1139 ><TR
1140 ><TD
1141 WIDTH="33%"
1142 ALIGN="left"
1143 VALIGN="top"
1144 >The eCos PCI Library</TD
1145 ><TD
1146 WIDTH="34%"
1147 ALIGN="center"
1148 VALIGN="top"
1149 ><A
1150 HREF="ecos-pci-library.html"
1151 ACCESSKEY="U"
1152 >Up</A
1153 ></TD
1154 ><TD
1155 WIDTH="33%"
1156 ALIGN="right"
1157 VALIGN="top"
1158 >eCos POSIX compatibility layer</TD
1159 ></TR
1160 ></TABLE
1161 ></DIV
1162 ></BODY
1163 ></HTML
1164 >