source: rtems/cpukit/libblock/include/rtems/bdpart.h @ 9ab091e

4.11
Last change on this file since 9ab091e was 9ab091e, checked in by Mathew Kallada <matkallada@…>, on Dec 28, 2012 at 4:35:32 PM

Header File Doxygen Enhancement Task #2

  • Property mode set to 100644
File size: 11.6 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup rtems_bdpart
5 *
6 * @brief Block Device Partition Management
7 */
8
9/*
10 * Copyright (c) 2009-2012 embedded brains GmbH.  All rights reserved.
11 *
12 *  embedded brains GmbH
13 *  Obere Lagerstr. 30
14 *  82178 Puchheim
15 *  Germany
16 *  <rtems@embedded-brains.de>
17 *
18 * The license and distribution terms for this file may be
19 * found in the file LICENSE in this distribution or at
20 * http://www.rtems.com/license/LICENSE.
21 */
22
23#ifndef RTEMS_BDPART_H
24#define RTEMS_BDPART_H
25
26#include <uuid/uuid.h>
27
28#include <rtems.h>
29#include <rtems/blkdev.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif /* __cplusplus */
34
35/**
36 * @defgroup rtems_bdpart Block Device Partition Management
37 *
38 * @ingroup rtems_libblock
39 *
40 * @brief This module provides functions to manage partitions of a disk device.
41 *
42 * A @ref rtems_disk "disk" is a set of blocks which are identified by a
43 * consecutive set of non-negative integers starting at zero.  There are also
44 * logical disks which contain a subset of consecutive disk blocks.  The
45 * logical disks are used to represent the partitions of a disk. The disk
46 * devices are accessed via the @ref rtems_disk "block device buffer module".
47 *
48 * The partition format on the physical disk will be converted to an internal
49 * representation.  It is possible to convert the internal representation into
50 * a specific output format and write it to the physical disk.  One of the
51 * constrains for the internal representation was to support the GPT format
52 * easily.
53 *
54 * Currently two physical partition formats are supported.  These are the MBR
55 * and the GPT format.  Please note that the GPT support is not implemented.
56 * With MBR format we mean the partition format of the wide spread IBM
57 * PC-compatible systems.  The GPT format is defined in the Extensible Firmware
58 * Interface (EFI).
59 *
60 * The most common task will be to read the partition information of a disk and
61 * register logical disks for each partition.  This can be done with the
62 * rtems_bdpart_register_from_disk() function.  Afterwards you can
63 * @ref rtems_fsmount "mount" the file systems within the partitions.
64 *
65 * You can read the partition information from a disk with rtems_bdpart_read()
66 * and write it to the disk with rtems_bdpart_write().
67 *
68 * To create a partition table from scratch for a disk use
69 * rtems_bdpart_create().
70 *
71 * You can access some disk functions with the shell command @c fdisk.
72 *
73 * References used to create this module:
74 *  - <a href="http://en.wikipedia.org/wiki/UUID">Universally Unique Identifier</a>
75 *  - <a href="http://en.wikipedia.org/wiki/Globally_Unique_Identifier">Globally Unique Identifier</a>
76 *  - <a href="http://en.wikipedia.org/wiki/Disk_partitioning">Disk Paritioning</a>
77 *  - <a href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID Partition Table</a>
78 *  - <a href="http://en.wikipedia.org/wiki/Master_boot_record">Master Boot Record</a>
79 *  - <a href="http://en.wikipedia.org/wiki/Extended_boot_record">Extended Boot Record</a>
80 *  - <a href="http://en.wikipedia.org/wiki/Cylinder-head-sector">Cylinder Head Sector</a>
81 *  - <a href="http://www.win.tue.nl/~aeb/partitions/partition_types-1.html">Partition Types</a>
82 *
83 * @{
84 */
85
86/**
87 * @name MBR Partition Types and Flags
88 *
89 * @{
90 */
91
92#define RTEMS_BDPART_MBR_EMPTY 0x0U
93
94#define RTEMS_BDPART_MBR_FAT_12 0x1U
95
96#define RTEMS_BDPART_MBR_FAT_16 0x4U
97
98#define RTEMS_BDPART_MBR_FAT_16_LBA 0xeU
99
100#define RTEMS_BDPART_MBR_FAT_32 0xbU
101
102#define RTEMS_BDPART_MBR_FAT_32_LBA 0xcU
103
104#define RTEMS_BDPART_MBR_EXTENDED 0x5U
105
106#define RTEMS_BDPART_MBR_DATA 0xdaU
107
108#define RTEMS_BDPART_MBR_GPT 0xeeU
109
110#define RTEMS_BDPART_MBR_FLAG_ACTIVE 0x80U
111
112/** @} */
113
114/**
115 * Recommended maximum partition table size.
116 */
117#define RTEMS_BDPART_PARTITION_NUMBER_HINT 16
118
119/**
120 * Partition description.
121 */
122typedef struct rtems_bdpart_partition {
123  /**
124   * Block index for partition begin.
125   */
126  rtems_blkdev_bnum begin;
127
128  /**
129   * Block index for partition end (this block is not a part of the partition).
130   */
131  rtems_blkdev_bnum end;
132
133  /**
134   * Partition type.
135   */
136  uuid_t type;
137
138  /**
139   * Partition ID.
140   */
141  uuid_t id;
142
143  /**
144   * Partition flags.
145   */
146  uint64_t flags;
147} rtems_bdpart_partition;
148
149/**
150 * Disk format for the partition tables.
151 */
152typedef enum {
153  /**
154   * Type value for MBR format.
155   */
156  RTEMS_BDPART_FORMAT_MBR,
157
158  /**
159   * Type value for GPT format.
160   */
161  RTEMS_BDPART_FORMAT_GPT
162} rtems_bdpart_format_type;
163
164/**
165 * Disk format description.
166 */
167typedef union {
168  /**
169   * Format type.
170   */
171  rtems_bdpart_format_type type;
172
173  /**
174   * MBR format fields.
175   */
176  struct {
177    rtems_bdpart_format_type type;
178
179    /**
180     * Disk ID in MBR at offset 440.
181     */
182    uint32_t disk_id;
183
184    /**
185     * This option is used for partition table creation and validation checks
186     * before a write to the disk.  It ensures that the first primary
187     * partition and the logical partitions start at head one and sector one
188     * under the virtual one head and 63 sectors geometry.  Each begin and
189     * end of a partition will be aligned to the virtual cylinder boundary.
190     */
191    bool dos_compatibility;
192  } mbr;
193
194  /**
195   * GPT format fields.
196   */
197  struct {
198    rtems_bdpart_format_type type;
199
200    /**
201     * Disk ID in GPT header.
202     */
203    uuid_t disk_id;
204  } gpt;
205} rtems_bdpart_format;
206
207/**
208 * @brief Reads the partition information from the physical disk device with
209 * name @a disk_name.
210 *
211 * The partition information will be stored in the partition table
212 * @a partitions with a maximum of @a count partitions.  The number of actual
213 * partitions will be stored in @a count.  If there are more partitions than
214 * space for storage an error status will be returned.  The partition table
215 * format recognized on the disk will be stored in @a format.
216 */
217rtems_status_code rtems_bdpart_read(
218  const char *disk_name,
219  rtems_bdpart_format *format,
220  rtems_bdpart_partition *partitions,
221  size_t *count
222);
223
224/**
225 * @brief Sorts the partition table @a partitions with @a count partitions to
226 * have ascending begin blocks
227 */
228void rtems_bdpart_sort( rtems_bdpart_partition *partitions, size_t count);
229
230/**
231 * @brief Writes the partition table to the physical disk device with name
232 * @a disk_name.
233 *
234 * The partition table @a partitions with @a count partitions will be written
235 * to the disk.  The output format for the partition table on the disk is
236 * specified by @a format.  There are some consistency checks applied to the
237 * partition table.  The partition table must be sorted such that the begin
238 * blocks are in ascending order.  This can be done with the
239 * rtems_bdpart_sort() function.  The partitions must not overlap.  The
240 * partitions must have a positive size.  The partitions must be within the
241 * disk.  Depending on the output format there are additional constrains.
242 */
243rtems_status_code rtems_bdpart_write(
244  const char *disk_name,
245  const rtems_bdpart_format *format,
246  const rtems_bdpart_partition *partitions,
247  size_t count
248);
249
250/**
251 * @brief Creates a partition table in @a partitions with @a count partitions
252 * for the physical disk device with name @a disk_name.
253 *
254 * The array of positive integer weights in @a distribution must have exactly
255 * @a count elements.  The weights in the distribution array are summed up.
256 * Each weight is then divided by the sum to obtain the disk fraction which
257 * forms the corresponding partition.  The partition boundaries are generated
258 * with respect to the output format in @a format.
259 */
260rtems_status_code rtems_bdpart_create(
261  const char *disk_name,
262  const rtems_bdpart_format *format,
263  rtems_bdpart_partition *partitions,
264  const unsigned *distribution,
265  size_t count
266);
267
268/**
269 * @brief Registers the partitions as logical disks for the physical disk
270 * device with name @a disk_name.
271 *
272 * For each partition of the partition table @a partitions with @a count
273 * partitions a logical disk is registered.  The partition number equals the
274 * partition table index plus one.  The name of the logical disk device is the
275 * concatenation of the physical disk device name and the partition number.
276 *
277 * @see rtems_blkdev_create_partition().
278 */
279rtems_status_code rtems_bdpart_register(
280  const char *disk_name,
281  const rtems_bdpart_partition *partitions,
282  size_t count
283);
284
285/**
286 * @a brief Reads the partition table from the disk device with name @a
287 * disk_name and registers the partitions as logical disks.
288 *
289 * @see rtems_bdpart_register() and rtems_fsmount().
290 */
291rtems_status_code rtems_bdpart_register_from_disk( const char *disk_name);
292
293/**
294 * @brief Deletes the logical disks associated with the partitions of the disk
295 * device with name @a disk_name.
296 *
297 * The partition table @a partitions with @a count partitions will be used to
298 * determine which disks need to be deleted.  It may be obtained from
299 * rtems_bdpart_read().
300 */
301rtems_status_code rtems_bdpart_unregister(
302  const char *disk_name,
303  const rtems_bdpart_partition *partitions,
304  size_t count
305);
306
307/**
308 * @brief Mounts all supported file systems inside the logical disks derived
309 * from the partitions of the physical disk device with name @a disk_name.
310 *
311 * For each partition in the partition table @a partitions with @a count
312 * partitions it will be checked if it contains a supported file system.  In
313 * this case a mount point derived from the disk name will be created in the
314 * mount base path @a mount_base.  The file system will be mounted there.  The
315 * partition number equals the partition table index plus one.  The mount point
316 * name for each partition will be the concatenation of the mount base path,
317 * the disk device file name and the parition number.
318 *
319 * @see rtems_bdpart_read().
320 */
321rtems_status_code rtems_bdpart_mount(
322  const char *disk_name,
323  const rtems_bdpart_partition *partitions,
324  size_t count,
325  const char *mount_base
326);
327
328/**
329 * @brief Unmounts all file systems mounted with rtems_bdpart_mount().
330 */
331rtems_status_code rtems_bdpart_unmount(
332  const char *disk_name,
333  const rtems_bdpart_partition *partitions,
334  size_t count,
335  const char *mount_base
336);
337
338/**
339 * @brief Prints the partition table @a partitions with @a count partitions to
340 * standard output.
341 */
342void rtems_bdpart_dump( const rtems_bdpart_partition *partitions, size_t count);
343
344/**
345 * @brief Returns the partition type for the MBR partition type value
346 * @a mbr_type in @a type.
347 */
348void rtems_bdpart_to_partition_type( uint8_t mbr_type, uuid_t type);
349
350/**
351 * @brief Converts the partition type in @a type to the MBR partition type.
352 *
353 * The result will be stored in @a mbr_type.  Returns @c true in case of a
354 * successful convertion and otherwise @c false.  Both arguments must not be
355 * @c NULL.
356 */
357bool rtems_bdpart_to_mbr_partition_type(
358  const uuid_t type,
359  uint8_t *mbr_type
360);
361
362/** @} */
363
364#define RTEMS_BDPART_MBR_CYLINDER_SIZE 63
365
366#define RTEMS_BDPART_NUMBER_SIZE 4
367
368#define RTEMS_BDPART_BLOCK_SIZE 512
369
370#define RTEMS_BDPART_MBR_TABLE_ENTRY_SIZE 16
371
372#define RTEMS_BDPART_MBR_OFFSET_TABLE_0 446
373
374#define RTEMS_BDPART_MBR_OFFSET_TABLE_1 \
375  (RTEMS_BDPART_MBR_OFFSET_TABLE_0 + RTEMS_BDPART_MBR_TABLE_ENTRY_SIZE)
376
377#define RTEMS_BDPART_MBR_OFFSET_DISK_ID 440
378
379#define RTEMS_BDPART_MBR_OFFSET_SIGNATURE_0 510
380
381#define RTEMS_BDPART_MBR_OFFSET_SIGNATURE_1 511
382
383#define RTEMS_BDPART_MBR_SIGNATURE_0 0x55U
384
385#define RTEMS_BDPART_MBR_SIGNATURE_1 0xaaU
386
387#define RTEMS_BDPART_MBR_OFFSET_BEGIN 8
388
389#define RTEMS_BDPART_MBR_OFFSET_SIZE 12
390
391#define RTEMS_BDPART_MBR_OFFSET_TYPE 4
392
393#define RTEMS_BDPART_MBR_OFFSET_FLAGS 0
394
395static inline uint8_t rtems_bdpart_mbr_partition_type(
396  const uuid_t type
397)
398{
399  return type [0];
400}
401
402rtems_status_code rtems_bdpart_get_disk_data(
403  const char *disk_name,
404  int *fd_ptr,
405  rtems_disk_device **dd_ptr,
406  rtems_blkdev_bnum *disk_end
407);
408
409#ifdef __cplusplus
410}
411#endif /* __cplusplus */
412
413#endif /* RTEMS_BDPART_H */
Note: See TracBrowser for help on using the repository browser.