include/rtems/ramdisk.h

0001 /**
0002  * @file
0003  *
0004  * @brief RAM Disk Block Device API
0005  */
0006
0007 /*
0008  * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
0009  * Author: Victor V. Vengerov <vvv@oktet.ru>
0010  */
0011
0012 #ifndef _RTEMS_RAMDISK_H
0013 #define _RTEMS_RAMDISK_H
0014
0015
0016 #include <rtems.h>
0017 #include <rtems/blkdev.h>
0018
0019 #ifdef __cplusplus
0020 extern "C" {
0021 #endif
0022
0023 /**
0024  * @defgroup rtems_ramdisk RAM Disk Device
0025  *
0026  * @ingroup rtems_blkdev
0027  *
0028  */
0029 /**@{**/
0030
0031 /**
0032  * @name Static Configuration
0033  */
0034 /**@{**/
0035
0036 /**
0037  * @brief RAM disk configuration table entry.
0038  */
0039 typedef struct rtems_ramdisk_config {
0040   /**
0041    * @brief RAM disk block size.
0042    */
0043   uint32_t block_size;
0044
0045   /**
0046    * @brief Number of blocks on this RAM disk.
0047    */
0048   rtems_blkdev_bnum block_num;
0049
0050   /**
0051    * @brief RAM disk location or @c NULL if RAM disk memory should be allocated
0052    * dynamically.
0053    */
0054   void *location;
0055 } rtems_ramdisk_config;
0056
0057 /**
0058  * @brief External reference to the RAM disk configuration table describing
0059  * each RAM disk in the system.
0060  *
0061  * The configuration table is provided by the application.
0062  */
0063 extern rtems_ramdisk_config rtems_ramdisk_configuration [];
0064
0065 /**
0066  * @brief External reference the size of the RAM disk configuration table
0067  * @ref rtems_ramdisk_configuration.
0068  *
0069  * The configuration table size is provided by the application.
0070  */
0071 extern size_t rtems_ramdisk_configuration_size;
0072
0073 /**
0074  * @brief RAM disk driver initialization entry point.
0075  */
0076 rtems_device_driver ramdisk_initialize(
0077  rtems_device_major_number major,
0078  rtems_device_minor_number minor,
0079  void *arg
0080 );
0081
0082 /**
0083  * RAM disk driver table entry.
0084  */
0085 #define RAMDISK_DRIVER_TABLE_ENTRY \
0086   { \
0087     ramdisk_initialize, \
0088     NULL, NULL, NULL, NULL, NULL \
0089   }
0090
0091 #define RAMDISK_DEVICE_BASE_NAME "/dev/rd"
0092
0093 /** @} */
0094
0095 /**
0096  * @name Runtime Configuration
0097  */
0098 /**@{**/
0099
0100 /**
0101  * @brief RAM disk descriptor.
0102  */
0103 typedef struct ramdisk {
0104   /**
0105    * @brief RAM disk block size, the media size.
0106    */
0107   uint32_t block_size;
0108
0109   /**
0110    * @brief Number of blocks on this RAM disk.
0111    */
0112   rtems_blkdev_bnum block_num;
0113
0114   /**
0115    * @brief RAM disk memory area.
0116    */
0117   void *area;
0118
0119   /**
0120    * @brief RAM disk is initialized.
0121    */
0122   bool initialized;
0123
0124   /**
0125    * @brief Indicates if memory is allocated by malloc() for this RAM disk.
0126    */
0127   bool malloced;
0128
0129   /**
0130    * @brief Trace enable.
0131    */
0132   bool trace;
0133
0134   /**
0135    * @brief Free the RAM disk at the block device delete request.
0136    */
0137   bool free_at_delete_request;
0138 } ramdisk;
0139
0140 int ramdisk_ioctl(rtems_disk_device *dd, uint32_t req, void *argp);
0141
0142 /**
0143  * @brief Allocates and initializes a RAM disk descriptor.
0144  *
0145  * The block size will be @a media_block_size.  The block count will be
0146  * @a media_block_count.  The disk storage area begins at @a area_begin.  If
0147  * @a area_begin is @c NULL, the memory will be allocated and zeroed.  Sets the
0148  * trace enable to @a trace.
0149  *
0150  * @return Pointer to allocated and initialized ramdisk structure, or @c NULL
0151  * if no memory is available.
0152  *
0153  * @note
0154  * Runtime configuration example:
0155  * @code
0156  * #include <rtems/ramdisk.h>
0157  *
0158  * rtems_status_code create_ramdisk(
0159  *   const char *device,
0160  *   uint32_t media_block_size,
0161  *   rtems_blkdev_bnum media_block_count
0162  * )
0163  * {
0164  *   rtems_status_code sc;
0165  *   ramdisk *rd;
0166  *
0167  *   rd = ramdisk_allocate(NULL, media_block_size, media_block_count, false);
0168  *   if (rd != NULL) {
0169  *     sc = rtems_blkdev_create(
0170  *       device,
0171  *       media_block_size,
0172  *       media_block_count,
0173  *       ramdisk_ioctl,
0174  *       rd
0175  *     );
0176  *   } else {
0177  *     sc = RTEMS_UNSATISFIED;
0178  *   }
0179  *
0180  *   return sc;
0181  * }
0182  * @endcode
0183  */
0184 ramdisk *ramdisk_allocate(
0185   void *area_begin,
0186   uint32_t media_block_size,
0187   rtems_blkdev_bnum media_block_count,
0188   bool trace
0189 );
0190
0191 void ramdisk_free(ramdisk *rd);
0192
0193 static inline void ramdisk_enable_free_at_delete_request(ramdisk *rd)
0194 {
0195   rd->free_at_delete_request = true;
0196 }
0197
0198 /**
0199  * @brief Allocates, initializes and registers a RAM disk.
0200  *
0201  * The block size will be @a media_block_size.  The block count will be
0202  * @a media_block_count.  The disk storage will be allocated.  Sets the trace
0203  * enable to @a trace.  Registers a device node with disk name path @a disk.
0204  * The registered device number will be returned in @a dev.
0205  *
0206  * @retval RTEMS_SUCCESSFUL Successful operation.
0207  * @retval RTEMS_UNSATISFIED Something is wrong.
0208  */
0209 rtems_status_code ramdisk_register(
0210   uint32_t media_block_size,
0211   rtems_blkdev_bnum media_block_count,
0212   bool trace,
0213   const char *disk
0214 );
0215
0216 /** @} */
0217
0218 /** @} */
0219
0220 #ifdef __cplusplus
0221 }
0222 #endif
0223
0224 #endif