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 // 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__ */ 358
