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[out] 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: %s.",
 108                         jaylink_strerror(ret));
 109                 return ret;
 110         }
 111
 112         buf[0] = CMD_EMUCOM;
 113         buf[1] = EMUCOM_CMD_READ;
 114
 115         buffer_set_u32(buf, channel, 2);
 116         buffer_set_u32(buf, *length, 6);
 117
 118         ret = transport_write(devh, buf, 10);
 119
 120         if (ret != JAYLINK_OK) {
 121                 log_err(ctx, "transport_write() failed: %s.",
 122                         jaylink_strerror(ret));
 123                 return ret;
 124         }
 125
 126         ret = transport_read(devh, buf, 4);
 127
 128         if (ret != JAYLINK_OK) {
 129                 log_err(ctx, "transport_read() failed: %s.",
 130                         jaylink_strerror(ret));
 131                 return ret;
 132         }
 133
 134         tmp = buffer_get_u32(buf, 0);
 135
 136         if (tmp == EMUCOM_ERR_NOT_SUPPORTED)
 137                 return JAYLINK_ERR_DEV_NOT_SUPPORTED;
 138
 139         if ((tmp & ~EMUCOM_AVAILABLE_BYTES_MASK) == EMUCOM_ERR_NOT_AVAILABLE) {
 140                 *length = tmp & EMUCOM_AVAILABLE_BYTES_MASK;
 141                 return JAYLINK_ERR_DEV_NOT_AVAILABLE;
 142         }
 143
 144         if (tmp & EMUCOM_ERR) {
 145                 log_err(ctx, "Failed to read from channel 0x%x.", channel);
 146                 return JAYLINK_ERR_DEV;
 147         }
 148
 149         if (tmp > *length) {
 150                 log_err(ctx, "Requested at most %u bytes but device "
 151                         "returned %u bytes.", *length, tmp);
 152                 return JAYLINK_ERR_PROTO;
 153         }
 154
 155         *length = tmp;
 156
 157         if (!tmp)
 158                 return JAYLINK_OK;
 159
 160         ret = transport_start_read(devh, tmp);
 161
 162         if (ret != JAYLINK_OK) {
 163                 log_err(ctx, "transport_start_read() failed: %s.",
 164                         jaylink_strerror(ret));
 165                 return ret;
 166         }
 167
 168         ret = transport_read(devh, buffer, tmp);
 169
 170         if (ret != JAYLINK_OK) {
 171                 log_err(ctx, "transport_read() failed: %s.",
 172                         jaylink_strerror(ret));
 173                 return ret;
 174         }
 175
 176         return JAYLINK_OK;
 177 }
 178
 179 /**
 180  * Write to an EMUCOM channel.
 181  *
 182  * @note This function must only be used if the device has the
 183  *       #JAYLINK_DEV_CAP_EMUCOM capability.
 184  *
 185  * @param[in,out] devh Device handle.
 186  * @param[in] channel Channel to write data to.
 187  * @param[in] buffer Buffer to write data from.
 188  * @param[in,out] length Number of bytes to write. On success, the value gets
 189  *                       updated with the actual number of bytes written. The
 190  *                       value is undefined on failure.
 191  *
 192  * @retval JAYLINK_OK Success.
 193  * @retval JAYLINK_ERR_ARG Invalid arguments.
 194  * @retval JAYLINK_ERR_TIMEOUT A timeout occurred.
 195  * @retval JAYLINK_ERR_PROTO Protocol violation.
 196  * @retval JAYLINK_ERR_DEV Unspecified device error.
 197  * @retval JAYLINK_ERR_DEV_NOT_SUPPORTED Channel is not supported by the
 198  *                                       device.
 199  * @retval JAYLINK_ERR Other error conditions.
 200  *
 201  * @since 0.1.0
 202  */
 203 JAYLINK_API int jaylink_emucom_write(struct jaylink_device_handle *devh,
 204                 uint32_t channel, const uint8_t *buffer, uint32_t *length)
 205 {
 206         int ret;
 207         struct jaylink_context *ctx;
 208         uint8_t buf[10];
 209         uint32_t tmp;
 210
 211         if (!devh || !buffer || !length)
 212                 return JAYLINK_ERR_ARG;
 213
 214         if (!*length)
 215                 return JAYLINK_ERR_ARG;
 216
 217         ctx = devh->dev->ctx;
 218         ret = transport_start_write(devh, 10, true);
 219
 220         if (ret != JAYLINK_OK) {
 221                 log_err(ctx, "transport_start_write() failed: %s.",
 222                         jaylink_strerror(ret));
 223                 return ret;
 224         }
 225
 226         buf[0] = CMD_EMUCOM;
 227         buf[1] = EMUCOM_CMD_WRITE;
 228
 229         buffer_set_u32(buf, channel, 2);
 230         buffer_set_u32(buf, *length, 6);
 231
 232         ret = transport_write(devh, buf, 10);
 233
 234         if (ret != JAYLINK_OK) {
 235                 log_err(ctx, "transport_write() failed: %s.",
 236                         jaylink_strerror(ret));
 237                 return ret;
 238         }
 239
 240         ret = transport_start_write_read(devh, *length, 4, false);
 241
 242         if (ret != JAYLINK_OK) {
 243                 log_err(ctx, "transport_start_write_read() failed: %s.",
 244                         jaylink_strerror(ret));
 245                 return ret;
 246         }
 247
 248         ret = transport_write(devh, buffer, *length);
 249
 250         if (ret != JAYLINK_OK) {
 251                 log_err(ctx, "transport_write() failed: %s.",
 252                         jaylink_strerror(ret));
 253                 return ret;
 254         }
 255
 256         ret = transport_read(devh, buf, 4);
 257
 258         if (ret != JAYLINK_OK) {
 259                 log_err(ctx, "transport_read() failed: %s.",
 260                         jaylink_strerror(ret));
 261                 return ret;
 262         }
 263
 264         tmp = buffer_get_u32(buf, 0);
 265
 266         if (tmp == EMUCOM_ERR_NOT_SUPPORTED)
 267                 return JAYLINK_ERR_DEV_NOT_SUPPORTED;
 268
 269         if (tmp & EMUCOM_ERR) {
 270                 log_err(ctx, "Failed to write to channel 0x%x.", channel);
 271                 return JAYLINK_ERR_DEV;
 272         }
 273
 274         if (tmp > *length) {
 275                 log_err(ctx, "Only %u bytes were supposed to be written, but "
 276                         "the device reported %u written bytes.", *length, tmp);
 277                 return JAYLINK_ERR_PROTO;
 278         }
 279
 280         *length = tmp;
 281
 282         return JAYLINK_OK;
 283 }