/*
 * 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";
	}