1/*
2 * Copyright (c) International Business Machines Corp., 2006
3 * Copyright (c) Nokia Corporation, 2006, 2007
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
13 * the GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 *
19 * Author: Artem Bityutskiy (���������������� ����������)
20 */
21
22#ifndef __UBI_UBI_H__
23#define __UBI_UBI_H__
24
25#include <linux/init.h>
26#include <linux/types.h>
27#include <linux/list.h>
28#include <linux/rbtree.h>
29#include <linux/sched.h>
30#include <linux/wait.h>
31#include <linux/mutex.h>
32#include <linux/rwsem.h>
33#include <linux/spinlock.h>
34#include <linux/fs.h>
35#include <linux/cdev.h>
36#include <linux/device.h>
37#include <linux/string.h>
38#include <linux/mtd/mtd.h>
39
40#include <mtd/ubi-header.h>
41#include <linux/mtd/ubi.h>
42
43#include "scan.h"
44#include "debug.h"
45
46/* Maximum number of supported UBI devices */
47#define UBI_MAX_DEVICES 32
48
49/* UBI name used for character devices, sysfs, etc */
50#define UBI_NAME_STR "ubi"
51
52/* Normal UBI messages */
53#define ubi_msg(fmt, ...) printk(KERN_NOTICE "UBI: " fmt "\n", ##__VA_ARGS__)
54/* UBI warning messages */
55#define ubi_warn(fmt, ...) printk(KERN_WARNING "UBI warning: %s: " fmt "\n", \
56				  __FUNCTION__, ##__VA_ARGS__)
57/* UBI error messages */
58#define ubi_err(fmt, ...) printk(KERN_ERR "UBI error: %s: " fmt "\n", \
59				 __FUNCTION__, ##__VA_ARGS__)
60
61/* Lowest number PEBs reserved for bad PEB handling */
62#define MIN_RESEVED_PEBS 2
63
64/* Background thread name pattern */
65#define UBI_BGT_NAME_PATTERN "ubi_bgt%dd"
66
67/* This marker in the EBA table means that the LEB is um-mapped */
68#define UBI_LEB_UNMAPPED -1
69
70/*
71 * In case of errors, UBI tries to repeat the operation several times before
72 * returning error. The below constant defines how many times UBI re-tries.
73 */
74#define UBI_IO_RETRIES 3
75
76/*
77 * Error codes returned by the I/O unit.
78 *
79 * UBI_IO_PEB_EMPTY: the physical eraseblock is empty, i.e. it contains only
80 * 0xFF bytes
81 * UBI_IO_PEB_FREE: the physical eraseblock is free, i.e. it contains only a
82 * valid erase counter header, and the rest are %0xFF bytes
83 * UBI_IO_BAD_EC_HDR: the erase counter header is corrupted (bad magic or CRC)
84 * UBI_IO_BAD_VID_HDR: the volume identifier header is corrupted (bad magic or
85 * CRC)
86 * UBI_IO_BITFLIPS: bit-flips were detected and corrected
87 */
88enum {
89	UBI_IO_PEB_EMPTY = 1,
90	UBI_IO_PEB_FREE,
91	UBI_IO_BAD_EC_HDR,
92	UBI_IO_BAD_VID_HDR,
93	UBI_IO_BITFLIPS
94};
95
96extern int ubi_devices_cnt;
97extern struct ubi_device *ubi_devices[];
98
99struct ubi_volume_desc;
100
101/**
102 * struct ubi_volume - UBI volume description data structure.
103 * @dev: device object to make use of the the Linux device model
104 * @cdev: character device object to create character device
105 * @ubi: reference to the UBI device description object
106 * @vol_id: volume ID
107 * @readers: number of users holding this volume in read-only mode
108 * @writers: number of users holding this volume in read-write mode
109 * @exclusive: whether somebody holds this volume in exclusive mode
110 * @removed: if the volume was removed
111 * @checked: if this static volume was checked
112 *
113 * @reserved_pebs: how many physical eraseblocks are reserved for this volume
114 * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
115 * @usable_leb_size: logical eraseblock size without padding
116 * @used_ebs: how many logical eraseblocks in this volume contain data
117 * @last_eb_bytes: how many bytes are stored in the last logical eraseblock
118 * @used_bytes: how many bytes of data this volume contains
119 * @upd_marker: non-zero if the update marker is set for this volume
120 * @corrupted: non-zero if the volume is corrupted (static volumes only)
121 * @alignment: volume alignment
122 * @data_pad: how many bytes are not used at the end of physical eraseblocks to
123 * satisfy the requested alignment
124 * @name_len: volume name length
125 * @name: volume name
126 *
127 * @updating: whether the volume is being updated
128 * @upd_ebs: how many eraseblocks are expected to be updated
129 * @upd_bytes: how many bytes are expected to be received
130 * @upd_received: how many update bytes were already received
131 * @upd_buf: update buffer which is used to collect update data
132 *
133 * @eba_tbl: EBA table of this volume (LEB->PEB mapping)
134 *
135 * @gluebi_desc: gluebi UBI volume descriptor
136 * @gluebi_refcount: reference count of the gluebi MTD device
137 * @gluebi_mtd: MTD device description object of the gluebi MTD device
138 *
139 * The @corrupted field indicates that the volume's contents is corrupted.
140 * Since UBI protects only static volumes, this field is not relevant to
141 * dynamic volumes - it is user's responsibility to assure their data
142 * integrity.
143 *
144 * The @upd_marker flag indicates that this volume is either being updated at
145 * the moment or is damaged because of an unclean reboot.
146 */
147struct ubi_volume {
148	struct device dev;
149	struct cdev cdev;
150	struct ubi_device *ubi;
151	int vol_id;
152	int readers;
153	int writers;
154	int exclusive;
155	int removed;
156	int checked;
157
158	int reserved_pebs;
159	int vol_type;
160	int usable_leb_size;
161	int used_ebs;
162	int last_eb_bytes;
163	long long used_bytes;
164	int upd_marker;
165	int corrupted;
166	int alignment;
167	int data_pad;
168	int name_len;
169	char name[UBI_VOL_NAME_MAX+1];
170
171	int updating;
172	int upd_ebs;
173	long long upd_bytes;
174	long long upd_received;
175	void *upd_buf;
176
177	int *eba_tbl;
178
179#ifdef CONFIG_MTD_UBI_GLUEBI
180	/* Gluebi-related stuff may be compiled out */
181	struct ubi_volume_desc *gluebi_desc;
182	int gluebi_refcount;
183	struct mtd_info gluebi_mtd;
184#endif
185};
186
187/**
188 * struct ubi_volume_desc - descriptor of the UBI volume returned when it is
189 * opened.
190 * @vol: reference to the corresponding volume description object
191 * @mode: open mode (%UBI_READONLY, %UBI_READWRITE, or %UBI_EXCLUSIVE)
192 */
193struct ubi_volume_desc {
194	struct ubi_volume *vol;
195	int mode;
196};
197
198struct ubi_wl_entry;
199
200/**
201 * struct ubi_device - UBI device description structure
202 * @dev: class device object to use the the Linux device model
203 * @cdev: character device object to create character device
204 * @ubi_num: UBI device number
205 * @ubi_name: UBI device name
206 * @major: character device major number
207 * @vol_count: number of volumes in this UBI device
208 * @volumes: volumes of this UBI device
209 * @volumes_lock: protects @volumes, @rsvd_pebs, @avail_pebs, beb_rsvd_pebs,
210 * @beb_rsvd_level, @bad_peb_count, @good_peb_count, @vol_count, @vol->readers,
211 * @vol->writers, @vol->exclusive, @vol->removed, @vol->mapping and
212 * @vol->eba_tbl.
213 *
214 * @rsvd_pebs: count of reserved physical eraseblocks
215 * @avail_pebs: count of available physical eraseblocks
216 * @beb_rsvd_pebs: how many physical eraseblocks are reserved for bad PEB
217 * handling
218 * @beb_rsvd_level: normal level of PEBs reserved for bad PEB handling
219 *
220 * @vtbl_slots: how many slots are available in the volume table
221 * @vtbl_size: size of the volume table in bytes
222 * @vtbl: in-RAM volume table copy
223 *
224 * @max_ec: current highest erase counter value
225 * @mean_ec: current mean erase counter value
226 *
227 * global_sqnum: global sequence number
228 * @ltree_lock: protects the lock tree and @global_sqnum
229 * @ltree: the lock tree
230 * @vtbl_mutex: protects on-flash volume table
231 *
232 * @used: RB-tree of used physical eraseblocks
233 * @free: RB-tree of free physical eraseblocks
234 * @scrub: RB-tree of physical eraseblocks which need scrubbing
235 * @prot: protection trees
236 * @prot.pnum: protection tree indexed by physical eraseblock numbers
237 * @prot.aec: protection tree indexed by absolute erase counter value
238 * @wl_lock: protects the @used, @free, @prot, @lookuptbl, @abs_ec, @move_from,
239 * @move_to, @move_to_put @erase_pending, @wl_scheduled, and @works
240 * fields
241 * @wl_scheduled: non-zero if the wear-leveling was scheduled
242 * @lookuptbl: a table to quickly find a &struct ubi_wl_entry object for any
243 * physical eraseblock
244 * @abs_ec: absolute erase counter
245 * @move_from: physical eraseblock from where the data is being moved
246 * @move_to: physical eraseblock where the data is being moved to
247 * @move_from_put: if the "from" PEB was put
248 * @move_to_put: if the "to" PEB was put
249 * @works: list of pending works
250 * @works_count: count of pending works
251 * @bgt_thread: background thread description object
252 * @thread_enabled: if the background thread is enabled
253 * @bgt_name: background thread name
254 *
255 * @flash_size: underlying MTD device size (in bytes)
256 * @peb_count: count of physical eraseblocks on the MTD device
257 * @peb_size: physical eraseblock size
258 * @bad_peb_count: count of bad physical eraseblocks
259 * @good_peb_count: count of good physical eraseblocks
260 * @min_io_size: minimal input/output unit size of the underlying MTD device
261 * @hdrs_min_io_size: minimal I/O unit size used for VID and EC headers
262 * @ro_mode: if the UBI device is in read-only mode
263 * @leb_size: logical eraseblock size
264 * @leb_start: starting offset of logical eraseblocks within physical
265 * eraseblocks
266 * @ec_hdr_alsize: size of the EC header aligned to @hdrs_min_io_size
267 * @vid_hdr_alsize: size of the VID header aligned to @hdrs_min_io_size
268 * @vid_hdr_offset: starting offset of the volume identifier header (might be
269 * unaligned)
270 * @vid_hdr_aloffset: starting offset of the VID header aligned to
271 * @hdrs_min_io_size
272 * @vid_hdr_shift: contains @vid_hdr_offset - @vid_hdr_aloffset
273 * @bad_allowed: whether the MTD device admits of bad physical eraseblocks or
274 * not
275 * @mtd: MTD device descriptor
276 */
277struct ubi_device {
278	struct cdev cdev;
279	struct device dev;
280	int ubi_num;
281	char ubi_name[sizeof(UBI_NAME_STR)+5];
282	int major;
283	int vol_count;
284	struct ubi_volume *volumes[UBI_MAX_VOLUMES+UBI_INT_VOL_COUNT];
285	spinlock_t volumes_lock;
286
287	int rsvd_pebs;
288	int avail_pebs;
289	int beb_rsvd_pebs;
290	int beb_rsvd_level;
291
292	int vtbl_slots;
293	int vtbl_size;
294	struct ubi_vtbl_record *vtbl;
295	struct mutex vtbl_mutex;
296
297	int max_ec;
298	int mean_ec;
299
300	/* EBA unit's stuff */
301	unsigned long long global_sqnum;
302	spinlock_t ltree_lock;
303	struct rb_root ltree;
304
305	/* Wear-leveling unit's stuff */
306	struct rb_root used;
307	struct rb_root free;
308	struct rb_root scrub;
309	struct {
310		struct rb_root pnum;
311		struct rb_root aec;
312	} prot;
313	spinlock_t wl_lock;
314	int wl_scheduled;
315	struct ubi_wl_entry **lookuptbl;
316	unsigned long long abs_ec;
317	struct ubi_wl_entry *move_from;
318	struct ubi_wl_entry *move_to;
319	int move_from_put;
320	int move_to_put;
321	struct list_head works;
322	int works_count;
323	struct task_struct *bgt_thread;
324	int thread_enabled;
325	char bgt_name[sizeof(UBI_BGT_NAME_PATTERN)+2];
326
327	/* I/O unit's stuff */
328	long long flash_size;
329	int peb_count;
330	int peb_size;
331	int bad_peb_count;
332	int good_peb_count;
333	int min_io_size;
334	int hdrs_min_io_size;
335	int ro_mode;
336	int leb_size;
337	int leb_start;
338	int ec_hdr_alsize;
339	int vid_hdr_alsize;
340	int vid_hdr_offset;
341	int vid_hdr_aloffset;
342	int vid_hdr_shift;
343	int bad_allowed;
344	struct mtd_info *mtd;
345};
346
347extern struct file_operations ubi_cdev_operations;
348extern struct file_operations ubi_vol_cdev_operations;
349extern struct class *ubi_class;
350
351/* vtbl.c */
352int ubi_change_vtbl_record(struct ubi_device *ubi, int idx,
353			   struct ubi_vtbl_record *vtbl_rec);
354int ubi_read_volume_table(struct ubi_device *ubi, struct ubi_scan_info *si);
355
356/* vmt.c */
357int ubi_create_volume(struct ubi_device *ubi, struct ubi_mkvol_req *req);
358int ubi_remove_volume(struct ubi_volume_desc *desc);
359int ubi_resize_volume(struct ubi_volume_desc *desc, int reserved_pebs);
360int ubi_add_volume(struct ubi_device *ubi, int vol_id);
361void ubi_free_volume(struct ubi_device *ubi, int vol_id);
362
363/* upd.c */
364int ubi_start_update(struct ubi_device *ubi, int vol_id, long long bytes);
365int ubi_more_update_data(struct ubi_device *ubi, int vol_id,
366			 const void __user *buf, int count);
367
368/* misc.c */
369int ubi_calc_data_len(const struct ubi_device *ubi, const void *buf, int length);
370int ubi_check_volume(struct ubi_device *ubi, int vol_id);
371void ubi_calculate_reserved(struct ubi_device *ubi);
372
373/* gluebi.c */
374#ifdef CONFIG_MTD_UBI_GLUEBI
375int ubi_create_gluebi(struct ubi_device *ubi, struct ubi_volume *vol);
376int ubi_destroy_gluebi(struct ubi_volume *vol);
377#else
378#define ubi_create_gluebi(ubi, vol) 0
379#define ubi_destroy_gluebi(vol) 0
380#endif
381
382/* eba.c */
383int ubi_eba_unmap_leb(struct ubi_device *ubi, int vol_id, int lnum);
384int ubi_eba_read_leb(struct ubi_device *ubi, int vol_id, int lnum, void *buf,
385		     int offset, int len, int check);
386int ubi_eba_write_leb(struct ubi_device *ubi, int vol_id, int lnum,
387		      const void *buf, int offset, int len, int dtype);
388int ubi_eba_write_leb_st(struct ubi_device *ubi, int vol_id, int lnum,
389			 const void *buf, int len, int dtype,
390			 int used_ebs);
391int ubi_eba_atomic_leb_change(struct ubi_device *ubi, int vol_id, int lnum,
392			      const void *buf, int len, int dtype);
393int ubi_eba_copy_leb(struct ubi_device *ubi, int from, int to,
394		     struct ubi_vid_hdr *vid_hdr);
395int ubi_eba_init_scan(struct ubi_device *ubi, struct ubi_scan_info *si);
396void ubi_eba_close(const struct ubi_device *ubi);
397
398/* wl.c */
399int ubi_wl_get_peb(struct ubi_device *ubi, int dtype);
400int ubi_wl_put_peb(struct ubi_device *ubi, int pnum, int torture);
401int ubi_wl_flush(struct ubi_device *ubi);
402int ubi_wl_scrub_peb(struct ubi_device *ubi, int pnum);
403int ubi_wl_init_scan(struct ubi_device *ubi, struct ubi_scan_info *si);
404void ubi_wl_close(struct ubi_device *ubi);
405
406/* io.c */
407int ubi_io_read(const struct ubi_device *ubi, void *buf, int pnum, int offset,
408		int len);
409int ubi_io_write(const struct ubi_device *ubi, const void *buf, int pnum,
410		 int offset, int len);
411int ubi_io_sync_erase(const struct ubi_device *ubi, int pnum, int torture);
412int ubi_io_is_bad(const struct ubi_device *ubi, int pnum);
413int ubi_io_mark_bad(const struct ubi_device *ubi, int pnum);
414int ubi_io_read_ec_hdr(const struct ubi_device *ubi, int pnum,
415		       struct ubi_ec_hdr *ec_hdr, int verbose);
416int ubi_io_write_ec_hdr(const struct ubi_device *ubi, int pnum,
417			struct ubi_ec_hdr *ec_hdr);
418int ubi_io_read_vid_hdr(const struct ubi_device *ubi, int pnum,
419			struct ubi_vid_hdr *vid_hdr, int verbose);
420int ubi_io_write_vid_hdr(const struct ubi_device *ubi, int pnum,
421			 struct ubi_vid_hdr *vid_hdr);
422
423/*
424 * ubi_rb_for_each_entry - walk an RB-tree.
425 * @rb: a pointer to type 'struct rb_node' to to use as a loop counter
426 * @pos: a pointer to RB-tree entry type to use as a loop counter
427 * @root: RB-tree's root
428 * @member: the name of the 'struct rb_node' within the RB-tree entry
429 */
430#define ubi_rb_for_each_entry(rb, pos, root, member)                         \
431	for (rb = rb_first(root),                                            \
432	     pos = (rb ? container_of(rb, typeof(*pos), member) : NULL);     \
433	     rb;                                                             \
434	     rb = rb_next(rb), pos = container_of(rb, typeof(*pos), member))
435
436/**
437 * ubi_zalloc_vid_hdr - allocate a volume identifier header object.
438 * @ubi: UBI device description object
439 *
440 * This function returns a pointer to the newly allocated and zero-filled
441 * volume identifier header object in case of success and %NULL in case of
442 * failure.
443 */
444static inline struct ubi_vid_hdr *ubi_zalloc_vid_hdr(const struct ubi_device *ubi)
445{
446	void *vid_hdr;
447
448	vid_hdr = kzalloc(ubi->vid_hdr_alsize, GFP_KERNEL);
449	if (!vid_hdr)
450		return NULL;
451
452	/*
453	 * VID headers may be stored at un-aligned flash offsets, so we shift
454	 * the pointer.
455	 */
456	return vid_hdr + ubi->vid_hdr_shift;
457}
458
459/**
460 * ubi_free_vid_hdr - free a volume identifier header object.
461 * @ubi: UBI device description object
462 * @vid_hdr: the object to free
463 */
464static inline void ubi_free_vid_hdr(const struct ubi_device *ubi,
465				    struct ubi_vid_hdr *vid_hdr)
466{
467	void *p = vid_hdr;
468
469	if (!p)
470		return;
471
472	kfree(p - ubi->vid_hdr_shift);
473}
474
475/*
476 * This function is equivalent to 'ubi_io_read()', but @offset is relative to
477 * the beginning of the logical eraseblock, not to the beginning of the
478 * physical eraseblock.
479 */
480static inline int ubi_io_read_data(const struct ubi_device *ubi, void *buf,
481				   int pnum, int offset, int len)
482{
483	ubi_assert(offset >= 0);
484	return ubi_io_read(ubi, buf, pnum, offset + ubi->leb_start, len);
485}
486
487/*
488 * This function is equivalent to 'ubi_io_write()', but @offset is relative to
489 * the beginning of the logical eraseblock, not to the beginning of the
490 * physical eraseblock.
491 */
492static inline int ubi_io_write_data(const struct ubi_device *ubi, const void *buf,
493				    int pnum, int offset, int len)
494{
495	ubi_assert(offset >= 0);
496	return ubi_io_write(ubi, buf, pnum, offset + ubi->leb_start, len);
497}
498
499/**
500 * ubi_ro_mode - switch to read-only mode.
501 * @ubi: UBI device description object
502 */
503static inline void ubi_ro_mode(struct ubi_device *ubi)
504{
505	ubi->ro_mode = 1;
506	ubi_warn("switch to read-only mode");
507}
508
509/**
510 * vol_id2idx - get table index by volume ID.
511 * @ubi: UBI device description object
512 * @vol_id: volume ID
513 */
514static inline int vol_id2idx(const struct ubi_device *ubi, int vol_id)
515{
516	if (vol_id >= UBI_INTERNAL_VOL_START)
517		return vol_id - UBI_INTERNAL_VOL_START + ubi->vtbl_slots;
518	else
519		return vol_id;
520}
521
522/**
523 * idx2vol_id - get volume ID by table index.
524 * @ubi: UBI device description object
525 * @idx: table index
526 */
527static inline int idx2vol_id(const struct ubi_device *ubi, int idx)
528{
529	if (idx >= ubi->vtbl_slots)
530		return idx - ubi->vtbl_slots + UBI_INTERNAL_VOL_START;
531	else
532		return idx;
533}
534
535#endif /* !__UBI_UBI_H__ */
536