Sandbox block devices (implementation)

(See Block Device Emulation for operation)

Sandbox block devices are implemented using the UCLASS_HOST uclass. Only one driver is provided (host_sb_drv) so all devices in the uclass use the same driver.

The uclass has a simple API allowing files to be attached and detached. Attaching a file results in it appearing as a block device in sandbox. This allows filesystems and whole disk images to be accessed from U-Boot. This is particularly useful for tests.

Devices are created using host_create_device(). This sets up a new UCLASS_HOST.

The device can then be attached to a file with host_attach_file(). This creates the child block device (and bootdev device).

The host device’s block device must be probed before use, as normal.

To destroy a device, call host_destroy_device(). This removes the device (and its children of course), then closes any attached file, then unbinds the device.

There is no arbitrary limit to the number of host devices that can be created.

Uclass API

This is incomplete as it isn’t clear how to make Sphinx do the right thing for struct host_ops. See include/sandbox_host.h for full details.

struct host_sb_plat: platform data for a host device

Definition

struct host_sb_plat {
  char *label;
  char *filename;
  int fd;
};

Members

label: Label for this device (allocated)
filename: Name of file this is attached to, or NULL (allocated)
fd: File descriptor of file, or 0 for none (file is not open)

struct host_ops: operations supported by UCLASS_HOST

Definition

struct host_ops {
  int (*attach_file)(struct udevice *dev, const char *filename);
  int (*detach_file)(struct udevice *dev);
};

Members

attach_file

Attach a new file to the device

attach_file.dev: Device to update attach_file.filename: Name of the file, e.g. “/path/to/disk.img” attach_file.Returns: 0 if OK, -EEXIST if a file is already attached, other -ve on other error

detach_file

Detach a file from the device

detach_file.dev: Device to detach from detach_file.Returns: 0 if OK, -ENOENT if no file is attached, other -ve on other error

int host_attach_file(struct udevice *dev, const char *filename): Attach a new file to the device

Parameters

struct udevice *dev: Device to update
const char *filename: Name of the file, e.g. “/path/to/disk.img”

Return

0 if OK, -EEXIST if a file is already attached, other -ve on other error

int host_detach_file(struct udevice *dev): Detach a file from the device

Parameters

struct udevice *dev: Device to detach from

Return

0 if OK, -ENOENT if no file is attached, other -ve on other error

int host_create_device(const char *label, bool removable, unsigned long blksz, struct udevice **devp): Create a new host device

Parameters

const char *label: Label of the attachment, e.g. “test1”
bool removable: true if the device should be marked as removable, false if it is fixed. See enum blk_flag_t
unsigned long blksz: logical block size of the device
struct udevice **devp: Returns the device created, on success

Description

Any existing device with the same label is removed and unbound first

Return

0 if OK, -ve on error

int host_create_attach_file(const char *label, const char *filename, bool removable, unsigned long blksz, struct udevice **devp): Create a new host device attached to a file

Parameters

const char *label: Label of the attachment, e.g. “test1”
const char *filename: Name of the file, e.g. “/path/to/disk.img”
bool removable: true if the device should be marked as removable, false if it is fixed. See enum blk_flag_t
unsigned long blksz: logical block size of the device
struct udevice **devp: Returns the device created, on success

Return

0 if OK, -ve on error

struct udevice *host_find_by_label(const char *label): Find a host by label

Parameters

const char *label: Label to find

Description

Searches all host devices to find one with the given label

Return

associated device, or NULL if not found

struct udevice *host_get_cur_dev(void): Get the current device

Parameters

void: no arguments

Description

Returns current device, or NULL if none

void host_set_cur_dev(struct udevice *dev): Set the current device

Parameters

struct udevice *dev: Device to set as the current one

Description

Sets the current device, or clears it if dev is NULL