xref: /freebsd/stand/userboot/userboot.h (revision 56e53cb8ef000c3ef72337a4095987a932cdedef)
1 /*-
2  * Copyright (c) 2011 Doug Rabson
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24  * SUCH DAMAGE.
25  *
26  * $FreeBSD$
27  */
28 
29 /*
30  * USERBOOT interface versions
31  */
32 #define	USERBOOT_VERSION_1      1
33 #define	USERBOOT_VERSION_2      2
34 #define	USERBOOT_VERSION_3      3
35 
36 /*
37  * Version 4 added more generic callbacks for setting up
38  * registers and descriptors. The callback structure is
39  * backward compatible (new callbacks have been added at
40  * the tail end).
41  */
42 #define	USERBOOT_VERSION_4      4
43 
44 /*
45  * Exit codes from the loader
46  */
47 #define	USERBOOT_EXIT_QUIT      1
48 #define	USERBOOT_EXIT_REBOOT    2
49 
50 struct loader_callbacks {
51 	/*
52 	 * Console i/o
53 	 */
54 
55         /*
56          * Wait until a key is pressed on the console and then return it
57          */
58 	int		(*getc)(void *arg);
59 
60         /*
61          * Write the character ch to the console
62          */
63 	void		(*putc)(void *arg, int ch);
64 
65         /*
66          * Return non-zero if a key can be read from the console
67          */
68 	int		(*poll)(void *arg);
69 
70 	/*
71 	 * Host filesystem i/o
72 	 */
73 
74         /*
75          * Open a file in the host filesystem
76          */
77 	int		(*open)(void *arg, const char *filename, void **h_return);
78 
79         /*
80          * Close a file
81          */
82 	int		(*close)(void *arg, void *h);
83 
84         /*
85          * Return non-zero if the file is a directory
86          */
87 	int		(*isdir)(void *arg, void *h);
88 
89         /*
90          * Read size bytes from a file. The number of bytes remaining
91          * in dst after reading is returned in *resid_return
92          */
93 	int		(*read)(void *arg, void *h, void *dst, size_t size,
94             size_t *resid_return);
95 
96         /*
97          * Read an entry from a directory. The entry's inode number is
98          * returned in *fileno_return, its type in *type_return and
99          * the name length in *namelen_return. The name itself is
100          * copied to the buffer name which must be at least PATH_MAX
101          * in size.
102          */
103 	int		(*readdir)(void *arg, void *h, uint32_t *fileno_return,
104             uint8_t *type_return, size_t *namelen_return, char *name);
105 
106         /*
107          * Seek to a location within an open file
108          */
109 	int		(*seek)(void *arg, void *h, uint64_t offset,
110             int whence);
111 
112         /*
113          * Return some stat(2) related information about the file
114          */
115 	int		(*stat)(void *arg, void *h, int *mode_return,
116             int *uid_return, int *gid_return, uint64_t *size_return);
117 
118 	/*
119 	 * Disk image i/o
120 	 */
121 
122         /*
123          * Read from a disk image at the given offset
124          */
125 	int		(*diskread)(void *arg, int unit, uint64_t offset,
126             void *dst, size_t size, size_t *resid_return);
127 
128 	/*
129 	 * Guest virtual machine i/o
130 	 */
131 
132         /*
133          * Copy to the guest address space
134          */
135 	int		(*copyin)(void *arg, const void *from,
136             uint64_t to, size_t size);
137 
138         /*
139          * Copy from the guest address space
140          */
141 	int		(*copyout)(void *arg, uint64_t from,
142             void *to, size_t size);
143 
144         /*
145          * Set a guest register value
146          */
147 	void		(*setreg)(void *arg, int, uint64_t);
148 
149         /*
150          * Set a guest MSR value
151          */
152 	void		(*setmsr)(void *arg, int, uint64_t);
153 
154         /*
155          * Set a guest CR value
156          */
157 	void		(*setcr)(void *arg, int, uint64_t);
158 
159         /*
160          * Set the guest GDT address
161          */
162         void            (*setgdt)(void *arg, uint64_t, size_t);
163 
164         /*
165          * Transfer control to the guest at the given address
166          */
167 	void		(*exec)(void *arg, uint64_t pc);
168 
169 	/*
170 	 * Misc
171 	 */
172 
173         /*
174          * Sleep for usec microseconds
175          */
176 	void		(*delay)(void *arg, int usec);
177 
178         /*
179          * Exit with the given exit code
180          */
181 	void		(*exit)(void *arg, int v);
182 
183         /*
184          * Return guest physical memory map details
185          */
186 	void		(*getmem)(void *arg, uint64_t *lowmem,
187             uint64_t *highmem);
188 
189 	/*
190 	 * ioctl interface to the disk device
191 	 */
192 	int		(*diskioctl)(void *arg, int unit, u_long cmd,
193 	    void *data);
194 
195 	/*
196 	 * Returns an environment variable in the form "name=value".
197 	 *
198 	 * If there are no more variables that need to be set in the
199 	 * loader environment then return NULL.
200 	 *
201 	 * 'num' is used as a handle for the callback to identify which
202 	 * environment variable to return next. It will begin at 0 and
203 	 * each invocation will add 1 to the previous value of 'num'.
204 	 */
205 	char *		(*getenv)(void *arg, int num);
206 
207 	/*
208 	 * Version 4 additions.
209 	 */
210 	int	(*vm_set_register)(void *arg, int vcpu, int reg, uint64_t val);
211 	int	(*vm_set_desc)(void *arg, int vcpu, int reg, uint64_t base,
212 	    u_int limit, u_int access);
213 };
214