hardware.h File Reference

#include <stdbool.h>
#include "libnotify/notify.h"
#include "libstd/nexus.h"
#include "libos/semaphore.h"

Include dependency graph for hardware.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	hw_uart_metadata
struct	hw_timer_metadata
struct	hw_button_metadata
union	adc_trigger_metadata
struct	hw_adc_metadata
union	hw_metadata
struct	_isr_subscription
struct	hw_channel
struct	hw_driver

Macros
#define	HW_DRIVER_MAX_CHANNELS   8
#define	HW_DRIVER_MAX_SUBSCRIPTIONS   8
#define	hw_init(type, metadata)
#define	hw_init_and_subscribe(type, metadata, pseudo_isr)
#define	hw_subscribe(type, metadata, isr)   _hw_subscribe(type, metadata, isr, false)
#define	hw_subscribe_single_shot(type, metadata, isr)   _hw_subscribe(type, metadata, isr, true)

Typedefs
typedef uint8_t	hw_iterator
typedef struct _isr_subscription	_isr_subscription

Enumerations
enum	HW_TYPE { HW_UART, HW_TIMER, HW_BUTTON, HW_ADC }

Functions
uint32_t *	get_adc_samples ()
void	hw_init_daemon ()
void	hw_driver_init (HW_TYPE, hw_metadata)
void	hw_channel_init (HW_TYPE, hw_metadata)
void	_hw_subscribe (HW_TYPE, hw_metadata, void(*isr)(notification note), bool)
void	hw_unsubscribe (HW_TYPE, hw_metadata, void(*isr)(notification note))
hw_channel *	_hw_get_channel (HW_TYPE, hw_metadata)
hw_driver *	hw_driver_singleton (HW_TYPE)
void	hw_notify (HW_TYPE, hw_metadata, notification)
void	hw_notify_uart (hw_metadata uart_metadata)
void	hw_daemon (void)

Variables
static volatile semaphore_t	HW_SEM_UART0

Macro Definition Documentation

#define HW_DRIVER_MAX_CHANNELS   8

Typedef for an interrupt service routine, which can never accept arguments or return a value.

Maximum number of channels supported by each hardware peripheral

Definition at line 112 of file hardware.h.

#define HW_DRIVER_MAX_SUBSCRIPTIONS   8

Maximum number of subscribed threads each hardware driver is responsible for responding to

Definition at line 116 of file hardware.h.

Referenced by hw_channel_init().

#define hw_init	(		type,
			metadata
	)

Value:

hw_driver_init(type, metadata); \
    hw_channel_init(type, metadata)

Initialize hw driver and channel. Simply a convenience to reduce boilerplate.

Definition at line 143 of file hardware.h.

Referenced by adc_interrupt_init(), and main().

#define hw_init_and_subscribe	(		type,
			metadata,
			pseudo_isr
	)

Value:

hw_init(type, metadata);                              \
    hw_subscribe(type, metadata, pseudo_isr)

Initialize hw driver, channel and subscribe to notifications. Simply a convenience to reduce boilerplate.

Definition at line 149 of file hardware.h.

Referenced by main().

#define hw_subscribe	(		type,
			metadata,
			isr
	)		_hw_subscribe(type, metadata, isr, false)

Subscribe to a hardware interrupt. This is also called connecting a signal (the isr to be notified) to a slot (the hw-triggered driver isr).

Parameters

The	hardware type in question
Metadata	about the device
The	pseudo-isr to be notified by the hardware driver

Definition at line 178 of file hardware.h.

Referenced by main(), and shell_spawn().

#define hw_subscribe_single_shot	(		type,
			metadata,
			isr
	)		_hw_subscribe(type, metadata, isr, true)

Subscribe to a single-shot hardware interrupt. This is also called connecting a signal (the isr to be notified) to a slot (the hw-triggered driver isr). Note that a single-shot subscription differs from a normal subscription in that after the first notification, the subscription will unsubscribe itself.

Parameters

The	hardware type in question
Metadata	about the device
The	pseudo-isr to be notified by the hardware driver

Definition at line 190 of file hardware.h.

Referenced by button_debounce_start().

Typedef Documentation

typedef struct _isr_subscription _isr_subscription

Each peripheral channel needs to be able to notify subscribers about incoming hardware events

Definition at line 121 of file hardware.h.

typedef uint8_t hw_iterator

An iterator ensured to be of an optimized size according to the relevant #defines below it.

Definition at line 105 of file hardware.h.

Enumeration Type Documentation

enum HW_TYPE

Enum of possible hw types. This enum also serves as an offset into the uthash of the hw drivers' internal data structures.

Enumerator
HW_UART
HW_TIMER
HW_BUTTON
HW_ADC

Definition at line 46 of file hardware.h.

             {
    HW_UART,
    HW_TIMER,
    HW_BUTTON,
    HW_ADC
} HW_TYPE;

Function Documentation

hw_channel* _hw_get_channel ( HW_TYPE  , hw_metadata    )

inline

For internal use only. Take care of the conversion between a memory-mapped (raw) hw address and the index of said peripheral channel in the memory banks of libhw's device-specific data structures.

Parameters

hw_group	The hardware group in question
raw_hw_channel	The specific channel of

Returns

Index of 'channel in 's data structures

Definition at line 203 of file hardware.c.

References hw_timer_metadata::base, hw_button_metadata::base, hw_metadata::button, hw_uart_metadata::channel, hw_driver::channels, GPIO_PORTE_BASE, HW_BUTTON, hw_driver_singleton(), HW_TIMER, HW_UART, postpone_death, hw_metadata::timer, TIMER0_BASE, hw_metadata::uart, and UART0_BASE.

Referenced by _hw_subscribe(), hw_channel_init(), hw_notify(), and hw_unsubscribe().

                                                                {

    memory_address_t idx;
    switch(type){
        /* optimize: divide should be a shift */
    case HW_UART:   idx = (metadata.uart.channel - UART0_BASE)     / 0x1000; break;
    case HW_TIMER:  idx = (metadata.timer.base   - TIMER0_BASE)    / 0x1000; break;
    case HW_BUTTON: idx = (metadata.button.base  - GPIO_PORTE_BASE)/ 0x1000; break;
        /* Note: libhw won't allow for the use of ports higher than
         * GPIO_PORTE without modification of the above indexing
         * algorithm */
    default: postpone_death();
    }
    return &(hw_driver_singleton(type)->channels[idx]);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void _hw_subscribe	(	HW_TYPE	,
		hw_metadata	,
		void(*)(notification note)	isr,
		bool
	)

Subscribe to a hardware interrupt. This is also called connecting a signal (the isr to be notified) to a slot (the hw-triggered driver isr).

Parameters

The	hardware type in question
Metadata	about the device
The	pseudo-isr to be notified by the hardware driver

Definition at line 121 of file hardware.c.

References _hw_get_channel(), CDL_DELETE, CDL_PREPEND, hw_channel::free_slots, hw_channel::full_slots, _isr_subscription::single_shot_subscription, and _isr_subscription::slot.

Referenced by schedule_aperiodic().

                                            {

    hw_iterator i;
    hw_channel* channel = _hw_get_channel(type, metadata);
    _isr_subscription* new_subscrip = channel->free_slots;

    CDL_DELETE(channel->free_slots, new_subscrip);
    CDL_PREPEND(channel->full_slots, new_subscrip);

    new_subscrip->single_shot_subscription = single_shot;
    new_subscrip->slot = isr;
}

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t* get_adc_samples

(

)

void hw_channel_init	(	HW_TYPE	,
		hw_metadata
	)

This function is responsible for enabling a specific channel on the specified hardware device. Internal libhw datastructures will also be reset.

Parameters

hw_group	The hardware group in question
raw_channel	The memory-mapped address of the device channel to initialize
metadata	Information about how to initialize the device

Definition at line 94 of file hardware.c.

References _hw_get_channel(), button_set_interrupt(), CDL_PREPEND, hw_channel::free_slots, hw_channel::full_slots, HW_BUTTON, HW_DRIVER_MAX_SUBSCRIPTIONS, HW_TIMER, HW_UART, hw_channel::isr_subscriptions, NULL, postpone_death, timer_add_interrupt(), and uart_init().

Referenced by adc_interrupt_init(), button_debounce_start(), and main().

                                                         {

    hw_iterator i;
    hw_channel* channel = _hw_get_channel(type, metadata);
    channel->full_slots = NULL;
    for(i=0; i<HW_DRIVER_MAX_SUBSCRIPTIONS; ++i) {
        CDL_PREPEND(channel->free_slots, &channel->isr_subscriptions[i]);
    }

    switch(type) {
    case HW_UART:
        uart_init(metadata);
        break;

    case HW_TIMER:
        timer_add_interrupt(metadata);
        break;

    case HW_BUTTON:
        /* TODO: parametrize */
        button_set_interrupt(metadata);
        break;

    default: postpone_death();
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void hw_daemon

(

void

)

Definition at line 172 of file hardware.c.

References hw_notify_uart(), HW_SEM_UART0, INT_UART0, os_surrender_context, sem_guard, sem_take, UART0_BASE, UART_DEFAULT_BAUD_RATE, and uart_metadata_init.

Referenced by hw_init_daemon(), and main().

                     {
    while (1) {
        /* mind ordering of sem_checks */
        /* fixme: one thread for each hardware device, so individual
         * priorities can be assigned to the threads (which will
         * handle simultaneous interrupts according to priority
         * scheduler's interpretation of priority) */
        sem_guard(HW_SEM_UART0) {
            sem_take(HW_SEM_UART0);
            /* todo: schedule */
            uart_metadata_init(UART_DEFAULT_BAUD_RATE, UART0_BASE, INT_UART0);
            hw_notify_uart(uart_metadata);
        }
        os_surrender_context();
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void hw_driver_init	(	HW_TYPE	,
		hw_metadata
	)

This function is responsible for enabling the peripherals and internal data strutures used by the specified .

Parameters

hw_group

The hardware group driver to initialize

Definition at line 62 of file hardware.c.

References hw_timer_metadata::base, button_init(), hw_uart_metadata::channel, HW_BUTTON, HW_TIMER, HW_UART, postpone_death, SYSCTL_PERIPH_GPIOA, SYSCTL_PERIPH_GPIOF, SYSCTL_PERIPH_TIMER0, SYSCTL_PERIPH_UART0, SysCtlPeripheralEnable(), hw_metadata::timer, TIMER0_BASE, hw_metadata::uart, and UART0_BASE.

Referenced by main().

                                                        {

    switch(type) {
    case HW_UART:
        SysCtlPeripheralEnable(SYSCTL_PERIPH_UART0 +
                               (metadata.uart.channel - UART0_BASE) / 0x1000);
        /* todo: parametrize - are they all on A? */
        SysCtlPeripheralEnable(SYSCTL_PERIPH_GPIOA);
        break;

    case HW_TIMER:
        SysCtlPeripheralEnable(SYSCTL_PERIPH_TIMER0 +
                               (metadata.timer.base - TIMER0_BASE) / 0x1000);
        break;

    case HW_BUTTON:
        /* TODO: parametrize to allow other buttons to be driven */
        SysCtlPeripheralEnable(SYSCTL_PERIPH_GPIOF);
        /* #need4speed: Buttons on the board are only used for input,
         * we know how they're going to be used. Break the libhw
         * convention and initialize these buttons so this code never
         * has to be run again */
        button_init(metadata);
        break;

    default: postpone_death();
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

hw_driver* hw_driver_singleton ( HW_TYPE  )

inline

Return the one hw_driver per hardware device group in use by the TM4C.

Parameters

The	hardware type to grab a pointer of

Returns

Pointer to the hw_driver data structure managing

Definition at line 220 of file hardware.c.

References HW_BUTTON, HW_BUTTON_DRIVER, HW_TIMER, HW_TIMER_DRIVER, HW_UART, HW_UART_DRIVER, NULL, and postpone_death.

Referenced by _hw_get_channel().

                                             {

    switch(type) {
    case HW_UART:   return &HW_UART_DRIVER;
    case HW_TIMER:  return &HW_TIMER_DRIVER;
    case HW_BUTTON: return &HW_BUTTON_DRIVER;
    default:        postpone_death();
    }
    return NULL;
}

Here is the caller graph for this function:

void hw_init_daemon

(

)

Initialize libhw's internal data structures

Definition at line 54 of file hardware.c.

References hw_daemon(), and os_add_thread().

                      {

    os_add_thread(hw_daemon);
}

Here is the call graph for this function:

void hw_notify	(	HW_TYPE	,
		hw_metadata	,
		notification
	)

Notify threads subscribed to about an incoming hardware event.

Parameters

hw_group	The hardwawre group that received the incoming hardware event
channel	The channel of that received the incoming hardware event
notifications	The notification (prepared by NVIC-invoked ISR) containing information regarding the recently-occurring hardware interrupt event

Definition at line 149 of file hardware.c.

References _hw_get_channel(), CDL_DELETE, CDL_PREPEND, hw_channel::free_slots, hw_channel::full_slots, _isr_subscription::next, NULL, _isr_subscription::single_shot_subscription, and _isr_subscription::slot.

Referenced by GPIOPortF_Handler(), hw_notify_uart(), s_Handler(), sA_Handler(), TIMER0A_Handler(), TIMER1A_Handler(), and TIMER2A_Handler().

                                                                      {

    hw_iterator i=0;
    hw_channel* channel = _hw_get_channel(type, metadata);
    _isr_subscription* subscrip = channel->full_slots;
    _isr_subscription* new_subscrip = NULL;

    /* TODO: make this a doubly linked list, not circular */
    /* consider similar changes to os lib also */
    while(subscrip && subscrip != new_subscrip) {
        subscrip->slot(note);
        new_subscrip = subscrip->next;
        if (subscrip->single_shot_subscription) {
            /* Cease fire! cease fire! */
            subscrip->single_shot_subscription = false;
            CDL_DELETE(channel->full_slots, subscrip);
            CDL_PREPEND(channel->free_slots, subscrip);
        }
        subscrip = new_subscrip;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void hw_notify_uart

(

hw_metadata

uart_metadata

)

Iterate over all chars in the respective uart's RX_FIFO and notify all subscribed tasks.

Parameters

UART

metadata

Definition at line 189 of file hardware.c.

References notification::_char, buffer_dec, buffer_empty, buffer_last, hw_notify(), HW_UART, and UART0_RX_BUFFER.

Referenced by hw_daemon().

                                               {

    notification note;
    /* get-it-working: assume the dev knows which buffer to use */
    uint8_t* buffer = UART0_RX_BUFFER;
    while(!buffer_empty(UART0_RX_BUFFER)) {
        note._char = buffer_last(UART0_RX_BUFFER);
        buffer_dec(UART0_RX_BUFFER);
        hw_notify(HW_UART, uart_metadata, note);
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void hw_unsubscribe	(	HW_TYPE	,
		hw_metadata	,
		void(*)(notification note)	isr
	)

Unsubscribe from a hardware interrupt. This is also called disconnecting a signal (the isr in question) from a slot (the hw-triggered driver isr).

Parameters

The	hardware type in question
Metadata	about the device
The	pseudo-isr to be notified by the hardware driver

Definition at line 137 of file hardware.c.

References _hw_get_channel(), CDL_DELETE, CDL_PREPEND, hw_channel::free_slots, and hw_channel::full_slots.

Referenced by shell_kill().

                                                    {

    hw_channel* channel = _hw_get_channel(type, metadata);
    _isr_subscription* remove = channel->full_slots;

    while(remove->slot != isr) {++remove;}
    CDL_DELETE(channel->full_slots, remove);
    CDL_PREPEND(channel->free_slots, remove);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

volatile semaphore_t HW_SEM_UART0

static

Definition at line 11 of file hardware.h.

Referenced by hw_daemon(), and UART0_Handler().