libjaylink/emucom.c

   1 /*
   2  * This file is part of the libjaylink project.
   3  *
   4  * Copyright (C) 2015-2016 Marc Schink <jaylink-dev@marcschink.de>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include <stdint.h>
  21 #include <stdbool.h>
  22
  23 #include "libjaylink.h"
  24 #include "libjaylink-internal.h"
  25
  26 /**
  27  * @file
  28  *
  29  * Emulator communication (EMUCOM).
  30  */
  31
  32 /** @cond PRIVATE */
  33 #define CMD_EMUCOM                      0xee
  34
  35 #define EMUCOM_CMD_READ                 0x00
  36 #define EMUCOM_CMD_WRITE                0x01
  37
  38 /** Bitmask for the error indication bit of an EMUCOM status code. */
  39 #define EMUCOM_ERR                      0x80000000
  40
  41 /** Error code indicating that the channel is not supported by the device. */
  42 #define EMUCOM_ERR_NOT_SUPPORTED        0x80000001
  43
  44 /**
  45  * Error code indicating that the channel is not available for the requested
  46  * number of bytes to be read.
  47  *
  48  * The number of bytes available on this channel is encoded in the lower
  49  * 24 bits of the EMUCOM status code.
  50  *
  51  * @see EMUCOM_AVAILABLE_BYTES_MASK
  52  */
  53 #define EMUCOM_ERR_NOT_AVAILABLE        0x81000000
  54
  55 /**
  56  * Bitmask to extract the number of available bytes on a channel from an EMUCOM
  57  * status code.
  58  */
  59 #define EMUCOM_AVAILABLE_BYTES_MASK     0x00ffffff
  60 /** @endcond */
  61
  62 /**
  63  * Read from an EMUCOM channel.
  64  *
  65  * @note This function must only be used if the device has the
  66  *       #JAYLINK_DEV_CAP_EMUCOM capability.
  67  *
  68  * @param[in,out] devh Device handle.
  69  * @param[in] channel Channel to read data from.
  70  * @param[in] buffer Buffer to store read data on success. Its content is
  71  *                   undefined on failure.
  72  * @param[in,out] length Number of bytes to read. On success, the value gets
  73  *                       updated with the actual number of bytes read. Unless
  74  *                       otherwise specified, the value is undefined on
  75  *                       failure.
  76  *
  77  * @retval JAYLINK_OK Success.
  78  * @retval JAYLINK_ERR_ARG Invalid arguments.
  79  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
  80  * @retval JAYLINK_ERR_PROTO Protocol violation.
  81  * @retval JAYLINK_ERR_DEV Unspecified device error.
  82  * @retval JAYLINK_ERR_DEV_NOT_SUPPORTED Channel is not supported by the
  83  *                                       device.
  84  * @retval JAYLINK_ERR_DEV_NOT_AVAILABLE Channel is not available for the
  85  *                                       requested amount of data. @p length is
  86  *                                       updated with the number of bytes
  87  *                                       available on this channel.
  88  * @retval JAYLINK_ERR Other error conditions.
  89  *
  90  * @since 0.1.0
  91  */
  92 JAYLINK_API int jaylink_emucom_read(struct jaylink_device_handle *devh,
  93                 uint32_t channel, uint8_t *buffer, uint32_t *length)
  94 {
  95         int ret;
  96         struct jaylink_context *ctx;
  97         uint8_t buf[10];
  98         uint32_t tmp;
  99
 100         if (!devh || !buffer || !length)
 101                 return JAYLINK_ERR_ARG;
 102
 103         ctx = devh->dev->ctx;
 104         ret = transport_start_write_read(devh, 10, 4, true);
 105
 106         if (ret != JAYLINK_OK) {
 107                 log_err(ctx, "transport_start_write_read() failed: %i.", ret);
 108                 return ret;
 109         }
 110
 111         buf[0] = CMD_EMUCOM;
 112         buf[1] = EMUCOM_CMD_READ;
 113
 114         buffer_set_u32(buf, channel, 2);
 115         buffer_set_u32(buf, *length, 6);
 116
 117         ret = transport_write(devh, buf, 10);
 118
 119         if (ret != JAYLINK_OK) {
 120                 log_err(ctx, "transport_write() failed: %i.", ret);
 121                 return ret;
 122         }
 123
 124         ret = transport_read(devh, buf, 4);
 125
 126         if (ret != JAYLINK_OK) {
 127                 log_err(ctx, "transport_read() failed: %i.", ret);
 128                 return ret;
 129         }
 130
 131         tmp = buffer_get_u32(buf, 0);
 132
 133         if (tmp == EMUCOM_ERR_NOT_SUPPORTED)
 134                 return JAYLINK_ERR_DEV_NOT_SUPPORTED;
 135
 136         if ((tmp & ~EMUCOM_AVAILABLE_BYTES_MASK) == EMUCOM_ERR_NOT_AVAILABLE) {
 137                 *length = tmp & EMUCOM_AVAILABLE_BYTES_MASK;
 138                 return JAYLINK_ERR_DEV_NOT_AVAILABLE;
 139         }
 140
 141         if (tmp & EMUCOM_ERR) {
 142                 log_err(ctx, "Failed to read from channel 0x%x.", channel);
 143                 return JAYLINK_ERR_DEV;
 144         }
 145
 146         if (tmp > *length) {
 147                 log_err(ctx, "Requested at most %u bytes but device "
 148                         "returned %u bytes.", *length, tmp);
 149                 return JAYLINK_ERR_PROTO;
 150         }
 151
 152         *length = tmp;
 153
 154         if (!tmp)
 155                 return JAYLINK_OK;
 156
 157         ret = transport_start_read(devh, tmp);
 158
 159         if (ret != JAYLINK_OK) {
 160                 log_err(ctx, "transport_start_read() failed: %i.", ret);
 161                 return ret;
 162         }
 163
 164         ret = transport_read(devh, buffer, tmp);
 165
 166         if (ret != JAYLINK_OK) {
 167                 log_err(ctx, "transport_read() failed: %i.", ret);
 168                 return ret;
 169         }
 170
 171         return JAYLINK_OK;
 172 }
 173
 174 /**
 175  * Write to an EMUCOM channel.
 176  *
 177  * @note This function must only be used if the device has the
 178  *       #JAYLINK_DEV_CAP_EMUCOM capability.
 179  *
 180  * @param[in,out] devh Device handle.
 181  * @param[in] channel Channel to write data to.
 182  * @param[in] buffer Buffer to write data from.
 183  * @param[in,out] length Number of bytes to write. On success, the value gets
 184  *                       updated with the actual number of bytes written. The
 185  *                       value is undefined on failure.
 186  *
 187  * @retval JAYLINK_OK Success.
 188  * @retval JAYLINK_ERR_ARG Invalid arguments.
 189  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 190  * @retval JAYLINK_ERR_PROTO Protocol violation.
 191  * @retval JAYLINK_ERR_DEV Unspecified device error.
 192  * @retval JAYLINK_ERR_DEV_NOT_SUPPORTED Channel is not supported by the device.
 193  * @retval JAYLINK_ERR Other error conditions.
 194  *
 195  * @since 0.1.0
 196  */
 197 JAYLINK_API int jaylink_emucom_write(struct jaylink_device_handle *devh,
 198                 uint32_t channel, const uint8_t *buffer, uint32_t *length)
 199 {
 200         int ret;
 201         struct jaylink_context *ctx;
 202         uint8_t buf[10];
 203         uint32_t tmp;
 204
 205         if (!devh || !buffer || !length)
 206                 return JAYLINK_ERR_ARG;
 207
 208         if (!*length)
 209                 return JAYLINK_ERR_ARG;
 210
 211         ctx = devh->dev->ctx;
 212         ret = transport_start_write(devh, 10, true);
 213
 214         if (ret != JAYLINK_OK) {
 215                 log_err(ctx, "transport_start_write() failed: %i.", ret);
 216                 return ret;
 217         }
 218
 219         buf[0] = CMD_EMUCOM;
 220         buf[1] = EMUCOM_CMD_WRITE;
 221
 222         buffer_set_u32(buf, channel, 2);
 223         buffer_set_u32(buf, *length, 6);
 224
 225         ret = transport_write(devh, buf, 10);
 226
 227         if (ret != JAYLINK_OK) {
 228                 log_err(ctx, "transport_write() failed: %i.", ret);
 229                 return ret;
 230         }
 231
 232         ret = transport_start_write_read(devh, *length, 4, false);
 233
 234         if (ret != JAYLINK_OK) {
 235                 log_err(ctx, "transport_start_write_read() failed: %i.", ret);
 236                 return ret;
 237         }
 238
 239         ret = transport_write(devh, buffer, *length);
 240
 241         if (ret != JAYLINK_OK) {
 242                 log_err(ctx, "transport_write() failed: %i.", ret);
 243                 return ret;
 244         }
 245
 246         ret = transport_read(devh, buf, 4);
 247
 248         if (ret != JAYLINK_OK) {
 249                 log_err(ctx, "transport_read() failed: %i.", ret);
 250                 return ret;
 251         }
 252
 253         tmp = buffer_get_u32(buf, 0);
 254
 255         if (tmp == EMUCOM_ERR_NOT_SUPPORTED)
 256                 return JAYLINK_ERR_DEV_NOT_SUPPORTED;
 257
 258         if (tmp & EMUCOM_ERR) {
 259                 log_err(ctx, "Failed to write to channel 0x%x.", channel);
 260                 return JAYLINK_ERR_DEV;
 261         }
 262
 263         if (tmp > *length) {
 264                 log_err(ctx, "Only %u bytes were supposed to be written, but "
 265                         "the device reported %u written bytes.", *length, tmp);
 266                 return JAYLINK_ERR_PROTO;
 267         }
 268
 269         *length = tmp;
 270
 271         return JAYLINK_OK;
 272 }