Generic Adeos-based hardware abstraction layer. More...

Files
file	hal.c
	Adeos-based Real-Time Abstraction Layer for ARM.

file	hal.c
	Adeos-based Real-Time Abstraction Layer for the Blackfin architecture.

file	hal.c
	Generic Real-Time HAL.

file	hal.c
	Adeos-based Real-Time Abstraction Layer for the NIOS2 architecture.

file	hal.c
	Adeos-based Real-Time Abstraction Layer for PowerPC.

file	hal.c
	Adeos-based Real-Time Abstraction Layer for the SuperH architecture.

file	hal-common.c
	Adeos-based Real-Time Abstraction Layer for x86.

file	hal_32.c
	Adeos-based Real-Time Abstraction Layer for x86.

file	hal_64.c
	Adeos-based Real-Time Abstraction Layer for x86_64.

file	smi.c
	SMI workaround for x86.

Functions
int	rthal_timer_request (void(tick_handler)(void), void(mode_emul)(enum clock_event_mode mode, struct clock_event_device cdev), int(tick_emul)(unsigned long delay, struct clock_event_device *cdev), int cpu)
	Grab the hardware timer. More...

void	rthal_timer_release (int cpu)
	Release the hardware timer. More...

int	rthal_irq_host_request (unsigned irq, rthal_irq_host_handler_t handler, char name, void dev_id)
	Install a shared Linux interrupt handler. More...

int	rthal_irq_host_release (unsigned irq, void *dev_id)
	Uninstall a shared Linux interrupt handler. More...

int	rthal_irq_enable (unsigned irq)
	Enable an interrupt source. More...

int	rthal_irq_disable (unsigned irq)
	Disable an interrupt source. More...

int	rthal_irq_request (unsigned irq, rthal_irq_handler_t handler, rthal_irq_ackfn_t ackfn, void *cookie)
	Install a real-time interrupt handler. More...

int	rthal_irq_release (unsigned irq)
	Uninstall a real-time interrupt handler. More...

rthal_trap_handler_t	rthal_trap_catch (rthal_trap_handler_t handler)
	Installs a fault handler. More...

int	rthal_apc_alloc (const char name, void(handler)(void cookie), void cookie)
	Allocate an APC slot. More...

void	rthal_apc_free (int apc)
	Releases an APC slot. More...

Detailed Description

Generic Adeos-based hardware abstraction layer.

x86_64-specific HAL services.

i386-specific HAL services.

SuperH-specific HAL services.

PowerPC-specific HAL services.

NIOS2-specific HAL services.

Blackfin-specific HAL services.

ARM-specific HAL services.

Function Documentation

int rthal_apc_alloc	(	const char *	name,
		void()(void cookie)	handler,
		void *	cookie
	)

Allocate an APC slot.

APC is the acronym for Asynchronous Procedure Call, a mean by which activities from the Xenomai domain can schedule deferred invocations of handlers to be run into the Linux domain, as soon as possible when the Linux kernel gets back in control. Up to BITS_PER_LONG APC slots can be active at any point in time. APC support is built upon Adeos's virtual interrupt support.

The HAL guarantees that any Linux kernel service which would be callable from a regular Linux interrupt handler is also available to APC handlers.

Parameters

name	is a symbolic name identifying the APC which will get reported through the /proc/xenomai/apc interface. Passing NULL to create an anonymous APC is allowed.
handler	The address of the fault handler to call upon exception condition. The handle will be passed the cookie value unmodified.
cookie	A user-defined opaque cookie the HAL will pass to the APC handler as its sole argument.

Returns: an valid APC id. is returned upon success, or a negative error code otherwise:

-EINVAL is returned if handler is invalid.
-EBUSY is returned if no more APC slots are available.

Environments:

This service can be called from:

Linux domain context.

int rthal_apc_free ( int apc )

Releases an APC slot.

This service deallocates an APC slot obtained by rthal_apc_alloc().

Parameters

apc	The APC id. to release, as returned by a successful call to the rthal_apc_alloc() service.

Environments:

This service can be called from:

Any domain context.

int rthal_irq_disable ( unsigned irq )

Disable an interrupt source.

Disables an interrupt source at PIC level. After this call has returned, no more IRQs from the given source will be allowed, until the latter is enabled again using rthal_irq_enable().

Parameters

irq	The interrupt source to disable. This value is architecture-dependent.

Returns: 0 is returned upon success. Otherwise:

-EINVAL is returned if irq is invalid.
Other error codes might be returned in case some internal error happens at the Adeos level. Such error might caused by conflicting Adeos requests made by third-party code.

Environments:

This service can be called from:

Any domain context.

int rthal_irq_enable ( unsigned irq )

Enable an interrupt source.

Enables an interrupt source at PIC level. Since Adeos masks and acknowledges the associated interrupt source upon IRQ receipt, this action is usually needed whenever the HAL handler does not propagate the IRQ event to the Linux domain, thus preventing the regular Linux interrupt handling code from re-enabling said source. After this call has returned, IRQs from the given source will be enabled again.

Parameters

irq	The interrupt source to enable. This value is architecture-dependent.

Returns: 0 is returned upon success. Otherwise:

-EINVAL is returned if irq is invalid.
Other error codes might be returned in case some internal error happens at the Adeos level. Such error might caused by conflicting Adeos requests made by third-party code.

Environments:

This service can be called from:

Any domain context.

int rthal_irq_host_release	(	unsigned	irq,
		void *	dev_id
	)

Uninstall a shared Linux interrupt handler.

Uninstalls a shared interrupt handler from the Linux domain for the given interrupt source. The handler is removed from the existing list of Linux handlers for this interrupt source.

Parameters

irq	The interrupt source to detach the shared handler from. This value is architecture-dependent.
dev_id	is a valid device id, identical in essence to the one requested by the free_irq() service provided by the Linux kernel. This value will be used to locate the handler to remove from the chain of existing Linux handlers for the given interrupt source. This parameter must match the device id. passed to rthal_irq_host_request() for the same handler instance.

Returns: 0 is returned upon success. Otherwise:

-EINVAL is returned if irq is invalid.

Environments:

This service can be called from:

Linux domain context.

int rthal_irq_host_request	(	unsigned	irq,
		rthal_irq_host_handler_t	handler,
		char *	name,
		void *	dev_id
	)

Install a shared Linux interrupt handler.

Installs a shared interrupt handler in the Linux domain for the given interrupt source. The handler is appended to the existing list of Linux handlers for this interrupt source.

Parameters

irq	The interrupt source to attach the shared handler to. This value is architecture-dependent.
handler	The address of a valid interrupt service routine. This handler will be called each time the corresponding IRQ is delivered, as part of the chain of existing regular Linux handlers for this interrupt source. The handler prototype is the same as the one required by the request_irq() service provided by the Linux kernel.
name	is a symbolic name identifying the handler which will get reported through the /proc/interrupts interface.
dev_id	is a unique device id, identical in essence to the one requested by the request_irq() service.

Returns: 0 is returned upon success. Otherwise:

-EINVAL is returned if irq is invalid or handler is NULL.

Environments:

This service can be called from:

Linux domain context.

int rthal_irq_release ( unsigned irq )

Uninstall a real-time interrupt handler.

Uninstalls an interrupt handler previously attached using the rthal_irq_request() service.

Parameters

irq	The hardware interrupt channel to uninstall a handler from. This value is architecture-dependent.

Returns: 0 is returned upon success. Otherwise:

-EINVAL is returned if irq is invalid.
Other error codes might be returned in case some internal error happens at the Adeos level. Such error might caused by conflicting Adeos requests made by third-party code.

Environments:

This service can be called from:

Any domain context.

Referenced by rthal_timer_release().

int rthal_irq_request	(	unsigned	irq,
		rthal_irq_handler_t	handler,
		rthal_irq_ackfn_t	ackfn,
		void *	cookie
	)

Install a real-time interrupt handler.

Installs an interrupt handler for the specified IRQ line by requesting the appropriate Adeos virtualization service. The handler is invoked by Adeos on behalf of the Xenomai domain context. Once installed, the HAL interrupt handler will be called prior to the regular Linux handler for the same interrupt source.

Parameters

irq	The hardware interrupt channel to install a handler on. This value is architecture-dependent.
handler	The address of a valid interrupt service routine. This handler will be called each time the corresponding IRQ is delivered, and will be passed the cookie value unmodified.
ackfn	The address of an optional interrupt acknowledge routine, aimed at replacing the one provided by Adeos. Only very specific situations actually require to override the default Adeos setting for this parameter, like having to acknowledge non-standard PIC hardware. If ackfn is NULL, the default Adeos routine will be used instead.
cookie	A user-defined opaque cookie the HAL will pass to the interrupt handler as its sole argument.

Returns: 0 is returned upon success. Otherwise:

-EBUSY is returned if an interrupt handler is already installed. rthal_irq_release() must be issued first before a handler is installed anew.
-EINVAL is returned if irq is invalid or handler is NULL.
Other error codes might be returned in case some internal error happens at the Adeos level. Such error might caused by conflicting Adeos requests made by third-party code.

Environments:

This service can be called from:

Any domain context.

Referenced by rthal_timer_request().

void rthal_timer_release ( int cpu )

Release the hardware timer.

Releases the hardware timer, thus reverting the effect of a previous call to rthal_timer_request(). In case the timer hardware is shared with Linux, a periodic setup suitable for the Linux kernel will be reset.

Parameters

cpu	The CPU number the timer was grabbed from.

Environments:

This service can be called from:

Linux domain context.

References rthal_irq_release().

int rthal_timer_request	(	void(*)(void)	tick_handler,
		void()(enum clock_event_mode mode, struct clock_event_device cdev)	mode_emul,
		int()(unsigned long delay, struct clock_event_device cdev)	tick_emul,
		int	cpu
	)

Grab the hardware timer.

rthal_timer_request() grabs and tunes the hardware timer in oneshot mode in order to clock the master time base.

A user-defined routine is registered as the clock tick handler. This handler will always be invoked on behalf of the Xenomai domain for each incoming tick.

Hooks for emulating oneshot mode for the tick device are accepted when CONFIG_GENERIC_CLOCKEVENTS is defined for the host kernel. Host tick emulation is a way to share the clockchip hardware between Linux and Xenomai, when the former provides support for oneshot timing (i.e. high resolution timers and no-HZ scheduler ticking).

Parameters

tick_handler	The address of the Xenomai tick handler which will process each incoming tick.
mode_emul	The optional address of a callback to be invoked upon mode switch of the host tick device, notified by the Linux kernel. This parameter is only considered whenever CONFIG_GENERIC_CLOCKEVENTS is defined.
tick_emul	The optional address of a callback to be invoked upon setup of the next shot date for the host tick device, notified by the Linux kernel. This parameter is only considered whenever CONFIG_GENERIC_CLOCKEVENTS is defined.
cpu	The CPU number to grab the timer from.

Returns: a positive value is returned on success, representing the duration of a Linux periodic tick expressed as a count of nanoseconds; zero should be returned when the Linux kernel does not undergo periodic timing on the given CPU (e.g. oneshot mode). Otherwise:

-EBUSY is returned if the hardware timer has already been grabbed. rthal_timer_request() must be issued before rthal_timer_request() is called again.
-ENODEV is returned if the hardware timer cannot be used. This situation may occur after the kernel disabled the timer due to invalid calibration results; in such a case, such hardware is unusable for any timing duties.

Environments:

This service can be called from:

Linux domain context.

References rthal_irq_request().

int rthal_trap_catch ( rthal_trap_handler_t handler )

Installs a fault handler.

The HAL attempts to invoke a fault handler whenever an uncontrolled exception or fault is caught at machine level. This service allows to install a user-defined handler for such events.

Parameters

handler The address of the fault handler to call upon exception condition. The handler is passed the address of the low-level information block describing the fault as passed by Adeos. Its layout is implementation-dependent.

Returns: The address of the fault handler previously installed.

Environments:

This service can be called from:

Any domain context.

Files

Functions

Detailed Description

Function Documentation