libnx  v4.7.0
Data Structures | Enumerations | Functions
usbhs.h File Reference

USB (usb:hs) devices service IPC wrapper. More...

#include "../types.h"
#include "../sf/service.h"
#include "../services/usb.h"
#include "../kernel/event.h"
#include "../kernel/tmem.h"

Go to the source code of this file.

Data Structures

struct  UsbHsInterfaceFilter
 Interface filtering struct. More...
 
struct  UsbHsInterfaceInfo
 Descriptors which are not available are set to all-zero. More...
 
struct  UsbHsInterface
 Interface struct. Note that devices have a seperate UsbHsInterface for each interface. More...
 
struct  UsbHsXferReport
 
struct  UsbHsRingHeader
 
struct  UsbHsClientIfSession
 The interface service object. These Events have autoclear=false. More...
 
struct  UsbHsClientEpSession
 

Enumerations

enum  UsbHsInterfaceFilterFlags {
  UsbHsInterfaceFilterFlags_idVendor = (1U<<( 0 )) ,
  UsbHsInterfaceFilterFlags_idProduct = (1U<<( 1 )) ,
  UsbHsInterfaceFilterFlags_bcdDevice_Min = (1U<<( 2 )) ,
  UsbHsInterfaceFilterFlags_bcdDevice_Max = (1U<<( 3 )) ,
  UsbHsInterfaceFilterFlags_bDeviceClass = (1U<<( 4 )) ,
  UsbHsInterfaceFilterFlags_bDeviceSubClass = (1U<<( 5 )) ,
  UsbHsInterfaceFilterFlags_bDeviceProtocol = (1U<<( 6 )) ,
  UsbHsInterfaceFilterFlags_bInterfaceClass = (1U<<( 7 )) ,
  UsbHsInterfaceFilterFlags_bInterfaceSubClass = (1U<<( 8 )) ,
  UsbHsInterfaceFilterFlags_bInterfaceProtocol = (1U<<( 9 ))
}
 

Functions

Result usbHsInitialize (void)
 Initialize usb:hs.
 
void usbHsExit (void)
 Exit usb:hs.
 
ServiceusbHsGetServiceSession (void)
 Gets the Service object for the actual usb:hs service session.
 
EventusbHsGetInterfaceStateChangeEvent (void)
 Returns the Event loaded during init with autoclear=false. More...
 
Result usbHsQueryAllInterfaces (const UsbHsInterfaceFilter *filter, UsbHsInterface *interfaces, size_t interfaces_maxsize, s32 *total_entries)
 Returns an array of all UsbHsInterface. More...
 
Result usbHsQueryAvailableInterfaces (const UsbHsInterfaceFilter *filter, UsbHsInterface *interfaces, size_t interfaces_maxsize, s32 *total_entries)
 Returns an array of UsbHsInterface which are available. More...
 
Result usbHsQueryAcquiredInterfaces (UsbHsInterface *interfaces, size_t interfaces_maxsize, s32 *total_entries)
 Returns an array of UsbHsInterface which were previously acquired. More...
 
Result usbHsCreateInterfaceAvailableEvent (Event *out_event, bool autoclear, u8 index, const UsbHsInterfaceFilter *filter)
 Creates an event which is signaled when an interface is available which passes the filtering checks. More...
 
Result usbHsDestroyInterfaceAvailableEvent (Event *event, u8 index)
 Destroys an event setup by usbHsCreateInterfaceAvailableEvent. More...
 
Result usbHsAcquireUsbIf (UsbHsClientIfSession *s, UsbHsInterface *interface)
 Acquires/opens the specified interface. More...
 
void usbHsIfClose (UsbHsClientIfSession *s)
 UsbHsClientIfSession. More...
 
static bool usbHsIfIsActive (UsbHsClientIfSession *s)
 Returns whether the specified interface session was initialized.
 
static s32 usbHsIfGetID (UsbHsClientIfSession *s)
 Returns the ID which can be used for comparing with the ID in the output interfaces from usbHsQueryAcquiredInterfaces.
 
Result usbHsIfSetInterface (UsbHsClientIfSession *s, UsbHsInterfaceInfo *inf, u8 id)
 Selects an interface. More...
 
Result usbHsIfGetInterface (UsbHsClientIfSession *s, UsbHsInterfaceInfo *inf)
 Gets an interface. More...
 
Result usbHsIfGetAlternateInterface (UsbHsClientIfSession *s, UsbHsInterfaceInfo *inf, u8 id)
 Gets an alternate interface. More...
 
Result usbHsIfGetCurrentFrame (UsbHsClientIfSession *s, u32 *out)
 On [1.0.0] this is stubbed, just returns 0 with out=0.
 
Result usbHsIfCtrlXfer (UsbHsClientIfSession *s, u8 bmRequestType, u8 bRequest, u16 wValue, u16 wIndex, u16 wLength, void *buffer, u32 *transferredSize)
 Uses a control transfer, this will block until the transfer finishes. The buffer address and size should be aligned to 0x1000-bytes, where wLength is the original size.
 
Result usbHsIfOpenUsbEp (UsbHsClientIfSession *s, UsbHsClientEpSession *ep, u16 maxUrbCount, u32 maxXferSize, struct usb_endpoint_descriptor *desc)
 Opens an endpoint. More...
 
Result usbHsIfResetDevice (UsbHsClientIfSession *s)
 Resets the device: has the same affect as unplugging the device and plugging it back in.
 
void usbHsEpClose (UsbHsClientEpSession *s)
 UsbHsClientEpSession. More...
 
static EventusbHsEpGetXferEvent (UsbHsClientEpSession *s)
 Gets the Xfer Event which is signaled when PostBufferAsync finishes. This is only valid for [2.0.0+]. If using eventWait with this, then eventClear should be used if the event was signaled (since the autoclear is false).
 
static u32 usbHsEpGetReportRingSize (UsbHsClientEpSession *s)
 Gets the buffer size to use with usbHsEpShareReportRing.
 
Result usbHsEpPostBufferAsync (UsbHsClientEpSession *s, void *buffer, u32 size, u64 id, u32 *xferId)
 Starts an async data transfer with the specified endpoint. More...
 
Result usbHsEpGetXferReport (UsbHsClientEpSession *s, UsbHsXferReport *reports, u32 max_reports, u32 *count)
 Gets an array of UsbHsXferReport for the specified endpoint. More...
 
Result usbHsEpPostBuffer (UsbHsClientEpSession *s, void *buffer, u32 size, u32 *transferredSize)
 Uses a data transfer with the specified endpoint, this will block until the transfer finishes. More...
 
Result usbHsEpBatchBufferAsync (UsbHsClientEpSession *s, void *buffer, u32 *urbs, u32 urbCount, u64 id, u32 unk1, u32 unk2, u32 *xferId)
 This uses the same functionality internally as usbHsEpPostBufferAsync except the urbs array and unk1/unk2 are specified by the user instead. More...
 
Result usbHsEpCreateSmmuSpace (UsbHsClientEpSession *s, void *buffer, u32 size)
 This can be used to map the specified buffer as devicemem, which can then be used with usbHsEpPostBufferAsync / usbHsEpPostBuffer / usbHsEpBatchBufferAsync. More...
 
Result usbHsEpShareReportRing (UsbHsClientEpSession *s, void *buffer, size_t size)
 This creates TransferMemory which is used to read UsbHsXferReport when usbHsEpGetXferReport is used, instead of using the service cmd. More...
 

Detailed Description

USB (usb:hs) devices service IPC wrapper.

Author
yellows8

Enumeration Type Documentation

◆ UsbHsInterfaceFilterFlags

Enumerator
UsbHsInterfaceFilterFlags_idVendor 

These use usb_device_descriptor. Bit2..6 require [6.0.0+], these are ignored on eariler versions.

UsbHsInterfaceFilterFlags_bDeviceProtocol 

These use usb_interface_descriptor.

Function Documentation

◆ usbHsAcquireUsbIf()

Result usbHsAcquireUsbIf ( UsbHsClientIfSession s,
UsbHsInterface interface 
)

Acquires/opens the specified interface.

This returns an error if the interface was already acquired by another process.

Parameters
[in]sThe service object.
[in]interfaceInterface to use.

◆ usbHsCreateInterfaceAvailableEvent()

Result usbHsCreateInterfaceAvailableEvent ( Event out_event,
bool  autoclear,
u8  index,
const UsbHsInterfaceFilter filter 
)

Creates an event which is signaled when an interface is available which passes the filtering checks.

Parameters
[out]out_eventEvent object.
[in]autoclearEvent autoclear.
[in]indexEvent index, must be 0..2.
[in]filterUsbHsInterfaceFilter.

◆ usbHsDestroyInterfaceAvailableEvent()

Result usbHsDestroyInterfaceAvailableEvent ( Event event,
u8  index 
)

Destroys an event setup by usbHsCreateInterfaceAvailableEvent.

This must be used at some point during cleanup.

Parameters
[in]eventEvent object to close.
[in]indexEvent index, must be 0..2.

◆ usbHsEpBatchBufferAsync()

Result usbHsEpBatchBufferAsync ( UsbHsClientEpSession s,
void *  buffer,
u32 urbs,
u32  urbCount,
u64  id,
u32  unk1,
u32  unk2,
u32 xferId 
)

This uses the same functionality internally as usbHsEpPostBufferAsync except the urbs array and unk1/unk2 are specified by the user instead.

Note
Only available on [2.0.0+].
Parameters
[in]sThe endpoint object.
bufferData buffer. The buffer address and size should be aligned to 0x1000-bytes.
[in]urbsInput array of u32s for the size of each urb.
[in]urbCountTotal entries in the urbs array.
[in]idSame as usbHsEpPostBufferAsync.
[in]unk1usbHsEpPostBufferAsync would internally pass value 0 here.
[in]unk2usbHsEpPostBufferAsync would internally pass value 0 here.
[out]xferIdOutput xferId.

◆ usbHsEpClose()

void usbHsEpClose ( UsbHsClientEpSession s)

UsbHsClientEpSession.

Closes the specified endpoint session.

◆ usbHsEpCreateSmmuSpace()

Result usbHsEpCreateSmmuSpace ( UsbHsClientEpSession s,
void *  buffer,
u32  size 
)

This can be used to map the specified buffer as devicemem, which can then be used with usbHsEpPostBufferAsync / usbHsEpPostBuffer / usbHsEpBatchBufferAsync.

If the buffer address passed to those funcs is within this SmmuSpace, the specified buffer must be within the bounds of the SmmuSpace buffer.

Note
Only available on [4.0.0+].
A buffer from usbHsEpCreateSmmuSpace can't be reused by another endpoint with the aforementioned funcs.
This can only be used once per UsbHsClientEpSession object.
Parameters
[in]sThe endpoint object.
bufferBuffer address, this must be aligned to 0x1000-bytes.
[in]sizeBuffer size, this must be aligned to 0x1000-bytes.

◆ usbHsEpGetXferReport()

Result usbHsEpGetXferReport ( UsbHsClientEpSession s,
UsbHsXferReport reports,
u32  max_reports,
u32 count 
)

Gets an array of UsbHsXferReport for the specified endpoint.

This should be used after waiting on the Event from usbHsEpGetXferEvent.

Note
Only available on [2.0.0+].
Parameters
[in]sThe endpoint object.
[out]reportsOutput array of UsbHsXferReport.
[in]max_reportsSize of the reports array in entries.
[out]countNumber of entries written to the array.

◆ usbHsEpPostBuffer()

Result usbHsEpPostBuffer ( UsbHsClientEpSession s,
void *  buffer,
u32  size,
u32 transferredSize 
)

Uses a data transfer with the specified endpoint, this will block until the transfer finishes.

This wraps usbHsEpPostBufferAsync and usbHsEpGetXferReport, and also handles the Event (on pre-2.0.0 this handles using the relevant cmds instead). If async is needed, use usbHsEpPostBufferAsync instead.

Parameters
[in]sThe endpoint object.
bufferData buffer. The buffer address and size should be aligned to 0x1000-bytes.
[in]sizeThe actual data size.
[out]transferredSizeOutput transferred size.

◆ usbHsEpPostBufferAsync()

Result usbHsEpPostBufferAsync ( UsbHsClientEpSession s,
void *  buffer,
u32  size,
u64  id,
u32 xferId 
)

Starts an async data transfer with the specified endpoint.

The Event from usbHsEpGetXferEvent can be used to determine when the transfer finished. If you don't need async, usbHsEpPostBuffer can be used instead.

Note
Only available on [2.0.0+].
Parameters
[in]sThe endpoint object.
bufferData buffer. The buffer address and size should be aligned to 0x1000-bytes.
[in]sizeThe actual data size.
[in]idThis is an arbitrary value which will be later returned in UsbHsXferReport. For example a value starting at 0 can be used, then if sending multiple requests at once this value can be incremented each time (with 0 for the first request in this set of requests).
[out]xferIdOutput xferId.

◆ usbHsEpShareReportRing()

Result usbHsEpShareReportRing ( UsbHsClientEpSession s,
void *  buffer,
size_t  size 
)

This creates TransferMemory which is used to read UsbHsXferReport when usbHsEpGetXferReport is used, instead of using the service cmd.

Note
Only available on [4.0.0+].
Parameters
bufferBuffer, must be 0x1000-byte aligned.
[in]sizeBuffer size, usbHsEpGetReportRingSize can be used to calculate this.

◆ usbHsGetInterfaceStateChangeEvent()

Event* usbHsGetInterfaceStateChangeEvent ( void  )

Returns the Event loaded during init with autoclear=false.

Signaled when a device was removed. When signaled, the user should use usbHsQueryAcquiredInterfaces and cleanup state for all interfaces which are not listed in the output interfaces (none of the IDs match usbHsIfGetID output).

◆ usbHsIfClose()

void usbHsIfClose ( UsbHsClientIfSession s)

UsbHsClientIfSession.

Closes the specified interface session.

◆ usbHsIfGetAlternateInterface()

Result usbHsIfGetAlternateInterface ( UsbHsClientIfSession s,
UsbHsInterfaceInfo inf,
u8  id 
)

Gets an alternate interface.

Parameters
[in]sThe service object.
[out]infThe output interface info. If NULL, the output is stored within s instead.
[in]idID

◆ usbHsIfGetInterface()

Result usbHsIfGetInterface ( UsbHsClientIfSession s,
UsbHsInterfaceInfo inf 
)

Gets an interface.

Parameters
[in]sThe service object.
[out]infThe output interface info. If NULL, the output is stored within s instead.

◆ usbHsIfOpenUsbEp()

Result usbHsIfOpenUsbEp ( UsbHsClientIfSession s,
UsbHsClientEpSession ep,
u16  maxUrbCount,
u32  maxXferSize,
struct usb_endpoint_descriptor desc 
)

Opens an endpoint.

maxUrbCount*maxXferSize must be non-zero.

Parameters
[in]sThe interface object.
[out]epThe endpoint object.
[in]maxUrbCountmaxUrbCount, must be <0x11.
[in]maxXferSizeMax transfer size for a packet. This can be desc->wMaxPacketSize. Must be <=0xFF0000.
[in]descEndpoint descriptor.

◆ usbHsIfSetInterface()

Result usbHsIfSetInterface ( UsbHsClientIfSession s,
UsbHsInterfaceInfo inf,
u8  id 
)

Selects an interface.

Parameters
[in]sThe service object.
[out]infThe output interface info. If NULL, the output is stored within s instead.
[in]idID

◆ usbHsQueryAcquiredInterfaces()

Result usbHsQueryAcquiredInterfaces ( UsbHsInterface interfaces,
size_t  interfaces_maxsize,
s32 total_entries 
)

Returns an array of UsbHsInterface which were previously acquired.

Parameters
[out]interfacesArray of output interfaces.
[in]interfaces_maxsizeMax byte-size of the interfaces buffer.
[out]total_entriesTotal number of output interfaces.

◆ usbHsQueryAllInterfaces()

Result usbHsQueryAllInterfaces ( const UsbHsInterfaceFilter filter,
UsbHsInterface interfaces,
size_t  interfaces_maxsize,
s32 total_entries 
)

Returns an array of all UsbHsInterface.

Internally this loads the same interfaces as usbHsQueryAvailableInterfaces, followed by usbHsQueryAcquiredInterfaces. However, ID in UsbHsInterface is set to -1, hence the output from this should not be used with usbHsAcquireUsbIf.

Parameters
[in]filterUsbHsInterfaceFilter.
[out]interfacesArray of output interfaces.
[in]interfaces_maxsizeMax byte-size of the interfaces buffer.
[out]total_entriesTotal number of output interfaces.

◆ usbHsQueryAvailableInterfaces()

Result usbHsQueryAvailableInterfaces ( const UsbHsInterfaceFilter filter,
UsbHsInterface interfaces,
size_t  interfaces_maxsize,
s32 total_entries 
)

Returns an array of UsbHsInterface which are available.

Parameters
[in]filterUsbHsInterfaceFilter.
[out]interfacesArray of output interfaces.
[in]interfaces_maxsizeMax byte-size of the interfaces buffer.
[out]total_entriesTotal number of output interfaces.