source: rtems/bsps/arm/atsam/include/bsp/power.h @ 2afb22b

Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 5.5 KB
Line 
1/*
2 * Copyright (c) 2016 embedded brains GmbH.  All rights reserved.
3 *
4 *  embedded brains GmbH
5 *  Dornierstr. 4
6 *  82178 Puchheim
7 *  Germany
8 *  <rtems@embedded-brains.de>
9 *
10 * The license and distribution terms for this file may be
11 * found in the file LICENSE in this distribution or at
12 * http://www.rtems.org/license/LICENSE.
13 */
14
15#ifndef LIBBSP_ARM_ATSAM_POWER_H
16#define LIBBSP_ARM_ATSAM_POWER_H
17
18#include <sys/types.h>
19
20#include <stdint.h>
21
22#ifdef __cplusplus
23extern "C"{
24#endif /* __cplusplus */
25
26/**
27 * @brief Status of the Low Power Support
28 */
29typedef enum {
30  /**
31   * @brief Used for Initialization of Handlers
32   */
33  ATSAM_POWER_INIT,
34  /**
35   * @brief Used for Switching On of Handlers
36   */
37  ATSAM_POWER_ON,
38  /**
39   * @brief Used for Switching Off of Handlers
40   */
41  ATSAM_POWER_OFF
42} atsam_power_state;
43
44/**
45 * @brief Control structure for power control handling
46 */
47typedef struct atsam_power_control {
48  /**
49   * @brief Data pointer to the handler with its desired state
50   */
51  void (*handler)(
52      const struct atsam_power_control *control,
53      atsam_power_state state
54  );
55  /**
56   * @brief Data chunk that is used by the handler
57   */
58  union {
59    void *arg;
60    struct {
61      uint8_t first;
62      uint8_t last;
63    } peripherals;
64  } data;
65} atsam_power_control;
66
67/**
68 * @brief Performs a power state change according to the state parameter.
69 *
70 * The handlers of the control table are invoked in forward order (invocation
71 * starts with table index zero) for the ATSAM_POWER_INIT and ATSAM_POWER_OFF
72 * states, otherwise the handlers are invoked in reverse order (invocation
73 * starts with the last table index).
74 *
75 * @param controls Table with power controls.
76 * @param n Count of power control table entries.
77 * @param state The desired power state.
78 *
79 * @code
80 * #include <rtems.h>
81 * #include <pthread.h>
82 *
83 * #include <bsp/power.h>
84 *
85 * static atsam_power_data_rtc_driver rtc_data = { .interval = 5 };
86 *
87 * static const atsam_power_control power_controls[] = {
88 *   ATSAM_POWER_CLOCK_DRIVER,
89 *   ATSAM_POWER_RTC_DRIVER(&rtc_data),
90 *   ATSAM_POWER_SLEEP_MODE
91 * };
92 *
93 * static pthread_once_t once = PTHREAD_ONCE_INIT;
94 *
95 * static void init(void)
96 * {
97 *   atsam_power_change_state(
98 *     &power_controls[0],
99 *     RTEMS_ARRAY_SIZE(power_controls),
100 *     ATSAM_POWER_INIT
101 *   );
102 * }
103 *
104 * void power_init(void)
105 * {
106 *   pthread_once(&once, init);
107 * }
108 *
109 * void low_power(void)
110 * {
111 *   atsam_power_change_state(
112 *     &power_controls[0],
113 *     RTEMS_ARRAY_SIZE(power_controls),
114 *     ATSAM_POWER_OFF
115 *   );
116 *   atsam_power_change_state(
117 *     &power_controls[0],
118 *     RTEMS_ARRAY_SIZE(power_controls),
119 *     ATSAM_POWER_ON
120 *   );
121 * }
122 * @end
123 */
124void atsam_power_change_state(
125  const atsam_power_control *controls,
126  size_t n,
127  atsam_power_state state
128);
129
130/**
131 * @brief Power handler for a set of peripherals according to the specified
132 * peripheral indices.
133 *
134 * For the power off state, the peripherals are enabled in the PMC.
135 *
136 * For the power on state, the peripherals are disabled in the Power Management
137 * Controller (PMC).
138 *
139 * @see ATSAM_POWER_PERIPHERAL().
140 */
141void atsam_power_handler_peripheral(
142  const atsam_power_control *controls,
143  atsam_power_state state
144);
145
146/**
147 * @brief Power handler for the clock driver.
148 *
149 * For the power off state, the system tick is disabled.
150 *
151 * For the power on state, the system tick is enabled.  In case no clock driver
152 * is used by the application, then this may lead to a spurious interrupt
153 * resulting in a fatal error.
154 *
155 * @see ATSAM_POWER_CLOCK_DRIVER().
156 */
157void atsam_power_handler_clock_driver(
158  const atsam_power_control *controls,
159  atsam_power_state state
160);
161
162/**
163 * @brief Power handler for the RTC driver.
164 *
165 * This handler installs an interrupt handler during power support initialization.
166 *
167 * For the power off state, the RTC alarm interrupt is set up according to the
168 * interval of the corresponding handler data.
169 *
170 * For the power on state, the RTC alarm interrupt is disabled.
171 *
172 * @see ATSAM_POWER_RTC_DRIVER().
173 */
174void atsam_power_handler_rtc_driver(
175  const atsam_power_control *controls,
176  atsam_power_state state
177);
178
179/**
180 * @brief Power handler to enter the processor sleep mode.
181 *
182 * For the power off state, the processor is set into the sleep mode and issues
183 * a wait for interrupt instruction.
184 *
185 * @see ATSAM_POWER_SLEEP_MODE().
186 */
187void atsam_power_handler_sleep_mode(
188  const atsam_power_control *controls,
189  atsam_power_state state
190);
191
192/**
193 * @brief Initializer for a peripheral power support.
194 *
195 * @param f The first peripheral index.
196 * @param l The last peripheral index.
197 */
198#define ATSAM_POWER_PERIPHERAL(f, l) \
199 { \
200   .handler = atsam_power_handler_peripheral, \
201   .data = { .peripherals = { .first = f, .last = l } } \
202 }
203
204#define ATSAM_POWER_HANDLER(h, a) \
205 { \
206   .handler = h, \
207   .data = { .arg = a } \
208 }
209
210#define ATSAM_POWER_CLOCK_DRIVER \
211 { .handler = atsam_power_handler_clock_driver }
212
213#define ATSAM_POWER_SLEEP_MODE \
214 { .handler = atsam_power_handler_sleep_mode }
215
216/**
217 * @brief Data for RTC driver power support.
218 *
219 * @see ATSAM_POWER_RTC_DRIVER().
220 */
221typedef struct {
222  /**
223   * @brief Interval in seconds for which the power off mode should be active.
224   */
225  uint8_t interval;
226} atsam_power_data_rtc_driver;
227
228/**
229 * @brief Initializer for RTC driver power support.
230 *
231 * @param a Pointer to RTC driver power data.
232 *
233 * @see atsam_power_data_rtc_driver.
234 */
235#define ATSAM_POWER_RTC_DRIVER(a) \
236 { \
237    .handler = atsam_power_handler_rtc_driver, \
238    .data = { .arg = a } \
239 }
240
241#ifdef __cplusplus
242}
243#endif /* __cplusplus */
244
245#endif /* LIBBSP_ARM_ATSAM_POWER_H */
Note: See TracBrowser for help on using the repository browser.