hardware.h

Go to the documentation of this file.

/* -*- mode: c; c-basic-offset: 4; -*- */
#ifndef __HARDWARE__
#define __HARDWARE__

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

/* TODO: Expand this for all devices */
static volatile semaphore_t HW_SEM_UART0;

uint32_t* get_adc_samples();
/* Note to developers:
 *
 * Why did the authors create structs that contain only an array?
 * Wouldn't it be easier to simply refer to the array instead of
 * unwrapping it from the context of the struct each time it is
 * invoked? You could even use a typedef to further shorten each invocation!
 *
 * Wisdom, thrown down from the mountain:
 * http://stackoverflow.com/a/4523537 [quoted below]
 *
 * [An unwrapped array with a typedef for convenience] is probably a
 * very bad idea, because the resulting type is an array type, but
 * users of it won't see that it's an array type. If used as a
 * function argument, it will be passed by reference, not by value,
 * and the sizeof for it will then be wrong.
 */

/* A note about this library:
 *
 * This hardware driver interfaces between userspace programs and
 * peripheral drivers. Users should never touch drivers directly but
 * instead rely on libhw's notification system.
 *
 * todo for developers: update this after the impending redesign
 */

typedef enum {
    HW_UART,
    HW_TIMER,
    HW_BUTTON,
    HW_ADC
} HW_TYPE;

typedef struct {
    uint32_t baud_rate;
    memory_address_t channel;
    uint32_t interrupt;
} hw_uart_metadata;

/* todo: add union for timer_frequency or timer_period */
typedef struct {
    memory_address_t base;
    frequency_t frequency;
    uint32_t interrupt;
    uint32_t periodic; /* TIMER_CFG_PERIODIC or TIMER_CFG_ONE_SHOT */
} hw_timer_metadata;

typedef struct {
    /* NOTE: base will be used in the future when we have buttons on
       different ports */
    memory_address_t base;
    memory_address_t pin;
    uint32_t interrupt;
} hw_button_metadata;

typedef union {
    hw_timer_metadata timer;
} adc_trigger_metadata;

typedef struct {
    /* NOTE: base will be used in the future when we have adcs on
       different ports */
    memory_address_t base;
    uint32_t trigger_source;
    uint32_t sample_sequence;
    uint32_t channel;
    uint32_t channel_configuration;
    adc_trigger_metadata trigger_metadata;
} hw_adc_metadata;

typedef union {
    hw_uart_metadata uart;
    hw_timer_metadata timer;
    hw_button_metadata button;
    hw_adc_metadata adc;
} hw_metadata;

typedef uint8_t hw_iterator;

/* typedef void (*isr_t)(notification note); */

#define HW_DRIVER_MAX_CHANNELS 8

#define HW_DRIVER_MAX_SUBSCRIPTIONS 8

typedef struct _isr_subscription _isr_subscription;
struct _isr_subscription {
    bool single_shot_subscription;
    void (*slot)(notification);
    _isr_subscription* next;
    _isr_subscription* prev;
};

typedef struct {
    _isr_subscription isr_subscriptions[HW_DRIVER_MAX_SUBSCRIPTIONS];
    _isr_subscription* free_slots;
    _isr_subscription* full_slots;
} hw_channel;

typedef struct {
    hw_channel channels[HW_DRIVER_MAX_CHANNELS];
} hw_driver;

#define hw_init(type, metadata)     \
    hw_driver_init(type, metadata); \
    hw_channel_init(type, metadata)

#define hw_init_and_subscribe(type, metadata, pseudo_isr) \
    hw_init(type, metadata);                              \
    hw_subscribe(type, metadata, pseudo_isr)

void hw_init_daemon();

void hw_driver_init(HW_TYPE, hw_metadata);

void hw_channel_init(HW_TYPE, hw_metadata);

#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)

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);

/* TODO: Doxygenize */
void hw_daemon(void);

#endif