Skip to content

Commit 2a94a3d

Browse files
c1728p9c1728p9
committed
Separate USBPhyEvents and USBPhyTypes from USBPhy
Break apart USBPhy into three separate header files. Also make some doxygen updates.
1 parent 73084e0 commit 2a94a3d

File tree

4 files changed

+192
-124
lines changed

4 files changed

+192
-124
lines changed

‎platform/USBPhy.h

Lines changed: 16 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,14 @@
1717
#ifndef USBPHY_H
1818
#define USBPHY_H
1919

20-
#include <stdint.h>
20+
#include "USBPhyTypes.h"
21+
#include "USBPhyEvents.h"
2122

22-
/**
23-
* \defgroup hal_usb_device USB Device HAL
24-
* Abstract interface to physical USB hardware
23+
/** Abstract interface to physical USB hardware
2524
*
2625
* # Defined behavior
2726
* * Any endpoint configurations which fit in the parameters of the table returned
28-
* by USBPhy::endpointTable can be used.
27+
* by USBPhy::endpoint_table can be used.
2928
* * All endpoints in any valid endpoint configuration can be used concurrently
3029
* * Device supports use of at least one control, bulk, interrupt and
3130
* isochronous in each direction at the same time - at least 8 endpoints.
@@ -49,127 +48,20 @@
4948
* * Devices behavior is undefined if latency is greater than 10ms when a reset occurs - see USB spec 7.1.7.5
5049
* * Calling any of the USBPhy::endpoint_* functions on endpoint 0
5150
*
52-
* # Potential bugs
53-
* * Processing control packets in the wrong order when multiple packets are present
54-
* * Back to back setup packets handled incorrectly
55-
* * Signal corruption not handled correctly
56-
* * USB race conditions
51+
* # Notes
52+
* * Make sure USB packets are processed in the correct order when multiple packets are present.
53+
* Typically IN endpoints should be handled before OUT endpoints if both are pending.
54+
* * Setup packets may be resent if there is noise on the USB line. The USBPhy should be able
55+
* to gracefully handle this scenario and respond to the setup packet with an ACK.
56+
* * Bi-directional protocols making use of alternating IN and OUT phases should not rely
57+
* on the last ACK an IN transfer to indicate that the OUT phase should start. Instead,
58+
* the OUT phase should be started at the same time the last IN transfer is started. This
59+
* is because the ACK to the last in transfer may be dropped if there is noise on the USB
60+
* line. If dropped it will only get re-sent on the next IN phase. More info on this can be
61+
* found in section 8.5.3.3 of the USB spec.
5762
*
63+
* @ingroup usb_device_core
5864
*/
59-
60-
typedef uint8_t usb_ep_t;
61-
62-
typedef enum {
63-
USB_EP_TYPE_CTRL = 0,
64-
USB_EP_TYPE_ISO = 1,
65-
USB_EP_TYPE_BULK = 2,
66-
USB_EP_TYPE_INT = 3
67-
} usb_ep_type_t;
68-
69-
enum {
70-
USB_EP_ATTR_ALLOW_CTRL = 1 << USB_EP_TYPE_CTRL,
71-
USB_EP_ATTR_ALLOW_BULK = 1 << USB_EP_TYPE_BULK,
72-
USB_EP_ATTR_ALLOW_INT = 1 << USB_EP_TYPE_INT,
73-
USB_EP_ATTR_ALLOW_ISO = 1 << USB_EP_TYPE_ISO,
74-
USB_EP_ATTR_ALLOW_ALL = USB_EP_ATTR_ALLOW_CTRL | USB_EP_ATTR_ALLOW_BULK |
75-
USB_EP_ATTR_ALLOW_INT | USB_EP_ATTR_ALLOW_ISO,
76-
77-
USB_EP_ATTR_DIR_IN = 0 << 4,
78-
USB_EP_ATTR_DIR_OUT = 1 << 4,
79-
USB_EP_ATTR_DIR_IN_OR_OUT = 2 << 4,
80-
USB_EP_ATTR_DIR_IN_AND_OUT = 3 << 4,
81-
USB_EP_ATTR_DIR_MASK = 3 << 4
82-
};
83-
typedef uint8_t usb_ep_attr_t;
84-
85-
struct usb_ep_entry_t {
86-
usb_ep_attr_t attributes;
87-
uint8_t byte_cost;
88-
uint16_t base_cost;
89-
};
90-
91-
struct usb_ep_table_t {
92-
uint32_t resources;
93-
usb_ep_entry_t table[16];
94-
};
95-
96-
class USBPhyEvents {
97-
public:
98-
USBPhyEvents() {};
99-
virtual ~USBPhyEvents() {};
100-
101-
/**
102-
* Callback called when a bus reset occurs
103-
* @note called in the contex of USBPhy::process
104-
*/
105-
virtual void reset() = 0;
106-
107-
/**
108-
* Callback called when an endpoint 0 setup packet is received
109-
* @note called in the contex of USBPhy::process
110-
*/
111-
virtual void ep0_setup() = 0;
112-
113-
/**
114-
* Callback called when an endpoint 0 out packet is received
115-
* @note called in the contex of USBPhy::process
116-
*/
117-
virtual void ep0_out() = 0;
118-
119-
/**
120-
* Callback called when an endpoint 0 in packet is received
121-
* @note called in the contex of USBPhy::process
122-
*/
123-
virtual void ep0_in() = 0;
124-
125-
/**
126-
* Callback called USB power is applied or removed
127-
*
128-
* @param powered true if USB power is present, false otherwise
129-
* @note called in the contex of USBPhy::process
130-
*/
131-
virtual void power(bool powered) = 0;
132-
133-
/**
134-
* Callback called when entering or leaving suspend mode
135-
*
136-
* @param suspended true if entering suspend mode false otherwise
137-
* @note called in the contex of USBPhy::process
138-
*/
139-
virtual void suspend(bool suspended) = 0;
140-
141-
/**
142-
* Callback called on start of frame
143-
*
144-
* @param frame_number The current frame number
145-
* @note This callback is enabled/disabled by
146-
* calling USBPhy::sof_enable / USBPhy::sof_disable
147-
* @note called in the contex of USBPhy::process
148-
*/
149-
virtual void sof(int frame_number) = 0;
150-
151-
/**
152-
* Callback called on the reception of an OUT packet
153-
*
154-
* @param endpoint Endpoint which received the OUT packet
155-
* @note called in the contex of USBPhy::process
156-
*/
157-
virtual void out(usb_ep_t endpoint) = 0;
158-
159-
/**
160-
* Callback called on the transmission of an IN packet
161-
*
162-
* @param endpoint Endpoint which sent the IN packet
163-
* @note called in the contex of USBPhy::process
164-
*/
165-
virtual void in(usb_ep_t endpoint) = 0;
166-
167-
/**
168-
* Callback called to indicate the USB processing needs to be done
169-
*/
170-
virtual void start_process() = 0;
171-
};
172-
17365
class USBPhy {
17466
public:
17567
USBPhy() {};

‎platform/USBPhyEvents.h

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
/* mbed Microcontroller Library
2+
* Copyright (c) 2018-2018 ARM Limited
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#ifndef USBPHY_EVENTS_H
18+
#define USBPHY_EVENTS_H
19+
20+
#include "USBPhyTypes.h"
21+
22+
/** Event handler for USBPhy
23+
*
24+
* This class is the event handler for the USBPhy class. Any events generated
25+
* by USBPhy are passed to this class via the virtual functions.
26+
*
27+
* @ingroup usb_device_core
28+
*
29+
*/
30+
class USBPhyEvents {
31+
public:
32+
USBPhyEvents() {};
33+
virtual ~USBPhyEvents() {};
34+
35+
/**
36+
* Callback called when a bus reset occurs
37+
* @note called in the contex of USBPhy::process
38+
*/
39+
virtual void reset() = 0;
40+
41+
/**
42+
* Callback called when an endpoint 0 setup packet is received
43+
* @note called in the contex of USBPhy::process
44+
*/
45+
virtual void ep0_setup() = 0;
46+
47+
/**
48+
* Callback called when an endpoint 0 out packet is received
49+
* @note called in the contex of USBPhy::process
50+
*/
51+
virtual void ep0_out() = 0;
52+
53+
/**
54+
* Callback called when an endpoint 0 in packet is received
55+
* @note called in the contex of USBPhy::process
56+
*/
57+
virtual void ep0_in() = 0;
58+
59+
/**
60+
* Callback called USB power is applied or removed
61+
*
62+
* @param powered true if USB power is present, false otherwise
63+
* @note called in the contex of USBPhy::process
64+
*/
65+
virtual void power(bool powered) = 0;
66+
67+
/**
68+
* Callback called when entering or leaving suspend mode
69+
*
70+
* @param suspended true if entering suspend mode false otherwise
71+
* @note called in the contex of USBPhy::process
72+
*/
73+
virtual void suspend(bool suspended) = 0;
74+
75+
/**
76+
* Callback called on start of frame
77+
*
78+
* @param frame_number The current frame number
79+
* @note This callback is enabled/disabled by
80+
* calling USBPhy::sof_enable / USBPhy::sof_disable
81+
* @note called in the contex of USBPhy::process
82+
*/
83+
virtual void sof(int frame_number) = 0;
84+
85+
/**
86+
* Callback called on the reception of an OUT packet
87+
*
88+
* @param endpoint Endpoint which received the OUT packet
89+
* @note called in the contex of USBPhy::process
90+
*/
91+
virtual void out(usb_ep_t endpoint) = 0;
92+
93+
/**
94+
* Callback called on the transmission of an IN packet
95+
*
96+
* @param endpoint Endpoint which sent the IN packet
97+
* @note called in the contex of USBPhy::process
98+
*/
99+
virtual void in(usb_ep_t endpoint) = 0;
100+
101+
/**
102+
* Callback called to indicate the USB processing needs to be done
103+
*/
104+
virtual void start_process() = 0;
105+
};
106+
107+
#endif

‎platform/USBPhyTypes.h

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
/* mbed Microcontroller Library
2+
* Copyright (c) 2018-2018 ARM Limited
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#ifndef USBPHY_TYPES_H
18+
#define USBPHY_TYPES_H
19+
20+
#include <stdint.h>
21+
22+
typedef uint8_t usb_ep_t;
23+
24+
typedef enum {
25+
USB_EP_TYPE_CTRL = 0,
26+
USB_EP_TYPE_ISO = 1,
27+
USB_EP_TYPE_BULK = 2,
28+
USB_EP_TYPE_INT = 3
29+
} usb_ep_type_t;
30+
31+
enum {
32+
USB_EP_ATTR_ALLOW_CTRL = 1 << USB_EP_TYPE_CTRL,
33+
USB_EP_ATTR_ALLOW_BULK = 1 << USB_EP_TYPE_BULK,
34+
USB_EP_ATTR_ALLOW_INT = 1 << USB_EP_TYPE_INT,
35+
USB_EP_ATTR_ALLOW_ISO = 1 << USB_EP_TYPE_ISO,
36+
USB_EP_ATTR_ALLOW_ALL = USB_EP_ATTR_ALLOW_CTRL | USB_EP_ATTR_ALLOW_BULK |
37+
USB_EP_ATTR_ALLOW_INT | USB_EP_ATTR_ALLOW_ISO,
38+
39+
USB_EP_ATTR_DIR_IN = 0 << 4,
40+
USB_EP_ATTR_DIR_OUT = 1 << 4,
41+
USB_EP_ATTR_DIR_IN_OR_OUT = 2 << 4,
42+
USB_EP_ATTR_DIR_IN_AND_OUT = 3 << 4,
43+
USB_EP_ATTR_DIR_MASK = 3 << 4
44+
};
45+
typedef uint8_t usb_ep_attr_t;
46+
47+
struct usb_ep_entry_t {
48+
usb_ep_attr_t attributes;
49+
uint8_t byte_cost;
50+
uint16_t base_cost;
51+
};
52+
53+
struct usb_ep_table_t {
54+
uint32_t resources;
55+
usb_ep_entry_t table[16];
56+
};
57+
58+
#endif

‎usb/device/USBDevice/EndpointResolver.h

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,17 @@
2121

2222
#include "USBPhy.h"
2323

24+
/**
25+
* Utility class for resolving endpoints
26+
*
27+
* This class is intended to make the process of
28+
* selecting the correct endpoint from a device endpoint
29+
* table easier. It also provides a verification function
30+
* to check if the device has enough resources for the
31+
* given configuration.
32+
*
33+
* @ingroup usb_device_core
34+
*/
2435
class EndpointResolver {
2536
public:
2637
EndpointResolver(const usb_ep_table_t *table);

0 commit comments

Comments
 (0)