source: rtems/bsps/arm/atsam/include/libchip/include/pio.h @ 7633f5b

Last change on this file since 7633f5b 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: 7.7 KB
Line 
1/* ---------------------------------------------------------------------------- */
2/*                  Atmel Microcontroller Software Support                      */
3/*                       SAM Software Package License                           */
4/* ---------------------------------------------------------------------------- */
5/* Copyright (c) 2015, Atmel Corporation                                        */
6/*                                                                              */
7/* All rights reserved.                                                         */
8/*                                                                              */
9/* Redistribution and use in source and binary forms, with or without           */
10/* modification, are permitted provided that the following condition is met:    */
11/*                                                                              */
12/* - Redistributions of source code must retain the above copyright notice,     */
13/* this list of conditions and the disclaimer below.                            */
14/*                                                                              */
15/* Atmel's name may not be used to endorse or promote products derived from     */
16/* this software without specific prior written permission.                     */
17/*                                                                              */
18/* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
19/* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
20/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
21/* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
22/* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
23/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
24/* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
25/* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
26/* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
27/* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
28/* ---------------------------------------------------------------------------- */
29
30/**
31 *  \file
32 *
33 *  \section Purpose
34 *
35 *  This file provides a basic API for PIO configuration and usage of
36 *  user-controlled pins. Please refer to the board.h file for a list of
37 *  available pin definitions.
38 *
39 *  \section Usage
40 *
41 *  -# Define a constant pin description array such as the following one, using
42 *     the existing definitions provided by the board.h file if possible:
43 *     \code
44 *        const Pin pPins[] = {PIN_USART0_TXD, PIN_USART0_RXD};
45 *     \endcode
46 *     Alternatively, it is possible to add new pins by provided the full Pin
47 *     structure:
48 *     \code
49 *     // Pin instance to configure PA10 & PA11 as inputs with the internal
50 *     // pull-up enabled.
51 *     const Pin pPins = {
52 *          (1 << 10) | (1 << 11),
53 *          REG_PIOA,
54 *          ID_PIOA,
55 *          PIO_INPUT,
56 *          PIO_PULLUP
57 *     };
58 *     \endcode
59 *  -# Configure a pin array by calling PIO_Configure() with a pointer to the
60 *     array and its size (which is computed using the PIO_LISTSIZE macro).
61 *  -# Change and get the value of a user-controlled pin using the PIO_Set,
62 *     PIO_Clear and PIO_Get methods.
63 *  -# Get the level being currently output by a user-controlled pin configured
64 *     as an output using PIO_GetOutputDataStatus().
65 */
66
67#ifndef _PIO_
68#define _PIO_
69
70/*
71 *         Headers
72 */
73
74#include "chip.h"
75
76#include <stdint.h>
77
78/*
79 *         Global Definitions
80 */
81
82/**  The pin is controlled by the associated signal of peripheral A. */
83#define PIO_PERIPH_A                0
84/**  The pin is controlled by the associated signal of peripheral B. */
85#define PIO_PERIPH_B                1
86/**  The pin is controlled by the associated signal of peripheral C. */
87#define PIO_PERIPH_C                2
88/**  The pin is controlled by the associated signal of peripheral D. */
89#define PIO_PERIPH_D                3
90/**  The pin is an input. */
91#define PIO_INPUT                   4
92/**  The pin is an output and has a default level of 0. */
93#define PIO_OUTPUT_0                5
94/**  The pin is an output and has a default level of 1. */
95#define PIO_OUTPUT_1                6
96
97/**  Default pin configuration (no attribute). */
98#define PIO_DEFAULT                 (0 << 0)
99/**  The internal pin pull-up is active. */
100#define PIO_PULLUP                  (1 << 0)
101/**  The internal glitch filter is active. */
102#define PIO_DEGLITCH                (1 << 1)
103/**  The pin is open-drain. */
104#define PIO_OPENDRAIN               (1 << 2)
105
106/**  The internal debouncing filter is active. */
107#define PIO_DEBOUNCE                (1 << 3)
108
109/**  Enable additional interrupt modes. */
110#define PIO_IT_AIME                 (1 << 4)
111
112/**  Interrupt High Level/Rising Edge detection is active. */
113#define PIO_IT_RE_OR_HL             (1 << 5)
114/**  Interrupt Edge detection is active. */
115#define PIO_IT_EDGE                 (1 << 6)
116
117/**  Low level interrupt is active */
118#define PIO_IT_LOW_LEVEL          (0               | 0 | PIO_IT_AIME)
119/**  High level interrupt is active */
120#define PIO_IT_HIGH_LEVEL         (PIO_IT_RE_OR_HL | 0 | PIO_IT_AIME)
121/**  Falling edge interrupt is active */
122#define PIO_IT_FALL_EDGE          (0               | PIO_IT_EDGE | PIO_IT_AIME)
123/**  Rising edge interrupt is active */
124#define PIO_IT_RISE_EDGE          (PIO_IT_RE_OR_HL | PIO_IT_EDGE | PIO_IT_AIME)
125/** The WP is enable */
126#define PIO_WPMR_WPEN_EN          (0x01     << 0)
127/** The WP is disable */
128#define PIO_WPMR_WPEN_DIS         (0x00     << 0)
129/** Valid WP key */
130#define PIO_WPMR_WPKEY_VALID      (0x50494F << 8)
131#ifdef __cplusplus
132extern "C" {
133#endif
134
135/*
136 *          Global Macros
137 */
138
139/**
140 *  Calculates the size of an array of Pin instances. The array must be defined
141 *  locally (i.e. not a pointer), otherwise the computation will not be correct.
142 *  \param pPins  Local array of Pin instances.
143 *  \return Number of elements in array.
144 */
145#define PIO_LISTSIZE(pPins)    (sizeof(pPins) / sizeof(Pin))
146
147/*
148 *         Global Types
149 */
150
151
152/*
153 *  Describes the type and attribute of one PIO pin or a group of similar pins.
154 *  The #type# field can have the following values:
155 *     - PIO_PERIPH_A
156 *     - PIO_PERIPH_B
157 *     - PIO_OUTPUT_0
158 *     - PIO_OUTPUT_1
159 *     - PIO_INPUT
160 *
161 *  The #attribute# field is a bitmask that can either be set to PIO_DEFAULt,
162 *  or combine (using bitwise OR '|') any number of the following constants:
163 *     - PIO_PULLUP
164 *     - PIO_DEGLITCH
165 *     - PIO_DEBOUNCE
166 *     - PIO_OPENDRAIN
167 *     - PIO_IT_LOW_LEVEL
168 *     - PIO_IT_HIGH_LEVEL
169 *     - PIO_IT_FALL_EDGE
170 *     - PIO_IT_RISE_EDGE
171 */
172typedef struct _Pin {
173        /*  Bitmask indicating which pin(s) to configure. */
174        uint32_t mask;
175        /*  Pointer to the PIO controller which has the pin(s). */
176        Pio    *pio;
177        /*  Peripheral ID of the PIO controller which has the pin(s). */
178        uint8_t id;
179        /*  Pin type. */
180        uint8_t type;
181        /*  Pin attribute. */
182        uint8_t attribute;
183} Pin;
184
185/*
186 *         Global Access Macros
187 */
188
189/*
190 *         Global Functions
191 */
192
193extern uint8_t PIO_Configure(const Pin *list, uint32_t size);
194
195extern void PIO_Set(const Pin *pin);
196
197extern void PIO_Clear(const Pin *pin);
198
199extern uint8_t PIO_Get(const Pin *pin);
200
201extern uint8_t PIO_GetOutputDataStatus(const Pin *pin);
202
203extern void PIO_SetDebounceFilter(const Pin *pin, uint32_t cuttoff);
204
205extern void PIO_EnableWriteProtect(const Pin *pin);
206
207extern void PIO_DisableWriteProtect(const Pin *pin);
208
209extern void PIO_SetPinType(Pin *pin, uint8_t pinType);
210
211extern uint32_t PIO_GetWriteProtectViolationInfo(const Pin *pin);
212#ifdef __cplusplus
213}
214#endif
215
216#endif /* #ifndef _PIO_ */
217
Note: See TracBrowser for help on using the repository browser.