iPXE
sanboot.h
Go to the documentation of this file.
00001 #ifndef _IPXE_SANBOOT_H
00002 #define _IPXE_SANBOOT_H
00003 
00004 /** @file
00005  *
00006  * iPXE sanboot API
00007  *
00008  * The sanboot API provides methods for hooking, unhooking,
00009  * describing, and booting from SAN devices.
00010  */
00011 
00012 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00013 
00014 #include <ipxe/api.h>
00015 #include <ipxe/refcnt.h>
00016 #include <ipxe/list.h>
00017 #include <ipxe/uri.h>
00018 #include <ipxe/retry.h>
00019 #include <ipxe/process.h>
00020 #include <ipxe/blockdev.h>
00021 #include <ipxe/acpi.h>
00022 #include <config/sanboot.h>
00023 
00024 /** A SAN path */
00025 struct san_path {
00026         /** Containing SAN device */
00027         struct san_device *sandev;
00028         /** Path index */
00029         unsigned int index;
00030         /** SAN device URI */
00031         struct uri *uri;
00032         /** List of open/closed paths */
00033         struct list_head list;
00034 
00035         /** Underlying block device interface */
00036         struct interface block;
00037         /** Process */
00038         struct process process;
00039         /** Path status */
00040         int path_rc;
00041 
00042         /** ACPI descriptor (if applicable) */
00043         struct acpi_descriptor *desc;
00044 };
00045 
00046 /** A SAN device */
00047 struct san_device {
00048         /** Reference count */
00049         struct refcnt refcnt;
00050         /** List of SAN devices */
00051         struct list_head list;
00052 
00053         /** Drive number */
00054         unsigned int drive;
00055         /** Flags */
00056         unsigned int flags;
00057 
00058         /** Command interface */
00059         struct interface command;
00060         /** Command timeout timer */
00061         struct retry_timer timer;
00062         /** Command status */
00063         int command_rc;
00064 
00065         /** Raw block device capacity */
00066         struct block_device_capacity capacity;
00067         /** Block size shift
00068          *
00069          * To allow for emulation of CD-ROM access, this represents
00070          * the left-shift required to translate from exposed logical
00071          * I/O blocks to underlying blocks.
00072          */
00073         unsigned int blksize_shift;
00074         /** Drive is a CD-ROM */
00075         int is_cdrom;
00076 
00077         /** Driver private data */
00078         void *priv;
00079 
00080         /** Number of paths */
00081         unsigned int paths;
00082         /** Current active path */
00083         struct san_path *active;
00084         /** List of opened SAN paths */
00085         struct list_head opened;
00086         /** List of closed SAN paths */
00087         struct list_head closed;
00088         /** SAN paths */
00089         struct san_path path[0];
00090 };
00091 
00092 /** SAN device flags */
00093 enum san_device_flags {
00094         /** Device should not be included in description tables */
00095         SAN_NO_DESCRIBE = 0x0001,
00096 };
00097 
00098 /**
00099  * Calculate static inline sanboot API function name
00100  *
00101  * @v _prefix           Subsystem prefix
00102  * @v _api_func         API function
00103  * @ret _subsys_func    Subsystem API function
00104  */
00105 #define SANBOOT_INLINE( _subsys, _api_func ) \
00106         SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
00107 
00108 /**
00109  * Provide a sanboot API implementation
00110  *
00111  * @v _prefix           Subsystem prefix
00112  * @v _api_func         API function
00113  * @v _func             Implementing function
00114  */
00115 #define PROVIDE_SANBOOT( _subsys, _api_func, _func ) \
00116         PROVIDE_SINGLE_API ( SANBOOT_PREFIX_ ## _subsys, _api_func, _func )
00117 
00118 /**
00119  * Provide a static inline sanboot API implementation
00120  *
00121  * @v _prefix           Subsystem prefix
00122  * @v _api_func         API function
00123  */
00124 #define PROVIDE_SANBOOT_INLINE( _subsys, _api_func ) \
00125         PROVIDE_SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
00126 
00127 /* Include all architecture-independent sanboot API headers */
00128 #include <ipxe/null_sanboot.h>
00129 #include <ipxe/dummy_sanboot.h>
00130 #include <ipxe/efi/efi_block.h>
00131 
00132 /* Include all architecture-dependent sanboot API headers */
00133 #include <bits/sanboot.h>
00134 
00135 /**
00136  * Hook SAN device
00137  *
00138  * @v drive             Drive number
00139  * @v uris              List of URIs
00140  * @v count             Number of URIs
00141  * @v flags             Flags
00142  * @ret drive           Drive number, or negative error
00143  */
00144 int san_hook ( unsigned int drive, struct uri **uris, unsigned int count,
00145                unsigned int flags );
00146 
00147 /**
00148  * Unhook SAN device
00149  *
00150  * @v drive             Drive number
00151  */
00152 void san_unhook ( unsigned int drive );
00153 
00154 /**
00155  * Attempt to boot from a SAN device
00156  *
00157  * @v drive             Drive number
00158  * @v filename          Filename (or NULL to use default)
00159  * @ret rc              Return status code
00160  */
00161 int san_boot ( unsigned int drive, const char *filename );
00162 
00163 /**
00164  * Describe SAN devices for SAN-booted operating system
00165  *
00166  * @ret rc              Return status code
00167  */
00168 int san_describe ( void );
00169 
00170 extern struct list_head san_devices;
00171 
00172 /** Iterate over all SAN devices */
00173 #define for_each_sandev( sandev ) \
00174         list_for_each_entry ( (sandev), &san_devices, list )
00175 
00176 /** There exist some SAN devices
00177  *
00178  * @ret existence       Existence of SAN devices
00179  */
00180 static inline int have_sandevs ( void ) {
00181         return ( ! list_empty ( &san_devices ) );
00182 }
00183 
00184 /**
00185  * Get reference to SAN device
00186  *
00187  * @v sandev            SAN device
00188  * @ret sandev          SAN device
00189  */
00190 static inline __attribute__ (( always_inline )) struct san_device *
00191 sandev_get ( struct san_device *sandev ) {
00192         ref_get ( &sandev->refcnt );
00193         return sandev;
00194 }
00195 
00196 /**
00197  * Drop reference to SAN device
00198  *
00199  * @v sandev            SAN device
00200  */
00201 static inline __attribute__ (( always_inline )) void
00202 sandev_put ( struct san_device *sandev ) {
00203         ref_put ( &sandev->refcnt );
00204 }
00205 
00206 /**
00207  * Calculate SAN device block size
00208  *
00209  * @v sandev            SAN device
00210  * @ret blksize         Sector size
00211  */
00212 static inline size_t sandev_blksize ( struct san_device *sandev ) {
00213         return ( sandev->capacity.blksize << sandev->blksize_shift );
00214 }
00215 
00216 /**
00217  * Calculate SAN device capacity
00218  *
00219  * @v sandev            SAN device
00220  * @ret blocks          Number of blocks
00221  */
00222 static inline uint64_t sandev_capacity ( struct san_device *sandev ) {
00223         return ( sandev->capacity.blocks >> sandev->blksize_shift );
00224 }
00225 
00226 /**
00227  * Check if SAN device needs to be reopened
00228  *
00229  * @v sandev            SAN device
00230  * @ret needs_reopen    SAN device needs to be reopened
00231  */
00232 static inline int sandev_needs_reopen ( struct san_device *sandev ) {
00233         return ( sandev->active == NULL );
00234 }
00235 
00236 extern struct san_device * sandev_find ( unsigned int drive );
00237 extern int sandev_reopen ( struct san_device *sandev );
00238 extern int sandev_reset ( struct san_device *sandev );
00239 extern int sandev_read ( struct san_device *sandev, uint64_t lba,
00240                          unsigned int count, userptr_t buffer );
00241 extern int sandev_write ( struct san_device *sandev, uint64_t lba,
00242                           unsigned int count, userptr_t buffer );
00243 extern struct san_device * alloc_sandev ( struct uri **uris, unsigned int count,
00244                                           size_t priv_size );
00245 extern int register_sandev ( struct san_device *sandev, unsigned int drive,
00246                              unsigned int flags );
00247 extern void unregister_sandev ( struct san_device *sandev );
00248 extern unsigned int san_default_drive ( void );
00249 
00250 #endif /* _IPXE_SANBOOT_H */