19b0e7716SRobert Mustacchi.\" 29b0e7716SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 39b0e7716SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 49b0e7716SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 59b0e7716SRobert Mustacchi.\" 1.0 of the CDDL. 69b0e7716SRobert Mustacchi.\" 79b0e7716SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 89b0e7716SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 99b0e7716SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 109b0e7716SRobert Mustacchi.\" 119b0e7716SRobert Mustacchi.\" 129b0e7716SRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 139b0e7716SRobert Mustacchi.\" 14*c5bab702SPeter Tribble.Dd Nov 26, 2017 159b0e7716SRobert Mustacchi.Dt USBA_HCDI_CB 9F 169b0e7716SRobert Mustacchi.Os 179b0e7716SRobert Mustacchi.Sh NAME 189b0e7716SRobert Mustacchi.Nm usba_hcdi_cb 199b0e7716SRobert Mustacchi.Nd USBA transfer callback 209b0e7716SRobert Mustacchi.Sh SYNOPSIS 219b0e7716SRobert Mustacchi.In sys/usb/usba/hcdi.h 229b0e7716SRobert Mustacchi.Ft void 239b0e7716SRobert Mustacchi.Fo usba_hcdi_cb 249b0e7716SRobert Mustacchi.Fa "usba_pipe_handle_data_t *ph" 259b0e7716SRobert Mustacchi.Fa "usb_opaque_t req" 269b0e7716SRobert Mustacchi.Fa "ucb_cr_t cr" 279b0e7716SRobert Mustacchi.Fc 289b0e7716SRobert Mustacchi.Sh INTERFACE LEVEL 299b0e7716SRobert Mustacchi.Sy Volatile - 309b0e7716SRobert Mustacchiillumos USB HCD private function 319b0e7716SRobert Mustacchi.Pp 3272d3dbb9SYuri PankovThis is a private function that is not part of the stable DDI. 3372d3dbb9SYuri PankovIt may be removed or changed at any time. 349b0e7716SRobert Mustacchi.Sh PARAMETERS 359b0e7716SRobert Mustacchi.Bl -tag -width Fa 369b0e7716SRobert Mustacchi.It Fa ph 379b0e7716SRobert MustacchiA pointer to the USBA pipe handle that was passed to the HCD driver 389b0e7716SRobert Mustacchiduring a call to the 3972d3dbb9SYuri Pankov.Xr usba_hcdi_pipe_open 9E 409b0e7716SRobert Mustacchientry point. 419b0e7716SRobert Mustacchi.It Fa req 429b0e7716SRobert MustacchiA pointer to the request structure that is being completed. 439b0e7716SRobert Mustacchi.It Fa cr 449b0e7716SRobert MustacchiThe completion code for the request. 459b0e7716SRobert Mustacchi.El 469b0e7716SRobert Mustacchi.Sh DESCRIPTION 479b0e7716SRobert MustacchiThe 489b0e7716SRobert Mustacchi.Fn usba_hcdi_cb 499b0e7716SRobert Mustacchifunction is used when the HCD controller has completed processing a USB 509b0e7716SRobert Mustacchitransfer request, whether 519b0e7716SRobert Mustacchisuccessfully or not. 529b0e7716SRobert Mustacchi.Pp 539b0e7716SRobert MustacchiThe USB transfer will have been initiated by a call to 549b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_bulk_xfer 9E , 559b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_ctrl_xfer 9E , 569b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_intr_xfer 9E , 579b0e7716SRobert Mustacchior 589b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_isoc_xfer 9E . 599b0e7716SRobert MustacchiIf the transfer initiated was a periodic transfer (certain Interrupt-IN 609b0e7716SRobert Mustacchiand Isochronous-IN transfers), then there may be more than one callback 619b0e7716SRobert Mustacchiperformed over the life of the transfer. 629b0e7716SRobert Mustacchi.Pp 639b0e7716SRobert MustacchiThis function must not be used if the HCD driver returned a value 649b0e7716SRobert Mustacchiother than 659b0e7716SRobert Mustacchi.Sy USB_SUCCESS 6672d3dbb9SYuri Pankovto one of the transfer initialization functions listed above. 6772d3dbb9SYuri PankovFor more information on transfer request handling, see 689b0e7716SRobert Mustacchi.Xr usba_hcdi 9E . 699b0e7716SRobert Mustacchi.Pp 709b0e7716SRobert MustacchiThe 719b0e7716SRobert Mustacchi.Fa ph 729b0e7716SRobert Mustacchiargument corresponds to the USBA framework's pipe handle that was given 7372d3dbb9SYuri Pankovto the HCDI when the pipe was opened. 7472d3dbb9SYuri PankovSee 759b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_open 9E 769b0e7716SRobert Mustacchiand 779b0e7716SRobert Mustacchi.Xr usba_hcdi 9E 789b0e7716SRobert Mustacchifor more information. 799b0e7716SRobert Mustacchi.Pp 809b0e7716SRobert MustacchiThe 819b0e7716SRobert Mustacchi.Fa req 829b0e7716SRobert Mustacchiargument is one of the four request structures, 839b0e7716SRobert Mustacchi.Xr usb_bulk_req 9S , 849b0e7716SRobert Mustacchi.Xr usb_ctrl_req 9S , 859b0e7716SRobert Mustacchi.Xr usb_intr_req 9S , 869b0e7716SRobert Mustacchior 879b0e7716SRobert Mustacchi.Xr usb_isoc_req 9S , 889b0e7716SRobert Mustacchiwhich have been cast to the type 89*c5bab702SPeter Tribble.Ft usb_opaque_t . 909b0e7716SRobert MustacchiThe caller should ensure that all appropriate members of the request 9172d3dbb9SYuri Pankovstructure have been filled in. 9272d3dbb9SYuri PankovFor example, if expecting data from the device and the request has completed 9372d3dbb9SYuri Pankovsuccessfully, then that data should be copied into the request structure's 949b0e7716SRobert Mustacchi.Xr mblk 9S 959b0e7716SRobert Mustacchiprior to handing the request structure to the 969b0e7716SRobert Mustacchi.Fn usb_hcdi_cb 979b0e7716SRobert Mustacchifunction. 989b0e7716SRobert MustacchiSimilarly, the 999b0e7716SRobert Mustacchi.Xr usb_isoc_req 9S 1009b0e7716SRobert Mustacchistructure's 1019b0e7716SRobert Mustacchi.Sy isoc_pkt_descr 1029b0e7716SRobert Mustacchimember should be filled in with the appropriate data. 1039b0e7716SRobert Mustacchi.Pp 1049b0e7716SRobert MustacchiOnce the request structure has been passed to the 1059b0e7716SRobert Mustacchi.Fn usba_hcdi_cb 10672d3dbb9SYuri Pankovfunction, the HCD driver must not access the structure ever again. 10772d3dbb9SYuri PankovIt should be treated as freed memory. 1089b0e7716SRobert Mustacchi.Pp 1099b0e7716SRobert MustacchiThe 1109b0e7716SRobert Mustacchi.Fa cr 1119b0e7716SRobert Mustacchiargument us used to indicate whether the transfer was successful or not. 1129b0e7716SRobert MustacchiIf 1139b0e7716SRobert Mustacchi.Fa cr 1149b0e7716SRobert Mustacchiis set to 1159b0e7716SRobert Mustacchi.Sy USB_CR_OK 11672d3dbb9SYuri Pankovthat indicates that the transfer completed successfully. 11772d3dbb9SYuri PankovThis should also be used when a permitted short transfer has occurred. 11872d3dbb9SYuri PankovOtherwise, it should be set to one of the completion reasons. 1199b0e7716SRobert Mustacchi.Ss Locking 1209b0e7716SRobert MustacchiThe HCD driver should not hold its own internal locks across a call to 1219b0e7716SRobert Mustacchithe 1229b0e7716SRobert Mustacchi.Fn usba_hcdi_cb 12372d3dbb9SYuri Pankovfunction. 12472d3dbb9SYuri PankovIt is possible that the driver will have once of its 1259b0e7716SRobert Mustacchi.Xr usba_hcdi 9E 1269b0e7716SRobert Mustacchientry points called based on the return value specified. 1279b0e7716SRobert Mustacchi.Sh CONTEXT 1289b0e7716SRobert MustacchiThe 1299b0e7716SRobert Mustacchi.Fn usba_hcdi_cb 1309b0e7716SRobert Mustacchifunction may be called from 1319b0e7716SRobert Mustacchi.Sy user , 1329b0e7716SRobert Mustacchi.Sy kernel , 1339b0e7716SRobert Mustacchior 1349b0e7716SRobert Mustacchi.Sy interrupt 1359b0e7716SRobert Mustacchicontext. 1369b0e7716SRobert Mustacchi.Sh SEE ALSO 1379b0e7716SRobert Mustacchi.Xr usba_hcdi 9E , 1389b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_bulk_xfer 9E , 1399b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_ctrl_xfer 9E , 1409b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_intr_xfer 9E , 1419b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_isoc_xfer 9E , 1429b0e7716SRobert Mustacchi.Xr usba_hcdi_pipe_open 9E , 1439b0e7716SRobert Mustacchi.Xr mblk 9S , 1449b0e7716SRobert Mustacchi.Xr usb_bulk_req 9S , 1459b0e7716SRobert Mustacchi.Xr usb_ctrl_req 9S , 1469b0e7716SRobert Mustacchi.Xr usb_intr_req 9S , 1479b0e7716SRobert Mustacchi.Xr usb_isoc_req 9S 148