oslib/libmtd.h

   1 /*
   2  * Copyright (C) 2008, 2009 Nokia Corporation
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  12  * the GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  * Author: Artem Bityutskiy
  19  *
  20  * MTD library.
  21  */
  22
  23 /* Imported from mtd-utils by dehrenberg */
  24
  25 #ifndef __LIBMTD_H__
  26 #define __LIBMTD_H__
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 // Needed for uint8_t, uint64_t
  33 #include <stdint.h>
  34
  35 /* Maximum MTD device name length */
  36 #define MTD_NAME_MAX 127
  37 /* Maximum MTD device type string length */
  38 #define MTD_TYPE_MAX 64
  39
  40 /* MTD library descriptor */
  41 typedef void * libmtd_t;
  42
  43 /* Forward decls */
  44 struct region_info_user;
  45
  46 /**
  47  * @mtd_dev_cnt: count of MTD devices in system
  48  * @lowest_mtd_num: lowest MTD device number in system
  49  * @highest_mtd_num: highest MTD device number in system
  50  * @sysfs_supported: non-zero if sysfs is supported by MTD
  51  */
  52 struct mtd_info
  53 {
  54         int mtd_dev_cnt;
  55         int lowest_mtd_num;
  56         int highest_mtd_num;
  57         unsigned int sysfs_supported:1;
  58 };
  59
  60 /**
  61  * struct mtd_dev_info - information about an MTD device.
  62  * @mtd_num: MTD device number
  63  * @major: major number of corresponding character device
  64  * @minor: minor number of corresponding character device
  65  * @type: flash type (constants like %MTD_NANDFLASH defined in mtd-abi.h)
  66  * @type_str: static R/O flash type string
  67  * @name: device name
  68  * @size: device size in bytes
  69  * @eb_cnt: count of eraseblocks
  70  * @eb_size: eraseblock size
  71  * @min_io_size: minimum input/output unit size
  72  * @subpage_size: sub-page size
  73  * @oob_size: OOB size (zero if the device does not have OOB area)
  74  * @region_cnt: count of additional erase regions
  75  * @writable: zero if the device is read-only
  76  * @bb_allowed: non-zero if the MTD device may have bad eraseblocks
  77  */
  78 struct mtd_dev_info
  79 {
  80         int mtd_num;
  81         int major;
  82         int minor;
  83         int type;
  84         char type_str[MTD_TYPE_MAX + 1];
  85         char name[MTD_NAME_MAX + 1];
  86         long long size;
  87         int eb_cnt;
  88         int eb_size;
  89         int min_io_size;
  90         int subpage_size;
  91         int oob_size;
  92         int region_cnt;
  93         unsigned int writable:1;
  94         unsigned int bb_allowed:1;
  95 };
  96
  97 /**
  98  * libmtd_open - open MTD library.
  99  *
 100  * This function initializes and opens the MTD library and returns MTD library
 101  * descriptor in case of success and %NULL in case of failure. In case of
 102  * failure, errno contains zero if MTD is not present in the system, or
 103  * contains the error code if a real error happened.
 104  */
 105 libmtd_t libmtd_open(void);
 106
 107 /**
 108  * libmtd_close - close MTD library.
 109  * @desc: MTD library descriptor
 110  */
 111 void libmtd_close(libmtd_t desc);
 112
 113 /**
 114  * mtd_dev_present - check whether a MTD device is present.
 115  * @desc: MTD library descriptor
 116  * @mtd_num: MTD device number to check
 117  *
 118  * This function returns %1 if MTD device is present and %0 if not.
 119  */
 120 int mtd_dev_present(libmtd_t desc, int mtd_num);
 121
 122 /**
 123  * mtd_get_info - get general MTD information.
 124  * @desc: MTD library descriptor
 125  * @info: the MTD device information is returned here
 126  *
 127  * This function fills the passed @info object with general MTD information and
 128  * returns %0 in case of success and %-1 in case of failure. If MTD subsystem is
 129  * not present in the system, errno is set to @ENODEV.
 130  */
 131 int mtd_get_info(libmtd_t desc, struct mtd_info *info);
 132
 133 /**
 134  * mtd_get_dev_info - get information about an MTD device.
 135  * @desc: MTD library descriptor
 136  * @node: name of the MTD device node
 137  * @mtd: the MTD device information is returned here
 138  *
 139  * This function gets information about MTD device defined by the @node device
 140  * node file and saves this information in the @mtd object. Returns %0 in case
 141  * of success and %-1 in case of failure. If MTD subsystem is not present in the
 142  * system, or the MTD device does not exist, errno is set to @ENODEV.
 143  */
 144 int mtd_get_dev_info(libmtd_t desc, const char *node, struct mtd_dev_info *mtd);
 145
 146 /**
 147  * mtd_get_dev_info1 - get information about an MTD device.
 148  * @desc: MTD library descriptor
 149  * @mtd_num: MTD device number to fetch information about
 150  * @mtd: the MTD device information is returned here
 151  *
 152  * This function is identical to 'mtd_get_dev_info()' except that it accepts
 153  * MTD device number, not MTD character device.
 154  */
 155 int mtd_get_dev_info1(libmtd_t desc, int mtd_num, struct mtd_dev_info *mtd);
 156
 157 /**
 158  * mtd_lock - lock eraseblocks.
 159  * @desc: MTD library descriptor
 160  * @mtd: MTD device description object
 161  * @fd: MTD device node file descriptor
 162  * @eb: eraseblock to lock
 163  *
 164  * This function locks eraseblock @eb. Returns %0 in case of success and %-1
 165  * in case of failure.
 166  */
 167 int mtd_lock(const struct mtd_dev_info *mtd, int fd, int eb);
 168
 169 /**
 170  * mtd_unlock - unlock eraseblocks.
 171  * @desc: MTD library descriptor
 172  * @mtd: MTD device description object
 173  * @fd: MTD device node file descriptor
 174  * @eb: eraseblock to lock
 175  *
 176  * This function unlocks eraseblock @eb. Returns %0 in case of success and %-1
 177  * in case of failure.
 178  */
 179 int mtd_unlock(const struct mtd_dev_info *mtd, int fd, int eb);
 180
 181 /**
 182  * mtd_erase - erase an eraseblock.
 183  * @desc: MTD library descriptor
 184  * @mtd: MTD device description object
 185  * @fd: MTD device node file descriptor
 186  * @eb: eraseblock to erase
 187  *
 188  * This function erases eraseblock @eb of MTD device described by @fd. Returns
 189  * %0 in case of success and %-1 in case of failure.
 190  */
 191 int mtd_erase(libmtd_t desc, const struct mtd_dev_info *mtd, int fd, int eb);
 192
 193 /**
 194  * mtd_regioninfo - get information about an erase region.
 195  * @fd: MTD device node file descriptor
 196  * @regidx: index of region to look up
 197  * @reginfo: the region information is returned here
 198  *
 199  * This function gets information about an erase region defined by the
 200  * @regidx index and saves this information in the @reginfo object.
 201  * Returns %0 in case of success and %-1 in case of failure. If the
 202  * @regidx is not valid or unavailable, errno is set to @ENODEV.
 203  */
 204 int mtd_regioninfo(int fd, int regidx, struct region_info_user *reginfo);
 205
 206 /**
 207  * mtd_is_locked - see if the specified eraseblock is locked.
 208  * @mtd: MTD device description object
 209  * @fd: MTD device node file descriptor
 210  * @eb: eraseblock to check
 211  *
 212  * This function checks to see if eraseblock @eb of MTD device described
 213  * by @fd is locked. Returns %0 if it is unlocked, %1 if it is locked, and
 214  * %-1 in case of failure. If the ioctl is not supported (support was added in
 215  * Linux kernel 2.6.36) or this particular device does not support it, errno is
 216  * set to @ENOTSUPP.
 217  */
 218 int mtd_is_locked(const struct mtd_dev_info *mtd, int fd, int eb);
 219
 220 /**
 221  * mtd_torture - torture an eraseblock.
 222  * @desc: MTD library descriptor
 223  * @mtd: MTD device description object
 224  * @fd: MTD device node file descriptor
 225  * @eb: eraseblock to torture
 226  *
 227  * This function tortures eraseblock @eb. Returns %0 in case of success and %-1
 228  * in case of failure.
 229  */
 230 int mtd_torture(libmtd_t desc, const struct mtd_dev_info *mtd, int fd, int eb);
 231
 232 /**
 233  * mtd_is_bad - check if eraseblock is bad.
 234  * @mtd: MTD device description object
 235  * @fd: MTD device node file descriptor
 236  * @eb: eraseblock to check
 237  *
 238  * This function checks if eraseblock @eb is bad. Returns %0 if not, %1 if yes,
 239  * and %-1 in case of failure.
 240  */
 241 int mtd_is_bad(const struct mtd_dev_info *mtd, int fd, int eb);
 242
 243 /**
 244  * mtd_mark_bad - mark an eraseblock as bad.
 245  * @mtd: MTD device description object
 246  * @fd: MTD device node file descriptor
 247  * @eb: eraseblock to mark as bad
 248  *
 249  * This function marks eraseblock @eb as bad. Returns %0 in case of success and
 250  * %-1 in case of failure.
 251  */
 252 int mtd_mark_bad(const struct mtd_dev_info *mtd, int fd, int eb);
 253
 254 /**
 255  * mtd_read - read data from an MTD device.
 256  * @mtd: MTD device description object
 257  * @fd: MTD device node file descriptor
 258  * @eb: eraseblock to read from
 259  * @offs: offset withing the eraseblock to read from
 260  * @buf: buffer to read data to
 261  * @len: how many bytes to read
 262  *
 263  * This function reads @len bytes of data from eraseblock @eb and offset @offs
 264  * of the MTD device defined by @mtd and stores the read data at buffer @buf.
 265  * Returns %0 in case of success and %-1 in case of failure.
 266  */
 267 int mtd_read(const struct mtd_dev_info *mtd, int fd, int eb, int offs,
 268              void *buf, int len);
 269
 270 /**
 271  * mtd_write - write data to an MTD device.
 272  * @desc: MTD library descriptor
 273  * @mtd: MTD device description object
 274  * @fd: MTD device node file descriptor
 275  * @eb: eraseblock to write to
 276  * @offs: offset withing the eraseblock to write to
 277  * @data: data buffer to write
 278  * @len: how many data bytes to write
 279  * @oob: OOB buffer to write
 280  * @ooblen: how many OOB bytes to write
 281  * @mode: write mode (e.g., %MTD_OOB_PLACE, %MTD_OOB_RAW)
 282  *
 283  * This function writes @len bytes of data to eraseblock @eb and offset @offs
 284  * of the MTD device defined by @mtd. Returns %0 in case of success and %-1 in
 285  * case of failure.
 286  *
 287  * Can only write to a single page at a time if writing to OOB.
 288  */
 289 int mtd_write(libmtd_t desc, const struct mtd_dev_info *mtd, int fd, int eb,
 290               int offs, void *data, int len, void *oob, int ooblen,
 291               uint8_t mode);
 292
 293 /**
 294  * mtd_read_oob - read out-of-band area.
 295  * @desc: MTD library descriptor
 296  * @mtd: MTD device description object
 297  * @fd: MTD device node file descriptor
 298  * @start: page-aligned start address
 299  * @length: number of OOB bytes to read
 300  * @data: read buffer
 301  *
 302  * This function reads @length OOB bytes starting from address @start on
 303  * MTD device described by @fd. The address is specified as page byte offset
 304  * from the beginning of the MTD device. This function returns %0 in case of
 305  * success and %-1 in case of failure.
 306  */
 307 int mtd_read_oob(libmtd_t desc, const struct mtd_dev_info *mtd, int fd,
 308                  uint64_t start, uint64_t length, void *data);
 309
 310 /**
 311  * mtd_write_oob - write out-of-band area.
 312  * @desc: MTD library descriptor
 313  * @mtd: MTD device description object
 314  * @fd: MTD device node file descriptor
 315  * @start: page-aligned start address
 316  * @length: number of OOB bytes to write
 317  * @data: write buffer
 318  *
 319  * This function writes @length OOB bytes starting from address @start on
 320  * MTD device described by @fd. The address is specified as page byte offset
 321  * from the beginning of the MTD device. Returns %0 in case of success and %-1
 322  * in case of failure.
 323  */
 324 int mtd_write_oob(libmtd_t desc, const struct mtd_dev_info *mtd, int fd,
 325                   uint64_t start, uint64_t length, void *data);
 326
 327 /**
 328  * mtd_write_img - write a file to MTD device.
 329  * @mtd: MTD device description object
 330  * @fd: MTD device node file descriptor
 331  * @eb: eraseblock to write to
 332  * @offs: offset withing the eraseblock to write to
 333  * @img_name: the file to write
 334  *
 335  * This function writes an image @img_name the MTD device defined by @mtd. @eb
 336  * and @offs are the starting eraseblock and offset on the MTD device. Returns
 337  * %0 in case of success and %-1 in case of failure.
 338  */
 339 int mtd_write_img(const struct mtd_dev_info *mtd, int fd, int eb, int offs,
 340                   const char *img_name);
 341
 342 /**
 343  * mtd_probe_node - test MTD node.
 344  * @desc: MTD library descriptor
 345  * @node: the node to test
 346  *
 347  * This function tests whether @node is an MTD device node and returns %1 if it
 348  * is, and %-1 if it is not (errno is %ENODEV in this case) or if an error
 349  * occurred.
 350  */
 351 int mtd_probe_node(libmtd_t desc, const char *node);
 352
 353 #ifdef __cplusplus
 354 }
 355 #endif
 356
 357 #endif /* __LIBMTD_H__ */