XIO API

From LinuxMIPS
Revision as of 19:25, 8 February 2005 by Skylark (talk | contribs) (separate XIO layer and XIO provider functionality; add bus_register)
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_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.