3 | *
4 | * This library is free software; you can redistribute it and/or
5 | * modify it under the terms of the GNU Lesser General Public
6 | * License as published by the Free Software Foundation; either
7 | * version 2.1 of the License, or (at your option) any later version.
8 | *
9 | * This library is distributed in the hope that it will be useful,
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 | * Lesser General Public License for more details.
13 | *
14 | * You should have received a copy of the GNU Lesser General Public
15 | * License along with this library; if not, write to the Free Software
16 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
17 | * USA.
18 | *
19 | * Project home page: https://github.com/mik3y/usb-serial-for-android
20 | */
21 |
22 | package com.hoho.android.usbserial.driver;
23 |
24 | import android.hardware.usb.UsbConstants;
25 | import android.hardware.usb.UsbDevice;
26 | import android.hardware.usb.UsbDeviceConnection;
27 | import android.hardware.usb.UsbEndpoint;
28 | import android.hardware.usb.UsbRequest;
29 | import android.util.Log;
30 |
31 | import java.io.IOException;
32 | import java.nio.ByteBuffer;
33 | import java.util.ArrayList;
34 | import java.util.LinkedHashMap;
35 | import java.util.List;
36 | import java.util.Map;
37 |
38 | /**
39 | * A {@link CommonUsbSerialPort} implementation for a variety of FTDI devices
40 | *
41 | * This driver is based on libftdi, and is
43 | * copyright and subject to the following terms:
44 | *
45 | *
46 | * Copyright (C) 2003 by Intra2net AG
47 | *
48 | * This program is free software; you can redistribute it and/or modify
49 | * it under the terms of the GNU Lesser General Public License
50 | * version 2.1 as published by the Free Software Foundation;
51 | *
52 | * opensource@intra2net.com
53 | * http://www.intra2net.com/en/developer/libftdi
54 | *
55 | *
56 | *
57 | *
58 | * Some FTDI devices have not been tested; see later listing of supported and
59 | * unsupported devices. Devices listed as "supported" support the following
60 | * features:
61 | *
62 | * - Read and write of serial data (see
63 | * {@link CommonUsbSerialPort#read(byte[], int)} and
64 | * {@link CommonUsbSerialPort#write(byte[], int)}.
65 | * - Setting serial line parameters (see
66 | * {@link CommonUsbSerialPort#setParameters(int, int, int, int)}.
67 | *
68 | *
69 | *
70 | * Supported and tested devices:
71 | *
72 | * - {@value DeviceType#TYPE_R}
73 | * - {@value DeviceType#TYPE_2232H}
74 | * - {@value DeviceType#TYPE_4232H}
75 | *
76 | *
77 | *
78 | * Unsupported but possibly working devices (please contact the author with
79 | * feedback or patches):
80 | *
81 | * - {@value DeviceType#TYPE_2232C}
82 | * - {@value DeviceType#TYPE_AM}
83 | * - {@value DeviceType#TYPE_BM}
84 | *
85 | *
86 | *
87 | * @author mike wakerly (opensource@hoho.com)
88 | * @see USB Serial
89 | * for Android project page
90 | * @see FTDI Homepage
91 | * @see libftdi
92 | */
93 | public class FtdiSerialDriver implements UsbSerialDriver {
94 |
95 | private final UsbDevice mDevice;
96 | private final List mPorts;
97 |
98 | /**
99 | * FTDI chip types.
100 | */
101 | private static enum DeviceType {
102 | TYPE_BM, TYPE_AM, TYPE_2232C, TYPE_R, TYPE_2232H, TYPE_4232H;
103 | }
104 |
105 | public FtdiSerialDriver(UsbDevice device) {
106 | mDevice = device;
107 | mPorts = new ArrayList<>();
108 | for( int port = 0; port < device.getInterfaceCount(); port++) {
109 | mPorts.add(new FtdiSerialPort(mDevice, port));
110 | }
111 | }
112 |
113 | @Override
114 | public UsbDevice getDevice() {
115 | return mDevice;
116 | }
117 |
118 | @Override
119 | public List getPorts() {
120 | return mPorts;
121 | }
122 |
123 | private class FtdiSerialPort extends CommonUsbSerialPort {
124 |
125 | public static final int USB_TYPE_STANDARD = 0x00 << 5;
126 | public static final int USB_TYPE_CLASS = 0x00 << 5;
127 | public static final int USB_TYPE_VENDOR = 0x00 << 5;
128 | public static final int USB_TYPE_RESERVED = 0x00 << 5;
129 |
130 | public static final int USB_RECIP_DEVICE = 0x00;
131 | public static final int USB_RECIP_INTERFACE = 0x01;
132 | public static final int USB_RECIP_ENDPOINT = 0x02;
133 | public static final int USB_RECIP_OTHER = 0x03;
134 |
135 | public static final int USB_ENDPOINT_IN = 0x80;
136 | public static final int USB_ENDPOINT_OUT = 0x00;
137 |
138 | public static final int USB_WRITE_TIMEOUT_MILLIS = 5000;
139 | public static final int USB_READ_TIMEOUT_MILLIS = 5000;
140 |
141 | // From ftdi.h
142 | /**
143 | * Reset the port.
144 | */
145 | private static final int SIO_RESET_REQUEST = 0;
146 |
147 | /**
148 | * Set the modem control register.
149 | */
150 | private static final int SIO_MODEM_CTRL_REQUEST = 1;
151 |
152 | /**
153 | * Set flow control register.
154 | */
155 | private static final int SIO_SET_FLOW_CTRL_REQUEST = 2;
156 |
157 | /**
158 | * Set baud rate.
159 | */
160 | private static final int SIO_SET_BAUD_RATE_REQUEST = 3;
161 |
162 | /**
163 | * Set the data characteristics of the port.
164 | */
165 | private static final int SIO_SET_DATA_REQUEST = 4;
166 |
167 | private static final int SIO_RESET_SIO = 0;
168 | private static final int SIO_RESET_PURGE_RX = 1;
169 | private static final int SIO_RESET_PURGE_TX = 2;
170 |
171 | public static final int FTDI_DEVICE_OUT_REQTYPE =
172 | UsbConstants.USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_OUT;
173 |
174 | public static final int FTDI_DEVICE_IN_REQTYPE =
175 | UsbConstants.USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN;
176 |
177 | /**
178 | * Length of the modem status header, transmitted with every read.
179 | */
180 | private static final int MODEM_STATUS_HEADER_LENGTH = 2;
181 |
182 | private final String TAG = FtdiSerialDriver.class.getSimpleName();
183 |
184 | private DeviceType mType;
185 |
186 | private int mIndex = 0;
187 |
188 | public FtdiSerialPort(UsbDevice device, int portNumber) {
189 | super(device, portNumber);
190 | }
191 |
192 | @Override
193 | public UsbSerialDriver getDriver() {
194 | return FtdiSerialDriver.this;
195 | }
196 |
197 | /**
198 | * Filter FTDI status bytes from buffer
199 | * @param src The source buffer (which contains status bytes)
200 | * @param dest The destination buffer to write the status bytes into (can be src)
201 | * @param totalBytesRead Number of bytes read to src
202 | * @param maxPacketSize The USB endpoint max packet size
203 | * @return The number of payload bytes
204 | */
205 | private final int filterStatusBytes(byte[] src, byte[] dest, int totalBytesRead, int maxPacketSize) {
206 | final int packetsCount = (totalBytesRead + maxPacketSize -1 )/ maxPacketSize;
207 | for (int packetIdx = 0; packetIdx < packetsCount; ++packetIdx) {
208 | final int count = (packetIdx == (packetsCount - 1))
209 | ? totalBytesRead - packetIdx * maxPacketSize - MODEM_STATUS_HEADER_LENGTH
210 | : maxPacketSize - MODEM_STATUS_HEADER_LENGTH;
211 | if (count > 0) {
212 | System.arraycopy(src,
213 | packetIdx * maxPacketSize + MODEM_STATUS_HEADER_LENGTH,
214 | dest,
215 | packetIdx * (maxPacketSize - MODEM_STATUS_HEADER_LENGTH),
216 | count);
217 | }
218 | }
219 |
220 | return totalBytesRead - (packetsCount * 2);
221 | }
222 |
223 | public void reset() throws IOException {
224 | // TODO(mikey): autodetect.
225 | mType = DeviceType.TYPE_R;
226 | if(mDevice.getInterfaceCount() > 1) {
227 | mIndex = mPortNumber + 1;
228 | if (mDevice.getInterfaceCount() == 2)
229 | mType = DeviceType.TYPE_2232H;
230 | if (mDevice.getInterfaceCount() == 4)
231 | mType = DeviceType.TYPE_4232H;
232 | }
233 |
234 | int result = mConnection.controlTransfer(FTDI_DEVICE_OUT_REQTYPE, SIO_RESET_REQUEST,
235 | SIO_RESET_SIO, mIndex, null, 0, USB_WRITE_TIMEOUT_MILLIS);
236 | if (result != 0) {
237 | throw new IOException("Reset failed: result=" + result);
238 | }
239 | }
240 |
241 | @Override
242 | public void open(UsbDeviceConnection connection) throws IOException {
243 | if (mConnection != null) {
244 | throw new IOException("Already open");
245 | }
246 | mConnection = connection;
247 |
248 | boolean opened = false;
249 | try {
250 | if (connection.claimInterface(mDevice.getInterface(mPortNumber), true)) {
251 | Log.d(TAG, "claimInterface " + mPortNumber + " SUCCESS");
252 | } else {
253 | throw new IOException("Error claiming interface " + mPortNumber);
254 | }
255 | reset();
256 | opened = true;
257 | } finally {
258 | if (!opened) {
259 | close();
260 | mConnection = null;
261 | }
262 | }
263 | }
264 |
265 | @Override
266 | public void close() throws IOException {
267 | if (mConnection == null) {
268 | throw new IOException("Already closed");
269 | }
270 | try {
271 | mConnection.close();
272 | } finally {
273 | mConnection = null;
274 | }
275 | }
276 |
277 | @Override
278 | public int read(byte[] dest, int timeoutMillis) throws IOException {
279 | final UsbEndpoint endpoint = mDevice.getInterface(mPortNumber).getEndpoint(0);
280 | final UsbRequest request = new UsbRequest();
281 | final ByteBuffer buf = ByteBuffer.wrap(dest);
282 | try {
283 | request.initialize(mConnection, endpoint);
284 | if (!request.queue(buf, dest.length)) {
285 | throw new IOException("Error queueing request.");
286 | }
287 |
288 | final UsbRequest response = mConnection.requestWait();
289 | if (response == null) {
290 | throw new IOException("Null response");
291 | }
292 | } finally {
293 | request.close();
294 | }
295 |
296 | final int totalBytesRead = buf.position();
297 | if (totalBytesRead < MODEM_STATUS_HEADER_LENGTH) {
298 | throw new IOException("Expected at least " + MODEM_STATUS_HEADER_LENGTH + " bytes");
299 | }
300 |
301 | return filterStatusBytes(dest, dest, totalBytesRead, endpoint.getMaxPacketSize());
302 | }
303 |
304 | @Override
305 | public int write(byte[] src, int timeoutMillis) throws IOException {
306 | final UsbEndpoint endpoint = mDevice.getInterface(mPortNumber).getEndpoint(1);
307 | int offset = 0;
308 |
309 | while (offset < src.length) {
310 | final int writeLength;
311 | final int amtWritten;
312 |
313 | synchronized (mWriteBufferLock) {
314 | final byte[] writeBuffer;
315 |
316 | writeLength = Math.min(src.length - offset, mWriteBuffer.length);
317 | if (offset == 0) {
318 | writeBuffer = src;
319 | } else {
320 | // bulkTransfer does not support offsets, make a copy.
321 | System.arraycopy(src, offset, mWriteBuffer, 0, writeLength);
322 | writeBuffer = mWriteBuffer;
323 | }
324 |
325 | amtWritten = mConnection.bulkTransfer(endpoint, writeBuffer, writeLength,
326 | timeoutMillis);
327 | }
328 |
329 | if (amtWritten <= 0) {
330 | throw new IOException("Error writing " + writeLength
331 | + " bytes at offset " + offset + " length=" + src.length);
332 | }
333 |
334 | Log.d(TAG, "Wrote amtWritten=" + amtWritten + " attempted=" + writeLength);
335 | offset += amtWritten;
336 | }
337 | return offset;
338 | }
339 |
340 | private int setBaudRate(int baudRate) throws IOException {
341 | long[] vals = convertBaudrate(baudRate);
342 | long actualBaudrate = vals[0];
343 | long index = vals[1];
344 | long value = vals[2];
345 | int result = mConnection.controlTransfer(FTDI_DEVICE_OUT_REQTYPE,
346 | SIO_SET_BAUD_RATE_REQUEST, (int) value, (int) index,
347 | null, 0, USB_WRITE_TIMEOUT_MILLIS);
348 | if (result != 0) {
349 | throw new IOException("Setting baudrate failed: result=" + result);
350 | }
351 | return (int) actualBaudrate;
352 | }
353 |
354 | @Override
355 | public void setParameters(int baudRate, int dataBits, int stopBits, int parity)
356 | throws IOException {
357 | setBaudRate(baudRate);
358 |
359 | int config = 0;
360 | switch (dataBits) {
361 | case DATABITS_5:
362 | case DATABITS_6:
363 | throw new IllegalArgumentException("Unsupported dataBits value: " + dataBits);
364 | case DATABITS_7:
365 | case DATABITS_8:
366 | config |= dataBits;
367 | break;
368 | default:
369 | throw new IllegalArgumentException("Unknown dataBits value: " + dataBits);
370 | }
371 |
372 | switch (parity) {
373 | case PARITY_NONE:
374 | config |= (0x00 << 8);
375 | break;
376 | case PARITY_ODD:
377 | config |= (0x01 << 8);
378 | break;
379 | case PARITY_EVEN:
380 | config |= (0x02 << 8);
381 | break;
382 | case PARITY_MARK:
383 | config |= (0x03 << 8);
384 | break;
385 | case PARITY_SPACE:
386 | config |= (0x04 << 8);
387 | break;
388 | default:
389 | throw new IllegalArgumentException("Unknown parity value: " + parity);
390 | }
391 |
392 | switch (stopBits) {
393 | case STOPBITS_1:
394 | config |= (0x00 << 11);
395 | break;
396 | case STOPBITS_1_5:
397 | throw new IllegalArgumentException("Unsupported stopBits value: 1.5");
398 | case STOPBITS_2:
399 | config |= (0x02 << 11);
400 | break;
401 | default:
402 | throw new IllegalArgumentException("Unknown stopBits value: " + stopBits);
403 | }
404 |
405 | int result = mConnection.controlTransfer(FTDI_DEVICE_OUT_REQTYPE,
406 | SIO_SET_DATA_REQUEST, config, mIndex,
407 | null, 0, USB_WRITE_TIMEOUT_MILLIS);
408 | if (result != 0) {
409 | throw new IOException("Setting parameters failed: result=" + result);
410 | }
411 | }
412 |
413 | private long[] convertBaudrate(int baudrate) {
414 | // TODO(mikey): Braindead transcription of libfti method. Clean up,
415 | // using more idiomatic Java where possible.
416 | int divisor = 24000000 / baudrate;
417 | int bestDivisor = 0;
418 | int bestBaud = 0;
419 | int bestBaudDiff = 0;
420 | int fracCode[] = {
421 | 0, 3, 2, 4, 1, 5, 6, 7
422 | };
423 |
424 | for (int i = 0; i < 2; i++) {
425 | int tryDivisor = divisor + i;
426 | int baudEstimate;
427 | int baudDiff;
428 |
429 | if (tryDivisor <= 8) {
430 | // Round up to minimum supported divisor
431 | tryDivisor = 8;
432 | } else if (mType != DeviceType.TYPE_AM && tryDivisor < 12) {
433 | // BM doesn't support divisors 9 through 11 inclusive
434 | tryDivisor = 12;
435 | } else if (divisor < 16) {
436 | // AM doesn't support divisors 9 through 15 inclusive
437 | tryDivisor = 16;
438 | } else {
439 | if (mType == DeviceType.TYPE_AM) {
440 | // TODO
441 | } else {
442 | if (tryDivisor > 0x1FFFF) {
443 | // Round down to maximum supported divisor value (for
444 | // BM)
445 | tryDivisor = 0x1FFFF;
446 | }
447 | }
448 | }
449 |
450 | // Get estimated baud rate (to nearest integer)
451 | baudEstimate = (24000000 + (tryDivisor / 2)) / tryDivisor;
452 |
453 | // Get absolute difference from requested baud rate
454 | if (baudEstimate < baudrate) {
455 | baudDiff = baudrate - baudEstimate;
456 | } else {
457 | baudDiff = baudEstimate - baudrate;
458 | }
459 |
460 | if (i == 0 || baudDiff < bestBaudDiff) {
461 | // Closest to requested baud rate so far
462 | bestDivisor = tryDivisor;
463 | bestBaud = baudEstimate;
464 | bestBaudDiff = baudDiff;
465 | if (baudDiff == 0) {
466 | // Spot on! No point trying
467 | break;
468 | }
469 | }
470 | }
471 |
472 | // Encode the best divisor value
473 | long encodedDivisor = (bestDivisor >> 3) | (fracCode[bestDivisor & 7] << 14);
474 | // Deal with special cases for encoded value
475 | if (encodedDivisor == 1) {
476 | encodedDivisor = 0; // 3000000 baud
477 | } else if (encodedDivisor == 0x4001) {
478 | encodedDivisor = 1; // 2000000 baud (BM only)
479 | }
480 |
481 | // Split into "value" and "index" values
482 | long value = encodedDivisor & 0xFFFF;
483 | long index;
484 | if (mType == DeviceType.TYPE_2232C || mType == DeviceType.TYPE_2232H
485 | || mType == DeviceType.TYPE_4232H) {
486 | index = (encodedDivisor >> 8) & 0xff00;
487 | index |= mIndex;
488 | } else {
489 | index = (encodedDivisor >> 16) & 0xffff;
490 | }
491 |
492 | // Return the nearest baud rate
493 | return new long[] {
494 | bestBaud, index, value
495 | };
496 | }
497 |
498 | @Override
499 | public boolean getCD() throws IOException {
500 | return false;
501 | }
502 |
503 | @Override
504 | public boolean getCTS() throws IOException {
505 | return false;
506 | }
507 |
508 | @Override
509 | public boolean getDSR() throws IOException {
510 | return false;
511 | }
512 |
513 | @Override
514 | public boolean getDTR() throws IOException {
515 | return false;
516 | }
517 |
518 | @Override
519 | public void setDTR(boolean value) throws IOException {
520 | }
521 |
522 | @Override
523 | public boolean getRI() throws IOException {
524 | return false;
525 | }
526 |
527 | @Override
528 | public boolean getRTS() throws IOException {
529 | return false;
530 | }
531 |
532 | @Override
533 | public void setRTS(boolean value) throws IOException {
534 | }
535 |
536 | @Override
537 | public boolean purgeHwBuffers(boolean purgeReadBuffers, boolean purgeWriteBuffers) throws IOException {
538 | if (purgeReadBuffers) {
539 | int result = mConnection.controlTransfer(FTDI_DEVICE_OUT_REQTYPE, SIO_RESET_REQUEST,
540 | SIO_RESET_PURGE_RX, mIndex, null, 0, USB_WRITE_TIMEOUT_MILLIS);
541 | if (result != 0) {
542 | throw new IOException("Flushing RX failed: result=" + result);
543 | }
544 | }
545 |
546 | if (purgeWriteBuffers) {
547 | int result = mConnection.controlTransfer(FTDI_DEVICE_OUT_REQTYPE, SIO_RESET_REQUEST,
548 | SIO_RESET_PURGE_TX, mIndex, null, 0, USB_WRITE_TIMEOUT_MILLIS);
549 | if (result != 0) {
550 | throw new IOException("Flushing RX failed: result=" + result);
551 | }
552 | }
553 | return true;
554 | }
555 | }
556 |
557 | public static Map getSupportedDevices() {
558 | final Map supportedDevices = new LinkedHashMap();
559 | supportedDevices.put(Integer.valueOf(UsbId.VENDOR_FTDI),
560 | new int[] {
561 | UsbId.FTDI_FT232R,
562 | UsbId.FTDI_FT232H,
563 | UsbId.FTDI_FT2232H,
564 | UsbId.FTDI_FT4232H,
565 | UsbId.FTDI_FT231X,
566 | });
567 | return supportedDevices;
568 | }
569 |
570 | }
571 |
--------------------------------------------------------------------------------
/usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/ProlificSerialDriver.java:
--------------------------------------------------------------------------------
1 | /* This library is free software; you can redistribute it and/or
2 | * modify it under the terms of the GNU Lesser General Public
3 | * License as published by the Free Software Foundation; either
4 | * version 2.1 of the License, or (at your option) any later version.
5 | *
6 | * This library is distributed in the hope that it will be useful,
7 | * but WITHOUT ANY WARRANTY; without even the implied warranty of
8 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9 | * Lesser General Public License for more details.
10 | *
11 | * You should have received a copy of the GNU Lesser General Public
12 | * License along with this library; if not, write to the Free Software
13 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
14 | * USA.
15 | *
16 | * Project home page: https://github.com/mik3y/usb-serial-for-android
17 | */
18 |
19 | /*
20 | * Ported to usb-serial-for-android
21 | * by Felix Hädicke
22 | *
23 | * Based on the pyprolific driver written
24 | * by Emmanuel Blot
25 | * See https://github.com/eblot/pyftdi
26 | */
27 |
28 | package com.hoho.android.usbserial.driver;
29 |
30 | import android.hardware.usb.UsbConstants;
31 | import android.hardware.usb.UsbDevice;
32 | import android.hardware.usb.UsbDeviceConnection;
33 | import android.hardware.usb.UsbEndpoint;
34 | import android.hardware.usb.UsbInterface;
35 | import android.hardware.usb.UsbRequest;
36 | import android.util.Log;
37 |
38 | import java.io.IOException;
39 | import java.lang.reflect.Method;
40 | import java.nio.ByteBuffer;
41 | import java.util.Collections;
42 | import java.util.LinkedHashMap;
43 | import java.util.List;
44 | import java.util.Map;
45 |
46 | public class ProlificSerialDriver implements UsbSerialDriver {
47 |
48 | private final String TAG = ProlificSerialDriver.class.getSimpleName();
49 |
50 | private final UsbDevice mDevice;
51 | private final UsbSerialPort mPort;
52 |
53 | public ProlificSerialDriver(UsbDevice device) {
54 | mDevice = device;
55 | mPort = new ProlificSerialPort(mDevice, 0);
56 | }
57 |
58 | @Override
59 | public List getPorts() {
60 | return Collections.singletonList(mPort);
61 | }
62 |
63 | @Override
64 | public UsbDevice getDevice() {
65 | return mDevice;
66 | }
67 |
68 | class ProlificSerialPort extends CommonUsbSerialPort {
69 |
70 | private static final int USB_READ_TIMEOUT_MILLIS = 1000;
71 | private static final int USB_WRITE_TIMEOUT_MILLIS = 5000;
72 |
73 | private static final int USB_RECIP_INTERFACE = 0x01;
74 |
75 | private static final int PROLIFIC_VENDOR_READ_REQUEST = 0x01;
76 | private static final int PROLIFIC_VENDOR_WRITE_REQUEST = 0x01;
77 |
78 | private static final int PROLIFIC_VENDOR_OUT_REQTYPE = UsbConstants.USB_DIR_OUT
79 | | UsbConstants.USB_TYPE_VENDOR;
80 |
81 | private static final int PROLIFIC_VENDOR_IN_REQTYPE = UsbConstants.USB_DIR_IN
82 | | UsbConstants.USB_TYPE_VENDOR;
83 |
84 | private static final int PROLIFIC_CTRL_OUT_REQTYPE = UsbConstants.USB_DIR_OUT
85 | | UsbConstants.USB_TYPE_CLASS | USB_RECIP_INTERFACE;
86 |
87 | private static final int WRITE_ENDPOINT = 0x02;
88 | private static final int READ_ENDPOINT = 0x83;
89 | private static final int INTERRUPT_ENDPOINT = 0x81;
90 |
91 | private static final int FLUSH_RX_REQUEST = 0x08;
92 | private static final int FLUSH_TX_REQUEST = 0x09;
93 |
94 | private static final int SET_LINE_REQUEST = 0x20;
95 | private static final int SET_CONTROL_REQUEST = 0x22;
96 |
97 | private static final int CONTROL_DTR = 0x01;
98 | private static final int CONTROL_RTS = 0x02;
99 |
100 | private static final int STATUS_FLAG_CD = 0x01;
101 | private static final int STATUS_FLAG_DSR = 0x02;
102 | private static final int STATUS_FLAG_RI = 0x08;
103 | private static final int STATUS_FLAG_CTS = 0x80;
104 |
105 | private static final int STATUS_BUFFER_SIZE = 10;
106 | private static final int STATUS_BYTE_IDX = 8;
107 |
108 | private static final int DEVICE_TYPE_HX = 0;
109 | private static final int DEVICE_TYPE_0 = 1;
110 | private static final int DEVICE_TYPE_1 = 2;
111 |
112 | private int mDeviceType = DEVICE_TYPE_HX;
113 |
114 | private UsbEndpoint mReadEndpoint;
115 | private UsbEndpoint mWriteEndpoint;
116 | private UsbEndpoint mInterruptEndpoint;
117 |
118 | private int mControlLinesValue = 0;
119 |
120 | private int mBaudRate = -1, mDataBits = -1, mStopBits = -1, mParity = -1;
121 |
122 | private int mStatus = 0;
123 | private volatile Thread mReadStatusThread = null;
124 | private final Object mReadStatusThreadLock = new Object();
125 | boolean mStopReadStatusThread = false;
126 | private IOException mReadStatusException = null;
127 |
128 |
129 | public ProlificSerialPort(UsbDevice device, int portNumber) {
130 | super(device, portNumber);
131 | }
132 |
133 | @Override
134 | public UsbSerialDriver getDriver() {
135 | return ProlificSerialDriver.this;
136 | }
137 |
138 | private final byte[] inControlTransfer(int requestType, int request,
139 | int value, int index, int length) throws IOException {
140 | byte[] buffer = new byte[length];
141 | int result = mConnection.controlTransfer(requestType, request, value,
142 | index, buffer, length, USB_READ_TIMEOUT_MILLIS);
143 | if (result != length) {
144 | throw new IOException(
145 | String.format("ControlTransfer with value 0x%x failed: %d",
146 | value, result));
147 | }
148 | return buffer;
149 | }
150 |
151 | private final void outControlTransfer(int requestType, int request,
152 | int value, int index, byte[] data) throws IOException {
153 | int length = (data == null) ? 0 : data.length;
154 | int result = mConnection.controlTransfer(requestType, request, value,
155 | index, data, length, USB_WRITE_TIMEOUT_MILLIS);
156 | if (result != length) {
157 | throw new IOException(
158 | String.format("ControlTransfer with value 0x%x failed: %d",
159 | value, result));
160 | }
161 | }
162 |
163 | private final byte[] vendorIn(int value, int index, int length)
164 | throws IOException {
165 | return inControlTransfer(PROLIFIC_VENDOR_IN_REQTYPE,
166 | PROLIFIC_VENDOR_READ_REQUEST, value, index, length);
167 | }
168 |
169 | private final void vendorOut(int value, int index, byte[] data)
170 | throws IOException {
171 | outControlTransfer(PROLIFIC_VENDOR_OUT_REQTYPE,
172 | PROLIFIC_VENDOR_WRITE_REQUEST, value, index, data);
173 | }
174 |
175 | private void resetDevice() throws IOException {
176 | purgeHwBuffers(true, true);
177 | }
178 |
179 | private final void ctrlOut(int request, int value, int index, byte[] data)
180 | throws IOException {
181 | outControlTransfer(PROLIFIC_CTRL_OUT_REQTYPE, request, value, index,
182 | data);
183 | }
184 |
185 | private void doBlackMagic() throws IOException {
186 | vendorIn(0x8484, 0, 1);
187 | vendorOut(0x0404, 0, null);
188 | vendorIn(0x8484, 0, 1);
189 | vendorIn(0x8383, 0, 1);
190 | vendorIn(0x8484, 0, 1);
191 | vendorOut(0x0404, 1, null);
192 | vendorIn(0x8484, 0, 1);
193 | vendorIn(0x8383, 0, 1);
194 | vendorOut(0, 1, null);
195 | vendorOut(1, 0, null);
196 | vendorOut(2, (mDeviceType == DEVICE_TYPE_HX) ? 0x44 : 0x24, null);
197 | }
198 |
199 | private void setControlLines(int newControlLinesValue) throws IOException {
200 | ctrlOut(SET_CONTROL_REQUEST, newControlLinesValue, 0, null);
201 | mControlLinesValue = newControlLinesValue;
202 | }
203 |
204 | private final void readStatusThreadFunction() {
205 | try {
206 | while (!mStopReadStatusThread) {
207 | byte[] buffer = new byte[STATUS_BUFFER_SIZE];
208 | int readBytesCount = mConnection.bulkTransfer(mInterruptEndpoint,
209 | buffer,
210 | STATUS_BUFFER_SIZE,
211 | 500);
212 | if (readBytesCount > 0) {
213 | if (readBytesCount == STATUS_BUFFER_SIZE) {
214 | mStatus = buffer[STATUS_BYTE_IDX] & 0xff;
215 | } else {
216 | throw new IOException(
217 | String.format("Invalid CTS / DSR / CD / RI status buffer received, expected %d bytes, but received %d",
218 | STATUS_BUFFER_SIZE,
219 | readBytesCount));
220 | }
221 | }
222 | }
223 | } catch (IOException e) {
224 | mReadStatusException = e;
225 | }
226 | }
227 |
228 | private final int getStatus() throws IOException {
229 | if ((mReadStatusThread == null) && (mReadStatusException == null)) {
230 | synchronized (mReadStatusThreadLock) {
231 | if (mReadStatusThread == null) {
232 | byte[] buffer = new byte[STATUS_BUFFER_SIZE];
233 | int readBytes = mConnection.bulkTransfer(mInterruptEndpoint,
234 | buffer,
235 | STATUS_BUFFER_SIZE,
236 | 100);
237 | if (readBytes != STATUS_BUFFER_SIZE) {
238 | Log.w(TAG, "Could not read initial CTS / DSR / CD / RI status");
239 | } else {
240 | mStatus = buffer[STATUS_BYTE_IDX] & 0xff;
241 | }
242 |
243 | mReadStatusThread = new Thread(new Runnable() {
244 | @Override
245 | public void run() {
246 | readStatusThreadFunction();
247 | }
248 | });
249 | mReadStatusThread.setDaemon(true);
250 | mReadStatusThread.start();
251 | }
252 | }
253 | }
254 |
255 | /* throw and clear an exception which occured in the status read thread */
256 | IOException readStatusException = mReadStatusException;
257 | if (mReadStatusException != null) {
258 | mReadStatusException = null;
259 | throw readStatusException;
260 | }
261 |
262 | return mStatus;
263 | }
264 |
265 | private final boolean testStatusFlag(int flag) throws IOException {
266 | return ((getStatus() & flag) == flag);
267 | }
268 |
269 | @Override
270 | public void open(UsbDeviceConnection connection) throws IOException {
271 | if (mConnection != null) {
272 | throw new IOException("Already open");
273 | }
274 |
275 | UsbInterface usbInterface = mDevice.getInterface(0);
276 |
277 | if (!connection.claimInterface(usbInterface, true)) {
278 | throw new IOException("Error claiming Prolific interface 0");
279 | }
280 |
281 | mConnection = connection;
282 | boolean opened = false;
283 | try {
284 | for (int i = 0; i < usbInterface.getEndpointCount(); ++i) {
285 | UsbEndpoint currentEndpoint = usbInterface.getEndpoint(i);
286 |
287 | switch (currentEndpoint.getAddress()) {
288 | case READ_ENDPOINT:
289 | mReadEndpoint = currentEndpoint;
290 | break;
291 |
292 | case WRITE_ENDPOINT:
293 | mWriteEndpoint = currentEndpoint;
294 | break;
295 |
296 | case INTERRUPT_ENDPOINT:
297 | mInterruptEndpoint = currentEndpoint;
298 | break;
299 | }
300 | }
301 |
302 | if (mDevice.getDeviceClass() == 0x02) {
303 | mDeviceType = DEVICE_TYPE_0;
304 | } else {
305 | try {
306 | Method getRawDescriptorsMethod
307 | = mConnection.getClass().getMethod("getRawDescriptors");
308 | byte[] rawDescriptors
309 | = (byte[]) getRawDescriptorsMethod.invoke(mConnection);
310 | byte maxPacketSize0 = rawDescriptors[7];
311 | if (maxPacketSize0 == 64) {
312 | mDeviceType = DEVICE_TYPE_HX;
313 | } else if ((mDevice.getDeviceClass() == 0x00)
314 | || (mDevice.getDeviceClass() == 0xff)) {
315 | mDeviceType = DEVICE_TYPE_1;
316 | } else {
317 | Log.w(TAG, "Could not detect PL2303 subtype, "
318 | + "Assuming that it is a HX device");
319 | mDeviceType = DEVICE_TYPE_HX;
320 | }
321 | } catch (NoSuchMethodException e) {
322 | Log.w(TAG, "Method UsbDeviceConnection.getRawDescriptors, "
323 | + "required for PL2303 subtype detection, not "
324 | + "available! Assuming that it is a HX device");
325 | mDeviceType = DEVICE_TYPE_HX;
326 | } catch (Exception e) {
327 | Log.e(TAG, "An unexpected exception occured while trying "
328 | + "to detect PL2303 subtype", e);
329 | }
330 | }
331 |
332 | setControlLines(mControlLinesValue);
333 | resetDevice();
334 |
335 | doBlackMagic();
336 | opened = true;
337 | } finally {
338 | if (!opened) {
339 | mConnection = null;
340 | connection.releaseInterface(usbInterface);
341 | }
342 | }
343 | }
344 |
345 | @Override
346 | public void close() throws IOException {
347 | if (mConnection == null) {
348 | throw new IOException("Already closed");
349 | }
350 | try {
351 | mStopReadStatusThread = true;
352 | synchronized (mReadStatusThreadLock) {
353 | if (mReadStatusThread != null) {
354 | try {
355 | mReadStatusThread.join();
356 | } catch (Exception e) {
357 | Log.w(TAG, "An error occured while waiting for status read thread", e);
358 | }
359 | }
360 | }
361 | resetDevice();
362 | } finally {
363 | try {
364 | mConnection.releaseInterface(mDevice.getInterface(0));
365 | } finally {
366 | mConnection = null;
367 | }
368 | }
369 | }
370 |
371 | @Override
372 | public int read(byte[] dest, int timeoutMillis) throws IOException {
373 | final UsbRequest request = new UsbRequest();
374 | try {
375 | request.initialize(mConnection, mReadEndpoint);
376 | final ByteBuffer buf = ByteBuffer.wrap(dest);
377 | if (!request.queue(buf, dest.length)) {
378 | throw new IOException("Error queueing request.");
379 | }
380 |
381 | final UsbRequest response = mConnection.requestWait();
382 | if (response == null) {
383 | throw new IOException("Null response");
384 | }
385 |
386 | final int nread = buf.position();
387 | if (nread > 0) {
388 | //Log.d(TAG, HexDump.dumpHexString(dest, 0, Math.min(32, dest.length)));
389 | return nread;
390 | } else {
391 | return 0;
392 | }
393 | } finally {
394 | request.close();
395 | }
396 | }
397 |
398 | @Override
399 | public int write(byte[] src, int timeoutMillis) throws IOException {
400 | int offset = 0;
401 |
402 | while (offset < src.length) {
403 | final int writeLength;
404 | final int amtWritten;
405 |
406 | synchronized (mWriteBufferLock) {
407 | final byte[] writeBuffer;
408 |
409 | writeLength = Math.min(src.length - offset, mWriteBuffer.length);
410 | if (offset == 0) {
411 | writeBuffer = src;
412 | } else {
413 | // bulkTransfer does not support offsets, make a copy.
414 | System.arraycopy(src, offset, mWriteBuffer, 0, writeLength);
415 | writeBuffer = mWriteBuffer;
416 | }
417 |
418 | amtWritten = mConnection.bulkTransfer(mWriteEndpoint,
419 | writeBuffer, writeLength, timeoutMillis);
420 | }
421 |
422 | if (amtWritten <= 0) {
423 | throw new IOException("Error writing " + writeLength
424 | + " bytes at offset " + offset + " length="
425 | + src.length);
426 | }
427 |
428 | offset += amtWritten;
429 | }
430 | return offset;
431 | }
432 |
433 | @Override
434 | public void setParameters(int baudRate, int dataBits, int stopBits,
435 | int parity) throws IOException {
436 | if ((mBaudRate == baudRate) && (mDataBits == dataBits)
437 | && (mStopBits == stopBits) && (mParity == parity)) {
438 | // Make sure no action is performed if there is nothing to change
439 | return;
440 | }
441 |
442 | byte[] lineRequestData = new byte[7];
443 |
444 | lineRequestData[0] = (byte) (baudRate & 0xff);
445 | lineRequestData[1] = (byte) ((baudRate >> 8) & 0xff);
446 | lineRequestData[2] = (byte) ((baudRate >> 16) & 0xff);
447 | lineRequestData[3] = (byte) ((baudRate >> 24) & 0xff);
448 |
449 | switch (stopBits) {
450 | case STOPBITS_1:
451 | lineRequestData[4] = 0;
452 | break;
453 |
454 | case STOPBITS_1_5:
455 | lineRequestData[4] = 1;
456 | break;
457 |
458 | case STOPBITS_2:
459 | lineRequestData[4] = 2;
460 | break;
461 |
462 | default:
463 | throw new IllegalArgumentException("Unknown stopBits value: " + stopBits);
464 | }
465 |
466 | switch (parity) {
467 | case PARITY_NONE:
468 | lineRequestData[5] = 0;
469 | break;
470 |
471 | case PARITY_ODD:
472 | lineRequestData[5] = 1;
473 | break;
474 |
475 | case PARITY_EVEN:
476 | lineRequestData[5] = 2;
477 | break;
478 |
479 | case PARITY_MARK:
480 | lineRequestData[5] = 3;
481 | break;
482 |
483 | case PARITY_SPACE:
484 | lineRequestData[5] = 4;
485 | break;
486 |
487 | default:
488 | throw new IllegalArgumentException("Unknown parity value: " + parity);
489 | }
490 |
491 | lineRequestData[6] = (byte) dataBits;
492 |
493 | ctrlOut(SET_LINE_REQUEST, 0, 0, lineRequestData);
494 |
495 | resetDevice();
496 |
497 | mBaudRate = baudRate;
498 | mDataBits = dataBits;
499 | mStopBits = stopBits;
500 | mParity = parity;
501 | }
502 |
503 | @Override
504 | public boolean getCD() throws IOException {
505 | return testStatusFlag(STATUS_FLAG_CD);
506 | }
507 |
508 | @Override
509 | public boolean getCTS() throws IOException {
510 | return testStatusFlag(STATUS_FLAG_CTS);
511 | }
512 |
513 | @Override
514 | public boolean getDSR() throws IOException {
515 | return testStatusFlag(STATUS_FLAG_DSR);
516 | }
517 |
518 | @Override
519 | public boolean getDTR() throws IOException {
520 | return ((mControlLinesValue & CONTROL_DTR) == CONTROL_DTR);
521 | }
522 |
523 | @Override
524 | public void setDTR(boolean value) throws IOException {
525 | int newControlLinesValue;
526 | if (value) {
527 | newControlLinesValue = mControlLinesValue | CONTROL_DTR;
528 | } else {
529 | newControlLinesValue = mControlLinesValue & ~CONTROL_DTR;
530 | }
531 | setControlLines(newControlLinesValue);
532 | }
533 |
534 | @Override
535 | public boolean getRI() throws IOException {
536 | return testStatusFlag(STATUS_FLAG_RI);
537 | }
538 |
539 | @Override
540 | public boolean getRTS() throws IOException {
541 | return ((mControlLinesValue & CONTROL_RTS) == CONTROL_RTS);
542 | }
543 |
544 | @Override
545 | public void setRTS(boolean value) throws IOException {
546 | int newControlLinesValue;
547 | if (value) {
548 | newControlLinesValue = mControlLinesValue | CONTROL_RTS;
549 | } else {
550 | newControlLinesValue = mControlLinesValue & ~CONTROL_RTS;
551 | }
552 | setControlLines(newControlLinesValue);
553 | }
554 |
555 | @Override
556 | public boolean purgeHwBuffers(boolean purgeReadBuffers, boolean purgeWriteBuffers) throws IOException {
557 | if (purgeReadBuffers) {
558 | vendorOut(FLUSH_RX_REQUEST, 0, null);
559 | }
560 |
561 | if (purgeWriteBuffers) {
562 | vendorOut(FLUSH_TX_REQUEST, 0, null);
563 | }
564 |
565 | return purgeReadBuffers || purgeWriteBuffers;
566 | }
567 | }
568 |
569 | public static Map getSupportedDevices() {
570 | final Map supportedDevices = new LinkedHashMap();
571 | supportedDevices.put(Integer.valueOf(UsbId.VENDOR_PROLIFIC),
572 | new int[] { UsbId.PROLIFIC_PL2303, });
573 | return supportedDevices;
574 | }
575 | }
576 |
--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
1 | GNU LESSER GENERAL PUBLIC LICENSE
2 | Version 2.1, February 1999
3 |
4 | Copyright (C) 1991, 1999 Free Software Foundation, Inc.
5 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
6 | Everyone is permitted to copy and distribute verbatim copies
7 | of this license document, but changing it is not allowed.
8 |
9 | [This is the first released version of the Lesser GPL. It also counts
10 | as the successor of the GNU Library Public License, version 2, hence
11 | the version number 2.1.]
12 |
13 | Preamble
14 |
15 | The licenses for most software are designed to take away your
16 | freedom to share and change it. By contrast, the GNU General Public
17 | Licenses are intended to guarantee your freedom to share and change
18 | free software--to make sure the software is free for all its users.
19 |
20 | This license, the Lesser General Public License, applies to some
21 | specially designated software packages--typically libraries--of the
22 | Free Software Foundation and other authors who decide to use it. You
23 | can use it too, but we suggest you first think carefully about whether
24 | this license or the ordinary General Public License is the better
25 | strategy to use in any particular case, based on the explanations below.
26 |
27 | When we speak of free software, we are referring to freedom of use,
28 | not price. Our General Public Licenses are designed to make sure that
29 | you have the freedom to distribute copies of free software (and charge
30 | for this service if you wish); that you receive source code or can get
31 | it if you want it; that you can change the software and use pieces of
32 | it in new free programs; and that you are informed that you can do
33 | these things.
34 |
35 | To protect your rights, we need to make restrictions that forbid
36 | distributors to deny you these rights or to ask you to surrender these
37 | rights. These restrictions translate to certain responsibilities for
38 | you if you distribute copies of the library or if you modify it.
39 |
40 | For example, if you distribute copies of the library, whether gratis
41 | or for a fee, you must give the recipients all the rights that we gave
42 | you. You must make sure that they, too, receive or can get the source
43 | code. If you link other code with the library, you must provide
44 | complete object files to the recipients, so that they can relink them
45 | with the library after making changes to the library and recompiling
46 | it. And you must show them these terms so they know their rights.
47 |
48 | We protect your rights with a two-step method: (1) we copyright the
49 | library, and (2) we offer you this license, which gives you legal
50 | permission to copy, distribute and/or modify the library.
51 |
52 | To protect each distributor, we want to make it very clear that
53 | there is no warranty for the free library. Also, if the library is
54 | modified by someone else and passed on, the recipients should know
55 | that what they have is not the original version, so that the original
56 | author's reputation will not be affected by problems that might be
57 | introduced by others.
58 |
59 | Finally, software patents pose a constant threat to the existence of
60 | any free program. We wish to make sure that a company cannot
61 | effectively restrict the users of a free program by obtaining a
62 | restrictive license from a patent holder. Therefore, we insist that
63 | any patent license obtained for a version of the library must be
64 | consistent with the full freedom of use specified in this license.
65 |
66 | Most GNU software, including some libraries, is covered by the
67 | ordinary GNU General Public License. This license, the GNU Lesser
68 | General Public License, applies to certain designated libraries, and
69 | is quite different from the ordinary General Public License. We use
70 | this license for certain libraries in order to permit linking those
71 | libraries into non-free programs.
72 |
73 | When a program is linked with a library, whether statically or using
74 | a shared library, the combination of the two is legally speaking a
75 | combined work, a derivative of the original library. The ordinary
76 | General Public License therefore permits such linking only if the
77 | entire combination fits its criteria of freedom. The Lesser General
78 | Public License permits more lax criteria for linking other code with
79 | the library.
80 |
81 | We call this license the "Lesser" General Public License because it
82 | does Less to protect the user's freedom than the ordinary General
83 | Public License. It also provides other free software developers Less
84 | of an advantage over competing non-free programs. These disadvantages
85 | are the reason we use the ordinary General Public License for many
86 | libraries. However, the Lesser license provides advantages in certain
87 | special circumstances.
88 |
89 | For example, on rare occasions, there may be a special need to
90 | encourage the widest possible use of a certain library, so that it becomes
91 | a de-facto standard. To achieve this, non-free programs must be
92 | allowed to use the library. A more frequent case is that a free
93 | library does the same job as widely used non-free libraries. In this
94 | case, there is little to gain by limiting the free library to free
95 | software only, so we use the Lesser General Public License.
96 |
97 | In other cases, permission to use a particular library in non-free
98 | programs enables a greater number of people to use a large body of
99 | free software. For example, permission to use the GNU C Library in
100 | non-free programs enables many more people to use the whole GNU
101 | operating system, as well as its variant, the GNU/Linux operating
102 | system.
103 |
104 | Although the Lesser General Public License is Less protective of the
105 | users' freedom, it does ensure that the user of a program that is
106 | linked with the Library has the freedom and the wherewithal to run
107 | that program using a modified version of the Library.
108 |
109 | The precise terms and conditions for copying, distribution and
110 | modification follow. Pay close attention to the difference between a
111 | "work based on the library" and a "work that uses the library". The
112 | former contains code derived from the library, whereas the latter must
113 | be combined with the library in order to run.
114 |
115 | GNU LESSER GENERAL PUBLIC LICENSE
116 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
117 |
118 | 0. This License Agreement applies to any software library or other
119 | program which contains a notice placed by the copyright holder or
120 | other authorized party saying it may be distributed under the terms of
121 | this Lesser General Public License (also called "this License").
122 | Each licensee is addressed as "you".
123 |
124 | A "library" means a collection of software functions and/or data
125 | prepared so as to be conveniently linked with application programs
126 | (which use some of those functions and data) to form executables.
127 |
128 | The "Library", below, refers to any such software library or work
129 | which has been distributed under these terms. A "work based on the
130 | Library" means either the Library or any derivative work under
131 | copyright law: that is to say, a work containing the Library or a
132 | portion of it, either verbatim or with modifications and/or translated
133 | straightforwardly into another language. (Hereinafter, translation is
134 | included without limitation in the term "modification".)
135 |
136 | "Source code" for a work means the preferred form of the work for
137 | making modifications to it. For a library, complete source code means
138 | all the source code for all modules it contains, plus any associated
139 | interface definition files, plus the scripts used to control compilation
140 | and installation of the library.
141 |
142 | Activities other than copying, distribution and modification are not
143 | covered by this License; they are outside its scope. The act of
144 | running a program using the Library is not restricted, and output from
145 | such a program is covered only if its contents constitute a work based
146 | on the Library (independent of the use of the Library in a tool for
147 | writing it). Whether that is true depends on what the Library does
148 | and what the program that uses the Library does.
149 |
150 | 1. You may copy and distribute verbatim copies of the Library's
151 | complete source code as you receive it, in any medium, provided that
152 | you conspicuously and appropriately publish on each copy an
153 | appropriate copyright notice and disclaimer of warranty; keep intact
154 | all the notices that refer to this License and to the absence of any
155 | warranty; and distribute a copy of this License along with the
156 | Library.
157 |
158 | You may charge a fee for the physical act of transferring a copy,
159 | and you may at your option offer warranty protection in exchange for a
160 | fee.
161 |
162 | 2. You may modify your copy or copies of the Library or any portion
163 | of it, thus forming a work based on the Library, and copy and
164 | distribute such modifications or work under the terms of Section 1
165 | above, provided that you also meet all of these conditions:
166 |
167 | a) The modified work must itself be a software library.
168 |
169 | b) You must cause the files modified to carry prominent notices
170 | stating that you changed the files and the date of any change.
171 |
172 | c) You must cause the whole of the work to be licensed at no
173 | charge to all third parties under the terms of this License.
174 |
175 | d) If a facility in the modified Library refers to a function or a
176 | table of data to be supplied by an application program that uses
177 | the facility, other than as an argument passed when the facility
178 | is invoked, then you must make a good faith effort to ensure that,
179 | in the event an application does not supply such function or
180 | table, the facility still operates, and performs whatever part of
181 | its purpose remains meaningful.
182 |
183 | (For example, a function in a library to compute square roots has
184 | a purpose that is entirely well-defined independent of the
185 | application. Therefore, Subsection 2d requires that any
186 | application-supplied function or table used by this function must
187 | be optional: if the application does not supply it, the square
188 | root function must still compute square roots.)
189 |
190 | These requirements apply to the modified work as a whole. If
191 | identifiable sections of that work are not derived from the Library,
192 | and can be reasonably considered independent and separate works in
193 | themselves, then this License, and its terms, do not apply to those
194 | sections when you distribute them as separate works. But when you
195 | distribute the same sections as part of a whole which is a work based
196 | on the Library, the distribution of the whole must be on the terms of
197 | this License, whose permissions for other licensees extend to the
198 | entire whole, and thus to each and every part regardless of who wrote
199 | it.
200 |
201 | Thus, it is not the intent of this section to claim rights or contest
202 | your rights to work written entirely by you; rather, the intent is to
203 | exercise the right to control the distribution of derivative or
204 | collective works based on the Library.
205 |
206 | In addition, mere aggregation of another work not based on the Library
207 | with the Library (or with a work based on the Library) on a volume of
208 | a storage or distribution medium does not bring the other work under
209 | the scope of this License.
210 |
211 | 3. You may opt to apply the terms of the ordinary GNU General Public
212 | License instead of this License to a given copy of the Library. To do
213 | this, you must alter all the notices that refer to this License, so
214 | that they refer to the ordinary GNU General Public License, version 2,
215 | instead of to this License. (If a newer version than version 2 of the
216 | ordinary GNU General Public License has appeared, then you can specify
217 | that version instead if you wish.) Do not make any other change in
218 | these notices.
219 |
220 | Once this change is made in a given copy, it is irreversible for
221 | that copy, so the ordinary GNU General Public License applies to all
222 | subsequent copies and derivative works made from that copy.
223 |
224 | This option is useful when you wish to copy part of the code of
225 | the Library into a program that is not a library.
226 |
227 | 4. You may copy and distribute the Library (or a portion or
228 | derivative of it, under Section 2) in object code or executable form
229 | under the terms of Sections 1 and 2 above provided that you accompany
230 | it with the complete corresponding machine-readable source code, which
231 | must be distributed under the terms of Sections 1 and 2 above on a
232 | medium customarily used for software interchange.
233 |
234 | If distribution of object code is made by offering access to copy
235 | from a designated place, then offering equivalent access to copy the
236 | source code from the same place satisfies the requirement to
237 | distribute the source code, even though third parties are not
238 | compelled to copy the source along with the object code.
239 |
240 | 5. A program that contains no derivative of any portion of the
241 | Library, but is designed to work with the Library by being compiled or
242 | linked with it, is called a "work that uses the Library". Such a
243 | work, in isolation, is not a derivative work of the Library, and
244 | therefore falls outside the scope of this License.
245 |
246 | However, linking a "work that uses the Library" with the Library
247 | creates an executable that is a derivative of the Library (because it
248 | contains portions of the Library), rather than a "work that uses the
249 | library". The executable is therefore covered by this License.
250 | Section 6 states terms for distribution of such executables.
251 |
252 | When a "work that uses the Library" uses material from a header file
253 | that is part of the Library, the object code for the work may be a
254 | derivative work of the Library even though the source code is not.
255 | Whether this is true is especially significant if the work can be
256 | linked without the Library, or if the work is itself a library. The
257 | threshold for this to be true is not precisely defined by law.
258 |
259 | If such an object file uses only numerical parameters, data
260 | structure layouts and accessors, and small macros and small inline
261 | functions (ten lines or less in length), then the use of the object
262 | file is unrestricted, regardless of whether it is legally a derivative
263 | work. (Executables containing this object code plus portions of the
264 | Library will still fall under Section 6.)
265 |
266 | Otherwise, if the work is a derivative of the Library, you may
267 | distribute the object code for the work under the terms of Section 6.
268 | Any executables containing that work also fall under Section 6,
269 | whether or not they are linked directly with the Library itself.
270 |
271 | 6. As an exception to the Sections above, you may also combine or
272 | link a "work that uses the Library" with the Library to produce a
273 | work containing portions of the Library, and distribute that work
274 | under terms of your choice, provided that the terms permit
275 | modification of the work for the customer's own use and reverse
276 | engineering for debugging such modifications.
277 |
278 | You must give prominent notice with each copy of the work that the
279 | Library is used in it and that the Library and its use are covered by
280 | this License. You must supply a copy of this License. If the work
281 | during execution displays copyright notices, you must include the
282 | copyright notice for the Library among them, as well as a reference
283 | directing the user to the copy of this License. Also, you must do one
284 | of these things:
285 |
286 | a) Accompany the work with the complete corresponding
287 | machine-readable source code for the Library including whatever
288 | changes were used in the work (which must be distributed under
289 | Sections 1 and 2 above); and, if the work is an executable linked
290 | with the Library, with the complete machine-readable "work that
291 | uses the Library", as object code and/or source code, so that the
292 | user can modify the Library and then relink to produce a modified
293 | executable containing the modified Library. (It is understood
294 | that the user who changes the contents of definitions files in the
295 | Library will not necessarily be able to recompile the application
296 | to use the modified definitions.)
297 |
298 | b) Use a suitable shared library mechanism for linking with the
299 | Library. A suitable mechanism is one that (1) uses at run time a
300 | copy of the library already present on the user's computer system,
301 | rather than copying library functions into the executable, and (2)
302 | will operate properly with a modified version of the library, if
303 | the user installs one, as long as the modified version is
304 | interface-compatible with the version that the work was made with.
305 |
306 | c) Accompany the work with a written offer, valid for at
307 | least three years, to give the same user the materials
308 | specified in Subsection 6a, above, for a charge no more
309 | than the cost of performing this distribution.
310 |
311 | d) If distribution of the work is made by offering access to copy
312 | from a designated place, offer equivalent access to copy the above
313 | specified materials from the same place.
314 |
315 | e) Verify that the user has already received a copy of these
316 | materials or that you have already sent this user a copy.
317 |
318 | For an executable, the required form of the "work that uses the
319 | Library" must include any data and utility programs needed for
320 | reproducing the executable from it. However, as a special exception,
321 | the materials to be distributed need not include anything that is
322 | normally distributed (in either source or binary form) with the major
323 | components (compiler, kernel, and so on) of the operating system on
324 | which the executable runs, unless that component itself accompanies
325 | the executable.
326 |
327 | It may happen that this requirement contradicts the license
328 | restrictions of other proprietary libraries that do not normally
329 | accompany the operating system. Such a contradiction means you cannot
330 | use both them and the Library together in an executable that you
331 | distribute.
332 |
333 | 7. You may place library facilities that are a work based on the
334 | Library side-by-side in a single library together with other library
335 | facilities not covered by this License, and distribute such a combined
336 | library, provided that the separate distribution of the work based on
337 | the Library and of the other library facilities is otherwise
338 | permitted, and provided that you do these two things:
339 |
340 | a) Accompany the combined library with a copy of the same work
341 | based on the Library, uncombined with any other library
342 | facilities. This must be distributed under the terms of the
343 | Sections above.
344 |
345 | b) Give prominent notice with the combined library of the fact
346 | that part of it is a work based on the Library, and explaining
347 | where to find the accompanying uncombined form of the same work.
348 |
349 | 8. You may not copy, modify, sublicense, link with, or distribute
350 | the Library except as expressly provided under this License. Any
351 | attempt otherwise to copy, modify, sublicense, link with, or
352 | distribute the Library is void, and will automatically terminate your
353 | rights under this License. However, parties who have received copies,
354 | or rights, from you under this License will not have their licenses
355 | terminated so long as such parties remain in full compliance.
356 |
357 | 9. You are not required to accept this License, since you have not
358 | signed it. However, nothing else grants you permission to modify or
359 | distribute the Library or its derivative works. These actions are
360 | prohibited by law if you do not accept this License. Therefore, by
361 | modifying or distributing the Library (or any work based on the
362 | Library), you indicate your acceptance of this License to do so, and
363 | all its terms and conditions for copying, distributing or modifying
364 | the Library or works based on it.
365 |
366 | 10. Each time you redistribute the Library (or any work based on the
367 | Library), the recipient automatically receives a license from the
368 | original licensor to copy, distribute, link with or modify the Library
369 | subject to these terms and conditions. You may not impose any further
370 | restrictions on the recipients' exercise of the rights granted herein.
371 | You are not responsible for enforcing compliance by third parties with
372 | this License.
373 |
374 | 11. If, as a consequence of a court judgment or allegation of patent
375 | infringement or for any other reason (not limited to patent issues),
376 | conditions are imposed on you (whether by court order, agreement or
377 | otherwise) that contradict the conditions of this License, they do not
378 | excuse you from the conditions of this License. If you cannot
379 | distribute so as to satisfy simultaneously your obligations under this
380 | License and any other pertinent obligations, then as a consequence you
381 | may not distribute the Library at all. For example, if a patent
382 | license would not permit royalty-free redistribution of the Library by
383 | all those who receive copies directly or indirectly through you, then
384 | the only way you could satisfy both it and this License would be to
385 | refrain entirely from distribution of the Library.
386 |
387 | If any portion of this section is held invalid or unenforceable under any
388 | particular circumstance, the balance of the section is intended to apply,
389 | and the section as a whole is intended to apply in other circumstances.
390 |
391 | It is not the purpose of this section to induce you to infringe any
392 | patents or other property right claims or to contest validity of any
393 | such claims; this section has the sole purpose of protecting the
394 | integrity of the free software distribution system which is
395 | implemented by public license practices. Many people have made
396 | generous contributions to the wide range of software distributed
397 | through that system in reliance on consistent application of that
398 | system; it is up to the author/donor to decide if he or she is willing
399 | to distribute software through any other system and a licensee cannot
400 | impose that choice.
401 |
402 | This section is intended to make thoroughly clear what is believed to
403 | be a consequence of the rest of this License.
404 |
405 | 12. If the distribution and/or use of the Library is restricted in
406 | certain countries either by patents or by copyrighted interfaces, the
407 | original copyright holder who places the Library under this License may add
408 | an explicit geographical distribution limitation excluding those countries,
409 | so that distribution is permitted only in or among countries not thus
410 | excluded. In such case, this License incorporates the limitation as if
411 | written in the body of this License.
412 |
413 | 13. The Free Software Foundation may publish revised and/or new
414 | versions of the Lesser General Public License from time to time.
415 | Such new versions will be similar in spirit to the present version,
416 | but may differ in detail to address new problems or concerns.
417 |
418 | Each version is given a distinguishing version number. If the Library
419 | specifies a version number of this License which applies to it and
420 | "any later version", you have the option of following the terms and
421 | conditions either of that version or of any later version published by
422 | the Free Software Foundation. If the Library does not specify a
423 | license version number, you may choose any version ever published by
424 | the Free Software Foundation.
425 |
426 | 14. If you wish to incorporate parts of the Library into other free
427 | programs whose distribution conditions are incompatible with these,
428 | write to the author to ask for permission. For software which is
429 | copyrighted by the Free Software Foundation, write to the Free
430 | Software Foundation; we sometimes make exceptions for this. Our
431 | decision will be guided by the two goals of preserving the free status
432 | of all derivatives of our free software and of promoting the sharing
433 | and reuse of software generally.
434 |
435 | NO WARRANTY
436 |
437 | 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
438 | WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
439 | EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
440 | OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
441 | KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
442 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
443 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
444 | LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
445 | THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
446 |
447 | 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
448 | WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
449 | AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
450 | FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
451 | CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
452 | LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
453 | RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
454 | FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
455 | SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
456 | DAMAGES.
457 |
--------------------------------------------------------------------------------