legion/docs/readmes/README.libpiu

/*
 * Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */
#pragma ident   "@(#)README.libpiu      1.1     05/10/05 SMI"

                "piu" device howto
=======================================================

I. What is "piu" device?
------------------------
This device implements the PCI Express Interface Unit (PIU) to
allow an PCIE based I/O subsystem (PCIE end point device) to
be connected to the Niagara2 chip.


II. Where is libpiu?
--------------------
The source is in <ws>/devices/mem_bus/libpiu


III. How is libpiu implemented?
-------------------------------
It is implemented as a typical dev_type_t device module


        dev_type_t dev_type_piu={
                "piu",
                piu_parse(),
                piu_init(),
                piu_dump(),
                generic_device_non_cacheable(),
                piu_cpu_access(),
                DEV_MAGIC
        };

The device specific parser interface "piu_parse" is extended so
it's capable of parsing and loading an PCIE end point device.

The downbound transaction (N2 core->PIU->PCIE end device) is
handled by the the "piu_cpu_access" interface for

    * access to PCIE CSRs
    * read/write access to PCIE Cfg/IO, MEM32 and MEM64 space


The PCIE end device is implemented by with a new device type
which is derived from the dev_type_t and similar to the one
used in the "fire" device module:


        typedef struct pcie_dev_type  {
                char            *dev_type_namep;
                void            (*dev_init)();
                void            (*dev_parse)();
                void            (*dev_dump)();
                uint16_t        req_id;
                bool_t          (*dev_cfg_read)();
                bool_t          (*dev_cfg_write)();
                int             (*bar_test)();
                bool_t          (*dev_mem_read)();
                bool_t          (*dev_mem_write)();
                bool_t          (*dev_io_read)();
                bool_t          (*dev_io_write)();
                pcie_model_t    *pcie_modp;
                pcie_access_t   *pcie_accessp;
                struct pcie_dev_type *next;
        } pcie_dev_type_t;

where "pcie_access_t" is defined as below to handle the
upbound transaction (PCIE end device->PIU->N2 core) such
as the DMA read and write:

typedef struct pcie_access {
        bool_t  *pcie_dma_read();
        bool_t  *pcie_dma_write();
        bool_t  *pcie_msi_write();
        bool_t  *pcie_msg_assert_intx();
        bool_t  *pcie_msg_deassert_intx();
} pcie_access_t;


III. How do I configure the "piu" device
----------------------------------------
The config syntax for loading the "piu" device and an PCIE
end point device is:

        device "piu" <addr1> + <size1>, <addr2> + <size2>
        {
           pcie_device "dev_name" <pcie device properties>; // optional
        }

Example:
        load "bcm" device as an PCIE end point device:

        device "piu" 0x8800000000 + 8M, 0xC000000000 + 64G
        {
           pcie_device "bcm" 2 0 "/dev/bge";
        }