xferbuf.c File Reference

Data transfer buffers. More...

#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <ipxe/xfer.h>
#include <ipxe/iobuf.h>
#include <ipxe/umalloc.h>
#include <ipxe/profile.h>
#include <ipxe/image.h>
#include <ipxe/xferbuf.h>

Go to the source code of this file.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
void	xferbuf_free (struct xfer_buffer *xferbuf)
	Free data transfer buffer.
static int	xferbuf_ensure_size (struct xfer_buffer *xferbuf, size_t len)
	Ensure that data transfer buffer is large enough for the specified size.
int	xferbuf_write (struct xfer_buffer *xferbuf, size_t offset, const void *data, size_t len)
	Write to data transfer buffer.
int	xferbuf_read (struct xfer_buffer *xferbuf, size_t offset, void *data, size_t len)
	Read from data transfer buffer.
int	xferbuf_deliver (struct xfer_buffer *xferbuf, struct io_buffer *iobuf, struct xfer_metadata *meta)
	Add received data to data transfer buffer.
static void *	xferbuf_raw_access (struct xfer_buffer *xferbuf)
	Access raw pointer based data buffer.
static int	xferbuf_malloc_realloc (struct xfer_buffer *xferbuf, size_t len)
	Reallocate malloc()-based data transfer buffer.
static int	xferbuf_umalloc_realloc (struct xfer_buffer *xferbuf, size_t len)
	Reallocate umalloc()-based data transfer buffer.
static int	xferbuf_fixed_realloc (struct xfer_buffer *xferbuf, size_t len)
	Reallocate fixed-size data transfer buffer.
static int	xferbuf_void_realloc (struct xfer_buffer *xferbuf, size_t len __unused)
	Reallocate void data transfer buffer.
static int	xferbuf_image_realloc (struct xfer_buffer *xferbuf, size_t len)
	Reallocate image-based data transfer buffer.
static void *	xferbuf_image_access (struct xfer_buffer *xferbuf)
	Access image-based data transfer buffer.
struct xfer_buffer *	xfer_buffer (struct interface *intf)
	Get underlying data transfer buffer.

Variables
static struct profiler xferbuf_deliver_profiler	__profiler
	Data delivery profiler.
struct xfer_buffer_operations	xferbuf_malloc_operations
	malloc()-based data buffer operations
struct xfer_buffer_operations	xferbuf_umalloc_operations
	umalloc()-based data buffer operations
struct xfer_buffer_operations	xferbuf_fixed_operations
	Fixed-size data buffer operations.
struct xfer_buffer_operations	xferbuf_void_operations
	Void data buffer operations.
struct xfer_buffer_operations	xferbuf_image_operations
	Image-based data buffer operations.

Detailed Description

Data transfer buffers.

Data transfer buffers provide an abstraction of an underlying storage buffer, with strictly bounds-checking accessors for reading and writing data and optional automatic resizing. They are designed primarily to act as the ultimate sink for receiving I/O buffers containing downloaded data, after all protocol-level framing has been stripped.

The underlying storage buffer may be backed by a malloc() allocation, a umalloc() allocation, a fixed-size buffer, a downloadable image's data, or a /dev/null-style void buffer.

Consumers of data buffers pass an offset and length when reading from or writing to the buffer. Any integer overflow will be reported as a failure (and no data will be read or written).

Attempting to read beyond the end of a buffer will always fail. Attempting to write beyond the end of a buffer will automatically attempt to resize the buffer to accommodate the write (and will fail if this cannot be done).

An object interface may choose to implement the xfer_buffer() interface method to provide another object with direct access to its own data buffer. This is something of a layering violation, but is required to support the badly designed PeerDist protocol which fails to provide the AES initialisation vector until after the encrypted data has all been received.

Definition in file xferbuf.c.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

xferbuf_free()

void xferbuf_free

(

struct xfer_buffer *

xferbuf

)

Free data transfer buffer.

Parameters

xferbuf

Data transfer buffer

Definition at line 88 of file xferbuf.c.

                                                  {
 
        xferbuf->op->realloc ( xferbuf, 0 );
        xferbuf->len = 0;
        xferbuf->max = 0;
        xferbuf->pos = 0;
}

References xfer_buffer::len, xfer_buffer::max, xfer_buffer::op, xfer_buffer::pos, and xfer_buffer_operations::realloc.

Referenced by peerblk_reset(), peermux_free(), validator_free(), and validator_xfer_close().

xferbuf_ensure_size()

int xferbuf_ensure_size ( struct xfer_buffer * xferbuf, size_t len )

static

Ensure that data transfer buffer is large enough for the specified size.

Parameters

xferbuf	Data transfer buffer
len	Required minimum size

Return values

rc	Return status code

Definition at line 103 of file xferbuf.c.

                                                                           {
        int rc;
 
        /* Record maximum required size */
        if ( len > xferbuf->max )
                xferbuf->max = len;
 
        /* If buffer is already large enough, do nothing */
        if ( len <= xferbuf->len )
                return 0;
 
        /* Extend buffer */
        if ( ( rc = xferbuf->op->realloc ( xferbuf, len ) ) != 0 ) {
                DBGC ( xferbuf, "XFERBUF %p could not extend buffer to "
                       "%zd bytes: %s\n", xferbuf, len, strerror ( rc ) );
                return rc;
        }
        xferbuf->len = len;
 
        return 0;
}

References DBGC, len, xfer_buffer::len, xfer_buffer::max, xfer_buffer::op, rc, xfer_buffer_operations::realloc, and strerror().

Referenced by xferbuf_write().

xferbuf_write()

int xferbuf_write	(	struct xfer_buffer *	xferbuf,
		size_t	offset,
		const void *	data,
		size_t	len )

Write to data transfer buffer.

Parameters

xferbuf	Data transfer buffer
offset	Starting offset
data	Data to write
len	Length of data

Definition at line 133 of file xferbuf.c.

                                                   {
        size_t max_len;
        void *raw;
        int rc;
 
        /* Check for overflow */
        max_len = ( offset + len );
        if ( max_len < offset )
                return -EOVERFLOW;
 
        /* Ensure buffer is large enough to contain this write */
        if ( ( rc = xferbuf_ensure_size ( xferbuf, max_len ) ) != 0 )
                return rc;
 
        /* Copy data to buffer (if non-void) */
        raw = xferbuf->op->access ( xferbuf );
        profile_start ( &xferbuf_write_profiler );
        if ( raw )
                memcpy ( ( raw + offset ), data, len );
        profile_stop ( &xferbuf_write_profiler );
 
        return 0;
}

References xfer_buffer_operations::access, data, EOVERFLOW, len, memcpy(), offset, xfer_buffer::op, profile_start(), profile_stop(), raw, rc, and xferbuf_ensure_size().

Referenced by aoecmd_ata_rsp(), fcpcmd_recv_rddata(), iscsi_rx_data_in(), peerblk_decrypt_write(), peerblk_retrieval_rx(), usbblk_in_data(), and xferbuf_deliver().

xferbuf_read()

int xferbuf_read	(	struct xfer_buffer *	xferbuf,
		size_t	offset,
		void *	data,
		size_t	len )

Read from data transfer buffer.

Parameters

xferbuf	Data transfer buffer
offset	Starting offset
data	Data to write
len	Length of data

Definition at line 166 of file xferbuf.c.

                                            {
        const void *raw;
 
        /* Check that read is within buffer range */
        if ( ( offset > xferbuf->len ) ||
             ( len > ( xferbuf->len - offset ) ) )
                return -ENOENT;
 
        /* Access raw data buffer */
        raw = xferbuf->op->access ( xferbuf );
 
        /* Check that buffer is non-void */
        if ( len && ( ! raw ) )
                return -ENOTTY;
 
        /* Copy data from buffer */
        profile_start ( &xferbuf_read_profiler );
        memcpy ( data, ( raw + offset ), len );
        profile_stop ( &xferbuf_read_profiler );
 
        return 0;
}

References xfer_buffer_operations::access, data, ENOENT, ENOTTY, len, xfer_buffer::len, memcpy(), offset, xfer_buffer::op, profile_start(), profile_stop(), and raw.

Referenced by aoecmd_ata_cmd(), fcpcmd_send_wrdata(), iscsi_tx_data_out(), peerblk_decrypt_read(), and usbblk_out_data().

xferbuf_deliver()

int xferbuf_deliver	(	struct xfer_buffer *	xferbuf,
		struct io_buffer *	iobuf,
		struct xfer_metadata *	meta )

Add received data to data transfer buffer.

Parameters

xferbuf	Data transfer buffer
iobuf	I/O buffer
meta	Data transfer metadata

Return values

rc	Return status code

Definition at line 198 of file xferbuf.c.

                                                   {
        size_t len = iob_len ( iobuf );
        size_t pos;
        int rc;
 
        /* Start profiling */
        profile_start ( &xferbuf_deliver_profiler );
 
        /* Calculate new buffer position */
        pos = xferbuf->pos;
        if ( meta->flags & XFER_FL_ABS_OFFSET )
                pos = 0;
        pos += meta->offset;
 
        /* Write data to buffer */
        if ( ( rc = xferbuf_write ( xferbuf, pos, iobuf->data, len ) ) != 0 )
                goto done;
 
        /* Update current buffer position */
        xferbuf->pos = ( pos + len );
 
 done:
        free_iob ( iobuf );
        profile_stop ( &xferbuf_deliver_profiler );
        return rc;
}

References io_buffer::data, done, free_iob(), iob_len(), len, meta, xfer_buffer::pos, profile_start(), profile_stop(), rc, XFER_FL_ABS_OFFSET, and xferbuf_write().

Referenced by blktrans_deliver(), downloader_deliver(), efi_pxe_tftp_deliver(), peermux_info_deliver(), and validator_xfer_deliver().

xferbuf_raw_access()

void * xferbuf_raw_access ( struct xfer_buffer * xferbuf )

static

Access raw pointer based data buffer.

Parameters

xferbuf

Data transfer buffer

Return values

raw	Raw data pointer

Definition at line 232 of file xferbuf.c.

                                                                 {
 
        return xferbuf->data;
}

References xfer_buffer::data.

xferbuf_malloc_realloc()

int xferbuf_malloc_realloc ( struct xfer_buffer * xferbuf, size_t len )

static

Reallocate malloc()-based data transfer buffer.

Parameters

xferbuf	Data transfer buffer
len	New length (or zero to free buffer)

Return values

rc	Return status code

Definition at line 244 of file xferbuf.c.

                                                                              {
        void *new_data;
 
        new_data = realloc ( xferbuf->data, len );
        if ( ! new_data )
                return -ENOSPC;
        xferbuf->data = new_data;
        return 0;
}

References xfer_buffer::data, ENOSPC, len, and realloc().

xferbuf_umalloc_realloc()

int xferbuf_umalloc_realloc ( struct xfer_buffer * xferbuf, size_t len )

static

Reallocate umalloc()-based data transfer buffer.

Parameters

xferbuf	Data transfer buffer
len	New length (or zero to free buffer)

Return values

rc	Return status code

Definition at line 267 of file xferbuf.c.

                                                                               {
        void *new_udata;
 
        new_udata = urealloc ( xferbuf->data, len );
        if ( ! new_udata )
                return -ENOSPC;
        xferbuf->data = new_udata;
        return 0;
}

References xfer_buffer::data, ENOSPC, len, and urealloc().

xferbuf_fixed_realloc()

int xferbuf_fixed_realloc ( struct xfer_buffer * xferbuf, size_t len )

static

Reallocate fixed-size data transfer buffer.

Parameters

xferbuf	Data transfer buffer
len	New length (or zero to free buffer)

Return values

rc	Return status code

Definition at line 290 of file xferbuf.c.

                                                                             {
 
        /* Refuse to allocate extra space */
        if ( len > xferbuf->len ) {
                /* Note that EFI relies upon this error mapping to
                 * EFI_BUFFER_TOO_SMALL.
                 */
                return -ERANGE;
        }
 
        return 0;
}

References ERANGE, len, and xfer_buffer::len.

xferbuf_void_realloc()

int xferbuf_void_realloc ( struct xfer_buffer * xferbuf, size_t len __unused )

static

Reallocate void data transfer buffer.

Parameters

xferbuf	Data transfer buffer
len	New length (or zero to free buffer)

Return values

rc	Return status code

Definition at line 316 of file xferbuf.c.

                                                        {
 
        /* Succeed without ever allocating data */
        assert ( xferbuf->data == NULL );
        return 0;
}

References __unused, assert, xfer_buffer::data, len, and NULL.

xferbuf_image_realloc()

int xferbuf_image_realloc ( struct xfer_buffer * xferbuf, size_t len )

static

Reallocate image-based data transfer buffer.

Parameters

xferbuf	Data transfer buffer
len	New length (or zero to free buffer)

Return values

rc	Return status code

Definition at line 337 of file xferbuf.c.

                                                                             {
        struct image *image = xferbuf->data;
        int rc;
 
        /* Resize image */
        if ( ( rc = image_set_len ( image, len ) ) != 0 )
                return rc;
 
        return 0;
}

References xfer_buffer::data, image_set_len(), len, and rc.

xferbuf_image_access()

void * xferbuf_image_access ( struct xfer_buffer * xferbuf )

static

Access image-based data transfer buffer.

Parameters

xferbuf

Data transfer buffer

Return values

raw	Raw data pointer

Definition at line 354 of file xferbuf.c.

                                                                   {
        struct image *image = xferbuf->data;
 
        return image->rwdata;
}

References xfer_buffer::data, and image::rwdata.

xfer_buffer()

struct xfer_buffer * xfer_buffer

(

struct interface *

intf

)

Get underlying data transfer buffer.

Parameters

interface

Data transfer interface

Return values

xferbuf

Data transfer buffer, or NULL on error

This call will check that the xfer_buffer() handler belongs to the destination interface which also provides xfer_deliver() for this interface.

This is done to prevent accidental accesses to a data transfer buffer which may be located behind a non-transparent datapath via a series of pass-through interfaces.

Definition at line 380 of file xferbuf.c.

                                                            {
        struct interface *dest;
        xfer_buffer_TYPE ( void * ) *op =
                intf_get_dest_op ( intf, xfer_buffer, &dest );
        void *object = intf_object ( dest );
        struct interface *xfer_deliver_dest;
        struct xfer_buffer *xferbuf;
 
        /* Check that this operation is provided by the same interface
         * which handles xfer_deliver().
         */
        ( void ) intf_get_dest_op ( intf, xfer_deliver, &xfer_deliver_dest );
 
        if ( op && ( dest == xfer_deliver_dest ) ) {
                xferbuf = op ( object );
        } else {
                /* Default is to not have a data transfer buffer */
                xferbuf = NULL;
        }
 
        intf_put ( xfer_deliver_dest );
        intf_put ( dest );
        return xferbuf;
}

References dest, interface::intf, intf_get_dest_op, intf_object(), intf_put(), NULL, op, xfer_buffer_TYPE, and xfer_deliver().

Referenced by http_content_buffer(), peerblk_decrypt(), and peermux_block_buffer().

Variable Documentation

__profiler

struct profiler xferbuf_read_profiler __profiler

static

Initial value:

             =
{ .name = "xferbuf.deliver" }

Data delivery profiler.

Data read profiler.

Data write profiler.

Definition at line 72 of file xferbuf.c.

                                                                { .name = "xferbuf.deliver" };

xferbuf_malloc_operations

struct xfer_buffer_operations xferbuf_malloc_operations

Initial value:

                            = {
        .realloc = xferbuf_malloc_realloc,
        .access = xferbuf_raw_access,
}

malloc()-based data buffer operations

Definition at line 255 of file xferbuf.c.

                                                        {
        .realloc = xferbuf_malloc_realloc,
        .access = xferbuf_raw_access,
};

Referenced by xferbuf_malloc_init().

xferbuf_umalloc_operations

struct xfer_buffer_operations xferbuf_umalloc_operations

Initial value:

                            = {
        .realloc = xferbuf_umalloc_realloc,
        .access = xferbuf_raw_access,
}

umalloc()-based data buffer operations

Definition at line 278 of file xferbuf.c.

                                                         {
        .realloc = xferbuf_umalloc_realloc,
        .access = xferbuf_raw_access,
};

Referenced by xferbuf_umalloc_init().

xferbuf_fixed_operations

struct xfer_buffer_operations xferbuf_fixed_operations

Initial value:

                            = {
        .realloc = xferbuf_fixed_realloc,
        .access = xferbuf_raw_access,
}

Fixed-size data buffer operations.

Definition at line 304 of file xferbuf.c.

                                                       {
        .realloc = xferbuf_fixed_realloc,
        .access = xferbuf_raw_access,
};

Referenced by xferbuf_fixed_init().

xferbuf_void_operations

struct xfer_buffer_operations xferbuf_void_operations

Initial value:

                            = {
        .realloc = xferbuf_void_realloc,
        .access = xferbuf_raw_access,
}

Void data buffer operations.

Definition at line 325 of file xferbuf.c.

                                                      {
        .realloc = xferbuf_void_realloc,
        .access = xferbuf_raw_access,
};

Referenced by xferbuf_void_init().

xferbuf_image_operations

struct xfer_buffer_operations xferbuf_image_operations

Initial value:

                            = {
        .realloc = xferbuf_image_realloc,
        .access = xferbuf_image_access,
}

Image-based data buffer operations.

Definition at line 361 of file xferbuf.c.

                                                       {
        .realloc = xferbuf_image_realloc,
        .access = xferbuf_image_access,
};

Referenced by xferbuf_image_init().