Renesas ELC driver APIs

Renesas ELC driver public APIs. More...

Data Structures
struct	renesas_elc_dt_spec
	Container for Renesas ELC information specified in devicetree. More...

Macros
#define	RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_NAME(node_id, name)
	Get the device pointer from the "renesas-elcs" property by element name.
#define	RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_IDX(node_id, idx)
	Get the device pointer from the "renesas-elcs" property by index.
#define	RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_NAME_OR_NULL(node_id, name)
	Get the device pointer from the "renesas-elcs" property by element name, or return NULL if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_IDX_OR_NULL(node_id, idx)
	Get the device pointer from the "renesas-elcs" property by index, or return NULL if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_NAME(inst, name)
	Get the device pointer from the "renesas-elcs" property by element name for a DT_DRV_COMPAT instance.
#define	RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_IDX(inst, idx)
	Get the device pointer from the "renesas-elcs" property by index for a DT_DRV_COMPAT instance.
#define	RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_NAME_OR_NULL(inst, name)
	Get the device pointer from the "renesas-elcs" property by element name for a DT_DRV_COMPAT instance, or return NULL if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_IDX_OR_NULL(inst, idx)
	Get the device pointer from the "renesas-elcs" property by index for a DT_DRV_COMPAT instance, or return NULL if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME(node_id, name)
	Get the peripheral cell value from the "renesas-elcs" property by element name.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX(node_id, idx)
	Get the peripheral cell value from the "renesas-elcs" property by index.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME_OR(node_id, name, default_value)
	Get the peripheral cell value from the "renesas-elcs" property by element name, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX_OR(node_id, idx, default_value)
	Get the peripheral cell value from the "renesas-elcs" property by index, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_NAME(inst, name)
	Get the peripheral cell value by element name for a DT_DRV_COMPAT instance.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_IDX(inst, idx)
	Get the peripheral cell value by index for a DT_DRV_COMPAT instance.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_NAME_OR(inst, name, default_value)
	Get the peripheral cell value by element name for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_IDX_OR(inst, idx, default_value)
	Get the peripheral cell value by index for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME(node_id, name)
	Get the event cell value from the "renesas-elcs" property by element name.
#define	RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX(node_id, idx)
	Get the event cell value from the "renesas-elcs" property by index.
#define	RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME_OR(node_id, name, default_value)
	Get the event cell value from the "renesas-elcs" property by element name, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX_OR(node_id, idx, default_value)
	Get the event cell value from the "renesas-elcs" property by index, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_NAME(inst, name)
	Get the event cell value by element name for a DT_DRV_COMPAT instance.
#define	RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_IDX(inst, idx)
	Get the event cell value by index for a DT_DRV_COMPAT instance.
#define	RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_NAME_OR(inst, name, default_value)
	Get the event cell value by element name for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.
#define	RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_IDX_OR(inst, idx, default_value)
	Get the event cell value by index for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.

Functions
int	renesas_elc_software_event_generate (const struct device *dev, uint32_t event)
	Generate a software event in the Event Link Controller.
int	renesas_elc_link_set (const struct device *dev, uint32_t peripheral, uint32_t event)
	Create a single event link.
int	renesas_elc_link_break (const struct device *dev, uint32_t peripheral)
	Break an event link.
int	renesas_elc_enable (const struct device *dev)
	Enable the operation of the Event Link Controller.
int	renesas_elc_disable (const struct device *dev)
	Disable the operation of the Event Link Controller.

Detailed Description

Renesas ELC driver public APIs.

Macro Definition Documentation

RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_IDX

#define RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_IDX	(		node_id,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET(DT_PHANDLE_BY_IDX(node_id, renesas_elcs, idx))

Get the device pointer from the "renesas-elcs" property by index.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into the renesas-elcs property.

Returns

Device pointer.

RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_IDX_OR_NULL

#define RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_IDX_OR_NULL	(		node_id,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET_OR_NULL(DT_PHANDLE_BY_IDX(node_id, renesas_elcs, idx))

Get the device pointer from the "renesas-elcs" property by index, or return NULL if the property does not exist.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into the renesas-elcs property.

Returns

Device pointer or NULL.

RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_NAME

#define RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_NAME	(		node_id,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET(DT_PHANDLE_BY_NAME(node_id, renesas_elcs, name))

Get the device pointer from the "renesas-elcs" property by element name.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Device pointer.

RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_NAME_OR_NULL

#define RENESAS_ELC_DT_SPEC_DEVICE_GET_BY_NAME_OR_NULL	(		node_id,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET_OR_NULL(DT_PHANDLE_BY_NAME(node_id, renesas_elcs, name))

Get the device pointer from the "renesas-elcs" property by element name, or return NULL if the property does not exist.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Device pointer or NULL.

RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_IDX

#define RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_IDX	(		inst,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET(DT_PHANDLE_BY_IDX(DT_DRV_INST(inst), renesas_elcs, idx))

Get the device pointer from the "renesas-elcs" property by index for a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number.
idx	Logical index into the renesas-elcs property.

Returns

Device pointer.

RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_IDX_OR_NULL

#define RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_IDX_OR_NULL	(		inst,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET_OR_NULL(DT_PHANDLE_BY_IDX(DT_DRV_INST(inst), renesas_elcs, idx))

Get the device pointer from the "renesas-elcs" property by index for a DT_DRV_COMPAT instance, or return NULL if the property does not exist.

Parameters

inst	DT_DRV_COMPAT instance number.
idx	Logical index into the renesas-elcs property.

Returns

Device pointer or NULL.

RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_NAME

#define RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_NAME	(		inst,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET(DT_PHANDLE_BY_NAME(DT_DRV_INST(inst), renesas_elcs, name))

Get the device pointer from the "renesas-elcs" property by element name for a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Device pointer.

RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_NAME_OR_NULL

#define RENESAS_ELC_DT_SPEC_DEVICE_INST_GET_BY_NAME_OR_NULL	(		inst,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DEVICE_DT_GET_OR_NULL(DT_PHANDLE_BY_NAME(DT_DRV_INST(inst), renesas_elcs, name))

Get the device pointer from the "renesas-elcs" property by element name for a DT_DRV_COMPAT instance, or return NULL if the property does not exist.

Parameters

inst	DT_DRV_COMPAT instance number.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Device pointer or NULL.

RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX

#define RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX	(		node_id,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DT_PHA_BY_IDX(node_id, renesas_elcs, idx, event)

Get the event cell value from the "renesas-elcs" property by index.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into the renesas-elcs property.

Returns

Event cell value.

RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX_OR

#define RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX_OR	(		node_id,
			idx,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, renesas_elcs),                                       \
                (RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX(node_id, idx)),                              \
                (default_value))

Get the event cell value from the "renesas-elcs" property by index, or return a default value if the property does not exist.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into the renesas-elcs property.
default_value	Value to return if the property is not present.

Returns

Event cell value or default_value.

RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME

#define RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME	(		node_id,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DT_PHA_BY_NAME(node_id, renesas_elcs, name, event)

Get the event cell value from the "renesas-elcs" property by element name.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Event cell value.

RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME_OR

#define RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME_OR	(		node_id,
			name,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, renesas_elcs),                                       \
                (RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME(node_id, name)),                            \
                (default_value))

Get the event cell value from the "renesas-elcs" property by element name, or return a default value if the property does not exist.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.
default_value	Value to return if the property is not present.

Returns

Event cell value or default_value.

RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_IDX

#define RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_IDX	(		inst,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX(DT_DRV_INST(inst), idx)

Get the event cell value by index for a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number.
idx	Logical index into the renesas-elcs property.

Returns

Event cell value.

RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_IDX_OR

#define RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_IDX_OR	(		inst,
			idx,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_EVENT_GET_BY_IDX_OR(DT_DRV_INST(inst), idx, default_value)

Get the event cell value by index for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.

Parameters

inst	DT_DRV_COMPAT instance number.
idx	Logical index into the renesas-elcs property.
default_value	Value to return if the property is not present.

Returns

Event cell value or default_value.

RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_NAME

#define RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_NAME	(		inst,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME(DT_DRV_INST(inst), name)

Get the event cell value by element name for a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Event cell value.

RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_NAME_OR

#define RENESAS_ELC_DT_SPEC_EVENT_INST_GET_BY_NAME_OR	(		inst,
			name,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_EVENT_GET_BY_NAME_OR(DT_DRV_INST(inst), name, default_value)

Get the event cell value by element name for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.

Parameters

inst	DT_DRV_COMPAT instance number.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.
default_value	Value to return if the property is not present.

Returns

Event cell value or default_value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX	(		node_id,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DT_PHA_BY_IDX(node_id, renesas_elcs, idx, peripheral)

Get the peripheral cell value from the "renesas-elcs" property by index.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into the renesas-elcs property.

Returns

Peripheral cell value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX_OR

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX_OR	(		node_id,
			idx,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, renesas_elcs),                                       \
                (RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX(node_id, idx)),                         \
                (default_value))

Get the peripheral cell value from the "renesas-elcs" property by index, or return a default value if the property does not exist.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into the renesas-elcs property.
default_value	Value to return if the property is not present.

Returns

Peripheral cell value or default_value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME	(		node_id,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        DT_PHA_BY_NAME(node_id, renesas_elcs, name, peripheral)

Get the peripheral cell value from the "renesas-elcs" property by element name.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Peripheral cell value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME_OR

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME_OR	(		node_id,
			name,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, renesas_elcs),                                       \
                (RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME(node_id, name)),                       \
                (default_value))

Get the peripheral cell value from the "renesas-elcs" property by element name, or return a default value if the property does not exist.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.
default_value	Value to return if the property is not present.

Returns

Peripheral cell value or default_value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_IDX

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_IDX	(		inst,
			idx )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX(DT_DRV_INST(inst), idx)

Get the peripheral cell value by index for a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number.
idx	Logical index into the renesas-elcs property.

Returns

Peripheral cell value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_IDX_OR

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_IDX_OR	(		inst,
			idx,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_IDX_OR(DT_DRV_INST(inst), idx, default_value)

Get the peripheral cell value by index for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.

Parameters

inst	DT_DRV_COMPAT instance number.
idx	Logical index into the renesas-elcs property.
default_value	Value to return if the property is not present.

Returns

Peripheral cell value or default_value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_NAME

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_NAME	(		inst,
			name )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME(DT_DRV_INST(inst), name)

Get the peripheral cell value by element name for a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.

Returns

Peripheral cell value.

RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_NAME_OR

#define RENESAS_ELC_DT_SPEC_PERIPHERAL_INST_GET_BY_NAME_OR	(		inst,
			name,
			default_value )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Value:

        RENESAS_ELC_DT_SPEC_PERIPHERAL_GET_BY_NAME_OR(DT_DRV_INST(inst), name, default_value)

Get the peripheral cell value by element name for a DT_DRV_COMPAT instance, or return a default value if the property does not exist.

Parameters

inst	DT_DRV_COMPAT instance number.
name	Lowercase-and-underscores name as specified in the renesas-elcs-names property.
default_value	Value to return if the property is not present.

Returns

Peripheral cell value or default_value.

Function Documentation

renesas_elc_disable()

int renesas_elc_disable

(

const struct device *

dev

)

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Disable the operation of the Event Link Controller.

This function disables the ELC, stopping event processing.

Parameters

dev	Event Link Controller device.

Returns

0 if successful.

A negative errno code on failure.

renesas_elc_enable()

int renesas_elc_enable

(

const struct device *

dev

)

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Enable the operation of the Event Link Controller.

This function enables the ELC so that it can process events.

Parameters

dev	Event Link Controller device.

Returns

0 if successful.

A negative errno code on failure.

renesas_elc_link_break()

int renesas_elc_link_break	(	const struct device *	dev,
		uint32_t	peripheral )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Break an event link.

This function breaks an existing event link for the given peripheral.

Parameters

dev	Event Link Controller device.
peripheral	Peripheral ID whose link is to be broken.

Returns

0 if successful.

A negative errno code on failure.

renesas_elc_link_set()

int renesas_elc_link_set	(	const struct device *	dev,
		uint32_t	peripheral,
		uint32_t	event )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Create a single event link.

This function configures an event link by associating a peripheral with a specific event signal.

Parameters

dev	Event Link Controller device.
peripheral	Peripheral ID to be linked to the event signal.
event	Event signal ID to be associated with the peripheral.

Returns

0 if successful.

A negative errno code on failure.

renesas_elc_software_event_generate()

int renesas_elc_software_event_generate	(	const struct device *	dev,
		uint32_t	event )

#include <zephyr/drivers/misc/interconn/renesas_elc/renesas_elc.h>

Generate a software event in the Event Link Controller.

This function requests the Renesas ELC to generate a software event identified by event.

Parameters

dev	The Event Link Controller device.
event	Software event ID to generate.

Returns

0 if successful.

A negative errno code on failure.