The futex operation to be performed in the context of a futex system call. More...

#include <futex.hxx>

Inheritance diagram for clues::item::FutexOperation:

Public Types
enum class	Command : int { WAIT = FUTEX_WAIT , WAKE = FUTEX_WAKE , WAIT_REQUEUE_PI = FUTEX_WAIT_REQUEUE_PI , CREATE_FD = FUTEX_FD , REQUEUE = FUTEX_REQUEUE , CMP_REQUEUE = FUTEX_CMP_REQUEUE , CMP_REQUEUE_PI = FUTEX_CMP_REQUEUE_PI , WAKE_OP = FUTEX_WAKE_OP , WAIT_BITSET = FUTEX_WAIT_BITSET , WAKE_BITSET = FUTEX_WAKE_BITSET , LOCK_PI = FUTEX_LOCK_PI , LOCK_PI2 = FUTEX_LOCK_PI2 , TRYLOCK_PI = FUTEX_TRYLOCK_PI , UNLOCK_PI = FUTEX_UNLOCK_PI }

enum class	Flag : int { PRIVATE_FLAG = FUTEX_PRIVATE_FLAG , REALTIME = FUTEX_CLOCK_REALTIME }

using	Flags = cosmos::BitMask<Flag>

Public Types inherited from clues::SystemCallItem
enum class	Flag { DEFER_FILL = 1 << 0 }

using	Flags = cosmos::BitMask<Flag>

Public Member Functions
std::string	str () const override
	Returns a human readable string representation of the item.

void	processValue (const Tracee &) override
	Processes the value stored in m_val acc. to the actual item type.

auto	command () const

auto	flags () const

Public Member Functions inherited from clues::item::ValueInParameter
	ValueInParameter (const std::string_view short_name, const std::string_view long_name={})

Public Member Functions inherited from clues::item::ValueParameter
	ValueParameter (const ItemType type, const std::string_view short_name, const std::string_view long_name={})

Public Member Functions inherited from clues::SystemCallItem
	SystemCallItem (const ItemType type, const std::string_view short_name={}, const std::string_view long_name={})
	Constructs a new SystemCallItem.

auto	type () const

bool	isIn () const

bool	isOut () const

bool	isInOut () const

bool	isReturnValue () const

void	fill (const Tracee &proc, const Word word)
	Fills the item from the given register data.

bool	needsUpdate () const
	Returns whether the item needs to be updated after the system call is finished.

std::string_view	shortName () const
	Returns the friendly short name for this item.

std::string_view	longName () const
	Returns the friendly long name for this item, if available, else the short name.

auto	hasLongName () const

bool	isZero () const
	Returns whether the parameter is set to 0 / NULL.

Word	value () const
	Returns the currently stored raw value of the item.

template<typename OTHER>
OTHER	valueAs () const
	Helper to cast the strongly typed `Word` `m_val` to other strong enum types.

ForeignPtr	asPtr () const

Flags	flags () const

bool	deferFill () const

Protected Attributes
Command	m_cmd = Command{0}

Flags	m_flags

Protected Attributes inherited from clues::SystemCallItem
const SystemCall *	m_call = nullptr
	The system call context this item part of.

const ItemType	m_type
	The type of item.

std::string_view	m_short_name
	A human readable short name for the item, should be one word only.

std::string_view	m_long_name
	A human readable longer name for the item.

Word	m_val
	The raw register value for the item.

Flags	m_flags
	Flags influencing the processing of the item.

Additional Inherited Members
Protected Member Functions inherited from clues::SystemCallItem
virtual void	updateData (const Tracee &t)
	Called upon exit of the system call to update possible out parameters.

void	setSystemCall (const SystemCall &sc)
	Sets the system call context this item is a part of.

Detailed Description

The futex operation to be performed in the context of a futex system call.

The operation consists of a command and a set of bit mask flags.

Definition at line 18 of file futex.hxx.

Member Typedef Documentation

◆ Flags

using clues::item::FutexOperation::Flags = cosmos::BitMask<Flag>

Definition at line 44 of file futex.hxx.

Member Enumeration Documentation

◆ Command

enum class clues::item::FutexOperation::Command : int

strong

Definition at line 22 of file futex.hxx.

                           : int {
                WAIT            = FUTEX_WAIT, /* wait for `val` to be changed */
                WAKE            = FUTEX_WAKE, /* wake given number of waiters */
                WAIT_REQUEUE_PI = FUTEX_WAIT_REQUEUE_PI, /* wait on a non-PI futex, potentially being requeued to a PI futex on addr2 */
                CREATE_FD       = FUTEX_FD, /* create a futex FD, dropped in Linux 2.6.25 */
                REQUEUE         = FUTEX_REQUEUE, /* wakeup some waiters, requeue others */
                CMP_REQUEUE     = FUTEX_CMP_REQUEUE, /* additionally compare futex value */
                CMP_REQUEUE_PI  = FUTEX_CMP_REQUEUE_PI, /* CMP_REQUEUE with priority-inheritance semantics. `val1` must be 1. */
                WAKE_OP         = FUTEX_WAKE_OP, /* wake up waiters based on provided criteria */
                WAIT_BITSET     = FUTEX_WAIT_BITSET, /* wait based on a 32-bit bitset limiting wakeups */
                WAKE_BITSET     = FUTEX_WAKE_BITSET, /* wake up waiters with matching bits in a 32-bit bitset */
                LOCK_PI         = FUTEX_LOCK_PI, /* priority-inheritance lock operation */
                LOCK_PI2        = FUTEX_LOCK_PI2, /* save as above, but supports Flag::REALTIME on top */
                TRYLOCK_PI      = FUTEX_TRYLOCK_PI, /* try to lock the futex based on extra kernel information, does not block */
                UNLOCK_PI       = FUTEX_UNLOCK_PI, /* unlock with priority inheritance semantics */
        };

◆ Flag

enum class clues::item::FutexOperation::Flag : int

strong

Definition at line 39 of file futex.hxx.

                        : int {
                PRIVATE_FLAG = FUTEX_PRIVATE_FLAG, /* futex between threads only */
                REALTIME = FUTEX_CLOCK_REALTIME, /* for wait related operations, use CLOCK_REALTIME instead of MONOTONIC */
        };

Constructor & Destructor Documentation

◆ FutexOperation()

clues::item::FutexOperation::FutexOperation ( )

inlineexplicit

Definition at line 48 of file futex.hxx.

                                  :
                        ValueInParameter{"op", "futex operation"} {
        }

Member Function Documentation

◆ command()

auto clues::item::FutexOperation::command ( ) const

inline

Definition at line 56 of file futex.hxx.

                             {
                return m_cmd;
        }

◆ flags()

auto clues::item::FutexOperation::flags ( ) const

inline

Definition at line 60 of file futex.hxx.

                           {
                return m_flags;
        }

◆ processValue()

void clues::item::FutexOperation::processValue ( const Tracee & )

overridevirtual

Processes the value stored in m_val acc. to the actual item type.

This function is called for all parameter types upon entry to a system call, and for ItemType::RETVAL upon exit from a system call.

For parameters of ItemType::PARAM_OUT this callback can be used to reset any stored data to be filled in later when updateData() is called.

Reimplemented from clues::SystemCallItem.

Definition at line 54 of file futex.cxx.

                                                {
        m_cmd = Command{valueAs<int>() & FUTEX_CMD_MASK};
        m_flags = Flags{valueAs<int>() xor cosmos::to_integral(m_cmd)};
}

◆ str()

std::string clues::item::FutexOperation::str ( ) const

overridevirtual

Returns a human readable string representation of the item.

This member function should be specialized in derived classes to output the item's data in a fashion suitable for the concrete item type.

Reimplemented from clues::SystemCallItem.

Definition at line 11 of file futex.cxx.

                                    {
        /*
         * there are a number of undocumented constants and some flags can be
         * or'd in like FUTEX_PRIVATE_FLAG. Without exactly understanding that
         * we can't sensibly trace this ...
         * it seems the man page doesn't tell the complete story, strace
         * understands all the "private" stuff that can also be found in the
         * header.
         */
        auto format_op = [](int val) -> std::string {
                switch (val & FUTEX_CMD_MASK) {
                        CASE_ENUM_TO_STR(FUTEX_CMP_REQUEUE);
                        CASE_ENUM_TO_STR(FUTEX_CMP_REQUEUE_PI);
                        CASE_ENUM_TO_STR(FUTEX_FD);
                        CASE_ENUM_TO_STR(FUTEX_LOCK_PI);
                        CASE_ENUM_TO_STR(FUTEX_LOCK_PI2);
                        CASE_ENUM_TO_STR(FUTEX_REQUEUE);
                        CASE_ENUM_TO_STR(FUTEX_TRYLOCK_PI);
                        CASE_ENUM_TO_STR(FUTEX_UNLOCK_PI);
                        CASE_ENUM_TO_STR(FUTEX_WAIT);
                        CASE_ENUM_TO_STR(FUTEX_WAIT_BITSET);
                        CASE_ENUM_TO_STR(FUTEX_WAIT_REQUEUE_PI);
                        CASE_ENUM_TO_STR(FUTEX_WAKE);
                        CASE_ENUM_TO_STR(FUTEX_WAKE_BITSET);
                        CASE_ENUM_TO_STR(FUTEX_WAKE_OP);
                        default: return cosmos::sprintf("unknown (%d)", val);
                }
        };
 
        const auto val = valueAs<int>();
        BITFLAGS_FORMAT_START_COMBINED(m_flags, val);
 
        BITFLAGS_STREAM() << format_op(val);
 
        if (!m_flags.none()) {
                BITFLAGS_STREAM() << '|';
                BITFLAGS_ADD(FUTEX_PRIVATE_FLAG);
                BITFLAGS_ADD(FUTEX_CLOCK_REALTIME);
        }
 
        return BITFLAGS_STR();
}

Member Data Documentation

◆ m_cmd

Command clues::item::FutexOperation::m_cmd = Command{0}

protected

Definition at line 66 of file futex.hxx.

66{0};

◆ m_flags

Flags clues::item::FutexOperation::m_flags