XIO API

From LinuxMIPS
Revision as of 18:15, 21 March 2005 by Skylark (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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_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. The implementation phase is expected to start around February 24, 2004. Current headers are available at: [[1]].