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 <stdio.h>
  21 #include <errno.h>
  22 #include <gpxe/xfer.h>
  23
  24 /** @file
  25  *
  26  * Data transfer interfaces
  27  *
  28  */
  29
  30 /**
  31  * Close data transfer interface
  32  *
  33  * @v xfer              Data transfer interface
  34  * @v rc                Reason for close
  35  */
  36 void xfer_close ( struct xfer_interface *xfer, int rc ) {
  37         struct xfer_interface *dest = xfer_get_dest ( xfer );
  38
  39         DBGC ( xfer, "XFER %p->%p close\n", xfer, dest );
  40
  41         dest->op->close ( dest, rc );
  42         xfer_unplug ( xfer );
  43         xfer_put ( dest );
  44 }
  45
  46 /**
  47  * Send redirection event
  48  *
  49  * @v xfer              Data transfer interface
  50  * @v type              New location type
  51  * @v args              Remaining arguments depend upon location type
  52  * @ret rc              Return status code
  53  */
  54 int xfer_vredirect ( struct xfer_interface *xfer, int type, va_list args ) {
  55         struct xfer_interface *dest = xfer_get_dest ( xfer );
  56         int rc;
  57
  58         DBGC ( xfer, "XFER %p->%p redirect\n", xfer, dest );
  59
  60         rc = dest->op->vredirect ( dest, type, args );
  61
  62         if ( rc != 0 ) {
  63                 DBGC ( xfer, "XFER %p<-%p redirect: %s\n", xfer, dest,
  64                        strerror ( rc ) );
  65         }
  66         xfer_put ( dest );
  67         return rc;
  68 }
  69
  70 /**
  71  * Send redirection event
  72  *
  73  * @v xfer              Data transfer interface
  74  * @v type              New location type
  75  * @v ...               Remaining arguments depend upon location type
  76  * @ret rc              Return status code
  77  */
  78 int xfer_redirect ( struct xfer_interface *xfer, int type, ... ) {
  79         va_list args;
  80         int rc;
  81
  82         va_start ( args, type );
  83         rc = xfer_vredirect ( xfer, type, args );
  84         va_end ( args );
  85         return rc;
  86 }
  87
  88 /**
  89  * Request data
  90  *
  91  * @v xfer              Data transfer interface
  92  * @v offset            Offset to new position
  93  * @v whence            Basis for new position
  94  * @v len               Length of requested data
  95  * @ret rc              Return status code
  96  */
  97 int xfer_request ( struct xfer_interface *xfer, off_t offset, int whence,
  98                    size_t len ) {
  99         struct xfer_interface *dest = xfer_get_dest ( xfer );
 100         int rc;
 101
 102         DBGC ( xfer, "XFER %p->%p request %s+%ld %zd\n", xfer, dest,
 103                whence_text ( whence ), offset, len );
 104
 105         rc = dest->op->request ( dest, offset, whence, len );
 106
 107         if ( rc != 0 ) {
 108                 DBGC ( xfer, "XFER %p<-%p request: %s\n", xfer, dest,
 109                        strerror ( rc ) );
 110         }
 111         xfer_put ( dest );
 112         return rc;
 113 }
 114
 115 /**
 116  * Seek to position
 117  *
 118  * @v xfer              Data transfer interface
 119  * @v offset            Offset to new position
 120  * @v whence            Basis for new position
 121  * @ret rc              Return status code
 122  */
 123 int xfer_seek ( struct xfer_interface *xfer, off_t offset, int whence ) {
 124         struct xfer_interface *dest = xfer_get_dest ( xfer );
 125         int rc;
 126
 127         DBGC ( xfer, "XFER %p->%p seek %s+%ld\n", xfer, dest,
 128                whence_text ( whence ), offset );
 129
 130         rc = dest->op->seek ( dest, offset, whence );
 131
 132         if ( rc != 0 ) {
 133                 DBGC ( xfer, "XFER %p<-%p seek: %s\n", xfer, dest,
 134                        strerror ( rc ) );
 135         }
 136         xfer_put ( dest );
 137         return rc;
 138 }
 139
 140 /**
 141  * Test to see if interface is ready to accept data
 142  *
 143  * @v xfer              Data transfer interface
 144  * @ret rc              Return status code
 145  *
 146  * This test is optional; the data transfer interface may wish that it
 147  * does not yet wish to accept data, but cannot prevent attempts to
 148  * deliver data to it.
 149  */
 150 int xfer_ready ( struct xfer_interface *xfer ) {
 151         return xfer_seek ( xfer, 0, SEEK_CUR );
 152 }
 153
 154 /**
 155  * Allocate I/O buffer
 156  *
 157  * @v xfer              Data transfer interface
 158  * @v len               I/O buffer payload length
 159  * @ret iobuf           I/O buffer
 160  */
 161 struct io_buffer * xfer_alloc_iob ( struct xfer_interface *xfer, size_t len ) {
 162         struct xfer_interface *dest = xfer_get_dest ( xfer );
 163         struct io_buffer *iobuf;
 164
 165         DBGC ( xfer, "XFER %p->%p alloc_iob %zd\n", xfer, dest, len );
 166
 167         iobuf = dest->op->alloc_iob ( dest, len );
 168
 169         if ( ! iobuf ) {
 170                 DBGC ( xfer, "XFER %p<-%p alloc_iob failed\n", xfer, dest );
 171         }
 172         xfer_put ( dest );
 173         return iobuf;
 174 }
 175
 176 /**
 177  * Deliver datagram as I/O buffer with metadata
 178  *
 179  * @v xfer              Data transfer interface
 180  * @v iobuf             Datagram I/O buffer
 181  * @v meta              Data transfer metadata, or NULL
 182  * @ret rc              Return status code
 183  */
 184 int xfer_deliver_iob_meta ( struct xfer_interface *xfer,
 185                             struct io_buffer *iobuf,
 186                             struct xfer_metadata *meta ) {
 187         struct xfer_interface *dest = xfer_get_dest ( xfer );
 188         int rc;
 189
 190         DBGC ( xfer, "XFER %p->%p deliver_iob %zd\n", xfer, dest,
 191                iob_len ( iobuf ) );
 192
 193         rc = dest->op->deliver_iob ( dest, iobuf, meta );
 194
 195         if ( rc != 0 ) {
 196                 DBGC ( xfer, "XFER %p<-%p deliver_iob: %s\n", xfer, dest,
 197                        strerror ( rc ) );
 198         }
 199         xfer_put ( dest );
 200         return rc;
 201 }
 202
 203 /**
 204  * Deliver datagram as I/O buffer with metadata
 205  *
 206  * @v xfer              Data transfer interface
 207  * @v iobuf             Datagram I/O buffer
 208  * @ret rc              Return status code
 209  */
 210 int xfer_deliver_iob ( struct xfer_interface *xfer,
 211                        struct io_buffer *iobuf ) {
 212         return xfer_deliver_iob_meta ( xfer, iobuf, NULL );
 213 }
 214
 215 /**
 216  * Deliver datagram as raw data
 217  *
 218  * @v xfer              Data transfer interface
 219  * @v iobuf             Datagram I/O buffer
 220  * @ret rc              Return status code
 221  */
 222 int xfer_deliver_raw ( struct xfer_interface *xfer,
 223                        const void *data, size_t len ) {
 224         struct xfer_interface *dest = xfer_get_dest ( xfer );
 225         int rc;
 226
 227         DBGC ( xfer, "XFER %p->%p deliver_raw %p+%zd\n", xfer, dest,
 228                data, len );
 229
 230         rc = dest->op->deliver_raw ( dest, data, len );
 231
 232         if ( rc != 0 ) {
 233                 DBGC ( xfer, "XFER %p<-%p deliver_raw: %s\n", xfer, dest,
 234                        strerror ( rc ) );
 235         }
 236         xfer_put ( dest );
 237         return rc;
 238 }
 239
 240 /**
 241  * Deliver formatted string
 242  *
 243  * @v xfer              Data transfer interface
 244  * @v format            Format string
 245  * @v args              Arguments corresponding to the format string
 246  * @ret rc              Return status code
 247  */
 248 int xfer_vprintf ( struct xfer_interface *xfer, const char *format,
 249                    va_list args ) {
 250         size_t len;
 251         va_list args_tmp;
 252
 253         va_copy ( args_tmp, args );
 254         len = vsnprintf ( NULL, 0, format, args );
 255         {
 256                 char buf[len + 1];
 257                 vsnprintf ( buf, sizeof ( buf ), format, args_tmp );
 258                 va_end ( args_tmp );
 259                 return xfer_deliver_raw ( xfer, buf, len );
 260         }
 261 }
 262
 263 /**
 264  * Deliver formatted string
 265  *
 266  * @v xfer              Data transfer interface
 267  * @v format            Format string
 268  * @v ...               Arguments corresponding to the format string
 269  * @ret rc              Return status code
 270  */
 271 int xfer_printf ( struct xfer_interface *xfer, const char *format, ... ) {
 272         va_list args;
 273         int rc;
 274
 275         va_start ( args, format );
 276         rc = xfer_vprintf ( xfer, format, args );
 277         va_end ( args );
 278         return rc;
 279 }
 280
 281 /****************************************************************************
 282  *
 283  * Helper methods
 284  *
 285  * These functions are designed to be used as methods in the
 286  * xfer_interface_operations table.
 287  *
 288  */
 289
 290 /**
 291  * Ignore close() event
 292  *
 293  * @v xfer              Data transfer interface
 294  * @v rc                Reason for close
 295  */
 296 void ignore_xfer_close ( struct xfer_interface *xfer __unused,
 297                          int rc __unused ) {
 298         /* Nothing to do */
 299 }
 300
 301 /**
 302  * Ignore vredirect() event
 303  *
 304  * @v xfer              Data transfer interface
 305  * @v type              New location type
 306  * @v args              Remaining arguments depend upon location type
 307  * @ret rc              Return status code
 308  */
 309 int ignore_xfer_vredirect ( struct xfer_interface *xfer __unused,
 310                             int type __unused, va_list args __unused ) {
 311         return 0;
 312 }
 313
 314 /**
 315  * Ignore request() event
 316  *
 317  * @v xfer              Data transfer interface
 318  * @v offset            Offset to new position
 319  * @v whence            Basis for new position
 320  * @v len               Length of requested data
 321  * @ret rc              Return status code
 322  */
 323 int ignore_xfer_request ( struct xfer_interface *xfer __unused,
 324                           off_t offset __unused, int whence __unused,
 325                           size_t len __unused ) {
 326         return 0;
 327 }
 328
 329 /**
 330  * Ignore seek() event
 331  *
 332  * @v xfer              Data transfer interface
 333  * @v offset            Offset to new position
 334  * @v whence            Basis for new position
 335  * @ret rc              Return status code
 336  */
 337 int ignore_xfer_seek ( struct xfer_interface *xfer __unused,
 338                        off_t offset __unused, int whence __unused ) {
 339         return 0;
 340 }
 341
 342 /**
 343  * Allocate I/O buffer
 344  *
 345  * @v xfer              Data transfer interface
 346  * @v len               I/O buffer payload length
 347  * @ret iobuf           I/O buffer
 348  */
 349 struct io_buffer *
 350 default_xfer_alloc_iob ( struct xfer_interface *xfer __unused, size_t len ) {
 351         return alloc_iob ( len );
 352 }
 353
 354 /**
 355  * Deliver datagram as raw data
 356  *
 357  * @v xfer              Data transfer interface
 358  * @v iobuf             Datagram I/O buffer
 359  * @v meta              Data transfer metadata
 360  * @ret rc              Return status code
 361  *
 362  * This function is intended to be used as the deliver() method for
 363  * data transfer interfaces that prefer to handle raw data.
 364  */
 365 int xfer_deliver_as_raw ( struct xfer_interface *xfer,
 366                           struct io_buffer *iobuf,
 367                           struct xfer_metadata *meta __unused ) {
 368         int rc;
 369
 370         rc = xfer->op->deliver_raw ( xfer, iobuf->data, iob_len ( iobuf ) );
 371         free_iob ( iobuf );
 372         return rc;
 373 }
 374
 375 /**
 376  * Deliver datagram as I/O buffer
 377  *
 378  * @v xfer              Data transfer interface
 379  * @v data              Data buffer
 380  * @v len               Length of data buffer
 381  * @ret rc              Return status code
 382  *
 383  * This function is intended to be used as the deliver_raw() method
 384  * for data transfer interfaces that prefer to handle I/O buffers.
 385  */
 386 int xfer_deliver_as_iob ( struct xfer_interface *xfer,
 387                           const void *data, size_t len ) {
 388         struct io_buffer *iobuf;
 389
 390         iobuf = xfer->op->alloc_iob ( xfer, len );
 391         if ( ! iobuf )
 392                 return -ENOMEM;
 393
 394         memcpy ( iob_put ( iobuf, len ), data, len );
 395         return xfer->op->deliver_iob ( xfer, iobuf, NULL );
 396 }
 397
 398 /**
 399  * Ignore datagram as raw data event
 400  *
 401  * @v xfer              Data transfer interface
 402  * @v data              Data buffer
 403  * @v len               Length of data buffer
 404  * @ret rc              Return status code
 405  */
 406 int ignore_xfer_deliver_raw ( struct xfer_interface *xfer,
 407                               const void *data __unused, size_t len ) {
 408         DBGC ( xfer, "XFER %p %zd bytes delivered %s\n", xfer, len,
 409                ( ( xfer == &null_xfer ) ?
 410                  "before connection" : "after termination" ) );
 411         return 0;
 412 }
 413
 414 /** Null data transfer interface operations */
 415 struct xfer_interface_operations null_xfer_ops = {
 416         .close          = ignore_xfer_close,
 417         .vredirect      = ignore_xfer_vredirect,
 418         .request        = ignore_xfer_request,
 419         .seek           = ignore_xfer_seek,
 420         .alloc_iob      = default_xfer_alloc_iob,
 421         .deliver_iob    = xfer_deliver_as_raw,
 422         .deliver_raw    = ignore_xfer_deliver_raw,
 423 };
 424
 425 /**
 426  * Null data transfer interface
 427  *
 428  * This is the interface to which data transfer interfaces are
 429  * connected when unplugged.  It will never generate messages, and
 430  * will silently absorb all received messages.
 431  */
 432 struct xfer_interface null_xfer = {
 433         .intf = {
 434                 .dest = &null_xfer.intf,
 435                 .refcnt = NULL,
 436         },
 437         .op = &null_xfer_ops,
 438 };