xref: /freebsd/sys/dev/ofw/ofw_if.m (revision aca5021d5f7dcab1e11692923266373e35322d9a)
1#-
2# Copyright (c) 2008 Nathan Whitehorn
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#include <dev/ofw/openfirm.h>
30#include <dev/ofw/ofwvar.h>
31
32/**
33 * @defgroup OFW ofw - KObj methods for Open Firmware RTAS implementations
34 * @brief A set of methods to implement the Open Firmware client side interface.
35 * @{
36 */
37
38INTERFACE ofw;
39
40/**
41 * @brief Initialize OFW client interface
42 *
43 * @param _cookie	A handle to the client interface, generally the OF
44 *			callback routine.
45 */
46METHOD int init {
47	ofw_t		_ofw;
48	void		*_cookie;
49};
50
51/**
52 * @brief Return next sibling of node.
53 *
54 * @param _node		Selected node
55 */
56METHOD phandle_t peer {
57	ofw_t		_ofw;
58	phandle_t	_node;
59};
60
61/**
62 * @brief Return parent of node.
63 *
64 * @param _node		Selected node
65 */
66METHOD phandle_t parent {
67	ofw_t		_ofw;
68	phandle_t	_node;
69};
70
71/**
72 * @brief Return first child of node.
73 *
74 * @param _node		Selected node
75 */
76METHOD phandle_t child {
77	ofw_t		_ofw;
78	phandle_t	_node;
79};
80
81/**
82 * @brief Return package corresponding to instance.
83 *
84 * @param _handle	Selected instance
85 */
86METHOD phandle_t instance_to_package {
87	ofw_t		_ofw;
88	ihandle_t	_handle;
89};
90
91/**
92 * @brief Return length of node property.
93 *
94 * @param _node		Selected node
95 * @param _prop		Property name
96 */
97METHOD ssize_t getproplen {
98	ofw_t		_ofw;
99	phandle_t	_node;
100	const char	*_prop;
101};
102
103/**
104 * @brief Read node property.
105 *
106 * @param _node		Selected node
107 * @param _prop		Property name
108 * @param _buf		Pointer to buffer
109 * @param _size		Size of buffer
110 */
111METHOD ssize_t getprop {
112	ofw_t		_ofw;
113	phandle_t	_node;
114	const char	*_prop;
115	void		*_buf;
116	size_t		_size;
117};
118
119/**
120 * @brief Get next property name.
121 *
122 * @param _node		Selected node
123 * @param _prop		Current property name
124 * @param _buf		Buffer for next property name
125 * @param _size		Size of buffer
126 */
127METHOD int nextprop {
128	ofw_t		_ofw;
129	phandle_t	_node;
130	const char	*_prop;
131	char		*_buf;
132	size_t		_size;
133};
134
135/**
136 * @brief Set property.
137 *
138 * @param _node		Selected node
139 * @param _prop		Property name
140 * @param _buf		Value to set
141 * @param _size		Size of buffer
142 */
143METHOD int setprop {
144	ofw_t		_ofw;
145	phandle_t	_node;
146	const char	*_prop;
147	const void	*_buf;
148	size_t		_size;
149};
150
151/**
152 * @brief Canonicalize path.
153 *
154 * @param _path		Path to canonicalize
155 * @param _buf		Buffer for canonicalized path
156 * @param _size		Size of buffer
157 */
158METHOD ssize_t canon {
159	ofw_t		_ofw;
160	const char	*_path;
161	char		*_buf;
162	size_t		_size;
163};
164
165/**
166 * @brief Return phandle for named device.
167 *
168 * @param _path		Device path
169 */
170METHOD phandle_t finddevice {
171	ofw_t		_ofw;
172	const char	*_path;
173};
174
175/**
176 * @brief Return path for node instance.
177 *
178 * @param _handle	Instance handle
179 * @param _path		Buffer for path
180 * @param _size		Size of buffer
181 */
182METHOD ssize_t instance_to_path {
183	ofw_t		_ofw;
184	ihandle_t	_handle;
185	char		*_path;
186	size_t		_size;
187};
188
189/**
190 * @brief Return path for node.
191 *
192 * @param _node		Package node
193 * @param _path		Buffer for path
194 * @param _size		Size of buffer
195 */
196METHOD ssize_t package_to_path {
197	ofw_t		_ofw;
198	phandle_t	_node;
199	char		*_path;
200	size_t		_size;
201};
202
203# Methods for OF method calls (optional)
204
205/**
206 * @brief Test to see if a service exists.
207 *
208 * @param _name		name of the service
209 */
210METHOD int test {
211	ofw_t		_ofw;
212	const char	*_name;
213};
214
215/**
216 * @brief Call method belonging to an instance handle.
217 *
218 * @param _instance	Instance handle
219 * @param _method	Method name
220 * @param _nargs	Number of arguments
221 * @param _nreturns	Number of return values
222 * @param _args_and_returns	Values for arguments, followed by returns
223 */
224
225METHOD int call_method {
226	ofw_t		_ofw;
227	ihandle_t	_instance;
228	const char	*_method;
229	int		_nargs;
230	int		_nreturns;
231
232	cell_t		*_args_and_returns;
233};
234
235/**
236 * @brief Interpret a forth command.
237 *
238 * @param _cmd		Command
239 * @param _nreturns	Number of return values
240 * @param _returns	Values for returns
241 */
242
243METHOD int interpret {
244	ofw_t		_ofw;
245	const char	*_cmd;
246	int		_nreturns;
247	cell_t		*_returns;
248};
249
250# Device I/O Functions (optional)
251
252/**
253 * @brief Open node, returning instance handle.
254 *
255 * @param _path		Path to node
256 */
257METHOD ihandle_t open {
258	ofw_t		_ofw;
259	const char	*_path;
260}
261
262/**
263 * @brief Close node instance.
264 *
265 * @param _instance	Instance to close
266 */
267METHOD void close {
268	ofw_t		_ofw;
269	ihandle_t	_instance;
270}
271
272/**
273 * @brief Read from device.
274 *
275 * @param _instance	Device instance
276 * @param _buf		Buffer to read to
277 * @param _size		Size of buffer
278 */
279METHOD ssize_t read {
280	ofw_t		_ofw;
281	ihandle_t	_instance;
282	void		*_buf;
283	size_t		size;
284}
285
286/**
287 * @brief Write to device.
288 *
289 * @param _instance	Device instance
290 * @param _buf		Buffer to write from
291 * @param _size		Size of buffer
292 */
293METHOD ssize_t write {
294	ofw_t		_ofw;
295	ihandle_t	_instance;
296	const void	*_buf;
297	size_t		size;
298}
299
300/**
301 * @brief Seek device.
302 *
303 * @param _instance	Device instance
304 * @param _off		Offset to which to seek
305 */
306METHOD int seek {
307	ofw_t		_ofw;
308	ihandle_t	_instance;
309	uint64_t	_off;
310}
311
312# Open Firmware memory management
313
314/**
315 * @brief Claim virtual memory.
316 *
317 * @param _addr		Requested memory location (NULL for first available)
318 * @param _size		Requested size in bytes
319 * @param _align	Requested alignment
320 */
321METHOD caddr_t claim {
322	ofw_t		_ofw;
323	void		*_addr;
324	size_t		_size;
325	u_int		_align;
326}
327
328/**
329 * @brief Release virtual memory.
330 *
331 * @param _addr		Memory location
332 * @param _size		Size in bytes
333 */
334METHOD void release {
335	ofw_t		_ofw;
336	void		*_addr;
337	size_t		_size;
338};
339
340# Commands for returning control to the firmware
341
342/**
343 * @brief Temporarily return control to firmware.
344 */
345METHOD void enter {
346	ofw_t		_ofw;
347};
348
349/**
350 * @brief Halt and return control to firmware.
351 */
352METHOD void exit {
353	ofw_t		_ofw;
354};
355