include/rtems/nvdisk.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief Non-volatile Disk Block Device Implementation
0007  */
0008
0009 /*
0010  * Copyright (C) 2007 Chris Johns
0011  *
0012  * Redistribution and use in source and binary forms, with or without
0013  * modification, are permitted provided that the following conditions
0014  * are met:
0015  * 1. Redistributions of source code must retain the above copyright
0016  *    notice, this list of conditions and the following disclaimer.
0017  * 2. Redistributions in binary form must reproduce the above copyright
0018  *    notice, this list of conditions and the following disclaimer in the
0019  *    documentation and/or other materials provided with the distribution.
0020  *
0021  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0022  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0023  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0024  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0025  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0026  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0027  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0028  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0029  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0030  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0031  * POSSIBILITY OF SUCH DAMAGE.
0032  */
0033
0034 /**
0035  * The Non-volatile disk provides a simple directly mapped disk
0036  * driver with checksums for each. It is designed to provied a
0037  * disk that can survive a restart. Examples are EEPROM devices
0038  * which have byte writeable locations, or a battery backed up
0039  * RAM disk.
0040  *
0041  * The low level driver provides the physical access to the
0042  * hardware.
0043  */
0044 #if !defined (_RTEMS_NVDISK_H_)
0045 #define _RTEMS_NVDISK_H_
0046
0047 #include <stdint.h>
0048 #include <sys/ioctl.h>
0049
0050 #include <rtems.h>
0051
0052 #ifdef __cplusplus
0053 extern "C" {
0054 #endif /* __cplusplus */
0055
0056 /**
0057  * The base name of the nv disks.
0058  */
0059 #define RTEMS_NVDISK_DEVICE_BASE_NAME "/dev/nvd"
0060
0061 /**
0062  * NV disk specific ioctl request types. To use open the
0063  * device and issue the ioctl call.
0064  *
0065  * @code
0066  *  int fd = open ("/dev/nvdisk0", O_WRONLY, 0);
0067  *  if (fd < 0)
0068  *  {
0069  *    printf ("driver open failed: %s\n", strerror (errno));
0070  *    exit (1);
0071  *  }
0072  *  if (ioctl (fd, RTEMS_NVDISK_IOCTL_ERASE_DISK) < 0)
0073  *  {
0074  *    printf ("driver erase failed: %s\n", strerror (errno));
0075  *    exit (1);
0076  *  }
0077  *  close (fd);
0078  * @endcode
0079  */
0080 #define RTEMS_NVDISK_IOCTL_ERASE_DISK   _IO('B', 128)
0081 #define RTEMS_NVDISK_IOCTL_MONITORING   _IO('B', 129)
0082 #define RTEMS_NVDISK_IOCTL_INFO_LEVEL   _IO('B', 130)
0083 #define RTEMS_NVDISK_IOCTL_PRINT_STATUS _IO('B', 131)
0084
0085 /**
0086  * NV Disk Monitoring Data allows a user to obtain
0087  * the current status of the disk.
0088  */
0089 typedef struct rtems_nvdisk_monitor_data
0090 {
0091   uint32_t block_size;
0092   uint32_t block_count;
0093   uint32_t page_count;
0094   uint32_t pages_available;
0095   uint32_t pages_used;
0096   uint32_t info_level;
0097 } rtems_nvdisk_monitor_data;
0098
0099 /**
0100  * Return the number of kilo-bytes.
0101  */
0102 #define RTEMS_NVDISK_KBYTES(_k) ((_k) * 1024)
0103
0104 /**
0105  * NV Low Level driver handlers.
0106
0107  * Typically this structure is part of a table of handlers in the
0108  * device which is referenced in the nvdisk configuration table.
0109  * The reference is kept in the driver and used all the time to
0110  * manage the nv device, therefore it must always exist.
0111  */
0112 typedef struct rtems_nvdisk_driver_handlers
0113 {
0114   /**
0115    * Read data from the device into the buffer. Return an errno
0116    * error number if the data cannot be read.
0117    *
0118    * @param device The device to read data from.
0119    * @param flags Device specific flags for the driver.
0120    * @param base The base address of the device.
0121    * @param offset The offset in the segment to read.
0122    * @param buffer The buffer to read the data into.
0123    * @param size The amount of data to read.
0124    * @retval 0 No error.
0125    * @retval EIO The read did not complete.
0126    */
0127   int (*read) (uint32_t device, uint32_t flags, void* base,
0128                uint32_t offset, void* buffer, size_t size);
0129
0130   /**
0131    * Write data from the buffer to the device. Return an errno
0132    * error number if the device cannot be written to.
0133    *
0134    * @param device The device to write data to.
0135    * @param flags Device specific flags for the driver.
0136    * @param base The base address of the device.
0137    * @param offset The offset in the device to write to.
0138    * @param buffer The buffer to write the data from.
0139    * @param size The amount of data to write.
0140    * @retval 0 No error.
0141    * @retval EIO The write did not complete or verify.
0142    */
0143   int (*write) (uint32_t device, uint32_t flags, void* base,
0144                 uint32_t offset, const void* buffer, size_t size);
0145
0146   /**
0147    * Verify data in the buffer to the data in the device. Return an
0148    * errno error number if the device cannot be read or the data verified.
0149    *
0150    * @param device The device to verify the data with.
0151    * @param flags Device specific flags for the driver.
0152    * @param base The base address of the device.
0153    * @param offset The offset in the device to verify.
0154    * @param buffer The buffer to verify the data in the device with.
0155    * @param size The amount of data to verify.
0156    * @retval 0 No error.
0157    * @retval EIO The data did not verify.
0158    */
0159   int (*verify) (uint32_t device, uint32_t flags, void* base,
0160                  uint32_t offset, const void* buffer, size_t size);
0161
0162 } rtems_nvdisk_driver_handlers;
0163
0164 /**
0165  * NV Device Descriptor holds the description of a device that is
0166  * part of the NV disk.
0167  *
0168  * Typically this structure is part of a table of the device which
0169  * is referenced in the nvdisk configuration table.
0170  * The reference is kept in the driver and used all the time to
0171  * manage the nv device, therefore it must always exist.
0172  */
0173 typedef struct rtems_nvdisk_device_desc
0174 {
0175   uint32_t                            flags;  /**< Private user flags. */
0176   void*                               base;   /**< Base address of the device. */
0177   uint32_t                            size;   /**< Size of the device. */
0178   const rtems_nvdisk_driver_handlers* nv_ops; /**< Device handlers. */
0179 } rtems_nvdisk_device_desc;
0180
0181 /**
0182  * RTEMS Non-Volatile Disk configuration table used to initialise the
0183  * driver.
0184  */
0185 typedef struct rtems_nvdisk_config
0186 {
0187   uint32_t                        block_size;   /**< The block size. */
0188   uint32_t                        device_count; /**< The number of devices. */
0189   const rtems_nvdisk_device_desc* devices;      /**< The device descriptions. */
0190   uint32_t                        flags;        /**< Set of flags to control
0191                                                      driver. */
0192   uint32_t                        info_level;   /**< Default info level. */
0193 } rtems_nvdisk_config;
0194
0195 /*
0196  * Driver flags.
0197  */
0198
0199 /**
0200  * Check the pages during initialisation to see which pages are
0201  * valid and which are not. This could slow down initialising the
0202  * disk driver.
0203  */
0204 #define RTEMS_NVDISK_CHECK_PAGES (1 << 0)
0205
0206 /**
0207  * Non-volatile disk device driver initialization. Place in a table as the
0208  * initialisation entry and remainder of the entries are the RTEMS block
0209  * device generic handlers.
0210  *
0211  * @param major NV disk major device number.
0212  * @param minor Minor device number, not applicable.
0213  * @param arg Initialization argument, not applicable.
0214  * @return The rtems_device_driver is actually just
0215  *         rtems_status_code.
0216  */
0217 rtems_device_driver
0218 rtems_nvdisk_initialize (rtems_device_major_number major,
0219                          rtems_device_minor_number minor,
0220                          void*                     arg);
0221
0222 /**
0223  * External reference to the configuration. Please supply.
0224  * Support is present in confdefs.h for providing this variable.
0225  */
0226 extern const rtems_nvdisk_config rtems_nvdisk_configuration[];
0227
0228 /**
0229  * External reference to the number of configurations. Please supply.
0230  * Support is present in confdefs.h for providing this variable.
0231  */
0232 extern uint32_t rtems_nvdisk_configuration_size;
0233
0234 #ifdef __cplusplus
0235 }
0236 #endif /* __cplusplus */
0237
0238 #endif