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"

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.

Service *	usbHsGetServiceSession (void)
	Gets the Service object for the actual usb:hs service session.

Event *	usbHsGetInterfaceStateChangeEvent (void)
	Returns the Event loaded during init with autoclear=false.

Result	usbHsQueryAllInterfaces (const UsbHsInterfaceFilter filter, UsbHsInterface interfaces, size_t interfaces_maxsize, s32 *total_entries)
	Returns an array of all UsbHsInterface.

Result	usbHsQueryAvailableInterfaces (const UsbHsInterfaceFilter filter, UsbHsInterface interfaces, size_t interfaces_maxsize, s32 *total_entries)
	Returns an array of UsbHsInterface which are available.

Result	usbHsQueryAcquiredInterfaces (UsbHsInterface interfaces, size_t interfaces_maxsize, s32 total_entries)
	Returns an array of UsbHsInterface which were previously acquired.

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.

Result	usbHsDestroyInterfaceAvailableEvent (Event *event, u8 index)
	Destroys an event setup by usbHsCreateInterfaceAvailableEvent.

Result	usbHsAcquireUsbIf (UsbHsClientIfSession s, UsbHsInterface interface)
	Acquires/opens the specified interface.

void	usbHsIfClose (UsbHsClientIfSession *s)
	UsbHsClientIfSession.

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.

Result	usbHsIfGetInterface (UsbHsClientIfSession s, UsbHsInterfaceInfo inf)
	Gets an interface.

Result	usbHsIfGetAlternateInterface (UsbHsClientIfSession s, UsbHsInterfaceInfo inf, u8 id)
	Gets an alternate interface.

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.

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.

static Event *	usbHsEpGetXferEvent (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.

Result	usbHsEpGetXferReport (UsbHsClientEpSession s, UsbHsXferReport reports, u32 max_reports, u32 *count)
	Gets an array of UsbHsXferReport for the specified endpoint.

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.

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.

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.

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.

Detailed Description

USB (usb:hs) devices service IPC wrapper.

Author: yellows8

Copyright: libnx Authors

Enumeration Type Documentation

◆ UsbHsInterfaceFilterFlags

enum 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]	s	The service object.
[in]	interface	Interface 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_event	Event object.
[in]	autoclear	Event autoclear.
[in]	index	Event index, must be 0..2.
[in]	filter	UsbHsInterfaceFilter.

◆ usbHsDestroyInterfaceAvailableEvent()

Result usbHsDestroyInterfaceAvailableEvent	(	Event *	event,
		u8	index
	)

Destroys an event setup by usbHsCreateInterfaceAvailableEvent.

This must be used at some point during cleanup.

Parameters

[in]	event	Event object to close.
[in]	index	Event 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]	s	The endpoint object.
	buffer	Data buffer. The buffer address and size should be aligned to 0x1000-bytes.
[in]	urbs	Input array of u32s for the size of each urb.
[in]	urbCount	Total entries in the urbs array.
[in]	id	Same as usbHsEpPostBufferAsync.
[in]	unk1	usbHsEpPostBufferAsync would internally pass value 0 here.
[in]	unk2	usbHsEpPostBufferAsync would internally pass value 0 here.
[out]	xferId	Output 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]	s	The endpoint object.
	buffer	Buffer address, this must be aligned to 0x1000-bytes.
[in]	size	Buffer 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]	s	The endpoint object.
[out]	reports	Output array of UsbHsXferReport.
[in]	max_reports	Size of the reports array in entries.
[out]	count	Number 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]	s	The endpoint object.
	buffer	Data buffer. The buffer address and size should be aligned to 0x1000-bytes.
[in]	size	The actual data size.
[out]	transferredSize	Output 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]	s	The endpoint object.
	buffer	Data buffer. The buffer address and size should be aligned to 0x1000-bytes.
[in]	size	The actual data size.
[in]	id	This 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]	xferId	Output 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

	buffer	Buffer, must be 0x1000-byte aligned.
[in]	size	Buffer 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]	s	The service object.
[out]	inf	The output interface info. If NULL, the output is stored within s instead.
[in]	id	ID

◆ usbHsIfGetInterface()

Result usbHsIfGetInterface	(	UsbHsClientIfSession *	s,
		UsbHsInterfaceInfo *	inf
	)

Gets an interface.

Parameters

[in]	s	The service object.
[out]	inf	The 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]	s	The interface object.
[out]	ep	The endpoint object.
[in]	maxUrbCount	maxUrbCount, must be <0x11.
[in]	maxXferSize	Max transfer size for a packet. This can be desc->wMaxPacketSize. Must be <=0xFF0000.
[in]	desc	Endpoint descriptor.

◆ usbHsIfSetInterface()

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

Selects an interface.

Parameters

[in]	s	The service object.
[out]	inf	The output interface info. If NULL, the output is stored within s instead.
[in]	id	ID

◆ usbHsQueryAcquiredInterfaces()

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

Returns an array of UsbHsInterface which were previously acquired.

Parameters

[out]	interfaces	Array of output interfaces.
[in]	interfaces_maxsize	Max byte-size of the interfaces buffer.
[out]	total_entries	Total 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]	filter	UsbHsInterfaceFilter.
[out]	interfaces	Array of output interfaces.
[in]	interfaces_maxsize	Max byte-size of the interfaces buffer.
[out]	total_entries	Total 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]	filter	UsbHsInterfaceFilter.
[out]	interfaces	Array of output interfaces.
[in]	interfaces_maxsize	Max byte-size of the interfaces buffer.
[out]	total_entries	Total number of output interfaces.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ UsbHsInterfaceFilterFlags

Function Documentation

◆ usbHsAcquireUsbIf()

◆ usbHsCreateInterfaceAvailableEvent()

◆ usbHsDestroyInterfaceAvailableEvent()

◆ usbHsEpBatchBufferAsync()

◆ usbHsEpClose()

◆ usbHsEpCreateSmmuSpace()

◆ usbHsEpGetXferReport()

◆ usbHsEpPostBuffer()

◆ usbHsEpPostBufferAsync()

◆ usbHsEpShareReportRing()

◆ usbHsGetInterfaceStateChangeEvent()

◆ usbHsIfClose()

◆ usbHsIfGetAlternateInterface()

◆ usbHsIfGetInterface()

◆ usbHsIfOpenUsbEp()

◆ usbHsIfSetInterface()

◆ usbHsQueryAcquiredInterfaces()

◆ usbHsQueryAllInterfaces()

◆ usbHsQueryAvailableInterfaces()