hw/usb/hcd-ehci: Change descriptor addresses to 64-bit with migration compatibility
Change internal EHCI descriptor addresses from uint32_t to uint64_t. The following fields are updated: - EHCIPacket::qtdaddr - EHCIQueue::{qhaddr, qtdaddr} - EHCIState::{a_fetch_addr, p_fetch_addr} Update get_dwords() and put_dwords() to take 64-bit addresses and propagate the type change through the descriptor traversal paths. Adjust NLPTR_GET() to operate on 64-bit values: #define NLPTR_GET(x) ((x) & ~0x1fULL) so that link pointer masking works correctly when descriptor addresses exceed 32-bit space. The previous mask (0xffffffe0) implicitly truncated addresses to 32 bits. This patch does not change the on-wire descriptor layout yet. It only removes the internal 32-bit address limit and prepares for later patches that will add full 64-bit QH/qTD/iTD/siTD support. Update the EHCI trace-events prototypes for QH, qTD, iTD, and siTD to use uint64_t for the address argument and print it with PRIx64. This ensures full 64-bit addresses are shown in trace output and improves debugging of queue heads and transfer descriptors. Migration compatibility: To preserve backward migration compatibility, keep the legacy 32-bit fetch address fields (a_fetch_addr_32, p_fetch_addr_32) alongside the new 64-bit fields. Migration format is selected using a machine compat property "x-migrate-fetch-addr-64bit": - Old machine types migrate 32-bit fetch addresses - New machine types migrate full 64-bit fetch addresses This is implemented using VMSTATE_UINT32_TEST() and VMSTATE_UINT64_TEST() so that only the appropriate format is migrated. In pre_save, the 32-bit shadow fields are populated when migrating to old machine types. In post_load, the 32-bit values are restored into the 64-bit fields when loading old migration streams. No functional change. Signed-off-by: Jamin Lin <jamin_lin@aspeedtech.com> Reviewed-by: Cédric Le Goater <clg@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com> Link: https://lore.kernel.org/qemu-devel/20260713032704.3583103-2-jamin_lin@aspeedtech.com Signed-off-by: Cédric Le Goater <clg@redhat.com>
Jamin Lin committed
Jul 13, 2026 at 03:27 UTC
38ed803aebb29ceebcc3e87b0b0d80114b9aa94c
4 files changed
+89
-41
hw/core/machine.c
+2
@@ -51,6 +51,8 @@ GlobalProperty hw_compat_11_0[] = {
51
{ TYPE_ARM_SMMUV3, "ssidsize", "0" },
52
{ TYPE_ARM_SMMUV3, "oas", "44" },
53
{ "migration", "switchover-ack-legacy", "on" },
54
+ { "sysbus-ehci-usb", "x-migrate-fetch-addr-64bit", "off" },
55
+ { "pci-ehci-usb", "x-migrate-fetch-addr-64bit", "off" },
56
};
57
const size_t hw_compat_11_0_len = G_N_ELEMENTS(hw_compat_11_0);
58
hw/usb/hcd-ehci.c
+52
-22
@@ -72,7 +72,7 @@ typedef enum {
72
} EHCI_STATES;
73
74
/* macros for accessing fields within next link pointer entry */
75
-#define NLPTR_GET(x) ((x) & 0xffffffe0)
75
+#define NLPTR_GET(x) ((x) & ~0x1fULL)
76
#define NLPTR_TYPE_GET(x) (((x) >> 1) & 3)
77
#define NLPTR_TBIT(x) ((x) & 1) /* 1=invalid, 0=valid */
78
@@ -287,7 +287,7 @@ static int ehci_get_state(EHCIState *s, int async)
287
return async ? s->astate : s->pstate;
288
}
289
290
-static void ehci_set_fetch_addr(EHCIState *s, int async, uint32_t addr)
290
+static void ehci_set_fetch_addr(EHCIState *s, int async, uint64_t addr)
291
{
292
if (async) {
293
s->a_fetch_addr = addr;
@@ -296,7 +296,7 @@ static void ehci_set_fetch_addr(EHCIState *s, int async, uint32_t addr)
296
}
297
}
298
299
-static int ehci_get_fetch_addr(EHCIState *s, int async)
299
+static uint64_t ehci_get_fetch_addr(EHCIState *s, int async)
300
{
301
return async ? s->a_fetch_addr : s->p_fetch_addr;
302
}
@@ -373,7 +373,7 @@ static inline bool ehci_periodic_enabled(EHCIState *s)
373
}
374
375
/* Get an array of dwords from main memory */
376
-static inline int get_dwords(EHCIState *ehci, uint32_t addr,
376
+static inline int get_dwords(EHCIState *ehci, uint64_t addr,
377
uint32_t *buf, int num)
378
{
379
int i;
@@ -395,7 +395,7 @@ static inline int get_dwords(EHCIState *ehci, uint32_t addr,
395
}
396
397
/* Put an array of dwords in to main memory */
398
-static inline int put_dwords(EHCIState *ehci, uint32_t addr,
398
+static inline int put_dwords(EHCIState *ehci, uint64_t addr,
399
uint32_t *buf, int num)
400
{
401
int i;
@@ -549,7 +549,7 @@ static void ehci_free_packet(EHCIPacket *p)
549
550
/* queue management */
551
552
-static EHCIQueue *ehci_alloc_queue(EHCIState *ehci, uint32_t addr, int async)
552
+static EHCIQueue *ehci_alloc_queue(EHCIState *ehci, uint64_t addr, int async)
553
{
554
EHCIQueueHead *head = async ? &ehci->aqueues : &ehci->pqueues;
555
EHCIQueue *q;
@@ -622,7 +622,7 @@ static void ehci_free_queue(EHCIQueue *q, const char *warn)
622
g_free(q);
623
}
624
625
-static EHCIQueue *ehci_find_queue_by_qh(EHCIState *ehci, uint32_t addr,
625
+static EHCIQueue *ehci_find_queue_by_qh(EHCIState *ehci, uint64_t addr,
626
int async)
627
{
628
EHCIQueueHead *head = async ? &ehci->aqueues : &ehci->pqueues;
@@ -1135,7 +1135,7 @@ static void ehci_flush_qh(EHCIQueue *q)
1135
{
1136
uint32_t *qh = (uint32_t *) &q->qh;
1137
uint32_t dwords = sizeof(EHCIqh) >> 2;
1138
- uint32_t addr = NLPTR_GET(q->qhaddr);
1138
+ uint64_t addr = NLPTR_GET(q->qhaddr);
1139
1140
put_dwords(q->ehci, addr + 3 * sizeof(uint32_t), qh + 3, dwords - 3);
1141
}
@@ -1406,12 +1406,13 @@ static int ehci_execute(EHCIPacket *p, const char *action)
1406
/* 4.7.2 */
1407
static int ehci_process_itd(EHCIState *ehci,
1408
EHCIitd *itd,
1409
- uint32_t addr)
1409
+ uint64_t addr)
1410
{
1411
USBDevice *dev;
1412
USBEndpoint *ep;
1413
uint32_t i, len, pid, dir, devaddr, endp;
1414
- uint32_t pg, off, ptr1, ptr2, max, mult;
1414
+ uint32_t pg, off, max, mult;
1415
+ uint64_t ptr1, ptr2;
1416
1417
ehci->periodic_sched_active = PERIODIC_ACTIVE;
1418
@@ -1528,7 +1529,7 @@ static int ehci_state_waitlisthead(EHCIState *ehci, int async)
1529
EHCIqh qh;
1530
int i = 0;
1531
int again = 0;
1531
- uint32_t entry = ehci->asynclistaddr;
1532
+ uint64_t entry = ehci->asynclistaddr;
1533
1534
/* set reclamation flag at start event (4.8.6) */
1535
if (async) {
@@ -1578,7 +1579,7 @@ out:
1579
static int ehci_state_fetchentry(EHCIState *ehci, int async)
1580
{
1581
int again = 0;
1581
- uint32_t entry = ehci_get_fetch_addr(ehci, async);
1582
+ uint64_t entry = ehci_get_fetch_addr(ehci, async);
1583
1584
if (NLPTR_TBIT(entry)) {
1585
ehci_set_state(ehci, async, EST_ACTIVE);
@@ -1611,8 +1612,8 @@ static int ehci_state_fetchentry(EHCIState *ehci, int async)
1612
default:
1613
/* TODO: handle FSTN type */
1614
qemu_log_mask(LOG_GUEST_ERROR,
1614
- "FETCHENTRY: entry at 0x%x is of type %u "
1615
- "which is not supported yet\n",
1615
+ "FETCHENTRY: entry at %" PRIx64 " is of type %" PRIu64
1616
+ " which is not supported yet\n",
1617
entry, NLPTR_TYPE_GET(entry));
1618
return -1;
1619
}
@@ -1623,7 +1624,7 @@ out:
1624
1625
static EHCIQueue *ehci_state_fetchqh(EHCIState *ehci, int async)
1626
{
1626
- uint32_t entry;
1627
+ uint64_t entry;
1628
EHCIQueue *q;
1629
EHCIqh qh;
1630
@@ -1712,7 +1713,7 @@ out:
1713
1714
static int ehci_state_fetchitd(EHCIState *ehci, int async)
1715
{
1715
- uint32_t entry;
1716
+ uint64_t entry;
1717
EHCIitd itd;
1718
1719
assert(!async);
@@ -1738,7 +1739,7 @@ static int ehci_state_fetchitd(EHCIState *ehci, int async)
1739
1740
static int ehci_state_fetchsitd(EHCIState *ehci, int async)
1741
{
1741
- uint32_t entry;
1742
+ uint64_t entry;
1743
EHCIsitd sitd;
1744
1745
assert(!async);
@@ -1802,7 +1803,7 @@ static int ehci_state_fetchqtd(EHCIQueue *q)
1803
EHCIqtd qtd;
1804
EHCIPacket *p;
1805
int again = 1;
1805
- uint32_t addr;
1806
+ uint64_t addr;
1807
1808
addr = NLPTR_GET(q->qtdaddr);
1809
if (get_dwords(q->ehci, addr + 8, &qtd.token, 1) < 0) {
@@ -1885,7 +1886,7 @@ static int ehci_fill_queue(EHCIPacket *p)
1886
USBEndpoint *ep = p->packet.ep;
1887
EHCIQueue *q = p->queue;
1888
EHCIqtd qtd = p->qtd;
1888
- uint32_t qtdaddr;
1889
+ uint64_t qtdaddr;
1890
1891
for (;;) {
1892
if (NLPTR_TBIT(qtd.next) != 0) {
@@ -2008,7 +2009,8 @@ static int ehci_state_executing(EHCIQueue *q)
2009
static int ehci_state_writeback(EHCIQueue *q)
2010
{
2011
EHCIPacket *p = QTAILQ_FIRST(&q->packets);
2011
- uint32_t *qtd, addr;
2012
+ uint32_t *qtd;
2013
+ uint64_t addr;
2014
int again = 0;
2015
2016
/* Write back the QTD from the QH area */
@@ -2414,6 +2416,18 @@ static USBBusOps ehci_bus_ops_standalone = {
2416
.wakeup_endpoint = ehci_wakeup_endpoint,
2417
};
2418
2419
+static bool ehci_fetch_addr_64_needed(void *opaque, int version_id)
2420
+{
2421
+ EHCIState *s = opaque;
2422
+
2423
+ return s->migrate_fetch_addr_64bit;
2424
+}
2425
+
2426
+static bool ehci_fetch_addr_32_needed(void *opaque, int version_id)
2427
+{
2428
+ return !ehci_fetch_addr_64_needed(opaque, version_id);
2429
+}
2430
+
2431
static int usb_ehci_pre_save(void *opaque)
2432
{
2433
EHCIState *ehci = opaque;
@@ -2424,6 +2438,11 @@ static int usb_ehci_pre_save(void *opaque)
2438
ehci->last_run_ns -= (ehci->frindex - new_frindex) * UFRAME_TIMER_NS;
2439
ehci->frindex = new_frindex;
2440
2441
+ if (!ehci->migrate_fetch_addr_64bit) {
2442
+ ehci->migrate_a_fetch_addr = ehci->a_fetch_addr;
2443
+ ehci->migrate_p_fetch_addr = ehci->p_fetch_addr;
2444
+ }
2445
+
2446
return 0;
2447
}
2448
@@ -2444,6 +2463,11 @@ static int usb_ehci_post_load(void *opaque, int version_id)
2463
}
2464
}
2465
2466
+ if (!s->migrate_fetch_addr_64bit) {
2467
+ s->a_fetch_addr = s->migrate_a_fetch_addr;
2468
+ s->p_fetch_addr = s->migrate_p_fetch_addr;
2469
+ }
2470
+
2471
return 0;
2472
}
2473
@@ -2504,8 +2528,14 @@ const VMStateDescription vmstate_ehci = {
2528
/* schedule state */
2529
VMSTATE_UINT32(astate, EHCIState),
2530
VMSTATE_UINT32(pstate, EHCIState),
2507
- VMSTATE_UINT32(a_fetch_addr, EHCIState),
2508
- VMSTATE_UINT32(p_fetch_addr, EHCIState),
2531
+ VMSTATE_UINT32_TEST(migrate_a_fetch_addr, EHCIState,
2532
+ ehci_fetch_addr_32_needed),
2533
+ VMSTATE_UINT32_TEST(migrate_p_fetch_addr, EHCIState,
2534
+ ehci_fetch_addr_32_needed),
2535
+ VMSTATE_UINT64_TEST(a_fetch_addr, EHCIState,
2536
+ ehci_fetch_addr_64_needed),
2537
+ VMSTATE_UINT64_TEST(p_fetch_addr, EHCIState,
2538
+ ehci_fetch_addr_64_needed),
2539
VMSTATE_END_OF_LIST()
2540
}
2541
};
hw/usb/hcd-ehci.h
+23
-7
@@ -208,7 +208,7 @@ struct EHCIPacket {
208
QTAILQ_ENTRY(EHCIPacket) next;
209
210
EHCIqtd qtd; /* copy of current QTD (being worked on) */
211
- uint32_t qtdaddr; /* address QTD read from */
211
+ uint64_t qtdaddr; /* address QTD read from */
212
213
USBPacket packet;
214
QEMUSGList sgl;
@@ -229,8 +229,8 @@ struct EHCIQueue {
229
* when guest removes an entry (doorbell, handshake sequence)
230
*/
231
EHCIqh qh; /* copy of current QH (being worked on) */
232
- uint32_t qhaddr; /* address QH read from */
233
- uint32_t qtdaddr; /* address QTD read from */
232
+ uint64_t qhaddr; /* address QH read from */
233
+ uint64_t qtdaddr; /* address QTD read from */
234
int last_pid; /* pid of last packet executed */
235
USBDevice *dev;
236
QTAILQ_HEAD(, EHCIPacket) packets;
@@ -256,6 +256,11 @@ struct EHCIState {
256
257
/* properties */
258
uint32_t maxframes;
259
+ /*
260
+ * Controls migration stream compatibility for old machine types.
261
+ * Old machine types only transfer 32-bit fetch addresses.
262
+ */
263
+ bool migrate_fetch_addr_64bit;
264
265
/*
266
* EHCI spec version 1.0 Section 2.3
@@ -293,9 +298,18 @@ struct EHCIState {
298
EHCIQueueHead aqueues;
299
EHCIQueueHead pqueues;
300
296
- /* which address to look at next */
297
- uint32_t a_fetch_addr;
298
- uint32_t p_fetch_addr;
301
+ /*
302
+ * which address to look at next
303
+ *
304
+ * Migration compatibility fields for old machine types that only
305
+ * support 32-bit fetch addresses in the migration stream.
306
+ *
307
+ * New machine types migrate the full 64-bit runtime fetch address.
308
+ */
309
+ uint32_t migrate_a_fetch_addr;
310
+ uint32_t migrate_p_fetch_addr;
311
+ uint64_t a_fetch_addr;
312
+ uint64_t p_fetch_addr;
313
314
USBPacket ipacket;
315
QEMUSGList isgl;
@@ -308,7 +322,9 @@ struct EHCIState {
322
};
323
324
#define DEFINE_EHCI_COMMON_PROPERTIES(_state) \
311
- DEFINE_PROP_UINT32("maxframes", _state, ehci.maxframes, 128)
325
+ DEFINE_PROP_UINT32("maxframes", _state, ehci.maxframes, 128), \
326
+ DEFINE_PROP_BOOL("x-migrate-fetch-addr-64bit", _state, \
327
+ ehci.migrate_fetch_addr_64bit, true)
328
329
extern const VMStateDescription vmstate_ehci;
330
hw/usb/trace-events
+12
-12
@@ -86,15 +86,15 @@ usb_ehci_portsc_write(uint32_t addr, uint32_t port, uint32_t val) "wr mmio 0x%04
86
usb_ehci_portsc_change(uint32_t addr, uint32_t port, uint32_t new, uint32_t old) "ch mmio 0x%04x [port %d] = 0x%x (old: 0x%x)"
87
usb_ehci_usbsts(const char *sts, int state) "usbsts %s %d"
88
usb_ehci_state(const char *schedule, const char *state) "%s schedule %s"
89
-usb_ehci_qh_ptrs(void *q, uint32_t addr, uint32_t nxt, uint32_t c_qtd, uint32_t n_qtd, uint32_t a_qtd) "q %p - QH @ 0x%08x: next 0x%08x qtds 0x%08x,0x%08x,0x%08x"
90
-usb_ehci_qh_fields(uint32_t addr, int rl, int mplen, int eps, int ep, int devaddr) "QH @ 0x%08x - rl %d, mplen %d, eps %d, ep %d, dev %d"
91
-usb_ehci_qh_bits(uint32_t addr, int c, int h, int dtc, int i) "QH @ 0x%08x - c %d, h %d, dtc %d, i %d"
89
+usb_ehci_qh_ptrs(void *q, uint64_t addr, uint32_t nxt, uint32_t c_qtd, uint32_t n_qtd, uint32_t a_qtd) "q %p - QH @ 0x%" PRIx64 ": next 0x%08x qtds 0x%08x,0x%08x,0x%08x"
90
+usb_ehci_qh_fields(uint64_t addr, int rl, int mplen, int eps, int ep, int devaddr) "QH @ 0x%" PRIx64 " - rl %d, mplen %d, eps %d, ep %d, dev %d"
91
+usb_ehci_qh_bits(uint64_t addr, int c, int h, int dtc, int i) "QH @ 0x%" PRIx64 " - c %d, h %d, dtc %d, i %d"
92
usb_ehci_qh_tbytes(uint32_t tbytes) "updating tbytes to %d"
93
-usb_ehci_qtd_ptrs(void *q, uint32_t addr, uint32_t nxt, uint32_t altnext) "q %p - QTD @ 0x%08x: next 0x%08x altnext 0x%08x"
94
-usb_ehci_qtd_fields(uint32_t addr, int tbytes, int cpage, int cerr, int pid) "QTD @ 0x%08x - tbytes %d, cpage %d, cerr %d, pid %d"
95
-usb_ehci_qtd_bits(uint32_t addr, int ioc, int active, int halt, int babble, int xacterr) "QTD @ 0x%08x - ioc %d, active %d, halt %d, babble %d, xacterr %d"
96
-usb_ehci_itd(uint32_t addr, uint32_t nxt, uint32_t mplen, uint32_t mult, uint32_t ep, uint32_t devaddr) "ITD @ 0x%08x: next 0x%08x - mplen %d, mult %d, ep %d, dev %d"
97
-usb_ehci_sitd(uint32_t addr, uint32_t nxt, uint32_t active) "ITD @ 0x%08x: next 0x%08x - active %d"
93
+usb_ehci_qtd_ptrs(void *q, uint64_t addr, uint32_t nxt, uint32_t altnext) "q %p - QTD @ 0x%" PRIx64 ": next 0x%08x altnext 0x%08x"
94
+usb_ehci_qtd_fields(uint64_t addr, int tbytes, int cpage, int cerr, int pid) "QTD @ 0x%" PRIx64 " - tbytes %d, cpage %d, cerr %d, pid %d"
95
+usb_ehci_qtd_bits(uint64_t addr, int ioc, int active, int halt, int babble, int xacterr) "QTD @ 0x%" PRIx64 " - ioc %d, active %d, halt %d, babble %d, xacterr %d"
96
+usb_ehci_itd(uint64_t addr, uint32_t nxt, uint32_t mplen, uint32_t mult, uint32_t ep, uint32_t devaddr) "ITD @ 0x%" PRIx64 ": next 0x%08x - mplen %d, mult %d, ep %d, dev %d"
97
+usb_ehci_sitd(uint64_t addr, uint32_t nxt, uint32_t active) "SITD @ 0x%" PRIx64 ": next 0x%08x - active %d"
98
usb_ehci_port_attach(uint32_t port, const char *owner, const char *device) "attach port #%d, owner %s, device %s"
99
usb_ehci_port_detach(uint32_t port, const char *owner) "detach port #%d, owner %s"
100
usb_ehci_port_reset(uint32_t port, int enable) "reset port #%d - %d"
@@ -104,15 +104,15 @@ usb_ehci_port_resume(uint32_t port) "port #%d"
104
usb_ehci_port_disable(uint32_t port) "port #%d"
105
usb_ehci_queue_action(void *q, const char *action) "q %p: %s"
106
usb_ehci_packet_action(void *q, void *p, const char *action) "q %p p %p: %s"
107
-usb_ehci_packet_submit(uint32_t qhaddr, uint32_t next, uint32_t qtdaddr, int pid, size_t len, int endp, int status, int actual_length) "qh=0x%x, next=0x%x, qtd=0x%x, pid=0x%x, len=%zd, endp=0x%x, status=%d, actual_length=%d"
107
+usb_ehci_packet_submit(uint64_t qhaddr, uint32_t next, uint64_t qtdaddr, int pid, size_t len, int endp, int status, int actual_length) "qh=0x%" PRIx64 ", next=0x%x, qtd=0x%" PRIx64 ", pid=0x%x, len=%zd, endp=0x%x, status=%d, actual_length=%d"
108
usb_ehci_irq(uint32_t level, uint32_t frindex, uint32_t sts, uint32_t mask) "level %d, frindex 0x%04x, sts 0x%x, mask 0x%x"
109
usb_ehci_guest_bug(const char *reason) "%s"
110
usb_ehci_doorbell_ring(void) ""
111
usb_ehci_doorbell_ack(void) ""
112
usb_ehci_dma_error(void) ""
113
-usb_ehci_execute_complete(uint32_t qhaddr, uint32_t next, uint32_t qtdaddr, int status, int actual_length) "qhaddr=0x%x, next=0x%x, qtdaddr=0x%x, status=%d, actual_length=%d"
114
-usb_ehci_fetchqh_reclaim_done(uint32_t qhaddr) "QH 0x%08x H-bit set, reclamation status reset - done processing"
115
-usb_ehci_fetchqh_dbg(uint32_t qhaddr, uint32_t h, uint32_t halt, uint32_t active, uint32_t next) "QH 0x%08x (h 0x%x halt 0x%x active 0x%x) next 0x%08x"
113
+usb_ehci_execute_complete(uint64_t qhaddr, uint32_t next, uint64_t qtdaddr, int status, int actual_length) "qhaddr=0x%" PRIx64 ", next=0x%x, qtdaddr=0x%" PRIx64 ", status=%d, actual_length=%d"
114
+usb_ehci_fetchqh_reclaim_done(uint64_t qhaddr) "QH 0x%" PRIx64 " H-bit set, reclamation status reset - done processing"
115
+usb_ehci_fetchqh_dbg(uint64_t qhaddr, uint32_t h, uint32_t halt, uint32_t active, uint32_t next) "QH 0x%" PRIx64 " (h 0x%x halt 0x%x active 0x%x) next 0x%08x"
116
usb_ehci_periodic_state_advance(uint32_t frame, uint32_t list, uint32_t entry) "frame=%d, list=0x%x, entry=0x%x"
117
usb_ehci_skipped_uframes(uint64_t skipped_uframes) "skipped %" PRIu64 " uframes"
118
usb_ehci_log(const char *msg) "%s"