irq: formalize external zephyr interrupt API

The app-facing interface for configuring interrupts was never
formally defined, instead it was defined separately for each arch
in their respective arch-specific header files. Occasionally these
would go out of sync.

Now there is a single irq.h header which defines this interface.
To avoid runtime overhead, these map to _arch_* implementations of
each that must be defined in headers pulled in by arch/cpu.h.

Change-Id: I69afbeff31fd07f981b5b291f3c427296b00a4ef
Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>

1 files changed, 126 insertions, 0 deletions

diff --git a/include/irq.h b/include/irq.h
new file mode 100644
index 000000000..62e008553
--- /dev/null
+++ b/include/irq.h
@@ -0,0 +1,126 @@
+/*
+ * Copyright (c) 2015 Intel corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file
+ * @brief Public interface for configuring interrupts
+ */
+#ifndef _IRQ_H_
+#define _IRQ_H_
+
+/* Pull in the arch-specific implementations */
+#include <arch/cpu.h>
+
+/**
+ * Configure a static interrupt.
+ *
+ * All arguments must be computable by the compiler at build time; if this
+ * can't be done use irq_connect_dynamic() instead.
+ *
+ * @param irq_p IRQ line number
+ * @param priority_p Interrupt priority
+ * @param isr_p Interrupt service routine
+ * @param isr_param_p ISR parameter
+ * @param flags_p Arch-specific IRQ configuration flags
+ *
+ * @return The vector assigned to this interrupt
+ */
+#define IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p) \
+	_ARCH_IRQ_CONNECT(irq_p, priority_p, isr_p, isr_param_p, flags_p)
+
+/**
+ * Configure a dynamic interrupt.
+ *
+ * @param irq_p IRQ line number
+ * @param priority_p Interrupt priority
+ * @param isr_p Interrupt service routine
+ * @param isr_param_p ISR parameter
+ * @param flags_p Arch-specific IRQ configuration flags
+ *
+ * @return The vector assigned to this interrupt
+ */
+#define irq_connect_dynamic(irq_p, priority_p, isr_p, isr_param_p, flags_p) \
+	_arch_irq_connect_dynamic(irq_p, priority_p, isr_p, isr_param_p, \
+				  flags_p)
+
+
+/**
+ * @brief Disable all interrupts on the CPU (inline)
+ *
+ * This routine disables interrupts.  It can be called from either interrupt,
+ * task or fiber level.  This routine returns an architecture-dependent
+ * lock-out key representing the "interrupt disable state" prior to the call;
+ * this key can be passed to irq_unlock() to re-enable interrupts.
+ *
+ * The lock-out key should only be used as the argument to the irq_unlock()
+ * API.  It should never be used to manually re-enable interrupts or to inspect
+ * or manipulate the contents of the source register.
+ *
+ * This function can be called recursively: it will return a key to return the
+ * state of interrupt locking to the previous level.
+ *
+ * WARNINGS
+ * Invoking a kernel routine with interrupts locked may result in
+ * interrupts being re-enabled for an unspecified period of time.  If the
+ * called routine blocks, interrupts will be re-enabled while another
+ * thread executes, or while the system is idle.
+ *
+ * The "interrupt disable state" is an attribute of a thread.  Thus, if a
+ * fiber or task disables interrupts and subsequently invokes a kernel
+ * routine that causes the calling thread to block, the interrupt
+ * disable state will be restored when the thread is later rescheduled
+ * for execution.
+ *
+ * @return An architecture-dependent unsigned int lock-out key representing the
+ * "interrupt disable state" prior to the call.
+ *
+ */
+#define irq_lock() _arch_irq_lock()
+
+/**
+ *
+ * @brief Enable all interrupts on the CPU (inline)
+ *
+ * This routine re-enables interrupts on the CPU.  The @a key parameter
+ * is an architecture-dependent lock-out key that is returned by a previous
+ * invocation of irq_lock().
+ *
+ * This routine can be called from either interrupt, task or fiber level
+ *
+ * @param key architecture-dependent lock-out key
+ *
+ * @return N/A
+ */
+#define irq_unlock(key) _arch_irq_unlock(key)
+
+/**
+ * @brief Enable a specific IRQ
+ *
+ * @param irq IRQ line
+ * @return N/A
+ */
+#define irq_enable(irq) _arch_irq_enable(irq)
+
+/**
+ * @brief Disable a specific IRQ
+ *
+ * @param irq IRQ line
+ * @return N/A
+ */
+#define irq_disable(irq) _arch_irq_disable(irq)
+
+
+#endif /* _IRQ_H_ */