tsiry-sandratraina.com
A modern Music Player Daemon based on Rockbox open source high quality audio player
libadwaita
audio
rust
zig
deno
mpris
rockbox
mpd
1/***************************************************************************
2 * __________ __ ___.
3 * Open \______ \ ____ ____ | | _\_ |__ _______ ___
4 * Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ /
5 * Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < <
6 * Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \
7 * \/ \/ \/ \/ \/
8 * $Id$
9 *
10 * Copyright (C) 2002 by Linus Nielsen Feltzing
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation; either version 2
15 * of the License, or (at your option) any later version.
16 *
17 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
18 * KIND, either express or implied.
19 *
20 ****************************************************************************/
21#ifndef _USB_H_
22#define _USB_H_
23
24#include "config.h"
25#include "kernel.h"
26#include "button.h"
27
28/** USB introduction
29 * Targets which do not have any hardware support for USB, and cannot even detect
30 * it must define USB_NONE. Otherwise, they must at least implement USB
31 * detection.
32 *
33 * USB architecture
34 * The USB code is split into several parts:
35 * - usb: manages the USB connection
36 * - usb_core: implements a software USB stack based on usb_drv
37 * - usb_drv: implements the USB protocol based on some hardware transceiver/core
38 * - usb_{hid,storage,...}: implement USB functionalities based on usb_core
39 * Note that not all those are compiled in, in particular in the case of a
40 * hardware USB stack, or when the driver doesn't support all types of transfers.
41 *
42 * Software versus hardware USB stack
43 * A very important thing to keep in mind is that there are two very different
44 * situations:
45 * - software USB stack: the device only provides a USB transceiver and the
46 * USB stack must be implemented entirely in software. In this case the target
47 * must define HAVE_USBSTACK, correctly set CONFIG_USBOTG and implement a driver
48 * for the transceiver.
49 * - hardware USB stack: the device has a dedicated chip which implements the
50 * USB stack in hardware. In this case the target must *NOT* define HAVE_USBSTACK
51 * but can still define CONFIG_USBOTG and implement a driver to enable/disable
52 * the USB hardware.
53 *
54 * USB ignore buttons
55 * In some cases, the user wants to prevent Rockbox from entering USB mode. It
56 * can do so by holding a button while inserting the cable. By default any button
57 * will prevent the USB mode from kicking-in, so targets can optionally define
58 * USBPOWER_BTN_IGNORE to a mask of buttons to ignore in this check.
59 *
60 * USB states
61 * It is important to understand that the usb code can be in one of three states:
62 * - extracted: no USB cable is plugged
63 * - powered-only: a USB cable is plugged but the USB mode will not be entered,
64 * either because no host was detected or because the user requested so.
65 * - inserted: a USB cable is plugged and the USB mode has been entered, either
66 * the software or hardware stack is running.
67 *
68 * USB exclusive mode
69 * Either in hardware or software stack, if the USB was configured to run in
70 * mass storage mode, it will require exclusive access to the disk and ask all
71 * threads to release any file handle and stop using the disks. It does so by
72 * broadcasting a SYS_USB_CONNECTED message, which threads must acknowledge using
73 * usb_acknowledge(SYS_USB_CONNECTED_ACK). They must not access the disk until
74 * SYS_USB_DISCONNECTED is broadcast. To ease waiting, threads can call
75 * usb_wait_for_disconnect() or usb_wait_for_disconnect_w_tmo() on their waiting
76 * queue.
77 *
78 * USB detection
79 * Except when no usb code is compiled at all (USB_NONE), the usb thread keeps
80 * track of the USB insertion state, which can be either USB_INSERTED (meaning
81 * 5v is present) or USB_EXTRACTED. Each target must implement usb_detect()
82 * to report the insertion state.
83 * Targets which support insertion/extraction interrupts must define
84 * USB_STATUS_BY_EVENT and notify the thread on changes by calling
85 * usb_status_event() with the new state. Other targets must *not* define
86 * USB_STATUS_BY_EVENT and the usb thread by regularly poll the insertion state
87 * using usb_detect().
88 *
89 * USB powering & charging
90 * Device which can be powered from USB must define HAVE_USB_POWER. Note that
91 * powering doesn't imply charging (for example a AA-powered device can be
92 * powered from USB but not charged), charging sources are reported by the
93 * power subsystem (see power.h). The USB specification mandates the maximum
94 * current which can be drawn under which cirmcunstances. Device which cannot
95 * control the charge current should make sure it is always <100mA to meet the
96 * USB specification. Device with configurable charging current which support
97 * >=100mA must define HAVE_USB_CHARGING_ENABLE and implement
98 * usb_charging_maxcurrent_change() to let the usb thread control the maximum
99 * charging control.
100 * */
101
102#if defined(IPOD_COLOR) || defined(IPOD_4G) \
103 || defined(IPOD_MINI) || defined(IPOD_MINI2G)
104#define USB_FIREWIRE_HANDLING
105#endif
106
107/* Messages from usb_tick and thread states */
108enum
109{
110 USB_SCREENDUMP = -1, /* State */
111 USB_EXTRACTED = 0, /* Event+State */
112 USB_INSERTED, /* Event+State */
113 USB_POWERED, /* State - transitional indicator if no host */
114#if (CONFIG_STORAGE & STORAGE_MMC)
115 USB_REENABLE, /* Event */
116#endif
117#ifdef HAVE_USBSTACK
118 USB_TRANSFER_COMPLETION, /* Event */
119 USB_NOTIFY_SET_ADDR, /* Event */
120 USB_NOTIFY_SET_CONFIG, /* Event */
121#endif
122#ifdef USB_FIREWIRE_HANDLING
123 USB_REQUEST_REBOOT, /* Event */
124#endif
125 USB_QUIT, /* Event */
126#if defined(HAVE_USB_CHARGING_ENABLE) && defined(HAVE_USBSTACK)
127 USB_CHARGER_UPDATE, /* Event */
128#endif
129#ifdef HAVE_BOOTLOADER_USB_MODE
130 USB_HANDLED, /* Bootloader status code */
131#endif
132};
133
134/* Supported usb modes. */
135enum
136{
137 USB_MODE_MASS_STORAGE,
138 USB_MODE_CHARGE,
139 USB_MODE_ADB
140};
141
142#ifdef HAVE_USB_POWER
143/*allow people to define this in config-target.h if they need it*/
144#if !defined(USBPOWER_BTN_IGNORE)
145#define USBPOWER_BTN_IGNORE 0
146#endif
147
148#if defined(BOOTLOADER)
149#define USBMODE_DEFAULT USB_MODE_MASS_STORAGE
150#else
151#define USBMODE_DEFAULT USB_MODE_MASS_STORAGE
152#endif
153
154#endif
155
156#ifdef HAVE_USBSTACK
157/* USB class drivers */
158enum {
159#ifdef USB_ENABLE_STORAGE
160 USB_DRIVER_MASS_STORAGE,
161#endif
162#ifdef USB_ENABLE_SERIAL
163 USB_DRIVER_SERIAL,
164#endif
165#ifdef USB_ENABLE_CHARGING_ONLY
166 USB_DRIVER_CHARGING_ONLY,
167#endif
168#ifdef USB_ENABLE_HID
169 USB_DRIVER_HID,
170#endif
171#ifdef USB_ENABLE_AUDIO
172 USB_DRIVER_AUDIO,
173#endif
174 USB_NUM_DRIVERS
175};
176
177struct usb_transfer_completion_event_data
178{
179 unsigned char endpoint;
180 int dir;
181 int status;
182 int length;
183 void* data[2];
184};
185#endif /* HAVE_USBSTACK */
186
187/* initialise the usb code and thread */
188void usb_init(void) INIT_ATTR;
189/* target must implement this to enable/disable the usb transceiver/core */
190void usb_enable(bool on);
191/* when one or more driver requires exclusive mode, this is called after all threads have acknowledged
192 * exclusive mode and disk have been umounted; otherwise it is called immediately after host has
193 * been detected */
194void usb_attach(void);
195/* enable usb detection monitoring; before this function is called, all usb
196 * detection changes are ignored */
197void usb_start_monitoring(void) INIT_ATTR;
198void usb_close(void);
199/* acknowledge usb connection, typically with SYS_USB_CONNECTED_ACK */
200void usb_acknowledge(long id);
201/* block the current thread until SYS_USB_DISCONNECTED has been broadcast */
202void usb_wait_for_disconnect(struct event_queue *q);
203/* same as usb_wait_for_disconnect() but with a timeout, returns 1 on timeout */
204int usb_wait_for_disconnect_w_tmo(struct event_queue *q, int ticks);
205/* check whether USB is plugged, note that this is the official value which has
206 * been reported to the thread */
207bool usb_inserted(void);
208/* check whether USB is plugged, note that this is the raw hardware value */
209int usb_detect(void);
210#ifdef USB_STATUS_BY_EVENT
211/* Notify USB insertion state (USB_INSERTED or USB_EXTRACTED) */
212void usb_status_event(int current_status);
213#endif
214#ifdef HAVE_USB_POWER
215/* returns whether the USB is in powered-only state */
216bool usb_powered_only(void);
217#ifdef HAVE_USB_CHARGING_ENABLE
218enum {
219 USB_CHARGING_DISABLE, /* the USB code will never ask for more than 100mA */
220 USB_CHARGING_ENABLE, /* the code will ask for the maximum possible value */
221 USB_CHARGING_FORCE /* the code will always ask for 500mA */
222};
223/* select the USB charging mode, typically used by apps/ to reflect user setting,
224 * implemented by usb_core on targets with a software stack, and by target code
225 * on targets with a hardware stack */
226void usb_charging_enable(int state);
227#ifdef HAVE_USBSTACK
228/* update the USB charging value based on the current USB state */
229void usb_charger_update(void);
230#endif /* HAVE_USBSTACK */
231/* limit the maximum USB current the charger can draw */
232void usb_charging_maxcurrent_change(int maxcurrent);
233/* returns the maximum allowed USB current, based on USB charging mode and state */
234int usb_charging_maxcurrent(void);
235#endif /* HAVE_USB_CHARGING_ENABLE */
236void usb_set_mode(int mode);
237#endif /* HAVE_USB_POWER */
238#ifdef HAVE_USBSTACK
239/* USB driver call this function to notify that a transfer has completed */
240void usb_signal_transfer_completion(
241 struct usb_transfer_completion_event_data *event_data);
242/* notify the USB code that some important event has occurred which influences the
243 * USB state (like USB_NOTIFY_SET_ADDR). USB drivers should call usb_core_notify_*
244 * functions and not this function. */
245void usb_signal_notify(long id, intptr_t data);
246/* returns whether a USB_DRIVER_* is enabled (like HID, mass storage, ...) */
247bool usb_driver_enabled(int driver);
248/* returns whether exclusive storage is available for USB */
249bool usb_exclusive_storage(void);
250#endif /* HAVE_USBSTACK */
251
252#ifdef USB_FIREWIRE_HANDLING
253bool firewire_detect(void);
254void usb_firewire_connect_event(void);
255#endif
256
257#ifdef USB_ENABLE_HID
258/* enable or disable the HID driver */
259void usb_set_hid(bool enable);
260#endif
261
262#ifdef USB_ENABLE_AUDIO
263void usb_set_audio(int value);
264#endif
265
266#if defined(USB_ENABLE_STORAGE) && defined(HAVE_MULTIDRIVE)
267/* when the target has several drives, decide whether mass storage should
268 * skip the first drive. This is useful when the second drive is a SD card
269 * and the host only supports access to the first USB drive (this is very common
270 * in car tuners and USB speakers) */
271void usb_set_skip_first_drive(bool skip);
272#endif
273
274#if !defined(SIMULATOR) && !defined(USB_NONE)
275/* initialise the USB hardware, this is a one-time init and it should setup what
276 * is necessary to do proper USB detection, and it should call usb_drv_startup()
277 * to do the one-time initialisation of the USB driver */
278void usb_init_device(void);
279#endif
280
281#endif