HAL.

---

Detailed Description

Generic Adeos-based hardware abstraction layer.

Files
file	hal.c
	Adeos-based Real-Time Abstraction Layer for PowerPC.
file	hal.c
	Adeos-based Real-Time Abstraction Layer for the Blackfin architecture.
file	nmi.c
	NMI watchdog support.
file	hal.c
	Generic Real-Time HAL.
file	nmi.c
	Adeos-based Real-Time Abstraction Layer for x86.
file	hal.c
	Adeos-based Real-Time Abstraction Layer for x86.
file	nmi.c
	NMI watchdog for x86, from linux/arch/i386/kernel/nmi.c.
file	smi.c
	SMI workaround for x86.
file	hal.c
	Adeos-based Real-Time Abstraction Layer for ia64.
file	hal.c
	Adeos-based Real-Time Abstraction Layer for PowerPC.
Functions
int	rthal_timer_request (void(*handler)(void), unsigned long nstick)
	Grab the hardware timer.
void	rthal_timer_release (void)
	Release the hardware timer.
int	rthal_irq_host_release (unsigned irq, void *dev_id)
	Uninstall a shared Linux interrupt handler.
int	rthal_irq_enable (unsigned irq)
	Enable an interrupt source.
int	rthal_irq_disable (unsigned irq)
	Disable an interrupt source.
int	rthal_irq_request (unsigned irq, rthal_irq_handler_t handler, rthal_irq_ackfn_t ackfn, void *cookie)
	Install a real-time interrupt handler.
int	rthal_irq_release (unsigned irq)
	Uninstall a real-time interrupt handler.
int	rthal_irq_host_pend (unsigned irq)
	Propagate an IRQ event to Linux.
int	rthal_irq_affinity (unsigned irq, cpumask_t cpumask, cpumask_t *oldmask)
	Set/Get processor affinity for external interrupt.
rthal_trap_handler_t	rthal_trap_catch (rthal_trap_handler_t handler)
	Installs a fault handler.
int	rthal_apc_alloc (const char *name, void(*handler)(void *cookie), void *cookie)
	Allocate an APC slot.
int	rthal_apc_free (int apc)
	Releases an APC slot.
int	rthal_apc_schedule (int apc)
	Schedule an APC invocation.

---

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, including over PREEMPT_RT kernels exhibiting a threaded IRQ model. 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. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if apc is invalid. Environments: This service can be called from: Any domain context.

int rthal_apc_schedule (  int  apc  )

Schedule an APC invocation. This service marks the APC as pending for the Linux domain, so that its handler will be called as soon as possible, when the Linux domain gets back in control. When posted from the Linux domain, the APC handler is fired as soon as the interrupt mask is explicitely cleared by some kernel code. When posted from the Xenomai domain, the APC handler is fired as soon as the Linux domain is resumed, i.e. after Xenomai has completed all its pending duties. Parameters: apc  The APC id. to schedule. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if apc is invalid. Environments: This service can be called from: Any domain context, albeit the usual calling place is from the Xenomai domain.

int rthal_irq_affinity (  unsigned  irq, cpumask_t  cpumask, cpumask_t *  oldmask )

Set/Get processor affinity for external interrupt. On SMP systems, this service ensures that the given interrupt is preferably dispatched to the specified set of processors. The previous affinity mask is returned by this service. Parameters: irq  The interrupt source whose processor affinity is affected by the operation. Only external interrupts can have their affinity changed/queried, thus virtual interrupt numbers allocated by rthal_alloc_virq() are invalid values for this parameter. cpumask  A list of CPU identifiers passed as a bitmask representing the new affinity for this interrupt. A zero value cause this service to return the current affinity mask without changing it. oldmask  If non-NULL, a pointer to a memory area which will bve overwritten by the previous affinity mask used for this interrupt source, or a zeroed mask if an error occurred. This service always returns a zeroed mask on uniprocessor systems. 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_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_pend (  unsigned  irq  )

Propagate an IRQ event to Linux. Causes the given IRQ to be propagated down to the Adeos pipeline to the Linux kernel. This operation is typically used after the given IRQ has been processed into the Xenomai domain by a real-time interrupt handler (see rthal_irq_request()), in case such interrupt must also be handled by the Linux kernel. Parameters: irq  The interrupt source to detach the shared handler from. This value is architecture-dependent. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if irq is invalid. Environments: This service can be called from: Xenomai 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_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.

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. ackfn should return a non-zero value to indicate that the interrupt has been properly acknowledged. 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.

void rthal_timer_release (  void   )

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. Environments: This service can be called from: Linux domain context.

int rthal_timer_request (  void(*)(void)  handler, unsigned long  nstick )

Grab the hardware timer. rthal_timer_request() grabs and tunes the hardware timer so that a user-defined routine is called according to a given frequency. On architectures that provide a oneshot-programmable time source, the hardware timer can operate either in aperiodic or periodic mode. Using the aperiodic mode still allows to run periodic timings over it: the underlying hardware simply needs to be reprogrammed after each tick using the appropriate interval value The time interval that elapses between two consecutive invocations of the handler is called a tick. The user-supplied handler will always be invoked on behalf of the Xenomai domain for each incoming tick. Parameters: handler  The address of the tick handler which will process each incoming tick. nstick  The timer period in nanoseconds. If this parameter is zero, the underlying hardware timer is set to operate in oneshot-programming mode. In this mode, timing accuracy is higher - since it is not rounded to a constant time slice - at the expense of a lesser efficicency due to the timer chip programming duties. On the other hand, the shorter the period, the higher the overhead induced by the periodic mode, since the handler will end up consuming a lot of CPU power to process useless ticks. Returns: 0 is returned on success. 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. Environments: This service can be called from: Linux domain context.

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.

---