1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Interrupt Handling</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="HAL Interfaces"
23 HREF="hal-interfaces.html"><LINK
25 TITLE="Architecture Characterization"
26 HREF="hal-architecture-characterization.html"><LINK
29 HREF="hal-input-and-output.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="hal-architecture-characterization.html"
65 >Chapter 9. HAL Interfaces</TD
71 HREF="hal-input-and-output.html"
85 NAME="HAL-INTERRUPT-HANDLING">Interrupt Handling</H1
87 >These interfaces contain definitions related to interrupt
88 handling. They include definitions of exception and interrupt numbers,
89 interrupt enabling and masking, and realtime clock operations.</P
91 >These definitions are normally found in
94 >cyg/hal/hal_intr.h</TT
95 >. This file is supplied by the
96 architecture HAL. Any variant or platform specific definitions will
99 >cyg/hal/var_intr.h</TT
103 >cyg/hal/plf_intr.h</TT
107 >cyg/hal/hal_platform_ints.h</TT
108 > in the variant or platform
109 HAL, depending on the exact target. These files are include
110 automatically by this header, so need not be included explicitly.</P
116 NAME="AEN7921">Vector numbers</H2
124 CLASS="PROGRAMLISTING"
125 >CYGNUM_HAL_VECTOR_XXXX
130 CYGNUM_HAL_INTERRUPT_XXXX
135 CYGNUM_HAL_EXCEPTION_XXXX
136 CYGNUM_HAL_EXCEPTION_MIN
137 CYGNUM_HAL_EXCEPTION_MAX
138 CYGNUM_HAL_EXCEPTION_COUNT</PRE
143 >All possible VSR, interrupt and exception vectors are specified here,
144 together with maximum and minimum values for range checking. While the
145 VSR and exception numbers will be defined in this file, the interrupt
146 numbers will normally be defined in the variant or platform HAL file
147 that is included by this header. </P
149 >There are two ranges of numbers, those for the vector service
150 routines and those for the interrupt service routines. The relationship
151 between these two ranges is undefined, and no equivalence should
152 be assumed if vectors from the two ranges coincide.</P
154 >The VSR vectors correspond to the set of exception vectors that can be
155 delivered by the CPU architecture, many of these will be internal
156 exception traps. The ISR vectors correspond to the set of external
157 interrupts that can be delivered and are usually determined by extra
158 decoding of the interrupt controller by the interrupt VSR.</P
160 >Where a CPU supports synchronous exceptions, the range of such
161 exceptions allowed are defined by <TT
163 >CYGNUM_HAL_EXCEPTION_MIN</TT
167 >CYGNUM_HAL_EXCEPTION_MAX</TT
171 >CYGNUM_HAL_EXCEPTION_XXXX</TT
173 standard names used by target independent code to test for the
174 presence of particular exceptions in the architecture. The actual
175 exception numbers will normally correspond to the VSR exception
176 range. In future other exceptions generated by the system software
177 (such as stack overflow) may be added.</P
181 >CYGNUM_HAL_ISR_COUNT</TT
184 >CYGNUM_HAL_VSR_COUNT</TT
188 >CYGNUM_HAL_EXCEPTION_COUNT</TT
189 > define the number of
190 ISRs, VSRs and EXCEPTIONs respectively for the purposes of defining
191 arrays etc. There might be a translation from the supplied vector
192 numbers into array offsets. Hence
195 >CYGNUM_HAL_XXX_COUNT</TT
199 >CYGNUM_HAL_XXX_MAX</TT
202 >CYGNUM_HAL_XXX_MIN</TT
205 >CYGNUM_HAL_XXX_MAX</TT
213 NAME="AEN7939">Interrupt state control</H2
221 CLASS="PROGRAMLISTING"
223 HAL_DISABLE_INTERRUPTS( old )
224 HAL_RESTORE_INTERRUPTS( old )
225 HAL_ENABLE_INTERRUPTS()
226 HAL_QUERY_INTERRUPTS( state )</PRE
231 >These macros provide control over the state of the CPUs interrupt mask
232 mechanism. They should normally manipulate a CPU status register to
233 enable and disable interrupt delivery. They should not access an
234 interrupt controller.</P
238 >CYG_INTERRUPT_STATE</TT
239 > is a data type that should be
240 used to store the interrupt state returned by
243 >HAL_DISABLE_INTERRUPTS()</TT
247 >HAL_QUERY_INTERRUPTS()</TT
251 >HAL_RESTORE_INTERRUPTS()</TT
256 >HAL_DISABLE_INTERRUPTS()</TT
257 > disables the delivery of
258 interrupts and stores the original state of the interrupt mask in the
259 variable passed in the <TT
268 >HAL_RESTORE_INTERRUPTS()</TT
269 > restores the state of
270 the interrupt mask to that recorded in <TT
279 >HAL_ENABLE_INTERRUPTS()</TT
280 > simply enables interrupts
281 regardless of the current state of the mask.</P
285 >HAL_QUERY_INTERRUPTS()</TT
286 > stores the state of the
287 interrupt mask in the variable passed in the <TT
292 > argument. The state stored here should also be
293 capable of being passed to
296 >HAL_RESTORE_INTERRUPTS()</TT
297 > at a later point.</P
299 >It is at the HAL implementer’s discretion exactly
300 which interrupts are masked by this mechanism. Where a CPU has more
301 than one interrupt type that may be masked separately (e.g. the
302 ARM's IRQ and FIQ) only those that can raise DSRs need
303 to be masked here. A separate architecture specific mechanism may
304 then be used to control the other interrupt types.</P
311 NAME="AEN7961">ISR and VSR management</H2
319 CLASS="PROGRAMLISTING"
320 >HAL_INTERRUPT_IN_USE( vector, state )
321 HAL_INTERRUPT_ATTACH( vector, isr, data, object )
322 HAL_INTERRUPT_DETACH( vector, isr )
323 HAL_VSR_SET( vector, vsr, poldvsr )
324 HAL_VSR_GET( vector, pvsr )
325 HAL_VSR_SET_TO_ECOS_HANDLER( vector, poldvsr )</PRE
330 >These macros manage the attachment of interrupt and vector service
331 routines to interrupt and exception vectors respectively.</P
335 >HAL_INTERRUPT_IN_USE()</TT
336 > tests the state of the
337 supplied interrupt vector and sets the value of the state parameter to
338 either 1 or 0 depending on whether there is already an ISR attached to
339 the vector. The HAL will only allow one ISR to be attached to each
340 vector, so it is a good idea to use this function before using
343 >HAL_INTERRUPT_ATTACH()</TT
348 >HAL_INTERRUPT_ATTACH()</TT
350 the ISR, data pointer and object pointer to the given
356 >. When an interrupt occurs on this
357 vector the ISR is called using the C calling convention and the vector
358 number and data pointer are passed to it as the first and second
359 arguments respectively.</P
363 >HAL_INTERRUPT_DETACH()</TT
364 > detaches the ISR from the
370 > replaces the VSR attached to the
376 > with the replacement supplied in
382 >. The old VSR is returned in the location
394 a copy of the VSR to the location pointed to by <TT
403 >HAL_VSR_SET_TO_ECOS_HANDLER()</TT
405 VSR for a specific exception is pointing at the eCos exception VSR and
406 not one for RedBoot or some other ROM monitor. The default when
407 running under RedBoot is for exceptions to be handled by RedBoot and
408 passed to GDB. This macro diverts the exception to eCos so that it may
409 be handled by application code. The arguments are the VSR vector to be
410 replaces, and a location in which to store the old VSR pointer, so
411 that it may be replaced at a later point.</P
418 NAME="AEN7983">Interrupt controller management</H2
426 CLASS="PROGRAMLISTING"
427 >HAL_INTERRUPT_MASK( vector )
428 HAL_INTERRUPT_UNMASK( vector )
429 HAL_INTERRUPT_ACKNOWLEDGE( vector )
430 HAL_INTERRUPT_CONFIGURE( vector, level, up )
431 HAL_INTERRUPT_SET_LEVEL( vector, level )</PRE
436 >These macros exert control over any prioritized interrupt
437 controller that is present. If no priority controller exists, then
438 these macros should be empty.</P
446 > These macros may not be reentrant, so care should be taken to
447 prevent them being called while interrupts are enabled. This means
448 that they can be safely used in initialization code before
449 interrupts are enabled, and in ISRs. In DSRs, ASRs and thread code,
450 however, interrupts must be disabled before these macros are
451 called. Here is an example for use in a DSR where the interrupt
452 source is unmasked after data processing:
461 CLASS="PROGRAMLISTING"
463 HAL_DISABLE_INTERRUPTS(old);
464 HAL_INTERRUPT_UNMASK(CYGNUM_HAL_INTERRUPT_ETH);
465 HAL_RESTORE_INTERRUPTS(old);
475 >HAL_INTERRUPT_MASK()</TT
476 > causes the interrupt
477 associated with the given vector to be blocked.</P
481 >HAL_INTERRUPT_UNMASK()</TT
482 > causes the interrupt
483 associated with the given vector to be unblocked.</P
487 >HAL_INTERRUPT_ACKNOWLEDGE()</TT
489 current interrupt from the given vector. This is usually executed from
490 the ISR for this vector when it is prepared to allow further
491 interrupts. Most interrupt controllers need some form of acknowledge
492 action before the next interrupt is allowed through. Executing this
493 macro may cause another interrupt to be delivered. Whether this
494 interrupts the current code depends on the state of the CPU interrupt
499 >HAL_INTERRUPT_CONFIGURE()</TT
501 control over how an interrupt signal is detected. The arguments
512 >The interrupt vector to be configured.</P
521 > if the interrupt is detected by
525 > if it is edge triggered.
532 > If the interrupt is set to level detect, then if this is
536 > it is detected by a high signal level,
540 > by a low signal level. If the
541 interrupt is set to edge triggered, then if this is
545 > it is triggered by a rising edge and if
557 >HAL_INTERRUPT_SET_LEVEL()</TT
558 > provides control over
559 the hardware priority of the interrupt. The arguments are:</P
569 >The interrupt whose level is to be set.</P
575 > The priority level to which the interrupt is to set. In some
576 architectures the masking of an interrupt is achieved by
577 changing its priority level. Hence this function,
580 >HAL_INTERRUPT_MASK()</TT
584 >HAL_INTERRUPT_UNMASK()</TT
597 NAME="AEN8030">Clock control</H2
605 CLASS="PROGRAMLISTING"
606 >HAL_CLOCK_INITIALIZE( period )
607 HAL_CLOCK_RESET( vector, period )
608 HAL_CLOCK_READ( pvalue )</PRE
613 >These macros provide control over a clock or timer device that may be
614 used by the kernel to provide time-out, delay and scheduling
615 services. The clock is assumed to be implemented by some form of
616 counter that is incremented or decremented by some external source and
617 which raises an interrupt when it reaches a predetermined value.</P
621 >HAL_CLOCK_INITIALIZE()</TT
622 > initializes the timer
623 device to interrupt at the given period. The period is essentially the
624 value used to initialize the timer counter and must be calculated from
625 the timer frequency and the desired interrupt rate. The timer device
626 should generate an interrupt every <TT
633 >HAL_CLOCK_RESET()</TT
634 > re-initializes the timer to
635 provoke the next interrupt. This macro is only really necessary when
636 the timer device needs to be reset in some way after each interrupt.</P
640 >HAL_CLOCK_READ()</TT
641 > reads the current value of the
642 timer counter and puts the value in the location pointed to by
648 >. The value stored will always be the
649 number of timer cycles since the last interrupt, and hence ranges
650 between zero and the initial period value. If this is a count-down
651 cyclic timer, some arithmetic may be necessary to generate this value.</P
658 NAME="AEN8042">Microsecond Delay</H2
666 CLASS="PROGRAMLISTING"
667 >HAL_DELAY_US(us)</PRE
672 >This is an optional definition. If defined the macro implements a busy
673 loop delay for the given number of microseconds. This is usually
674 implemented by waiting for the required number of hardware timer ticks
677 >This operation should normally be used when a very short delay is
678 needed when controlling hardware, programming FLASH devices and similar
679 situations where a wait/timeout loop would otherwise be used. Since it
680 may disable interrupts, and is implemented by busy waiting, it should
681 not be used in code that is sensitive to interrupt or context switch
690 SUMMARY="Footer navigation table"
701 HREF="hal-architecture-characterization.html"
719 HREF="hal-input-and-output.html"
729 >Architecture Characterization</TD
735 HREF="hal-interfaces.html"
projects / karo-tx-redboot.git / blob