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         /** SAN paths */
  89         struct san_path path[0];
  90
  91     unsigned int exdrive;
  92     int int13_command;
  93     void *x86_regptr;
  94     uint8_t boot_catalog_sector[2048];
  95 };
  96
  97 /** SAN device flags */
  98 enum san_device_flags {
  99         /** Device should not be included in description tables */
 100         SAN_NO_DESCRIBE = 0x0001,
 101 };
 102
 103 /**
 104  * Calculate static inline sanboot API function name
 105  *
 106  * @v _prefix           Subsystem prefix
 107  * @v _api_func         API function
 108  * @ret _subsys_func    Subsystem API function
 109  */
 110 #define SANBOOT_INLINE( _subsys, _api_func ) \
 111         SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
 112
 113 /**
 114  * Provide a sanboot API implementation
 115  *
 116  * @v _prefix           Subsystem prefix
 117  * @v _api_func         API function
 118  * @v _func             Implementing function
 119  */
 120 #define PROVIDE_SANBOOT( _subsys, _api_func, _func ) \
 121         PROVIDE_SINGLE_API ( SANBOOT_PREFIX_ ## _subsys, _api_func, _func )
 122
 123 /**
 124  * Provide a static inline sanboot API implementation
 125  *
 126  * @v _prefix           Subsystem prefix
 127  * @v _api_func         API function
 128  */
 129 #define PROVIDE_SANBOOT_INLINE( _subsys, _api_func ) \
 130         PROVIDE_SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
 131
 132 /* Include all architecture-independent sanboot API headers */
 133 #include <ipxe/null_sanboot.h>
 134 #include <ipxe/dummy_sanboot.h>
 135 #include <ipxe/efi/efi_block.h>
 136
 137 /* Include all architecture-dependent sanboot API headers */
 138 #include <bits/sanboot.h>
 139
 140 /**
 141  * Hook SAN device
 142  *
 143  * @v drive             Drive number
 144  * @v uris              List of URIs
 145  * @v count             Number of URIs
 146  * @v flags             Flags
 147  * @ret drive           Drive number, or negative error
 148  */
 149 int san_hook ( unsigned int drive, struct uri **uris, unsigned int count,
 150                unsigned int flags );
 151
 152 /**
 153  * Unhook SAN device
 154  *
 155  * @v drive             Drive number
 156  */
 157 void san_unhook ( unsigned int drive );
 158
 159 /**
 160  * Attempt to boot from a SAN device
 161  *
 162  * @v drive             Drive number
 163  * @v filename          Filename (or NULL to use default)
 164  * @ret rc              Return status code
 165  */
 166 int san_boot ( unsigned int drive, const char *filename );
 167
 168 /**
 169  * Describe SAN devices for SAN-booted operating system
 170  *
 171  * @ret rc              Return status code
 172  */
 173 int san_describe ( void );
 174
 175 extern struct list_head san_devices;
 176
 177 /** Iterate over all SAN devices */
 178 #define for_each_sandev( sandev ) \
 179         list_for_each_entry ( (sandev), &san_devices, list )
 180
 181 /** There exist some SAN devices
 182  *
 183  * @ret existence       Existence of SAN devices
 184  */
 185 static inline int have_sandevs ( void ) {
 186         return ( ! list_empty ( &san_devices ) );
 187 }
 188
 189 /**
 190  * Get reference to SAN device
 191  *
 192  * @v sandev            SAN device
 193  * @ret sandev          SAN device
 194  */
 195 static inline __attribute__ (( always_inline )) struct san_device *
 196 sandev_get ( struct san_device *sandev ) {
 197         ref_get ( &sandev->refcnt );
 198         return sandev;
 199 }
 200
 201 /**
 202  * Drop reference to SAN device
 203  *
 204  * @v sandev            SAN device
 205  */
 206 static inline __attribute__ (( always_inline )) void
 207 sandev_put ( struct san_device *sandev ) {
 208         ref_put ( &sandev->refcnt );
 209 }
 210
 211 /**
 212  * Calculate SAN device block size
 213  *
 214  * @v sandev            SAN device
 215  * @ret blksize         Sector size
 216  */
 217 static inline size_t sandev_blksize ( struct san_device *sandev ) {
 218         return ( sandev->capacity.blksize << sandev->blksize_shift );
 219 }
 220
 221 /**
 222  * Calculate SAN device capacity
 223  *
 224  * @v sandev            SAN device
 225  * @ret blocks          Number of blocks
 226  */
 227 static inline uint64_t sandev_capacity ( struct san_device *sandev ) {
 228         return ( sandev->capacity.blocks >> sandev->blksize_shift );
 229 }
 230
 231 /**
 232  * Check if SAN device needs to be reopened
 233  *
 234  * @v sandev            SAN device
 235  * @ret needs_reopen    SAN device needs to be reopened
 236  */
 237 static inline int sandev_needs_reopen ( struct san_device *sandev ) {
 238         return ( sandev->active == NULL );
 239 }
 240
 241 extern struct san_device * sandev_find ( unsigned int drive );
 242 extern int sandev_reopen ( struct san_device *sandev );
 243 extern int sandev_reset ( struct san_device *sandev );
 244 extern int sandev_read ( struct san_device *sandev, uint64_t lba,
 245                          unsigned int count, userptr_t buffer );
 246 extern int sandev_write ( struct san_device *sandev, uint64_t lba,
 247                           unsigned int count, userptr_t buffer );
 248 extern struct san_device * alloc_sandev ( struct uri **uris, unsigned int count,
 249                                           size_t priv_size );
 250 extern int register_sandev ( struct san_device *sandev, unsigned int drive,
 251                              unsigned int flags );
 252 extern void unregister_sandev ( struct san_device *sandev );
 253 extern unsigned int san_default_drive ( void );
 254
 255 #endif /* _IPXE_SANBOOT_H */