9. Remote Controller devices

9.1. Remote Controller core

enum rc_driver_type

type of the RC output

Constants

RC_DRIVER_SCANCODE

Driver or hardware generates a scancode

RC_DRIVER_IR_RAW

Driver or hardware generates pulse/space sequences. It needs a Infra-Red pulse/space decoder

RC_DRIVER_IR_RAW_TX

Device transmitter only, driver requires pulse/space data sequence.

struct rc_scancode_filter

Filter scan codes.

Definition

struct rc_scancode_filter {
  u32 data;
  u32 mask;
};

Members

data

Scancode data to match.

mask

Mask of bits of scancode to compare.

enum rc_filter_type

Filter type constants.

Constants

RC_FILTER_NORMAL

Filter for normal operation.

RC_FILTER_WAKEUP

Filter for waking from suspend.

RC_FILTER_MAX

Number of filter types.

struct rc_dev

represents a remote control device

Definition

struct rc_dev {
  struct device dev;
  atomic_t initialized;
  bool managed_alloc;
  const struct attribute_group * sysfs_groups[5];
  const char * input_name;
  const char * input_phys;
  struct input_id input_id;
  char * driver_name;
  const char * map_name;
  struct rc_map rc_map;
  struct mutex lock;
  unsigned int minor;
  struct ir_raw_event_ctrl * raw;
  struct input_dev * input_dev;
  enum rc_driver_type driver_type;
  bool idle;
  bool encode_wakeup;
  u64 allowed_protocols;
  u64 enabled_protocols;
  u64 allowed_wakeup_protocols;
  enum rc_type wakeup_protocol;
  struct rc_scancode_filter scancode_filter;
  struct rc_scancode_filter scancode_wakeup_filter;
  u32 scancode_mask;
  u32 users;
  void * priv;
  spinlock_t keylock;
  bool keypressed;
  unsigned long keyup_jiffies;
  struct timer_list timer_keyup;
  u32 last_keycode;
  enum rc_type last_protocol;
  u32 last_scancode;
  u8 last_toggle;
  u32 timeout;
  u32 min_timeout;
  u32 max_timeout;
  u32 rx_resolution;
  u32 tx_resolution;
  int (* change_protocol) (struct rc_dev *dev, u64 *rc_type);
  int (* open) (struct rc_dev *dev);
  void (* close) (struct rc_dev *dev);
  int (* s_tx_mask) (struct rc_dev *dev, u32 mask);
  int (* s_tx_carrier) (struct rc_dev *dev, u32 carrier);
  int (* s_tx_duty_cycle) (struct rc_dev *dev, u32 duty_cycle);
  int (* s_rx_carrier_range) (struct rc_dev *dev, u32 min, u32 max);
  int (* tx_ir) (struct rc_dev *dev, unsigned *txbuf, unsigned n);
  void (* s_idle) (struct rc_dev *dev, bool enable);
  int (* s_learning_mode) (struct rc_dev *dev, int enable);
  int (* s_carrier_report) (struct rc_dev *dev, int enable);
  int (* s_filter) (struct rc_dev *dev,struct rc_scancode_filter *filter);
  int (* s_wakeup_filter) (struct rc_dev *dev,struct rc_scancode_filter *filter);
  int (* s_timeout) (struct rc_dev *dev,unsigned int timeout);
};

Members

dev

driver model’s view of this device

initialized

1 if the device init has completed, 0 otherwise

managed_alloc

devm_rc_allocate_device was used to create rc_dev

sysfs_groups[5]

sysfs attribute groups

input_name

name of the input child device

input_phys

physical path to the input child device

input_id

id of the input child device (struct input_id)

driver_name

name of the hardware driver which registered this device

map_name

name of the default keymap

rc_map

current scan/key table

lock

used to ensure we’ve filled in all protocol details before anyone can call show_protocols or store_protocols

minor

unique minor remote control device number

raw

additional data for raw pulse/space devices

input_dev

the input child device used to communicate events to userspace

driver_type

specifies if protocol decoding is done in hardware or software

idle

used to keep track of RX state

encode_wakeup

wakeup filtering uses IR encode API, therefore the allowed wakeup protocols is the set of all raw encoders

allowed_protocols

bitmask with the supported RC_BIT_* protocols

enabled_protocols

bitmask with the enabled RC_BIT_* protocols

allowed_wakeup_protocols

bitmask with the supported RC_BIT_* wakeup protocols

wakeup_protocol

the enabled RC_TYPE_* wakeup protocol or RC_TYPE_UNKNOWN if disabled.

scancode_filter

scancode filter

scancode_wakeup_filter

scancode wakeup filters

scancode_mask

some hardware decoders are not capable of providing the full scancode to the application. As this is a hardware limit, we can’t do anything with it. Yet, as the same keycode table can be used with other devices, a mask is provided to allow its usage. Drivers should generally leave this field in blank

users

number of current users of the device

priv

driver-specific data

keylock

protects the remaining members of the struct

keypressed

whether a key is currently pressed

keyup_jiffies

time (in jiffies) when the current keypress should be released

timer_keyup

timer for releasing a keypress

last_keycode

keycode of last keypress

last_protocol

protocol of last keypress

last_scancode

scancode of last keypress

last_toggle

toggle value of last command

timeout

optional time after which device stops sending data

min_timeout

minimum timeout supported by device

max_timeout

maximum timeout supported by device

rx_resolution

resolution (in ns) of input sampler

tx_resolution

resolution (in ns) of output sampler

change_protocol

allow changing the protocol used on hardware decoders

open

callback to allow drivers to enable polling/irq when IR input device is opened.

close

callback to allow drivers to disable polling/irq when IR input device is opened.

s_tx_mask

set transmitter mask (for devices with multiple tx outputs)

s_tx_carrier

set transmit carrier frequency

s_tx_duty_cycle

set transmit duty cycle (0% - 100%)

s_rx_carrier_range

inform driver about carrier it is expected to handle

tx_ir

transmit IR

s_idle

enable/disable hardware idle mode, upon which, device doesn’t interrupt host until it sees IR pulses

s_learning_mode

enable wide band receiver used for learning

s_carrier_report

enable carrier reports

s_filter

set the scancode filter

s_wakeup_filter

set the wakeup scancode filter. If the mask is zero then wakeup should be disabled. wakeup_protocol will be set to a valid protocol if mask is nonzero.

s_timeout

set hardware timeout in ns

struct rc_dev * rc_allocate_device(enum rc_driver_type)

Allocates a RC device

Parameters

enum rc_driver_type

specifies the type of the RC output to be allocated returns a pointer to struct rc_dev.

struct rc_dev * devm_rc_allocate_device(struct device * dev, enum rc_driver_type)

Managed RC device allocation

Parameters

struct device * dev

pointer to struct device

enum rc_driver_type

specifies the type of the RC output to be allocated returns a pointer to struct rc_dev.

void rc_free_device(struct rc_dev * dev)

Frees a RC device

Parameters

struct rc_dev * dev

pointer to struct rc_dev.

int rc_register_device(struct rc_dev * dev)

Registers a RC device

Parameters

struct rc_dev * dev

pointer to struct rc_dev.

int devm_rc_register_device(struct device * parent, struct rc_dev * dev)

Manageded registering of a RC device

Parameters

struct device * parent

pointer to struct device.

struct rc_dev * dev

pointer to struct rc_dev.

void rc_unregister_device(struct rc_dev * dev)

Unregisters a RC device

Parameters

struct rc_dev * dev

pointer to struct rc_dev.

int rc_open(struct rc_dev * rdev)

Opens a RC device

Parameters

struct rc_dev * rdev

pointer to struct rc_dev.

void rc_close(struct rc_dev * rdev)

Closes a RC device

Parameters

struct rc_dev * rdev

pointer to struct rc_dev.

enum rc_type

type of the Remote Controller protocol

Constants

RC_TYPE_UNKNOWN

Protocol not known

RC_TYPE_OTHER

Protocol known but proprietary

RC_TYPE_RC5

Philips RC5 protocol

RC_TYPE_RC5X_20

Philips RC5x 20 bit protocol

RC_TYPE_RC5_SZ

StreamZap variant of RC5

RC_TYPE_JVC

JVC protocol

RC_TYPE_SONY12

Sony 12 bit protocol

RC_TYPE_SONY15

Sony 15 bit protocol

RC_TYPE_SONY20

Sony 20 bit protocol

RC_TYPE_NEC

NEC protocol

RC_TYPE_NECX

Extended NEC protocol

RC_TYPE_NEC32

NEC 32 bit protocol

RC_TYPE_SANYO

Sanyo protocol

RC_TYPE_MCE_KBD

RC6-ish MCE keyboard/mouse

RC_TYPE_RC6_0

Philips RC6-0-16 protocol

RC_TYPE_RC6_6A_20

Philips RC6-6A-20 protocol

RC_TYPE_RC6_6A_24

Philips RC6-6A-24 protocol

RC_TYPE_RC6_6A_32

Philips RC6-6A-32 protocol

RC_TYPE_RC6_MCE

MCE (Philips RC6-6A-32 subtype) protocol

RC_TYPE_SHARP

Sharp protocol

RC_TYPE_XMP

XMP protocol

RC_TYPE_CEC

CEC protocol

struct rc_map_table

represents a scancode/keycode pair

Definition

struct rc_map_table {
  u32 scancode;
  u32 keycode;
};

Members

scancode

scan code (u32)

keycode

Linux input keycode

struct rc_map

represents a keycode map table

Definition

struct rc_map {
  struct rc_map_table * scan;
  unsigned int size;
  unsigned int len;
  unsigned int alloc;
  enum rc_type rc_type;
  const char * name;
  spinlock_t lock;
};

Members

scan

pointer to struct rc_map_table

size

Max number of entries

len

Number of entries that are in use

alloc

size of *scan, in bytes

rc_type

type of the remote controller protocol, as defined at enum rc_type

name

name of the key map table

lock

lock to protect access to this structure

struct rc_map_list

list of the registered rc_map maps

Definition

struct rc_map_list {
  struct list_head list;
  struct rc_map map;
};

Members

list

pointer to struct list_head

map

pointer to struct rc_map

int rc_map_register(struct rc_map_list * map)

Registers a Remote Controler scancode map

Parameters

struct rc_map_list * map

pointer to struct rc_map_list

void rc_map_unregister(struct rc_map_list * map)

Unregisters a Remote Controler scancode map

Parameters

struct rc_map_list * map

pointer to struct rc_map_list

struct rc_map * rc_map_get(const char * name)

gets an RC map from its name

Parameters

const char * name

name of the RC scancode map

9.2. LIRC

struct lirc_driver

Defines the parameters on a LIRC driver

Definition

struct lirc_driver {
  char name[40];
  int minor;
  __u32 code_length;
  unsigned int buffer_size;
  int sample_rate;
  __u32 features;
  unsigned int chunk_size;
  void * data;
  int min_timeout;
  int max_timeout;
  int (* add_to_buf) (void *data, struct lirc_buffer *buf);
  struct lirc_buffer * rbuf;
  int (* set_use_inc) (void *data);
  void (* set_use_dec) (void *data);
  struct rc_dev * rdev;
  const struct file_operations * fops;
  struct device * dev;
  struct module * owner;
};

Members

name[40]

this string will be used for logs

minor

indicates minor device (/dev/lirc) number for registered driver if caller fills it with negative value, then the first free minor number will be used (if available).

code_length

length of the remote control key code expressed in bits.

buffer_size

Number of FIFO buffers with chunk_size size. If zero, creates a buffer with BUFLEN size (16 bytes).

sample_rate

if zero, the device will wait for an event with a new code to be parsed. Otherwise, specifies the sample rate for polling. Value should be between 0 and HZ. If equal to HZ, it would mean one polling per second.

features

lirc compatible hardware features, like LIRC_MODE_RAW, LIRC_CAN_*, as defined at include/media/lirc.h.

chunk_size

Size of each FIFO buffer.

data

it may point to any driver data and this pointer will be passed to all callback functions.

min_timeout

Minimum timeout for record. Valid only if LIRC_CAN_SET_REC_TIMEOUT is defined.

max_timeout

Maximum timeout for record. Valid only if LIRC_CAN_SET_REC_TIMEOUT is defined.

add_to_buf

add_to_buf will be called after specified period of the time or triggered by the external event, this behavior depends on value of the sample_rate this function will be called in user context. This routine should return 0 if data was added to the buffer and -ENODATA if none was available. This should add some number of bits evenly divisible by code_length to the buffer.

rbuf

if not NULL, it will be used as a read buffer, you will have to write to the buffer by other means, like irq’s (see also lirc_serial.c).

set_use_inc

set_use_inc will be called after device is opened

set_use_dec

set_use_dec will be called after device is closed

rdev

Pointed to struct rc_dev associated with the LIRC device.

fops

file_operations for drivers which don’t fit the current driver model. Some ioctl’s can be directly handled by lirc_dev if the driver’s ioctl function is NULL or if it returns -ENOIOCTLCMD (see also lirc_serial.c).

dev

pointer to the struct device associated with the LIRC device.

owner

the module owning this struct