IPXE/ipxe_mod_code/ipxe-3fe683e/src/include/ipxe/sanboot.h

   1 #ifndef _IPXE_SANBOOT_H
   2 #define _IPXE_SANBOOT_H
   3
   4 /** @file
   5  *
   6  * iPXE sanboot API
   7  *
   8  * The sanboot API provides methods for hooking, unhooking,
   9  * describing, and booting from SAN devices.
  10  */
  11
  12 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
  13
  14 #include <ipxe/api.h>
  15 #include <ipxe/refcnt.h>
  16 #include <ipxe/list.h>
  17 #include <ipxe/uri.h>
  18 #include <ipxe/retry.h>
  19 #include <ipxe/process.h>
  20 #include <ipxe/blockdev.h>
  21 #include <ipxe/acpi.h>
  22 #include <config/sanboot.h>
  23
  24 /** A SAN path */
  25 struct san_path {
  26         /** Containing SAN device */
  27         struct san_device *sandev;
  28         /** Path index */
  29         unsigned int index;
  30         /** SAN device URI */
  31         struct uri *uri;
  32         /** List of open/closed paths */
  33         struct list_head list;
  34
  35         /** Underlying block device interface */
  36         struct interface block;
  37         /** Process */
  38         struct process process;
  39         /** Path status */
  40         int path_rc;
  41
  42         /** ACPI descriptor (if applicable) */
  43         struct acpi_descriptor *desc;
  44 };
  45
  46 /** A SAN device */
  47 struct san_device {
  48         /** Reference count */
  49         struct refcnt refcnt;
  50         /** List of SAN devices */
  51         struct list_head list;
  52
  53         /** Drive number */
  54         unsigned int drive;
  55         /** Flags */
  56         unsigned int flags;
  57
  58         /** Command interface */
  59         struct interface command;
  60         /** Command timeout timer */
  61         struct retry_timer timer;
  62         /** Command status */
  63         int command_rc;
  64
  65         /** Raw block device capacity */
  66         struct block_device_capacity capacity;
  67         /** Block size shift
  68          *
  69          * To allow for emulation of CD-ROM access, this represents
  70          * the left-shift required to translate from exposed logical
  71          * I/O blocks to underlying blocks.
  72          */
  73         unsigned int blksize_shift;
  74         /** Drive is a CD-ROM */
  75         int is_cdrom;
  76
  77         /** Driver private data */
  78         void *priv;
  79
  80         /** Number of paths */
  81         unsigned int paths;
  82         /** Current active path */
  83         struct san_path *active;
  84         /** List of opened SAN paths */
  85         struct list_head opened;
  86         /** List of closed SAN paths */
  87         struct list_head closed;
  88
  89     unsigned int exdrive;
  90     int int13_command;
  91     void *x86_regptr;
  92     uint8_t boot_catalog_sector[2048];
  93
  94         /** SAN paths */
  95         struct san_path path[0];
  96 };
  97
  98 /** SAN device flags */
  99 enum san_device_flags {
 100         /** Device should not be included in description tables */
 101         SAN_NO_DESCRIBE = 0x0001,
 102 };
 103
 104 /**
 105  * Calculate static inline sanboot API function name
 106  *
 107  * @v _prefix           Subsystem prefix
 108  * @v _api_func         API function
 109  * @ret _subsys_func    Subsystem API function
 110  */
 111 #define SANBOOT_INLINE( _subsys, _api_func ) \
 112         SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
 113
 114 /**
 115  * Provide a sanboot API implementation
 116  *
 117  * @v _prefix           Subsystem prefix
 118  * @v _api_func         API function
 119  * @v _func             Implementing function
 120  */
 121 #define PROVIDE_SANBOOT( _subsys, _api_func, _func ) \
 122         PROVIDE_SINGLE_API ( SANBOOT_PREFIX_ ## _subsys, _api_func, _func )
 123
 124 /**
 125  * Provide a static inline sanboot API implementation
 126  *
 127  * @v _prefix           Subsystem prefix
 128  * @v _api_func         API function
 129  */
 130 #define PROVIDE_SANBOOT_INLINE( _subsys, _api_func ) \
 131         PROVIDE_SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
 132
 133 /* Include all architecture-independent sanboot API headers */
 134 #include <ipxe/null_sanboot.h>
 135 #include <ipxe/dummy_sanboot.h>
 136 #include <ipxe/efi/efi_block.h>
 137
 138 /* Include all architecture-dependent sanboot API headers */
 139 #include <bits/sanboot.h>
 140
 141 /**
 142  * Hook SAN device
 143  *
 144  * @v drive             Drive number
 145  * @v uris              List of URIs
 146  * @v count             Number of URIs
 147  * @v flags             Flags
 148  * @ret drive           Drive number, or negative error
 149  */
 150 int san_hook ( unsigned int drive, struct uri **uris, unsigned int count,
 151                unsigned int flags );
 152
 153 /**
 154  * Unhook SAN device
 155  *
 156  * @v drive             Drive number
 157  */
 158 void san_unhook ( unsigned int drive );
 159
 160 /**
 161  * Attempt to boot from a SAN device
 162  *
 163  * @v drive             Drive number
 164  * @v filename          Filename (or NULL to use default)
 165  * @ret rc              Return status code
 166  */
 167 int san_boot ( unsigned int drive, const char *filename );
 168
 169 /**
 170  * Describe SAN devices for SAN-booted operating system
 171  *
 172  * @ret rc              Return status code
 173  */
 174 int san_describe ( void );
 175
 176 extern struct list_head san_devices;
 177
 178 /** Iterate over all SAN devices */
 179 #define for_each_sandev( sandev ) \
 180         list_for_each_entry ( (sandev), &san_devices, list )
 181
 182 /** There exist some SAN devices
 183  *
 184  * @ret existence       Existence of SAN devices
 185  */
 186 static inline int have_sandevs ( void ) {
 187         return ( ! list_empty ( &san_devices ) );
 188 }
 189
 190 /**
 191  * Get reference to SAN device
 192  *
 193  * @v sandev            SAN device
 194  * @ret sandev          SAN device
 195  */
 196 static inline __attribute__ (( always_inline )) struct san_device *
 197 sandev_get ( struct san_device *sandev ) {
 198         ref_get ( &sandev->refcnt );
 199         return sandev;
 200 }
 201
 202 /**
 203  * Drop reference to SAN device
 204  *
 205  * @v sandev            SAN device
 206  */
 207 static inline __attribute__ (( always_inline )) void
 208 sandev_put ( struct san_device *sandev ) {
 209         ref_put ( &sandev->refcnt );
 210 }
 211
 212 /**
 213  * Calculate SAN device block size
 214  *
 215  * @v sandev            SAN device
 216  * @ret blksize         Sector size
 217  */
 218 static inline size_t sandev_blksize ( struct san_device *sandev ) {
 219         return ( sandev->capacity.blksize << sandev->blksize_shift );
 220 }
 221
 222 /**
 223  * Calculate SAN device capacity
 224  *
 225  * @v sandev            SAN device
 226  * @ret blocks          Number of blocks
 227  */
 228 static inline uint64_t sandev_capacity ( struct san_device *sandev ) {
 229         return ( sandev->capacity.blocks >> sandev->blksize_shift );
 230 }
 231
 232 /**
 233  * Check if SAN device needs to be reopened
 234  *
 235  * @v sandev            SAN device
 236  * @ret needs_reopen    SAN device needs to be reopened
 237  */
 238 static inline int sandev_needs_reopen ( struct san_device *sandev ) {
 239         return ( sandev->active == NULL );
 240 }
 241
 242 extern struct san_device * sandev_find ( unsigned int drive );
 243 extern int sandev_reopen ( struct san_device *sandev );
 244 extern int sandev_reset ( struct san_device *sandev );
 245 extern int sandev_read ( struct san_device *sandev, uint64_t lba,
 246                          unsigned int count, userptr_t buffer );
 247 extern int sandev_write ( struct san_device *sandev, uint64_t lba,
 248                           unsigned int count, userptr_t buffer );
 249 extern struct san_device * alloc_sandev ( struct uri **uris, unsigned int count,
 250                                           size_t priv_size );
 251 extern int register_sandev ( struct san_device *sandev, unsigned int drive,
 252                              unsigned int flags );
 253 extern void unregister_sandev ( struct san_device *sandev );
 254 extern unsigned int san_default_drive ( void );
 255
 256 #endif /* _IPXE_SANBOOT_H */