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