123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277 |
- #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 */
|