diff --git a/docs/NAVIGATION.md b/docs/NAVIGATION.md index be10ef3..1b78de5 100644 --- a/docs/NAVIGATION.md +++ b/docs/NAVIGATION.md @@ -72,6 +72,8 @@ - development/xtf-apis/*.md - [Xbox Virtual Input/Output](development/xvio/xvio-overview.md) - development/xvio/*.md + - Ring Buffers + - development/xvio/ring-buffers/*.md - Misc - [Codenames](misc/codenames.md) - [FAQ](faq.md) diff --git a/docs/development/xvio/ring-buffers/xvio-create-ring-buffer.md b/docs/development/xvio/ring-buffers/xvio-create-ring-buffer.md new file mode 100644 index 0000000..24e0bc2 --- /dev/null +++ b/docs/development/xvio/ring-buffers/xvio-create-ring-buffer.md @@ -0,0 +1,41 @@ +# XvioCreateRingBuffer function +Creates a ring buffer for passing large amounts of data between partitions. Interestingly, it seems to be used as an auxiliary XvioPostMessage in some cases, though the reason for this is unknown. + +## Syntax +```cpp title='C++' +NTSTATUS XvioCreateRingBuffer( + uint32_t ContextId, + uint64_t TargetPartition, + uint16_t Unk1, + uint32_t ReceivePageCount, + uint32_t SendPageCount, + PXVIO_RING_BUFFER RingBuffer +); +``` + +## Parameters +`uint32_t ContextId` +The *[Context ID](../xvio-overview.md/#context-identifiers)* to communicate to on the remote partition. + +`uint64_t TargetPartition` +Target partition for the ring buffer to be shared with. *See [partition identifiers](../xvio-overview.md/#partition-identifiers) for a list of partitions and their corresponding IDs.* + +`uint16_t Unk1` +Not sure what this is, seems important though. Perhaps allocation type? + +`uint32_t ReceivePageCount` +Amount of pages, used for reading data, to be allocated to the ring buffer. + +`uint32_t SendPageCount` +Amount of pages, used for writing data, to be allocated to the ring buffer. + +`PXVIO_RING_BUFFER RingBuffer` +Pointer to an **XVIO_RING_BUFFER** structure, used for output. + +## Return value +Returns a generic **NTSTATUS** value. + +## Under the microscope +Put simply, XvioCreateRingBuffer allocates a user-specified amount of contiguous physical pages. The guest physical address of these pages are then posted to HostOS, amongst other data, with the message code 0x5 - which I've chosen to name *RingBufferAction* as the same code is used when destroying a ring buffer. The local partition then waits for the Ring Buffer's synchronization event to be signalled (presumably by HostOS) before returning the Ring Buffer Context to the caller. + +*Research into how HostOS handles a RingBufferAction is planned, I've just yet to get around to it :)* \ No newline at end of file diff --git a/docs/development/xvio/ring-buffers/xvio-get-ring-buffer-context-safe.md b/docs/development/xvio/ring-buffers/xvio-get-ring-buffer-context-safe.md new file mode 100644 index 0000000..5341243 --- /dev/null +++ b/docs/development/xvio/ring-buffers/xvio-get-ring-buffer-context-safe.md @@ -0,0 +1,20 @@ +# XvioGetRingBufferContextSafe +Safe version of *[XvioGetRingBufferContext](./xvio-get-ring-buffer-context.md).* Essentially just checks if the XVIO context is initialized and the *ContextId* parameter matches the ring buffer's context ID. + +## Syntax +```cpp title='C++' +PXVIO_RING_BUFFER XvioGetRingBufferContext( + uint32_t TargetPartition, + uint32_t ContextId +); +``` + +## Parameters +`uint32_t TargetPartition` +The *[Partition ID](../xvio-overview.md/#partition-identifiers)* of the partition the ring buffer targets. + +`uint32_t ContextId` +The *[Context ID](../xvio-overview.md/#context-identifiers)* of the XVIO context the ring buffer targets. + +## Return value +Returns a pointer to a **XVIO_RING_BUFFER** structure. \ No newline at end of file diff --git a/docs/development/xvio/ring-buffers/xvio-get-ring-buffer-context.md b/docs/development/xvio/ring-buffers/xvio-get-ring-buffer-context.md new file mode 100644 index 0000000..8a371cf --- /dev/null +++ b/docs/development/xvio/ring-buffers/xvio-get-ring-buffer-context.md @@ -0,0 +1,4 @@ +# XvioGetRingBufferContext function +One would assume this function returns a pointer to a ring buffer context but instead, this appears to always return 0? Thus, for getting a ring buffer context, *[XvioGetRingBufferContextSafe](./xvio-get-ring-buffer-context-safe.md)* should be used instead as it actually returns a pointer to the ring buffer context. + +*Once I find any uses of XvioGetRingBufferContext in any drivers, I'll do a little research and update this page. But for now, this function shall remain a weird one.* \ No newline at end of file diff --git a/docs/development/xvio/ring-buffers/xvio-read-ring-buffer.md b/docs/development/xvio/ring-buffers/xvio-read-ring-buffer.md new file mode 100644 index 0000000..6d4ee96 --- /dev/null +++ b/docs/development/xvio/ring-buffers/xvio-read-ring-buffer.md @@ -0,0 +1,24 @@ +# XvioReadRingBuffer function +Reads data from a ring buffer into a buffer + +## Syntax +```cpp title='C++' +NTSTATUS XvioReadRingBuffer( + PXVIO_RING_BUFFER RingBuffer, + void* Buffer, + size_t* BytesRead +); +``` + +## Parameters +`PXVIO_RING_BUFFER` +Pointer to a ring buffer context. Can be retrieved with *[XvioGetRingBufferContext](./xvio-get-ring-buffer-context.md)* or *[XvioGetRingBufferContextSafe](./xvio-get-ring-buffer-context-safe.md).* + +`void* Buffer` +Pointer to a buffer containing the data to be written. + +`size_t* BytesRead` +Pointer to the amount of bytes to read. Also acts as the output for the amount of bytes read. + +## Return value +Either returns `0x213`, `0x214`, or a standard **NTSTATUS**. I believe that `0x213` means there's still more data and that `0x214` means the end of the ring buffer was reached during a read. That being said, I'm not 100% certain on this information. \ No newline at end of file diff --git a/docs/development/xvio/ring-buffers/xvio-write-ring-buffer.md b/docs/development/xvio/ring-buffers/xvio-write-ring-buffer.md new file mode 100644 index 0000000..448ab2a --- /dev/null +++ b/docs/development/xvio/ring-buffers/xvio-write-ring-buffer.md @@ -0,0 +1,28 @@ +# XvioWriteRingBuffer function +Writes to some data to a ring buffer. + +## Syntax +```cpp title='C++' +NTSTATUS XvioWriteRingBuffer( + PXVIO_RING_BUFFER RingBuffer, + void* Buffer, + size_t Length, + void** Unk1 +); +``` + +## Parameters +`PXVIO_RING_BUFFER RingBuffer` +Pointer to a ring buffer context. Can be retrieved with *[XvioGetRingBufferContext](./xvio-get-ring-buffer-context.md)* or *[XvioGetRingBufferContextSafe](./xvio-get-ring-buffer-context-safe.md).* + +`void* Buffer` +Pointer to a buffer containing the data to be written. + +`size_t Length` +Amount of bytes to be written from the user-specified buffer into the ring buffer. + +`void** Unk1` +Unknown :/ + +## Return value +Returns a standard **NTSTATUS** value. \ No newline at end of file diff --git a/docs/development/xvio/xvio-cleanup.md b/docs/development/xvio/xvio-cleanup.md new file mode 100644 index 0000000..856e7cd --- /dev/null +++ b/docs/development/xvio/xvio-cleanup.md @@ -0,0 +1,16 @@ +# XvioCleanup function +Cleans up and frees an XVIO Context ID. Also destroys the allocated ring buffer, if one has been allocated. + +## Syntax +```cpp title='C++' +NTSTATUS XvioCleanup( + uint32_t XvioContextId +); +``` + +## Parameters +`uint32_t XvioContextId` +The ID of the context to be cleaned up, same as the one created with *XvioInitialize.* + +## Return value +Returns a generic **NTSTATUS** value. diff --git a/docs/development/xvio/xvio-get-current-partition-id.md b/docs/development/xvio/xvio-get-current-partition-id.md new file mode 100644 index 0000000..4498036 --- /dev/null +++ b/docs/development/xvio/xvio-get-current-partition-id.md @@ -0,0 +1,10 @@ +# XvioGetCurrentPartitionId function +Do I need to explain this one? :) + +## Syntax +```cpp title='C++' +uint64_t XvioGetCurrentPartitionId(void); +``` + +## Return value +The ID of the current partition. \ No newline at end of file diff --git a/docs/development/xvio/xvio-post-message.md b/docs/development/xvio/xvio-post-message.md new file mode 100644 index 0000000..0b309ec --- /dev/null +++ b/docs/development/xvio/xvio-post-message.md @@ -0,0 +1,32 @@ +# XvioPostMessage function +Sends a message (asynchronously) to the target partition. The message is then handled by an *XVIO context* within one of the remote partition's drivers. + +## Syntax +```cpp title='C++' +NTSTATUS XvioPostMessage( + uint32_t TargetContextId, + uint64_t TargetPartition, + uint64_t MessageCode, + uint16_t DataSize, + void* Data +); +``` + +## Parameters +`uint32_t TargetContextId` +The context ID of the target XVIO instance *(pretty much the target driver)* on the target partition. + +`uint64_t TargetPartition` +Pretty self-explanatory, the partition the message is targeted to, be it HostOS, SystemOS or GameOS. *See [Partition IDs](./xvio-overview.md#partition-identifiers) for more details.* + +`uint64_t MessageCode` +The code that is being posted, practically designating the action to be performed by the target. + +`uint16_t DataSize` +Specifies the size of the *Data* buffer in bytes, with a maximum of 232 bytes total -- *can be 0.* + +`void* Data` +Pointer to the data to be sent to the target -- *can be NULL.* + +## Return value +Returns your standard **NTSTATUS** with some extra XVIO statuses added on top (will document these soon) \ No newline at end of file diff --git a/docs/development/xvio/xvio-set-focus.md b/docs/development/xvio/xvio-set-focus.md new file mode 100644 index 0000000..3c32b43 --- /dev/null +++ b/docs/development/xvio/xvio-set-focus.md @@ -0,0 +1,20 @@ +# XvioSetFocus function +Used for setting to another partition. Likely used for switching between SystemOS and GameOS. +It's weird this function is implemented in `xvio.sys` rather than `xvmctrl.sys` as it simply just posts a message to the Xbox VM Manager. + +## Syntax +```cpp title='C++' +NTSTATUS XvioSetFocus( + uint64_t TargetPartition +); +``` + +## Parameters +`uint64_t TargetPartition` +The target partition to focus. *See [partition identifiers](./xvio-overview.md/#partition-identifiers) for more info.* + +## Return value +Returns a standard **NTSTATUS** value. + +## Important notes +**Cannot** be called from GameOS, and will just return **STATUS_ACCESS_DENIED** if this is attempted. \ No newline at end of file