include/rtems/sparse-disk.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup rtems_sparse_disk
0007  *
0008  * @brief Sparse disk block device API.
0009  */
0010
0011 /*
0012  * Copyright (c) 2012 embedded brains GmbH & Co. KG
0013  *
0014  * Redistribution and use in source and binary forms, with or without
0015  * modification, are permitted provided that the following conditions
0016  * are met:
0017  * 1. Redistributions of source code must retain the above copyright
0018  *    notice, this list of conditions and the following disclaimer.
0019  * 2. Redistributions in binary form must reproduce the above copyright
0020  *    notice, this list of conditions and the following disclaimer in the
0021  *    documentation and/or other materials provided with the distribution.
0022  *
0023  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0024  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0025  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0026  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0027  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0028  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0029  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0030  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0031  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0032  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0033  * POSSIBILITY OF SUCH DAMAGE.
0034  */
0035
0036 #ifndef SPARSE_DISK_H
0037 #define SPARSE_DISK_H
0038
0039 #include <stddef.h>
0040 #include <stdint.h>
0041 #include <rtems.h>
0042 #include <rtems/diskdevs.h>
0043 #include <rtems/thread.h>
0044
0045 #ifdef __cplusplus
0046 extern "C" {
0047 #endif /* __cplusplus */
0048
0049 /**
0050  * @defgroup rtems_sparse_disk Sparse Disk Device
0051  *
0052  * @ingroup rtems_blkdev
0053  *
0054  */
0055 /**@{**/
0056
0057 typedef struct {
0058   rtems_blkdev_bnum  block;
0059   void              *data;
0060 } rtems_sparse_disk_key;
0061
0062 typedef struct rtems_sparse_disk rtems_sparse_disk;
0063
0064 typedef void (*rtems_sparse_disk_delete_handler)(rtems_sparse_disk *sparse_disk);
0065
0066 struct rtems_sparse_disk {
0067   rtems_mutex                      mutex;
0068   rtems_blkdev_bnum                blocks_with_buffer;
0069   size_t                           used_count;
0070   uint32_t                         media_block_size;
0071   rtems_sparse_disk_delete_handler delete_handler;
0072   uint8_t                          fill_pattern;
0073   rtems_sparse_disk_key           *key_table;
0074 };
0075
0076 /**
0077  * @brief Creates and registers a sparse disk.
0078  *
0079  * @param[in] device_file_name The device file name path.
0080  * @param[in] media_block_size The media block size in bytes.
0081  * @param[in] blocks_with_buffer Blocks of the device with a buffer.  Other
0082  * blocks can store only fill pattern value bytes.
0083  * @param[in] block_count The media block count of the device.  It is the sum
0084  * of blocks with buffer and blocks that contain only fill pattern value bytes.
0085  * @param[in] fill_pattern The fill pattern specifies the byte value of blocks
0086  * without a buffer.  It is also the initial value for blocks with a buffer.
0087  *
0088  * @retval RTEMS_SUCCESSFUL Successful operation.
0089  * @retval RTEMS_INVALID_NUMBER Media block size or media block count is not
0090  * positive.  The blocks with buffer count is greater than the media block count.
0091  * @retval RTEMS_NO_MEMORY Not enough memory.
0092  * @retval RTEMS_TOO_MANY Cannot create semaphore.
0093  * @retval RTEMS_UNSATISFIED Cannot create generic device node.
0094  *
0095  * @see rtems_sparse_disk_register().
0096  */
0097 rtems_status_code rtems_sparse_disk_create_and_register(
0098   const char        *device_file_name,
0099   uint32_t           media_block_size,
0100   rtems_blkdev_bnum  blocks_with_buffer,
0101   rtems_blkdev_bnum  media_block_count,
0102   uint8_t            fill_pattern
0103 );
0104
0105 /**
0106  * @brief Frees a sparse disk.
0107  *
0108  * Calls free() on the sparse disk pointer.
0109  */
0110 void rtems_sparse_disk_free( rtems_sparse_disk *sparse_disk );
0111
0112 /**
0113  * @brief Initializes and registers a sparse disk.
0114  *
0115  * This will create one semaphore for mutual exclusion.
0116  *
0117  * @param[in] device_file_name The device file name path.
0118  * @param[in, out] sparse_disk The sparse disk.
0119  * @param[in] media_block_size The media block size in bytes.
0120  * @param[in] blocks_with_buffer Blocks of the device with a buffer.  Other
0121  * blocks can store only fill pattern value bytes.
0122  * @param[in] block_count The media block count of the device.  It is the sum
0123  * of blocks with buffer and blocks that contain only fill pattern value bytes.
0124  * @param[in] fill_pattern The fill pattern specifies the byte value of blocks
0125  * without a buffer.  It is also the initial value for blocks with a buffer.
0126  * @param[in] sparse_disk_delete The sparse disk delete handler.
0127  *
0128  * @retval RTEMS_SUCCESSFUL Successful operation.
0129  * @retval RTEMS_INVALID_NUMBER Media block size or media block count is not
0130  * positive.  The blocks with buffer count is greater than the media block count.
0131  * @retval RTEMS_INVALID_ADDRESS Invalid sparse disk address.
0132  * @retval RTEMS_TOO_MANY Cannot create semaphore.
0133  * @retval RTEMS_UNSATISFIED Cannot create generic device node.
0134  */
0135 rtems_status_code rtems_sparse_disk_register(
0136   const char                       *device_file_name,
0137   rtems_sparse_disk                *sparse_disk,
0138   uint32_t                          media_block_size,
0139   rtems_blkdev_bnum                 blocks_with_buffer,
0140   rtems_blkdev_bnum                 media_block_count,
0141   uint8_t                           fill_pattern,
0142   rtems_sparse_disk_delete_handler  sparse_disk_delete
0143 );
0144
0145 /** @} */
0146
0147 #ifdef __cplusplus
0148 }
0149 #endif /* __cplusplus */
0150
0151 #endif /* SPARSE_DISK_H */