Microsoft Windows CE 3.0  

OhcdMdd_CreateMemoryObject

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function creates the OHCI shared memory area.

LPVOID
OhcdMdd_CreateMemoryObject(
DWORD
cbSize
,
DWORD
cbHighPrioritySize
,
PUCHAR
pVirtAddr
,
PUCHAR
pPhysAddr
);

Parameters

cbSize
[IN] Specifies the total size of OHCD shared memory area.
cbHighPrioritySize
[IN] Specifies the bytes reserved for high-priority isochronous or interrupt transfers and OHCI host controller communication area.
pVirtAddr
[IN] Pointer to the virtual address, which may be NULL, of a memory area.
pPhysAddr
[IN] Pointer to the physical address, which may be NULL, of a memory area.

Return Value

A pointer to an OHCD memory object indicates success. NULL indicates failure.

Remarks

This function is called by the OHCD PDD to initialize the shared memory area used by the OHCI driver. This memory contains the the Host Controller Communication Area (HCCA) for communicating with the OHCI hardware and is used to allocate DMA buffers for USB driver data transfers. Two options are available. If a platform has an area of memory set aside that can be used by OHCI, as specified in the Config.bib file, it can pass the virtual and physical address pointers in to this function. This is the recommended method. Alternatively, the PDD may pass NULL in for the physical and virtual address pointers, in which case the OhcdMdd_CreateMemoryObjectfunction attempts to allocate a suitable memory buffer from system RAM.

The OHC interface shared memory area is broken into two separate areas: a high-priority pool of buffers for the HCCA and for isochronous client buffers and a lower-priority pool of buffers for other client transfers.

The size of the shared memory area is dependent on the perceived usage of USB within the platform. The OHC interface controller uses 4-KB page boundaries for internal data structures, so the size should be a multiple of 4 KB and must be at least 8 KB for the control structures and memory needed for device configuration. Additionally, client drivers may need to utilize this area for their transfers, so it is recommended that OEMS provide additional memory. The maximum DMA memory used for a client transfer is 8 KB, so OEMs should try to determine what a reasonable number of outstanding client transfers may be.

A recommended value for general-purpose USB operation is 38 KB, with 20 KB reserved for high-priority transfers. OEMs that anticipate less demand on the USB subsystem can safely reduce this to 28 KB, of which 20 KB is high priority. Reducing the size of the high-priority buffer may cause isochronous transfers to fail if memory cannot be allocated, whereas reducing the size of the non-high-priority buffer reduces performance on bulk transfers. However, reducing the non-high-priority buffer does not cause failures, because bulk transfers can block to wait for memory to become available.

If possible, OEMs should consider placing the OHCD shared memory area in high-speed memory, particularly to support streaming (isochronous) data transfers.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 1.0 and later Ohcdddsi.h    
Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.


 Last updated on Tuesday, July 13, 2004

© 2004 Microsoft Corporation. All rights reserved.