usbg.h

Go to the documentation of this file.

/*
 * Copyright (C) 2013 Linaro Limited
 *
 * Matt Porter <mporter@linaro.org>
 *
 * Copyright (C) 2013 - 2015 Samsung Electronics
 *
 * Krzysztof Opasiak <k.opasiak@samsung.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library 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
 * Lesser General Public License for more details.
 */
 
#ifndef __USBG_H__
#define __USBG_H__
 
#include <dirent.h>
#include <sys/queue.h>
#include <netinet/ether.h>
#include <stdint.h>
#include <limits.h>
#include <stdbool.h>
#include <stdio.h> /* For FILE * */
#include <malloc.h>
 
#include "usbg_version.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define DEFAULT_UDC             NULL
#define LANG_US_ENG             0x0409
#define DEFAULT_CONFIG_LABEL "config"
 
/* This one has to be at least 18 bytes to hold network address */
#define USBG_MAX_STR_LENGTH 256
#define USBG_MAX_NAME_LENGTH 40
/* Dev name for ffs is a part of function name, we subtract 4 char for "ffs." */
#define USBG_MAX_DEV_LENGTH (USBG_MAX_NAME_LENGTH - 4)
 
#define USBG_TO_UNION(UNAME, FIELD, WHAT)       \
        ((union UNAME){ .FIELD = WHAT, })
 
#define USBG_RM_RECURSE 1
 
/*
 * Internal structures
 */
struct usbg_state;
struct usbg_gadget;
struct usbg_config;
struct usbg_function;
struct usbg_binding;
struct usbg_udc;
 
typedef struct usbg_state usbg_state;
 
typedef struct usbg_gadget usbg_gadget;
 
typedef struct usbg_config usbg_config;
 
typedef struct usbg_function usbg_function;
 
typedef struct usbg_binding usbg_binding;
 
typedef struct usbg_udc usbg_udc;
 
typedef enum {
        USBG_GADGET_ATTR_MIN = 0,
        USBG_BCD_USB = USBG_GADGET_ATTR_MIN,
        USBG_B_DEVICE_CLASS,
        USBG_B_DEVICE_SUB_CLASS,
        USBG_B_DEVICE_PROTOCOL,
        USBG_B_MAX_PACKET_SIZE_0,
        USBG_ID_VENDOR,
        USBG_ID_PRODUCT,
        USBG_BCD_DEVICE,
        USBG_GADGET_ATTR_MAX,
} usbg_gadget_attr;
 
struct usbg_gadget_attrs
{
        uint16_t bcdUSB;
        uint8_t bDeviceClass;
        uint8_t bDeviceSubClass;
        uint8_t bDeviceProtocol;
        uint8_t bMaxPacketSize0;
        uint16_t idVendor;
        uint16_t idProduct;
        uint16_t bcdDevice;
};
 
typedef enum {
        USBG_GADGET_STR_MIN = 0,
        USBG_STR_MANUFACTURER = USBG_GADGET_STR_MIN,
        USBG_STR_PRODUCT,
        USBG_STR_SERIAL_NUMBER,
        USBG_GADGET_STR_MAX,
} usbg_gadget_str;
 
struct usbg_gadget_strs
{
        char *manufacturer;
        char *product;
        char *serial;
};
 
struct usbg_gadget_os_descs
{
        bool use;
        uint8_t b_vendor_code;
        char *qw_sign;
};
 
typedef enum {
        USBG_GADGET_OS_DESC_MIN = 0,
        OS_DESC_USE = USBG_GADGET_OS_DESC_MIN,
        OS_DESC_B_VENDOR_CODE,
        OS_DESC_QW_SIGN,
        USBG_GADGET_OS_DESC_MAX,
} usbg_gadget_os_desc_strs;
 
struct usbg_config_attrs
{
        uint8_t bmAttributes;
        uint8_t bMaxPower;
};
 
struct usbg_config_strs
{
        char *configuration;
};
 
typedef enum
{
        USBG_FUNCTION_TYPE_MIN = 0,
        USBG_F_SERIAL = USBG_FUNCTION_TYPE_MIN,
        USBG_F_ACM,
        USBG_F_OBEX,
        USBG_F_ECM,
        USBG_F_SUBSET,
        USBG_F_NCM,
        USBG_F_EEM,
        USBG_F_RNDIS,
        USBG_F_PHONET,
        USBG_F_FFS,
        USBG_F_MASS_STORAGE,
        USBG_F_MIDI,
        USBG_F_LOOPBACK,
        USBG_F_HID,
        USBG_F_UAC2,
        USBG_FUNCTION_TYPE_MAX,
} usbg_function_type;
 
struct usbg_function_os_desc
{
        char *compatible_id;
        char *sub_compatible_id;
};
 
/* Error codes */
 
typedef enum  {
        USBG_SUCCESS = 0,
        USBG_ERROR_NO_MEM = -1,
        USBG_ERROR_NO_ACCESS = -2,
        USBG_ERROR_INVALID_PARAM = -3,
        USBG_ERROR_NOT_FOUND = -4,
        USBG_ERROR_IO = -5,
        USBG_ERROR_EXIST = -6,
        USBG_ERROR_NO_DEV = -7,
        USBG_ERROR_BUSY = -8,
        USBG_ERROR_NOT_SUPPORTED = -9,
        USBG_ERROR_PATH_TOO_LONG = -10,
        USBG_ERROR_INVALID_FORMAT = -11,
        USBG_ERROR_MISSING_TAG = -12,
        USBG_ERROR_INVALID_TYPE = -13,
        USBG_ERROR_INVALID_VALUE = -14,
        USBG_ERROR_NOT_EMPTY = -15,
        USBG_ERROR_OTHER_ERROR = -99
} usbg_error;
 
extern const char *usbg_error_name(usbg_error e);
 
extern const char *usbg_strerror(usbg_error e);
 
/* Library init and cleanup */
 
extern int usbg_init(const char *configfs_path, usbg_state **state);
 
extern void usbg_cleanup(usbg_state *s);
 
extern const char *usbg_get_configfs_path(usbg_state *s);
 
extern int usbg_get_configfs_path_s(usbg_state *s, char *buf, int len);
 
/* USB gadget queries */
 
extern usbg_gadget *usbg_get_gadget(usbg_state *s, const char *name);
 
extern usbg_function *usbg_get_function(usbg_gadget *g,
                usbg_function_type type, const char *instance);
 
extern usbg_config *usbg_get_config(usbg_gadget *g, int id, const char *label);
 
extern usbg_udc *usbg_get_udc(usbg_state *s, const char *name);
 
/* USB gadget/config/function/binding removal */
 
extern int usbg_rm_binding(usbg_binding *b);
 
extern int usbg_rm_config(usbg_config *c, int opts);
 
extern int usbg_rm_function(usbg_function *f, int opts);
 
extern int usbg_rm_gadget(usbg_gadget *g, int opts);
 
extern int usbg_rm_config_strs(usbg_config *c, int lang);
 
extern int usbg_rm_gadget_strs(usbg_gadget *g, int lang);
 
/* USB gadget allocation and configuration */
 
extern int usbg_create_gadget_vid_pid(usbg_state *s, const char *name,
                uint16_t idVendor, uint16_t idProduct, usbg_gadget **g);
 
extern int usbg_create_gadget(usbg_state *s, const char *name,
                              const struct usbg_gadget_attrs *g_attrs,
                              const struct usbg_gadget_strs *g_strs,
                              usbg_gadget **g);
 
extern const char *usbg_get_gadget_attr_str(usbg_gadget_attr attr);
 
extern int usbg_lookup_gadget_attr(const char *name);
 
extern int usbg_lookup_gadget_str(const char *name);
 
extern const char *usbg_get_gadget_str_name(usbg_gadget_str str);
 
extern const char *usbg_get_gadget_os_desc_name(usbg_gadget_os_desc_strs str);
 
extern int usbg_set_gadget_attr(usbg_gadget *g, usbg_gadget_attr attr, int val);
 
extern int usbg_get_gadget_attr(usbg_gadget *g, usbg_gadget_attr attr);
 
extern int usbg_set_gadget_attrs(usbg_gadget *g,
                                 const struct usbg_gadget_attrs *g_attrs);
 
extern int usbg_get_gadget_attrs(usbg_gadget *g,
                                 struct usbg_gadget_attrs *g_attrs);
 
extern const char *usbg_get_gadget_name(usbg_gadget *g);
 
extern int usbg_get_gadget_name_s(usbg_gadget *g, char *buf, int len);
 
extern int usbg_set_gadget_vendor_id(usbg_gadget *g, uint16_t idVendor);
 
extern int usbg_set_gadget_product_id(usbg_gadget *g, uint16_t idProduct);
 
extern int usbg_set_gadget_device_class(usbg_gadget *g,
                uint8_t bDeviceClass);
 
extern int usbg_set_gadget_device_protocol(usbg_gadget *g,
                uint8_t bDeviceProtocol);
 
extern int usbg_set_gadget_device_subclass(usbg_gadget *g,
                uint8_t bDeviceSubClass);
 
extern int usbg_set_gadget_device_max_packet(usbg_gadget *g,
                uint8_t bMaxPacketSize0);
 
extern int usbg_set_gadget_device_bcd_device(usbg_gadget *g,
                uint16_t bcdDevice);
 
extern int usbg_set_gadget_device_bcd_usb(usbg_gadget *g, uint16_t bcdUSB);
 
extern int usbg_get_gadget_strs(usbg_gadget *g, int lang,
                                struct usbg_gadget_strs *g_strs);
 
extern int usbg_get_gadget_strs_langs(usbg_gadget *g, int **langs);
 
static inline void usbg_free_gadget_strs(struct usbg_gadget_strs *g_strs)
{
        if (!g_strs)
                return;
 
        free(g_strs->manufacturer);
        free(g_strs->product);
        free(g_strs->serial);
}
 
extern int usbg_set_gadget_str(usbg_gadget *g, usbg_gadget_str str, int lang,
                const char *val);
 
extern int usbg_set_gadget_strs(usbg_gadget *g, int lang,
                                const struct usbg_gadget_strs *g_strs);
 
extern int usbg_set_gadget_serial_number(usbg_gadget *g, int lang,
                                         const char *ser);
 
extern int usbg_set_gadget_manufacturer(usbg_gadget *g, int lang,
                                        const char *mnf);
 
extern int usbg_set_gadget_product(usbg_gadget *g, int lang,
                                   const char *prd);
 
extern int usbg_get_gadget_os_descs(usbg_gadget *g,
                struct usbg_gadget_os_descs *g_os_descs);
 
static inline void usbg_free_gadget_os_desc(
                        struct usbg_gadget_os_descs *g_os_desc)
{
        if (!g_os_desc)
                return;
 
        free(g_os_desc->qw_sign);
}
 
extern int usbg_set_gadget_os_descs(usbg_gadget *g,
                const struct usbg_gadget_os_descs *g_os_descs);
 
/* USB function allocation and configuration */
 
extern int usbg_create_function(usbg_gadget *g, usbg_function_type type,
                 const char *instance, void *f_attrs, usbg_function **f);
 
extern const char *usbg_get_function_instance(usbg_function *f);
 
extern int usbg_get_function_instance_s(usbg_function *f, char *buf, int len);
 
extern const char *usbg_get_function_type_str(usbg_function_type type);
 
extern int usbg_lookup_function_type(const char *name);
 
extern void usbg_cleanup_function_attrs(usbg_function *f, void *f_attrs);
 
extern usbg_function_type usbg_get_function_type(usbg_function *f);
 
extern int usbg_get_function_attrs(usbg_function *f, void *f_attrs);
 
extern int usbg_set_function_attrs(usbg_function *f, void *f_attrs);
 
extern int usbg_get_interf_os_desc(usbg_function *f, const char *iname,
                struct usbg_function_os_desc *f_os_desc);
 
static inline void usbg_free_interf_os_desc(
                        struct usbg_function_os_desc *f_os_desc)
{
        if (!f_os_desc)
                return;
 
        free(f_os_desc->compatible_id);
        free(f_os_desc->sub_compatible_id);
}
 
extern int usbg_set_interf_os_desc(usbg_function *f, const char *iname,
                const struct usbg_function_os_desc *f_os_desc);
 
/* USB configurations allocation and configuration */
 
extern int usbg_create_config(usbg_gadget *g, int id, const char *label,
                              const struct usbg_config_attrs *c_attrs,
                              const struct usbg_config_strs *c_strs,
                              usbg_config **c);
 
extern const char *usbg_get_config_label(usbg_config *c);
 
extern int usbg_get_config_label_s(usbg_config *c, char *buf, int len);
 
extern int usbg_get_config_id(usbg_config *c);
 
extern int usbg_set_config_attrs(usbg_config *c,
                                 const struct usbg_config_attrs *c_attrs);
 
extern int usbg_get_config_attrs(usbg_config *c,
                                 struct usbg_config_attrs *c_attrs);
 
extern int usbg_set_config_max_power(usbg_config *c, int bMaxPower);
 
extern int usbg_set_config_bm_attrs(usbg_config *c, int bmAttributes);
 
extern int usbg_get_config_strs(usbg_config *c, int lang,
                                struct usbg_config_strs *c_strs);
 
extern int usbg_get_config_strs_langs(usbg_config *c, int **langs);
 
static inline void usbg_free_config_strs(struct usbg_config_strs *c_strs)
{
        if (!c_strs)
                return;
 
        free(c_strs->configuration);
}
 
extern int usbg_set_config_strs(usbg_config *c, int lang,
                                const struct usbg_config_strs *c_strs);
 
extern int usbg_set_config_string(usbg_config *c, int lang, const char *string);
 
extern int usbg_add_config_function(usbg_config *c, const char *name,
                                    usbg_function *f);
 
extern usbg_function *usbg_get_binding_target(usbg_binding *b);
 
extern const char *usbg_get_binding_name(usbg_binding *b);
 
extern int usbg_get_binding_name_s(usbg_binding *b, char *buf, int len);
 
usbg_config *usbg_get_os_desc_binding(usbg_gadget *g);
 
extern int usbg_set_os_desc_config(usbg_gadget *g, usbg_config *c);
 
/* USB gadget setup and teardown */
 
extern int usbg_enable_gadget(usbg_gadget *g, usbg_udc *udc);
 
extern int usbg_disable_gadget(usbg_gadget *g);
 
extern const char *usbg_get_udc_name(usbg_udc *u);
 
extern int usbg_get_udc_name_s(usbg_udc *u, char *buf, int len);
 
extern usbg_udc *usbg_get_gadget_udc(usbg_gadget *g);
 
extern usbg_gadget *usbg_get_udc_gadget(usbg_udc *u);
 
#define usbg_for_each_gadget(g, s) \
        for (g = usbg_get_first_gadget(s); \
        g != NULL; \
        g = usbg_get_next_gadget(g))
 
#define usbg_for_each_function(f, g) \
        for (f = usbg_get_first_function(g); \
        f != NULL; \
        f = usbg_get_next_function(f))
 
#define usbg_for_each_config(c, g) \
        for (c = usbg_get_first_config(g); \
        c != NULL; \
        c = usbg_get_next_config(c))
 
#define usbg_for_each_binding(b, c)     \
        for (b = usbg_get_first_binding(c); \
        b != NULL; \
        b = usbg_get_next_binding(b))
 
#define usbg_for_each_udc(u, s) \
        for (u = usbg_get_first_udc(s); \
        u != NULL; \
        u = usbg_get_next_udc(u))
 
extern usbg_gadget *usbg_get_first_gadget(usbg_state *s);
 
extern usbg_function *usbg_get_first_function(usbg_gadget *g);
 
extern usbg_config *usbg_get_first_config(usbg_gadget *g);
 
extern usbg_binding *usbg_get_first_binding(usbg_config *c);
 
extern usbg_udc *usbg_get_first_udc(usbg_state *s);
 
extern usbg_gadget *usbg_get_next_gadget(usbg_gadget *g);
 
extern usbg_function *usbg_get_next_function(usbg_function *f);
 
extern usbg_config *usbg_get_next_config(usbg_config *c);
 
extern usbg_binding *usbg_get_next_binding(usbg_binding *b);
 
extern usbg_udc *usbg_get_next_udc(usbg_udc *u);
 
/* Import / Export API */
 
extern int usbg_export_function(usbg_function *f, FILE *stream);
 
extern int usbg_export_config(usbg_config *c, FILE *stream);
 
extern int usbg_export_gadget(usbg_gadget *g, FILE *stream);
 
extern int usbg_import_function(usbg_gadget *g, FILE *stream,
                                const char *instance, usbg_function **f);
 
extern int usbg_import_config(usbg_gadget *g, FILE *stream, int id,
                                usbg_config **c);
 
extern int usbg_import_gadget(usbg_state *s, FILE *stream,
                              const char *name, usbg_gadget **g);
 
extern const char *usbg_get_func_import_error_text(usbg_gadget *g);
 
extern int usbg_get_func_import_error_line(usbg_gadget *g);
 
extern const char *usbg_get_config_import_error_text(usbg_gadget *g);
 
extern int usbg_get_config_import_error_line(usbg_gadget *g);
 
extern const char *usbg_get_gadget_import_error_text(usbg_state *s);
 
extern int usbg_get_gadget_import_error_line(usbg_state *s);
 
#ifdef __cplusplus
}
#endif
 
#endif /* __USBG_H__ */