Documented XVIO base functionality

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)

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 :)*

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.

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.*

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.

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.

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.

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.

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)

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.