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