Registry to receive messages of a specified protocol type by GNRC. More...

Detailed Description

Registry to receive messages of a specified protocol type by GNRC.

Files
file	netreg.h
	Definitions to register network protocol PIDs to use with GNRC communication interface.

Data Structures
struct	gnrc_netreg_entry_cbd_t
	Callback + Context descriptor. More...

struct	gnrc_netreg_entry
	Entry to the Network protocol registry. More...

Macros
#define	GNRC_NETREG_DEMUX_CTX_ALL (0xffff0000)
	Demux context value to get all packets of a certain type.

Typedefs
typedef void(*	gnrc_netreg_entry_cb_t) (uint16_t cmd, gnrc_pktsnip_t pkt, void ctx)
	Packet handler callback for netreg entries with callback.

typedef struct gnrc_netreg_entry	gnrc_netreg_entry_t
	Entry to the Network protocol registry.

Enumerations
enum	gnrc_netreg_type_t { GNRC_NETREG_TYPE_DEFAULT = 0 , GNRC_NETREG_TYPE_MBOX , GNRC_NETREG_TYPE_CB }
	The type of the netreg entry. More...

Functions
void	gnrc_netreg_init (void)
	Initializes module.

int	gnrc_netreg_register (gnrc_nettype_t type, gnrc_netreg_entry_t *entry)
	Registers a thread to the registry.

void	gnrc_netreg_unregister (gnrc_nettype_t type, gnrc_netreg_entry_t *entry)
	Removes a thread from the registry.

gnrc_netreg_entry_t *	gnrc_netreg_lookup (gnrc_nettype_t type, uint32_t demux_ctx)
	Searches for entries with given parameters in the registry and returns the first found.

int	gnrc_netreg_num (gnrc_nettype_t type, uint32_t demux_ctx)
	Returns number of entries with the same gnrc_netreg_entry_t::type and gnrc_netreg_entry_t::demux_ctx.

gnrc_netreg_entry_t *	gnrc_netreg_getnext (gnrc_netreg_entry_t *entry)
	Returns the next entry after `entry` with the same gnrc_netreg_entry_t::type and gnrc_netreg_entry_t::demux_ctx as the given entry.

int	gnrc_netreg_calc_csum (gnrc_pktsnip_t hdr, gnrc_pktsnip_t pseudo_hdr)
	Calculates the checksum for a header.

void	gnrc_netreg_acquire_shared (void)
	The global locking of netregs.

void	gnrc_netreg_release_shared (void)
	Release a shared lock on the GNRC netreg.

Dynamic entry initialization functions

static void	gnrc_netreg_entry_init_pid (gnrc_netreg_entry_t *entry, uint32_t demux_ctx, kernel_pid_t pid)
	Initializes a netreg entry dynamically with PID.

static void	gnrc_netreg_entry_init_mbox (gnrc_netreg_entry_t entry, uint32_t demux_ctx, mbox_t mbox)
	Initializes a netreg entry dynamically with mbox.

static void	gnrc_netreg_entry_init_cb (gnrc_netreg_entry_t entry, uint32_t demux_ctx, gnrc_netreg_entry_cbd_t cbd)
	Initializes a netreg entry dynamically with callback.

Static entry initialization macros

#define	GNRC_NETREG_ENTRY_INIT_PID(demux_ctx, pid) { NULL, demux_ctx, { pid } }
	Initializes a netreg entry statically with PID.

#define	GNRC_NETREG_ENTRY_INIT_MBOX(demux_ctx, _mbox)
	Initializes a netreg entry statically with mbox.

#define	GNRC_NETREG_ENTRY_INIT_CB(demux_ctx, _cbd)
	Initializes a netreg entry statically with callback.

Macro Definition Documentation

◆ GNRC_NETREG_DEMUX_CTX_ALL

#define GNRC_NETREG_DEMUX_CTX_ALL (0xffff0000)

Demux context value to get all packets of a certain type.

See also: gnrc_netreg_entry_t::demux_ctx

Definition at line 80 of file netreg.h.

◆ GNRC_NETREG_ENTRY_INIT_CB

#define GNRC_NETREG_ENTRY_INIT_CB	(	demux_ctx,
		_cbd
	)

Value:

                                                      { NULL, demux_ctx, \
                                                      GNRC_NETREG_TYPE_CB, \
                                                      { .cbd = _cbd } }

Initializes a netreg entry statically with callback.

Parameters

[in]	demux_ctx	The demux context for the netreg entry
[in]	_cbd	Target callback for the registry entry

Note: Only available with Callback extension.

Returns: An initialized netreg entry

Definition at line 133 of file netreg.h.

◆ GNRC_NETREG_ENTRY_INIT_MBOX

#define GNRC_NETREG_ENTRY_INIT_MBOX	(	demux_ctx,
		_mbox
	)

Value:

                                                       { NULL, demux_ctx, \
                                                       GNRC_NETREG_TYPE_MBOX, \
                                                       { .mbox = _mbox } }

Initializes a netreg entry statically with mbox.

Parameters

[in]	demux_ctx	The demux context for the netreg entry
[in]	_mbox	Target mailbox for the registry entry

Note: Only available with Mailbox IPC extension.

Returns: An initialized netreg entry

Definition at line 116 of file netreg.h.

◆ GNRC_NETREG_ENTRY_INIT_PID

#define GNRC_NETREG_ENTRY_INIT_PID	(	demux_ctx,
		pid
	)	{ NULL, demux_ctx, { pid } }

Initializes a netreg entry statically with PID.

Parameters

[in]	demux_ctx	The demux context for the netreg entry
[in]	pid	The PID of the registering thread

Returns: An initialized netreg entry

Definition at line 101 of file netreg.h.

Typedef Documentation

◆ gnrc_netreg_entry_cb_t

typedef void(* gnrc_netreg_entry_cb_t) (uint16_t cmd, gnrc_pktsnip_t *pkt, void *ctx)

Packet handler callback for netreg entries with callback.

Precondition: cmd ∈ { GNRC_NETAPI_MSG_TYPE_RCV, GNRC_NETAPI_MSG_TYPE_SND }

Note: Only available with Callback extension.

Parameters

[in]	cmd	GNRC communication interface command type. Must be either GNRC_NETAPI_MSG_TYPE_SND or GNRC_NETAPI_MSG_TYPE_RCV
[in]	pkt	The packet to handle.
[in]	ctx	Application context.

Definition at line 151 of file netreg.h.

Enumeration Type Documentation

◆ gnrc_netreg_type_t

enum gnrc_netreg_type_t

The type of the netreg entry.

    Different types are available dependent on the used modules.

Enumerator

GNRC_NETREG_TYPE_DEFAULT

Use default IPC for netapi operations.

Note: Implicitly chosen without gnrc_netapi_mbox and gnrc_netapi_callbacks modules.

GNRC_NETREG_TYPE_MBOX

Use centralized IPC for netapi operations.

Note: Only available with gnrc_netapi_mbox module.

GNRC_NETREG_TYPE_CB

Use function callbacks for netapi operations.

Note: Only available with gnrc_netapi_callbacks module.

Definition at line 45 of file netreg.h.

Function Documentation

◆ gnrc_netreg_acquire_shared()

void gnrc_netreg_acquire_shared ( void )

The global locking of netregs.

A shared lock must be held across calls to gnrc_netreg_lookup, and references obtained through that may only be used for the duration for which the lock is held.

The shared lock is counting (i.e. multiple sections of code can acquire it concurrently), and may be held across blocking operations, as long as they don't involve the exclusive lock (e.g. by blocking on a socket creation). It's generally good practice to release them as soon as possible.

There is an exclusive counterpart to the lock, which is internal to netreg (and used through functions such as gnrc_netreg_register and gnrc_netreg_unregister). The current implementation prioritizes shared locks. This means that shared locks are generally acquired fast (they only block if an exclusive operation has already started), but constant access through shared locks might starve registration and deregistration.

Acquire a shared lock on the GNRC netreg

This needs to be held around all calls to gnrc_netreg_lookup, and for as long as any of its results are used. After that, call gnrc_netreg_release_shared.

◆ gnrc_netreg_calc_csum()

int gnrc_netreg_calc_csum	(	gnrc_pktsnip_t *	hdr,
		gnrc_pktsnip_t *	pseudo_hdr
	)

Calculates the checksum for a header.

Parameters

[in]	hdr	The header the checksum should be calculated for.
[in]	pseudo_hdr	The header the pseudo header shall be generated from. NULL if none is needed.

Returns: 0, on success.; -EINVAL, if pseudo_hdr is NULL but a pseudo header was required.; -ENOENT, if Network protocol registry does not know how to calculate checksum for gnrc_pktsnip_t::type of hdr.

◆ gnrc_netreg_entry_init_cb()

static void gnrc_netreg_entry_init_cb	(	gnrc_netreg_entry_t *	entry,
		uint32_t	demux_ctx,
		gnrc_netreg_entry_cbd_t *	cbd
	)

inlinestatic

Initializes a netreg entry dynamically with callback.

Parameters

[out]	entry	A netreg entry
[in]	demux_ctx	The demux context for the netreg entry
[in]	cbd	Target callback for the registry entry

Note: Only available with Callback extension.

Definition at line 317 of file netreg.h.

◆ gnrc_netreg_entry_init_mbox()

static void gnrc_netreg_entry_init_mbox	(	gnrc_netreg_entry_t *	entry,
		uint32_t	demux_ctx,
		mbox_t *	mbox
	)

inlinestatic

Initializes a netreg entry dynamically with mbox.

Parameters

[out]	entry	A netreg entry
[in]	demux_ctx	The demux context for the netreg entry
[in]	mbox	Target mailbox for the registry entry

Note: Only available with Mailbox IPC extension.

Definition at line 295 of file netreg.h.

◆ gnrc_netreg_entry_init_pid()

static void gnrc_netreg_entry_init_pid	(	gnrc_netreg_entry_t *	entry,
		uint32_t	demux_ctx,
		kernel_pid_t	pid
	)

inlinestatic

Initializes a netreg entry dynamically with PID.

Parameters

[out]	entry	A netreg entry
[in]	demux_ctx	The demux context for the netreg entry
[in]	pid	The PID of the registering thread

Definition at line 272 of file netreg.h.

◆ gnrc_netreg_getnext()

gnrc_netreg_entry_t * gnrc_netreg_getnext ( gnrc_netreg_entry_t * entry )

Returns the next entry after entry with the same gnrc_netreg_entry_t::type and gnrc_netreg_entry_t::demux_ctx as the given entry.

The requirement on holding the global lock through gnrc_netreg_acquire_shared from gnrc_netreg_lookup extends to any results of this function: It may only be released when none of the pointers are used any more.

Parameters

[in] entry A registry entry retrieved by gnrc_netreg_lookup() or gnrc_netreg_getnext(). Must not be NULL.

Returns: The next entry after entry fitting the given parameters on success; NULL if no entry new entry can be found.

◆ gnrc_netreg_lookup()

gnrc_netreg_entry_t * gnrc_netreg_lookup	(	gnrc_nettype_t	type,
		uint32_t	demux_ctx
	)

Searches for entries with given parameters in the registry and returns the first found.

Precondition: The caller must hold the lock of gnrc_netreg_acquire_shared from before calling this function, and must stop using any obtained pointers before releasing the lock through gnrc_netreg_release_shared.

Parameters

[in]	type	Type of the protocol.
[in]	demux_ctx	The demultiplexing context for the registered thread. See gnrc_netreg_entry_t::demux_ctx.

Returns: The first entry fitting the given parameters on success; NULL if no entry can be found.

◆ gnrc_netreg_num()

int gnrc_netreg_num	(	gnrc_nettype_t	type,
		uint32_t	demux_ctx
	)

Returns number of entries with the same gnrc_netreg_entry_t::type and gnrc_netreg_entry_t::demux_ctx.

Parameters

[in]	type	Type of the protocol.
[in]	demux_ctx	The demultiplexing context for the registered thread. See gnrc_netreg_entry_t::demux_ctx.

Returns: Number of entries with the same gnrc_netreg_entry_t::type and gnrc_netreg_entry_t::demux_ctx as the given parameters.

Note that this returns a snapshot value, which may change at any time after that call. This is fine for most applications, as they just shortcut a code path if the number is zero. Callers that need that number to stay constant can acquire a shared lock through gnrc_netreg_acquire_shared, and rely on the number staying constant until that lock is released through gnrc_netreg_release_shared.

◆ gnrc_netreg_register()

int gnrc_netreg_register	(	gnrc_nettype_t	type,
		gnrc_netreg_entry_t *	entry
	)

Registers a thread to the registry.

The semantics are: Thread gnrc_netreg_entry_t::pid is interested in packets of protocol type with context gnrc_netreg_entry_t::demux_ctx.

Parameters

[in]	type	Type of the protocol. Must not be < GNRC_NETTYPE_UNDEF or >= GNRC_NETTYPE_NUMOF.
[in]	entry	An entry you want to add to the registry. This needs to be initialized before hand using the static or dynamic initialization helpers.

Warning: Call gnrc_netreg_unregister() before you leave the context you allocated entry in. Otherwise it might get overwritten.

Precondition: The calling thread must provide a message queue when using GNRC_NETREG_TYPE_DEFAULT for gnrc_netreg_entry_t::type of entry.

Returns: 0 on success; -EINVAL if type was < GNRC_NETTYPE_UNDEF or >= GNRC_NETTYPE_NUMOF

◆ gnrc_netreg_release_shared()

void gnrc_netreg_release_shared ( void )

Release a shared lock on the GNRC netreg.

Precondition: gnrc_netreg_acquire_shared was called

◆ gnrc_netreg_unregister()

void gnrc_netreg_unregister	(	gnrc_nettype_t	type,
		gnrc_netreg_entry_t *	entry
	)

Removes a thread from the registry.

Parameters

[in]	type	Type of the protocol.
[in]	entry	An entry you want to remove from the registry.

Detailed Description

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Dynamic entry initialization functions

Static entry initialization macros

Macro Definition Documentation

◆ GNRC_NETREG_DEMUX_CTX_ALL

◆ GNRC_NETREG_ENTRY_INIT_CB

◆ GNRC_NETREG_ENTRY_INIT_MBOX

◆ GNRC_NETREG_ENTRY_INIT_PID

Typedef Documentation

◆ gnrc_netreg_entry_cb_t

Enumeration Type Documentation

◆ gnrc_netreg_type_t

Function Documentation

◆ gnrc_netreg_acquire_shared()

◆ gnrc_netreg_calc_csum()

◆ gnrc_netreg_entry_init_cb()

◆ gnrc_netreg_entry_init_mbox()

◆ gnrc_netreg_entry_init_pid()

◆ gnrc_netreg_getnext()

◆ gnrc_netreg_lookup()

◆ gnrc_netreg_num()

◆ gnrc_netreg_register()

◆ gnrc_netreg_release_shared()

◆ gnrc_netreg_unregister()