Difference between revisions of "XIO API"

From LinuxMIPS
Jump to: navigation, search
(separate XIO layer and XIO provider functionality; add bus_register)
Line 1: Line 1:
 
The following functions are provided by the '''[[XIO]]''' layer.
 
The following functions are provided by the '''[[XIO]]''' layer.
  
== API ==
+
== XIO layer functions for device drivers ==
=== xio_create_bus ===
 
<pre>struct xio_bus *xio_create_bus(void);</pre>
 
Creates and registers a new XIO bus. Caller is expected to fill the structure afterwards.
 
 
 
=== xio_destroy_bus ===
 
<pre>void xio_destroy_bus(struct xio_bus *bus);</pre>
 
Unregisters and frees a XIO bus, destroying all devices before doing so.
 
 
 
=== xio_create_device ===
 
<pre>struct xio_device *xio_create_device(struct xio_bus *bus);</pre>
 
Creates a new XIO device on a given bus. Caller is expected to fill the
 
structure afterwards and to call xio_probe_device then.
 
 
 
=== xio_destroy_device ===
 
<pre>void xio_destroy_device(struct xio_device *dev);</pre>
 
Frees a XIO device after calling remove.
 
 
 
=== xio_probe_device ===
 
<pre>int xio_probe_device(struct xio_device *dev);</pre>
 
Tries to find a driver for a given XIO device. Returns true when successful (i.e. a device driver was found and executed probe successfully).
 
 
 
 
=== xio_register_driver ===
 
=== xio_register_driver ===
 
<pre>int xio_register_driver(struct xio_driver *drv);</pre>
 
<pre>int xio_register_driver(struct xio_driver *drv);</pre>
Line 62: Line 41:
 
Disconnects a handler and deallocates an interrupt number.
 
Disconnects a handler and deallocates an interrupt number.
  
The following functions are defined in the XIO provider.
+
== XIO provider functions for device drivers ==
 +
=== xio_dma_to_xio ===
 +
<pre>int xio_dma_to_xio(struct xio_dev *master, struct xio_dev *slave, unsigned long size, unsigned long *xioaddr);</pre>
 +
Represents an area of XIO widget slave in the XIO address space of XIO widget master.
 +
 
 +
=== xio_dma_to_mem ===
 +
<pre>int xio_dma_to_mem(struct xio_dev *master, dma_addr_t physaddr, unsigned long size, unsigned long *xioaddr);</pre>
 +
Represents an area of system physical memory in the XIO address space of XIO widget master.
 +
 
 +
=== xio_irq_to_cpu ===
 +
<pre>int xio_irq_to_cpu(struct xio_dev *sender, unsigned int irq, unsigned long *xioaddr);</pre>
 +
Represents a CPU interrupt in the XIO address space of XIO widget sender.
 +
 
 +
== XIO layer functions for XIO provider ==
 +
=== xio_create_bus ===
 +
<pre>struct xio_bus *xio_create_bus(void);</pre>
 +
Creates a new XIO bus. Caller is expected to fill the structure afterwards and register it with xio_register_bus.
 +
 
 +
=== xio_destroy_bus ===
 +
<pre>void xio_destroy_bus(struct xio_bus *bus);</pre>
 +
Unregisters and frees a XIO bus, destroying all devices before doing so.
 +
 
 +
=== xio_register_bus ===
 +
<pre>void xio_register_bus(struct xio_bus *bus);</pre>
 +
Registers a XIO bus created with xio_create_bus.
 +
 
 +
=== xio_create_device ===
 +
<pre>struct xio_device *xio_create_device(struct xio_bus *bus);</pre>
 +
Creates a new XIO device on a given bus. Caller is expected to fill the
 +
structure afterwards and to call xio_probe_device then.
 +
 
 +
=== xio_destroy_device ===
 +
<pre>void xio_destroy_device(struct xio_device *dev);</pre>
 +
Frees a XIO device after calling remove.
 +
 
 +
=== xio_probe_device ===
 +
<pre>int xio_probe_device(struct xio_device *dev);</pre>
 +
Tries to find a driver for a given XIO device. Returns true when successful (i.e. a device driver was found and executed probe successfully).
  
 +
== XIO provider functions for XIO layer ==
 
=== xio_setup ===
 
=== xio_setup ===
 
<pre>char *xio_setup(char *str);</pre>
 
<pre>char *xio_setup(char *str);</pre>
Line 84: Line 101:
 
<pre>void xio_free_region_int(struct xio_dev *dev, unsigned long *physaddr);</pre>
 
<pre>void xio_free_region_int(struct xio_dev *dev, unsigned long *physaddr);</pre>
 
Frees a translation of a XIO widget area.
 
Frees a translation of a XIO widget area.
 
=== xio_dma_to_xio ===
 
<pre>int xio_dma_to_xio(struct xio_dev *master, struct xio_dev *slave, unsigned long size, unsigned long *xioaddr);</pre>
 
Represents an area of XIO widget slave in the XIO address space of XIO widget master.
 
 
=== xio_dma_to_mem ===
 
<pre>int xio_dma_to_mem(struct xio_dev *master, dma_addr_t physaddr, unsigned long size, unsigned long *xioaddr);</pre>
 
Represents an area of system physical memory in the XIO address space of XIO widget master.
 
 
=== xio_irq_to_cpu ===
 
<pre>int xio_irq_to_cpu(struct xio_dev *sender, unsigned int irq, unsigned long *xioaddr);</pre>
 
Represents a CPU interrupt in the XIO address space of XIO widget sender.
 
  
 
== XIO probing process ==
 
== XIO probing process ==
Line 103: Line 108:
 
# XIO layer init code calls xio_scan_from_busses()
 
# XIO layer init code calls xio_scan_from_busses()
 
# XIO provider calls xio_create_bus() for each found bus
 
# XIO provider calls xio_create_bus() for each found bus
 +
# XIO provider calls xio_register_bus()
 
# XIO provider calls xio_create_device() for each found bus XBOW
 
# XIO provider calls xio_create_device() for each found bus XBOW
 
# XIO provider fills the XBOW device structure
 
# XIO provider fills the XBOW device structure

Revision as of 19:25, 8 February 2005

The following functions are provided by the XIO layer.

XIO layer functions for device drivers

xio_register_driver

int xio_register_driver(struct xio_driver *drv);

Registers a new XIO device driver.

xio_unregister_driver

void xio_unregister_driver(struct xio_driver *drv);

Unregisters a XIO device driver.

xio_request_region

int xio_request_region(struct xio_dev *dev, unsigned long size, void **virt, char *name);

Maps a XIO widget area to virtual CPU space (probably doing ioremap() in the processs).

xio_free_region

void xio_free_region(struct xio_dev *dev, void *virt);

Unmaps a XIO widget area from virtual CPU space.

xio_request_flow

int xio_request_flow(struct xio_dev *dev, unsigned long offset,
                     unsigned long size, unsigned int credits,
		     unsigned int timer,
		     irqreturn_t (*handler)(int, void *, struct pt_regs *),
		     void *irq_priv, char *name);

Connects an interrupt handler to a XIO flow control resource. Known XIO implementations can handle only size=1 (single address). A number of flow control resources is very limited (usually to 2 per system) and they should be used primarily by graphics drivers.

xio_free_flow

void xio_free_flow(struct xio_dev *dev, unsigned long offset);

Disconnects an interrupt handler from a XIO flow control resource.

xio_request_irq

int xio_request_irq(struct xio_dev *dev,
		    irqreturn_t (*handler)(int, void *, struct pt_regs *),
		    void *irq_priv, char *name,
		    unsigned int *irqnum, unsigned long *xioaddr);

Allocates an interrupt number and derives a word that has to be written to XIO device interrupt target registers. Returns allocated interrupt number in *irqnum. Connects a given handler to that IRQ.

xio_free_irq

void xio_free_irq(struct xio_dev *dev, void irqnum);

Disconnects a handler and deallocates an interrupt number.

XIO provider functions for device drivers

xio_dma_to_xio

int xio_dma_to_xio(struct xio_dev *master, struct xio_dev *slave, unsigned long size, unsigned long *xioaddr);

Represents an area of XIO widget slave in the XIO address space of XIO widget master.

xio_dma_to_mem

int xio_dma_to_mem(struct xio_dev *master, dma_addr_t physaddr, unsigned long size, unsigned long *xioaddr);

Represents an area of system physical memory in the XIO address space of XIO widget master.

xio_irq_to_cpu

int xio_irq_to_cpu(struct xio_dev *sender, unsigned int irq, unsigned long *xioaddr);

Represents a CPU interrupt in the XIO address space of XIO widget sender.

XIO layer functions for XIO provider

xio_create_bus

struct xio_bus *xio_create_bus(void);

Creates a new XIO bus. Caller is expected to fill the structure afterwards and register it with xio_register_bus.

xio_destroy_bus

void xio_destroy_bus(struct xio_bus *bus);

Unregisters and frees a XIO bus, destroying all devices before doing so.

xio_register_bus

void xio_register_bus(struct xio_bus *bus);

Registers a XIO bus created with xio_create_bus.

xio_create_device

struct xio_device *xio_create_device(struct xio_bus *bus);

Creates a new XIO device on a given bus. Caller is expected to fill the structure afterwards and to call xio_probe_device then.

xio_destroy_device

void xio_destroy_device(struct xio_device *dev);

Frees a XIO device after calling remove.

xio_probe_device

int xio_probe_device(struct xio_device *dev);

Tries to find a driver for a given XIO device. Returns true when successful (i.e. a device driver was found and executed probe successfully).

XIO provider functions for XIO layer

xio_setup

char *xio_setup(char *str);

Used to pass command-line parameters to the XIO provider.

xio_scan_for_busses

void xio_scan_for_busses(void)

Asks provider to make a boot-time scan for XIO busses. The provider should register all found busses by xio_create_bus, create XBOWs for them and perform probing on these XBOWs. Devices should not be probed for.

xio_is_alias

int xio_is_alias(const struct xio_dev *dev, const struct xio_bus *bus);

Checks if an alias of dev is present on bus (not dev itself). Will be used by the probing code.

xio_request_region_int

int xio_request_region_int(struct xio_dev *dev, unsigned long size,
                           unsigned long *physaddr);

Requests a translation of a XIO widget area to CPU physical address.

xio_free_region_int

void xio_free_region_int(struct xio_dev *dev, unsigned long *physaddr);

Frees a translation of a XIO widget area.

XIO probing process

  1. kernel calls xio_setup()
  2. kernel calls XIO layer init code
  3. XIO layer init code calls xio_scan_from_busses()
  4. XIO provider calls xio_create_bus() for each found bus
  5. XIO provider calls xio_register_bus()
  6. XIO provider calls xio_create_device() for each found bus XBOW
  7. XIO provider fills the XBOW device structure
  8. XIO provider calls xio_probe_device() for the XBOW
  9. XIO layer calls xio_is_alias() for the XBOW and all known busses
  10. XIO provider checks for an alias
  11. if it is an alias, xio_probe_device() returns false
  12. XIO layer calls XBOW driver probe function
  13. XBOW driver scans the XBOW for widgets
  14. XBOW driver calls xio_create_device() for each found device
  15. XBOW driver fills the device structure
  16. XBOW driver calls xio_probe_device()
  17. XIO layer calls device driver probe function if there is such device

Status

At the moment the XIO API is under design.