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.

1 files changed, 384 insertions, 0 deletions

diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h
new file mode 100644
index 0000000000..032c49525a
--- /dev/null
+++ b/cpukit/include/rtems/rtems/timer.h
@@ -0,0 +1,384 @@
+/**
+ * @file rtems/rtems/timer.h
+ *
+ * @defgroup ClassicTimer Timers
+ *
+ * @ingroup ClassicRTEMS
+ * @brief Instantiate RTEMS Timer Data
+ *
+ * This include file contains all the constants, structures, and
+ * prototypes associated with the Timer Manager. This manager provides
+ * facilities to configure, initiate, cancel, and delete timers which will
+ * fire at specified intervals of time.
+ *
+ * Directives provided are:
+ *
+ * - create a timer
+ * - get an ID of a timer
+ * - delete a timer
+ * - set timer to fire in context of clock tick
+ * - after a number of ticks have passed
+ * - when a specified date and time has been reached
+ * - initiate the timer server task
+ * - set timer to fire in context of the timer server task
+ * - after a number of ticks have passed
+ * - when a specified date and time has been reached
+ * - reset a timer
+ * - cancel a time
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2011.
+ * On-Line Applications Research Corporation (OAR).
+ *
+ * Copyright (c) 2009, 2016 embedded brains GmbH.
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.org/license/LICENSE.
+ */
+
+#ifndef _RTEMS_RTEMS_TIMER_H
+#define _RTEMS_RTEMS_TIMER_H
+
+#include <rtems/rtems/attr.h>
+#include <rtems/rtems/status.h>
+#include <rtems/rtems/tasks.h>
+#include <rtems/rtems/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ *  @defgroup ClassicTimer Timers
+ *
+ *  @ingroup ClassicRTEMS
+ *
+ *  This encapsulates functionality related to the Classic API Timer
+ *  Manager.  This manager provides functionality which allows the
+ *  application to schedule the execution of methods at a specified
+ *  time in the future.  These methods may be scheduled based upon
+ *  interval or wall time and may be executed in either the clock tick
+ *  ISR or in a special dedicated timer server task.
+ */
+/**@{*/
+
+#define TIMER_CLASS_BIT_TIME_OF_DAY 0x1
+
+#define TIMER_CLASS_BIT_ON_TASK 0x2
+
+#define TIMER_CLASS_BIT_NOT_DORMANT 0x4
+
+/**
+ *  The following enumerated type details the classes to which a timer
+ *  may belong.
+ */
+typedef enum {
+  /**
+   * This value indicates the timer is currently not in use.
+   */
+  TIMER_DORMANT,
+
+  /**
+   * This value indicates the timer is currently in use as an interval
+   * timer which will fire in the clock tick ISR.
+   */
+  TIMER_INTERVAL = TIMER_CLASS_BIT_NOT_DORMANT,
+
+  /**
+   * This value indicates the timer is currently in use as an interval
+   * timer which will fire in the timer server task.
+   */
+  TIMER_INTERVAL_ON_TASK =
+    TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_ON_TASK,
+
+  /**
+   * This value indicates the timer is currently in use as an time of day
+   * timer which will fire in the clock tick ISR.
+   */
+  TIMER_TIME_OF_DAY =
+    TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY,
+
+  /**
+   * This value indicates the timer is currently in use as an time of day
+   * timer which will fire in the timer server task.
+   */
+  TIMER_TIME_OF_DAY_ON_TASK =
+    TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY |
+    TIMER_CLASS_BIT_ON_TASK
+} Timer_Classes;
+
+/**
+ *  The following types define a pointer to a timer service routine.
+ */
+typedef void rtems_timer_service_routine;
+
+/**
+ *  This type defines the type used to manage and indirectly invoke
+ *  Timer Service Routines (TSRs).  This defines the prototype and interface
+ *  for a function which is to be used as a TSR.
+ */
+typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
+                 rtems_id,
+                 void *
+             );
+
+/**
+ *  The following records define the control block used to manage
+ *  each timer.
+ */
+typedef struct {
+  /** This field is the object management portion of a Timer instance. */
+  Objects_Control  Object;
+  /** This field is the Watchdog instance which will be the scheduled. */
+  Watchdog_Control Ticker;
+  /** This field indicates what type of timer this currently is. */
+  Timer_Classes    the_class;
+  /** This field is the timer service routine. */
+  rtems_timer_service_routine_entry routine;
+  /** This field is the timer service routine user data. */
+  void *user_data;
+  /** This field is the timer interval in ticks or seconds. */
+  Watchdog_Interval initial;
+  /** This field is the timer start time point in ticks. */
+  Watchdog_Interval start_time;
+  /** This field is the timer stop time point in ticks. */
+  Watchdog_Interval stop_time;
+}   Timer_Control;
+
+/**
+ * @brief RTEMS Create Timer
+ *
+ * This routine implements the rtems_timer_create directive. The
+ * timer will have the name name. It returns the id of the
+ * created timer in ID.
+ *
+ * @param[in] name is the timer name
+ * @param[out] id is the pointer to timer id
+ *
+ * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ */
+rtems_status_code rtems_timer_create(
+  rtems_name    name,
+  rtems_id     *id
+);
+
+/**
+ * @brief RTEMS Timer Name to Id
+ *
+ * This routine implements the rtems_timer_ident directive.
+ * This directive returns the timer ID associated with name.
+ * If more than one timer is named name, then the timer
+ * to which the ID belongs is arbitrary.
+ *
+ * @param[in] name is the user defined message queue name
+ * @param[in] id is the pointer to timer id
+ *
+ * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ * id filled with the message queue id
+ */
+rtems_status_code rtems_timer_ident(
+  rtems_name    name,
+  rtems_id     *id
+);
+
+/**
+ *  @brief rtems_timer_cancel
+ *
+ *  This routine implements the rtems_timer_cancel directive.  It is used
+ *  to stop the timer associated with ID from firing.
+ */
+rtems_status_code rtems_timer_cancel(
+  rtems_id   id
+);
+
+/**
+ * @brief RTEMS Delete Timer
+ *
+ * This routine implements the rtems_timer_delete directive. The
+ * timer indicated by ID is deleted.
+ *
+ * @param[in] id is the timer id
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ *         error. Otherwise, a status code is returned indicating the
+ *         source of the error.
+ */
+rtems_status_code rtems_timer_delete(
+  rtems_id   id
+);
+
+/**
+ * @brief RTEMS Timer Fire After
+ *
+ * This routine implements the rtems_timer_fire_after directive. It
+ * initiates the timer associated with ID to fire in ticks clock ticks.
+ * When the timer fires, the routine will be invoked in the context
+ * of the rtems_clock_tick directive which is normally invoked as
+ * part of servicing a periodic interupt.
+ *
+ * @param[in] id is the timer id
+ * @param[in] ticks is the interval until routine is fired
+ * @param[in] routine is the routine to schedule
+ * @param[in] user_data is the passed as argument to routine when it is fired
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ *         error. Otherwise, a status code is returned indicating the
+ *         source of the error.
+ */
+rtems_status_code rtems_timer_fire_after(
+  rtems_id                           id,
+  rtems_interval                     ticks,
+  rtems_timer_service_routine_entry  routine,
+  void                              *user_data
+);
+
+/**
+ * @brief RTEMS Timer Server Fire After
+ *
+ * This routine implements the rtems_timer_server_fire_after directive. It
+ * initiates the timer associated with ID to fire in ticks clock
+ * ticks. When the timer fires, the routine will be invoked by the
+ * Timer Server in the context of a task NOT IN THE CONTEXT of the
+ * clock tick interrupt.
+ *
+ * @param[in] id is the timer id
+ * @param[in] ticks is the interval until routine is fired
+ * @param[in] routine is the routine to schedule
+ * @param[in] user_data is the passed as argument to routine when it is fired
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ *         error. Otherwise, a status code is returned indicating the
+ *         source of the error.
+ */
+rtems_status_code rtems_timer_server_fire_after(
+  rtems_id                           id,
+  rtems_interval                     ticks,
+  rtems_timer_service_routine_entry  routine,
+  void                              *user_data
+);
+
+/**
+ * @brief RTEMS Timer Fire When
+ *
+ * This routine implements the rtems_timer_fire_when directive. It
+ * initiates the timer associated with ID to fire at wall_time
+ * When the timer fires, the routine will be invoked in the context
+ * of the rtems_clock_tick directive which is normally invoked as
+ * part of servicing a periodic interupt.
+ *
+ * @param[in] id is the timer id
+ * @param[in] wall_time is the time of day to fire timer
+ * @param[in] routine is the routine to schedule
+ * @param[in] user_data is the passed as argument to routine when it is fired
+ *
+ * @retval This method returns RTEMS_SUCCESSFUL if there was not an
+ *         error. Otherwise, a status code is returned indicating the
+ *         source of the error.
+ */
+rtems_status_code rtems_timer_fire_when(
+  rtems_id                            id,
+  rtems_time_of_day                  *wall_time,
+  rtems_timer_service_routine_entry   routine,
+  void                               *user_data
+);
+
+/**
+ *  @brief RTEMS Timer Server Fire When Directive
+ *
+ *  Timer Manager - RTEMS Timer Server Fire When Directive
+ *
+ *  This routine implements the rtems_timer_server_fire_when directive.  It
+ *  initiates the timer associated with ID to fire at wall_time
+ *  When the timer fires, the routine will be invoked by the
+ *  Timer Server in the context of a task NOT IN THE CONTEXT of the
+ *  clock tick interrupt.
+ */
+rtems_status_code rtems_timer_server_fire_when(
+  rtems_id                            id,
+  rtems_time_of_day                  *wall_time,
+  rtems_timer_service_routine_entry   routine,
+  void                               *user_data
+);
+
+/**
+ *  @brief RTEMS Timer Reset
+ *
+ *  Timer Manager - RTEMS Timer Reset
+ *
+ *  This routine implements the rtems_timer_reset directive.  It is used
+ *  to reinitialize the interval timer associated with ID just as if
+ *  rtems_timer_fire_after were re-invoked with the same arguments that
+ *  were used to initiate this timer.
+ */
+rtems_status_code rtems_timer_reset(
+  rtems_id   id
+);
+
+/**
+ *  @brief Initiates the timer server.
+ *
+ *  This directive creates and starts the server for task-based timers.
+ *  It must be invoked before any task-based timers can be initiated.
+ *
+ *  @param priority The timer server task priority.
+ *  @param stack_size The stack size in bytes for the timer server task.
+ *  @param attribute_set The timer server task attributes.
+ *
+ *  @return This method returns RTEMS_SUCCESSFUL if successful and an
+ *          error code otherwise.
+ */
+rtems_status_code rtems_timer_initiate_server(
+  rtems_task_priority priority,
+  size_t              stack_size,
+  rtems_attribute     attribute_set
+);
+
+/**
+ *  This is the default value for the priority of the Timer Server.
+ *  When given this priority, a special high priority not accessible
+ *  via the Classic API is used.
+ */
+#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY (uint32_t) -1
+
+/**
+ *  This is the structure filled in by the timer get information
+ *  service.
+ */
+typedef struct {
+  /** This indicates the current type of the timer. */
+  Timer_Classes      the_class;
+  /** This indicates the initial requested interval. */
+  Watchdog_Interval  initial;
+  /** This indicates the time the timer was initially scheduled. */
+  Watchdog_Interval  start_time;
+  /** This indicates the time the timer is scheduled to fire. */
+  Watchdog_Interval  stop_time;
+} rtems_timer_information;
+
+/**
+ * @brief RTEMS Get Timer Information
+ *
+ * This routine implements the rtems_timer_get_information directive.
+ * This directive returns information about the timer.
+ *
+ * @param[in] id is the timer id
+ * @param[in] the_info is the pointer to timer information block
+ *
+ * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ * 		*the_info region information block filled in
+ */
+rtems_status_code rtems_timer_get_information(
+  rtems_id                 id,
+  rtems_timer_information *the_info
+);
+
+/**@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+/* end of include file */