RFA: Expand/update documentation on Epiphany interrupt attribute
diff mbox

Message ID 20120207163411.70fbg1bfkg8k8ww8-nzlynne@webmail.spamcop.net
State New
Headers show

Commit Message

Joern Rennecke Feb. 7, 2012, 9:34 p.m. UTC
Tested by building 'info' for epiphany-elf, and by bootstrapping
x86_64-unknown-linux-gnu .
2012-02-07  Jeremy Bennett  <jeremy.bennett@embecosm.com>
            Joern Rennecke  <joern.rennecke@embecosm.com>

	* doc/extend.texi: Expand and update information on interrupt
	attribute for Epiphany.

Comments

Gerald Pfeifer Feb. 11, 2012, 10:53 p.m. UTC | #1
On Tue, 7 Feb 2012, Joern Rennecke wrote:
> Tested by building 'info' for epiphany-elf, and by bootstrapping
> x86_64-unknown-linux-gnu .

Jörn, you are listed as epihphany maintainer, so you don't needs
to RFA patches like this.

That said...

Index: doc/extend.texi
===================================================================
+On Epiphany targets one or more optional parameters may added like this:
                                                       ^^^

...something doesn't seem right here.  Perhaps "can be added" or
"can be specified"?

+Permissible values for these parameters are: @w{@code{reset}},
+@w{@code{software_exception}}, @w{@code{page_miss}},
+@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
+@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.

Would everyone needing to use these know what these different options
refer to?

+Multiple parameters indicate that multiple entries in the interrupt
+vector table should be initialized for this function.  The
+parameter(s) may be omitted entirely, in which case no interrupt
+vector table entry will be provided.

Is "provided" the right term here?  I would have expected "set"
or "inserted" or something like that, but am not familiar with 
this setting, so feel free to ignore this.


The patch per se is fine.

Gerald

Patch
diff mbox

Index: doc/extend.texi
===================================================================
--- doc/extend.texi	(revision 183982)
+++ doc/extend.texi	(working copy)
@@ -2727,7 +2727,8 @@  void bar (void)
 RL78, RX and Xstormy16 ports to indicate that the specified function is an
 interrupt handler.  The compiler will generate function entry and exit
 sequences suitable for use in an interrupt handler when this attribute
-is present.
+is present.  With Epiphany targets it may also generate a special section with
+code to initialize the interrupt vector table.
 
 Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze,
 and SH processors can be specified via the @code{interrupt_handler} attribute.
@@ -2746,6 +2747,47 @@  void f () __attribute__ ((interrupt ("IR
 On ARMv7-M the interrupt type is ignored, and the attribute means the function
 may be called with a word aligned stack pointer.
 
+On Epiphany targets one or more optional parameters may added like this:
+
+@smallexample
+void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
+@end smallexample
+
+Permissible values for these parameters are: @w{@code{reset}},
+@w{@code{software_exception}}, @w{@code{page_miss}},
+@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
+@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
+Multiple parameters indicate that multiple entries in the interrupt
+vector table should be initialized for this function.  The
+parameter(s) may be omitted entirely, in which case no interrupt
+vector table entry will be provided.
+
+Note, on Epiphany targets, interrupts are enabled inside the function
+unless the @code{disinterrupt} attribute is also specified.
+
+On Epiphany targets, you can also use the following attribute to
+modify the behavior of an interrupt handler:
+@table @code
+@item forwarder_section
+@cindex @code{forwarder_section} attribute
+The interrupt handler may be in external memory which cannot be
+reached by a branch instruction, so generate a local memory trampoline
+to transfer control.  The single parameter identifies the section where
+the trampoline will be placed.
+@end table
+
+The following examples are all valid uses of these attributes on
+Epiphany targets:
+@smallexample
+void __attribute__ ((interrupt)) universal_handler ();
+void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
+void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
+void __attribute__ ((interrupt ("timer0"), disinterrupt))
+  fast_timer_handler ();
+void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp")))
+  external_dma_handler ();
+@end smallexample
+
 On MIPS targets, you can use the following attributes to modify the behavior
 of an interrupt handler:
 @table @code