source: rtems/cpukit/libfs/src/dosfs/dosfs.h @ 83a4cbb

4.11
Last change on this file since 83a4cbb was 83a4cbb, checked in by Ralf Kirchner <ralf.kirchner@…>, on May 23, 2013 at 1:48:54 PM

dosfs: UTF-8 Support: Multibyte conversions

Add optional conversion methods for multibyte strings. With these
conversions which make use of iconv and utf8proc it becomes possible to
use strings from any language (Czech, Chinese, Arabian, Hebrew, Corean,
...) for file names and directory names.

NOTE: Iconv support must be activated during the build of the tool chain
for these conversion methods (options --enable-newlib-iconv
--enable-newlib-iconv-encodings=[ENCODINGS_YOU_WANT]). Alternatively
you can provide your own conversion methods.

  • Property mode set to 100644
File size: 9.4 KB
Line 
1/**
2 * @file
3 *
4 * @brief Application Interface to FAT Filesystem
5 *
6 * @ingroup DOSFS
7 */
8
9/*
10 *  Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia
11 *  Author: Eugeny S. Mints <Eugeny.Mints@oktet.ru>
12 *
13 *  Modifications to support UTF-8 in the file system are
14 *  Copyright (c) 2013 embedded brains GmbH.
15 *
16 *  The license and distribution terms for this file may be
17 *  found in the file LICENSE in this distribution or at
18 *  http://www.rtems.com/license/LICENSE.
19 */
20
21#ifndef _RTEMS_DOSFS_H
22#define _RTEMS_DOSFS_H
23
24#include <rtems.h>
25#include <rtems/libio.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31typedef struct rtems_dosfs_convert_control rtems_dosfs_convert_control;
32
33/**
34 * @brief Converts from UTF-8 into a specific code page.
35 *
36 * @param[in/out] self The convert control.
37 * @param[in] src A well-formed UTF-8 string to be converted.
38 * @param[in] src_size The size of the string in bytes (inludes '\0' if any).
39 * @param[out] dst The address the converted string will get copied to.
40 * @param[in/out] dst_size The size of the buffer in bytes respectively the
41 * number of bytes written to the buffer.
42 *
43 * @retval 0 Successful operation.
44 * @retval EINVAL Conversion was successful, but is not reversible.
45 * @retval ENOMEM Conversion failed (possibly due to insufficient buffer size).
46 */
47typedef int (*rtems_dosfs_utf8_to_codepage)(
48  rtems_dosfs_convert_control *self,
49  const uint8_t               *src,
50  size_t                       src_size,
51  char                        *dst,
52  size_t                      *dst_size
53);
54
55/**
56 * @brief Converts from a specific code page into UTF-8
57 *
58 * @param[in/out] self The convert control.
59 * @param[in] src A well-formed string in code page format.
60 * @param[in] src_size The size of the string in bytes (inludes '\0' if any).
61 * @param[out] dst The address the converted string will get copied to.
62 * @param[in/out] dst_size The size of the buffer in bytes respectively the
63 * number of bytes written to the buffer.
64 *
65 * @retval 0 Successful operation.
66 * @retval EINVAL Conversion was successful, but is not reversible.
67 * @retval ENOMEM Conversion failed (possibly due to insufficient buffer size).
68 */
69typedef int (*rtems_dosfs_codepage_to_utf8)(
70  rtems_dosfs_convert_control *self,
71  const char                  *src,
72  size_t                       src_size,
73  uint8_t                     *dst,
74  size_t                      *dst_size
75);
76
77/**
78 * @brief Converts from UTF-8 to UTF-16
79 *
80 * @param[in/out] self The convert control.
81 * @param[in] src A well-formed UTF-8 string to be converted.
82 * @param[in] src_size The size of the string in bytes (inludes '\0' if any).
83 * @param[out] dst The address the converted string will get copied to
84 * @param[in/out] dst_size The size of the buffer in bytes respectively the
85 * number of bytes written to the buffer.
86 *
87 * @retval 0 Successful operation.
88 * @retval EINVAL Conversion was successful, but is not reversible.
89 * @retval ENOMEM Conversion failed (possibly due to insufficient buffer size).
90 */
91typedef int (*rtems_dosfs_utf8_to_utf16)(
92  rtems_dosfs_convert_control *self,
93  const uint8_t               *src,
94  size_t                       src_size,
95  uint16_t                    *dst,
96  size_t                      *dst_size
97);
98
99/**
100 * @brief Converts from UTF-16 to UTF-8.
101 *
102 * @param[in/out] self The convert control.
103 * @param[in] src A well-formed UTF-16 string to be converted.
104 * @param[in] src_size The size of the string in bytes (inludes '\0' if any).
105 * @param[out] dst The address the converted string will get copied to.
106 * @param[in/out] dst_size The size of the buffer in bytes respectively the
107 * number of bytes written to the buffer
108 *
109 * @retval 0 Successful operation.
110 * @retval EINVAL Conversion was successful, but is not reversible.
111 * @retval ENOMEM Conversion failed (possibly due to insufficient buffer size).
112 */
113typedef int (*rtems_dosfs_utf16_to_utf8)(
114  rtems_dosfs_convert_control *self,
115  const uint16_t              *src,
116  size_t                       src_size,
117  uint8_t                     *dst,
118  size_t                      *dst_size
119);
120
121/**
122 * @brief Converts from UTF-8 to Normalized Form Canonical Decomposition.
123 *
124 * Does canonical decomposition of the UTF-8 string and in addition
125 * also converts upper case alphabetic characters to lower case characters
126 *
127 * @param[in/out] self The convert control.
128 * @param[in] src A well-formed UTF-8 string to be normalized and fold.
129 * @param[in] src_size The size of the string in bytes (inludes '\0' if any).
130 * @param[out] dst The address the normalized and fold string will get
131 * copied to.
132 * @param[in/out] dst_size The size of the buffer in bytes respectively the
133 * number of bytes written to the buffer.
134 *
135 * @retval 0 Successful operation.
136 * @retval EINVAL Conversion failed.
137 * @retval ENOMEM Conversion failed (possibly due to insufficient buffer size).
138 * @retval EOVERFLOW Conversion failed.
139 * @retval ENOENT Conversion failed.
140 */
141typedef int (*rtems_dosfs_utf8_normalize_and_fold)(
142  rtems_dosfs_convert_control *self,
143  const uint8_t               *src,
144  size_t                       src_size,
145  uint8_t                     *dst,
146  size_t                      *dst_size
147);
148
149/**
150 * @brief Destroys a convert control structure.
151 *
152 * @param[in/out] self The convert control for destruction.
153 */
154typedef void (*rtems_dosfs_convert_destroy)(
155  rtems_dosfs_convert_control *self
156);
157
158/**
159 * @brief FAT filesystem convert handler.
160 */
161typedef struct {
162  rtems_dosfs_utf8_to_codepage        utf8_to_codepage;
163  rtems_dosfs_codepage_to_utf8        codepage_to_utf8;
164  rtems_dosfs_utf8_to_utf16           utf8_to_utf16;
165  rtems_dosfs_utf16_to_utf8           utf16_to_utf8;
166  rtems_dosfs_utf8_normalize_and_fold utf8_normalize_and_fold;
167  rtems_dosfs_convert_destroy         destroy;
168} rtems_dosfs_convert_handler;
169
170typedef struct {
171  void   *data;
172  size_t  size;
173} rtems_dosfs_buffer;
174
175/**
176 * @brief FAT filesystem convert control.
177 *
178 * Short file names are stored in the code page format.  Long file names are
179 * stored as little-endian UTF-16.  The convert control determines the format
180 * conversions to and from the POSIX file name strings.
181 */
182struct rtems_dosfs_convert_control {
183  const rtems_dosfs_convert_handler *handler;
184  rtems_dosfs_buffer                 buffer;
185};
186
187/**
188 * @defgroup DOSFS FAT Filesystem Support
189 *
190 * @ingroup FileSystemTypesAndMount
191 *
192 * @{
193 */
194
195/**
196 * @brief Semaphore count per FAT filesystem instance.
197 *
198 * This can be used for system configuration via <rtems/confdefs.h>.
199 */
200#define RTEMS_DOSFS_SEMAPHORES_PER_INSTANCE 1
201
202/**
203 * @brief FAT filesystem mount options.
204 */
205typedef struct {
206  /**
207   * @brief Converter implementation for new filesystem instance.
208   *
209   * @see rtems_dosfs_create_default_converter() and
210   * rtems_dosfs_create_utf8_converter().
211   */
212  rtems_dosfs_convert_control *converter;
213} rtems_dosfs_mount_options;
214
215/**
216 * @brief Allocates and initializes a default converter.
217 *
218 * @retval NULL Something failed.
219 * @retval other Pointer to initialized converter.
220 *
221 * @see rtems_dosfs_mount_options and mount().
222 */
223rtems_dosfs_convert_control *rtems_dosfs_create_default_converter(void);
224
225/**
226 * @brief Allocates and initializes a UTF-8 converter.
227 *
228 * @param[in] codepage The iconv() identification string for the used codepage.
229 *
230 * @retval NULL Something failed.
231 * @retval other Pointer to initialized converter.
232 *
233 * @see rtems_dosfs_mount_options and mount().
234 */
235rtems_dosfs_convert_control *rtems_dosfs_create_utf8_converter(
236  const char *codepage
237);
238
239#define MSDOS_FMT_INFO_LEVEL_NONE   (0)
240#define MSDOS_FMT_INFO_LEVEL_INFO   (1)
241#define MSDOS_FMT_INFO_LEVEL_DETAIL (2)
242#define MSDOS_FMT_INFO_LEVEL_DEBUG  (3)
243
244/**
245 * @brief FAT file system format request parameters.
246 */
247typedef struct {
248  /**
249   * @brief OEM name string or NULL.
250   */
251  const char *OEMName;
252
253  /**
254   * @brief Volume label string or NULL.
255   */
256  const char *VolLabel;
257
258  /**
259   * @brief Sectors per cluster hint.
260   *
261   * The format procedure may choose another value.  Use 0 as default value.
262   */
263  uint32_t sectors_per_cluster;
264
265  /**
266   * @brief Number of FATs hint.
267   *
268   * Use 0 as default value.
269   */
270  uint32_t fat_num;
271
272  /**
273   * @brief Minimum files in root directory for FAT12 and FAT16.
274   *
275   * The format procedure may choose a greater value.  Use 0 as default value.
276   */
277  uint32_t files_per_root_dir;
278
279  /**
280   * @brief Media code.
281   *
282   * Use 0 as default value.  The default media code is 0xf8.
283   */
284  uint8_t media;
285
286  /**
287   * @brief Quick format.
288   *
289   * If set to true, then do not clear data sectors to zero.
290   */
291  bool quick_format;
292
293  /**
294   * @brief Do not align FAT, data cluster, and root directory to a cluster
295   * boundary.
296   */
297  bool skip_alignment;
298
299  /**
300   * @brief Synchronize device after write operations.
301   */
302  bool sync_device;
303
304  /**
305   * @brief The amount of info to output.
306   */
307  int info_level;
308} msdos_format_request_param_t;
309
310/**
311 * @brief Formats a block device with a FAT file system.
312 *
313 * @param[in] devname The block device path.
314 * @param[in] rqdata The FAT file system format request data.  Use NULL for
315 * default parameters.
316 *
317 * @retval 0 Successful operation.
318 * @retval -1 An error occurred.  The @c errno indicates the error.
319 */
320int msdos_format (
321  const char *devname,
322  const msdos_format_request_param_t *rqdata
323);
324
325/** @} */
326
327int rtems_dosfs_initialize(rtems_filesystem_mount_table_entry_t *mt_entry,
328                           const void                           *data);
329
330#ifdef __cplusplus
331}
332#endif
333
334#endif
Note: See TracBrowser for help on using the repository browser.