xfer.h

Go to the documentation of this file.

#ifndef _GPXE_XFER_H
#define _GPXE_XFER_H

/** @file
 *
 * Data transfer interfaces
 *
 */

FILE_LICENCE ( GPL2_OR_LATER );

#include <stddef.h>
#include <stdarg.h>
#include <gpxe/interface.h>
#include <gpxe/iobuf.h>

struct xfer_interface;
struct xfer_metadata;

/** Data transfer interface operations */
struct xfer_interface_operations {
        /** Close interface
         *
         * @v xfer              Data transfer interface
         * @v rc                Reason for close
         */
        void ( * close ) ( struct xfer_interface *xfer, int rc );
        /** Redirect to new location
         *
         * @v xfer              Data transfer interface
         * @v type              New location type
         * @v args              Remaining arguments depend upon location type
         * @ret rc              Return status code
         */
        int ( * vredirect ) ( struct xfer_interface *xfer, int type,
                              va_list args );
        /** Check flow control window
         *
         * @v xfer              Data transfer interface
         * @ret len             Length of window
         *
         * Flow control is regarded as advisory but not mandatory.
         * Users who have control over their own rate of data
         * generation should perform a flow control check before
         * generating new data.  Users who have no control (such as
         * NIC drivers or filter layers) are not obliged to check.
         *
         * Data transfer interfaces must be prepared to accept
         * datagrams even if they are advertising a window of zero
         * bytes.
         */
        size_t ( * window ) ( struct xfer_interface *xfer );
        /** Allocate I/O buffer
         *
         * @v xfer              Data transfer interface
         * @v len               I/O buffer payload length
         * @ret iobuf           I/O buffer
         */
        struct io_buffer * ( * alloc_iob ) ( struct xfer_interface *xfer,
                                             size_t len );
        /** Deliver datagram as I/O buffer with metadata
         *
         * @v xfer              Data transfer interface
         * @v iobuf             Datagram I/O buffer
         * @v meta              Data transfer metadata
         * @ret rc              Return status code
         *
         * A data transfer interface that wishes to support only raw
         * data delivery should set this method to
         * xfer_deliver_as_raw().
         */
        int ( * deliver_iob ) ( struct xfer_interface *xfer,
                                struct io_buffer *iobuf,
                                struct xfer_metadata *meta );
        /** Deliver datagram as raw data
         *
         * @v xfer              Data transfer interface
         * @v data              Data buffer
         * @v len               Length of data buffer
         * @ret rc              Return status code
         *
         * A data transfer interface that wishes to support only I/O
         * buffer delivery should set this method to
         * xfer_deliver_as_iob().
         */
        int ( * deliver_raw ) ( struct xfer_interface *xfer,
                                const void *data, size_t len );
};

/** A data transfer interface */
struct xfer_interface {
        /** Generic object communication interface */
        struct interface intf;
        /** Operations for received messages */
        struct xfer_interface_operations *op;
};

/** Basis positions for seek() events */
enum seek_whence {
        SEEK_CUR = 0,
        SEEK_SET,
};

/** Data transfer metadata */
struct xfer_metadata {
        /** Position of data within stream */
        off_t offset;
        /** Basis for data position
         *
         * Must be one of @c SEEK_CUR or @c SEEK_SET.
         */
        int whence;
        /** Source socket address, or NULL */
        struct sockaddr *src;
        /** Destination socket address, or NULL */
        struct sockaddr *dest;
        /** Network device, or NULL */
        struct net_device *netdev;
};

/**
 * Describe seek basis
 *
 * @v whence            Basis for new position
 */
static inline __attribute__ (( always_inline )) const char *
whence_text ( int whence ) {
        switch ( whence ) {
        case SEEK_CUR:  return "CUR";
        case SEEK_SET:  return "SET";
        default:        return "INVALID";
        }
}

extern struct xfer_interface null_xfer;
extern struct xfer_interface_operations null_xfer_ops;

extern void xfer_close ( struct xfer_interface *xfer, int rc );
extern int xfer_vredirect ( struct xfer_interface *xfer, int type,
                            va_list args );
extern int xfer_redirect ( struct xfer_interface *xfer, int type, ... );
extern size_t xfer_window ( struct xfer_interface *xfer );
extern struct io_buffer * xfer_alloc_iob ( struct xfer_interface *xfer,
                                           size_t len );
extern int xfer_deliver_iob ( struct xfer_interface *xfer,
                              struct io_buffer *iobuf );
extern int xfer_deliver_iob_meta ( struct xfer_interface *xfer,
                                   struct io_buffer *iobuf,
                                   struct xfer_metadata *meta );
extern int xfer_deliver_raw ( struct xfer_interface *xfer,
                              const void *data, size_t len );
extern int xfer_vprintf ( struct xfer_interface *xfer,
                          const char *format, va_list args );
extern int __attribute__ (( format ( printf, 2, 3 ) ))
xfer_printf ( struct xfer_interface *xfer, const char *format, ... );
extern int xfer_seek ( struct xfer_interface *xfer, off_t offset, int whence );

extern void ignore_xfer_close ( struct xfer_interface *xfer, int rc );
extern int ignore_xfer_vredirect ( struct xfer_interface *xfer,
                                   int type, va_list args );
extern size_t unlimited_xfer_window ( struct xfer_interface *xfer );
extern size_t no_xfer_window ( struct xfer_interface *xfer );
extern struct io_buffer * default_xfer_alloc_iob ( struct xfer_interface *xfer,
                                                   size_t len );
extern int xfer_deliver_as_raw ( struct xfer_interface *xfer,
                                 struct io_buffer *iobuf,
                                 struct xfer_metadata *meta );
extern int xfer_deliver_as_iob ( struct xfer_interface *xfer,
                                 const void *data, size_t len );
extern int ignore_xfer_deliver_raw ( struct xfer_interface *xfer,
                                     const void *data __unused, size_t len );

/**
 * Initialise a data transfer interface
 *
 * @v xfer              Data transfer interface
 * @v op                Data transfer interface operations
 * @v refcnt            Containing object reference counter, or NULL
 */
static inline void xfer_init ( struct xfer_interface *xfer,
                               struct xfer_interface_operations *op,
                               struct refcnt *refcnt ) {
        xfer->intf.dest = &null_xfer.intf;
        xfer->intf.refcnt = refcnt;
        xfer->op = op;
}

/**
 * Initialise a static data transfer interface
 *
 * @v operations                Data transfer interface operations
 */
#define XFER_INIT( operations ) {                       \
                .intf = {                               \
                        .dest = &null_xfer.intf,        \
                        .refcnt = NULL,                 \
                },                                      \
                .op = operations,                       \
        }

/**
 * Get data transfer interface from generic object communication interface
 *
 * @v intf              Generic object communication interface
 * @ret xfer            Data transfer interface
 */
static inline __attribute__ (( always_inline )) struct xfer_interface *
intf_to_xfer ( struct interface *intf ) {
        return container_of ( intf, struct xfer_interface, intf );
}

/**
 * Get reference to destination data transfer interface
 *
 * @v xfer              Data transfer interface
 * @ret dest            Destination interface
 */
static inline __attribute__ (( always_inline )) struct xfer_interface *
xfer_get_dest ( struct xfer_interface *xfer ) {
        return intf_to_xfer ( intf_get ( xfer->intf.dest ) );
}

/**
 * Drop reference to data transfer interface
 *
 * @v xfer              Data transfer interface
 */
static inline __attribute__ (( always_inline )) void
xfer_put ( struct xfer_interface *xfer ) {
        intf_put ( &xfer->intf );
}

/**
 * Plug a data transfer interface into a new destination interface
 *
 * @v xfer              Data transfer interface
 * @v dest              New destination interface
 */
static inline __attribute__ (( always_inline )) void
xfer_plug ( struct xfer_interface *xfer, struct xfer_interface *dest ) {
        plug ( &xfer->intf, &dest->intf );
}

/**
 * Plug two data transfer interfaces together
 *
 * @v a                 Data transfer interface A
 * @v b                 Data transfer interface B
 */
static inline __attribute__ (( always_inline )) void
xfer_plug_plug ( struct xfer_interface *a, struct xfer_interface *b ) {
        plug_plug ( &a->intf, &b->intf );
}

/**
 * Unplug a data transfer interface
 *
 * @v xfer              Data transfer interface
 */
static inline __attribute__ (( always_inline )) void
xfer_unplug ( struct xfer_interface *xfer ) {
        plug ( &xfer->intf, &null_xfer.intf );
}

/**
 * Stop using a data transfer interface
 *
 * @v xfer              Data transfer interface
 *
 * After calling this method, no further messages will be received via
 * the interface.
 */
static inline void xfer_nullify ( struct xfer_interface *xfer ) {
        xfer->op = &null_xfer_ops;
};

#endif /* _GPXE_XFER_H */