This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
cheri-ibex is 32-bit RISC-V microcontroller which implements the CheriIoT ISA extension in addition to RV32IMCB. Same as the original ibex core, the design can be configured either with a 2-stage or a 3-stage pipeline. It has passed preliminary simulation and FPGA validation, and is currently undergoing further verification as well as PPA analysis at Microsoft.
cheri-ibex supports all 30 instructions listed in the CheriIoT ISA specification, including
- To query or test capabilities: cgetaddr, cgetbase, cgetlen, cgetperm, cgettag, cgettop, cgettype, ctestsubset, csetequalexact, csub
- To modify or derive capabilities: auicgp, auipcc, candperm, ccleartag, cincaddr, cincaddrimm, cmove, cram, crrl, csetaddr, csetbounds, csetboundsexact, csetboundsimm, cseal, cunseal
- To load/store capabilities from memory: clc, csc
- To control the program flow: cjal, cjalr
- To access special capability registers (SCR): cspecialrw
Certain compressed instructions are also extended for capabilities, for example c.incaddr4cspn, c.incaddr16csp, c.jal, c.jalr. Also the RV64 c.ld and c.sd instructions are reused for c.clc and c.csc instructions
cheri-ibex contains a register file implementation (cheri_regfile.sv) which extends a configurable number of the general purpose registers into CherIoT capabilities.
cheri-ibex extends its data bus to 33-bit, where the MSB 1-bit is used as a valid tag to differentiate between capabilities and normal integer data. The load-store unit is modified to support atomic capability load and store transactions according to the CherIoT ISA specification.
Per CherIoT specification, the following SCR's are implemented,
- MTCC (address 28), which replaces mtvec
- MTDC (address 29)
- MScratchC (address 30)
- MEPCC (address 31), which replaces mepc.
In addition, the following SCR's are added for debug support
- CDPC (address 24)
- CDScratch0 (address 25)
- CDScratch1 (address 26)
- CDBGCTRL (address 27)
The PC capability register (PCC) is also implemented as part of the CSR module.
cheri-ibex performs capability-based memory access rule checking including
- data load/store accesses
- capability load/store accesses
- Instruction fetch (PCC-based)
- jump target calculation (cjal and cjalr)
Exceptions are generated in the case of access rule violations.
The cheri-ibex CLC implementation provides an optional load-barrier feature. When enabled (cheri_tsafe_en_i == 1), CLC checks a memory area which contains shadow flag bits for all memory data blocks at 8-byte granularity. The tag bit of the loaded capability is cleared if the corresponding shadow bits == 1 (revoked).
cheri-ibex provides a backward-compatibility mode which is enabled by setting the input cheri_pmode_i = 1. In this mode, the CheirIoT instructions can still execute, however all access rules are disabled and any binary code generated by non-Cheri RV32 compilers can run unmodified in cheri-ibex.
cheri-ibex design added the following configuration parameters,
| Parameter | Description |
|---|---|
| CheriPPLBC | pipelined implementation of load-barrier CLC. 0: non-pipelined implementation 1: pipelined implementation (better performance but needs a separate memory read interface). |
| CheriSBND2 | Select number of cycles taken by csetbounds* instructions. 0: csetbounds* takes 1 cycle. 1: csetbounds* takes 2 cycle (better fmax timing). |
| MemCapFmt | Select the format used to store capabilities in memory. 0: use canonical memory capbility format. 1: use the alternative memory capability format (better memory access timing). |
| HeapBase | 32-bit starting address of the system heap memory. only capabilities whose base pointing to an address in the heap space are subject to load-barrier checks during CLC. |
| TSMapSize | size of the shadow bits memory (in 32-bit words) used by the load-barrier operation. e.g., 1024 = 32k bits which covers 256kB heap memory. This parameter is only used when CheriPPLSBC == 1. |
| TSMapBase | Starting address of the shadow bits memory This parameter is only used when CheriPPLSBC == 0. |
| TSMapTop | Ending address of the shadow bits memory This parameter is only used when CheriPPLSBC == 0. |
cheri-ibex supports cheri-aware RISC-V debugging via JTAG interface. The debug module is published separately at (link). General-purpose capability registers and SCR's can both be accessed via the JTAG interface. SBA accesses are supported as well.
To debug capability-related software issues, cheri-ibex also provides a debug feature which when enabled, escalates tag-clearing events defined in the CherIoT ISA spec (e.g, csetbounds length violations) into exceptions. Writing a 0x1 to the CDBGCTRL SCR (address 27) to enable this feature.
cheri-ibex (with 3-stage pipeline) has been synthesized at 330MHz using TSMC 28nm HPC+ libraries (HVT only) and > 1GHz using TSMC n5 libraries (SVT only). The design size is ~70k gate equivalents.
A detailed PPA analysis is under way at Microsoft.