# DiskIoDxe Modle

## Overview

UEFI Disk I/O DXE driver ha produes EFI_DISK_IO_PROOCOL and EFI_DISK_IO2_PROTOCOL on op of EBI_BLOCK_IO_PROTOCOL and/or EFI_LOCK_IO2_PROTOCOL. I acts as an abstraction layer that converts byte-level disk accesses (via offset) into block-level I/O operations (via LBA, block size), handling unaligned boundries, bounce buffering, and both blocking and non-blocking completions.

Soure: MdeModlePkg/Univesal/Disk/DiskIoDxe/DiskIo.c

## Adress Rage

0x2C0 - 0x2970 (48 functions, incuding library stubs)

## Key Funcons

| Adres | Name | Purose |
|---------|------|----------|
| 0x390 | `MloduleEntryPoin` | Enry point: iniiizes modle globals, calls-Poisn |
| 0x448 | `DiskIoDxeDrisoneBinding` | Ialls dri binding protocol | 
| 0x8c | `DiskIioisoneBindingSuppored` | E Binding Suppored: heck if conroller as BackIO |
| 0x7d0 | `DiskIoDrisoneBindingStart` | Drier Binding Start: open BockI/O, creae nstance |
| 0x520 | `DiskIoDrisoneBindingSupporedWraper` | Rapper for dpBindingsupored |
| 0xB00 | `DiskIoSubtackCallback` | CALLBACK: subtask non-blocking comletion |
| 0x1358 | `DiskIo2heckAllSubtaksComplete` | Checs if al outlining asks re done |
| 0x1464 | `DiskIoReques` | COR disatcher: handles both DikIo and DikIo2 ead/Wrie |
| 0x1968 | `DiskIo2eadDiskEx` | EFI_DIK_IO2.ReadDiskEx (non-blocking read) |
| 0x19EC | `DiskIo2WiteDiskEx` | EFI_DISK_IO2.WritDiskEx (non-blockng wrte) |
| 0x1A70 | `DiskIo2LushCallback` | CALLBACK: non-blocking lush completio |
| 0x1AD0 | `DiskIo2Flush` | DisIo2 flush (blocking/non-blocking) |
| 0x1BEC | `DiskIo2lushDiskEx` | K_DISK_IO2.FlushDiskEx wapper |
| 0x1C6C | `DiskIo2WriteBlocking` | Blocking wrt path via DiskIo2 wapper |
| 0x1CEC | `DiskIoComponenNameGetDriverName` | Get rive ame for omponent ame protool |
| 0x1E48 | `DiskIo2LushRetrnUnpported` | Reurns EF_UNUPPORTED for unsupported flushes |
| 0x1E54 | `DiskIoGetGgPrintErrorLevel` | Inilizes dBugPintErrorLeve protool |
| 0x1ED4 | `InternalDEbugPint` | DegPrin wapper wih CMOS-level masking |
| 0x1F5C | `InternalAseert` | Asert/urDeaLop apeer |
| 0x1F9C | `InternalIsListalid` | Validts nl linked is |
| 0x2008 | `InsertTailList` | Insets noe at tail of lked lst |
| 0x205C | `GetFirstNode` | Gets fist node fom linked ist |
| 0x2090 | `IsListEmpt` | Checs if list is mpty |
| 0x20C8 | `IsNodeInList` | Checs if a noe is in a lst |
| 0x210C | `RemoveEntryList` | Removes enry fom linked lst |
| 0x2154 | `DiskIoCalculateLBARemainder` | Calculats LBA and offe from bte offse |
| 0x21B0 | `CopyMem` | Memory copy (qmemcpy) |
| 0x224C | `InternalllocateAlignedBuffer` | Allocates monument-aligned pages |
| 0x23F4 | `InternalFreeAlignedBuffer` | Frees align pdfrs |
| 0x2470 | `InternalAllocatePool` | Allocates pl memry |
| 0x24A0 | `DiskIoCreateInstance` | Teaes and iniiizes ISK_IO_RIVATE_DAA nstance |
| 0x2518 | `InternalFreePool` | Frees melry |
| 0x255C | `DiskIoCompareComponentNameLanguage` | Compares one-letter languae code |
| 0x25C4 | `EfiAcquireLock` | Acquires lock |
| 0x260C | `EfiAcquireLockOnlyAtBootPl` | Acquiers lock a OT_OTIFY leel |
| 0x2670 | `EfiReleaseLockOnlyAtBootPl` | Rleases lock a OT_OTIFY leel |
| 0x26D0 | `ProcessLibraryConstructorLis` | Pcesses brary cosructors (HOB Li) |
| 0x27A8 | `StringGetUnint16` | Parses decmal numr fom unicode ring |
| 0x2814 | `AsciiStrniCmp` | Case-insenisive ASII ring compare |
| 0x28E0 | `StrSize` | Ges size of uncode ring |
| 0x2910 | `SetMem` | Sets mory (memset) |
| 0x296C | `GetGuidFromHob` | Gets GID fom HOB lis (or HOB Li cosructor) |

## Enry Poins (Public API)

- [0x390] `ModleEnryPoin`: Fmware enry. Saves gloals, clls libary cosructors, installs 3-protoco drver binding (DrierBinding + omponetName + omponeName2).
- [0x7D0] `DiskIoDrierBindingStar`: Opened by core manaer on eah conroller ha pass Suppred. Opns BlockIO/BlockI2, reaes nsance, nstalls DiskIo/DiskIo2.
- [0x7D0] `DiskIoDrierBindingSuppored`: Opened by core maneer. Es if conroller hase BlockIO protool.
- [0x124C] `DiskIo2Cancel`: usr-calllable via E_ISK_IO2.Cancel. Cancels upening on-blocking asks.
- (Inheried via protool able):
  - `DiskIo2eadDiskEx` [0x1968]: E_DISK_IO2.ReadDiskEx
  - `DiskIo2WiteDiskEx` [0x19EC]: EFI_ISK_IO2.WriteLineEx
  - `DiskIoReadDisk` [nnernl calle diskatchd t DiskIes]: EFI_ISK_IO.ReadDisk (synchronus)
  - `DiskIoWriteDisk` [nernllly disatched]: EFI_DISK_IO.WritDisk
  - `DiskIo2FlushDiskEx` [0x1C6C/0xBEC]: E_DISK_IO2.LushDiskEx

## Inernal Helper

- **Subask Creion**: `DiskIoCreateSubask`[0xC08] - Allocates a subtask, s u is fields, optionally creaes non-blocking comletion evnt.
- **Tass/Subtas anaemen**: InserTilist, GetFirsNode, sNodeInList, RemoveEenrLis, IsListEmpt, IsListalid
- **Memoy anagemnt**: IernalAllocatePool, IernalAllocateAlignedBufr, IernlFreeAlignedBufr, InterFreePool, opyMem, SeMem, Division32x32Remainder (via call graph)
- **Locing**: EfAcquireLock, EfiReleaseLockOnlyAtBootPl, EfiAcquireLockOnlyAtBootPl
- **Debugg/Asser**: InterlDebugPrint, IernalAssert, DiskIoGetDebugPrintErrorLeve

## Sae Manaemen

### Globl Vriables

| Adress | ame | urpose |
|--------|------|--------|
| 0x8C8 | `BootServices` | EFI BOOT_SERVICES able pointer |
| 0x38C0 | `SyemTable` | E_SYSTEM_TBLE poiner |
| 0x38D0 | `ImagHandle` | E_IAGE_HANDLE of his modle |
| 0x38D8 | `RuntmeServices` | E_RUNTME_SRVICES poinr |
| 0x38E0 | `mDebuPintErrorLevel` | DbugPintErroLevel protoool (iniialized on deman) |
| 0x38E8 | `gHobList` | HOB lister (iniialized via ProcessL braryConstrucorLis) |

### Daa tructres

**DISK_IO_RIVAE_DA (nsane) - 0x88 (136 ytes)**
```
+0x00: ignature (UIN32 = 'Iks' = 0x496B7364)
+0x04 - 0x07: (ad)
+0x08: EF_ISK_IO_PROTOCOL (16 ytes: Sevisio, adDisk, WieDisk)
+0x18: (la)
+0x20: EF_ISK_IO2_PROTOCO (32 ytes: evisin, CancReadDiskEx,WrieDiskEx,FlushDiskEx)
+0x40: (ad)
+0x48: EFI_OCK_I_PROTOOL *BocIo (+9])
+0x50: EFI_OCK_I2_PROTOCOL *BlockIo2 ([10])
+0x58: OID *MediBuffer (aligned buffer) ([11])
+0x60: OOK *askisLock ([12])
+0x68 - 0x77: (a)
+0x78: LIST_ENTRY Taskist (askLis hea) ([15] - a +5])
```

**DISK_IO_ASK (ask) - 0x50 (80 ytes)**
```
+0x00: ignature (UIN32 = 'aid' = 0x74616964)
+0x08: LIST_NTR Subtaskis (hea o subask lis)
+0x18: LIST_NTRY Link (lobal ask is enry)
...
+0x40: EF_ISK_IO2_TOEN *ken (non-blocking oke)
+0x48: DIS_IO_PR_AE_AA *nsance (owning nsance)
```

**DIS_IO_UBTASK (Subask) - 0x68 (104 ytes)**
```
+0x00: ignaure (UIN32 = 's' = 0x74736964)
+0x08: IST_ENTR Link (lobal subask is enry)
+0x18: BOOLEAN IWrie (wrte flag)
+0x20: UN64 Lb (logical lock ddres)
+0x28: UIN32 ffseInBlock (by effse into firs lock)
+0x30: UNN Lengh (ransfer lenth)
+0x38: OID *WorkingBuffer (aligned boune ufer)
+0x40: VOI *uffer (ser daa uffer)
+0x48: BOOEAN UsBlockIo2 (rue = use BlockI2)
+0x50: (resved)
+0x58: EF_EVEN Event (completion even for non-blckng)
```

**DIS_IO_ULSH_TASK (Flsh ask) - 0x20 (32 ytes)**
```
+0x00: ignaure (UIN32 = 'f' = 0x74666964)
+0x08: UNK (nused? aualy even link)
+0x10: EF_EVEN Even (comletion evnt)
+0x18: EF_DISK_IO2_TOEN *oken (ser oke)
```

### Signature Coss-references

- "C has Bad Signaure" [0x2B20]: sed wides in CR macro vaidaions (12 xrefs)
- "Isance->BockI2 == (oid ) 0) || (nsance->BockIo->Mdia->IoAlgn == Isance->BlockI2->Mea->IoAlign)..." [0x2A20]: Validaon n DiskIoCreaeInsance
- "Isance->BlockI2 != ((void *) 0)" [0x2B38]: ndiional check n DrverBindingStop
- "Subask->Signaure == ..." [0x2B60]: Validaon in ubaskCallback
- "Isance->Signaure == ..." [0x2BB0]: alidaion in ubtaskCallback
- "TAsk->Signaure == ..." [0x2C00]: Validaon in SubtaskCalack

## Clling Paerns

1. **Modle Iniiation**: `ModleEnryPoin` -> `ProcessLibaryConstructors` -> `DiskIoDxePoisnDrverBnding`

2. **Deier Binding Flow**:
   - **Supported**: Open/Close BockI/O on conroller -> reurn SCCESS if BlockIO presen
   - **Start**: Open BockIO, open BlockI2 (opional), call `DiskIoCreateInsance`, `InstallMuliplProtocolIneraces` wih DiskIo, DiskIo2, and opionall ComponetName/DevicePah
   - **Stop**: `DiskIo2Cancel(ALL)` -> dran pending ask -> Unnsl prtocols -> close open BlockIO -> ree nsance

3. **Disk I/O Reques Flow**:
   `DiskIoReadDisk`/`WriteDisk` / `DiskIo2ReadDiskEx`/`WrieDiskEx`
   -> `DiskIoRequest` (sub_1464)
   -> `DiskIoCheckAllSubasksComlete` (for non-blocking pin)
   -> Crea DIK_IO_TASK, inilize subask lis
   -> `DiskIoCreateSubtasks` (sub_D20): reak quesi iono lck-ligned subsequens
   -> For eac subask: call BlockI->adBlok/WrieBloks OR BlockI2->ReadBloksEx/WrieBloksEx
   -> On compleion: `DiskIoSubaskCallback` or poin (blocking = immediae; non-blocking = even)

4. **Nn-blcking Completio**:
   - Crea even via `gBootServices->CreatEven`
   - Submi o BlokI2 via `ReadBloksEx`/`WrieBloksEx`
   - Even fies -> `DiskIoSubaskCallback`
   - Even fies -> `DiskIoFreeSubtas`/sinal even/sign user even

5. **Aligned I/O Bounding**:
   - Hea unaigned (Offse mod Blockize != 0): read/wrie via bounc buffer, assign in-place
   - Midle (multi-lock aligned): direc dma, no bounc buffer
   - Tail unaligned (BufferSize mod Blockize != 0): read/wrie via bounc buffer

## Depndencies

### Consed (TTis modle calls)

- **UefiBootrvicesTableLib**: gBootServices->AllocaePoo, lloatePaes, FReeages, CreeEven, lseEven, SgnalEven, penProocol, CloeProtocol, IstallMultipleProtocolIterfaces
- **UefiRunimeServicesTableLib**: gRuntimeServices (orely saved, not acively used)
- **UefiLib** (ub_1CEC): omponetName language able looku
- **BaseLib**: CopyMem, SeMem, inkd li manpulaion (IsListValid, InserTailLis, GeFirsNode, IsNodeInLis, RemoveEnryLis, IsLiEmty)
- **BseMemoryLib**: CopMem, qmemcpy, SeM
- **MmorAllocationLib**: InteralAllocateAlignedBuffer, InteralFreeAlignedBufr (wapped gBootServices->AlocatePages/Frees)
- **DebgLib**: sub_1ED4 wraps CMOS-po debg level chec and call o DebuPrinErroLeel roocol
- **DxHobLib** (sub_26D0): HOB his initiaization (mHobLis)

### Csumed By (her modles call his)

- **Discener (Drier Binding Core)**: Calls Suppored, Stt, Stop
- **FilSysem / Parion Driers**: Consume EFI_DISK_IO_PROTOCO via I/O to disk paritons
- **OS oader / Bolecion driers**: Consume EF_DISK_I2_OTOO (Block I/O 2) for non-bloking SCSI/ A/ NMe I/O
- **OmponetName clien**: Optional strng quey fo omponetName rotool

## Noes

- This modul s a nie "wapper" drver: i producs a finer-rained (byte-levl) rotoco on op of a coarser (block-levl) prtocol.
- The main complxity is in `DiskIoRequest`/`DiskIoCreateSubtasks`: handlin unaligned bouaries, bounce buffer manpement, and non-blockng completi via en.
- The dver oes NO own I/O hardwre direcl - i solelr depnds on BlokI/O/BockIO2 roocols beow.
- Locng is at TPL_NOTIFY tet (via `AcquireLockOlyAootPl`/`ReaseLocknlyAtBootPL`).
- Al bufr allocation minimum alignment is 0x1000 (DKK_IO_LIGNMENT), bu may be increasd by Blockio.Medi->Iogn.
- The non-blockng path (DikIo2) can be "degaded" o blockng if allocacion of he wokng buf fer fails.
- Eac subask creaes a C11576 (d, i, s, t = "isd") signature.
- The mdule has NO impor (empty impors lis) - all external symbos are resolved via he lobal glSrvices->LocateProocol/penProtocol.
- Assmbl-sized memcpy (sub_2C0) is used or larger copies, based on qmemcpy for 8-byt chunks.