freebsd-dev/sys/mips/beri/fdt_ic_if.m

267 lines
7.6 KiB
Mathematica
Raw Normal View History

#-
# Copyright (c) 2013 SRI International
# Copyright (c) 1998-2004 Doug Rabson
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
#
# $FreeBSD$
#
#include <sys/types.h>
#include <sys/systm.h>
#include <sys/bus.h>
/**
* @defgroup FST_IC fdt_ic - KObj methods for interrupt controllers
* @brief A set of methods required device drivers that are interrupt
* controllers. Derived from sys/kern/bus_if.m.
* @{
*/
INTERFACE fdt_ic;
/**
* @brief Allocate an interrupt resource
*
* This method is called by child devices of an interrupt controller to
* allocate an interrup. The meaning of the resource-ID field varies
* from bus to bus and is opaque to the interrupt controller. If a
* resource was allocated and the caller did not use the RF_ACTIVE
* to specify that it should be activated immediately, the caller is
* responsible for calling FDT_IC_ACTIVATE_INTR() when it actually uses
* the interupt.
*
* @param _dev the interrupt-parent device of @p _child
* @param _child the device which is requesting an allocation
* @param _rid a pointer to the resource identifier
* @param _irq interrupt source to allocate
* @param _flags any extra flags to control the resource
* allocation - see @c RF_XXX flags in
* <sys/rman.h> for details
*
* @returns the interrupt which was allocated or @c NULL if no
* resource could be allocated
*/
METHOD struct resource * alloc_intr {
device_t _dev;
device_t _child;
int *_rid;
u_long _irq;
u_int _flags;
};
/**
* @brief Activate an interrupt
*
* Activate an interrupt previously allocated with FDT_IC_ALLOC_INTR().
*
* @param _dev the parent device of @p _child
* @param _r interrupt to activate
*/
METHOD int activate_intr {
device_t _dev;
struct resource *_r;
};
/**
* @brief Deactivate an interrupt
*
* Deactivate a resource previously allocated with FDT_IC_ALLOC_INTR().
*
* @param _dev the parent device of @p _child
* @param _r the interrupt to deactivate
*/
METHOD int deactivate_intr {
device_t _dev;
struct resource *_r;
};
/**
* @brief Release an interrupt
*
* Free an interupt allocated by the FDT_IC_ALLOC_INTR.
*
* @param _dev the parent device of @p _child
* @param _r the resource to release
*/
METHOD int release_intr {
device_t _dev;
struct resource *_res;
};
/**
* @brief Install an interrupt handler
*
* This method is used to associate an interrupt handler function with
* an irq resource. When the interrupt triggers, the function @p _intr
* will be called with the value of @p _arg as its single
* argument. The value returned in @p *_cookiep is used to cancel the
* interrupt handler - the caller should save this value to use in a
* future call to FDT_IC_TEARDOWN_INTR().
*
* @param _dev the interrupt-parent device of @p _child
* @param _child the device which allocated the resource
* @param _irq the resource representing the interrupt
* @param _flags a set of bits from enum intr_type specifying
* the class of interrupt
* @param _intr the function to call when the interrupt
* triggers
* @param _arg a value to use as the single argument in calls
* to @p _intr
* @param _cookiep a pointer to a location to recieve a cookie
* value that may be used to remove the interrupt
* handler
*/
METHOD int setup_intr {
device_t _dev;
device_t _child;
struct resource *_irq;
int _flags;
driver_filter_t *_filter;
driver_intr_t *_intr;
void *_arg;
void **_cookiep;
};
/**
* @brief Uninstall an interrupt handler
*
* This method is used to disassociate an interrupt handler function
* with an irq resource. The value of @p _cookie must be the value
* returned from a previous call to FDT_IC_SETUP_INTR().
*
* @param _dev the interrupt-parent device of @p _child
* @param _child the device which allocated the resource
* @param _irq the resource representing the interrupt
* @param _cookie the cookie value returned when the interrupt
* was originally registered
*/
METHOD int teardown_intr {
device_t _dev;
device_t _child;
struct resource *_irq;
void *_cookie;
};
/**
* @brief Allow drivers to request that an interrupt be bound to a specific
* CPU.
*
* @param _dev the interrupt-parent device of @p _child
* @param _child the device which allocated the resource
* @param _irq the resource representing the interrupt
* @param _cpu the CPU to bind the interrupt to
*/
METHOD int bind_intr {
device_t _dev;
device_t _child;
struct resource *_irq;
int _cpu;
};
/**
* @brief Allow drivers to specify the trigger mode and polarity
* of the specified interrupt.
*
* @param _dev the interrupt-parent device
* @param _irq the interrupt number to modify
* @param _trig the trigger mode required
* @param _pol the interrupt polarity required
*/
METHOD int config_intr {
device_t _dev;
int _irq;
enum intr_trigger _trig;
enum intr_polarity _pol;
};
/**
* @brief Allow drivers to associate a description with an active
* interrupt handler.
*
* @param _dev the interrupt-parent device of @p _child
* @param _child the device which allocated the resource
* @param _irq the resource representing the interrupt
* @param _cookie the cookie value returned when the interrupt
* was originally registered
* @param _descr the description to associate with the interrupt
*/
METHOD int describe_intr {
device_t _dev;
device_t _child;
struct resource *_irq;
void *_cookie;
const char *_descr;
};
/**
* @brief Notify an ic that specified child's IRQ should be remapped.
*
* @param _dev the interrupt-parent device
* @param _child the child device
* @param _irq the irq number
*/
METHOD int remap_intr {
device_t _dev;
device_t _child;
u_int _irq;
};
/**
* @brief Enable an IPI source.
*
* @param _dev the interrupt controller
* @param _tid the thread ID (relative to the interrupt controller)
* to enable IPIs for
* @param _ipi_irq hardware IRQ to send IPIs to
*/
METHOD void setup_ipi {
device_t _dev;
u_int _tid;
u_int _irq;
};
/**
* @brief Send an IPI to the specified thread.
*
* @param _dev the interrupt controller
* @param _tid the thread ID (relative to the interrupt controller)
* to send IPIs to
*/
METHOD void send_ipi {
device_t _dev;
u_int _tid;
};
/**
* @brief Clear the IPI on the specfied thread. Only call with the
* local hardware thread or interrupts may be lost!
*
* @param _dev the interrupt controller
* @param _tid the thread ID (relative to the interrupt controller)
* to clear the IPI on
*/
METHOD void clear_ipi {
device_t _dev;
u_int _tid;
};