2019-11-19 18:42:19 +01:00
|
|
|
/* This program is free software: you can redistribute it and/or modify
|
|
|
|
* it under the terms of the GNU General Public License as published by
|
|
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
|
|
* (at your option) any later version.
|
|
|
|
*
|
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
* GNU General Public License for more details.
|
|
|
|
*
|
|
|
|
* You should have received a copy of the GNU General Public License
|
|
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
*
|
|
|
|
*/
|
|
|
|
/** USB cable definitions and utilities
|
|
|
|
* @file
|
|
|
|
* @author King Kévin <kingkevin@cuvoodoo.info>
|
|
|
|
* @date 2019
|
|
|
|
*/
|
|
|
|
|
2019-12-09 19:45:03 +01:00
|
|
|
/** the USB pin type */
|
2019-12-09 13:52:17 +01:00
|
|
|
enum usb_pin_type_t {
|
2019-12-09 19:45:03 +01:00
|
|
|
USB_PIN_TYPE_UNDEFINED, /*< the default type, undefined */
|
|
|
|
USB_PIN_TYPE_GROUND, /*< ground (including ground drain) */
|
|
|
|
USB_PIN_TYPE_POWER, /*< power (VBUS) */
|
|
|
|
USB_PIN_TYPE_SHIELD, /*< shield */
|
|
|
|
USB_PIN_TYPE_DIFFERENTIAL, /*< differential data pairs (D+/-, SSTX+/-, SSRX+/-) */
|
|
|
|
USB_PIN_TYPE_IDENTIFICATION, /*< pin to identify type (often connected to power or ground through resistor) */
|
|
|
|
USB_PIN_TYPE_OTHER, /*< any other type */
|
2019-12-09 13:52:17 +01:00
|
|
|
};
|
|
|
|
|
2019-12-09 19:44:25 +01:00
|
|
|
/** the type of connection between two pins
|
|
|
|
* @note to be used as bit mask
|
2019-12-09 20:25:54 +01:00
|
|
|
* @note ordered from least most most reliable/accurate
|
2019-12-09 19:44:25 +01:00
|
|
|
*/
|
|
|
|
enum usb_pin_connection_t {
|
|
|
|
USB_PIN_CONNECTION_DRIVE_FLOAT = (1 << 0), /*< the output side is driven using pull/push, the input is floating */
|
2019-12-09 20:25:54 +01:00
|
|
|
USB_PIN_CONNECTION_PULL_FLOAT = (1 << 1), /*< the output side is driven using pull up/down, the input is floating */
|
|
|
|
USB_PIN_CONNECTION_DRIVE_PULL = (1 << 2), /*< the output side is driven using pull/push, the input is pulled up/down */
|
2019-12-09 19:44:25 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
/** USB pin definition */
|
2019-11-19 18:42:19 +01:00
|
|
|
struct usb_pin_t {
|
|
|
|
const char* name; /*< pin name */
|
|
|
|
uint32_t port; /*< on which MCU port is this pin connected */
|
|
|
|
uint16_t pin; /*< on which MCU pin is this pin connected */
|
2019-12-09 13:52:17 +01:00
|
|
|
enum usb_pin_type_t type; /*< pin type */
|
2019-11-19 18:42:19 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
/** USB connector definition */
|
|
|
|
struct usb_connector_t {
|
|
|
|
const char* name; /*< connector name (A, B, mini-B, micro-B, C, ...) */
|
2019-12-30 17:44:50 +01:00
|
|
|
const char* shortname; /*< short connector name (A, B, mB, uB, C, ...) */
|
2019-12-13 09:45:00 +01:00
|
|
|
const char* variant; /*< variant if there are more than one of the same connector */
|
2019-11-19 18:42:19 +01:00
|
|
|
uint8_t pins_nb; /*< number of pins */
|
2019-12-10 22:33:32 +01:00
|
|
|
const uint8_t* pins; /*< all connector pins indexes */
|
2019-11-19 18:42:19 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
/** USB cable definition */
|
|
|
|
struct usb_cable_t {
|
|
|
|
const char* name; /*< cable name */
|
|
|
|
uint8_t connectors_nb; /*< number of connectors */
|
2019-11-20 03:22:32 +01:00
|
|
|
const struct usb_connector_t** connectors; /*< list of connectors this cables uses */
|
2019-12-31 11:47:37 +01:00
|
|
|
uint8_t mandatory_pairs_nb; /* number of connected pin pairs */
|
|
|
|
const uint8_t (*mandatory_pairs)[2]; /*< list of connected pin index pairs (order does not matter) */
|
|
|
|
uint8_t optional_pairs_nb; /* number of connected pin pairs */
|
|
|
|
const uint8_t (*optional_pairs)[2]; /*< list of connected pin index pairs (order does not matter) */
|
2019-11-19 18:42:19 +01:00
|
|
|
};
|
|
|
|
|
2019-12-10 22:33:32 +01:00
|
|
|
/** USB pin definitions */
|
|
|
|
extern const struct usb_pin_t usb_pins[105];
|
2019-11-19 18:42:19 +01:00
|
|
|
/** USB connectors definitions */
|
2019-11-20 03:22:32 +01:00
|
|
|
extern const struct usb_connector_t* usb_connectors[8];
|
2019-11-19 18:42:19 +01:00
|
|
|
/** USB cables definitions */
|
2019-12-12 13:39:32 +01:00
|
|
|
extern const struct usb_cable_t usb_cables[77];
|
2019-11-19 18:42:19 +01:00
|
|
|
|
2019-12-13 13:40:43 +01:00
|
|
|
/** set every USB pin from every USB connector to input floating */
|
|
|
|
void usb_cables_pins_float(void);
|
2019-11-19 18:42:19 +01:00
|
|
|
/** set every pin of connector to input floating
|
|
|
|
* @param[in] connector connector on which to set the pins floating
|
|
|
|
*/
|
2019-12-13 13:40:43 +01:00
|
|
|
void usb_cables_connector_float(const struct usb_connector_t* connector);
|
2019-11-19 18:42:19 +01:00
|
|
|
/** set every pin to the connectors to input floating
|
|
|
|
* @param[in] connectors list on connectors on which to set the pins floating
|
|
|
|
* @param[in] connectors_nb numbers of connectors
|
|
|
|
*/
|
2019-11-20 03:22:32 +01:00
|
|
|
void usb_cables_connectors_float(const struct usb_connector_t** connectors, uint8_t connectors_nb);
|
2019-12-13 14:45:14 +01:00
|
|
|
/** get connector from pin
|
|
|
|
* @param[in] pin pin index in usb_pins
|
|
|
|
* @return corresponding connector (NULL if none found)
|
|
|
|
*/
|
|
|
|
const struct usb_connector_t* usb_cables_get_connector(uint8_t pin);
|
2019-12-09 19:44:25 +01:00
|
|
|
/** test if two pins are connected
|
|
|
|
* @param[in] pin1 first pin
|
|
|
|
* @param[in] pin2 second pin
|
|
|
|
* @return first nibble corresponds to the connection types (usb_pin_connection_t) from pin1 to pin2, second nibble from pin2 to pin1
|
|
|
|
* @note setting both levels (high, low) in both directions (pin1 to pin2 and pin2 to pin1) are tested, except for ground pins
|
|
|
|
*/
|
2019-12-22 11:46:24 +01:00
|
|
|
uint8_t usb_cables_test_pins(const struct usb_pin_t* pin1, const struct usb_pin_t* pin2);
|
2019-12-22 11:47:53 +01:00
|
|
|
/** test connectors for connections between ground pins of the connectors
|
|
|
|
* @param[in] connectors connectors to test
|
2019-12-08 14:56:06 +01:00
|
|
|
* @param[in] connectors_nb numbers of connectors
|
2019-12-31 11:48:10 +01:00
|
|
|
* @param[out] connected which of the connectors are connected (optional)
|
|
|
|
* @return if at least on ground connection has been found
|
2019-12-22 11:47:53 +01:00
|
|
|
* @note connection between pin on the same connector are not tested
|
2019-12-08 14:56:06 +01:00
|
|
|
* @note it assumes all grounds are connected (e.g. only one cable is connected)
|
2019-12-30 19:56:44 +01:00
|
|
|
* @note this check is very fast
|
2019-12-08 14:56:06 +01:00
|
|
|
*/
|
2019-12-31 11:48:10 +01:00
|
|
|
bool usb_cables_test_ground(const struct usb_connector_t** connectors, uint8_t connectors_nb, bool* connected);
|
2019-12-22 11:37:04 +01:00
|
|
|
/** test if there is a load on the connector
|
|
|
|
* @param[in] connector connector to test
|
2019-12-09 13:52:17 +01:00
|
|
|
* @return if there is a load on the connector
|
|
|
|
*/
|
2019-12-22 11:37:04 +01:00
|
|
|
bool usb_cables_test_load(const struct usb_connector_t* connector);
|
2019-12-22 11:45:31 +01:00
|
|
|
/** test USB cable connections
|
|
|
|
* @param[in] usb_cable USB cable to test
|
2019-12-31 16:03:04 +01:00
|
|
|
* @param[out] defined number of pin pairs that are connected according to mandatory definition
|
|
|
|
* @param[out] optional number of pin pairs that are connected according to optional definition
|
2019-11-19 18:42:19 +01:00
|
|
|
* @param[out] undefined number of pin pairs that are connected but not according to definition
|
2019-12-09 23:08:16 +01:00
|
|
|
* @param[in] print print connection errors
|
2019-11-19 18:42:19 +01:00
|
|
|
* @return if the connections of the cable correspond to the definition
|
2019-12-22 11:45:31 +01:00
|
|
|
* @note each pair is tested in both directions
|
2019-11-19 18:42:19 +01:00
|
|
|
*/
|
2019-12-31 16:03:04 +01:00
|
|
|
bool usb_cables_test_cable(const struct usb_cable_t* cable, uint8_t* defined, uint8_t* optional, uint8_t* undefined, bool print);
|
2019-12-13 15:32:38 +01:00
|
|
|
/** test connections between connectors
|
2019-12-13 14:46:02 +01:00
|
|
|
* @param[in] connectors connectors to check
|
|
|
|
* @param[in] connectors_nb numbers of connectors
|
2019-12-13 15:32:38 +01:00
|
|
|
* @param[in] include_intra if connections between pins within a connector should be tested
|
|
|
|
* @param[in] ground_only only test connections between ground pins
|
2019-12-13 14:46:02 +01:00
|
|
|
* @param[out] connections_nb number of connections found
|
|
|
|
* @return list of pin pairs connections (NULL if 0 connections have been found or no connections have been found but no memory is available)
|
|
|
|
* @the list of pin pairs connections is allocated memory which should be freed by the caller
|
|
|
|
*/
|
2019-12-13 15:32:38 +01:00
|
|
|
uint8_t** usb_cables_test_connections(const struct usb_connector_t** connectors, uint8_t connectors_nb, bool include_intra, bool ground_only, uint16_t* connections_nb);
|