sanboot.h File Reference

iPXE sanboot API More...

#include <ipxe/api.h>
#include <ipxe/refcnt.h>
#include <ipxe/list.h>
#include <ipxe/uri.h>
#include <ipxe/retry.h>
#include <ipxe/process.h>
#include <ipxe/blockdev.h>
#include <ipxe/acpi.h>
#include <ipxe/uuid.h>
#include <config/sanboot.h>
#include <ipxe/null_sanboot.h>
#include <ipxe/dummy_sanboot.h>
#include <ipxe/efi/efi_block.h>
#include <bits/sanboot.h>

Go to the source code of this file.

Data Structures
struct	san_path
	A SAN path. More...
struct	san_device
	A SAN device. More...
struct	san_boot_config
	SAN boot configuration parameters. More...

Macros
#define	SAN_DEFAULT_DRIVE   0x80
	Default SAN drive number.
#define	SANBOOT_INLINE(_subsys, _api_func)
	Calculate static inline sanboot API function name.
#define	PROVIDE_SANBOOT(_subsys, _api_func, _func)
	Provide a sanboot API implementation.
#define	PROVIDE_SANBOOT_INLINE(_subsys, _api_func)
	Provide a static inline sanboot API implementation.
#define	for_each_sandev(sandev)
	Iterate over all SAN devices.

Enumerations
enum	san_device_flags { SAN_NO_DESCRIBE = 0x0001 }
	SAN device flags. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
int	san_hook (unsigned int drive, struct uri **uris, unsigned int count, unsigned int flags)
	Hook SAN device.
void	san_unhook (unsigned int drive)
	Unhook SAN device.
int	san_boot (unsigned int drive, struct san_boot_config *config)
	Attempt to boot from a SAN device.
int	san_describe (void)
	Describe SAN devices for SAN-booted operating system.
static int	have_sandevs (void)
	There exist some SAN devices.
static struct san_device *	sandev_get (struct san_device *sandev)
	Get reference to SAN device.
static void	sandev_put (struct san_device *sandev)
	Drop reference to SAN device.
static size_t	sandev_blksize (struct san_device *sandev)
	Calculate SAN device block size.
static uint64_t	sandev_capacity (struct san_device *sandev)
	Calculate SAN device capacity.
static int	sandev_needs_reopen (struct san_device *sandev)
	Check if SAN device needs to be reopened.
struct san_device *	sandev_find (unsigned int drive)
	Find SAN device by drive number.
struct san_device *	sandev_next (unsigned int drive)
	Find next SAN device by drive number.
int	sandev_reopen (struct san_device *sandev)
	(Re)open SAN device
int	sandev_reset (struct san_device *sandev)
	Reset SAN device.
int	sandev_read (struct san_device *sandev, uint64_t lba, unsigned int count, void *buffer)
	Read from SAN device.
int	sandev_write (struct san_device *sandev, uint64_t lba, unsigned int count, void *buffer)
	Write to SAN device.
struct san_device *	alloc_sandev (struct uri **uris, unsigned int count, size_t priv_size)
	Allocate SAN device.
int	register_sandev (struct san_device *sandev, unsigned int drive, unsigned int flags)
	Register SAN device.
void	unregister_sandev (struct san_device *sandev)
	Unregister SAN device.
unsigned int	san_default_drive (void)
	Get default SAN drive number.

Variables
struct list_head	san_devices

Detailed Description

iPXE sanboot API

The sanboot API provides methods for hooking, unhooking, describing, and booting from SAN devices.

Definition in file sanboot.h.

Macro Definition Documentation

SAN_DEFAULT_DRIVE

#define SAN_DEFAULT_DRIVE   0x80

Default SAN drive number.

The drive number is an externally defined concept only in a BIOS environment, where it represents the INT13 drive number (0x80 for the first hard disk). We retain it in other environments to allow for a simple way for iPXE commands to refer to SAN drives.

Definition at line 34 of file sanboot.h.

Referenced by efi_block_boot(), and san_default_drive().

SANBOOT_INLINE

#define SANBOOT_INLINE	(		_subsys,
			_api_func )

Value:

        SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )

Calculate static inline sanboot API function name.

Parameters

_prefix	Subsystem prefix
_api_func	API function

Return values

_subsys_func

Subsystem API function

Definition at line 129 of file sanboot.h.

#define SANBOOT_INLINE( _subsys, _api_func ) \
        SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )

PROVIDE_SANBOOT

#define PROVIDE_SANBOOT	(		_subsys,
			_api_func,
			_func )

Value:

        PROVIDE_SINGLE_API ( SANBOOT_PREFIX_ ## _subsys, _api_func, _func )

Provide a sanboot API implementation.

Parameters

_prefix	Subsystem prefix
_api_func	API function
_func	Implementing function

Definition at line 139 of file sanboot.h.

#define PROVIDE_SANBOOT( _subsys, _api_func, _func ) \
        PROVIDE_SINGLE_API ( SANBOOT_PREFIX_ ## _subsys, _api_func, _func )

PROVIDE_SANBOOT_INLINE

#define PROVIDE_SANBOOT_INLINE	(		_subsys,
			_api_func )

Value:

        PROVIDE_SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )

Provide a static inline sanboot API implementation.

Parameters

_prefix	Subsystem prefix
_api_func	API function

Definition at line 148 of file sanboot.h.

#define PROVIDE_SANBOOT_INLINE( _subsys, _api_func ) \
        PROVIDE_SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )

for_each_sandev

#define for_each_sandev

(

sandev

)

Value:

        list_for_each_entry ( (sandev), &san_devices, list )

Iterate over all SAN devices.

Definition at line 197 of file sanboot.h.

#define for_each_sandev( sandev ) \
        list_for_each_entry ( (sandev), &san_devices, list )

Referenced by efi_block_local(), int13(), int13_sync_num_drives(), and register_sandev().

Enumeration Type Documentation

san_device_flags

enum san_device_flags

SAN device flags.

Enumerator
SAN_NO_DESCRIBE	Device should not be included in description tables.

Definition at line 105 of file sanboot.h.

                      {
        /** Device should not be included in description tables */
        SAN_NO_DESCRIBE = 0x0001,
};

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

san_hook()

int san_hook	(	unsigned int	drive,
		struct uri **	uris,
		unsigned int	count,
		unsigned int	flags )

Hook SAN device.

Parameters

drive	Drive number
uris	List of URIs
count	Number of URIs
flags	Flags

Return values

drive

Drive number, or negative error

References count, drive, and flags.

Referenced by PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), and uriboot().

san_unhook()

void san_unhook

(

unsigned int

drive

)

Unhook SAN device.

Parameters

drive

Drive number

References drive.

Referenced by PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), and uriboot().

san_boot()

int san_boot	(	unsigned int	drive,
		struct san_boot_config *	config )

Attempt to boot from a SAN device.

Parameters

drive	Drive number
config	Boot configuration parameters

Return values

rc	Return status code

References drive.

Referenced by PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), and uriboot().

san_describe()

int san_describe

(

void

)

Describe SAN devices for SAN-booted operating system.

Return values

rc	Return status code

References san_devices.

Referenced by PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), PROVIDE_SANBOOT(), and uriboot().

have_sandevs()

int have_sandevs ( void )

inlinestatic

There exist some SAN devices.

Return values

existence

Existence of SAN devices

Definition at line 204 of file sanboot.h.

                                        {
        return ( ! list_empty ( &san_devices ) );
}

References list_empty, and san_devices.

Referenced by int13_hook(), and int13_unhook().

sandev_get()

struct san_device * sandev_get ( struct san_device * sandev )

inlinestatic

Get reference to SAN device.

Parameters

sandev

SAN device

Return values

sandev

SAN device

Definition at line 215 of file sanboot.h.

                                         {
        ref_get ( &sandev->refcnt );
        return sandev;
}

References ref_get, and san_device::refcnt.

sandev_put()

void sandev_put ( struct san_device * sandev )

inlinestatic

Drop reference to SAN device.

Parameters

sandev

SAN device

Definition at line 226 of file sanboot.h.

                                         {
        ref_put ( &sandev->refcnt );
}

References ref_put, and san_device::refcnt.

Referenced by dummy_san_hook(), dummy_san_unhook(), efi_block_hook(), efi_block_unhook(), int13_hook(), and int13_unhook().

sandev_blksize()

size_t sandev_blksize ( struct san_device * sandev )

inlinestatic

Calculate SAN device block size.

Parameters

sandev

SAN device

Return values

blksize

Sector size

Definition at line 236 of file sanboot.h.

                                                                  {
        return ( sandev->capacity.blksize << sandev->blksize_shift );
}

References block_device_capacity::blksize, san_device::blksize_shift, and san_device::capacity.

Referenced by int13_get_extended_parameters(), int13_get_parameters(), int13_hook(), and int13_rw_sectors().

sandev_capacity()

uint64_t sandev_capacity ( struct san_device * sandev )

inlinestatic

Calculate SAN device capacity.

Parameters

sandev

SAN device

Return values

blocks

Number of blocks

Definition at line 246 of file sanboot.h.

                                                                     {
        return ( sandev->capacity.blocks >> sandev->blksize_shift );
}

References san_device::blksize_shift, block_device_capacity::blocks, and san_device::capacity.

Referenced by int13_capacity32(), int13_get_extended_parameters(), and int13_guess_geometry_fdd().

sandev_needs_reopen()

int sandev_needs_reopen ( struct san_device * sandev )

inlinestatic

Check if SAN device needs to be reopened.

Parameters

sandev

SAN device

Return values

needs_reopen

SAN device needs to be reopened

Definition at line 256 of file sanboot.h.

                                                                    {
        return ( sandev->active == NULL );
}

References san_device::active, and NULL.

Referenced by int13_device_path_info(), and sandev_command().

sandev_find()

struct san_device * sandev_find ( unsigned int drive )

extern

Find SAN device by drive number.

Parameters

drive

Drive number

Return values

sandev

SAN device, or NULL

Definition at line 92 of file sanboot.c.

                                                       {
        struct san_device *sandev;
 
        list_for_each_entry ( sandev, &san_devices, list ) {
                if ( sandev->drive == drive )
                        return sandev;
        }
        return NULL;
}

References drive, san_device::drive, san_device::list, list_for_each_entry, NULL, and san_devices.

Referenced by dummy_san_unhook(), efi_block_unhook(), int13_unhook(), and register_sandev().

sandev_next()

struct san_device * sandev_next ( unsigned int drive )

extern

Find next SAN device by drive number.

Parameters

drive

Minimum drive number

Return values

sandev

SAN device, or NULL

Definition at line 108 of file sanboot.c.

                                                       {
        struct san_device *sandev;
 
        list_for_each_entry ( sandev, &san_devices, list ) {
                if ( sandev->drive >= drive )
                        return sandev;
        }
        return NULL;
}

References drive, san_device::drive, san_device::list, list_for_each_entry, NULL, and san_devices.

Referenced by efi_block_boot().

sandev_reopen()

int sandev_reopen ( struct san_device * sandev )

extern

(Re)open SAN device

Parameters

sandev

SAN device

Return values

rc	Return status code

This function will block until the device is available.

Definition at line 373 of file sanboot.c.

                                                {
        struct san_path *sanpath;
        int rc;
 
        /* Unquiesce system */
        unquiesce();
 
        /* Close any outstanding command and restart interfaces */
        sandev_restart ( sandev, -ECONNRESET );
        assert ( sandev->active == NULL );
        assert ( list_empty ( &sandev->opened ) );
 
        /* Open all paths */
        while ( ( sanpath = list_first_entry ( &sandev->closed,
                                               struct san_path, list ) ) ) {
                if ( ( rc = sanpath_open ( sanpath ) ) != 0 )
                        goto err_open;
        }
 
        /* Wait for any device to become available, or for all devices
         * to fail.
         */
        while ( sandev->active == NULL ) {
                step();
                if ( list_empty ( &sandev->opened ) ) {
                        /* Get status of the first device to be
                         * closed.  Do this on the basis that earlier
                         * errors (e.g. "invalid IQN") are probably
                         * more interesting than later errors
                         * (e.g. "TCP timeout").
                         */
                        rc = -ENODEV;
                        list_for_each_entry ( sanpath, &sandev->closed, list ) {
                                rc = sanpath->path_rc;
                                break;
                        }
                        DBGC ( sandev->drive, "SAN %#02x never became "
                               "available: %s\n", sandev->drive,
                               strerror ( rc ) );
                        goto err_none;
                }
        }
 
        assert ( ! list_empty ( &sandev->opened ) );
        return 0;
 
 err_none:
 err_open:
        sandev_restart ( sandev, rc );
        return rc;
}

References san_device::active, assert, san_device::closed, DBGC, san_device::drive, ECONNRESET, ENODEV, san_path::list, list_empty, list_first_entry, list_for_each_entry, NULL, san_device::opened, san_path::path_rc, rc, san_path::sandev, sandev_restart(), sanpath_open(), step(), strerror(), and unquiesce().

Referenced by int13_device_path_info(), register_sandev(), sandev_command(), and sandev_reset().

sandev_reset()

int sandev_reset ( struct san_device * sandev )

extern

Reset SAN device.

Parameters

sandev

SAN device

Return values

rc	Return status code

Definition at line 576 of file sanboot.c.

                                               {
        int rc;
 
        DBGC ( sandev->drive, "SAN %#02x reset\n", sandev->drive );
 
        /* Close and reopen underlying block device */
        if ( ( rc = sandev_reopen ( sandev ) ) != 0 )
                return rc;
 
        return 0;
}

References DBGC, san_device::drive, rc, san_path::sandev, and sandev_reopen().

Referenced by efi_block_io_reset(), and int13_reset().

sandev_read()

int sandev_read ( struct san_device * sandev, uint64_t lba, unsigned int count, void * buffer )

extern

Read from SAN device.

Parameters

sandev	SAN device
lba	Starting logical block address
count	Number of logical blocks
buffer	Data buffer

Return values

rc	Return status code

Definition at line 647 of file sanboot.c.

                                                     {
        int rc;
 
        /* Read from device */
        if ( ( rc = sandev_rw ( sandev, lba, count, buffer,
                                block_read ) ) != 0 )
                return rc;
 
        return 0;
}

References block_read(), buffer, count, lba, rc, and sandev_rw().

Referenced by efi_block_io_read(), int13_cdrom_read_boot_catalog(), int13_extended_read(), int13_guess_geometry_hdd(), int13_parse_eltorito(), int13_read_sectors(), and sandev_parse_iso9660().

sandev_write()

int sandev_write ( struct san_device * sandev, uint64_t lba, unsigned int count, void * buffer )

extern

Write to SAN device.

Parameters

sandev	SAN device
lba	Starting logical block address
count	Number of logical blocks
buffer	Data buffer

Return values

rc	Return status code

Definition at line 668 of file sanboot.c.

                                                      {
        int rc;
 
        /* Write to device */
        if ( ( rc = sandev_rw ( sandev, lba, count, buffer,
                                block_write ) ) != 0 )
                return rc;
 
        /* Quiesce system.  This is a heuristic designed to ensure
         * that the system is quiesced before Windows starts up, since
         * a Windows SAN boot will typically write a status flag to
         * the disk as its last action before transferring control to
         * the native drivers.
         */
        quiesce();
 
        return 0;
}

References block_write(), buffer, count, lba, quiesce(), rc, and sandev_rw().

Referenced by efi_block_io_write(), int13_extended_write(), and int13_write_sectors().

alloc_sandev()

struct san_device * alloc_sandev ( struct uri ** uris, unsigned int count, size_t priv_size )

extern

Allocate SAN device.

Parameters

uris	List of URIs
count	Number of URIs
priv_size	Size of private data

Return values

sandev

SAN device, or NULL

Definition at line 837 of file sanboot.c.

                                                      {
        struct san_device *sandev;
        struct san_path *sanpath;
        size_t size;
        unsigned int i;
 
        /* Allocate and initialise structure */
        size = ( sizeof ( *sandev ) + ( count * sizeof ( sandev->path[0] ) ) );
        sandev = zalloc ( size + priv_size );
        if ( ! sandev )
                return NULL;
        ref_init ( &sandev->refcnt, sandev_free );
        intf_init ( &sandev->command, &sandev_command_desc, &sandev->refcnt );
        timer_init ( &sandev->timer, sandev_command_expired, &sandev->refcnt );
        sandev->priv = ( ( ( void * ) sandev ) + size );
        sandev->paths = count;
        INIT_LIST_HEAD ( &sandev->opened );
        INIT_LIST_HEAD ( &sandev->closed );
        for ( i = 0 ; i < count ; i++ ) {
                sanpath = &sandev->path[i];
                sanpath->sandev = sandev;
                sanpath->index = i;
                sanpath->uri = uri_get ( uris[i] );
                list_add_tail ( &sanpath->list, &sandev->closed );
                intf_init ( &sanpath->block, &sanpath_block_desc,
                            &sandev->refcnt );
                process_init_stopped ( &sanpath->process, &sanpath_process_desc,
                                       &sandev->refcnt );
                sanpath->path_rc = -EINPROGRESS;
        }
 
        return sandev;
}

References san_path::block, san_device::closed, san_device::command, count, EINPROGRESS, san_path::index, INIT_LIST_HEAD, intf_init(), san_path::list, list_add_tail, NULL, san_device::opened, san_device::path, san_path::path_rc, san_device::paths, san_device::priv, san_path::process, process_init_stopped(), ref_init, san_device::refcnt, san_path::sandev, sandev_command_desc, sandev_command_expired(), sandev_free(), sanpath_block_desc, sanpath_process_desc, size, san_device::timer, san_path::uri, uri_get(), and zalloc().

Referenced by dummy_san_hook(), efi_block_hook(), and int13_hook().

register_sandev()

int register_sandev ( struct san_device * sandev, unsigned int drive, unsigned int flags )

extern

Register SAN device.

Parameters

sandev	SAN device
drive	Drive number
flags	Flags

Return values

rc	Return status code

Definition at line 880 of file sanboot.c.

                                           {
        struct san_device *before;
        int rc;
 
        /* Check that drive number is not in use */
        if ( sandev_find ( drive ) != NULL ) {
                DBGC ( sandev->drive, "SAN %#02x is already in use\n", drive );
                rc = -EADDRINUSE;
                goto err_in_use;
        }
 
        /* Record drive number and flags */
        sandev->drive = drive;
        sandev->flags = flags;
 
        /* Check that device is capable of being opened (i.e. that all
         * URIs are well-formed and that at least one path is
         * working).
         */
        if ( ( rc = sandev_reopen ( sandev ) ) != 0 )
                goto err_reopen;
 
        /* Describe device */
        if ( ( rc = sandev_describe ( sandev ) ) != 0 )
                goto err_describe;
 
        /* Read device capacity */
        if ( ( rc = sandev_command ( sandev, sandev_command_read_capacity,
                                     NULL ) ) != 0 )
                goto err_capacity;
 
        /* Configure as a CD-ROM, if applicable */
        if ( ( rc = sandev_parse_iso9660 ( sandev ) ) != 0 )
                goto err_iso9660;
 
        /* Add to list of SAN devices, in drive order */
        for_each_sandev ( before ) {
                if ( before->drive > sandev->drive )
                        break;
        }
        list_add_tail ( &sandev->list, &before->list );
        DBGC ( sandev->drive, "SAN %#02x registered\n", sandev->drive );
 
        return 0;
 
        list_del ( &sandev->list );
 err_iso9660:
 err_capacity:
 err_describe:
 err_reopen:
        sandev_restart ( sandev, rc );
        sandev_undescribe ( sandev );
 err_in_use:
        return rc;
}

References before, DBGC, drive, san_device::drive, EADDRINUSE, flags, san_device::flags, for_each_sandev, san_device::list, list_add_tail, list_del, NULL, rc, sandev_command(), sandev_command_read_capacity(), sandev_describe(), sandev_find(), sandev_parse_iso9660(), sandev_reopen(), sandev_restart(), and sandev_undescribe().

Referenced by dummy_san_hook(), efi_block_hook(), and int13_hook().

unregister_sandev()

void unregister_sandev ( struct san_device * sandev )

extern

Unregister SAN device.

Parameters

sandev

SAN device

Definition at line 942 of file sanboot.c.

                                                     {
 
        /* Sanity check */
        assert ( ! timer_running ( &sandev->timer ) );
 
        /* Remove from list of SAN devices */
        list_del ( &sandev->list );
 
        /* Shut down interfaces */
        sandev_restart ( sandev, 0 );
 
        /* Remove ACPI descriptors */
        sandev_undescribe ( sandev );
 
        DBGC ( sandev->drive, "SAN %#02x unregistered\n", sandev->drive );
}

References assert, DBGC, san_device::drive, san_device::list, list_del, sandev_restart(), sandev_undescribe(), and san_device::timer.

Referenced by dummy_san_hook(), dummy_san_unhook(), efi_block_hook(), efi_block_unhook(), int13_hook(), and int13_unhook().

san_default_drive()

unsigned int san_default_drive ( void )

extern

Get default SAN drive number.

Return values

drive

Default drive number

Definition at line 973 of file sanboot.c.

                                        {
        unsigned long drive;
 
        /* Use "san-drive" setting, if specified */
        if ( fetch_uint_setting ( NULL, &san_drive_setting, &drive ) >= 0 )
                return drive;
 
        /* Otherwise, default to booting from first hard disk */
        return SAN_DEFAULT_DRIVE;
}

References drive, fetch_uint_setting(), NULL, and SAN_DEFAULT_DRIVE.

Referenced by netboot(), and sanboot_core_exec().

Variable Documentation

san_devices

struct list_head san_devices

extern

Referenced by have_sandevs(), LIST_HEAD(), san_describe(), sandev_find(), and sandev_next().