File : s-bbbosu.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
4 -- --
5 -- S Y S T E M . B B . B O A R D _ S U P P O R T --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1999-2002 Universidad Politecnica de Madrid --
10 -- Copyright (C) 2003-2006 The European Space Agency --
11 -- Copyright (C) 2003-2016, AdaCore --
12 -- --
13 -- GNARL is free software; you can redistribute it and/or modify it under --
14 -- terms of the GNU General Public License as published by the Free Soft- --
15 -- ware Foundation; either version 3, or (at your option) any later ver- --
16 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
17 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
18 -- or FITNESS FOR A PARTICULAR PURPOSE. --
19 -- --
20 -- --
21 -- --
22 -- --
23 -- --
24 -- You should have received a copy of the GNU General Public License and --
25 -- a copy of the GCC Runtime Library Exception along with this program; --
26 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
27 -- <http://www.gnu.org/licenses/>. --
28 -- --
29 -- GNARL was developed by the GNARL team at Florida State University. --
30 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
31 -- --
32 -- The port of GNARL to bare board targets was initially developed by the --
33 -- Real-Time Systems Group at the Technical University of Madrid. --
34 -- --
35 ------------------------------------------------------------------------------
36
37 -- This package defines an interface used for handling the peripherals
38 -- available in the target board that are needed by the target-independent
39 -- part of the run time.
40
41 pragma Restrictions (No_Elaboration_Code);
42
43 with System.BB.Interrupts;
44 with System.BB.CPU_Primitives;
45
46 package System.BB.Board_Support is
47 pragma Preelaborate;
48
49 -----------------------------
50 -- Hardware Initialization --
51 -----------------------------
52
53 procedure Initialize_Board;
54 -- Procedure that performs the hardware initialization of the board.
55 -- Should be called before any other operations in this package.
56
57 ------------------------------------------------
58 -- Clock and Timer Definitions and Primitives --
59 ------------------------------------------------
60
61 type Timer_Interval is mod 2 ** 32;
62 for Timer_Interval'Size use 32;
63 -- This type represents any interval that we can measure within a
64 -- Clock_Interrupt_Period. Even though this type is always 32 bits, its
65 -- actual allowed range is 0 .. Max_Timer_Interval, which may be less,
66 -- depending on the target.
67
68 function Max_Timer_Interval return Timer_Interval;
69 pragma Inline (Max_Timer_Interval);
70 -- The maximum value of the hardware clock. The is the maximum value that
71 -- Read_Clock may return, and the longest interval that Set_Alarm may use.
72 -- The hardware clock period is Max_Timer_Interval + 1 clock ticks. An
73 -- interrupt occurs after this number of ticks.
74
75 procedure Set_Alarm (Ticks : Timer_Interval);
76 -- Set an alarm that will expire after the specified number of clock ticks.
77 -- This cancels any previous alarm set.
78
79 function Read_Clock return Timer_Interval;
80 -- Read the value contained in the clock hardware counter, and return the
81 -- number of ticks elapsed since the last clock interrupt, that is, since
82 -- the clock counter was last reloaded.
83
84 function Alarm_Interrupt_ID return Interrupts.Interrupt_ID;
85 pragma Inline (Alarm_Interrupt_ID);
86 -- Return the interrupt level to use for the alarm clock handler
87
88 procedure Clear_Alarm_Interrupt;
89 pragma Inline (Clear_Alarm_Interrupt);
90 -- Acknowledge the alarm interrupt
91
92 ----------------
93 -- Interrupts --
94 ----------------
95
96 procedure Clear_Interrupt_Request
97 (Interrupt : System.BB.Interrupts.Interrupt_ID);
98 pragma Inline (Clear_Interrupt_Request);
99 -- Acknowledge the end of the interrupt
100
101 function Get_Interrupt_Request
102 (Vector : CPU_Primitives.Vector_Id)
103 return System.BB.Interrupts.Interrupt_ID;
104 pragma Inline (Get_Interrupt_Request);
105 -- Function to be called from the trap handler to determine the external
106 -- interrupt to handle for the given trap vector. If the trap does not
107 -- correspond to an external interrupt (that is, if it is a synchronous
108 -- trap) then interrupt level 0 (no interrupt) is returned. If the
109 -- system shares a single trap handler for multiple external interrupts,
110 -- this would typically query the interrupt controller for determining
111 -- the interrupt to handle.
112
113 function Priority_Of_Interrupt
114 (Interrupt : System.BB.Interrupts.Interrupt_ID)
115 return System.Any_Priority;
116 pragma Inline (Priority_Of_Interrupt);
117 -- Function to obtain the priority associated with an interrupt. It returns
118 -- System.Any_Priority'First if Interrupt is equal to zero (no interrupt).
119
120 procedure Install_Interrupt_Handler
121 (Handler : Address;
122 Interrupt : Interrupts.Interrupt_ID;
123 Prio : Interrupt_Priority);
124 -- Determine the trap vector that will be called for handling the given
125 -- external interrupt on the current CPU, and install the given handler
126 -- there. It is an error to try to install two different handlers for the
127 -- vector, though this procedure may be called for multiple interrupts
128 -- that share the same vector, as long as they use the same Handler.
129 -- The handler expects a single argument indicating the vector called.
130 -- This routine may need to set up the interrupt controller to enable the
131 -- given interrupt source, so it will actually cause a trap on the CPU.
132 -- Note, this should not actually enable interrupts, as this is only done
133 -- through CPU_Primitives.Enable_Interrupts, which typically uses a
134 -- processor status register. Prio is the priority for the interrupt, and
135 -- the hardware can be programmed to use that priority.
136
137 procedure Set_Current_Priority (Priority : Integer);
138 pragma Inline (Set_Current_Priority);
139 -- Only allow interrupts higher than the specified priority. This routine
140 -- differes from the Enable_Interrupts/Disable_Interrupts procedures
141 -- in CPU_Primitives in that it disables interrupts at the board level,
142 -- rather than the CPU. Typically if board-specific support of an interrupt
143 -- controller is needed to block interrupts of insufficient priority, this
144 -- routine will be needed. On other systems, where the processor has this
145 -- control, or where only a single interrupt priority is supported, this
146 -- may be a null procedure.
147
148 procedure Power_Down;
149 pragma Inline (Power_Down);
150 -- Power-down the current CPU. This procedure is called only by the idle
151 -- task, with interrupt enabled.
152
153 ---------------------
154 -- Multiprocessors --
155 ---------------------
156
157 -- The following functions define an interface for handling the "poke"
158 -- interrupts that are used to signal other processors in an multiprocessor
159 -- system.
160
161 function Poke_Interrupt_ID return Interrupts.Interrupt_ID;
162 pragma Inline (Poke_Interrupt_ID);
163 -- Return the interrupt level to use for poke, or No_Interrupt if the
164 -- system is a monoprocessor or otherwise does not require pokes.
165
166 procedure Clear_Poke_Interrupt;
167 pragma Inline (Clear_Poke_Interrupt);
168 -- Acknowledge the Poke interrupt
169
170 end System.BB.Board_Support;