dm: Add block device document
Signed-off-by: Pavel Herrmann <morpheus.ibis@gmail.com>
diff --git a/doc/driver-model/UDM-block.txt b/doc/driver-model/UDM-block.txt
new file mode 100644
index 0000000..5d5c776
--- /dev/null
+++ b/doc/driver-model/UDM-block.txt
@@ -0,0 +1,279 @@
+The U-Boot Driver Model Project
+===============================
+Block device subsystem analysis
+===============================
+
+Pavel Herrmann <morpheus.ibis@gmail.com>
+2012-03-08
+
+I) Overview
+-----------
+
+ U-Boot currently implements several distinct APIs for block devices - some
+ drivers use the SATA API, some drivers use the IDE API, sym53c8xx and
+ AHCI use the SCSI API, mg_disk has a separate API, and systemace also has a
+ separate API. There are also MMC and USB APIs used outside of drivers/block,
+ those will be detailed in their specific documents.
+
+ Block devices are described by block_dev_desc structure, that holds, among
+ other things, the read/write/erase callbacks. Block device structures are
+ stored in any way depending on the API, but can be accessed by
+
+ block_dev_desc_t * $api_get_dev(int dev)
+
+ function, as seen in disk/part.c.
+
+ 1) SATA interface
+ -----------------
+
+ The SATA interface drivers implement the following functions:
+
+ int init_sata(int dev)
+ int scan_sata(int dev)
+ ulong sata_read(int dev, ulong blknr, ulong blkcnt, void *buffer)
+ ulong sata_write(int dev, ulong blknr, ulong blkcnt, const void *buffer)
+
+ Block devices are kept in sata_dev_desc[], which is prefilled with values
+ common to all SATA devices in cmd_sata.c, and then modified in init_sata
+ function in the drivers. Callbacks of the block device use SATA API
+ directly. The sata_get_dev function is defined in cmd_sata.c.
+
+ 2) SCSI interface
+ -----------------
+
+ The SCSI interface drivers implement the following functions:
+
+ void scsi_print_error(ccb *pccb)
+ int scsi_exec(ccb *pccb)
+ void scsi_bus_reset(void)
+ void scsi_low_level_init(int busdevfunc)
+
+ The SCSI API works through the scsi_exec function, the actual operation
+ requested is found in the ccb structure.
+
+ Block devices are kept in scsi_dev_desc[], which lives only in cmd_scsi.c.
+ Callbacks of the block device use functions from cmd_scsi.c, which in turn
+ call scsi_exec of the controller. The scsi_get_dev function is also defined
+ in cmd_scsi.c.
+
+ 3) mg_disk interface
+ --------------------
+
+ The mg_disk interface drivers implement the following functions:
+
+ struct mg_drv_data* mg_get_drv_data (void)
+ uint mg_disk_init (void)
+ uint mg_disk_read (u32 addr, u8 *buff, u32 len)
+ uint mg_disk_write(u32 addr, u8 *buff, u32 len)
+ uint mg_disk_write_sects(void *buff, u32 sect_num, u32 sect_cnt)
+ uint mg_disk_read_sects(void *buff, u32 sect_num, u32 sect_cnt)
+
+ The mg_get_drv_data function is to be overridden per-board, but there are no
+ board in-tree that do this.
+
+ Only one driver for this API exists, and it only supports one block device.
+ Callbacks for this device are implemented in mg_disk.c and call the mg_disk
+ API. The mg_disk_get_dev function is defined in mg_disk.c and ignores the
+ device number, always returning the same device.
+
+ 4) systemace interface
+ ----------------------
+
+ The systemace interface does not define any driver API, and has no command
+ itself. The single defined function is systemace_get_devs() from
+ systemace.c, which returns a single static structure for the only supported
+ block device. Callbacks for this device are also implemented in systemace.c.
+
+ 5) IDE interface
+ ----------------
+
+ The IDE interface drivers implement the following functions, but only if
+ CONFIG_IDE_AHB is set:
+
+ uchar ide_read_register(int dev, unsigned int port);
+ void ide_write_register(int dev, unsigned int port, unsigned char val);
+ void ide_read_data(int dev, ulong *sect_buf, int words);
+ void ide_write_data(int dev, ulong *sect_buf, int words);
+
+ The first two functions are called from ide_inb()/ide_outb(), and will
+ default to direct memory access if CONFIG_IDE_AHB is not set, or
+ ide_inb()/ide_outb() functions will get overridden by the board altogether.
+
+ The second two functions are called from input_data()/output_data()
+ functions, and also default to direct memory access, but cannot be
+ overridden by the board.
+
+ One function shared by IDE drivers (but not defined in ide.h) is
+ int ide_preinit(void)
+ This function gets called from ide_init in cmd_ide.c if CONFIG_IDE_PREINIT
+ is defined, and will do the driver-specific initialization of the device.
+
+ Block devices are kept in ide_dev_desc[], which is filled in cmd_ide.c.
+ Callbacks of the block device are defined in cmd_ide.c, and use the
+ ide_inb()/ide_outb()/input_data()/output_data() functions mentioned above.
+ The ide_get_dev function is defined in cmd_ide.c.
+
+II) Approach
+------------
+
+ A new block controller core and an associated API will be created to mimic the
+ current SATA API, its drivers will have the following ops:
+
+ struct block_ctrl_ops {
+ int scan(instance *i);
+ int reset(instance *i, int port);
+ lbaint_t read(instance *i, int port, lbaint_t start, lbatin_t length,
+ void *buffer);
+ lbaint_t write(instance *i, int port, lbaint_t start, lbatin_t length,
+ void*buffer);
+ }
+
+ The current sata_init() function will be changed into the driver probe()
+ function. The read() and write() functions should never be called directly,
+ instead they should be called by block device driver for disks.
+
+ Other block APIs would either be transformed into this API, or be kept as
+ legacy for old drivers, or be dropped altogether.
+
+ Legacy driver APIs will each have its own driver core that will contain the
+ shared logic, which is currently located mostly in cmd_* files. Callbacks for
+ block device drivers will then probably be implemented as a part of the core
+ logic, and will use the driver ops (which will copy current state of
+ respective APIs) to do the work.
+
+ All drivers will be cleaned up, most ifdefs should be converted into
+ platform_data, to enable support for multiple devices with different settings.
+
+ A new block device core will also be created, and will keep track of all
+ block devices on all interfaces.
+
+ Current block_dev_desc structure will be changed to fit the driver model, all
+ identification and configuration will be placed in private data, and
+ a single accessor and modifier will be defined, to accommodate the need for
+ different sets of options for different interfaces, while keeping the
+ structure small. The new block device drivers will have the following ops
+ structure (lbaint_t is either 32bit or 64bit unsigned, depending on
+ CONFIG_LBA48):
+
+ struct blockdev_ops {
+ lbaint_t (*block_read)(struct instance *i, lbaint_t start, lbaint_t blkcnt,
+ void *buffer);
+ lbaint_t (*block_write)(struct instance *i, lbaint_t start, lbaint_t blkcnt,
+ void *buffer);
+ lbaint_t (*block_erase)(struct instance *i, lbaint_t start, lbaint_t blkcnt
+ );
+ int (*get_option)(struct instance *i, enum blockdev_option_code op,
+ struct option *res);
+ int (*set_option)(struct instance *i, enum blockdev_option_code op,
+ struct option *val);
+ }
+
+ struct option {
+ uint32_t flags
+ union data {
+ uint64_t data_u;
+ char* data_s;
+ void* data_p;
+ }
+ }
+
+ enum blockdev_option_code {
+ BLKD_OPT_IFTYPE=0,
+ BLKD_OPT_TYPE,
+ BLKD_OPT_BLOCKSIZE,
+ BLKD_OPT_BLOCKCOUNT,
+ BLKD_OPT_REMOVABLE,
+ BLKD_OPT_LBA48,
+ BLKD_OPT_VENDOR,
+ BLKD_OPT_PRODICT,
+ BLKD_OPT_REVISION,
+ BLKD_OPT_SCSILUN,
+ BLKD_OPT_SCSITARGET,
+ BLKD_OPT_OFFSET
+ }
+
+ Flags in option above will contain the type of returned data (which should be
+ checked against what is expected, even though the option requested should
+ specify it), and a flag to indicate whether the returned pointer needs to be
+ free()'d.
+
+ The block device core will contain the logic now located in disk/part.c and
+ related files, and will be used to forward requests to block devices. The API
+ for the block device core will copy the ops of a block device (with a string
+ identifier instead of instance pointer). This means that partitions will also
+ be handled by the block device core, and exported as block devices, making
+ them transparent to the rest of the code.
+
+ Sadly, this will change how file systems can access the devices, and thus will
+ affect a lot of places. However, these changes should be localized and easy to
+ implement.
+
+ AHCI driver will be rewritten to fit the new unified block controller API,
+ making SCSI API easy to merge with sym53c8xx, or remove it once the device
+ driver has died.
+
+ Optionally, IDE core may be changed into one driver with unified block
+ controller API, as most of it is already in one place and device drivers are
+ just sets of hooks. Additionally, mg_disk driver is unused and may be removed
+ in near future.
+
+
+
+III) Analysis of in-tree drivers
+--------------------------------
+
+ 1) ahci.c
+ ---------
+ SCSI API, will be rewritten for a different API.
+
+ 2) ata_piix.c
+ -------------
+ SATA API, easy to port.
+
+ 3) fsl_sata.c
+ -------------
+ SATA API, few CONFIG macros, easy to port.
+
+ 4) ftide020.c
+ -------------
+ IDE API, defines CONFIG_IDE_AHB and ide_preinit hook functions.
+
+ 5) mg_disk.c
+ ------------
+ Single driver with mg_disk API, not much to change, easy to port.
+
+ 6) mvsata_ide.c
+ ---------------
+ IDE API, only defines ide_preinit hook function.
+
+ 7) mxc_ata.c
+ ------------
+ IDE API, only defines ide_preinit hook function.
+
+ 8) pata_bfin.c
+ --------------
+ SATA API, easy to port.
+
+ 9) sata_dwc.c
+ -------------
+ SATA API, easy to port.
+
+ 10) sata_sil3114.c
+ ------------------
+ SATA API, easy to port.
+
+ 11) sata_sil.c
+ --------------
+ SATA API, easy to port.
+
+ 12) sil680.c
+ ------------
+ IDE API, only defines ide_preinit hook function.
+
+ 13) sym53c8xx.c
+ ---------------
+ SCSI API, may be merged with code from cmd_scsi.
+
+ 14) systemace.c
+ ---------------
+ Single driver with systemace API, not much to change, easy to port.