iPXE
sanboot.h
Go to the documentation of this file.
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 <ipxe/uuid.h>
23 #include <config/sanboot.h>
24 
25 /**
26  * Default SAN drive number
27  *
28  * The drive number is an externally defined concept only in a BIOS
29  * environment, where it represents the INT13 drive number (0x80 for
30  * the first hard disk). We retain it in other environments to allow
31  * for a simple way for iPXE commands to refer to SAN drives.
32  */
33 #define SAN_DEFAULT_DRIVE 0x80
34 
35 /** A SAN path */
36 struct san_path {
37  /** Containing SAN device */
38  struct san_device *sandev;
39  /** Path index */
40  unsigned int index;
41  /** SAN device URI */
42  struct uri *uri;
43  /** List of open/closed paths */
44  struct list_head list;
45 
46  /** Underlying block device interface */
47  struct interface block;
48  /** Process */
49  struct process process;
50  /** Path status */
51  int path_rc;
52 
53  /** ACPI descriptor (if applicable) */
55 };
56 
57 /** A SAN device */
58 struct san_device {
59  /** Reference count */
60  struct refcnt refcnt;
61  /** List of SAN devices */
62  struct list_head list;
63 
64  /** Drive number */
65  unsigned int drive;
66  /** Flags */
67  unsigned int flags;
68 
69  /** Command interface */
71  /** Command timeout timer */
73  /** Command status */
75 
76  /** Raw block device capacity */
78  /** Block size shift
79  *
80  * To allow for emulation of CD-ROM access, this represents
81  * the left-shift required to translate from exposed logical
82  * I/O blocks to underlying blocks.
83  */
84  unsigned int blksize_shift;
85  /** Drive is a CD-ROM */
86  int is_cdrom;
87 
88  /** Driver private data */
89  void *priv;
90 
91  /** Number of paths */
92  unsigned int paths;
93  /** Current active path */
94  struct san_path *active;
95  /** List of opened SAN paths */
96  struct list_head opened;
97  /** List of closed SAN paths */
98  struct list_head closed;
99  /** SAN paths */
100  struct san_path path[0];
101 };
102 
103 /** SAN device flags */
105  /** Device should not be included in description tables */
106  SAN_NO_DESCRIBE = 0x0001,
107 };
108 
109 /** SAN boot configuration parameters */
111  /** Boot filename (or NULL to use default) */
112  const char *filename;
113  /** Required extra filename (or NULL to ignore) */
114  const char *extra;
115  /** Filesystem label (or NULL to ignore volume label) */
116  const char *label;
117  /** UUID (or NULL to ignore UUID) */
118  union uuid *uuid;
119 };
120 
121 /**
122  * Calculate static inline sanboot API function name
123  *
124  * @v _prefix Subsystem prefix
125  * @v _api_func API function
126  * @ret _subsys_func Subsystem API function
127  */
128 #define SANBOOT_INLINE( _subsys, _api_func ) \
129  SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
130 
131 /**
132  * Provide a sanboot API implementation
133  *
134  * @v _prefix Subsystem prefix
135  * @v _api_func API function
136  * @v _func Implementing function
137  */
138 #define PROVIDE_SANBOOT( _subsys, _api_func, _func ) \
139  PROVIDE_SINGLE_API ( SANBOOT_PREFIX_ ## _subsys, _api_func, _func )
140 
141 /**
142  * Provide a static inline sanboot API implementation
143  *
144  * @v _prefix Subsystem prefix
145  * @v _api_func API function
146  */
147 #define PROVIDE_SANBOOT_INLINE( _subsys, _api_func ) \
148  PROVIDE_SINGLE_API_INLINE ( SANBOOT_PREFIX_ ## _subsys, _api_func )
149 
150 /* Include all architecture-independent sanboot API headers */
151 #include <ipxe/null_sanboot.h>
152 #include <ipxe/dummy_sanboot.h>
153 #include <ipxe/efi/efi_block.h>
154 
155 /* Include all architecture-dependent sanboot API headers */
156 #include <bits/sanboot.h>
157 
158 /**
159  * Hook SAN device
160  *
161  * @v drive Drive number
162  * @v uris List of URIs
163  * @v count Number of URIs
164  * @v flags Flags
165  * @ret drive Drive number, or negative error
166  */
167 int san_hook ( unsigned int drive, struct uri **uris, unsigned int count,
168  unsigned int flags );
169 
170 /**
171  * Unhook SAN device
172  *
173  * @v drive Drive number
174  */
175 void san_unhook ( unsigned int drive );
176 
177 /**
178  * Attempt to boot from a SAN device
179  *
180  * @v drive Drive number
181  * @v config Boot configuration parameters
182  * @ret rc Return status code
183  */
184 int san_boot ( unsigned int drive, struct san_boot_config *config );
185 
186 /**
187  * Describe SAN devices for SAN-booted operating system
188  *
189  * @ret rc Return status code
190  */
191 int san_describe ( void );
192 
193 extern struct list_head san_devices;
194 
195 /** Iterate over all SAN devices */
196 #define for_each_sandev( sandev ) \
197  list_for_each_entry ( (sandev), &san_devices, list )
198 
199 /** There exist some SAN devices
200  *
201  * @ret existence Existence of SAN devices
202  */
203 static inline int have_sandevs ( void ) {
204  return ( ! list_empty ( &san_devices ) );
205 }
206 
207 /**
208  * Get reference to SAN device
209  *
210  * @v sandev SAN device
211  * @ret sandev SAN device
212  */
213 static inline __attribute__ (( always_inline )) struct san_device *
214 sandev_get ( struct san_device *sandev ) {
215  ref_get ( &sandev->refcnt );
216  return sandev;
217 }
218 
219 /**
220  * Drop reference to SAN device
221  *
222  * @v sandev SAN device
223  */
224 static inline __attribute__ (( always_inline )) void
225 sandev_put ( struct san_device *sandev ) {
226  ref_put ( &sandev->refcnt );
227 }
228 
229 /**
230  * Calculate SAN device block size
231  *
232  * @v sandev SAN device
233  * @ret blksize Sector size
234  */
235 static inline size_t sandev_blksize ( struct san_device *sandev ) {
236  return ( sandev->capacity.blksize << sandev->blksize_shift );
237 }
238 
239 /**
240  * Calculate SAN device capacity
241  *
242  * @v sandev SAN device
243  * @ret blocks Number of blocks
244  */
245 static inline uint64_t sandev_capacity ( struct san_device *sandev ) {
246  return ( sandev->capacity.blocks >> sandev->blksize_shift );
247 }
248 
249 /**
250  * Check if SAN device needs to be reopened
251  *
252  * @v sandev SAN device
253  * @ret needs_reopen SAN device needs to be reopened
254  */
255 static inline int sandev_needs_reopen ( struct san_device *sandev ) {
256  return ( sandev->active == NULL );
257 }
258 
259 extern struct san_device * sandev_find ( unsigned int drive );
260 extern struct san_device * sandev_next ( unsigned int drive );
261 extern int sandev_reopen ( struct san_device *sandev );
262 extern int sandev_reset ( struct san_device *sandev );
263 extern int sandev_read ( struct san_device *sandev, uint64_t lba,
264  unsigned int count, userptr_t buffer );
265 extern int sandev_write ( struct san_device *sandev, uint64_t lba,
266  unsigned int count, userptr_t buffer );
267 extern struct san_device * alloc_sandev ( struct uri **uris, unsigned int count,
268  size_t priv_size );
269 extern int register_sandev ( struct san_device *sandev, unsigned int drive,
270  unsigned int flags );
271 extern void unregister_sandev ( struct san_device *sandev );
272 extern unsigned int san_default_drive ( void );
273 
274 #endif /* _IPXE_SANBOOT_H */
A process.
Definition: process.h:17
static struct san_device * sandev_get(struct san_device *sandev)
Get reference to SAN device.
Definition: sanboot.h:214
#define __attribute__(x)
Definition: compiler.h:10
iPXE internal APIs
int san_describe(void)
Describe SAN devices for SAN-booted operating system.
uint32_t lba
Start address.
Definition: scsi.h:23
int san_hook(unsigned int drive, struct uri **uris, unsigned int count, unsigned int flags)
Hook SAN device.
struct san_path path[0]
SAN paths.
Definition: sanboot.h:100
struct list_head list
List of open/closed paths.
Definition: sanboot.h:44
A universally unique ID.
Definition: uuid.h:15
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
A command-line command.
Definition: command.h:9
int command_rc
Command status.
Definition: sanboot.h:74
Retry timers.
int san_boot(unsigned int drive, struct san_boot_config *config)
Attempt to boot from a SAN device.
struct interface block
Underlying block device interface.
Definition: sanboot.h:47
A retry timer.
Definition: retry.h:21
unsigned long long uint64_t
Definition: stdint.h:13
Universally unique IDs.
struct list_head san_devices
static void sandev_put(struct san_device *sandev)
Drop reference to SAN device.
Definition: sanboot.h:225
x86-specific sanboot API implementations
static int sandev_needs_reopen(struct san_device *sandev)
Check if SAN device needs to be reopened.
Definition: sanboot.h:255
uint32_t buffer
Buffer index (or NETVSC_RNDIS_NO_BUFFER)
Definition: netvsc.h:16
int register_sandev(struct san_device *sandev, unsigned int drive, unsigned int flags)
Register SAN device.
Definition: sanboot.c:877
Standard do-nothing sanboot interface.
uint8_t drive
Drive number.
Definition: int13.h:16
struct list_head opened
List of opened SAN paths.
Definition: sanboot.h:96
Uniform Resource Identifiers.
void unregister_sandev(struct san_device *sandev)
Unregister SAN device.
Definition: sanboot.c:939
unsigned int san_default_drive(void)
Get default SAN drive number.
Definition: sanboot.c:970
unsigned int index
Path index.
Definition: sanboot.h:40
A doubly-linked list entry (or list head)
Definition: list.h:18
A reference counter.
Definition: refcnt.h:26
A timer.
Definition: timer.h:28
Dummy SAN device.
static int have_sandevs(void)
There exist some SAN devices.
Definition: sanboot.h:203
#define list_empty(list)
Test whether a list is empty.
Definition: list.h:136
An object interface.
Definition: interface.h:124
A SAN path.
Definition: sanboot.h:36
unsigned int drive
Drive number.
Definition: sanboot.h:65
SAN boot configuration parameters.
Definition: sanboot.h:110
union uuid * uuid
UUID (or NULL to ignore UUID)
Definition: sanboot.h:118
static uint64_t sandev_capacity(struct san_device *sandev)
Calculate SAN device capacity.
Definition: sanboot.h:245
const char * filename
Boot filename (or NULL to use default)
Definition: sanboot.h:112
unsigned int blksize_shift
Block size shift.
Definition: sanboot.h:84
uint64_t blocks
Total number of blocks.
Definition: blockdev.h:20
sanboot API configuration
Linked lists.
Block devices.
struct list_head closed
List of closed SAN paths.
Definition: sanboot.h:98
ACPI data structures.
int is_cdrom
Drive is a CD-ROM.
Definition: sanboot.h:86
#define ref_get(refcnt)
Get additional reference to object.
Definition: refcnt.h:92
struct list_head list
List of SAN devices.
Definition: sanboot.h:62
int path_rc
Path status.
Definition: sanboot.h:51
A SAN device.
Definition: sanboot.h:58
const char * label
Filesystem label (or NULL to ignore volume label)
Definition: sanboot.h:116
Processes.
Device should not be included in description tables.
Definition: sanboot.h:106
unsigned int paths
Number of paths.
Definition: sanboot.h:92
struct uri * uri
SAN device URI.
Definition: sanboot.h:42
struct block_device_capacity capacity
Raw block device capacity.
Definition: sanboot.h:77
void san_unhook(unsigned int drive)
Unhook SAN device.
An ACPI descriptor (used to construct ACPI tables)
Definition: acpi.h:278
struct san_device * sandev_next(unsigned int drive)
Find next SAN device by drive number.
Definition: sanboot.c:106
Block device capacity.
Definition: blockdev.h:18
struct refcnt refcnt
Reference count.
Definition: sanboot.h:60
int sandev_reset(struct san_device *sandev)
Reset SAN device.
Definition: sanboot.c:574
int sandev_write(struct san_device *sandev, uint64_t lba, unsigned int count, userptr_t buffer)
Write to SAN device.
Definition: sanboot.c:665
const char * extra
Required extra filename (or NULL to ignore)
Definition: sanboot.h:114
void * priv
Driver private data.
Definition: sanboot.h:89
uint16_t count
Number of entries.
Definition: ena.h:22
Reference counting.
static size_t sandev_blksize(struct san_device *sandev)
Calculate SAN device block size.
Definition: sanboot.h:235
int sandev_reopen(struct san_device *sandev)
(Re)open SAN device
Definition: sanboot.c:371
A Uniform Resource Identifier.
Definition: uri.h:64
struct san_path * active
Current active path.
Definition: sanboot.h:94
unsigned int flags
Flags.
Definition: sanboot.h:67
int sandev_read(struct san_device *sandev, uint64_t lba, unsigned int count, userptr_t buffer)
Read from SAN device.
Definition: sanboot.c:645
struct acpi_descriptor * desc
ACPI descriptor (if applicable)
Definition: sanboot.h:54
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
struct san_device * sandev
Containing SAN device.
Definition: sanboot.h:38
struct san_device * sandev_find(unsigned int drive)
Find SAN device by drive number.
Definition: sanboot.c:90
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106
size_t blksize
Block size.
Definition: blockdev.h:22
san_device_flags
SAN device flags.
Definition: sanboot.h:104
unsigned long userptr_t
A pointer to a user buffer.
Definition: uaccess.h:33
struct san_device * alloc_sandev(struct uri **uris, unsigned int count, size_t priv_size)
Allocate SAN device.
Definition: sanboot.c:834
uint8_t flags
Flags.
Definition: ena.h:18