<commit_before>  <hr>
    <h1 align="center">Documentation of the LIRC driver API version 2.</h1>
    <hr>

    <p>This document describes the API used by the LIRC userspace drivers in version 2.<p>
      <!--p>A dynamic driver can be distributed as source and/or binary, and installed in existing LIRC setups without recompiling.</p-->

    <p>It is targeted at active C programmers, and not written with the intention to be
       understandable by non-programmers.
     </p>

     <p>The guide aims at being fully compatible with the upcoming release LIRC 0.9.2. (CLARIFY)</p>

    <hr width="70%">
    <br>
    <h1>Introduction</h1>
    <p>There are three kinds of drivers in LIRC:
    <ol>
        <li>Kernel drivers, also called kernel modules. </li>
        <li>User space, statically linked drivers.</li>
        <li>User space, dynamically linked drivers.</li>
    </ol>
    <p>Kernel drivers will not be covered in the present article. User space drivers are
        nothing else but normal compiled C functions, running as the invoking user (which may or may not be root).
        Therefore, the decomposition between "program" and driver is a priori not always necessary,
        but instead serves modularization and structuring.
    </p>

    <p>In the beginning, due to its focus on very simple hardware, LIRC was very centered around kernal modules
        like directly connected LEDs or IR sensors. Modern hardware, due to embedded micro processors etc.,
        have less requirements on precise timing, and
        user space drivers are normally the preferred solution. One such driver consists of a C file, containing a number of function,
        which are linked into the executing program (e. g., Lircd).
        Traditionally (at least for LIRC) linking takes place during
        the build process (statically linking). The API for these drivers we will call "Driver API version 1".</p>

    <p>Dynamically loaded drivers was introduced LIRC just recently, <em>replacing</em> the statically linked drivers.
        It turned out to be necessary to slighty augment the driver API version 1. The new version will
        be referred to as "Driver API version 2".</p>

    <p>In this guide, the word <em>plugin</em> refers to the so-file on disk. Each such file
contains one or more driver(s) visible in the user interface. </p>

    <h1>Two flavors of drivers</h1>
    <p>An IR signal consists of a sequence of on-times (pulses) and off-times (gaps). (We disregard modulation for the time being.)
        A full-fledged IR driver, on reading, can deliver the timing of these period ("durations"). On sending,
        it can be fed with a list of durations, and it sends these on- and off-periods as (modulated) IR signals. Such a piece of
        hardware is suitable for receiving and/or transmitting "arbitrary" IR sequences.</p>

  <p>Much IR hardware was not designed as general-purpose IR hardware, but to allow e.g. a laptop computer or a TV
      card to be be controlled by the supplied remote. This hardware in general decodes the IR signal in its own hardware,
      and delivers, for recognized signals, an integer code denoting the code received (like "play").
      For signals not following the protocol, no output is generated. This property
      is indicated in the drivers as the feature <code>LIRC_CAN_REC_LIRCCODE</code>.</p>

  <p>As usable and flexible IR hardware for LIRC, these devices are second choice.
      The "learns" (configuration files) from such a device is of very limited value, and not portable to other IR devices,
      since timing information is missing. In the configuration file,
      this can be determined by the lines <code>one 0 0</code> and <code>one 0 0</code>,
      which is clearly not usable without the context, namely the hardware used for capturing.</p>

<p>This guide is intended for programmers
      writing and maintain "real" drivers.</p>

  <p>At the time of writing, there are about  44 plugins and 54 drivers. Of the drivers, 13 are 
     "general receivers"; the others  are LIRCCODE drivers. (The actual numbers vary depending
     on configuration i. e. libraries installed on the build system.)
     Since hardware related to LIRCCODE drivers (typically a TV-card) normally doesn't support
     sending there is no LIRCCODE driver which can send data. </p>

  <p> The tool lirc-lsplugins can be used to generate overviews of the drivers and their
     capabilities. </p>
  </p>
    <!--hr width="70%">
    <br-->
    <h1>The C interface</h1>
    <p>A (user space) driver is a C file where all the functions are declared <code>static</code>, i.e. not (directly)
        visible from outside of the file. The only thing visible from outside is a particular data structure,
        containing some data elements, and some pointers to functions, that in these way effectively are made public API.
        In this way a certain encapsulation is achieved. The data structure will be described next.</p>
    <h2>The <code>struct driver</code></h2>
    <p>The <code>struct driver</code> is the data structure representing the driver for LIRC.
        It is defined in <code>driver.h</code> (in directory <code>lib</code>).


    <pre>
struct driver {
        char *device;
        int fd;
        __u32 features;
        __u32 send_mode;
        __u32 rec_mode;
        __u32 code_length;
        int (*init_func) (void);
        int (*deinit_func) (void);
        int (*send_func) (struct ir_remote * remote, struct ir_ncode * code);
        char *(*rec_func) (struct ir_remote * remotes);
        int (*decode_func) (struct ir_remote * remote, struct decode_ctx_t* ctx);
        int (*drvctl_func) (unsigned int cmd, void *arg);
         lirc_t(*readdata) (lirc_t timeout);
        char *name;
        unsigned int resolution;

        /* The following fields are API version 2 extensions */
        const int api_version;
        const char* driver_version;
        int (*const close_func)(void);
	int (*const open_func)(const char* device);
};
    </pre>
    <p>These fields will next be described. Note that a driver sometimes "misuses" a field;
        e.g. the UDP driver expects a port number (as string) in the <code>device</code> field.
    </p>
    <p>Also note that some function pointer may be NULL, indicating that the driver
        does not implement the said functionality (e.g. sending of IR signals).</p>

    <p>The structures <code>ir_remote, ir_ncode</code> and, <code>ir_code</code> are declared in the file <code>ir_remote_types.h</code>.
        The data type <code>lirc_t</code> (what a meaningful name!) is an integer value used in many places for storing timing data.
        It is defined by <code>#define int</code> in <code>lirc.h</code>.
    <dl>
    <dt>device</dt>
    <dd>Typically the name of the device as text string in Linux. This
        corresponds to the <code>--device</code> argument to lircd
        Not all drivers respect the device field; some have hardcoded
        device name(s), some use autodetecting code. </dd>

    <dt>fd</dt>
    <dd>A file descriptor associated with the driver.</dd>

    <dt>features</dt>
    <dd>Code for the features of the present device, see Appendix. It consist of the bitwise or of a number of possible features.</dd>
    <dt>send_mode</dt>
    <dd>Use <code>LIRC_MODE_PULSE</code>.</dd>
    <dt>rec_mode</dt>
    <dd>Use <code>LIRC_MODE_MODE2</code>.</dd>
    <dt>code_length</dt>
    <dd>Only of relevance for LIRC_MODE_LIRCCODE drivers, for which it is the size in bits of the LIRCCODE.</dd>
    <dt>init_func</dt>
    <dd>Function pointer, see below.</dd>
    <dt>deinit_func</dt>
    <dd>Function pointer, see below.</dd>
    <dt>send_func<dt>
    <dd>Function pointer, see below. NULL if the driver cannot transmit.</dd>
    <dt>rec_func<dt>
    <dd>Function pointer, see below. NULL if the driver cannot receive.</dd>
    <dt>decode_func</dt>
    <dd>Function pointer, for "real" drivers (not using LIRC_MODE_LIRCCODE),
        just use <code>receive_decode</code>, a function defined in <code>receive.c</code>.</dd>
    <dt>ioctl_func</dt>
    <dd>Function pointer, see below. May be NULL if there are no ioctls.</dd>
    <dt>
    <dt>readdata</dt>
    <dd>Function pointer, see below. Is NULL if the driver reads uses LIRC_MODE_LIRCCODE.</dd>
    <dt>name<dt>
    <dd>Name of the driver in a human readable form, as listed e.g. by <code>lircd --driver help</code>
        or <code>irrecord --driver help</code>. Although not enforced,
        it is recommended to use names following the syntax for C identifiers.</dd>
    <dt>resolution</dt>
    <dd>The resolution in microseconds of the recorded durations when reading signals.
        Used as default value for the <code>aeps</code> parameter in remotes.</dd>
    <dt>api_version<dt>
    <dd>Use 2.</dd>
    <dt>driver_version</dt>
    <dd>Free form string used to identify the version of the driver, if desired.</dd>
    <dt>close_func</dt>
    <dd>Function pointer, see below.</dd>
    </dl>

    <h2>Driver lifecycle and <code>lircd</code></h2>
    <p>
        The driver is loaded, used and unloaded by the executing program according to the
    following:
    <ol><commit_msg>doc: Add driver info update.<commit_after>  <hr>
    <h1 align="center">Documentation of the LIRC driver API version 2.</h1>
    <hr>

    <p>This document describes the API used by the LIRC userspace drivers in version 2.<p>
      <!--p>A dynamic driver can be distributed as source and/or binary, and installed in existing LIRC setups without recompiling.</p-->

    <p>It is targeted at active C programmers, and not written with the intention to be
       understandable by non-programmers.
     </p>

     <p>The guide aims at being fully compatible with the upcoming release LIRC 0.9.2. (CLARIFY)</p>

    <hr width="70%">
    <br>
    <h1>Introduction</h1>
    <p>There are three kinds of drivers in LIRC:
    <ol>
        <li>Kernel drivers, also called kernel modules. </li>
        <li>User space, statically linked drivers.</li>
        <li>User space, dynamically linked drivers.</li>
    </ol>
    <p>Kernel drivers will not be covered in the present article. User space drivers are
        nothing else but normal compiled C functions, running as the invoking user (which may or may not be root).
        Therefore, the decomposition between "program" and driver is a priori not always necessary,
        but instead serves modularization and structuring.
    </p>

    <p>In the beginning, due to its focus on very simple hardware, LIRC was very centered around kernal modules
        like directly connected LEDs or IR sensors. Modern hardware, due to embedded micro processors etc.,
        have less requirements on precise timing, and
        user space drivers are normally the preferred solution. One such driver consists of a C file, containing a number of function,
        which are linked into the executing program (e. g., Lircd).
        Traditionally (at least for LIRC) linking takes place during
        the build process (statically linking). The API for these drivers we will call "Driver API version 1".</p>

    <p>Dynamically loaded drivers was introduced LIRC just recently, <em>replacing</em> the statically linked drivers.
        It turned out to be necessary to slighty augment the driver API version 1. The new version will
        be referred to as "Driver API version 2".</p>

    <p>In this guide, the word <em>plugin</em> refers to the so-file on disk. Each such file
contains one or more driver(s) visible in the user interface. </p>

    <h1>Two flavors of drivers</h1>
    <p>An IR signal consists of a sequence of on-times (pulses) and off-times (gaps). (We disregard modulation for the time being.)
        A full-fledged IR driver, on reading, can deliver the timing of these period ("durations"). On sending,
        it can be fed with a list of durations, and it sends these on- and off-periods as (modulated) IR signals. Such a piece of
        hardware is suitable for receiving and/or transmitting "arbitrary" IR sequences.</p>

  <p>Much IR hardware was not designed as general-purpose IR hardware, but to allow e.g. a laptop computer or a TV
      card to be be controlled by the supplied remote. This hardware in general decodes the IR signal in its own hardware,
      and delivers, for recognized signals, an integer code denoting the code received (like "play").
      For signals not following the protocol, no output is generated. This property
      is indicated in the drivers as the feature <code>LIRC_CAN_REC_LIRCCODE</code>.</p>

  <p>As usable and flexible IR hardware for LIRC, these devices are second choice.
      The "learns" (configuration files) from such a device is of very limited value, and not portable to other IR devices,
      since timing information is missing. In the configuration file,
      this can be determined by the lines <code>one 0 0</code> and <code>one 0 0</code>,
      which is clearly not usable without the context, namely the hardware used for capturing.</p>

<p>This guide is intended for programmers
      writing and maintain "real" drivers.</p>

  <p>At the time of writing, there are about  44 plugins and 54 drivers. Of the drivers, 13 are 
     "general receivers"; the others  are LIRCCODE drivers. (The actual numbers vary depending
     on configuration i. e. libraries installed on the build system.)
     Since hardware related to LIRCCODE drivers (typically a TV-card) normally doesn't support
     sending there is no LIRCCODE driver which can send data. </p>

  <p> The tool lirc-lsplugins can be used to generate overviews of the drivers and their
     capabilities. </p>
  </p>
    <!--hr width="70%">
    <br-->
    <h1>The C interface</h1>
    <p>A (user space) driver is a C file where all the functions are declared <code>static</code>, i.e. not (directly)
        visible from outside of the file. The only thing visible from outside is a particular data structure,
        containing some data elements, and some pointers to functions, that in these way effectively are made public API.
        In this way a certain encapsulation is achieved. The data structure will be described next.</p>
    <h2>The <code>struct driver</code></h2>
    <p>The <code>struct driver</code> is the data structure representing the driver for LIRC.
        It is defined in <code>driver.h</code> (in directory <code>lib</code>).


    <pre>
struct driver {
        char *device;
        int fd;
        __u32 features;
        __u32 send_mode;
        __u32 rec_mode;
        __u32 code_length;
        int (*init_func) (void);
        int (*deinit_func) (void);
        int (*send_func) (struct ir_remote * remote, struct ir_ncode * code);
        char *(*rec_func) (struct ir_remote * remotes);
        int (*decode_func) (struct ir_remote * remote, struct decode_ctx_t* ctx);
        int (*drvctl_func) (unsigned int cmd, void *arg);
         lirc_t(*readdata) (lirc_t timeout);
        char *name;
        unsigned int resolution;

        /* The following fields are API version 2 extensions */
        const int api_version;
        const char* driver_version;
        const char* info;
        int (*const close_func)(void);
        int (*const open_func)(const char* device);
};
    </pre>
    <p>These fields will next be described. Note that a driver sometimes "misuses" a field;
        e.g. the UDP driver expects a port number (as string) in the <code>device</code> field.
    </p>
    <p>Also note that some function pointer may be NULL, indicating that the driver
        does not implement the said functionality (e.g. sending of IR signals).</p>

    <p>The structures <code>ir_remote, ir_ncode</code> and, <code>ir_code</code> are declared in the file <code>ir_remote_types.h</code>.
        The data type <code>lirc_t</code> (what a meaningful name!) is an integer value used in many places for storing timing data.
        It is defined by <code>#define int</code> in <code>lirc.h</code>.
    <dl>
    <dt>device</dt>
    <dd>Typically the name of the device as text string in Linux. This
        corresponds to the <code>--device</code> argument to lircd
        Not all drivers respect the device field; some have hardcoded
        device name(s), some use autodetecting code. </dd>

    <dt>fd</dt>
    <dd>A file descriptor associated with the driver.</dd>

    <dt>features</dt>
    <dd>Code for the features of the present device, see Appendix. It consist of the bitwise or of a number of possible features.</dd>
    <dt>send_mode</dt>
    <dd>Use <code>LIRC_MODE_PULSE</code>.</dd>
    <dt>rec_mode</dt>
    <dd>Use <code>LIRC_MODE_MODE2</code>.</dd>
    <dt>code_length</dt>
    <dd>Only of relevance for LIRC_MODE_LIRCCODE drivers, for which it is the size in bits of the LIRCCODE.</dd>
    <dt>init_func</dt>
    <dd>Function pointer, see below.</dd>
    <dt>deinit_func</dt>
    <dd>Function pointer, see below.</dd>
    <dt>send_func<dt>
    <dd>Function pointer, see below. NULL if the driver cannot transmit.</dd>
    <dt>rec_func<dt>
    <dd>Function pointer, see below. NULL if the driver cannot receive.</dd>
    <dt>decode_func</dt>
    <dd>Function pointer, for "real" drivers (not using LIRC_MODE_LIRCCODE),
        just use <code>receive_decode</code>, a function defined in <code>receive.c</code>.</dd>
    <dt>ioctl_func</dt>
    <dd>Function pointer, see below. May be NULL if there are no ioctls.</dd>
    <dt>
    <dt>readdata</dt>
    <dd>Function pointer, see below. Is NULL if the driver reads uses LIRC_MODE_LIRCCODE.</dd>
    <dt>name<dt>
    <dd>Name of the driver in a human readable form, as listed e.g. by <code>lircd --driver help</code>
        or <code>irrecord --driver help</code>. Although not enforced,
        it is recommended to use names following the syntax for C identifiers.</dd>
    <dt>resolution</dt>
    <dd>The resolution in microseconds of the recorded durations when reading signals.
        Used as default value for the <code>aeps</code> parameter in remotes.</dd>
    <dt>api_version<dt>
    <dd>Use 2.</dd>
    <dt>driver_version</dt>
    <dd>Free form string used to identify the version of the driver, if desired.</dd>
    <dt>info</dt>
    <dd>Free form string, overall driver information.</dd>
    <dt>close_func</dt>
    <dd>Function pointer, see below.</dd>
    </dl>

    <h2>Driver lifecycle and <code>lircd</code></h2>
    <p>
        The driver is loaded, used and unloaded by the executing program according to the
    following:
    <ol>
{'fraction_non_alphanumeric': 0.09111003288586986, 'fraction_numerical': 0.0048520135856380394, 'mean_word_length': 3.1057990261177513, 'pattern_counts': {'":': 0, '<': 397, '<?xml version=': 0, '>': 397, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4530293', 'n_tokens_mistral': 5406, 'n_tokens_neox': 5245, 'n_words': 2369}