diff --git a/src/asm.rs b/src/asm.rs index 3ce3e39..e6f61ba 100644 --- a/src/asm.rs +++ b/src/asm.rs @@ -24,7 +24,7 @@ use core::arch::asm; /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn dcache_call() { asm!(".insn i 0x0B, 0, x0, x0, 0x001") @@ -32,7 +32,7 @@ pub unsafe fn dcache_call() { /// DCACHE.IALL, D-cache invalid all items instruction /// -/// Invalidates all L1 D-cache table items. +/// Invalidates all L1 D-cache table items. This instruction only operates on the current hart. /// /// # Permissions /// @@ -40,14 +40,12 @@ pub unsafe fn dcache_call() { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn dcache_iall() { asm!(".insn i 0x0B, 0, x0, x0, 0x002") @@ -63,14 +61,12 @@ pub unsafe fn dcache_iall() { /// /// # Exceptions /// -/// Raises illegal instruction exception, or load page fault exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn dcache_ciall() { asm!(".insn i 0x0B, 0, x0, x0, 0x003") @@ -139,7 +135,7 @@ pub unsafe fn ipop() { /// ICACHE.IALL, I-cache invalid all items instruction /// -/// Invalidates all I-cache table items. +/// Invalidates all I-cache table items. This instruction only operates on the current hart. /// /// # Permissions /// @@ -147,23 +143,21 @@ pub unsafe fn ipop() { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn icache_iall() { asm!(".insn i 0x0B, 0, x0, x0, 0x010") } -/// ICACHE.IALLS, I-cache broadcast all cores to invalid all items instruction +/// ICACHE.IALLS, I-cache broadcast all harts to invalid all items instruction /// -/// Invalidates all I-cache table items, broadcast other cores to invalid all I-cache items. -/// This operation effects on I-cache on all cores. +/// Invalidates all I-cache table items, and broadcast other cores to invalid all I-cache items. +/// This operation operates on I-cache on all harts. /// /// # Permissions /// @@ -171,32 +165,75 @@ pub unsafe fn icache_iall() { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn icache_ialls() { asm!(".insn i 0x0B, 0, x0, x0, 0x011") } /// L2CACHE.CALL, L2-cache clean all dirty items instruction +/// +/// Clears all L2-cache table items, write all dirty items to next level storage. +/// +/// # Permissions +/// +/// Must run on M or S mode. +/// +/// # Exceptions +/// +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. +/// +/// # Platform support +/// +/// This instruction is supported on Xuantie C910 core. #[inline] pub unsafe fn l2cache_call() { asm!(".insn i 0x0B, 0, x0, x0, 0x015") } /// L2CACHE.IALL, L2-cache invalid all items instruction +/// +/// Invalidates all L2-cache table items. +/// +/// # Permissions +/// +/// Can run on M or S mode. +/// +/// # Exceptions +/// +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. +/// +/// # Platform support +/// +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn l2cache_iall() { asm!(".insn i 0x0B, 0, x0, x0, 0x016") } /// L2CACHE.CIALL, L2-cache clean all dirty and invalid item instruction +/// +/// Writes all L2-cache dirty items to next level storage, and invalidate all L2-cache table items. +/// +/// # Permissions +/// +/// Can run on M or S mode. +/// +/// # Exceptions +/// +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. +/// +/// # Platform support +/// +/// This instruction is supported on Xuantie C910 core. #[inline] pub unsafe fn l2cache_ciall() { asm!(".insn i 0x0B, 0, x0, x0, 0x017") @@ -288,14 +325,16 @@ pub unsafe fn dcache_csw(way_and_set: usize) { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. +/// +/// The C910 core has a 2-way set-associative D-cache. Input variable `rs1[31]` represents number of way, +/// while `rs1[w:6]` represents number of set. When D-cache is configurated 32 Kibibytes, `w` equals 13; +/// when configurated 64 Kibibytes, `w` equals 14. /// /// The C906 core has a 4-way set-associative D-cache. Input variable `rs1[31:30]` represents number of way, /// while `rs1[w:6]` represents number of set. When D-cache is configurated 32 Kibibytes, `w` equals 13; @@ -309,6 +348,7 @@ pub unsafe fn dcache_isw(way_and_set: usize) { /// /// Writes L1 D-cache dirty item corresponding to given way and set to next level storage, /// and invalidate this table item. +/// This instruction only operates on the current hart. /// /// # Permissions /// @@ -316,14 +356,16 @@ pub unsafe fn dcache_isw(way_and_set: usize) { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. +/// +/// The C910 core has a 2-way set-associative D-cache. Input variable `rs1[31]` represents number of way, +/// while `rs1[w:6]` represents number of set. When D-cache is configurated 32 Kibibytes, `w` equals 13; +/// when configurated 64 Kibibytes, `w` equals 14. /// /// The C906 core has a 4-way set-associative D-cache. Input variable `rs1[31:30]` represents number of way, /// while `rs1[w:6]` represents number of set. When D-cache is configurated 32 Kibibytes, `w` equals 13; @@ -336,7 +378,7 @@ pub unsafe fn dcache_cisw(way_and_set: usize) { /// DCACHE.CVAL1, L1 D-cache clean dirty item for virtual address instruction /// /// Writes D-cache table item corresponding to virtual address `va` to next level storage. -/// This operation effects on L1 cache on all cores. +/// This operation effects on L1-cache on all harts. /// /// # Permissions /// @@ -353,14 +395,37 @@ pub unsafe fn dcache_cisw(way_and_set: usize) { /// /// # Platform support /// -/// This instruction is supported on C906 core. On official C906 document, this instruction is -/// named `DCACHE.CVA`. +/// This instruction is supported on Xuantie C910 and C906 cores. +/// On official C906 document, this instruction is named `DCACHE.CVA`. #[inline] pub unsafe fn dcache_cval1(va: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x024", in(reg) va) } /// DCACHE.CVA, D-cache clean dirty item for virtual address instruction +/// +/// Writes D-cache anhd L2-cache table item corresponding to virtual address `va` to next level storage. +/// This operation effects on all harts and the L2-cache. +/// +/// # Permissions +/// +/// Can run on M or S mode. +/// +/// # Exceptions +/// +/// Raises illegal instruction exception, or load page fault exception. +/// +/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. +/// - When `mxstatus.theadisaee = 1`, and `mxstatus.ucme = 1`, this instruction can be run on U mode. +/// - When `mxstatus.theadisaee = 1`, and `mxstatus.ucme = 0`, +/// this instruction will raise illegal instruction when being run on U mode. +/// +/// # Platform support +/// +/// This instruction is supported on Xuantie C910 core. +/// +/// The Xuantie C906 User Manual names `DCACHE.CVAL1` as `DCACHE.CVA`; to clean dirty item on +/// C906 you may need to use function [`dcache_cval1`] on this library. #[inline] pub unsafe fn dcache_cva(va: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x025", in(reg) va) @@ -368,7 +433,11 @@ pub unsafe fn dcache_cva(va: usize) { /// DCACHE.IVA, D-cache invalid item for virtual address instruction /// -/// Invalidates D-cache table item corresponding to virtual address `va`. +/// Invalidates D-cache or L2-cache (if applicable) table item corresponding to virtual address `va`. +/// +/// This instruction operates on the current hart. If applicable, this instruction will +/// operates on L2-cache, and decide whether to broadcast to other cores according to +/// the share attribute of the virtual address. /// /// # Permissions /// @@ -383,7 +452,7 @@ pub unsafe fn dcache_cva(va: usize) { /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn dcache_iva(va: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x026", in(reg) va) @@ -391,8 +460,12 @@ pub unsafe fn dcache_iva(va: usize) { /// DCACHE.CIVA, D-cache clean dirty and invalid for virtual address instruction /// -/// Write D-cache table item corresponding to virtual address `va` to next level storage, -/// and invalidate this table item. +/// Write D-cache or L2-cache (if applicable) table item corresponding to virtual address `va` +/// to next level storage, and invalidate this table item. +/// +/// This instruction operates on the current hart. If applicable, this instruction will +/// operates on L2-cache, and decide whether to broadcast to other cores according to +/// the share attribute of the virtual address. /// /// # Permissions /// @@ -409,7 +482,7 @@ pub unsafe fn dcache_iva(va: usize) { /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn dcache_civa(va: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x027", in(reg) va) @@ -418,7 +491,7 @@ pub unsafe fn dcache_civa(va: usize) { /// DCACHE.CPAL1, L1 D-cache clean dirty item for physical address instruction /// /// Writes D-cache table item corresponding to physical address `pa` to next level storage. -/// This operation effects on L1 cache on all cores. +/// This operation effects on L1-cache for all harts. /// /// # Permissions /// @@ -426,21 +499,38 @@ pub unsafe fn dcache_civa(va: usize) { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. On official C906 document, this instruction is -/// named `DCACHE.CPA`. +/// This instruction is supported on Xuantie C906 and C910 cores. +/// On official C906 document, this instruction is named `DCACHE.CPA`. #[inline] pub unsafe fn dcache_cpal1(pa: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x028", in(reg) pa) } /// DCACHE.CPA, D-cache clean dirty item for physical address instruction +/// +/// Writes D-cache anhd L2-cache table item corresponding to physical address `pa` to next level storage. +/// This operation effects on all harts and the L2-cache. +/// +/// # Permissions +/// +/// Can run on M or S mode. +/// +/// # Exceptions +/// +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. +/// +/// # Platform support +/// +/// This instruction is supported on Xuantie C910 core. +/// +/// The Xuantie C906 User Manual names `DCACHE.CPAL1` as `DCACHE.CPA`; to clean dirty item on +/// C906 you may need to use function [`dcache_cpal1`] on this library. #[inline] pub unsafe fn dcache_cpa(pa: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x029", in(reg) pa) @@ -457,22 +547,21 @@ pub unsafe fn dcache_cpa(pa: usize) { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. pub unsafe fn dcache_ipa(pa: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x02A", in(reg) pa) } /// DCACHE.CIPA, D-cache clean dirty and invalid for physical address instruction /// -/// Writes D-cache table item corresponding to physical address `pa` to next level storage, -/// and invalidate this table item. +/// Writes D-cache or L2-cache (if applicable) table item corresponding to physical address `pa` +/// to next level storage, and invalidate this table item. +/// If applicable, this instruction operates on all harts and the L2-cache. /// /// # Permissions /// @@ -480,14 +569,12 @@ pub unsafe fn dcache_ipa(pa: usize) { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn dcache_cipa(pa: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x02B", in(reg) pa) @@ -497,6 +584,10 @@ pub unsafe fn dcache_cipa(pa: usize) { /// /// Invalidates the I-cache table item corresponding to virtual address `va`. /// +/// This instruction operates on the current hart. If applicable, this instruction will +/// operates on L2-cache, and decide whether to broadcast to other cores according to +/// the share attribute of the virtual address. +/// /// # Permissions /// /// Can run on M, S or U mode. @@ -512,7 +603,7 @@ pub unsafe fn dcache_cipa(pa: usize) { /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn icache_iva(va: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x030", in(reg) va) @@ -521,6 +612,7 @@ pub unsafe fn icache_iva(va: usize) { /// ICACHE.IPA, I-cache invalid item for physical address instruction /// /// Invalidates I-cache table item corresponding to physical address `pa`. +/// If applicable, this instruction operates on all harts. /// /// # Permissions /// @@ -528,14 +620,12 @@ pub unsafe fn icache_iva(va: usize) { /// /// # Exceptions /// -/// May raise illegal instruction exception. -/// -/// - When `mxstatus.theadisaee = 0`, this instruction always raise illegal instruction exception. -/// - When `mxstatus.theadisaee = 1`, this instruction will raise illegal instruction when being run on U mode. +/// Raises illegal instruction exception when `mxstatus.theadisaee = 0`, or +/// when `mxstatus.theadisaee = 1` but run on U mode. /// /// # Platform support /// -/// This instruction is supported on C906 core. +/// This instruction is supported on Xuantie C910 and C906 cores. #[inline] pub unsafe fn icache_ipa(pa: usize) { asm!(".insn i 0x0B, 0, x0, {}, 0x038", in(reg) pa)