uaccess.h

Go to the documentation of this file.

#ifndef _IPXE_UACCESS_H
#define _IPXE_UACCESS_H

/**
 * @file
 *
 * Access to external ("user") memory
 *
 * iPXE often needs to transfer data between internal and external
 * buffers.  On i386, the external buffers may require access via a
 * different segment, and the buffer address cannot be encoded into a
 * simple void * pointer.  The @c userptr_t type encapsulates the
 * information needed to identify an external buffer, and the
 * copy_to_user() and copy_from_user() functions provide methods for
 * transferring data between internal and external buffers.
 *
 * Note that userptr_t is an opaque type; in particular, performing
 * arithmetic upon a userptr_t is not allowed.
 *
 */

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );

#include <stdint.h>
#include <string.h>
#include <ipxe/api.h>
#include <config/ioapi.h>

/**
 * A pointer to a user buffer
 *
 */
typedef unsigned long userptr_t;

/** Equivalent of NULL for user pointers */
#define UNULL ( ( userptr_t ) 0 )

/**
 * @defgroup uaccess_trivial Trivial user access API implementations
 *
 * User access API implementations that can be used by environments in
 * which virtual addresses allow access to all of memory.
 *
 * @{
 *
 */

/**
 * Convert virtual address to user pointer
 *
 * @v addr              Virtual address
 * @ret userptr         User pointer
 */
static inline __always_inline userptr_t
trivial_virt_to_user ( volatile const void *addr ) {
        return ( ( userptr_t ) addr );
}

/**
 * Convert user pointer to virtual address
 *
 * @v userptr           User pointer
 * @v offset            Offset from user pointer
 * @ret addr            Virtual address
 *
 * This operation is not available under all memory models.
 */
static inline __always_inline void *
trivial_user_to_virt ( userptr_t userptr, off_t offset ) {
        return ( ( void * ) userptr + offset );
}

/**
 * Add offset to user pointer
 *
 * @v userptr           User pointer
 * @v offset            Offset
 * @ret userptr         New pointer value
 */
static inline __always_inline userptr_t
trivial_userptr_add ( userptr_t userptr, off_t offset ) {
        return ( userptr + offset );
}

/**
 * Subtract user pointers
 *
 * @v userptr           User pointer
 * @v subtrahend        User pointer to be subtracted
 * @ret offset          Offset
 */
static inline __always_inline off_t
trivial_userptr_sub ( userptr_t userptr, userptr_t subtrahend ) {
        return ( userptr - subtrahend );
}

/**
 * Copy data between user buffers
 *
 * @v dest              Destination
 * @v dest_off          Destination offset
 * @v src               Source
 * @v src_off           Source offset
 * @v len               Length
 */
static inline __always_inline void
trivial_memcpy_user ( userptr_t dest, off_t dest_off,
                      userptr_t src, off_t src_off, size_t len ) {
        memcpy ( ( ( void * ) dest + dest_off ),
                 ( ( void * ) src + src_off ), len );
}

/**
 * Copy data between user buffers, allowing for overlap
 *
 * @v dest              Destination
 * @v dest_off          Destination offset
 * @v src               Source
 * @v src_off           Source offset
 * @v len               Length
 */
static inline __always_inline void
trivial_memmove_user ( userptr_t dest, off_t dest_off,
                       userptr_t src, off_t src_off, size_t len ) {
        memmove ( ( ( void * ) dest + dest_off ),
                  ( ( void * ) src + src_off ), len );
}

/**
 * Compare data between user buffers
 *
 * @v first             First buffer
 * @v first_off         First buffer offset
 * @v second            Second buffer
 * @v second_off        Second buffer offset
 * @v len               Length
 * @ret diff            Difference
 */
static inline __always_inline int
trivial_memcmp_user ( userptr_t first, off_t first_off,
                      userptr_t second, off_t second_off, size_t len ) {
        return memcmp ( ( ( void * ) first + first_off ),
                        ( ( void * ) second + second_off ), len );
}

/**
 * Fill user buffer with a constant byte
 *
 * @v buffer            User buffer
 * @v offset            Offset within buffer
 * @v c                 Constant byte with which to fill
 * @v len               Length
 */
static inline __always_inline void
trivial_memset_user ( userptr_t buffer, off_t offset, int c, size_t len ) {
        memset ( ( ( void * ) buffer + offset ), c, len );
}

/**
 * Find length of NUL-terminated string in user buffer
 *
 * @v buffer            User buffer
 * @v offset            Offset within buffer
 * @ret len             Length of string (excluding NUL)
 */
static inline __always_inline size_t
trivial_strlen_user ( userptr_t buffer, off_t offset ) {
        return strlen ( ( void * ) buffer + offset );
}

/**
 * Find character in user buffer
 *
 * @v buffer            User buffer
 * @v offset            Starting offset within buffer
 * @v c                 Character to search for
 * @v len               Length of user buffer
 * @ret offset          Offset of character, or <0 if not found
 */
static inline __always_inline off_t
trivial_memchr_user ( userptr_t buffer, off_t offset, int c, size_t len ) {
        void *found;

        found = memchr ( ( ( void * ) buffer + offset ), c, len );
        return ( found ? ( found - ( void * ) buffer ) : -1 );
}

/** @} */

/**
 * Calculate static inline user access API function name
 *
 * @v _prefix           Subsystem prefix
 * @v _api_func         API function
 * @ret _subsys_func    Subsystem API function
 */
#define UACCESS_INLINE( _subsys, _api_func ) \
        SINGLE_API_INLINE ( UACCESS_PREFIX_ ## _subsys, _api_func )

/**
 * Provide an user access API implementation
 *
 * @v _prefix           Subsystem prefix
 * @v _api_func         API function
 * @v _func             Implementing function
 */
#define PROVIDE_UACCESS( _subsys, _api_func, _func ) \
        PROVIDE_SINGLE_API ( UACCESS_PREFIX_ ## _subsys, _api_func, _func )

/**
 * Provide a static inline user access API implementation
 *
 * @v _prefix           Subsystem prefix
 * @v _api_func         API function
 */
#define PROVIDE_UACCESS_INLINE( _subsys, _api_func ) \
        PROVIDE_SINGLE_API_INLINE ( UACCESS_PREFIX_ ## _subsys, _api_func )

/* Include all architecture-independent user access API headers */
#include <ipxe/efi/efi_uaccess.h>
#include <ipxe/linux/linux_uaccess.h>

/* Include all architecture-dependent user access API headers */
#include <bits/uaccess.h>

/**
 * Convert physical address to user pointer
 *
 * @v phys_addr         Physical address
 * @ret userptr         User pointer
 */
userptr_t phys_to_user ( unsigned long phys_addr );

/**
 * Convert user pointer to physical address
 *
 * @v userptr           User pointer
 * @v offset            Offset from user pointer
 * @ret phys_addr       Physical address
 */
unsigned long user_to_phys ( userptr_t userptr, off_t offset );

/**
 * Convert virtual address to user pointer
 *
 * @v addr              Virtual address
 * @ret userptr         User pointer
 */
userptr_t virt_to_user ( volatile const void *addr );

/**
 * Convert user pointer to virtual address
 *
 * @v userptr           User pointer
 * @v offset            Offset from user pointer
 * @ret addr            Virtual address
 *
 * This operation is not available under all memory models.
 */
void * user_to_virt ( userptr_t userptr, off_t offset );

/**
 * Add offset to user pointer
 *
 * @v userptr           User pointer
 * @v offset            Offset
 * @ret userptr         New pointer value
 */
userptr_t userptr_add ( userptr_t userptr, off_t offset );

/**
 * Subtract user pointers
 *
 * @v userptr           User pointer
 * @v subtrahend        User pointer to be subtracted
 * @ret offset          Offset
 */
off_t userptr_sub ( userptr_t userptr, userptr_t subtrahend );

/**
 * Convert virtual address to a physical address
 *
 * @v addr              Virtual address
 * @ret phys_addr       Physical address
 */
static inline __always_inline unsigned long
virt_to_phys ( volatile const void *addr ) {
        return user_to_phys ( virt_to_user ( addr ), 0 );
}

/**
 * Convert physical address to a virtual address
 *
 * @v addr              Virtual address
 * @ret phys_addr       Physical address
 *
 * This operation is not available under all memory models.
 */
static inline __always_inline void * phys_to_virt ( unsigned long phys_addr ) {
        return user_to_virt ( phys_to_user ( phys_addr ), 0 );
}

/**
 * Copy data between user buffers
 *
 * @v dest              Destination
 * @v dest_off          Destination offset
 * @v src               Source
 * @v src_off           Source offset
 * @v len               Length
 */
void memcpy_user ( userptr_t dest, off_t dest_off,
                   userptr_t src, off_t src_off, size_t len );

/**
 * Copy data to user buffer
 *
 * @v dest              Destination
 * @v dest_off          Destination offset
 * @v src               Source
 * @v len               Length
 */
static inline __always_inline void
copy_to_user ( userptr_t dest, off_t dest_off, const void *src, size_t len ) {
        memcpy_user ( dest, dest_off, virt_to_user ( src ), 0, len );
}

/**
 * Copy data from user buffer
 *
 * @v dest              Destination
 * @v src               Source
 * @v src_off           Source offset
 * @v len               Length
 */
static inline __always_inline void
copy_from_user ( void *dest, userptr_t src, off_t src_off, size_t len ) {
        memcpy_user ( virt_to_user ( dest ), 0, src, src_off, len );
}

/**
 * Copy data between user buffers, allowing for overlap
 *
 * @v dest              Destination
 * @v dest_off          Destination offset
 * @v src               Source
 * @v src_off           Source offset
 * @v len               Length
 */
void memmove_user ( userptr_t dest, off_t dest_off,
                    userptr_t src, off_t src_off, size_t len );

/**
 * Compare data between user buffers
 *
 * @v first             First buffer
 * @v first_off         First buffer offset
 * @v second            Second buffer
 * @v second_off        Second buffer offset
 * @v len               Length
 * @ret diff            Difference
 */
int memcmp_user ( userptr_t first, off_t first_off,
                  userptr_t second, off_t second_off, size_t len );

/**
 * Fill user buffer with a constant byte
 *
 * @v userptr           User buffer
 * @v offset            Offset within buffer
 * @v c                 Constant byte with which to fill
 * @v len               Length
 */
void memset_user ( userptr_t userptr, off_t offset, int c, size_t len );

/**
 * Find length of NUL-terminated string in user buffer
 *
 * @v userptr           User buffer
 * @v offset            Offset within buffer
 * @ret len             Length of string (excluding NUL)
 */
size_t strlen_user ( userptr_t userptr, off_t offset );

/**
 * Find character in user buffer
 *
 * @v userptr           User buffer
 * @v offset            Starting offset within buffer
 * @v c                 Character to search for
 * @v len               Length of user buffer
 * @ret offset          Offset of character, or <0 if not found
 */
off_t memchr_user ( userptr_t userptr, off_t offset, int c, size_t len );

#endif /* _IPXE_UACCESS_H */