source: rtems/cpukit/include/rtems/nvdisk.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: 6.6 KB
Line 
1/**
2 * @file rtems/nvdisk.h
3 *
4 * @brief Non-volatile Disk Block Device Implementation
5 */
6
7/*
8 * Copyright (C) 2007 Chris Johns
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/**
16 * The Non-volatile disk provides a simple directly mapped disk
17 * driver with checksums for each. It is designed to provied a
18 * disk that can survive a restart. Examples are EEPROM devices
19 * which have byte writeable locations, or a battery backed up
20 * RAM disk.
21 *
22 * The low level driver provides the physical access to the
23 * hardware.
24 */
25#if !defined (_RTEMS_NVDISK_H_)
26#define _RTEMS_NVDISK_H_
27
28#include <stdint.h>
29#include <sys/ioctl.h>
30
31#include <rtems.h>
32
33/**
34 * The base name of the nv disks.
35 */
36#define RTEMS_NVDISK_DEVICE_BASE_NAME "/dev/nvd"
37
38/**
39 * NV disk specific ioctl request types. To use open the
40 * device and issue the ioctl call.
41 *
42 * @code
43 *  int fd = open ("/dev/nvdisk0", O_WRONLY, 0);
44 *  if (fd < 0)
45 *  {
46 *    printf ("driver open failed: %s\n", strerror (errno));
47 *    exit (1);
48 *  }
49 *  if (ioctl (fd, RTEMS_NVDISK_IOCTL_ERASE_DISK) < 0)
50 *  {
51 *    printf ("driver erase failed: %s\n", strerror (errno));
52 *    exit (1);
53 *  }
54 *  close (fd);
55 * @endcode
56 */
57#define RTEMS_NVDISK_IOCTL_ERASE_DISK   _IO('B', 128)
58#define RTEMS_NVDISK_IOCTL_MONITORING   _IO('B', 129)
59#define RTEMS_NVDISK_IOCTL_INFO_LEVEL   _IO('B', 130)
60#define RTEMS_NVDISK_IOCTL_PRINT_STATUS _IO('B', 131)
61
62/**
63 * NV Disk Monitoring Data allows a user to obtain
64 * the current status of the disk.
65 */
66typedef struct rtems_nvdisk_monitor_data
67{
68  uint32_t block_size;
69  uint32_t block_count;
70  uint32_t page_count;
71  uint32_t pages_available;
72  uint32_t pages_used;
73  uint32_t info_level;
74} rtems_nvdisk_monitor_data;
75
76/**
77 * Return the number of kilo-bytes.
78 */
79#define RTEMS_NVDISK_KBYTES(_k) ((_k) * 1024)
80
81/**
82 * NV Low Level driver handlers.
83
84 * Typically this structure is part of a table of handlers in the
85 * device which is referenced in the nvdisk configuration table.
86 * The reference is kept in the driver and used all the time to
87 * manage the nv device, therefore it must always exist.
88 */
89typedef struct rtems_nvdisk_driver_handlers
90{
91  /**
92   * Read data from the device into the buffer. Return an errno
93   * error number if the data cannot be read.
94   *
95   * @param device The device to read data from.
96   * @param flags Device specific flags for the driver.
97   * @param base The base address of the device.
98   * @param offset The offset in the segment to read.
99   * @param buffer The buffer to read the data into.
100   * @param size The amount of data to read.
101   * @retval 0 No error.
102   * @retval EIO The read did not complete.
103   */
104  int (*read) (uint32_t device, uint32_t flags, void* base,
105               uint32_t offset, void* buffer, size_t size);
106
107  /**
108   * Write data from the buffer to the device. Return an errno
109   * error number if the device cannot be written to.
110   *
111   * @param device The device to write data to.
112   * @param flags Device specific flags for the driver.
113   * @param base The base address of the device.
114   * @param offset The offset in the device to write to.
115   * @param buffer The buffer to write the data from.
116   * @param size The amount of data to write.
117   * @retval 0 No error.
118   * @retval EIO The write did not complete or verify.
119   */
120  int (*write) (uint32_t device, uint32_t flags, void* base,
121                uint32_t offset, const void* buffer, size_t size);
122
123  /**
124   * Verify data in the buffer to the data in the device. Return an
125   * errno error number if the device cannot be read or the data verified.
126   *
127   * @param device The device to verify the data with.
128   * @param flags Device specific flags for the driver.
129   * @param base The base address of the device.
130   * @param offset The offset in the device to verify.
131   * @param buffer The buffer to verify the data in the device with.
132   * @param size The amount of data to verify.
133   * @retval 0 No error.
134   * @retval EIO The data did not verify.
135   */
136  int (*verify) (uint32_t device, uint32_t flags, void* base,
137                 uint32_t offset, const void* buffer, size_t size);
138
139} rtems_nvdisk_driver_handlers;
140
141/**
142 * NV Device Descriptor holds the description of a device that is
143 * part of the NV disk.
144 *
145 * Typically this structure is part of a table of the device which
146 * is referenced in the nvdisk configuration table.
147 * The reference is kept in the driver and used all the time to
148 * manage the nv device, therefore it must always exist.
149 */
150typedef struct rtems_nvdisk_device_desc
151{
152  uint32_t                            flags;  /**< Private user flags. */
153  void*                               base;   /**< Base address of the device. */
154  uint32_t                            size;   /**< Size of the device. */
155  const rtems_nvdisk_driver_handlers* nv_ops; /**< Device handlers. */
156} rtems_nvdisk_device_desc;
157
158/**
159 * RTEMS Non-Volatile Disk configuration table used to initialise the
160 * driver.
161 */
162typedef struct rtems_nvdisk_config
163{
164  uint32_t                        block_size;   /**< The block size. */
165  uint32_t                        device_count; /**< The number of devices. */
166  const rtems_nvdisk_device_desc* devices;      /**< The device descriptions. */
167  uint32_t                        flags;        /**< Set of flags to control
168                                                     driver. */
169  uint32_t                        info_level;   /**< Default info level. */
170} rtems_nvdisk_config;
171
172/*
173 * Driver flags.
174 */
175
176/**
177 * Check the pages during initialisation to see which pages are
178 * valid and which are not. This could slow down initialising the
179 * disk driver.
180 */
181#define RTEMS_NVDISK_CHECK_PAGES (1 << 0)
182
183/**
184 * Non-volatile disk device driver initialization. Place in a table as the
185 * initialisation entry and remainder of the entries are the RTEMS block
186 * device generic handlers.
187 *
188 * @param major NV disk major device number.
189 * @param minor Minor device number, not applicable.
190 * @param arg Initialization argument, not applicable.
191 * @return The rtems_device_driver is actually just
192 *         rtems_status_code.
193 */
194rtems_device_driver
195rtems_nvdisk_initialize (rtems_device_major_number major,
196                         rtems_device_minor_number minor,
197                         void*                     arg);
198
199/**
200 * External reference to the configuration. Please supply.
201 * Support is present in confdefs.h for providing this variable.
202 */
203extern const rtems_nvdisk_config rtems_nvdisk_configuration[];
204
205/**
206 * External reference to the number of configurations. Please supply.
207 * Support is present in confdefs.h for providing this variable.
208 */
209extern uint32_t rtems_nvdisk_configuration_size;
210
211#endif
Note: See TracBrowser for help on using the repository browser.