Data-transfer interface should now be functionally complete.
[people/holger/gpxe.git] / src / core / xfer.c
1 /*
2  * Copyright (C) 2007 Michael Brown <mbrown@fensystems.co.uk>.
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License as
6  * published by the Free Software Foundation; either version 2 of the
7  * License, or any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17  */
18
19 #include <string.h>
20 #include <errno.h>
21 #include <gpxe/xfer.h>
22
23 /** @file
24  *
25  * Data transfer interfaces
26  *
27  */
28
29 /**
30  * Close data transfer interface
31  *
32  * @v xfer              Data transfer interface
33  * @v rc                Reason for close
34  */
35 void xfer_close ( struct xfer_interface *xfer, int rc ) {
36         struct xfer_interface *dest = xfer_dest ( xfer );
37
38         dest->op->close ( dest, rc );
39         xfer_unplug ( xfer );
40 }
41
42 /**
43  * Send redirection event
44  *
45  * @v xfer              Data transfer interface
46  * @v type              New location type
47  * @v args              Remaining arguments depend upon location type
48  * @ret rc              Return status code
49  */
50 int xfer_vredirect ( struct xfer_interface *xfer, int type, va_list args ) {
51         struct xfer_interface *dest = xfer_dest ( xfer );
52
53         return dest->op->vredirect ( dest, type, args );
54 }
55
56 /**
57  * Send redirection event
58  *
59  * @v xfer              Data transfer interface
60  * @v type              New location type
61  * @v ...               Remaining arguments depend upon location type
62  * @ret rc              Return status code
63  */
64 int xfer_redirect ( struct xfer_interface *xfer, int type, ... ) {
65         va_list args;
66         int rc;
67
68         va_start ( args, type );
69         rc = xfer_vredirect ( xfer, type, args );
70         va_end ( args );
71         return rc;
72 }
73
74 /**
75  * Request data
76  *
77  * @v xfer              Data transfer interface
78  * @v offset            Offset to new position
79  * @v whence            Basis for new position
80  * @v len               Length of requested data
81  * @ret rc              Return status code
82  */
83 int xfer_request ( struct xfer_interface *xfer, off_t offset, int whence,
84                    size_t len ) {
85         struct xfer_interface *dest = xfer_dest ( xfer );
86
87         return dest->op->request ( dest, offset, whence, len );
88 }
89
90 /**
91  * Request all data
92  *
93  * @v xfer              Data transfer interface
94  * @ret rc              Return status code
95  */
96 int xfer_request_all ( struct xfer_interface *xfer ) {
97         return xfer_request ( xfer, 0, SEEK_SET, ~( ( size_t ) 0 ) );
98 }
99
100 /**
101  * Seek to position
102  *
103  * @v xfer              Data transfer interface
104  * @v offset            Offset to new position
105  * @v whence            Basis for new position
106  * @ret rc              Return status code
107  */
108 int xfer_seek ( struct xfer_interface *xfer, off_t offset, int whence ) {
109         struct xfer_interface *dest = xfer_dest ( xfer );
110
111         return dest->op->seek ( dest, offset, whence );
112 }
113
114 /**
115  * Allocate I/O buffer
116  *
117  * @v xfer              Data transfer interface
118  * @v len               I/O buffer payload length
119  * @ret iobuf           I/O buffer
120  */
121 struct io_buffer * xfer_alloc_iob ( struct xfer_interface *xfer, size_t len ) {
122         struct xfer_interface *dest = xfer_dest ( xfer );
123
124         return dest->op->alloc_iob ( dest, len );
125 }
126
127 /**
128  * Deliver datagram
129  *
130  * @v xfer              Data transfer interface
131  * @v iobuf             Datagram I/O buffer
132  * @ret rc              Return status code
133  */
134 int xfer_deliver_iob ( struct xfer_interface *xfer, struct io_buffer *iobuf ) {
135         struct xfer_interface *dest = xfer_dest ( xfer );
136
137         return dest->op->deliver_iob ( dest, iobuf );
138 }
139
140 /**
141  * Deliver datagram as raw data
142  *
143  * @v xfer              Data transfer interface
144  * @v iobuf             Datagram I/O buffer
145  * @ret rc              Return status code
146  */
147 int xfer_deliver_raw ( struct xfer_interface *xfer,
148                        const void *data, size_t len ) {
149         struct xfer_interface *dest = xfer_dest ( xfer );
150
151         return dest->op->deliver_raw ( dest, data, len );
152 }
153
154 /****************************************************************************
155  *
156  * Helper methods
157  *
158  * These functions are designed to be used as methods in the
159  * xfer_interface_operations table.
160  *
161  */
162
163 /**
164  * Ignore close() event
165  *
166  * @v xfer              Data transfer interface
167  * @v rc                Reason for close
168  */
169 void ignore_xfer_close ( struct xfer_interface *xfer __unused,
170                          int rc __unused ) {
171         /* Nothing to do */
172 }
173
174 /**
175  * Ignore vredirect() event
176  *
177  * @v xfer              Data transfer interface
178  * @v type              New location type
179  * @v args              Remaining arguments depend upon location type
180  * @ret rc              Return status code
181  */
182 int ignore_xfer_vredirect ( struct xfer_interface *xfer __unused,
183                             int type __unused, va_list args __unused ) {
184         return 0;
185 }
186
187 /**
188  * Ignore request() event
189  *
190  * @v xfer              Data transfer interface
191  * @v offset            Offset to new position
192  * @v whence            Basis for new position
193  * @v len               Length of requested data
194  * @ret rc              Return status code
195  */
196 int ignore_xfer_request ( struct xfer_interface *xfer __unused,
197                           off_t offset __unused, int whence __unused, 
198                           size_t len __unused ) {
199         return 0;
200 }
201
202 /**
203  * Ignore seek() event
204  *
205  * @v xfer              Data transfer interface
206  * @v offset            Offset to new position
207  * @v whence            Basis for new position
208  * @ret rc              Return status code
209  */
210 int ignore_xfer_seek ( struct xfer_interface *xfer __unused,
211                        off_t offset __unused, int whence __unused ) {
212         return 0;
213 }
214
215 /**
216  * Allocate I/O buffer
217  *
218  * @v xfer              Data transfer interface
219  * @v len               I/O buffer payload length
220  * @ret iobuf           I/O buffer
221  */
222 struct io_buffer *
223 default_xfer_alloc_iob ( struct xfer_interface *xfer __unused, size_t len ) {
224         return alloc_iob ( len );
225 }
226
227 /**
228  * Deliver datagram as raw data
229  *
230  * @v xfer              Data transfer interface
231  * @v iobuf             Datagram I/O buffer
232  * @ret rc              Return status code
233  *
234  * This function is intended to be used as the deliver() method for
235  * data transfer interfaces that prefer to handle raw data.
236  */
237 int xfer_deliver_as_raw ( struct xfer_interface *xfer,
238                           struct io_buffer *iobuf ) {
239         int rc;
240
241         rc = xfer->op->deliver_raw ( xfer, iobuf->data, iob_len ( iobuf ) );
242         free_iob ( iobuf );
243         return rc;
244 }
245
246 /**
247  * Deliver datagram as I/O buffer
248  *
249  * @v xfer              Data transfer interface
250  * @v data              Data buffer
251  * @v len               Length of data buffer
252  * @ret rc              Return status code
253  *
254  * This function is intended to be used as the deliver_raw() method
255  * for data transfer interfaces that prefer to handle I/O buffers.
256  */
257 int xfer_deliver_as_iob ( struct xfer_interface *xfer,
258                           const void *data, size_t len ) {
259         struct io_buffer *iobuf;
260
261         iobuf = xfer->op->alloc_iob ( xfer, len );
262         if ( ! iobuf )
263                 return -ENOMEM;
264
265         memcpy ( iob_put ( iobuf, len ), data, len );
266         return xfer->op->deliver_iob ( xfer, iobuf );
267 }
268
269 /**
270  * Ignore datagram as raw data event
271  *
272  * @v xfer              Data transfer interface
273  * @v data              Data buffer
274  * @v len               Length of data buffer
275  * @ret rc              Return status code
276  */
277 int ignore_xfer_deliver_raw ( struct xfer_interface *xfer,
278                               const void *data __unused, size_t len ) {
279         DBGC ( xfer, "XFER %p %zd bytes delivered %s\n", xfer, len,
280                ( ( xfer == &null_xfer ) ?
281                  "before connection" : "after termination" ) );
282         return 0;
283 }
284
285 /** Null data transfer interface operations */
286 struct xfer_interface_operations null_xfer_ops = {
287         .close          = ignore_xfer_close,
288         .vredirect      = ignore_xfer_vredirect,
289         .request        = ignore_xfer_request,
290         .seek           = ignore_xfer_seek,
291         .alloc_iob      = default_xfer_alloc_iob,
292         .deliver_iob    = xfer_deliver_as_raw,
293         .deliver_raw    = ignore_xfer_deliver_raw,
294 };
295
296 /**
297  * Null data transfer interface
298  *
299  * This is the interface to which data transfer interfaces are
300  * connected when unplugged.  It will never generate messages, and
301  * will silently absorb all received messages.
302  */
303 struct xfer_interface null_xfer = {
304         .intf = {
305                 .dest = &null_xfer.intf,
306                 .refcnt = NULL,
307         },
308         .op = &null_xfer_ops,
309 };