clues::FutexSystemCall Struct Reference

futex() system call with context-sensitive parameters and return values. More...

#include <thread.hxx>

Inheritance diagram for clues::FutexSystemCall:

Public Attributes
item::GenericPointerValue	futex_addr
item::FutexOperation	operation
std::optional< item::Uint32Value >	value
	! the value expected at futex_addr (WAIT, WAIT_REQUEUE_PI).
std::optional< item::Uint32Value >	wake_count
	! number of waiters to wake up (WAKE, REQUEUE, CMP_REQUEUE, WAKE_OP, CMD_REQUEUE_PI).
std::optional< item::SignalNumber >	fd_sig
	! signal used for asynchronous notifications (CREATE_FD).
std::optional< item::TimeSpecParameter >	timeout
	! optional relative timeout (WAIT) or absolute timeout (WAIT_BITSET, LOCK_PI, LOCK_PI2).
std::optional< item::GenericPointerValue >	futex2_addr
	! "uaddr2" requeue address (REQUEUE, CMP_REQUEUE, CMP_REQUEUE_PI, WAIT_REQUEUE_PI) or additional futex (WAKE_OP).
std::optional< item::Uint32Value >	requeue_value
	! "val3" used for comparison in CMP_REQUEUE, CMP_REQUEUE_PI.
std::optional< item::Uint32Value >	requeue_limit
	! "val2", upper limit on waiters to be requeued to addr2 (REQUEUE, CMP_REQUEUE, CMP_REQUEUE_PI).
std::optional< item::Uint32Value >	wake_count2
	! "val2", number of waiters at futex2_addr to wakeup (WAKE_OP).
std::optional< item::FutexWakeOperation >	wake_op
	! instructions for how to perform the wake operation (WAKE_OP).
std::optional< item::GenericPointerValue >	bitset
	! bitset to restrict wait/wakeup (FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET).
std::optional< item::ReturnValue >	num_woken_up
	! number of waiters woken up (WAKE, WAKE_OP).
std::optional< item::FileDescriptor >	new_fd
	! new file descriptor (CREATE_FD).
std::optional< item::SuccessResult >	result
	! success status (all remaining operations).

Protected Member Functions
bool	check2ndPass (const Tracee &) override
	Check whether a second pass needs to be made processing parameters.
void	prepareNewSystemCall () override
	Perform any necessary actions before processing a new system call entry event.
void	updateFDTracking (const Tracee &proc) override
	Update file descriptor tracking.
Protected Member Functions inherited from clues::SystemCall
void	fillParameters (const Tracee &proc, const SystemCallInfo &info)
void	setReturnItem (SystemCallItem &ret)
	Sets the return value system call item.
void	addParameters ()
template<typename T, typename... Targs>
void	addParameters (T &par, Targs &...rest)
template<typename... Targs>
void	setParameters (Targs &...args)
void	dropFD (const Tracee &proc, const cosmos::FileNum num)
void	trackFD (const Tracee &proc, FDInfo &&info)

Additional Inherited Members
Public Types inherited from clues::SystemCall
using	ParameterVector = std::vector<SystemCallItemPtr>
	Vector of the parameters required for a system call.
Public Member Functions inherited from clues::SystemCall
	SystemCall (const SystemCallNr nr)
	Instantiates a new SystemCall object with given properties.
	SystemCall (const SystemCall &other)=delete
SystemCall &	operator= (const SystemCall &other)=delete
void	setEntryInfo (const Tracee &proc, const SystemCallInfo &info)
	Update the stored parameter values from the given tracee.
void	setExitInfo (const Tracee &proc, const SystemCallInfo &info)
	Update possible out and return parameter values from the given tracee.
std::string_view	name () const
	Returns the system call's human readable name.
size_t	numPars () const
	Returns the number of parameters for this system call.
SystemCallNr	callNr () const
	Returns the system call table number for this system call.
const ParameterVector &	parameters () const
	Access to the parameters associated with this system call.
SystemCallItemPtr	result () const
	Access to the return value parameter associated with this system call.
std::optional< ErrnoResult >	error () const
	Access to the errno result seen for this system call.
bool	hasOutParameter () const
bool	hasResultValue () const
bool	hasErrorCode () const
ABI	abi () const
	Returns the system call ABi seen during system call entry.
bool	is32BitEmulationABI () const
const SystemCallInfo *	currentInfo () const
	Access the current SystemCallInfo if currently processing syscall entry/exit.
Static Public Member Functions inherited from clues::SystemCall
static const char *	name (const SystemCallNr nr)
	Returns the name of the given system call or "<unknown>" if unknown.
static bool	validNr (const SystemCallNr nr)
	Returns whether the given system call number is in a valid range.
Protected Attributes inherited from clues::SystemCall
SystemCallNr	m_nr
	The raw system call number of the system call.
const std::string_view	m_name
	The basic name of the system call.
const SystemCallInfo *	m_info = nullptr
	Current system call info during entry/exit processing, nullptr otherwise.
SystemCallItemPtr	m_return
	The return value of the system call.
std::optional< ErrnoResult >	m_error
	If the system call fails, this is the error code.
ParameterVector	m_pars
	The array of system call parameters, if any.
ABI	m_abi = ABI::UNKNOWN
	The current system call ABI which is in effect.

Detailed Description

futex() system call with context-sensitive parameters and return values.

This is an ioctl() style system call or high complexity.

Definition at line 83 of file thread.hxx.

Constructor & Destructor Documentation

FutexSystemCall()

clues::FutexSystemCall::FutexSystemCall ( )

inline

Definition at line 86 of file thread.hxx.

                          :
                        SystemCall{SystemCallNr::FUTEX},
                        futex_addr{"addr", "pointer to futex word"},
                        result{item::SuccessResult{}} {
                /*
                 * minimal default setup, the actual parameters and return
                 * values are setup in the member functions in a
                 * context-sensitive manner.
                 */
                setReturnItem(*result);
                setParameters(futex_addr, operation);
        }

Member Function Documentation

check2ndPass()

bool clues::FutexSystemCall::check2ndPass ( const Tracee & )

overrideprotectedvirtual

Check whether a second pass needs to be made processing parameters.

This function can be overridden by the actual system call implementation to perform context-sensitive evaluation of system call parameters (e.g. for ioctl() style system calls) upon system call entry.

The implementation of this function is allowed to modify the amount and types of system call parameters and return parameter. In this case true must be returned to let the base class implementation reevaluate all system call parameters.

Reimplemented from clues::SystemCall.

Definition at line 31 of file thread.cxx.

                                                 {
        using enum item::FutexOperation::Command;
 
        auto setNewReturnItem = [this](auto &new_ret) {
                result.reset();
                setReturnItem(new_ret);
        };
 
        auto setWokenUpReturnValue = [this, setNewReturnItem]() {
                num_woken_up.emplace(item::ReturnValue{"nwokenup", "number of waiters woken up"});
                setNewReturnItem(*num_woken_up);
        };
 
        const auto command = operation.command();
 
        switch (command) {
        case WAIT: [[fallthrough]];
        case WAIT_BITSET:
                value.emplace(item::Uint32Value{"value"});
                timeout.emplace(item::TimeSpecParameter{"timeout"});
                if (command == WAIT) {
                        addParameters(*value, *timeout);
                } else {
                        bitset.emplace(item::GenericPointerValue{"bitset"});
                        addParameters(*value, *timeout, item::unused, *bitset);
                }
                break;
        case WAKE: [[fallthrough]];
        case WAKE_BITSET:
                wake_count.emplace(item::Uint32Value{"nwakeup", "number of waiters to wake up"});
                if (command == WAKE) {
                        addParameters(*wake_count);
                } else {
                        bitset.emplace(item::GenericPointerValue{"bitset"});
                        addParameters(*wake_count, item::unused, item::unused, *bitset);
                }
 
                setWokenUpReturnValue();
                break;
        case CREATE_FD:
                /*
                 * this operation is not supported anymore, but we model it
                 * anyway
                 */
                fd_sig.emplace(item::SignalNumber{});
                new_fd.emplace(item::FileDescriptor{});
                addParameters(*fd_sig);
                new_fd.emplace(item::FileDescriptor{ItemType::RETVAL});
                setNewReturnItem(*new_fd);
                break;
        case REQUEUE: [[fallthrough]];
        case CMP_REQUEUE: [[fallthrough]];
        case CMP_REQUEUE_PI:
                wake_count.emplace(item::Uint32Value{"nwakeup", "number of waiters to wake up"});
                requeue_limit.emplace(item::Uint32Value{"val2", "max number of waiters to requeue"});
                futex2_addr.emplace(item::GenericPointerValue{"addr2", "requeue address"});
                if (command == REQUEUE) {
                        addParameters(*wake_count, *requeue_limit, *futex2_addr);
                } else {
                        requeue_value.emplace(item::Uint32Value{"val3", "comparison value"});
                        addParameters(*wake_count, *requeue_limit, *futex2_addr, *requeue_value);
                }
 
                setWokenUpReturnValue();
                break;
        case WAKE_OP:
                wake_count.emplace(item::Uint32Value{"nwakeup", "number of waiters to wake up at addr1"});
                wake_count2.emplace(item::Uint32Value{"nwakeup2", "number of waiters to wake up at addr2"});
                futex2_addr.emplace(item::GenericPointerValue{"addr2", "op-futex"});
                wake_op.emplace(item::FutexWakeOperation{});
                addParameters(*wake_count, *wake_count2, *futex2_addr, *wake_op);
 
                setWokenUpReturnValue();
                break;
        case LOCK_PI: [[fallthrough]];
        case LOCK_PI2:
                // absolute timeout measured against CLOCK_REALTIME (or
                // MONOTONIC in case of LOCK_PI2, if the CLOCK_REALTIME flag
                // is not passed in `operation`.
                timeout.emplace(item::TimeSpecParameter{"timeout"});
                addParameters(item::unused, *timeout);
                break;
        case TRYLOCK_PI: [[fallthrough]];
        case UNLOCK_PI:
                // none of the extra arguments are used in these cases
                break;
        case WAIT_REQUEUE_PI:
                value.emplace(item::Uint32Value{"value"});
                // absolute timeout
                timeout.emplace(item::TimeSpecParameter{"timeout"});
                futex2_addr.emplace(item::GenericPointerValue{"addr2", "requeue address"});
                addParameters(*value, *timeout, *futex2_addr);
                break;
        default:
                /* unknown operation? keep defaults. */
                break;
        }
 
        return true;
}

prepareNewSystemCall()

void clues::FutexSystemCall::prepareNewSystemCall ( )

overrideprotectedvirtual

Perform any necessary actions before processing a new system call entry event.

Reimplemented from clues::SystemCall.

Definition at line 6 of file thread.cxx.

                                           {
        /* drop all but the fixed initial two parameters */
        m_pars.erase(m_pars.begin() + 2, m_pars.end());
 
        /* args */
        value.reset();
        wake_count.reset();
        fd_sig.reset();
        timeout.reset();
        futex2_addr.reset();
        requeue_value.reset();
        requeue_limit.reset();
        wake_count2.reset();
        wake_op.reset();
        bitset.reset();
 
        /* retvals */
        num_woken_up.reset();
        new_fd.reset();
 
        // setup the default return value
        result.emplace(item::SuccessResult{});
        setReturnItem(*result);
}

updateFDTracking()

void clues::FutexSystemCall::updateFDTracking ( const Tracee & proc )

overrideprotectedvirtual

Update file descriptor tracking.

This function is called upon successful system call exit to track any potential new file descriptors or stop tracking of existing file descriptors.

Specializations of SystemCall that create or close file descriptors need to overwrite this function and call proc.trackFD() or proc.dropFD() accordingly.

Reimplemented from clues::SystemCall.

Definition at line 132 of file thread.cxx.

                                                         {
        if (new_fd) {
                // we don't even have a type for this, because this feature
                // was dropped in kernel 2.6.26, so I guess it doesn't make
                // sense to track anything here.
                (void)proc;
        }
}

Member Data Documentation

bitset

std::optional<item::GenericPointerValue> clues::FutexSystemCall::bitset

! bitset to restrict wait/wakeup (FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET).

Definition at line 126 of file thread.hxx.

fd_sig

std::optional<item::SignalNumber> clues::FutexSystemCall::fd_sig

! signal used for asynchronous notifications (CREATE_FD).

Definition at line 112 of file thread.hxx.

futex2_addr

std::optional<item::GenericPointerValue> clues::FutexSystemCall::futex2_addr

! "uaddr2" requeue address (REQUEUE, CMP_REQUEUE, CMP_REQUEUE_PI, WAIT_REQUEUE_PI) or additional futex (WAKE_OP).

Definition at line 116 of file thread.hxx.

futex_addr

item::GenericPointerValue clues::FutexSystemCall::futex_addr

Definition at line 102 of file thread.hxx.

new_fd

std::optional<item::FileDescriptor> clues::FutexSystemCall::new_fd

! new file descriptor (CREATE_FD).

Definition at line 133 of file thread.hxx.

num_woken_up

std::optional<item::ReturnValue> clues::FutexSystemCall::num_woken_up

! number of waiters woken up (WAKE, WAKE_OP).

Definition at line 131 of file thread.hxx.

operation

item::FutexOperation clues::FutexSystemCall::operation

Definition at line 103 of file thread.hxx.

requeue_limit

std::optional<item::Uint32Value> clues::FutexSystemCall::requeue_limit

! "val2", upper limit on waiters to be requeued to addr2 (REQUEUE, CMP_REQUEUE, CMP_REQUEUE_PI).

Definition at line 120 of file thread.hxx.

requeue_value

std::optional<item::Uint32Value> clues::FutexSystemCall::requeue_value

! "val3" used for comparison in CMP_REQUEUE, CMP_REQUEUE_PI.

Definition at line 118 of file thread.hxx.

result

std::optional<item::SuccessResult> clues::FutexSystemCall::result

! success status (all remaining operations).

Definition at line 135 of file thread.hxx.

timeout

std::optional<item::TimeSpecParameter> clues::FutexSystemCall::timeout

! optional relative timeout (WAIT) or absolute timeout (WAIT_BITSET, LOCK_PI, LOCK_PI2).

Definition at line 114 of file thread.hxx.

value

std::optional<item::Uint32Value> clues::FutexSystemCall::value

! the value expected at futex_addr (WAIT, WAIT_REQUEUE_PI).

Definition at line 108 of file thread.hxx.

wake_count

std::optional<item::Uint32Value> clues::FutexSystemCall::wake_count

! number of waiters to wake up (WAKE, REQUEUE, CMP_REQUEUE, WAKE_OP, CMD_REQUEUE_PI).

Definition at line 110 of file thread.hxx.

wake_count2

std::optional<item::Uint32Value> clues::FutexSystemCall::wake_count2

! "val2", number of waiters at futex2_addr to wakeup (WAKE_OP).

Definition at line 122 of file thread.hxx.

wake_op

std::optional<item::FutexWakeOperation> clues::FutexSystemCall::wake_op

! instructions for how to perform the wake operation (WAKE_OP).

Definition at line 124 of file thread.hxx.

---

The documentation for this struct was generated from the following files:

• include/syscalls/thread.hxx
• src/syscalls/thread.cxx