iPXE
Data Structures | Defines | Functions | Variables
interface.h File Reference

Object interfaces. More...

#include <stddef.h>
#include <stdarg.h>
#include <ipxe/refcnt.h>

Go to the source code of this file.

Data Structures

struct  interface_operation
 An object interface operation. More...
struct  interface_descriptor
 An object interface descriptor. More...
struct  interface
 An object interface. More...

Defines

#define INTF_OP(op_type, object_type, op_func)
 Define an object interface operation.
#define intf_offset(object_type, intf)
#define INTF_DESC(object_type, intf, operations)
 Define an object interface descriptor.
#define INTF_DESC_PASSTHRU(object_type, intf, operations, passthru)
 Define an object interface descriptor with pass-through interface.
#define INTF_DESC_PURE(operations)
 Define an object interface descriptor for a pure-interface object.
#define intf_close_TYPE(object_type)   typeof ( void ( object_type, int rc ) )
#define intf_poke_TYPE(object_type)   typeof ( void ( object_type ) )
#define INTF_INIT(descriptor)
 Initialise a static object interface.
#define intf_get_dest_op_no_passthru(intf, type, dest)
 Get object interface destination and operation method (without pass-through)
#define intf_get_dest_op(intf, type, dest)
 Get object interface destination and operation method.
#define INTF_COL(intf)   intf_object ( intf )
 Find debugging colourisation for an object interface.
#define INTF_FMT   "%p+%zx"
 printf() format string for INTF_DBG()
#define INTF_DBG(intf)   intf_object ( intf ), (intf)->desc->offset
 printf() arguments for representing an object interface
#define INTF_INTF_FMT   INTF_FMT "->" INTF_FMT
 printf() format string for INTF_INTF_DBG()
#define INTF_INTF_DBG(intf, dest)   INTF_DBG ( intf ), INTF_DBG ( dest )
 printf() arguments for representing an object interface pair

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
void intf_plug (struct interface *intf, struct interface *dest)
 Plug an object interface into a new destination object interface.
void intf_plug_plug (struct interface *a, struct interface *b)
 Plug two object interfaces together.
void intf_unplug (struct interface *intf)
 Unplug an object interface.
void intf_nullify (struct interface *intf)
 Ignore all further operations on an object interface.
struct interfaceintf_get (struct interface *intf)
 Increment reference count on an object interface.
void intf_put (struct interface *intf)
 Decrement reference count on an object interface.
void * __attribute__ ((pure)) intf_object(struct interface *intf)
void * intf_get_dest_op_no_passthru_untyped (struct interface *intf, void *type, struct interface **dest)
 Get object interface destination and operation method (without pass-through)
void * intf_get_dest_op_untyped (struct interface *intf, void *type, struct interface **dest)
 Get object interface destination and operation method.
void intf_close (struct interface *intf, int rc)
 Close an object interface.
void intf_shutdown (struct interface *intf, int rc)
 Shut down an object interface.
void intfs_vshutdown (va_list intfs, int rc)
 Shut down multiple object interfaces.
void intfs_shutdown (int rc,...) __attribute__((sentinel))
 Shut down multiple object interfaces.
void intf_restart (struct interface *intf, int rc)
 Shut down and restart an object interface.
void intfs_vrestart (va_list intfs, int rc)
 Shut down and restart multiple object interfaces.
void intfs_restart (int rc,...) __attribute__((sentinel))
 Shut down and restart multiple object interfaces.
void intf_poke (struct interface *intf, void(type)(struct interface *intf))
 Poke an object interface.
static void intf_init (struct interface *intf, struct interface_descriptor *desc, struct refcnt *refcnt)
 Initialise an object interface.
static void intf_reinit (struct interface *intf)
 Reinitialise an object interface.

Variables

struct interface_descriptor null_intf_desc
 Null interface descriptor.
struct interface null_intf
 The null interface.

Detailed Description

Object interfaces.

Definition in file interface.h.


Define Documentation

#define INTF_OP (   op_type,
  object_type,
  op_func 
)
Value:
{                             \
                .type = op_type,                                              \
                .func = ( ( ( ( typeof ( op_func ) * ) NULL ) ==              \
                            ( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
                          ? op_func : op_func ),                              \
        }

Define an object interface operation.

Parameters:
op_typeOperation type
object_typeImplementing method's expected object type
op_funcImplementing method
Return values:
opObject interface operation

Definition at line 32 of file interface.h.

#define intf_offset (   object_type,
  intf 
)
Value:
( ( ( ( typeof ( ( ( object_type * ) NULL )->intf ) * ) NULL )        \
            == ( ( struct interface * ) NULL ) )                              \
          ? offsetof ( object_type, intf )                                    \
          : offsetof ( object_type, intf ) )

Definition at line 51 of file interface.h.

#define INTF_DESC (   object_type,
  intf,
  operations 
)
Value:
{                             \
                .offset = intf_offset ( object_type, intf ),                  \
                .op = operations,                                             \
                .num_op = ( sizeof ( operations ) /                           \
                            sizeof ( operations[0] ) ),                       \
                .passthru_offset = 0,                                         \
        }

Define an object interface descriptor.

Parameters:
object_typeContaining object data type
intfInterface name (i.e. field within object data type)
operationsObject interface operations array
Return values:
descObject interface descriptor

Definition at line 65 of file interface.h.

#define INTF_DESC_PASSTHRU (   object_type,
  intf,
  operations,
  passthru 
)
Value:
{             \
                .offset = offsetof ( object_type, intf ),                     \
                .op = operations,                                             \
                .num_op = ( sizeof ( operations ) /                           \
                            sizeof ( operations[0] ) ),                       \
                .passthru_offset = ( intf_offset ( object_type, passthru ) -  \
                                     intf_offset ( object_type, intf ) ),     \
        }

Define an object interface descriptor with pass-through interface.

Parameters:
object_typeContaining object data type
intfInterface name (i.e. field within object data type)
operationsObject interface operations array
passthruPass-through interface name
Return values:
descObject interface descriptor

Definition at line 82 of file interface.h.

#define INTF_DESC_PURE (   operations)
Value:
{                                             \
                .offset = 0,                                                  \
                .op = operations,                                             \
                .num_op = ( sizeof ( operations ) /                           \
                            sizeof ( operations[0] ) ),                       \
                .passthru_offset = 0,                                         \
        }

Define an object interface descriptor for a pure-interface object.

Parameters:
operationsObject interface operations array
Return values:
descObject interface descriptor

A pure-interface object is an object that consists solely of a single interface.

Definition at line 100 of file interface.h.

#define intf_close_TYPE (   object_type)    typeof ( void ( object_type, int rc ) )

Definition at line 148 of file interface.h.

Referenced by intf_close().

#define intf_poke_TYPE (   object_type)    typeof ( void ( object_type ) )

Definition at line 160 of file interface.h.

Referenced by intf_poke().

#define INTF_INIT (   descriptor)
Value:
{               \
                .dest = &null_intf,             \
                .refcnt = NULL,                 \
                .desc = &(descriptor),          \
                .original = &(descriptor),      \
        }

Initialise a static object interface.

Parameters:
descriptorObject interface descriptor

Definition at line 187 of file interface.h.

Referenced by ifpoller_wait(), and xfer_vredirect().

#define intf_get_dest_op_no_passthru (   intf,
  type,
  dest 
)
Value:
( ( type ## _TYPE ( void * ) * )                                \
          intf_get_dest_op_no_passthru_untyped ( intf, type, dest ) )

Get object interface destination and operation method (without pass-through)

Parameters:
intfObject interface
typeOperation type
Return values:
destDestination interface
funcImplementing method, or NULL

Definition at line 202 of file interface.h.

Referenced by xfer_vredirect().

#define intf_get_dest_op (   intf,
  type,
  dest 
)
Value:
( ( type ## _TYPE ( void * ) * )                                \
          intf_get_dest_op_untyped ( intf, type, dest ) )

Get object interface destination and operation method.

Parameters:
intfObject interface
typeOperation type
Return values:
destDestination interface
funcImplementing method, or NULL

Definition at line 214 of file interface.h.

Referenced by acpi_describe(), ata_command(), block_capacity(), block_read(), block_read_capacity(), block_write(), edd_describe(), identify_device(), intf_close(), job_progress(), peerdisc_stat(), resolv_done(), scsi_command(), scsi_response(), xfer_alloc_iob(), xfer_buffer(), xfer_deliver(), and xfer_window().

#define INTF_COL (   intf)    intf_object ( intf )

Find debugging colourisation for an object interface.

Parameters:
intfObject interface
Return values:
colDebugging colourisation

Use as the first argument to DBGC() or equivalent macro.

Definition at line 226 of file interface.h.

Referenced by intf_close(), intf_plug(), intf_restart(), intf_shutdown(), intf_unplug(), job_progress(), resolv_done(), xfer_alloc_iob(), xfer_deliver(), xfer_open_socket(), xfer_open_uri(), xfer_open_uri_string(), xfer_seek(), xfer_vopen(), and xfer_vredirect().

#define INTF_FMT   "%p+%zx"
#define INTF_DBG (   intf)    intf_object ( intf ), (intf)->desc->offset

printf() arguments for representing an object interface

Parameters:
intfObject interface
Return values:
argsprintf() argument list corresponding to INTF_FMT

Definition at line 237 of file interface.h.

Referenced by intf_plug(), intf_restart(), intf_shutdown(), xfer_open_socket(), xfer_open_uri(), xfer_open_uri_string(), xfer_seek(), and xfer_vopen().

#define INTF_INTF_FMT   INTF_FMT "->" INTF_FMT
#define INTF_INTF_DBG (   intf,
  dest 
)    INTF_DBG ( intf ), INTF_DBG ( dest )

printf() arguments for representing an object interface pair

Parameters:
intfObject interface
destDestination object interface
Return values:
argsprintf() argument list corresponding to INTF_INTF_FMT

Definition at line 249 of file interface.h.

Referenced by intf_close(), intf_plug(), intf_unplug(), job_progress(), resolv_done(), xfer_alloc_iob(), xfer_deliver(), and xfer_vredirect().


Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )
void intf_plug ( struct interface intf,
struct interface dest 
)

Plug an object interface into a new destination object interface.

Parameters:
intfObject interface
destNew destination object interface

The reference to the existing destination interface is dropped, a reference to the new destination interface is obtained, and the interface is updated to point to the new destination interface.

Definition at line 83 of file interface.c.

References DBGC, interface::dest, dest, INTF_COL, INTF_DBG, INTF_FMT, intf_get(), INTF_INTF_DBG, INTF_INTF_FMT, and intf_put().

Referenced by intf_plug_plug(), and xfer_vredirect().

                                                                  {
        DBGC ( INTF_COL ( intf ),
               "INTF " INTF_INTF_FMT " replug to " INTF_FMT "\n",
               INTF_INTF_DBG ( intf, intf->dest ), INTF_DBG ( dest ) );
        intf_get ( dest );
        intf_put ( intf->dest );
        intf->dest = dest;
}
void intf_plug_plug ( struct interface a,
struct interface b 
)
void intf_unplug ( struct interface intf)

Unplug an object interface.

Parameters:
intfObject interface

Definition at line 112 of file interface.c.

References DBGC, interface::dest, INTF_COL, INTF_INTF_DBG, INTF_INTF_FMT, intf_put(), and null_intf.

Referenced by intf_shutdown(), named_resolv_done(), and xfer_vredirect().

                                            {
        DBGC ( INTF_COL ( intf ), "INTF " INTF_INTF_FMT " unplug\n",
               INTF_INTF_DBG ( intf, intf->dest ) );
        intf_put ( intf->dest );
        intf->dest = &null_intf;
}
void intf_nullify ( struct interface intf)

Ignore all further operations on an object interface.

Parameters:
intfObject interface

Definition at line 124 of file interface.c.

References interface::desc, and null_intf_desc.

Referenced by intf_shutdown(), intfs_vshutdown(), named_resolv_done(), and peermux_close().

                                             {
        intf->desc = &null_intf_desc;
}
struct interface* intf_get ( struct interface intf) [read]

Increment reference count on an object interface.

Parameters:
intfObject interface
Return values:
intfObject interface

Definition at line 134 of file interface.c.

References ref_get, and interface::refcnt.

Referenced by intf_get_dest_op_no_passthru_untyped(), and intf_plug().

                                                       {
        ref_get ( intf->refcnt );
        return intf;
}
void intf_put ( struct interface intf)
void* __attribute__ ( (pure)  )
void* intf_get_dest_op_no_passthru_untyped ( struct interface intf,
void *  type,
struct interface **  dest 
)

Get object interface destination and operation method (without pass-through)

Parameters:
intfObject interface
typeOperation type
Return values:
destDestination interface
funcImplementing method, or NULL

Definition at line 182 of file interface.c.

References interface::dest, interface_operation::func, intf_get(), NULL, interface_descriptor::num_op, interface_descriptor::op, op, and interface_operation::type.

Referenced by intf_get_dest_op_untyped().

                                                                        {
        struct interface_descriptor *desc;
        struct interface_operation *op;
        unsigned int i;

        *dest = intf_get ( intf->dest );
        desc = (*dest)->desc;
        for ( i = desc->num_op, op = desc->op ; i ; i--, op++ ) {
                if ( op->type == type )
                        return op->func;
        }

        return NULL;
}
void* intf_get_dest_op_untyped ( struct interface intf,
void *  type,
struct interface **  dest 
)

Get object interface destination and operation method.

Parameters:
intfObject interface
typeOperation type
Return values:
destDestination interface
funcImplementing method, or NULL

Definition at line 207 of file interface.c.

References interface_operation::func, intf_get_dest_op_no_passthru_untyped(), intf_get_passthru(), intf_put(), and NULL.

Referenced by intf_poke().

                                                            {
        void *func;

        while ( 1 ) {

                /* Search for an implementing method provided by the
                 * current destination interface.
                 */
                func = intf_get_dest_op_no_passthru_untyped( intf, type, dest );
                if ( func )
                        return func;

                /* Pass through to the underlying interface, if applicable */
                if ( ! ( intf = intf_get_passthru ( *dest ) ) )
                        return NULL;
                intf_put ( *dest );
        }
}
void intf_close ( struct interface intf,
int  rc 
)

Close an object interface.

Parameters:
intfObject interface
rcReason for close

Note that this function merely informs the destination object that the interface is about to be closed; it doesn't actually disconnect the interface. In most cases, you probably want to use intf_shutdown() or intf_restart() instead.

Definition at line 244 of file interface.c.

References DBGC, dest, intf_close(), intf_close_TYPE, INTF_COL, intf_get_dest_op, INTF_INTF_DBG, INTF_INTF_FMT, intf_object(), intf_put(), intf_restart(), op, and strerror().

Referenced by ifconf_progress(), iflinkwait_progress(), intf_close(), intf_shutdown(), netdev_close(), sync_progress(), and xfer_vredirect().

                                                   {
        struct interface *dest;
        intf_close_TYPE ( void * ) *op =
                intf_get_dest_op ( intf, intf_close, &dest );
        void *object = intf_object ( dest );

        DBGC ( INTF_COL ( intf ), "INTF " INTF_INTF_FMT " close (%s)\n",
               INTF_INTF_DBG ( intf, dest ), strerror ( rc ) );

        if ( op ) {
                op ( object, rc );
        } else {
                /* Default is to restart the interface */
                intf_restart ( dest, rc );
        }

        intf_put ( dest );
}
void intf_shutdown ( struct interface intf,
int  rc 
)

Shut down an object interface.

Parameters:
intfObject interface
rcReason for close

Blocks further operations from being received via the interface, executes a close operation on the destination interface, and unplugs the interface.

Definition at line 273 of file interface.c.

References DBGC, interface::dest, intf_close(), INTF_COL, INTF_DBG, INTF_FMT, intf_nullify(), intf_unplug(), null_intf, and strerror().

Referenced by aoecmd_close(), aoedev_close(), aoedev_config_done(), atacmd_close(), atadev_close(), blktrans_close(), comboot_resolv_close(), dhcp_finished(), dhcpv6_finished(), dns_done(), downloader_finished(), efi_download_close(), efi_local_close(), fc_els_close(), fc_ns_query_close(), fc_peer_close(), fc_port_close(), fc_ulp_close(), fc_xchg_close(), fcoe_close(), fcpcmd_close(), fcpdev_close(), ftp_done(), http_conn_close(), http_transfer_complete(), hw_finished(), ib_cmrc_close(), ib_srp_close(), intf_restart(), intfs_vshutdown(), ipv6conf_done(), named_close(), nfs_deliver(), nfs_done(), nfs_pm_deliver(), nslookup_close(), ntp_close(), numeric_step(), peerblk_close(), peermux_close(), peermux_info_close(), ping_close(), pinger_close(), posix_file_finished(), pxe_tftp_close(), resmux_close(), slam_finished(), srpcmd_close(), srpdev_close(), tcp_close(), tftp_done(), tls_close(), udp_close(), validator_finished(), and xcm_destroy().

                                                      {
        struct interface tmp;

        DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " shutting down (%s)\n",
               INTF_DBG ( intf ), strerror ( rc ) );

        /* Block further operations */
        intf_nullify ( intf );

        /* Transfer destination to temporary interface */
        tmp.dest = intf->dest;
        intf->dest = &null_intf;

        /* Notify destination of close via temporary interface */
        intf_close ( &tmp, rc );

        /* Unplug temporary interface */
        intf_unplug ( &tmp );
}
void intfs_vshutdown ( va_list  intfs,
int  rc 
)

Shut down multiple object interfaces.

Parameters:
intfsObject interfaces
rcReason for close

Definition at line 299 of file interface.c.

References intf_nullify(), intf_shutdown(), va_arg, va_copy, and va_end.

Referenced by intfs_shutdown(), and intfs_vrestart().

                                               {
        struct interface *intf;
        va_list tmp;

        /* Nullify all interfaces to avoid potential loops */
        va_copy ( tmp, intfs );
        while ( ( intf = va_arg ( tmp, struct interface * ) ) )
                intf_nullify ( intf );
        va_end ( tmp );

        /* Shut down all interfaces */
        while ( ( intf = va_arg ( intfs, struct interface * ) ) )
                intf_shutdown ( intf, rc );
}
void intfs_shutdown ( int  rc,
  ... 
)

Shut down multiple object interfaces.

Parameters:
rcReason for close
...Object interfaces

Definition at line 320 of file interface.c.

References intfs_vshutdown(), va_end, and va_start.

Referenced by http_close(), iscsi_close(), scsicmd_close(), and scsidev_close().

                                    {
        va_list intfs;

        va_start ( intfs, rc );
        intfs_vshutdown ( intfs, rc );
        va_end ( intfs );
}
void intf_restart ( struct interface intf,
int  rc 
)

Shut down and restart an object interface.

Parameters:
intfObject interface
rcReason for close

Shuts down the interface, then unblocks operations that were blocked during shutdown.

Definition at line 337 of file interface.c.

References DBGC, INTF_COL, INTF_DBG, INTF_FMT, intf_reinit(), and intf_shutdown().

Referenced by apply_syslog_settings(), apply_syslogs_settings(), efi_pxe_tftp_close(), efi_pxe_udp_close(), fc_peer_plogi(), fc_peer_plogi_done(), fc_port_examine(), fc_port_flogi_done(), fc_port_login(), fc_port_ns_plogi_done(), fc_ulp_examine(), fc_ulp_prli_done(), fcoe_reset(), http_block_read(), http_block_read_capacity(), http_conn_close(), http_conn_xfer_close(), http_reopen(), http_transfer_complete(), intf_close(), iscsi_close_connection(), iscsi_command_close(), iscsi_scsi_done(), monojob_close(), netdev_config_close(), netdev_configure(), peerblk_raw_close(), peerblk_raw_open(), peerblk_raw_rx(), peerblk_reset(), peerblk_retrieval_close(), peerblk_retrieval_open(), peerblk_retrieval_rx(), peerdisc_socket_close(), peerdisc_socket_open(), peermux_block_close(), pxenv_udp_close(), pxenv_udp_open(), resmux_child_close(), sandev_command_close(), sanpath_close(), scsicmd_done(), scsidev_ready(), tftp_reopen(), tftp_reopen_mc(), tftp_timer_expired(), tls_validator_done(), validator_xfer_close(), xcm_close(), xcm_reopen(), and xfer_vreopen().

                                                     {

        /* Shut down the interface */
        intf_shutdown ( intf, rc );

        DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " restarting\n",
               INTF_DBG ( intf ) );

        /* Restore the interface descriptor.  Must be done after
         * shutdown (rather than inhibiting intf_shutdown() from
         * nullifying the descriptor) in order to avoid a potential
         * infinite loop as the intf_close() operations on each side
         * of the link call each other recursively.
         */
        intf_reinit ( intf );
}
void intfs_vrestart ( va_list  intfs,
int  rc 
)

Shut down and restart multiple object interfaces.

Parameters:
intfsObject interfaces
rcReason for close

Definition at line 360 of file interface.c.

References intf_reinit(), intfs_vshutdown(), va_arg, va_copy, and va_end.

Referenced by intfs_restart().

                                              {
        struct interface *intf;
        va_list tmp;

        /* Shut down all interfaces */
        va_copy ( tmp, intfs );
        intfs_vshutdown ( tmp, rc );
        va_end ( tmp );

        /* Reinitialise all interfaces */
        while ( ( intf = va_arg ( intfs, struct interface * ) ) )
                intf_reinit ( intf );
}
void intfs_restart ( int  rc,
  ... 
)

Shut down and restart multiple object interfaces.

Parameters:
rcReason for close
...Object interfaces

Definition at line 380 of file interface.c.

References intfs_vrestart(), va_end, and va_start.

Referenced by http_transfer_complete(), and sanpath_close().

                                   {
        va_list intfs;

        va_start ( intfs, rc );
        intfs_vrestart ( intfs, rc );
        va_end ( intfs );
}
void intf_poke ( struct interface intf,
void(type)(struct interface *intf)   
)

Poke an object interface.

Parameters:
intfObject interface
typeOperation type

This is a helper function to implement methods which take no parameters and return nothing.

Definition at line 397 of file interface.c.

References dest, intf_get_dest_op_untyped(), intf_object(), intf_poke_TYPE, intf_put(), op, and type.

Referenced by pool_recycle(), pool_reopen(), and xfer_window_changed().

                                                            {
        struct interface *dest;
        intf_poke_TYPE ( void * ) *op =
                intf_get_dest_op_untyped ( intf, type, &dest );
        void *object = intf_object ( dest );

        if ( op ) {
                op ( object );
        } else {
                /* Default is to do nothing */
        }

        intf_put ( dest );
}
static void intf_init ( struct interface intf,
struct interface_descriptor desc,
struct refcnt refcnt 
) [inline, static]
static void intf_reinit ( struct interface intf) [inline, static]

Reinitialise an object interface.

Parameters:
intfObject interface

Definition at line 256 of file interface.h.

References interface::desc, and interface::original.

Referenced by intf_restart(), and intfs_vrestart().

                                                          {

        /* Restore original interface descriptor */
        intf->desc = intf->original;
}

Variable Documentation

Null interface descriptor.

Definition at line 61 of file interface.c.

Referenced by intf_nullify(), numeric_resolv(), and xfer_vredirect().

The null interface.

Definition at line 65 of file interface.c.

Referenced by block_translate(), intf_init(), intf_shutdown(), and intf_unplug().