source: rtems/cpukit/include/rtems/rtems/dpmem.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.3 KB
Line 
1/**
2 * @file rtems/rtems/dpmem.h
3 *
4 * @defgroup ClassicDPMEM Dual Ported Memory
5 *
6 * @ingroup ClassicRTEMS
7 * @brief Dual Ported Memory Manager
8 *
9 * This include file contains all the constants and structures associated
10 * with the Dual Ported Memory Manager. This manager provides a mechanism
11 * for converting addresses between internal and external representations
12 * for multiple dual-ported memory areas.
13 *
14 * Directives provided are:
15 *
16 * - create a port
17 * - get ID of a port
18 * - delete a port
19 * - convert external to internal address
20 * - convert internal to external address
21 *
22 */
23
24/* COPYRIGHT (c) 1989-2008.
25 * On-Line Applications Research Corporation (OAR).
26 *
27 * The license and distribution terms for this file may be
28 * found in the file LICENSE in this distribution or at
29 * http://www.rtems.org/license/LICENSE.
30 */
31
32#ifndef _RTEMS_RTEMS_DPMEM_H
33#define _RTEMS_RTEMS_DPMEM_H
34
35#include <rtems/rtems/types.h>
36#include <rtems/rtems/status.h>
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/**
43 *  @defgroup ClassicDPMEM Dual Ported Memory
44 *
45 *  @ingroup ClassicRTEMS
46 *
47 *  This encapsulates functionality related to the
48 *  Classic API Dual Ported Memory Manager.
49 */
50/**@{*/
51
52/**
53 *  The following structure defines the port control block.  Each port
54 *  has a control block associated with it.  This control block contains
55 *  all information required to support the port related operations.
56 */
57typedef struct {
58  /** This field is the object management portion of a Port instance. */
59  Objects_Control  Object;
60  /** This field is the base internal address of the port. */
61  void            *internal_base;
62  /** This field is the base external address of the port. */
63  void            *external_base;
64  /** This field is the length of dual-ported area of the port. */
65  uint32_t         length;
66}   Dual_ported_memory_Control;
67
68/**
69 * @brief Creates a port into a dual-ported memory area.
70 *
71 * This routine implements the rtems_port_create directive. The port
72 * will have the name @a name. The port maps onto an area of dual ported
73 * memory of length bytes which has internal_start and external_start
74 * as the internal and external starting addresses, respectively.
75 * It returns the id of the created port in ID.
76 *
77 * @param[in] name is the user defined port name
78 * @param[in] internal_start is the internal start address of port
79 * @param[in] external_start is the external start address of port
80 * @param[in] length is the physical length in bytes
81 * @param[out] id is the address of port id to set
82 *
83 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
84 *         error. Otherwise, a status code is returned indicating the
85 *         source of the error. If successful, the id will
86 *         be filled in with the port id.
87 */
88rtems_status_code rtems_port_create(
89  rtems_name    name,
90  void         *internal_start,
91  void         *external_start,
92  uint32_t      length,
93  rtems_id     *id
94);
95
96/**
97 * @brief RTEMS Port Name to Id
98 *
99 * This routine implements the rtems_port_ident directive. This directive
100 * returns the port ID associated with name. If more than one port is
101 * named name, then the port to which the ID belongs is arbitrary.
102 *
103 * @param[in] name is the user defined port name
104 * @param[out] id is the pointer to port id
105 *
106 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
107 */
108rtems_status_code rtems_port_ident(
109  rtems_name    name,
110  rtems_id     *id
111);
112
113/**
114 * @brief RTEMS Delete Port
115 *
116 * This routine implements the rtems_port_delete directive. It deletes
117 * the port associated with ID.
118 *
119 * @param[in] id is the dual-ported memory area id
120 *
121 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
122 *         error. Otherwise, a status code is returned indicating the
123 *         source of the error.
124 */
125rtems_status_code rtems_port_delete(
126  rtems_id   id
127);
128
129/**
130 * @brief RTEMS Port External to Internal
131 *
132 * This routine implements the rtems_port_external_to_internal directive.
133 * It returns the internal port address which maps to the provided
134 * external port address for the specified port ID. If the given external
135 * address is an invalid dual-ported address, then the internal address is
136 * set to the given external address.
137 *
138 * @param[in] id is the id of dp memory object
139 * @param[in] external is the external address
140 * @param[out] internal is the pointer of internal address to set
141 *
142 * @retval RTEMS_SUCCESSFUL
143 */
144rtems_status_code rtems_port_external_to_internal(
145  rtems_id     id,
146  void        *external,
147  void       **internal
148);
149
150/**
151 * @brief RTEMS Port Internal to External
152 *
153 * This routine implements the Port_internal_to_external directive.
154 * It returns the external port address which maps to the provided
155 * internal port address for the specified port ID. If the given
156 * internal address is an invalid dual-ported address, then the
157 * external address is set to the given internal address.
158 *
159 * @param[in] id is the id of dual-ported memory object
160 * @param[in] internal is the internal address to set
161 * @param[in] external is the pointer to external address
162 *
163 * @retval RTEMS_SUCCESSFUL and the external will be filled in
164 * with the external addresses
165 */
166rtems_status_code rtems_port_internal_to_external(
167  rtems_id     id,
168  void        *internal,
169  void       **external
170);
171
172/**@}*/
173
174#ifdef __cplusplus
175}
176#endif
177
178#endif
179/* end of include file */
Note: See TracBrowser for help on using the repository browser.