Tue, 26 Aug 2008 22:01:01 +0100
add Doxygen control file
philpem@0 | 1 | /**************************************************************************** |
philpem@0 | 2 | * Project: liblpfk |
philpem@0 | 3 | * Purpose: Driver library for the IBM 6094-020 Lighted Program Function |
philpem@0 | 4 | * Keyboard. |
philpem@0 | 5 | * Version: 1.0 |
philpem@0 | 6 | * Author: Philip Pemberton <philpem@philpem.me.uk> |
philpem@0 | 7 | * |
philpem@0 | 8 | * The latest version of this library is available from |
philpem@0 | 9 | * <http://www.philpem.me.uk/code/liblpfk/>. |
philpem@0 | 10 | * |
philpem@0 | 11 | * Copyright (c) 2008, Philip Pemberton |
philpem@0 | 12 | * All rights reserved. |
philpem@0 | 13 | * |
philpem@0 | 14 | * Redistribution and use in source and binary forms, with or without |
philpem@0 | 15 | * modification, are permitted provided that the following conditions |
philpem@0 | 16 | * are met: |
philpem@0 | 17 | * |
philpem@0 | 18 | * * Redistributions of source code must retain the above copyright |
philpem@0 | 19 | * notice, this list of conditions and the following disclaimer. |
philpem@0 | 20 | * * Redistributions in binary form must reproduce the above copyright |
philpem@0 | 21 | * notice, this list of conditions and the following disclaimer in |
philpem@0 | 22 | * the documentation and/or other materials provided with the |
philpem@0 | 23 | * distribution. |
philpem@0 | 24 | * * Neither the name of the project nor the names of its |
philpem@0 | 25 | * contributors may be used to endorse or promote products derived |
philpem@0 | 26 | * from this software without specific prior written permission. |
philpem@0 | 27 | * |
philpem@0 | 28 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
philpem@0 | 29 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
philpem@0 | 30 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS |
philpem@0 | 31 | * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE |
philpem@0 | 32 | * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, |
philpem@0 | 33 | * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
philpem@0 | 34 | * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS |
philpem@0 | 35 | * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
philpem@0 | 36 | * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR |
philpem@0 | 37 | * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE |
philpem@0 | 38 | * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
philpem@0 | 39 | ****************************************************************************/ |
philpem@0 | 40 | |
philpem@0 | 41 | /** |
philpem@0 | 42 | * @file liblpfk.h |
philpem@0 | 43 | * @brief liblpfk library header |
philpem@0 | 44 | */ |
philpem@0 | 45 | |
philpem@0 | 46 | #ifndef _liblpfk_h_included |
philpem@0 | 47 | #define _liblpfk_h_included |
philpem@0 | 48 | |
philpem@0 | 49 | #include <termios.h> |
philpem@0 | 50 | |
philpem@0 | 51 | /** |
philpem@0 | 52 | * @brief LPFK context |
philpem@0 | 53 | * |
philpem@0 | 54 | * Do not change any variables inside this struct, they are for liblpfk's |
philpem@0 | 55 | * internal use only. |
philpem@0 | 56 | */ |
philpem@0 | 57 | typedef struct { |
philpem@0 | 58 | int fd; ///< serial port file descriptor |
philpem@0 | 59 | struct termios oldtio; ///< old termios setup |
philpem@0 | 60 | int enabled; ///< LPFK enabled |
philpem@0 | 61 | unsigned long led_mask; ///< lit LEDs mask |
philpem@0 | 62 | } LPFK_CTX; |
philpem@0 | 63 | |
philpem@0 | 64 | /** |
philpem@0 | 65 | * @brief liblpfk error codes |
philpem@0 | 66 | */ |
philpem@0 | 67 | enum { |
philpem@0 | 68 | LPFK_E_OK = 0, ///< No error, success. |
philpem@4 | 69 | LPFK_E_NO_KEYS = -1, ///< No keys in input buffer |
philpem@4 | 70 | LPFK_E_PORT_OPEN = -2, ///< Could not open comm port. |
philpem@4 | 71 | LPFK_E_NOT_PRESENT = -3, ///< LPFK not present on specified port. |
philpem@4 | 72 | LPFK_E_COMMS = -4, ///< Communication error. |
philpem@4 | 73 | LPFK_E_PARAM = -5, ///< Invalid function parameter. |
philpem@4 | 74 | LPFK_E_NOT_ENABLED = -6 ///< Attempt to read key when LPFK disabled |
philpem@0 | 75 | }; |
philpem@0 | 76 | |
philpem@0 | 77 | /** |
philpem@0 | 78 | * @brief Open a serial port and attempt to connecct to an LPFK on that |
philpem@0 | 79 | * port. |
philpem@0 | 80 | * @param port Serial port path (e.g. /dev/ttyS0). |
philpem@0 | 81 | * @param ctx Pointer to an LPFK_CTX struct where LPFK context will be |
philpem@0 | 82 | * stored. |
philpem@0 | 83 | * @return LPFK_E_OK on success, LPFK_E_PORT_OPEN if port could not be |
philpem@0 | 84 | * opened, LPFK_E_NOT_PRESENT if no LPFK present on specified port. |
philpem@0 | 85 | */ |
philpem@2 | 86 | int lpfk_open(LPFK_CTX *ctx, const char *port); |
philpem@0 | 87 | |
philpem@0 | 88 | /** |
philpem@0 | 89 | * @brief Close the LPFK. |
philpem@0 | 90 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@0 | 91 | * @return LPFK_E_OK |
philpem@0 | 92 | */ |
philpem@0 | 93 | int lpfk_close(LPFK_CTX *ctx); |
philpem@0 | 94 | |
philpem@0 | 95 | /** |
philpem@0 | 96 | * @brief Enable or disable LPFK input |
philpem@0 | 97 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@0 | 98 | * @param val true to enable the LPFK's keys, false to disable. |
philpem@0 | 99 | * @return LPFK_E_OK on success, LPFK_E_COMMS on comms error. |
philpem@0 | 100 | */ |
philpem@2 | 101 | int lpfk_enable(LPFK_CTX *ctx, const int val); |
philpem@0 | 102 | |
philpem@0 | 103 | /** |
philpem@1 | 104 | * @brief Set or clear an LED in the cached LED mask buffer. |
philpem@1 | 105 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@1 | 106 | * @param num LED/key number, from 0 to 31. |
philpem@1 | 107 | * @param state State, true for on, false for off. |
philpem@1 | 108 | * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS |
philpem@1 | 109 | * on comms error. |
philpem@1 | 110 | */ |
philpem@1 | 111 | int lpfk_set_led_cached(LPFK_CTX *ctx, const int num, const int state); |
philpem@1 | 112 | |
philpem@1 | 113 | /** |
philpem@1 | 114 | * @brief Set or clear all the LEDs in the shadow register. |
philpem@1 | 115 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@1 | 116 | * @param state State, true for on, false for off. |
philpem@1 | 117 | * @return LPFK_E_OK on success. |
philpem@1 | 118 | */ |
philpem@1 | 119 | int lpfk_set_leds_cached(LPFK_CTX *ctx, const int state); |
philpem@1 | 120 | |
philpem@1 | 121 | /** |
philpem@1 | 122 | * @brief Set the LPFK's LED state from the cached LED mask. |
philpem@1 | 123 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@1 | 124 | * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS |
philpem@1 | 125 | * on comms error. |
philpem@1 | 126 | */ |
philpem@1 | 127 | int lpfk_update_leds(LPFK_CTX *ctx); |
philpem@1 | 128 | |
philpem@1 | 129 | /** |
philpem@0 | 130 | * @brief Set or clear an LED on the LPFK. |
philpem@0 | 131 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@0 | 132 | * @param num LED/key number, from 0 to 31. |
philpem@0 | 133 | * @param state State, true for on, false for off. |
philpem@0 | 134 | * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS |
philpem@0 | 135 | * on comms error. |
philpem@1 | 136 | * @note Equivalent to a call to lpfk_set_led_cached() followed by a call |
philpem@1 | 137 | * to lpfk_update_leds(). |
philpem@0 | 138 | */ |
philpem@0 | 139 | int lpfk_set_led(LPFK_CTX *ctx, const int num, const int state); |
philpem@0 | 140 | |
philpem@0 | 141 | /** |
philpem@0 | 142 | * @brief Set or clear all the LEDs on the LPFK. |
philpem@0 | 143 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@0 | 144 | * @param state State, true for on, false for off. |
philpem@0 | 145 | * @return LPFK_E_OK on success, LPFK_E_PARAM on bad parameter, LPFK_E_COMMS |
philpem@0 | 146 | * on comms error. |
philpem@1 | 147 | * @note Equivalent to a call to lpfk_set_leds_cached() followed by a call |
philpem@1 | 148 | * to lpfk_update_leds(). |
philpem@0 | 149 | */ |
philpem@0 | 150 | int lpfk_set_leds(LPFK_CTX *ctx, const int state); |
philpem@0 | 151 | |
philpem@0 | 152 | /** |
philpem@0 | 153 | * @brief Get the status of an LED on the LPFK. |
philpem@0 | 154 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@0 | 155 | * @param num LED/key number, from 0 to 31. |
philpem@0 | 156 | * @return true if LED is on, false otherwise. |
philpem@0 | 157 | */ |
philpem@0 | 158 | int lpfk_get_led(LPFK_CTX *ctx, const int num); |
philpem@0 | 159 | |
philpem@0 | 160 | /** |
philpem@0 | 161 | * @brief Read a key from the LPFK |
philpem@0 | 162 | * @param ctx Pointer to an LPFK_CTX struct initialised by lpfk_open(). |
philpem@4 | 163 | * @return LPFK_E_NO_KEYS if no keys in buffer, 0-31 for key 1-32 down. |
philpem@0 | 164 | */ |
philpem@0 | 165 | int lpfk_read(LPFK_CTX *ctx); |
philpem@0 | 166 | |
philpem@0 | 167 | #endif // _liblpfk_h_included |