include/blk.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * (C) Copyright 2000-2004
   4  * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
   5  */
   6
   7 #ifndef BLK_H
   8 #define BLK_H
   9
  10 #include <dm/uclass-id.h>
  11 #include <efi.h>
  12
  13 #ifdef CONFIG_SYS_64BIT_LBA
  14 typedef uint64_t lbaint_t;
  15 #define LBAFlength "ll"
  16 #else
  17 typedef ulong lbaint_t;
  18 #define LBAFlength "l"
  19 #endif
  20 #define LBAF "%" LBAFlength "x"
  21 #define LBAFU "%" LBAFlength "u"
  22
  23 struct udevice;
  24
  25 static inline bool blk_enabled(void)
  26 {
  27         return CONFIG_IS_ENABLED(BLK) || IS_ENABLED(CONFIG_SPL_LEGACY_BLOCK);
  28 }
  29
  30 #define BLK_VEN_SIZE            40
  31 #define BLK_PRD_SIZE            20
  32 #define BLK_REV_SIZE            8
  33
  34 #define PART_FORMAT_PCAT        0x1
  35 #define PART_FORMAT_GPT         0x2
  36
  37 /*
  38  * Identifies the partition table type (ie. MBR vs GPT GUID) signature
  39  */
  40 enum sig_type {
  41         SIG_TYPE_NONE,
  42         SIG_TYPE_MBR,
  43         SIG_TYPE_GUID,
  44
  45         SIG_TYPE_COUNT                  /* Number of signature types */
  46 };
  47
  48 /*
  49  * With driver model (CONFIG_BLK) this is uclass platform data, accessible
  50  * with dev_get_uclass_plat(dev)
  51  */
  52 struct blk_desc {
  53         /*
  54          * TODO: With driver model we should be able to use the parent
  55          * device's uclass instead.
  56          */
  57         enum uclass_id  uclass_id;      /* type of the interface */
  58         int             devnum;         /* device number */
  59         unsigned char   part_type;      /* partition type */
  60         unsigned char   target;         /* target SCSI ID */
  61         unsigned char   lun;            /* target LUN */
  62         unsigned char   hwpart;         /* HW partition, e.g. for eMMC */
  63         unsigned char   type;           /* device type */
  64         unsigned char   removable;      /* removable device */
  65 #ifdef CONFIG_LBA48
  66         /* device can use 48bit addr (ATA/ATAPI v7) */
  67         unsigned char   lba48;
  68 #endif
  69         lbaint_t        lba;            /* number of blocks */
  70         unsigned long   blksz;          /* block size */
  71         int             log2blksz;      /* for convenience: log2(blksz) */
  72         char            vendor[BLK_VEN_SIZE + 1]; /* device vendor string */
  73         char            product[BLK_PRD_SIZE + 1]; /* device product number */
  74         char            revision[BLK_REV_SIZE + 1]; /* firmware revision */
  75         enum sig_type   sig_type;       /* Partition table signature type */
  76         union {
  77                 uint32_t mbr_sig;       /* MBR integer signature */
  78                 efi_guid_t guid_sig;    /* GPT GUID Signature */
  79         };
  80 #if CONFIG_IS_ENABLED(BLK)
  81         /*
  82          * For now we have a few functions which take struct blk_desc as a
  83          * parameter. This field allows them to look up the associated
  84          * device. Once these functions are removed we can drop this field.
  85          */
  86         struct udevice *bdev;
  87 #else
  88         unsigned long   (*block_read)(struct blk_desc *block_dev,
  89                                       lbaint_t start,
  90                                       lbaint_t blkcnt,
  91                                       void *buffer);
  92         unsigned long   (*block_write)(struct blk_desc *block_dev,
  93                                        lbaint_t start,
  94                                        lbaint_t blkcnt,
  95                                        const void *buffer);
  96         unsigned long   (*block_erase)(struct blk_desc *block_dev,
  97                                        lbaint_t start,
  98                                        lbaint_t blkcnt);
  99         void            *priv;          /* driver private struct pointer */
 100 #endif
 101 };
 102
 103 #define BLOCK_CNT(size, blk_desc) (PAD_COUNT(size, blk_desc->blksz))
 104 #define PAD_TO_BLOCKSIZE(size, blk_desc) \
 105         (PAD_SIZE(size, blk_desc->blksz))
 106
 107 #if CONFIG_IS_ENABLED(BLOCK_CACHE)
 108
 109 /**
 110  * blkcache_init() - initialize the block cache list pointers
 111  */
 112 int blkcache_init(void);
 113
 114 /**
 115  * blkcache_read() - attempt to read a set of blocks from cache
 116  *
 117  * @param iftype - uclass_id_x for type of device
 118  * @param dev - device index of particular type
 119  * @param start - starting block number
 120  * @param blkcnt - number of blocks to read
 121  * @param blksz - size in bytes of each block
 122  * @param buffer - buffer to contain cached data
 123  *
 124  * Return: - 1 if block returned from cache, 0 otherwise.
 125  */
 126 int blkcache_read(int iftype, int dev,
 127                   lbaint_t start, lbaint_t blkcnt,
 128                   unsigned long blksz, void *buffer);
 129
 130 /**
 131  * blkcache_fill() - make data read from a block device available
 132  * to the block cache
 133  *
 134  * @param iftype - uclass_id_x for type of device
 135  * @param dev - device index of particular type
 136  * @param start - starting block number
 137  * @param blkcnt - number of blocks available
 138  * @param blksz - size in bytes of each block
 139  * @param buffer - buffer containing data to cache
 140  *
 141  */
 142 void blkcache_fill(int iftype, int dev,
 143                    lbaint_t start, lbaint_t blkcnt,
 144                    unsigned long blksz, void const *buffer);
 145
 146 /**
 147  * blkcache_invalidate() - discard the cache for a set of blocks
 148  * because of a write or device (re)initialization.
 149  *
 150  * @iftype - UCLASS_ID_ for type of device, or -1 for any
 151  * @dev - device index of particular type, if @iftype is not -1
 152  */
 153 void blkcache_invalidate(int iftype, int dev);
 154
 155 /**
 156  * blkcache_configure() - configure block cache
 157  *
 158  * @param blocks - maximum blocks per entry
 159  * @param entries - maximum entries in cache
 160  */
 161 void blkcache_configure(unsigned blocks, unsigned entries);
 162
 163 /*
 164  * statistics of the block cache
 165  */
 166 struct block_cache_stats {
 167         unsigned hits;
 168         unsigned misses;
 169         unsigned entries; /* current entry count */
 170         unsigned max_blocks_per_entry;
 171         unsigned max_entries;
 172 };
 173
 174 /**
 175  * get_blkcache_stats() - return statistics and reset
 176  *
 177  * @param stats - statistics are copied here
 178  */
 179 void blkcache_stats(struct block_cache_stats *stats);
 180
 181 /** blkcache_free() - free all memory allocated to the block cache */
 182 void blkcache_free(void);
 183
 184 #else
 185
 186 static inline int blkcache_read(int iftype, int dev,
 187                                 lbaint_t start, lbaint_t blkcnt,
 188                                 unsigned long blksz, void *buffer)
 189 {
 190         return 0;
 191 }
 192
 193 static inline void blkcache_fill(int iftype, int dev,
 194                                  lbaint_t start, lbaint_t blkcnt,
 195                                  unsigned long blksz, void const *buffer) {}
 196
 197 static inline void blkcache_invalidate(int iftype, int dev) {}
 198
 199 static inline void blkcache_free(void) {}
 200
 201 #endif
 202
 203 #if CONFIG_IS_ENABLED(BLK)
 204 struct udevice;
 205
 206 /* Operations on block devices */
 207 struct blk_ops {
 208         /**
 209          * read() - read from a block device
 210          *
 211          * @dev:        Device to read from
 212          * @start:      Start block number to read (0=first)
 213          * @blkcnt:     Number of blocks to read
 214          * @buffer:     Destination buffer for data read
 215          * @return number of blocks read, or -ve error number (see the
 216          * IS_ERR_VALUE() macro
 217          */
 218         unsigned long (*read)(struct udevice *dev, lbaint_t start,
 219                               lbaint_t blkcnt, void *buffer);
 220
 221         /**
 222          * write() - write to a block device
 223          *
 224          * @dev:        Device to write to
 225          * @start:      Start block number to write (0=first)
 226          * @blkcnt:     Number of blocks to write
 227          * @buffer:     Source buffer for data to write
 228          * @return number of blocks written, or -ve error number (see the
 229          * IS_ERR_VALUE() macro
 230          */
 231         unsigned long (*write)(struct udevice *dev, lbaint_t start,
 232                                lbaint_t blkcnt, const void *buffer);
 233
 234         /**
 235          * erase() - erase a section of a block device
 236          *
 237          * @dev:        Device to (partially) erase
 238          * @start:      Start block number to erase (0=first)
 239          * @blkcnt:     Number of blocks to erase
 240          * @return number of blocks erased, or -ve error number (see the
 241          * IS_ERR_VALUE() macro
 242          */
 243         unsigned long (*erase)(struct udevice *dev, lbaint_t start,
 244                                lbaint_t blkcnt);
 245
 246         /**
 247          * select_hwpart() - select a particular hardware partition
 248          *
 249          * Some devices (e.g. MMC) can support partitioning at the hardware
 250          * level. This is quite separate from the normal idea of
 251          * software-based partitions. MMC hardware partitions must be
 252          * explicitly selected. Once selected only the region of the device
 253          * covered by that partition is accessible.
 254          *
 255          * The MMC standard provides for two boot partitions (numbered 1 and 2),
 256          * rpmb (3), and up to 4 addition general-purpose partitions (4-7).
 257          *
 258          * @dev:        Block device to update
 259          * @hwpart:     Hardware partition number to select. 0 means the raw
 260          *              device, 1 is the first partition, 2 is the second, etc.
 261          * @return 0 if OK, -ve on error
 262          */
 263         int (*select_hwpart)(struct udevice *dev, int hwpart);
 264 };
 265
 266 #define blk_get_ops(dev)        ((struct blk_ops *)(dev)->driver->ops)
 267
 268 /*
 269  * These functions should take struct udevice instead of struct blk_desc,
 270  * but this is convenient for migration to driver model. Add a 'd' prefix
 271  * to the function operations, so that blk_read(), etc. can be reserved for
 272  * functions with the correct arguments.
 273  */
 274 unsigned long blk_dread(struct blk_desc *block_dev, lbaint_t start,
 275                         lbaint_t blkcnt, void *buffer);
 276 unsigned long blk_dwrite(struct blk_desc *block_dev, lbaint_t start,
 277                          lbaint_t blkcnt, const void *buffer);
 278 unsigned long blk_derase(struct blk_desc *block_dev, lbaint_t start,
 279                          lbaint_t blkcnt);
 280
 281 /**
 282  * blk_read() - Read from a block device
 283  *
 284  * @dev: Device to read from
 285  * @start: Start block for the read
 286  * @blkcnt: Number of blocks to read
 287  * @buf: Place to put the data
 288  * @return number of blocks read (which may be less than @blkcnt),
 289  * or -ve on error. This never returns 0 unless @blkcnt is 0
 290  */
 291 long blk_read(struct udevice *dev, lbaint_t start, lbaint_t blkcnt,
 292               void *buffer);
 293
 294 /**
 295  * blk_write() - Write to a block device
 296  *
 297  * @dev: Device to write to
 298  * @start: Start block for the write
 299  * @blkcnt: Number of blocks to write
 300  * @buf: Data to write
 301  * @return number of blocks written (which may be less than @blkcnt),
 302  * or -ve on error. This never returns 0 unless @blkcnt is 0
 303  */
 304 long blk_write(struct udevice *dev, lbaint_t start, lbaint_t blkcnt,
 305                const void *buffer);
 306
 307 /**
 308  * blk_erase() - Erase part of a block device
 309  *
 310  * @dev: Device to erase
 311  * @start: Start block for the erase
 312  * @blkcnt: Number of blocks to erase
 313  * @return number of blocks erased (which may be less than @blkcnt),
 314  * or -ve on error. This never returns 0 unless @blkcnt is 0
 315  */
 316 long blk_erase(struct udevice *dev, lbaint_t start, lbaint_t blkcnt);
 317
 318 /**
 319  * blk_find_device() - Find a block device
 320  *
 321  * This function does not activate the device. The device will be returned
 322  * whether or not it is activated.
 323  *
 324  * @uclass_id:  Interface type (enum uclass_id_t)
 325  * @devnum:     Device number (specific to each interface type)
 326  * @devp:       the device, if found
 327  * Return: 0 if found, -ENODEV if no device found, or other -ve error value
 328  */
 329 int blk_find_device(int uclass_id, int devnum, struct udevice **devp);
 330
 331 /**
 332  * blk_get_device() - Find and probe a block device ready for use
 333  *
 334  * @uclass_id:  Interface type (enum uclass_id_t)
 335  * @devnum:     Device number (specific to each interface type)
 336  * @devp:       the device, if found
 337  * Return: 0 if found, -ENODEV if no device found, or other -ve error value
 338  */
 339 int blk_get_device(int uclass_id, int devnum, struct udevice **devp);
 340
 341 /**
 342  * blk_first_device() - Find the first device for a given interface
 343  *
 344  * The device is probed ready for use
 345  *
 346  * @devnum:     Device number (specific to each interface type)
 347  * @devp:       the device, if found
 348  * Return: 0 if found, -ENODEV if no device, or other -ve error value
 349  */
 350 int blk_first_device(int uclass_id, struct udevice **devp);
 351
 352 /**
 353  * blk_next_device() - Find the next device for a given interface
 354  *
 355  * This can be called repeatedly after blk_first_device() to iterate through
 356  * all devices of the given interface type.
 357  *
 358  * The device is probed ready for use
 359  *
 360  * @devp:       On entry, the previous device returned. On exit, the next
 361  *              device, if found
 362  * Return: 0 if found, -ENODEV if no device, or other -ve error value
 363  */
 364 int blk_next_device(struct udevice **devp);
 365
 366 /**
 367  * blk_create_device() - Create a new block device
 368  *
 369  * @parent:     Parent of the new device
 370  * @drv_name:   Driver name to use for the block device
 371  * @name:       Name for the device
 372  * @uclass_id:  Interface type (enum uclass_id_t)
 373  * @devnum:     Device number, specific to the interface type, or -1 to
 374  *              allocate the next available number
 375  * @blksz:      Block size of the device in bytes (typically 512)
 376  * @lba:        Total number of blocks of the device
 377  * @devp:       the new device (which has not been probed)
 378  */
 379 int blk_create_device(struct udevice *parent, const char *drv_name,
 380                       const char *name, int uclass_id, int devnum, int blksz,
 381                       lbaint_t lba, struct udevice **devp);
 382
 383 /**
 384  * blk_create_devicef() - Create a new named block device
 385  *
 386  * @parent:     Parent of the new device
 387  * @drv_name:   Driver name to use for the block device
 388  * @name:       Name for the device (parent name is prepended)
 389  * @uclass_id:  Interface type (enum uclass_id_t)
 390  * @devnum:     Device number, specific to the interface type, or -1 to
 391  *              allocate the next available number
 392  * @blksz:      Block size of the device in bytes (typically 512)
 393  * @lba:        Total number of blocks of the device
 394  * @devp:       the new device (which has not been probed)
 395  */
 396 int blk_create_devicef(struct udevice *parent, const char *drv_name,
 397                        const char *name, int uclass_id, int devnum, int blksz,
 398                        lbaint_t lba, struct udevice **devp);
 399
 400 /**
 401  * blk_probe_or_unbind() - Try to probe
 402  *
 403  * Try to probe the device, primarily for enumerating partitions.
 404  * If it fails, the device itself is unbound since it means that it won't
 405  * work any more.
 406  *
 407  * @dev:        The device to probe
 408  * Return:      0 if OK, -ve on error
 409  */
 410 int blk_probe_or_unbind(struct udevice *dev);
 411
 412 /**
 413  * blk_unbind_all() - Unbind all device of the given interface type
 414  *
 415  * The devices are removed and then unbound.
 416  *
 417  * @uclass_id:  Interface type to unbind
 418  * Return: 0 if OK, -ve on error
 419  */
 420 int blk_unbind_all(int uclass_id);
 421
 422 /**
 423  * blk_find_max_devnum() - find the maximum device number for an interface type
 424  *
 425  * Finds the last allocated device number for an interface type @uclass_id. The
 426  * next number is safe to use for a newly allocated device.
 427  *
 428  * @uclass_id:  Interface type to scan
 429  * Return: maximum device number found, or -ENODEV if none, or other -ve on
 430  * error
 431  */
 432 int blk_find_max_devnum(enum uclass_id uclass_id);
 433
 434 /**
 435  * blk_next_free_devnum() - get the next device number for an interface type
 436  *
 437  * Finds the next number that is safe to use for a newly allocated device for
 438  * an interface type @uclass_id.
 439  *
 440  * @uclass_id:  Interface type to scan
 441  * Return: next device number safe to use, or -ve on error
 442  */
 443 int blk_next_free_devnum(enum uclass_id uclass_id);
 444
 445 /**
 446  * blk_select_hwpart() - select a hardware partition
 447  *
 448  * Select a hardware partition if the device supports it (typically MMC does)
 449  *
 450  * @dev:        Device to update
 451  * @hwpart:     Partition number to select
 452  * Return: 0 if OK, -ve on error
 453  */
 454 int blk_select_hwpart(struct udevice *dev, int hwpart);
 455
 456 /**
 457  * blk_find_from_parent() - find a block device by looking up its parent
 458  *
 459  * All block devices have a parent 'media' device which provides the block
 460  * driver for the block device, ensuring that access to the underlying medium
 461  * is available.
 462  *
 463  * The block device is not activated by this function. See
 464  * blk_get_from_parent() for that.
 465  *
 466  * @parent: Media device
 467  * @devp: Returns the associated block device, if any
 468  * Returns: 0 if OK, -ENODEV if @parent is not a media device and has no
 469  * UCLASS_BLK child
 470  */
 471 int blk_find_from_parent(struct udevice *parent, struct udevice **devp);
 472
 473 /**
 474  * blk_get_from_parent() - obtain a block device by looking up its parent
 475  *
 476  * All block devices have a parent 'media' device which provides the block
 477  * driver for the block device, ensuring that access to the underlying medium
 478  * is available.
 479  *
 480  * The block device is probed and ready for use.
 481  *
 482  * @parent: Media device
 483  * @devp: Returns the associated block device, if any
 484  * Returns: 0 if OK, -ENODEV if @parent is not a media device and has no
 485  * UCLASS_BLK child
 486  */
 487 int blk_get_from_parent(struct udevice *parent, struct udevice **devp);
 488
 489 /**
 490  * blk_get_devtype() - Get the device type of a block device
 491  *
 492  * @dev:        Block device to check
 493  * Return: device tree, i.e. the uclass name of its parent, e.g. "mmc"
 494  */
 495 const char *blk_get_devtype(struct udevice *dev);
 496
 497 /**
 498  * blk_get_by_device() - Get the block device descriptor for the given device
 499  * @dev:        Instance of a storage device (the parent of the block device)
 500  *
 501  * Return: With block device descriptor on success , NULL if there is no such
 502  *         block device.
 503  */
 504 struct blk_desc *blk_get_by_device(struct udevice *dev);
 505
 506 #else
 507 #include <errno.h>
 508 /*
 509  * These functions should take struct udevice instead of struct blk_desc,
 510  * but this is convenient for migration to driver model. Add a 'd' prefix
 511  * to the function operations, so that blk_read(), etc. can be reserved for
 512  * functions with the correct arguments.
 513  */
 514 static inline ulong blk_dread(struct blk_desc *block_dev, lbaint_t start,
 515                               lbaint_t blkcnt, void *buffer)
 516 {
 517         ulong blks_read;
 518         if (blkcache_read(block_dev->uclass_id, block_dev->devnum,
 519                           start, blkcnt, block_dev->blksz, buffer))
 520                 return blkcnt;
 521
 522         /*
 523          * We could check if block_read is NULL and return -ENOSYS. But this
 524          * bloats the code slightly (cause some board to fail to build), and
 525          * it would be an error to try an operation that does not exist.
 526          */
 527         blks_read = block_dev->block_read(block_dev, start, blkcnt, buffer);
 528         if (blks_read == blkcnt)
 529                 blkcache_fill(block_dev->uclass_id, block_dev->devnum,
 530                               start, blkcnt, block_dev->blksz, buffer);
 531
 532         return blks_read;
 533 }
 534
 535 static inline ulong blk_dwrite(struct blk_desc *block_dev, lbaint_t start,
 536                                lbaint_t blkcnt, const void *buffer)
 537 {
 538         blkcache_invalidate(block_dev->uclass_id, block_dev->devnum);
 539         return block_dev->block_write(block_dev, start, blkcnt, buffer);
 540 }
 541
 542 static inline ulong blk_derase(struct blk_desc *block_dev, lbaint_t start,
 543                                lbaint_t blkcnt)
 544 {
 545         blkcache_invalidate(block_dev->uclass_id, block_dev->devnum);
 546         return block_dev->block_erase(block_dev, start, blkcnt);
 547 }
 548
 549 /**
 550  * struct blk_driver - Driver for block interface types
 551  *
 552  * This provides access to the block devices for each interface type. One
 553  * driver should be provided using U_BOOT_LEGACY_BLK() for each interface
 554  * type that is to be supported.
 555  *
 556  * @uclass_idname:      Interface type name
 557  * @uclass_id:          Interface type
 558  * @max_devs:           Maximum number of devices supported
 559  * @desc:               Pointer to list of devices for this interface type,
 560  *                      or NULL to use @get_dev() instead
 561  */
 562 struct blk_driver {
 563         const char *uclass_idname;
 564         enum uclass_id uclass_id;
 565         int max_devs;
 566         struct blk_desc *desc;
 567         /**
 568          * get_dev() - get a pointer to a block device given its number
 569          *
 570          * Each interface allocates its own devices and typically
 571          * struct blk_desc is contained with the interface's data structure.
 572          * There is no global numbering for block devices. This method allows
 573          * the device for an interface type to be obtained when @desc is NULL.
 574          *
 575          * @devnum:     Device number (0 for first device on that interface,
 576          *              1 for second, etc.
 577          * @descp:      Returns pointer to the block device on success
 578          * @return 0 if OK, -ve on error
 579          */
 580         int (*get_dev)(int devnum, struct blk_desc **descp);
 581
 582         /**
 583          * select_hwpart() - Select a hardware partition
 584          *
 585          * Some devices (e.g. MMC) can support partitioning at the hardware
 586          * level. This is quite separate from the normal idea of
 587          * software-based partitions. MMC hardware partitions must be
 588          * explicitly selected. Once selected only the region of the device
 589          * covered by that partition is accessible.
 590          *
 591          * The MMC standard provides for two boot partitions (numbered 1 and 2),
 592          * rpmb (3), and up to 4 addition general-purpose partitions (4-7).
 593          * Partition 0 is the main user-data partition.
 594          *
 595          * @desc:       Block device descriptor
 596          * @hwpart:     Hardware partition number to select. 0 means the main
 597          *              user-data partition, 1 is the first partition, 2 is
 598          *              the second, etc.
 599          * @return 0 if OK, other value for an error
 600          */
 601         int (*select_hwpart)(struct blk_desc *desc, int hwpart);
 602 };
 603
 604 /*
 605  * Declare a new U-Boot legacy block driver. New drivers should use driver
 606  * model (UCLASS_BLK).
 607  */
 608 #define U_BOOT_LEGACY_BLK(__name)                                       \
 609         ll_entry_declare(struct blk_driver, __name, blk_driver)
 610
 611 struct blk_driver *blk_driver_lookup_type(int uclass_id);
 612
 613 #endif /* !CONFIG_BLK */
 614
 615 /**
 616  * blk_get_devnum_by_uclass_idname() - Get a block device by type and number
 617  *
 618  * This looks through the available block devices of the given type, returning
 619  * the one with the given @devnum.
 620  *
 621  * @uclass_id:  Block device type
 622  * @devnum:     Device number
 623  * Return: point to block device descriptor, or NULL if not found
 624  */
 625 struct blk_desc *blk_get_devnum_by_uclass_id(enum uclass_id uclass_id, int devnum);
 626
 627 /**
 628  * blk_get_devnum_by_uclass_id() - Get a block device by type name, and number
 629  *
 630  * This looks up the block device type based on @uclass_idname, then calls
 631  * blk_get_devnum_by_uclass_id().
 632  *
 633  * @uclass_idname:      Block device type name
 634  * @devnum:             Device number
 635  * Return: point to block device descriptor, or NULL if not found
 636  */
 637 struct blk_desc *blk_get_devnum_by_uclass_idname(const char *uclass_idname,
 638                                             int devnum);
 639
 640 /**
 641  * blk_dselect_hwpart() - select a hardware partition
 642  *
 643  * This selects a hardware partition (such as is supported by MMC). The block
 644  * device size may change as this effectively points the block device to a
 645  * partition at the hardware level. See the select_hwpart() method above.
 646  *
 647  * @desc:       Block device descriptor for the device to select
 648  * @hwpart:     Partition number to select
 649  * Return: 0 if OK, -ve on error
 650  */
 651 int blk_dselect_hwpart(struct blk_desc *desc, int hwpart);
 652
 653 /**
 654  * blk_list_part() - list the partitions for block devices of a given type
 655  *
 656  * This looks up the partition type for each block device of type @uclass_id,
 657  * then displays a list of partitions.
 658  *
 659  * @uclass_id:  Block device type
 660  * Return: 0 if OK, -ENODEV if there is none of that type
 661  */
 662 int blk_list_part(enum uclass_id uclass_id);
 663
 664 /**
 665  * blk_list_devices() - list the block devices of a given type
 666  *
 667  * This lists each block device of the type @uclass_id, showing the capacity
 668  * as well as type-specific information.
 669  *
 670  * @uclass_id:  Block device type
 671  */
 672 void blk_list_devices(enum uclass_id uclass_id);
 673
 674 /**
 675  * blk_show_device() - show information about a given block device
 676  *
 677  * This shows the block device capacity as well as type-specific information.
 678  *
 679  * @uclass_id:  Block device type
 680  * @devnum:     Device number
 681  * Return: 0 if OK, -ENODEV for invalid device number
 682  */
 683 int blk_show_device(enum uclass_id uclass_id, int devnum);
 684
 685 /**
 686  * blk_print_device_num() - show information about a given block device
 687  *
 688  * This is similar to blk_show_device() but returns an error if the block
 689  * device type is unknown.
 690  *
 691  * @uclass_id:  Block device type
 692  * @devnum:     Device number
 693  * Return: 0 if OK, -ENODEV for invalid device number, -ENOENT if the block
 694  * device is not connected
 695  */
 696 int blk_print_device_num(enum uclass_id uclass_id, int devnum);
 697
 698 /**
 699  * blk_print_part_devnum() - print the partition information for a device
 700  *
 701  * @uclass_id:  Block device type
 702  * @devnum:     Device number
 703  * Return: 0 if OK, -ENOENT if the block device is not connected, -ENOSYS if
 704  * the interface type is not supported, other -ve on other error
 705  */
 706 int blk_print_part_devnum(enum uclass_id uclass_id, int devnum);
 707
 708 /**
 709  * blk_read_devnum() - read blocks from a device
 710  *
 711  * @uclass_id:  Block device type
 712  * @devnum:     Device number
 713  * @start:      Start block number to read (0=first)
 714  * @blkcnt:     Number of blocks to read
 715  * @buffer:     Address to write data to
 716  * Return: number of blocks read, or -ve error number on error
 717  */
 718 ulong blk_read_devnum(enum uclass_id uclass_id, int devnum, lbaint_t start,
 719                       lbaint_t blkcnt, void *buffer);
 720
 721 /**
 722  * blk_write_devnum() - write blocks to a device
 723  *
 724  * @uclass_id:  Block device type
 725  * @devnum:     Device number
 726  * @start:      Start block number to write (0=first)
 727  * @blkcnt:     Number of blocks to write
 728  * @buffer:     Address to read data from
 729  * Return: number of blocks written, or -ve error number on error
 730  */
 731 ulong blk_write_devnum(enum uclass_id uclass_id, int devnum, lbaint_t start,
 732                        lbaint_t blkcnt, const void *buffer);
 733
 734 /**
 735  * blk_select_hwpart_devnum() - select a hardware partition
 736  *
 737  * This is similar to blk_dselect_hwpart() but it looks up the interface and
 738  * device number.
 739  *
 740  * @uclass_id:  Block device type
 741  * @devnum:     Device number
 742  * @hwpart:     Partition number to select
 743  * Return: 0 if OK, -ve on error
 744  */
 745 int blk_select_hwpart_devnum(enum uclass_id uclass_id, int devnum, int hwpart);
 746
 747 /**
 748  * blk_get_uclass_name() - Get the name of an interface type
 749  *
 750  * @uclass_id: Interface type to check
 751  * Return: name of interface, or NULL if none
 752  */
 753 const char *blk_get_uclass_name(enum uclass_id uclass_id);
 754
 755 /**
 756  * blk_common_cmd() - handle common commands with block devices
 757  *
 758  * @args: Number of arguments to the command (argv[0] is the command itself)
 759  * @argv: Command arguments
 760  * @uclass_id: Interface type
 761  * @cur_devnump: Current device number for this interface type
 762  * Return: 0 if OK, CMD_RET_ERROR on error
 763  */
 764 int blk_common_cmd(int argc, char *const argv[], enum uclass_id uclass_id,
 765                    int *cur_devnump);
 766
 767 enum blk_flag_t {
 768         BLKF_FIXED      = 1 << 0,
 769         BLKF_REMOVABLE  = 1 << 1,
 770         BLKF_BOTH       = BLKF_FIXED | BLKF_REMOVABLE,
 771 };
 772
 773 /**
 774  * blk_first_device_err() - Get the first block device
 775  *
 776  * The device returned is probed if necessary, and ready for use
 777  *
 778  * @flags: Indicates type of device to return
 779  * @devp: Returns pointer to the first device in that uclass, or NULL if none
 780  * Return: 0 if found, -ENODEV if not found, other -ve on error
 781  */
 782 int blk_first_device_err(enum blk_flag_t flags, struct udevice **devp);
 783
 784 /**
 785  * blk_next_device_err() - Get the next block device
 786  *
 787  * The device returned is probed if necessary, and ready for use
 788  *
 789  * @flags: Indicates type of device to return
 790  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
 791  * to the next device in the uclass if no error occurred, or -ENODEV if
 792  * there is no next device.
 793  * Return: 0 if found, -ENODEV if not found, other -ve on error
 794  */
 795 int blk_next_device_err(enum blk_flag_t flags, struct udevice **devp);
 796
 797 /**
 798  * blk_find_first() - Return the first matching block device
 799  * @flags: Indicates type of device to return
 800  * @devp:       Returns pointer to device, or NULL on error
 801  *
 802  * The device is not prepared for use - this is an internal function.
 803  * The function uclass_get_device_tail() can be used to probe the device.
 804  *
 805  * Note that some devices are considered removable until they have been probed
 806  *
 807  * @return 0 if found, -ENODEV if not found
 808  */
 809 int blk_find_first(enum blk_flag_t flags, struct udevice **devp);
 810
 811 /**
 812  * blk_find_next() - Return the next matching block device
 813  * @flags: Indicates type of device to return
 814  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
 815  * to the next device in the same uclass, or NULL if none
 816  *
 817  * The device is not prepared for use - this is an internal function.
 818  * The function uclass_get_device_tail() can be used to probe the device.
 819  *
 820  * Note that some devices are considered removable until they have been probed
 821  *
 822  * @return 0 if found, -ENODEV if not found
 823  */
 824 int blk_find_next(enum blk_flag_t flags, struct udevice **devp);
 825
 826 /**
 827  * blk_foreach() - iterate through block devices
 828  *
 829  * This creates a for() loop which works through the available block devices in
 830  * order from start to end.
 831  *
 832  * If for some reason the uclass cannot be found, this does nothing.
 833  *
 834  * @_flags: Indicates type of device to return
 835  * @_pos: struct udevice * to hold the current device. Set to NULL when there
 836  * are no more devices.
 837  */
 838 #define blk_foreach(_flags, _pos) \
 839         for (int _ret = blk_find_first(_flags, &_pos); !_ret && _pos; \
 840              _ret = blk_find_next(_flags, &_pos))
 841
 842 /**
 843  * blk_foreach_probe() - Helper function to iteration through block devices
 844  *
 845  * This creates a for() loop which works through the available devices in
 846  * a uclass in order from start to end. Devices are probed if necessary,
 847  * and ready for use.
 848  *
 849  * @flags: Indicates type of device to return
 850  * @dev: struct udevice * to hold the current device. Set to NULL when there
 851  * are no more devices.
 852  */
 853 #define blk_foreach_probe(flags, pos)   \
 854         for (int _ret = blk_first_device_err(flags, &(pos)); \
 855              !_ret && pos; \
 856              _ret = blk_next_device_err(flags, &(pos)))
 857
 858 /**
 859  * blk_count_devices() - count the number of devices of a particular type
 860  *
 861  * @flags: Indicates type of device to find
 862  * Return: number of devices matching those flags
 863  */
 864 int blk_count_devices(enum blk_flag_t flag);
 865
 866 #endif