include/blk.h

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