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