xref: /openbmc/u-boot/include/blk.h (revision 8435179271106ec6fe9a9a5679b897755b1db8dd)
1  /*
2   * (C) Copyright 2000-2004
3   * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
4   *
5   * SPDX-License-Identifier:	GPL-2.0+
6   */
7  
8  #ifndef BLK_H
9  #define BLK_H
10  
11  #ifdef CONFIG_SYS_64BIT_LBA
12  typedef uint64_t lbaint_t;
13  #define LBAFlength "ll"
14  #else
15  typedef ulong lbaint_t;
16  #define LBAFlength "l"
17  #endif
18  #define LBAF "%" LBAFlength "x"
19  #define LBAFU "%" LBAFlength "u"
20  
21  /* Interface types: */
22  enum if_type {
23  	IF_TYPE_UNKNOWN = 0,
24  	IF_TYPE_IDE,
25  	IF_TYPE_SCSI,
26  	IF_TYPE_ATAPI,
27  	IF_TYPE_USB,
28  	IF_TYPE_DOC,
29  	IF_TYPE_MMC,
30  	IF_TYPE_SD,
31  	IF_TYPE_SATA,
32  	IF_TYPE_HOST,
33  	IF_TYPE_SYSTEMACE,
34  
35  	IF_TYPE_COUNT,			/* Number of interface types */
36  };
37  
38  /*
39   * With driver model (CONFIG_BLK) this is uclass platform data, accessible
40   * with dev_get_uclass_platdata(dev)
41   */
42  struct blk_desc {
43  	/*
44  	 * TODO: With driver model we should be able to use the parent
45  	 * device's uclass instead.
46  	 */
47  	enum if_type	if_type;	/* type of the interface */
48  	int		devnum;		/* device number */
49  	unsigned char	part_type;	/* partition type */
50  	unsigned char	target;		/* target SCSI ID */
51  	unsigned char	lun;		/* target LUN */
52  	unsigned char	hwpart;		/* HW partition, e.g. for eMMC */
53  	unsigned char	type;		/* device type */
54  	unsigned char	removable;	/* removable device */
55  #ifdef CONFIG_LBA48
56  	/* device can use 48bit addr (ATA/ATAPI v7) */
57  	unsigned char	lba48;
58  #endif
59  	lbaint_t	lba;		/* number of blocks */
60  	unsigned long	blksz;		/* block size */
61  	int		log2blksz;	/* for convenience: log2(blksz) */
62  	char		vendor[40+1];	/* IDE model, SCSI Vendor */
63  	char		product[20+1];	/* IDE Serial no, SCSI product */
64  	char		revision[8+1];	/* firmware revision */
65  #ifdef CONFIG_BLK
66  	/*
67  	 * For now we have a few functions which take struct blk_desc as a
68  	 * parameter. This field allows them to look up the associated
69  	 * device. Once these functions are removed we can drop this field.
70  	 */
71  	struct udevice *bdev;
72  #else
73  	unsigned long	(*block_read)(struct blk_desc *block_dev,
74  				      lbaint_t start,
75  				      lbaint_t blkcnt,
76  				      void *buffer);
77  	unsigned long	(*block_write)(struct blk_desc *block_dev,
78  				       lbaint_t start,
79  				       lbaint_t blkcnt,
80  				       const void *buffer);
81  	unsigned long	(*block_erase)(struct blk_desc *block_dev,
82  				       lbaint_t start,
83  				       lbaint_t blkcnt);
84  	void		*priv;		/* driver private struct pointer */
85  #endif
86  };
87  
88  #define BLOCK_CNT(size, blk_desc) (PAD_COUNT(size, blk_desc->blksz))
89  #define PAD_TO_BLOCKSIZE(size, blk_desc) \
90  	(PAD_SIZE(size, blk_desc->blksz))
91  
92  #ifdef CONFIG_BLOCK_CACHE
93  /**
94   * blkcache_read() - attempt to read a set of blocks from cache
95   *
96   * @param iftype - IF_TYPE_x for type of device
97   * @param dev - device index of particular type
98   * @param start - starting block number
99   * @param blkcnt - number of blocks to read
100   * @param blksz - size in bytes of each block
101   * @param buf - buffer to contain cached data
102   *
103   * @return - '1' if block returned from cache, '0' otherwise.
104   */
105  int blkcache_read(int iftype, int dev,
106  		  lbaint_t start, lbaint_t blkcnt,
107  		  unsigned long blksz, void *buffer);
108  
109  /**
110   * blkcache_fill() - make data read from a block device available
111   * to the block cache
112   *
113   * @param iftype - IF_TYPE_x for type of device
114   * @param dev - device index of particular type
115   * @param start - starting block number
116   * @param blkcnt - number of blocks available
117   * @param blksz - size in bytes of each block
118   * @param buf - buffer containing data to cache
119   *
120   */
121  void blkcache_fill(int iftype, int dev,
122  		   lbaint_t start, lbaint_t blkcnt,
123  		   unsigned long blksz, void const *buffer);
124  
125  /**
126   * blkcache_invalidate() - discard the cache for a set of blocks
127   * because of a write or device (re)initialization.
128   *
129   * @param iftype - IF_TYPE_x for type of device
130   * @param dev - device index of particular type
131   */
132  void blkcache_invalidate(int iftype, int dev);
133  
134  /**
135   * blkcache_configure() - configure block cache
136   *
137   * @param blocks - maximum blocks per entry
138   * @param entries - maximum entries in cache
139   */
140  void blkcache_configure(unsigned blocks, unsigned entries);
141  
142  /*
143   * statistics of the block cache
144   */
145  struct block_cache_stats {
146  	unsigned hits;
147  	unsigned misses;
148  	unsigned entries; /* current entry count */
149  	unsigned max_blocks_per_entry;
150  	unsigned max_entries;
151  };
152  
153  /**
154   * get_blkcache_stats() - return statistics and reset
155   *
156   * @param stats - statistics are copied here
157   */
158  void blkcache_stats(struct block_cache_stats *stats);
159  
160  #else
161  
162  static inline int blkcache_read(int iftype, int dev,
163  				lbaint_t start, lbaint_t blkcnt,
164  				unsigned long blksz, void *buffer)
165  {
166  	return 0;
167  }
168  
169  static inline void blkcache_fill(int iftype, int dev,
170  				 lbaint_t start, lbaint_t blkcnt,
171  				 unsigned long blksz, void const *buffer) {}
172  
173  static inline void blkcache_invalidate(int iftype, int dev) {}
174  
175  #endif
176  
177  #ifdef CONFIG_BLK
178  struct udevice;
179  
180  /* Operations on block devices */
181  struct blk_ops {
182  	/**
183  	 * read() - read from a block device
184  	 *
185  	 * @dev:	Device to read from
186  	 * @start:	Start block number to read (0=first)
187  	 * @blkcnt:	Number of blocks to read
188  	 * @buffer:	Destination buffer for data read
189  	 * @return number of blocks read, or -ve error number (see the
190  	 * IS_ERR_VALUE() macro
191  	 */
192  	unsigned long (*read)(struct udevice *dev, lbaint_t start,
193  			      lbaint_t blkcnt, void *buffer);
194  
195  	/**
196  	 * write() - write to a block device
197  	 *
198  	 * @dev:	Device to write to
199  	 * @start:	Start block number to write (0=first)
200  	 * @blkcnt:	Number of blocks to write
201  	 * @buffer:	Source buffer for data to write
202  	 * @return number of blocks written, or -ve error number (see the
203  	 * IS_ERR_VALUE() macro
204  	 */
205  	unsigned long (*write)(struct udevice *dev, lbaint_t start,
206  			       lbaint_t blkcnt, const void *buffer);
207  
208  	/**
209  	 * erase() - erase a section of a block device
210  	 *
211  	 * @dev:	Device to (partially) erase
212  	 * @start:	Start block number to erase (0=first)
213  	 * @blkcnt:	Number of blocks to erase
214  	 * @return number of blocks erased, or -ve error number (see the
215  	 * IS_ERR_VALUE() macro
216  	 */
217  	unsigned long (*erase)(struct udevice *dev, lbaint_t start,
218  			       lbaint_t blkcnt);
219  
220  	/**
221  	 * select_hwpart() - select a particular hardware partition
222  	 *
223  	 * Some devices (e.g. MMC) can support partitioning at the hardware
224  	 * level. This is quite separate from the normal idea of
225  	 * software-based partitions. MMC hardware partitions must be
226  	 * explicitly selected. Once selected only the region of the device
227  	 * covered by that partition is accessible.
228  	 *
229  	 * The MMC standard provides for two boot partitions (numbered 1 and 2),
230  	 * rpmb (3), and up to 4 addition general-purpose partitions (4-7).
231  	 *
232  	 * @desc:	Block device to update
233  	 * @hwpart:	Hardware partition number to select. 0 means the raw
234  	 *		device, 1 is the first partition, 2 is the second, etc.
235  	 * @return 0 if OK, -ve on error
236  	 */
237  	int (*select_hwpart)(struct udevice *dev, int hwpart);
238  };
239  
240  #define blk_get_ops(dev)	((struct blk_ops *)(dev)->driver->ops)
241  
242  /*
243   * These functions should take struct udevice instead of struct blk_desc,
244   * but this is convenient for migration to driver model. Add a 'd' prefix
245   * to the function operations, so that blk_read(), etc. can be reserved for
246   * functions with the correct arguments.
247   */
248  unsigned long blk_dread(struct blk_desc *block_dev, lbaint_t start,
249  			lbaint_t blkcnt, void *buffer);
250  unsigned long blk_dwrite(struct blk_desc *block_dev, lbaint_t start,
251  			 lbaint_t blkcnt, const void *buffer);
252  unsigned long blk_derase(struct blk_desc *block_dev, lbaint_t start,
253  			 lbaint_t blkcnt);
254  
255  /**
256   * blk_get_device() - Find and probe a block device ready for use
257   *
258   * @if_type:	Interface type (enum if_type_t)
259   * @devnum:	Device number (specific to each interface type)
260   * @devp:	the device, if found
261   * @return - if found, -ENODEV if no device found, or other -ve error value
262   */
263  int blk_get_device(int if_type, int devnum, struct udevice **devp);
264  
265  /**
266   * blk_first_device() - Find the first device for a given interface
267   *
268   * The device is probed ready for use
269   *
270   * @devnum:	Device number (specific to each interface type)
271   * @devp:	the device, if found
272   * @return 0 if found, -ENODEV if no device, or other -ve error value
273   */
274  int blk_first_device(int if_type, struct udevice **devp);
275  
276  /**
277   * blk_next_device() - Find the next device for a given interface
278   *
279   * This can be called repeatedly after blk_first_device() to iterate through
280   * all devices of the given interface type.
281   *
282   * The device is probed ready for use
283   *
284   * @devp:	On entry, the previous device returned. On exit, the next
285   *		device, if found
286   * @return 0 if found, -ENODEV if no device, or other -ve error value
287   */
288  int blk_next_device(struct udevice **devp);
289  
290  /**
291   * blk_create_device() - Create a new block device
292   *
293   * @parent:	Parent of the new device
294   * @drv_name:	Driver name to use for the block device
295   * @name:	Name for the device
296   * @if_type:	Interface type (enum if_type_t)
297   * @devnum:	Device number, specific to the interface type, or -1 to
298   *		allocate the next available number
299   * @blksz:	Block size of the device in bytes (typically 512)
300   * @size:	Total size of the device in bytes
301   * @devp:	the new device (which has not been probed)
302   */
303  int blk_create_device(struct udevice *parent, const char *drv_name,
304  		      const char *name, int if_type, int devnum, int blksz,
305  		      lbaint_t size, struct udevice **devp);
306  
307  /**
308   * blk_create_devicef() - Create a new named block device
309   *
310   * @parent:	Parent of the new device
311   * @drv_name:	Driver name to use for the block device
312   * @name:	Name for the device (parent name is prepended)
313   * @if_type:	Interface type (enum if_type_t)
314   * @devnum:	Device number, specific to the interface type, or -1 to
315   *		allocate the next available number
316   * @blksz:	Block size of the device in bytes (typically 512)
317   * @size:	Total size of the device in bytes
318   * @devp:	the new device (which has not been probed)
319   */
320  int blk_create_devicef(struct udevice *parent, const char *drv_name,
321  		       const char *name, int if_type, int devnum, int blksz,
322  		       lbaint_t size, struct udevice **devp);
323  
324  /**
325   * blk_prepare_device() - Prepare a block device for use
326   *
327   * This reads partition information from the device if supported.
328   *
329   * @dev:	Device to prepare
330   * @return 0 if ok, -ve on error
331   */
332  int blk_prepare_device(struct udevice *dev);
333  
334  /**
335   * blk_unbind_all() - Unbind all device of the given interface type
336   *
337   * The devices are removed and then unbound.
338   *
339   * @if_type:	Interface type to unbind
340   * @return 0 if OK, -ve on error
341   */
342  int blk_unbind_all(int if_type);
343  
344  /**
345   * blk_find_max_devnum() - find the maximum device number for an interface type
346   *
347   * Finds the last allocated device number for an interface type @if_type. The
348   * next number is safe to use for a newly allocated device.
349   *
350   * @if_type:	Interface type to scan
351   * @return maximum device number found, or -ENODEV if none, or other -ve on
352   * error
353   */
354  int blk_find_max_devnum(enum if_type if_type);
355  
356  /**
357   * blk_select_hwpart() - select a hardware partition
358   *
359   * Select a hardware partition if the device supports it (typically MMC does)
360   *
361   * @dev:	Device to update
362   * @hwpart:	Partition number to select
363   * @return 0 if OK, -ve on error
364   */
365  int blk_select_hwpart(struct udevice *dev, int hwpart);
366  
367  #else
368  #include <errno.h>
369  /*
370   * These functions should take struct udevice instead of struct blk_desc,
371   * but this is convenient for migration to driver model. Add a 'd' prefix
372   * to the function operations, so that blk_read(), etc. can be reserved for
373   * functions with the correct arguments.
374   */
375  static inline ulong blk_dread(struct blk_desc *block_dev, lbaint_t start,
376  			      lbaint_t blkcnt, void *buffer)
377  {
378  	ulong blks_read;
379  	if (blkcache_read(block_dev->if_type, block_dev->devnum,
380  			  start, blkcnt, block_dev->blksz, buffer))
381  		return blkcnt;
382  
383  	/*
384  	 * We could check if block_read is NULL and return -ENOSYS. But this
385  	 * bloats the code slightly (cause some board to fail to build), and
386  	 * it would be an error to try an operation that does not exist.
387  	 */
388  	blks_read = block_dev->block_read(block_dev, start, blkcnt, buffer);
389  	if (blks_read == blkcnt)
390  		blkcache_fill(block_dev->if_type, block_dev->devnum,
391  			      start, blkcnt, block_dev->blksz, buffer);
392  
393  	return blks_read;
394  }
395  
396  static inline ulong blk_dwrite(struct blk_desc *block_dev, lbaint_t start,
397  			       lbaint_t blkcnt, const void *buffer)
398  {
399  	blkcache_invalidate(block_dev->if_type, block_dev->devnum);
400  	return block_dev->block_write(block_dev, start, blkcnt, buffer);
401  }
402  
403  static inline ulong blk_derase(struct blk_desc *block_dev, lbaint_t start,
404  			       lbaint_t blkcnt)
405  {
406  	blkcache_invalidate(block_dev->if_type, block_dev->devnum);
407  	return block_dev->block_erase(block_dev, start, blkcnt);
408  }
409  
410  /**
411   * struct blk_driver - Driver for block interface types
412   *
413   * This provides access to the block devices for each interface type. One
414   * driver should be provided using U_BOOT_LEGACY_BLK() for each interface
415   * type that is to be supported.
416   *
417   * @if_typename:	Interface type name
418   * @if_type:		Interface type
419   * @max_devs:		Maximum number of devices supported
420   * @desc:		Pointer to list of devices for this interface type,
421   *			or NULL to use @get_dev() instead
422   */
423  struct blk_driver {
424  	const char *if_typename;
425  	enum if_type if_type;
426  	int max_devs;
427  	struct blk_desc *desc;
428  	/**
429  	 * get_dev() - get a pointer to a block device given its number
430  	 *
431  	 * Each interface allocates its own devices and typically
432  	 * struct blk_desc is contained with the interface's data structure.
433  	 * There is no global numbering for block devices. This method allows
434  	 * the device for an interface type to be obtained when @desc is NULL.
435  	 *
436  	 * @devnum:	Device number (0 for first device on that interface,
437  	 *		1 for second, etc.
438  	 * @descp:	Returns pointer to the block device on success
439  	 * @return 0 if OK, -ve on error
440  	 */
441  	int (*get_dev)(int devnum, struct blk_desc **descp);
442  
443  	/**
444  	 * select_hwpart() - Select a hardware partition
445  	 *
446  	 * Some devices (e.g. MMC) can support partitioning at the hardware
447  	 * level. This is quite separate from the normal idea of
448  	 * software-based partitions. MMC hardware partitions must be
449  	 * explicitly selected. Once selected only the region of the device
450  	 * covered by that partition is accessible.
451  	 *
452  	 * The MMC standard provides for two boot partitions (numbered 1 and 2),
453  	 * rpmb (3), and up to 4 addition general-purpose partitions (4-7).
454  	 * Partition 0 is the main user-data partition.
455  	 *
456  	 * @desc:	Block device descriptor
457  	 * @hwpart:	Hardware partition number to select. 0 means the main
458  	 *		user-data partition, 1 is the first partition, 2 is
459  	 *		the second, etc.
460  	 * @return 0 if OK, other value for an error
461  	 */
462  	int (*select_hwpart)(struct blk_desc *desc, int hwpart);
463  };
464  
465  /*
466   * Declare a new U-Boot legacy block driver. New drivers should use driver
467   * model (UCLASS_BLK).
468   */
469  #define U_BOOT_LEGACY_BLK(__name)					\
470  	ll_entry_declare(struct blk_driver, __name, blk_driver)
471  
472  struct blk_driver *blk_driver_lookup_type(int if_type);
473  
474  #endif /* !CONFIG_BLK */
475  
476  /**
477   * blk_get_devnum_by_typename() - Get a block device by type and number
478   *
479   * This looks through the available block devices of the given type, returning
480   * the one with the given @devnum.
481   *
482   * @if_type:	Block device type
483   * @devnum:	Device number
484   * @return point to block device descriptor, or NULL if not found
485   */
486  struct blk_desc *blk_get_devnum_by_type(enum if_type if_type, int devnum);
487  
488  /**
489   * blk_get_devnum_by_type() - Get a block device by type name, and number
490   *
491   * This looks up the block device type based on @if_typename, then calls
492   * blk_get_devnum_by_type().
493   *
494   * @if_typename:	Block device type name
495   * @devnum:		Device number
496   * @return point to block device descriptor, or NULL if not found
497   */
498  struct blk_desc *blk_get_devnum_by_typename(const char *if_typename,
499  					    int devnum);
500  
501  /**
502   * blk_dselect_hwpart() - select a hardware partition
503   *
504   * This selects a hardware partition (such as is supported by MMC). The block
505   * device size may change as this effectively points the block device to a
506   * partition at the hardware level. See the select_hwpart() method above.
507   *
508   * @desc:	Block device descriptor for the device to select
509   * @hwpart:	Partition number to select
510   * @return 0 if OK, -ve on error
511   */
512  int blk_dselect_hwpart(struct blk_desc *desc, int hwpart);
513  
514  /**
515   * blk_list_part() - list the partitions for block devices of a given type
516   *
517   * This looks up the partition type for each block device of type @if_type,
518   * then displays a list of partitions.
519   *
520   * @if_type:	Block device type
521   * @return 0 if OK, -ENODEV if there is none of that type
522   */
523  int blk_list_part(enum if_type if_type);
524  
525  /**
526   * blk_list_devices() - list the block devices of a given type
527   *
528   * This lists each block device of the type @if_type, showing the capacity
529   * as well as type-specific information.
530   *
531   * @if_type:	Block device type
532   */
533  void blk_list_devices(enum if_type if_type);
534  
535  /**
536   * blk_show_device() - show information about a given block device
537   *
538   * This shows the block device capacity as well as type-specific information.
539   *
540   * @if_type:	Block device type
541   * @devnum:	Device number
542   * @return 0 if OK, -ENODEV for invalid device number
543   */
544  int blk_show_device(enum if_type if_type, int devnum);
545  
546  /**
547   * blk_print_device_num() - show information about a given block device
548   *
549   * This is similar to blk_show_device() but returns an error if the block
550   * device type is unknown.
551   *
552   * @if_type:	Block device type
553   * @devnum:	Device number
554   * @return 0 if OK, -ENODEV for invalid device number, -ENOENT if the block
555   * device is not connected
556   */
557  int blk_print_device_num(enum if_type if_type, int devnum);
558  
559  /**
560   * blk_print_part_devnum() - print the partition information for a device
561   *
562   * @if_type:	Block device type
563   * @devnum:	Device number
564   * @return 0 if OK, -ENOENT if the block device is not connected, -ENOSYS if
565   * the interface type is not supported, other -ve on other error
566   */
567  int blk_print_part_devnum(enum if_type if_type, int devnum);
568  
569  /**
570   * blk_read_devnum() - read blocks from a device
571   *
572   * @if_type:	Block device type
573   * @devnum:	Device number
574   * @blkcnt:	Number of blocks to read
575   * @buffer:	Address to write data to
576   * @return number of blocks read, or -ve error number on error
577   */
578  ulong blk_read_devnum(enum if_type if_type, int devnum, lbaint_t start,
579  		      lbaint_t blkcnt, void *buffer);
580  
581  /**
582   * blk_write_devnum() - write blocks to a device
583   *
584   * @if_type:	Block device type
585   * @devnum:	Device number
586   * @blkcnt:	Number of blocks to write
587   * @buffer:	Address to read data from
588   * @return number of blocks written, or -ve error number on error
589   */
590  ulong blk_write_devnum(enum if_type if_type, int devnum, lbaint_t start,
591  		       lbaint_t blkcnt, const void *buffer);
592  
593  /**
594   * blk_select_hwpart_devnum() - select a hardware partition
595   *
596   * This is similar to blk_dselect_hwpart() but it looks up the interface and
597   * device number.
598   *
599   * @if_type:	Block device type
600   * @devnum:	Device number
601   * @hwpart:	Partition number to select
602   * @return 0 if OK, -ve on error
603   */
604  int blk_select_hwpart_devnum(enum if_type if_type, int devnum, int hwpart);
605  
606  #endif
607