usb patch queue
Hi,
Here comes the usb patch queue. It has a number of fixes, mostly for xhci, and removes the old, pre-libusbx usb-host code.
please pull,
Gerd
The following changes since commit 6c2679fc19560699679200fb42ab4659bcbe7f79:
Merge remote-tracking branch 'kiszka/queues/slirp' into staging (2013-09-17 10:01:24 -0500)
are available in the git repository at:
git://git.kraxel.org/qemu usb.90
for you to fetch changes up to 0ca6db4f3b3df5c4e5285a48a7709bdced5068de:
usb: Fix iovec memleak on combined-packet free (2013-09-19 11:28:40 +0200)
----------------------------------------------------------------
Gerd Hoffmann (1):
usb: remove old usb-host code
Hans de Goede (6):
xhci: Fix number of streams allocated when using streams
xhci: Init a transfers xhci, slotid and epid member on epctx alloc
xhci: Add xhci_epid_to_usbep helper function
xhci: Fix memory leak on xhci_disable_ep
usb: Also reset max_packet_size on ep_reset
usb: Fix iovec memleak on combined-packet free
configure | 26 +- hw/usb/combined-packet.c | 1 + hw/usb/core.c | 3 + hw/usb/hcd-xhci.c | 45 +- hw/usb/host-bsd.c | 639 ---------------- hw/usb/host-linux.c | 1911 ---------------------------------------------- 6 files changed, 39 insertions(+), 2586 deletions(-) delete mode 100644 hw/usb/host-bsd.c delete mode 100644 hw/usb/host-linux.c
PATCH 1/7 usb: remove old usb-host code
The usb-host code has been rewritten for qemu 1.5 to use libusb, the old code has been left in as temporary fallback. Now we are two releases further out, targeting the 1.7 release. No major issues with the new code poped up until now. Time to remove it from tre tree. Should we ever need it again for some reason -- git has a copy for us in the history.
--- configure | 26 +- hw/usb/host-bsd.c | 639 ----------------- hw/usb/host-linux.c | 1911 --------------------------------------------------- 3 files changed, 4 insertions(+), 2572 deletions(-) delete mode 100644 hw/usb/host-bsd.c delete mode 100644 hw/usb/host-linux.c
configure +4 -22
@@ -562,7 +562,6 @@ Haiku) audio_possible_drivers="oss alsa sdl esd pa" linux="yes" linux_user="yes" - usb="linux" kvm="yes" vhost_net="yes" vhost_scsi="yes"
@@ -575,9 +574,6 @@ esac if [ "$bsd" = "yes" ] ; then if [ "$darwin" != "yes" ] ; then - if [ "$targetos" != "FreeBSD" ]; then - usb="bsd" - fi bsd_user="yes" fi fi
@@ -3126,7 +3122,6 @@ fi if test "$libusb" != "no" ; then if $pkg_config --atleast-version=1.0.13 libusb-1.0; then libusb="yes" - usb="libusb" libusb_cflags=$($pkg_config --cflags libusb-1.0) libusb_libs=$($pkg_config --libs libusb-1.0) QEMU_CFLAGS="$QEMU_CFLAGS $libusb_cflags"
@@ -4166,24 +4161,11 @@ if test "$virtio_blk_data_plane" = "yes" ; then fi # USB host support -case "$usb" in -linux) - echo "HOST_USB=linux legacy" >> $config_host_mak -;; -bsd) - echo "HOST_USB=bsd" >> $config_host_mak -;; -libusb) - if test "$linux" = "yes"; then - echo "HOST_USB=libusb linux legacy" >> $config_host_mak - else - echo "HOST_USB=libusb legacy" >> $config_host_mak - fi -;; -*) +if test "$libusb" = "yes"; then + echo "HOST_USB=libusb legacy" >> $config_host_mak +else echo "HOST_USB=stub" >> $config_host_mak -;; -esac +fi # TPM passthrough support? if test "$tpm" = "yes"; then
hw/usb/host-bsd.c deleted +0 -639
639 lines not on this page · raw message
hw/usb/host-linux.c deleted +0 -1911
1,911 lines not on this page · raw message
Signature · 1 line
1.8.3.1
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Quoted 6 lines · Gerd Hoffmann
The usb-host code has been rewritten for qemu 1.5 to use libusb, the old code has been left in as temporary fallback. Now we are two releases further out, targeting the 1.7 release. No major issues with the new code poped up until now. Time to remove it from tre tree. Should we ever need it again for some reason -- git has a copy for us in the history.
Well, maybe not many users were actually exploiting the new libusb code, thus were able to produce feedback.
Only very recent distros fulfill the need of >= 1.0.13, so you naturally fall back to this code. I just realized that even the factory build of OpenSUSE is still on libusb-1.0.9. Current Ubuntu versions are on 1.0.12 at best. Didn't check others so far.
So isn't this step a bit too early?
Jan
Signature · 2 lines
Siemens AG, Corporate Technology, CT RTC ITP SES-DE Corporate Competence Center Embedded Linux
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Quoted 8 lines · Jan Kiszka
Quoted 6 lines · Gerd Hoffmann
The usb-host code has been rewritten for qemu 1.5 to use libusb, the old code has been left in as temporary fallback. Now we are two releases further out, targeting the 1.7 release. No major issues with the new code poped up until now. Time to remove it from tre tree. Should we ever need it again for some reason -- git has a copy for us in the history.
Quoted 7 lines
Well, maybe not many users were actually exploiting the new libusb code, thus were able to produce feedback.
Only very recent distros fulfill the need of >= 1.0.13, so you naturally fall back to this code. I just realized that even the factory build of OpenSUSE is still on libusb-1.0.9. Current Ubuntu versions are on 1.0.12 at best. Didn't check others so far.
Ouch. The 1.0.13 release is one year old by now.
Fedora 19 is at 1.0.16 btw.
Quoted 1 line
So isn't this step a bit too early?
There is always the 'git revert' option in case it turns out there are too many issues ...
cheers,
Gerd
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Quoted 17 lines · Gerd Hoffmann
Quoted 8 lines · Jan Kiszka
Quoted 6 lines · Gerd Hoffmann
The usb-host code has been rewritten for qemu 1.5 to use libusb, the old code has been left in as temporary fallback. Now we are two releases further out, targeting the 1.7 release. No major issues with the new code poped up until now. Time to remove it from tre tree. Should we ever need it again for some reason -- git has a copy for us in the history.
Quoted 7 lines
Well, maybe not many users were actually exploiting the new libusb code, thus were able to produce feedback.
Only very recent distros fulfill the need of >= 1.0.13, so you naturally fall back to this code. I just realized that even the factory build of OpenSUSE is still on libusb-1.0.9. Current Ubuntu versions are on 1.0.12 at best. Didn't check others so far.
Quoted 8 lines
Ouch. The 1.0.13 release is one year old by now.
Fedora 19 is at 1.0.16 btw.
Quoted 1 line
So isn't this step a bit too early?
There is always the 'git revert' option in case it turns out there are too many issues ...
So what to do? Do you expect all the other distros to catch up regarding libusb until QEMU 1.7 is released?
Jan
Signature · 2 lines
Siemens AG, Corporate Technology, CT RTC ITP SES-DE Corporate Competence Center Embedded Linux
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Hi,
Quoted 9 lines
Quoted 9 lines
Quoted 4 lines
Only very recent distros fulfill the need of >= 1.0.13, so you naturally fall back to this code. I just realized that even the factory build of OpenSUSE is still on libusb-1.0.9. Current Ubuntu versions are on 1.0.12 at best. Didn't check others so far.
Ouch. The 1.0.13 release is one year old by now.
Fedora 19 is at 1.0.16 btw.
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
So isn't this step a bit too early?
There is always the 'git revert' option in case it turns out there are too many issues ...
So what to do? Do you expect all the other distros to catch up regarding libusb until QEMU 1.7 is released?
They will update once they figure this is needed for qemu 1.7 :) Updates will probably not yet be available at release time though.
If we revert, thereby continue fallback to the old code, chances are high that nothing happens and we'll face the same issue for qemu 1.8.
Given that there are some known issues in the host-linux code which are fixed in host-libusb I really want get rid of it.
cheers,
Gerd
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Quoted 19 lines · Gerd Hoffmann
Hi,
Quoted 9 lines
Quoted 9 lines
Quoted 4 lines
Only very recent distros fulfill the need of >= 1.0.13, so you naturally fall back to this code. I just realized that even the factory build of OpenSUSE is still on libusb-1.0.9. Current Ubuntu versions are on 1.0.12 at best. Didn't check others so far.
Ouch. The 1.0.13 release is one year old by now.
Fedora 19 is at 1.0.16 btw.
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
So isn't this step a bit too early?
There is always the 'git revert' option in case it turns out there are too many issues ...
So what to do? Do you expect all the other distros to catch up regarding libusb until QEMU 1.7 is released?
Quoted 8 lines
They will update once they figure this is needed for qemu 1.7 :) Updates will probably not yet be available at release time though.
If we revert, thereby continue fallback to the old code, chances are high that nothing happens and we'll face the same issue for qemu 1.8.
Given that there are some known issues in the host-linux code which are fixed in host-libusb I really want get rid of it.
OK, then here is the first issue I ran into while trying libusbx (git head, i.e. 1.0.17+: The new stack causes significant latency issues that makes it almost unusable for pass-through of USB audio devices (some headset in my case). Reverting usb-linux and disabling libusb over QEMU git head makes things work again. I'll have to stick with this for now as it is affecting my work environment.
Any spontaneous ideas how to analyse or even resolve this?
Jan
Signature · 2 lines
Siemens AG, Corporate Technology, CT RTC ITP SES-DE Corporate Competence Center Embedded Linux
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Hi,
Quoted 8 lines
OK, then here is the first issue I ran into while trying libusbx (git head, i.e. 1.0.17+: The new stack causes significant latency issues that makes it almost unusable for pass-through of USB audio devices (some headset in my case). Reverting usb-linux and disabling libusb over QEMU git head makes things work again. I'll have to stick with this for now as it is affecting my work environment.
Any spontaneous ideas how to analyse or even resolve this?
Try setting isobsize property to something smaller than 32 (which is the default).
cheers,
Gerd
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Quoted 9 lines · Gerd Hoffmann
Hi,
Quoted 7 lines
OK, then here is the first issue I ran into while trying libusbx (git head, i.e. 1.0.17+: The new stack causes significant latency issues that makes it almost unusable for pass-through of USB audio devices (some headset in my case). Reverting usb-linux and disabling libusb over QEMU git head makes things work again. I'll have to stick with this for now as it is affecting my work environment.
Quoted 4 lines
Quoted 1 line
Any spontaneous ideas how to analyse or even resolve this?
Try setting isobsize property to something smaller than 32 (which is the default).
OK, isobsize=2 and isobufs=32 helped, possibly other combinations as well - but not just reducing isobsize or increasing isobufs. Any theory about this? How can we find better defaults?
Jan
Signature · 2 lines
Siemens AG, Corporate Technology, CT RTC ITP SES-DE Corporate Competence Center Embedded Linux
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Quoted 10 lines · Jan Kiszka
Quoted 9 lines · Gerd Hoffmann
Hi,
Quoted 7 lines
OK, then here is the first issue I ran into while trying libusbx (git head, i.e. 1.0.17+: The new stack causes significant latency issues that makes it almost unusable for pass-through of USB audio devices (some headset in my case). Reverting usb-linux and disabling libusb over QEMU git head makes things work again. I'll have to stick with this for now as it is affecting my work environment.
Quoted 8 lines
Quoted 4 lines
Quoted 1 line
Any spontaneous ideas how to analyse or even resolve this?
Try setting isobsize property to something smaller than 32 (which is the default).
OK, isobsize=2 and isobufs=32 helped, possibly other combinations as well - but not just reducing isobsize or increasing isobufs. Any theory about this? How can we find better defaults?
isobsize is the size of a single buffer (in MaxPacketSize units). isobufs is the number of buffers in the ring.
So the total ring buffer size is MaxPacketSize * isobsize * isobufs.
isobsize basically trades overhead for latency. Larger numbers reduce the overhead, smaller numbers reduce latency.
isobufs should be as small as possible. Start with 4 (default). If you get overruns/underruns increase.
We should probably look at the endpoint interval, then calculate how many packets we should expect within a certain time range and use that as additional factor for the buffer size. That should get the defaults closer to the actual needs of the device.
cheers,
Gerd
Re: [Qemu-devel] [PATCH 1/7] usb: remove old usb-host code
Hi,
Quoted 28 lines · Gerd Hoffmann
Quoted 10 lines · Jan Kiszka
Quoted 9 lines · Gerd Hoffmann
Hi,Quoted 7 lines
OK, then here is the first issue I ran into while trying libusbx (git head, i.e. 1.0.17+: The new stack causes significant latency issues that makes it almost unusable for pass-through of USB audio devices (some headset in my case). Reverting usb-linux and disabling libusb over QEMU git head makes things work again. I'll have to stick with this for now as it is affecting my work environment.
Quoted 8 lines
Quoted 4 lines
Quoted 1 line
Any spontaneous ideas how to analyse or even resolve this?
Try setting isobsize property to something smaller than 32 (which is the default).
OK, isobsize=2 and isobufs=32 helped, possibly other combinations as well - but not just reducing isobsize or increasing isobufs. Any theory about this? How can we find better defaults?
isobsize is the size of a single buffer (in MaxPacketSize units). isobufs is the number of buffers in the ring.
So the total ring buffer size is MaxPacketSize * isobsize * isobufs.
isobsize basically trades overhead for latency. Larger numbers reduce the overhead, smaller numbers reduce latency.
Quoted 7 lines
isobufs should be as small as possible. Start with 4 (default). If you get overruns/underruns increase.
We should probably look at the endpoint interval, then calculate how many packets we should expect within a certain time range and use that as additional factor for the buffer size. That should get the defaults closer to the actual needs of the device.
hw/usb/redirect.c actually has some code for that, you could use that as a start for the host redirection code...
Regards,
Hans
PATCH 2/7 xhci: Fix number of streams allocated when using streams
In reply to Gerd HoffmannFrom: Hans de Goede <[email protected]>
According to the xhci spec the total number of streams is 2 ^ (MaxPStreams + 1), and this is also how the Linux xhci driver uses this field.
--- hw/usb/hcd-xhci.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
hw/usb/hcd-xhci.c +1 -1
@@ -1138,7 +1138,7 @@ static void xhci_reset_streams(XHCIEPContext *epctx)static void xhci_alloc_streams (XHCIEPContext *epctx,dma_addr_t base) {assert (epctx->pstreams ==NULL ); - epctx->nr_pstreams =2 << epctx->max_pstreams; + epctx->nr_pstreams =2 << (epctx->max_pstreams +1 ); epctx->pstreams =xhci_alloc_stream_contexts (epctx->nr_pstreams, base); }
Signature · 1 line
1.8.3.1
PATCH 3/7 xhci: Init a transfers xhci, slotid and epid member on epctx alloc
In reply to Gerd HoffmannFrom: Hans de Goede <[email protected]>
Transfers are part of an epctx, which is part of a slot, which is part of a xhci. Transfers cannot dynamically be moved from one epctx to another, so once created their xhci, slotid and epid are constant, so lets set these up at creation time, rather then re-initializing them with the same value each time a transfer gets submitted.
--- hw/usb/hcd-xhci.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
hw/usb/hcd-xhci.c +3 -3
@@ -1245,6 +1245,9 @@ static XHCIEPContext *xhci_alloc_epctx(XHCIState *xhci, epctx->epid = epid;for (i =0 ; i <ARRAY_SIZE (epctx->transfers); i++) { + epctx->transfers[i].xhci = xhci; + epctx->transfers[i].slotid = slotid; + epctx->transfers[i].epid = epid;usb_packet_init (&epctx->transfers[i].packet); } epctx->kick_timer =timer_new_ns (QEMU_CLOCK_VIRTUAL , xhci_ep_kick_timer, epctx);
@@ -2060,9 +2063,6 @@ static void xhci_kick_ep(XHCIState *xhci, unsigned int slotid,for (i =0 ; i < length; i++) {assert (xhci_ring_fetch (xhci, ring, &xfer->trbs[i],NULL )); } - xfer->xhci = xhci; - xfer->epid = epid; - xfer->slotid = slotid; xfer->streamid = streamid;if (epid ==1 ) {
Signature · 1 line
1.8.3.1
PATCH 4/7 xhci: Add xhci_epid_to_usbep helper function
In reply to Gerd HoffmannFrom: Hans de Goede <[email protected]>
And use it instead of prying the USBEndpoint out of the packet struct in various places.
--- hw/usb/hcd-xhci.c | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-)
hw/usb/hcd-xhci.c +22 -10
@@ -509,6 +509,8 @@ static TRBCCode xhci_disable_ep(XHCIState *xhci, unsigned int slotid, unsigned int epid);static void xhci_event (XHCIState *xhci,XHCIEvent *event,int v);static void xhci_write_event (XHCIState *xhci,XHCIEvent *event,int v); +static USBEndpoint *xhci_epid_to_usbep (XHCIState *xhci, +unsigned int slotid,unsigned int epid);static const char *TRBType_names[] = { [TRB_RESERVED ] ="TRB_RESERVED" ,
@@ -1361,13 +1363,12 @@ static int xhci_ep_nuke_xfers(XHCIState *xhci, unsigned int slotid, xferi = epctx->next_xfer;for (i =0 ; i <TD_QUEUE ; i++) { -if (epctx->transfers[xferi].packet.ep) { - ep = epctx->transfers[xferi].packet.ep; - } killed +=xhci_ep_nuke_one_xfer (&epctx->transfers[xferi]); epctx->transfers[xferi].packet.ep =NULL ; xferi = (xferi +1 ) %TD_QUEUE ; } + + ep =xhci_epid_to_usbep (xhci, slotid, epid);if (ep) {usb_device_ep_stopped (ep->dev, ep); }
@@ -1699,7 +1700,6 @@ static int xhci_submit(XHCIState *xhci, XHCITransfer *xfer,static int xhci_setup_packet (XHCITransfer *xfer) {XHCIState *xhci = xfer->xhci; -USBDevice *dev;USBEndpoint *ep;int dir;
@@ -1707,15 +1707,13 @@ static int xhci_setup_packet(XHCITransfer *xfer)if (xfer->packet.ep) { ep = xfer->packet.ep; - dev = ep->dev; }else { -if (!xhci->slots[xfer->slotid-1 ].uport) { + ep =xhci_epid_to_usbep (xhci, xfer->slotid, xfer->epid); +if (!ep) {fprintf (stderr,"xhci: slot %d has no device\n" , xfer->slotid);return -1 ; } - dev = xhci->slots[xfer->slotid-1 ].uport->dev; - ep =usb_ep_get (dev, dir, xfer->epid >>1 ); }xhci_xfer_create_sgl (xfer, dir ==USB_TOKEN_IN );/* Also sets int_req */
@@ -1723,7 +1721,7 @@ static int xhci_setup_packet(XHCITransfer *xfer) xfer->trbs[0].addr, false, xfer->int_req);usb_packet_map (&xfer->packet, &xfer->sgl);DPRINTF ("xhci: setup packet pid 0x%x addr %d ep %d\n" , - xfer->packet.pid, dev->addr, ep->nr); + xfer->packet.pid, ep->dev->addr, ep->nr);return 0 ; }
@@ -2075,7 +2073,6 @@ static void xhci_kick_ep(XHCIState *xhci, unsigned int slotid, }else {if (xhci_fire_transfer (xhci, xfer, epctx) >=0 ) { epctx->next_xfer = (epctx->next_xfer +1 ) %TD_QUEUE ; - ep = xfer->packet.ep; }else {if (!xfer->timed_xfer) {fprintf (stderr,"xhci: error firing data transfer\n" );
@@ -2092,6 +2089,8 @@ static void xhci_kick_ep(XHCIState *xhci, unsigned int slotid,break ; } } + + ep =xhci_epid_to_usbep (xhci, slotid, epid);if (ep) {usb_device_flush_ep_queue (ep->dev, ep); }
@@ -3321,6 +3320,19 @@ static int xhci_find_epid(USBEndpoint *ep) } } +static USBEndpoint *xhci_epid_to_usbep (XHCIState *xhci, +unsigned int slotid,unsigned int epid) +{ +assert (slotid >=1 && slotid <= xhci->numslots); + +if (!xhci->slots[slotid -1 ].uport) { +return NULL ; + } + +return usb_ep_get (xhci->slots[slotid -1 ].uport->dev, + (epid &1 ) ?USB_TOKEN_IN :USB_TOKEN_OUT , epid >>1 ); +} +static void xhci_wakeup_endpoint (USBBus *bus,USBEndpoint *ep,unsigned int stream) {
Signature · 1 line
1.8.3.1
PATCH 5/7 xhci: Fix memory leak on xhci_disable_ep
In reply to Gerd HoffmannFrom: Hans de Goede <[email protected]>
The USBPacket-s in the transfers need to be cleaned up so that the memory allocated by the iovec in there gets freed.
--- hw/usb/hcd-xhci.c | 5 +++++ 1 file changed, 5 insertions(+)
hw/usb/hcd-xhci.c +5 -0
@@ -1380,6 +1380,7 @@ static TRBCCode xhci_disable_ep(XHCIState *xhci, unsigned int slotid, {XHCISlot *slot;XHCIEPContext *epctx; +int i;trace_usb_xhci_ep_disable (slotid, epid);assert (slotid >=1 && slotid <= xhci->numslots);
@@ -1400,6 +1401,10 @@ static TRBCCode xhci_disable_ep(XHCIState *xhci, unsigned int slotid,xhci_free_streams (epctx); } +for (i =0 ; i <ARRAY_SIZE (epctx->transfers); i++) { +usb_packet_cleanup (&epctx->transfers[i].packet); + } +xhci_set_ep_state (xhci, epctx,NULL ,EP_DISABLED );timer_free (epctx->kick_timer);
Signature · 1 line
1.8.3.1
PATCH 6/7 usb: Also reset max_packet_size on ep_reset
In reply to Gerd HoffmannFrom: Hans de Goede <[email protected]>
--- hw/usb/core.c | 3 +++ 1 file changed, 3 insertions(+)
hw/usb/core.c +3 -0
@@ -622,6 +622,7 @@ void usb_ep_reset(USBDevice *dev) dev->ep_ctl.nr =0 ; dev->ep_ctl.type =USB_ENDPOINT_XFER_CONTROL ; dev->ep_ctl.ifnum =0 ; + dev->ep_ctl.max_packet_size =64 ; dev->ep_ctl.dev = dev; dev->ep_ctl.pipeline = false;for (ep =0 ; ep <USB_MAX_ENDPOINTS ; ep++) {
@@ -633,6 +634,8 @@ void usb_ep_reset(USBDevice *dev) dev->ep_out[ep].type =USB_ENDPOINT_XFER_INVALID ; dev->ep_in[ep].ifnum =USB_INTERFACE_INVALID ; dev->ep_out[ep].ifnum =USB_INTERFACE_INVALID ; + dev->ep_in[ep].max_packet_size =0 ; + dev->ep_out[ep].max_packet_size =0 ; dev->ep_in[ep].dev = dev; dev->ep_out[ep].dev = dev; dev->ep_in[ep].pipeline = false;
Signature · 1 line
1.8.3.1
PATCH 7/7 usb: Fix iovec memleak on combined-packet free
In reply to Gerd HoffmannFrom: Hans de Goede <[email protected]>
--- hw/usb/combined-packet.c | 1 + 1 file changed, 1 insertion(+)
hw/usb/combined-packet.c +1 -0
@@ -39,6 +39,7 @@ static void usb_combined_packet_remove(USBCombinedPacket *combined, p->combined =NULL ;QTAILQ_REMOVE (&combined->packets, p, combined_entry);if (QTAILQ_EMPTY (&combined->packets)) { +qemu_iovec_destroy (&combined->iov);g_free (combined); } }
Signature · 1 line
1.8.3.1