Departament d'Arquitectura de Computadors (DAC)
Universitat Politècnica de Catalunya (UPC)

Contribueix-hi

Ús d’aquesta guia

  • Recull les regles del llibre: contingut, llenguatge, format i eines. S’ha d’actualitzar sempre que es prengui una decisió de format, estil, etc.
  • El perquè de cada regla, datat i amb els commits, és al registre de decisions, 24_specs/registre_de_decisions.md. Les regles que hi tenen entrada hi enllacen amb el seu identificador, com ara D-1. Una regla nova o canviada porta la seva entrada al registre, en el mateix commit.
  • Per al flux de treball, el model d’IA i la fase actual del projecte, vegeu CLAUDE.md; els procediments que només fan servir les sessions de Claude Code són a les skills de .claude/skills/ (§IA).
  • Per a tasques pendents i decisions obertes, vegeu TODO.md.
  • Temes: Tx (T1–T9) designa un tema, el conjunt dels seus apunts, problemes i solucions (Ax.qmd, Px.qmd i Sx.qmd); és el sentit de §Decisions per tema. El laboratori (Ly.qmd) es numera per sessions: «Laboratori 1», o L1, a «Laboratori 6», o L6 (D-97).

Contingut

Criteri general

  • S’ha d’evitar emprar conceptes, termes, etc. que encara no s’han introduït al cos del text. Si es fa, cal referenciar la secció o el callout on s’explica el concepte en detall.
  • No s’ha de repetir informació (Don’t Repeat Yourself, DRY): ús de referències creuades; per a recordatoris puntuals, {.callout-caution}.
  • Mnemònics: El primer cop, si no estan prop d’una taula on se n’indiqui l’expansió, han d’anar seguits de l’expansió entre parèntesis. Ex: addi (add immediate).
  • No es permet que un nivell de profunditat tingui un sol ítem. En aquest cas, s’ha de pujar el contingut un nivell.
  • L’arquitectura de referència és RISC-V. No s’ha de fer cap referència a MIPS (tret d’on ja s’ha fet explícitament).
  • Prioritats: les màximes són la coherència pedagògica i el rigor tècnic en tot el contingut. La revisió és tècnica i profunda, i la lingüística, en català normatiu (§Llenguatge).
  • Precedència textual: els apunts (Ax.qmd) prevalen sobre els problemes (Px.qmd) i les solucions (Sx.qmd); dins dels apunts, el cos del text i els .callout-note prevalen sobre la resta de callouts i continguts. S’aplica, per exemple, als bits E i V de §T8 (D-1).

Fitxer de referència tècnica (11_riscv.qmd) i directori 21_riscv/

El fitxer 11_riscv.qmd és el compendi de referència tècnica de l’assignatura (capítol «Referència tècnica» del llibre). Conté exclusivament callouts #nte-rv-* sense text narratiu entre ells. Totes les taules s’obtenen via {{< include 21_riscv/NOM.qmd >}} (rutes relatives a l’arrel del projecte, sense ../).

El directori 21_riscv/ conté els fragments de taula reutilitzables (sols les files, sense header ni caption). Cada fitxer es pot incloure a múltiples llocs: als Ax.qmd dins el callout temàtic corresponent, i a 11_riscv.qmd per agrupar continguts de diverses extensions o categories sota un sol header diferent.

Convencions dels fitxers 21_riscv/:

  • Només files de taula (sense header, sense caption, sense atributs {}).
  • Nom: <extensió>_<categoria>_<descripció>.qmd. Exemples: RV32I_instruccions_aritmetiques.qmd, Zicsr_instruccions.qmd, RARS_syscall_codis.qmd.
  • Pseudoinstruccions: fragment propi, <extensió>_pseudo_<descripció>.qmd, i mai dins d’una taula ISA. Les columnes són sempre «Pseudoinstrucció | Operació | Expansió», amb l’operació en la notació de les taules ISA (§Codi, matemàtiques i cursiva); li, que té una expansió per a cada cas, hi afegeix «Condició» davant de l’expansió (D-66).
  • Excepció: els callouts que contenen figures SVG no s’externalitzen; es reprodueixen íntegrament a 11_riscv.qmd amb ID #nte-rv-*. Les figures, com totes les dels callouts #nte- (§Callouts), van sense etiqueta ni peu (D-2).

ID dels callouts a 11_riscv.qmd: prefix #nte-rv- (en comptes del #nte- dels Ax.qmd), per evitar conflictes de ID Quarto.

Referències creuades cap als Apunts: cada callout de 11_riscv.qmd acaba amb una nota «Vegeu @X[, @Y] i @Z.» que apunta al callout (o callouts) de l’Ax.qmd on es presenta el contingut per primer cop, amb el mateix format que les referències dels enunciats (§Problemes i solucions). Quan un mateix contingut es presenta a més d’un Ax.qmd (p. ex. mv/not/neg a T2/T3/T4), es llisten totes les referències. Els callouts sense cap presentació a la teoria (material exclusiu del compendi, com les directives RARS) no en porten.

Taules amb més d’un fragment font: Quarto no permet encadenar dos {{< include >}} consecutius dins la mateixa taula pipe. Quan una taula de 11_riscv.qmd combina files de més d’un fitxer de 21_riscv/ (p. ex. aritmètica + lui sota un sol header), els fragments es fusionen prèviament en un únic fitxer generat per 25_scripts/gen_taules_auto.py (manifest: 24_specs/taules_fusio.toml) i 11_riscv.qmd hi fa un únic {{< include auto_riscv/NOM.qmd >}}. El directori auto_riscv/ és generat (gitignored); no s’edita a mà.

L’script no és al pre-render de _quarto.yml: el fitxer fusionat ha d’existir abans d’invocar quarto (D-3). make taules el genera, i make render i make render-complet ja el criden; sense make, cal executar-lo a mà (python3 25_scripts/gen_taules_auto.py 24_specs/taules_fusio.toml 21_riscv --output-dir="auto_riscv/") el primer cop i sempre que s’editi un fitxer de 21_riscv/ que aparegui a 24_specs/taules_fusio.toml. Si quarto render diu could not find file .../auto_riscv/NOM.qmd, és que falta aquest pas. Si no, auto_riscv/ queda desactualitzat en silenci: quarto render no fallarà, però la taula final no reflectirà el canvi. Els fitxers font de 21_riscv/ continuen sent l’única font de veritat.

Contingut d’Aprofundiment exclòs de 11_riscv.qmd: el compendi de referència tècnica no pot incloure contingut que provingui únicament d’un callout d’Aprofundiment d’un Ax.qmd (material opcional, no bàsic). Exemple: Zicsr_instruccions_immediats.qmd (csrrwi/csrrsi/csrrci) es presenta a A9.qmd dins un callout d’Aprofundiment; per això 11_riscv.qmd només inclou Zicsr_instruccions.qmd (les instruccions base), no la taula d’immediats. El fitxer de 21_riscv/ es manté igualment, per a l’ús des de l’Ax.qmd corresponent.

Qui fa servir un fitxer de 21_riscv/: git grep -n <nom> -- '*.qmd' 24_specs/taules_fusio.toml, perquè el compendi en consumeix uns quants fusionats, a través de taules_fusio.toml (més avall). No se’n porta la llista, que es quedaria enrere (§Comprovacions per nivells, «Registres»).

Extensions RISC-V a EC

A EC s’estudien les extensions següents:

Extensió Descripció Tema
RV32I Base entera Tots
M Multiplicació i divisió entera T4
F Coma flotant T5
Zicsr Registres de control i estat T9

Zifencei (fence.i) no s’estudia: queda fora de l’abast, com la resta de les instruccions de barrera, perquè a EC no hi ha concurrència ni codi que es modifiqui a si mateix (D-77).

El camp filename dels blocs de codi reflecteix les extensions actives: RV32I, RV32IM, RV32IF, RV32IZicsr.

Decisions per tema

T2 i T3

  • .globl vs. .global: s’usa .globl (forma estàndard de GNU AS); .global és un àlies acceptat, però no s’usa als exemples ni al laboratori, i el text de T3 (#nte-globl) tampoc no l’esmenta: només el recull la taula de directives del compendi (21_riscv/RARS_directives.qmd) (D-4).
  • Mode base + desplaçament (terme canònic a EC): el mode d’adreçament que usa la sintaxi offset(rs1) s’anomena mode base + desplaçament a EC. El terme mode memòria és un sinònim de la literatura; es menciona com a tal al callout {#cau-mode-base-desplacament} de T2, però no s’usa com a terme principal.
  • Modes d’adreçament: quatre modes a EC: registre, immediat, base+desplaçament, relatiu al PC. lui → immediat; auipc → relatiu al PC (A3, taula resum dels modes); jalr → base+desplaçament.
  • Formats d’instrucció d’RV32I: quatre de nuclears, R, I, S i U, com diu la font de veritat ([1], «four core instruction formats»); B i J són variants de S i U, respectivament, i no formats independents. Cap text no ha de donar «sis formats» com a total. Escrit a A2.qmd §Format de les instruccions RV32I (#sec-format-instruccions). On es presenta cada format: els quatre nuclears a T2 —R, I i S a §Format de les instruccions RV32I (#nte-instruccions-tipus, la figura del qual els mostra tots com a visió de conjunt, la mateixa del compendi, i el text diu on es presenta cadascun) i U amb lui i auipc (les dues instruccions, a §Instruccions, #sec-instruccions-assemblador; el format, #nte-format-u, a §Operands en mode immediat)— i les dues variants a T3, amb les instruccions de salt (#nte-format-b, #nte-format-j), que remeten al format nuclear de T2. Així el text no presenta cap variant abans que el seu format nuclear (D-5).
  • Terminologia de salts: relatiu al PC (beq, jal) vs. indirecte (jalr). Tots els salts condicionals d’RV32I són relatius al PC.
  • Cap etiqueta ni constant b o B: és el nom del salt incondicional b (A RARS, una constant .eqv B ni tan sols assembla: RISC-V 2.10). Quan una sèrie de variables necessita lletres, les de tres o menys són X, Y, Z (x, y, z) i les més llargues, lletres consecutives a partir de P (P–W, p–u); el nom C i el text que les cita canvien amb l’etiqueta. verifica_format_codi.py ho comprova (F6), i make comprova atura el commit si en troba cap (D-111).
  • Etiquetes de bucle: bucle: i fibucle: als exemples didàctics; en la pràctica s’admeten etiquetes descriptives (while:, fiwhile:, etc.). El prefix de l’etiqueta de sortida és fi- (fibucle:, fifor:, fiwhile:).
    • Més d’un bucle al mateix bloc: quan un fragment conté dos bucles o més al mateix àmbit d’assemblador, les etiquetes es numeren (for1:/fifor1:, for2:/fifor2:), perquè dues etiquetes iguals al mateix bloc no assemblen. La numeració no és una desviació de la convenció: n’és l’extensió per al cas de bucles germans (D-6).
  • Registres als exemples: t0, t1, t2… tant en C com en assemblador per eliminar el soroll del mapatge.
  • la label+offset: admès a EC (pissarra i exàmens) però no suportat per RARS; al laboratori cal la + addi.
  • Pseudoinstruccions vs. macros: distinció explícita establerta a T2 (#sec-macros); T3 hi afegeix la de macro vs. subrutina (#cau-macros-vs-subrutines). Les macros es defineixen amb .macro/.end_macro i són locals al programa.
  • Alineació de la pila: la mida del BA i el valor de sp han de ser múltiples de 4 bytes a EC (relaxació pedagògica). L’ABI estàndard d’RV32I exigeix múltiples de 16 bytes; aquest fet és a {#nte-abi-alineacio-pila} de T3, i el criteri d’EC, a {#imp-abi-alineacio-pila}, just a continuació (D-7).
  • Retorn de resultats: les subrutines retornen com a màxim dos resultats escalars, per a0 i a1. El segon (a1) s’usa habitualment per a un codi d’error o un segon valor de retorn. Documentat a {#nte-abi-pas-parametres} de T3.
  • Retorn de subrutines — ret: als exemples s’usa sempre ret (pseudoinstrucció estàndard, més llegible), no jalr zero, 0(ra).
  • Títols «C — »: un títol de secció o de callout porta el prefix «C — » quan el contingut és només de C, sense cap part en RV32I (§C — Un tipus de punter per cada tipus de dades, A2); si té part en RV32I, no en porta. Els fills d’una secció «C — » no el repeteixen (D-114).
  • Notació del mode base + desplaçament: l’operand s’escriu sempre desplaçament(base), també a jalr (jalr zero, 0(ra), no jalr zero, ra, 0), al text, a les taules ISA i a les expansions de les pseudoinstruccions. A2 ho diu a #imp-notacio-base-desplacament (D-84).
  • .section: no s’utilitza. Només .data i .text, sense sagnar, a columna 0, també al laboratori (§Convencions globals del laboratori). No és una preferència d’estil: RARS 1.6 no admet la forma llarga. .section .data i .section .text no assemblen (error .section must be followed by a section name), i les formes que sí que assemblen són pitjors, perquè fallen en silenci: no commuten de segment i, amb un nom reconegut (.rodata, .sdata), descarten tot el codi que les segueix (D-8).
    • Excepció legítima: la forma amb sufix i flags (.section .text.trap, "ax") sí que assembla, i és la de l’exemple d’RSE mínima d’A9 (#sec-ei-rse-exemple), declarat il·lustratiu i no executable. No s’ha de tocar.

T4

  • Optimitzacions de bucle: tres de numerades, que es defineixen a T4 (Optimitzacions de bucle): #1 accés seqüencial, #2 avaluació de la condició al final i #3 eliminació de la variable d’inducció. El prerequisit no numerat, l’extracció d’invariants, s’introdueix a T2 (Extracció d’invariants) i s’hi remet des de T4. La numeració és única per al bloc, no es reparteix entre temes.
  • Notació de la multiplicació i la divisió: \(z = x \times y\) (multiplicand \(x\), multiplicador \(y\), producte \(z\)) i \(x = y \cdot q + r\) (dividend \(x\), divisor \(y\), quocient \(q\), residu \(r\)), a l’algorisme, als exemples i al pseudocodi dels circuits seqüencials. Els registres dels circuits (P, MD i MR; R, D i Q) són noms de maquinari, no variables: a la prosa, en rodona, i a les fórmules només amb el seu valor o un bit (\(P = 10000010_2\), \(R_{2n-1}\)) (D-9).

T1 i T5

  • «En excés» / «codificació en excés»: terme correcte per al concepte general de representació d’enters (T1, @sec-enters-en-exces). Usat quan el valor K és arbitrari.
  • «Esbiaixat» / «biaix»: terme correcte per a l’exponent IEEE 754 específicament (T5, L5, S5). No és sinònim de «biaix estadístic» (context RNE): són homònims, no el mateix concepte (D-10).
  • «Mantissa» (significand, a 24_specs/termes.toml) per a la part \(1{,}F\) del nombre en coma flotant, i no el calc «significand»: l’ambigüitat per la qual l’estàndard IEEE 754 en anglès el prefereix ja queda resolta a EC amb la distinció entre fracció i mantissa (§T5) (D-11).

T5

  • Fracció vs. mantissa: en el context IEEE 754, F designa la fracció (els 23/10 bits emmagatzemats); la mantissa és 1.F (inclou el bit ocult). Usar-los amb precisió evita confusions en calcular rangs i errors de representació. La precisió \(p\) compta els bits significatius de la mantissa, bit ocult inclòs: la fracció en té \(p-1\) (\(b_{-1} \ldots b_{-(p-1)}\)), i l’exponent és \(e\) tant en base 2 com en la notació científica decimal (\(v = m \times 10^e\)) (D-12).
  • Posició menys significativa (no posició 0): per referir-se al darrer bit de la fracció, a fi d’evitar l’ambigüitat entre indexació des de 0 o des de l’LSB.
  • Blocs de codi .default: per als càlculs pas a pas IEEE 754 (descomposició S/Eu/F, sumes binàries, alineació), es fa servir {.default filename="..."} amb el nom del pas com a etiqueta (filename="ft2 = 0x417AC000"). És una regla dels problemes i les solucions: la teoria (A5) presenta aquests càlculs amb fórmules (D-81).
  • Solucions: estructura de cada solució: **Enunciat**: @exr-... → explicació → blocs de càlcul → resultat en $$\boxed{...}$$. Els resultats intermedis van en blocs .default; el codi RISC-V en blocs .s filename="RV32IF".
  • fcvt.w.s/fcvt.wu.s s’arrodoneixen segons el camp rm de la instrucció, no trunquen sempre. Sense operand de mode (fcvt.w.s rd, rs1), l’assemblador RISC-V hi assigna dyn (mode dinàmic: el del registre frm, RNE per defecte a RARS). Per traduir la conversió de tipus (int) de C (que trunca cap a zero) cal escriure explícitament fcvt.w.s rd, rs1, rtz.
  • flt.s rd, rs1, rs2 avalua \(rs1 < rs2\). Per implementar a > b cal invertir els operands (flt.s rd, b, a), no negar el resultat.
  • No-associativitat (half): exemple canònic: \(A = \texttt{0xF3FD}\), \(B = \texttt{0x73FD}\), \(C = \texttt{0x3C00}\) → \((A+B)+C = 1 \neq 0 = A+(B+C)\). És l’exemple dels problemes i les solucions; A5 en fa servir un de precisió simple, la del tema (D-81).

T6

  • Ordre de seccions: Rendiment → Llei d’Amdahl → Potència, tant a la teoria com als enunciats i les solucions. El nom de la secció de potència és «Potència» (no «Potència i consum»).
  • Ordre dins de §Potència: definició i #eq-potencia primer, després §Potència dinàmica i §Potència estàtica, i al final §Miniaturització i límit tèrmic (llei de Moore, #wrn-dennard). Cap frase no ha de remetre a la potència, ni als corrents de fuita, abans que el text els hagi presentat (D-13).
  • Rendiment vs. productivitat: a EC, el rendiment és l’invers del temps d’execució (#eq-rendiment), i s’enuncia abans dels exemples que el comparen amb la productivitat. «Quant de treball per unitat de temps» és la definició de productivitat, no de rendiment (D-14).
  • Notació: les definicions formals (teoria) usen les formes llargues \(t_{clock}\), \(f_{clock}\), \(n_{ins}\); a partir de la seva introducció, la resta del tema (exemples, enunciats, solucions) usa lliurement les abreviatures \(t_c\), \(f\), \(N\). Fora de T6 (p. ex. el problema de rendiment de T3), les formes llargues.
  • Guany, llei d’Amdahl i potència: la notació de la teoria, també als problemes i les solucions. Guany \(s\) i guany màxim \(s_{max}\); fracció del temps \(P_x\) i guany \(s_x\) del component \(x\) (amb diversos components, \(\sum_x P_x/s_x\)); potència \(P\), \(P_d\) i \(P_s\); freqüències dels computadors A i B, \(f_A\) i \(f_B\) (D-15).
  • «Capacitat equivalent» (terme principal) / «capacitància» (sinònim): per a \(C\) a les fórmules de potència dinàmica. S’introdueix «capacitat equivalent» amb «(capacitància)» entre parèntesis a la primera aparició de cada fitxer; les aparicions posteriors poden fer servir qualsevol dels dos termes indistintament.
  • Sigles CMOS i CF: s’expandeixen a la primera aparició del llibre, com la resta (§Sigles, símbols i notació; «complementary metal–oxide–semiconductor (CMOS)»; «instruccions de coma flotant (CF)»), i tenen entrada a 12_sigles_simbols.qmd. FPU no s’usa als enunciats ni les solucions: es prefereix «unitat de coma flotant» (o «unitat CF» en segones aparicions).
  • Guany / speedup: el terme a EC és «guany»; speedup n’és la glossa anglesa, a la primera aparició de cada fitxer: «guany (speedup)» (§Anglicismes i terminologia obligatòria).
  • Majúscules de lleis i principis: «llei d’Amdahl», «llei de Moore» i «escalat de Dennard» s’escriuen amb minúscula inicial al cos del text (com qualsevol altre terme comú), tret dels títols de secció o de callout, que segueixen la regla general de majúscula de frase (p. ex. ## Llei d'Amdahl).
  • \(I_{fuita}\) (no I_leak) i «corrents de fuita» (plural, com a fenomen general): notació i terme establerts a T6, reutilitzats a T7 i T8.
  • Etiquetes de classe d’instruccions a les taules dels problemes: en català, com a la prosa i com diu el glossari (load, store): «Lectura», «Escriptura», «Lectura/escriptura» (abreujat «L/E», també en subíndex: \(P_{L/E}\)) i «Salt». No s’hi inclouen els noms anglesos de les instruccions a les taules ISA (load word), els identificadors (#nte-load-store) ni la glossa de les lletres de format i de mnemònic («S, store», «l, load») (D-16).
  • Amplada de les figures extretes de PDF (svg.md §15): l’atribut width de la imatge SVG es normalitza a 100%; l’amplada visual final la determina exclusivament l’atribut {width="X%"} del bloc Quarto, amb el mateix valor a HTML i a PDF (sense divergència entre formats). A T6: 40% per a fig-amdahl i fig-tc-tc-prima; 50% per a les tres figures fig-not-*.

T7

  • \(t_{bloc}\) (no \(t_{block}\)): notació canònica per al temps de transferència d’un bloc entre l’MC i la memòria principal (teoria, enunciats i solucions).
  • «línia» vs. «bloc»: la línia és el contenidor de l’MC; el bloc és el contingut (fragment de la memòria principal). Els enunciats especifiquen la geometria com a «\(N\) línies amb blocs de \(B\) bytes» o «\(N\) vies per conjunt», mai «\(N\) blocs» per comptar línies o vies.
  • Notació multinivell: la dels subíndexs de nivell de la teoria (@eq-tam-multinivell): \(t_{h_{L1}}\), \(t_{h_{L2}}\), \(m_{L1}\), \(m_{L2}\); els subíndexs numèrics (\(m_1\), \(m_2\)…) es reserven per enumerar alternatives dins d’un mateix exercici.
  • Tipus de fallades (les tres C): fallades d’arrencada en fred (cold-start), també obligatòries (compulsory) o de primera referència (first-reference); de conflicte (o de col·lisió); i de capacitat. La quarta C, les de coherència (o d’invalidació) dels processadors multinucli, és d’aprofundiment (#wrn-fallades-coherencia). Les figures generades diuen «obligatòria», la forma curta. A la resta del material (P7, S7, S8 i L6): a la prosa, «d’arrencada en fred», amb cold-start en cursiva a la primera aparició de cada fitxer; a les taules i als llocs curts (parèntesis, subíndexs), «obligatòria», com a les figures. S8 l’aplica a les fallades de TLB, que segueixen la mateixa classificació (D-17).

T8

  • Bit de permís d’escriptura E: la teoria, els enunciats i les solucions usen el bit E (E = 1 → permís d’escriptura; E = 0 → només lectura), no W (D-18).
  • Bit de validesa V: la teoria, els enunciats i les solucions usen V (valid bit, notació RISC-V Sv32 / Harris & Harris) per al bit de presència d’una PTE, no P. #wrn-mv-notacio-v a A8.qmd documenta la notació P per a qui consulti exàmens anteriors (D-18).
  • Mida de pàgina explícita: si un enunciat de memòria virtual no especifica la mida de pàgina, però les adreces la impliquen, s’afegeix explícitament a l’enunciat (rigor i bona definició).
  • Estat inicial del TLB: quan es dona l’estat inicial d’un TLB completament associatiu amb LRU, cal especificar també l’ordre d’ús de les entrades vàlides, amb el sentit explícit (de la més recent a la més antiga, o a l’inrevés); sense això el reemplaçament és ambigu (D-82).
  • Canvi de mida de pàgina sobre un estat fix: una pregunta que reutilitzi una taula de pàgines o un TLB donats per a una mida de pàgina concreta i en canviï la mida es torna incoherent; en aquests casos es reformula en clau qualitativa (efecte sobre el nombre de fallades).
  • Model del TLB: el de RISC-V, no el de MIPS. El TLB d’EC és un model docent (#imp-mv-model-tlb: a RISC-V el TLB no és arquitectònic), completament associatiu i amb LRU, que només conté traduccions de pàgines residents: la fallada de TLB la resol l’MMU (recorregut de la taula de pàgines per maquinari, transparent a l’SO); si la PTE té V = 1 es copia al TLB i la traducció continua, i si té V = 0 no es copia res i es produeix la fallada de pàgina. En expulsar una pàgina, l’SO posa V = 0 a la PTE de la víctima i n’invalida l’entrada del TLB (sfence.vma, T9), que queda lliure. El bit V d’una entrada del TLB vol dir «entrada ocupada», com el de les línies de l’MC (T7), i mai no és una còpia del V de la PTE. El bit D s’actualitza per maquinari a la primera escriptura, al TLB i a la PTE (l’opció HW de RISC-V; Svade a @wrn-tlb-bit-ad de T9). El model antic de MIPS (TLB arquitectònic, refill per programari, encert de TLB amb V = 0) queda com a nota històrica a #wrn-mv-tlb-hw-walker, amb l’avís per als exàmens antics d’EC. Conseqüències als problemes: les entrades lliures del TLB es donen com a «V = 0, —», no amb un VPN residual; i amb tants marcs com entrades de TLB el reemplaçament LRU del TLB no arriba a actuar (l’exemple d’A8 ho diu explícitament i remet a exr-t8-tlb-estat) (D-19).
  • Columnes de les taules de TLB: V | VPN | D | E | PPN (V primer, com a bit d’ocupació de l’entrada); les de la taula de pàgines, VPN | V | D | E | PPN, amb el VPN com a índex.
  • Fallades de TLB als problemes amb codi: els enunciats que compten fallades de TLB sobre un bucle diuen «TLB de dades» i que no es consideren les captures d’instruccions (exr-t8-tlb-basic, exr-t8-tlb-optimitzacio).
  • Exemple pràctic (#tip-mv-tlb-exemple): a la secció final del tema, #sec-mv-exemple. Els cinc accessos del PDF original, amb les dades del PDF, en text i en una taula resum; la traça és la figura dinàmica #fig-mv-tlb-exemple, generada per gen_T8.py a partir d’una simulació del model (que fa alhora de verificador numèric) (D-20).

T9

  • Excepció i interrupció: els termes anglesos, junts a T9. Exception i interrupt es presenten a #cau-terminologia (A9), on es defineixen tots dos, i no a la primera aparició del llibre, encara que «excepció» surt abans, des de T2: és una excepció a la regla de la primera aparició (§Anglicismes i terminologia obligatòria) (D-119).
  • ecall: la convenció de crides al sistema Linux/RISC-V usa a7 per al codi de servei (no a0) i admet fins a sis arguments (a0–a5).
  • RSE: cal desar tots els registres generals sense excepció, independentment de les convencions de l’ABI.
  • mepc: en excepcions, apunta a la instrucció causant; en interrupcions, a la instrucció següent. L’ajust (mepc + 4) és responsabilitat de l’RSE, no del maquinari.
  • Zicsr: les instruccions CSR (csrrw, csrrs, csrrc i variants immediates) pertanyen a l’extensió Zicsr, no a RV32I base. Els callouts d’ISA s’etiqueten ## Zicsr ISA — ....
  • Mode S: el mecanisme d’excepcions s’estudia en mode M; el mode S s’introdueix a #sec-ei-csr-modes i s’aplica, al cos del text, al tractament de la fallada de pàgina (satp, stval, sfence.vma; #sec-ei-tlb-modes). La fallada de TLB no és una excepció: la resol el maquinari (§T8, «Model del TLB») (D-21).

Problemes i solucions

  • Termes: les parts del llibre són «Problemes» (els enunciats) i «Solucions»; cada element és un problema (com als exàmens: «Problema 1», «Problema 2») amb la seva solució; «exercici» només al laboratori. No s’usa «problemari», que no és al DIEC2, al Termcat ni a l’Optimot (D-24).
  • Referències creuades cap a la teoria (Nivell 2): als problemes i a les solucions, afegir referències @sec-nom a la secció de teoria rellevant quan el concepte clau no és obvi o quan l’estudiant típicament s’encalla. No de forma mecànica a tots els problemes, sinó selectivament. Nivell 3 (@nte-, @tip-…) admès quan la solució és aplicació directa d’un exemple concret de teoria.
    • Format recomanat als enunciats: nota al final del bloc {#exr-} o sota la capçalera de secció: «Vegeu @sec-nom.» (al text real la referència va sense cometes invertides; les d’aquí marquen la metavariable).
    • Format recomanat a les solucions: integrat al text de la solució on es fa servir el concepte.
  • Identificadors d’enunciats i solucions: #exr-t<N>-<slug> i #sol-t<N>-<slug>, on <N> és el tema del fitxer que els defineix (P<N>.qmd/S<N>.qmd) i el <slug> és el mateix a l’enunciat i a la solució (D-22). Als temes pilot (de moment, T1), el filtre 25_scripts/plegables.lua afegeix al final de cada enunciat que té solució la remissió a la solució («Solució 19.1»), a partir d’aquest slug compartit: no s’escriu a mà (D-90).
  • Etiqueta visible: «Problema» a Problemes i Solucions, «Exercici» al laboratori. Tots dos fan servir #exr-, de manera que l’etiqueta no es pot fixar un sol cop a _quarto.yml. Cada format ho fa d’una manera:
    • HTML: cada Px.qmd i Sx.qmd porta a la capçalera language: amb crossref-exr-title: "Problema" i crossref-exr-prefix: "Problema". Un fitxer nou d’enunciats o de solucions l’ha de copiar.
    • PDF: és un sol document LaTeX, amb un sol \newtheorem{exercise}, i les metadades de cada fitxer no hi arriben. _quarto.yml (format: pdf: language:) hi posa «⁂» com a títol i prefix; preamble.tex fa que «⁂» s’expandeixi a \exercisename; i un bloc {=latex} amb \renewcommand{\exercisename}{…} a l’inici de P1.qmd («Problema») i d’L1.qmd («Exercici») el canvia a cada part. Una referència pren el nom de la part on és.
    • ⚠️ No es pot fer amb un bloc crossref: a la capçalera del fitxer ni escrivint \exercisename directament al prefix: totes dues formes s’han provat i no funcionen (D-23).
  • Detall de les solucions: pas a pas, excepte els passos trivials.
  • Selecció de solucions: cada tema publica la solució d’una selecció dels problemes, aproximadament un de cada dos o tres, triats perquè cobreixin els continguts del tema i diversos nivells de dificultat (D-73).
  • Veu dels enunciats: segona persona del plural (§Criteris generals → Veu impersonal).

Convencions globals del laboratori

  • El punt d’entrada no porta etiqueta. El primer bloc de .text comença directament amb la primera instrucció, sense cap etiqueta que l’anomeni —ni _start, ni main, ni cap altra—, i la prosa que se’n parla hi diu «el programa principal» o «el bloc principal» (D-25).
    • Quan el text esmenti l’excepció de RARS a l’assumpció bare-metal (@imp-directe-sobre-processador), ha de dir que és sobre els serveis que el programa crida, no sobre qui crida el programa.
    • El punt d’entrada no ha de tenir pròleg ni epíleg, perquè no és callee de ningú i acaba amb la sortida li a7, 93 + ecall; sí que ha d’usar registres segurs per a les dades pròpies que travessen crides.
  • Tres blocs del laboratori tenen .text sense punt d’entrada, i és legítim: s2_4_1.s (L2.qmd) és un fragment d’accés a vector, no un programa; s5_1_1.s i s5_2_1.s (L5.qmd) són fitxers de subrutina sola (abs i descompon), que s’enllacen amb el fitxer que porta el programa principal. Cap dels tres no s’ha d’«arreglar» afegint-hi un punt d’entrada (D-26).
  • Sortida del programa: li a7, 93 + ecall (syscall exit2). No es fa servir startup.s (D-125).
  • Expressions aritmètiques als operands: a la teoria, els problemes i els exàmens s’admeten (.space NF*NC*4, li t0, NC*4, la t0, vec+8), perquè fan visible l’estructura del càlcul. Al laboratori cal el literal ja calculat, amb l’expressió al comentari; i la rd, etiqueta+desplaçament se substitueix per la parella la + addi. Font única: @imp-ec-operands-expressions (el cas de la, a @imp-ec-la-offset).
  • Directives de segment: vegeu §T2 i T3, .section. Al laboratori la regla és obligatòria per motiu tècnic, no d’estil.
  • Codi dels exercicis: integrat al .qmd (no hi ha fitxers .s separats). Els alumnes el copien i l’enganxen.
  • Estructura de cada exercici: enunciat en {#exr-...} + solució en {#sol-...}.
  • Lliuraments i Lectura prèvia: dues seccions fixes al principi de cada sessió, en aquest ordre (§Ordre i atribut de seccions no numerades). «Lliuraments» porta una taula amb els exercicis i el nom del fitxer de lliurament; «Lectura prèvia» porta una taula amb columnes «Concepte» i «On trobar-ho».
  • Oracle i tècnica: on va cada cosa. Una verificació a RARS té dues parts, i tenen destinataris diferents (D-27):
    • L’oracle (els valors que l’estudiant ha d’obtenir) va al final de l’enunciat {#exr-...}, en prosa, amb l’imperatiu «Comproveu que…». Sense callout ni negreta.
    • Un oracle és una parella (entrada, resultat esperat). Si cal fixar una entrada perquè el resultat estigui determinat (p. ex. «afegint li s2, 7 abans del fragment»), la fixació va amb el resultat.
    • La tècnica (quina vista de RARS obrir, com avançar pas a pas, com interpretar el que es veu) es queda al bloc {#sol-...}, com a {.callout-tip title="Comprovació pràctica"}. No porta etiqueta #tip- perquè no es referencia des d’altres punts del text.
    • Si un cop separat l’oracle la tècnica no té contingut propi, el callout se suprimeix.
  • Directives .eqv: es defineixen abans de la primera directiva de segment (.data o .text), fora de qualsevol secció.
  • Calendari (Lcalendari.qmd, només a l’HTML): una sessió que es fa en un dia de la setmana diferent del de la seva fila (un canvi de dia del calendari acadèmic) porta la data en vermell i amb †, [07/05 †]{.canvi-dia}, i s’explica en una nota just sota la taula que comença amb [†]{.canvi-dia}. 25_scripts/verifica_calendari.py la dona per bona, i el hook d’abans del commit la mostra com a informació (D-74).

Nom dels fitxers de lliurament

Patró: s<N>_<S>_<E>.<ext> — sessió, secció, exercici, extensió (.s per a codi assemblador, .md per a documents escrits). Exemples: s3_3_1.s, s3_4_2.md, s3_4_2.s.

Ordre i atribut de seccions no numerades

Les seccions ### Lliuraments i ### Lectura prèvia porten {.unnumbered} per evitar que incrementin el comptador i provoquin un decalatge entre la numeració dels exercicis i els noms dels fitxers de lliurament. Són capçaleres de nivell 3 (###), no de nivell 2 (##) (D-28). L’ordre fix al principi de cada sessió és:

### Lliuraments {.unnumbered}
### Lectura prèvia {.unnumbered}

A continuació comencen les seccions numerades d’exercicis.

Títol del bloc d’exercici i lliuraments

El títol de {#exr-...} és el nom del fitxer de lliurament. Si hi ha dos lliuraments (.md + .s), ambdós apareixen al títol; la taula de lliuraments els reflecteix tots dos. Els exercicis amb .md requereixen anàlisi escrita prèvia (identificació de registres segurs, esquema del BA).

::: {#exr-nom}
## `s3_4_1.s`
:::

::: {#exr-nom2}
## `s3_4_2.md` i `s3_4_2.s`
:::

Llenguatge

Referència normativa

  • La norma general és la de l’IEC (Institut d’Estudis Catalans).
  • Fonts lèxiques, per aquest ordre de precedència: una forma d’una font mana sobre la d’una font de més avall (D-116).
    1. El DIEC2.
    2. El Termcat (el Cercaterm, amb les fitxes de la Neoloteca).
    3. L’Optimot (les seves fitxes).
    4. El diccionari anglès-català de Softcatalà.
    5. La Viquipèdia en català: un article sobre el concepte informàtic que en porti la forma al títol o com a denominació explícita a l’entradeta, no una menció de passada. Pot aportar una forma que les fonts 1–4 no tenen («taula de salts»), però no contradir-les.
    • Les fonts 2–4 es poden consultar amb els scripts de 24_specs/lexic/ (24_specs/lexic/README.md).
  • Diccionari del projecte: els mots que els diccionaris de l’ortografia no tenen (els mnemònics, els noms propis i la resta) són a 24_specs/diccionari.txt, un per línia; el fa servir make comprova i el corrector de VS Code. Un mot legítim nou s’hi afegeix en el mateix commit que el fa servir. Els dels termes del llibre no hi van: són a 24_specs/diccionari_termes.txt, que es genera de 24_specs/termes.toml (make registres), i una flexió d’un terme que el corrector no coneix va a mots del terme (D-115).
  • El català normatiu és el criteri de resolució per a qualsevol dubte lèxic o ortogràfic no cobert explícitament per aquesta guia.
  • Noms de persona: com els escriu la Viquipèdia i, si no hi tenen article, com els escriu la Wikipedia en anglès: «John von Neumann», «l’arquitectura de von Neumann» (D-107).

Criteris generals

  • Camel Case:
    • Només en els sintagmes anglesos.
    • En els sintagmes catalans (títols inclosos) només la primera lletra en majúscula.
  • Després de dos punts: minúscula en enumeracions i explicacions breus; majúscula en citacions textuals i paràgrafs independents.
  • Nombres:
    • Les quantitats petites (una instrucció, dos bytes) o genèriques (mil, deu mil) al cos del text preferiblement amb lletres.
    • La resta en nombres: “5 V”, “8 bits”, “12 bits”, “16 bits”, “32 bits”, “RV32I”, x0-x31.
    • Separador de milers: espai («65 535»), no coma anglesa («65,535», ambigua amb la coma decimal catalana) ni punt.
    • Unitats de mesura i percentatges: entre el nombre i la unitat o el símbol %, un espai («80 %», «32 bits», «4 KiB», «2 GHz»), com demana l’Optimot. Al codi font s’escriu un espai normal, i el filtre 25_scripts/espai_unitats.lua el converteix en un espai que no es parteix a final de línia; a les fórmules, \ («\(39{,}2\ \%\)») (D-87).
  • Prefixos de mida binaris vs. decimals: KiB, MiB, GiB, TiB (IEC, base 2) per a qualsevol mida que sigui una potència de 2 —mida de cau, de memòria, de pàgina, de bloc, rangs d’adreçament, etc.—, que és la immensa majoria de casos a EC: registres, memòries cau i memòria principal. KB, MB, GB, TB (base 10) es reserven per a les mides genuïnament decimals: l’emmagatzematge secundari (p. ex. la capacitat comercial anunciada d’un disc), els costos ($/GB) i les amplades de banda (GB/s, TB/s) (D-86). Explicat a A2.qmd (Essencial 2.5), primera aparició al llibre; en cas de dubte, per defecte KiB/MiB/GiB/TiB.
  • Hexadecimals: tres regles.
    • Majúscules o minúscules: la preferència és per majúscules (p. ex. 0xE6666666), però s’admeten minúscules perquè és el criteri de RARS. No cal, doncs, unificar-ho sistemàticament allà on ja apareguin totes dues grafies.
    • Amplada: els valors de 32 bits —adreces de memòria, contingut de registres i codificacions d’instrucció— s’escriuen sempre amb 8 dígits (0x00400000, t1 = 0x00000043), que és com els mostra RARS. La resta segueix l’amplada del seu rol: bytes (0xCC), mitges paraules (0x2211), immediats i camps (lui t1, 0x11223, VPN = 0x00001), màscares (0x7FFFFF) i les adreces de les màquines que defineix un problema (0x39 en una memòria de 64 bytes). Excepció explícita: si un problema escriu adreces de 32 bits en format reduït, sense els zeros de l’esquerra, perquè només en fan falta els bits de menys pes i l’enunciat no en fixa l’amplada, ho ha de dir amb una «Nota:» a l’enunciat i justificar-ho (D-30).
    • Separadors: les adreces de memòria van sense espais (0x10010000), no amb separador cada 4 quartets.
  • Ordre substantiu–adjectiu: els adjectius classificadors van darrere del nom: «precisió simple», «precisió doble», «la instrucció següent», «l’element següent». Anteposar-los («simple precisió», «la següent instrucció») és un calc de l’anglès. Excepcions, que sí que van davant: ordinals, quantificadors i indefinits, «mateix», «propi», «altre», adjectius valoratius idiomàtics i «simple» en el sentit de «mer» («un simple error tipogràfic») (D-31). Els qualificatius també van preferentment darrere: «una importància creixent», «les latències llargues», «dues modificacions possibles», «el format mínim» (no «una creixent importància») (D-72).
  • «No» davant d’un nom: amb guionet, com fixa l’IEC per a aquest ús de no («no-violència», «no-intervenció»): «no-associativitat», «no-distributivitat». Davant d’un adjectiu, sense guionet: «no és distributiva» (D-32).
  • Veu impersonal: Sempre: «Cal verificar que no hi ha errors» (no «hem de verificar»). Excepcions (D-33):
    • {.callout-tip}: segona persona del singular per a instruccions directes a l’estudiant (calcula, determina, suposa que…). També hi van les solucions dels problemes. Excepció dins de l’excepció mateixa: als exemples narrats (una traça o un escenari que es va desenvolupant pas a pas, no una instrucció puntual), s’admet el «nosaltres» expositiu (Considerem un sistema amb…, Suposem que…, Sabem que…). El criteri per triar entre tots dos: si la frase estableix el marc o l’estat d’un exemple, «nosaltres»; si demana una acció puntual a l’estudiant («calcula», «indica»), 2a persona del singular.
    • Enunciats dels problemes (#exr- de P1.qmd–P9.qmd): segona persona del plural («Traduïu», «Calculeu», «Contesteu»; no «Tradueix», «Calcula», «Contesta»).
    • Instruccions operatives pas a pas: imperatiu en segona persona del plural (descarregueu, obriu, executeu).

Puntuació

  • Punt d’acabament de frase: Sempre. Totes les frases del cos del text, incloses les llistes de vinyetes, han d’acabar obligatòriament en punt. Excepció: les llistes de passos en notació tècnica amb fletxa (→) no porten punt final, ja que no constitueixen prosa sinó notació de seguiment pas a pas.
  • Negretes acabades en dos punts: Els dos punts mai en negreta.
  • Nombres decimals: Amb coma, no amb punt. Ex: «0,5 V», «3,14», \(1{,}045\).
  • Abreviatura de versus: S’usa vs. (amb punt), que és la forma correcta en català segons l’Optimot. No s’usa «versus» desenvolupat excepte en prosa formal.

Ressaltat conceptual (negretes)

  • Conceptes nuclears: Paraules que defineixen l’essència de la secció (ex: abstracció, ISA).
  • Components del sistema: Elements de l’arquitectura (ex: registres, unitat de control).
  • Atributs clau: Paraules que marquen diferències operatives (ex: màxim rendiment, més lenta).
  • Sigles i acrònims: En les aparicions clau. A l’expansió, la sigla va en rodona, i la negreta, si cal, a la forma catalana (§Sigles, símbols i notació).
  • Referències a objectes: (ex: “Tal com mostra la Figura 1.2”).

Negretes dins de callouts:

  • Als callouts curts i sense títol per defecte (#cau- Essencial, #imp- Criteri EC), la negreta marca el nucli del recordatori o criteri (coherent amb la taula de callouts de §Callouts; vegeu-hi l’excepció per a callouts llargs).
  • Als callouts llargs (#tip- Exemple, #nte- RISC-V, #wrn- Aprofundiment), s’aplica el mateix criteri de ressaltat conceptual que al cos del text.

Anglicismes i terminologia obligatòria

  • Primera aparició: Traducció al català seguida de l’anglicisme en cursiva i entre parèntesis. Exemple: biblioteques de funcions (libraries). Excepció: exception i interrupt, que es presenten junts a T9 (§T9).
  • Aparicions posteriors: sempre el terme català; l’anglès no el substitueix mai. La glossa (anglès) es pot repetir a la primera aparició de cada fitxer, perquè els problemes, les solucions i el laboratori es llegeixen sols (§T6, «guany (speedup)»; §T7, «d’arrencada en fred (cold-start)») (D-116).
  • Els termes anglesos, sempre en cursiva: a totes les aparicions, també als de [en_angles] (heap, target), a les taules i al text de les figures; si van en negreta, en negreta i cursiva (***). No als comentaris del codi, que és codi. La comprovació de la prosa (§Comprovacions per nivells) atura el commit amb un terme de [termes] en pla, que s’escriu en català, i amb un de [en_angles] sense cursiva; [angles_en_pla] de termes.toml en recull les excepcions, amb el motiu (noms propis, com «RISC-V GNU Compiler Toolchain», o el títol d’un document). Mira també les cel·les de les taules, però no les figures (D-116).
  • Triples asteriscs (***): S’utilitzen quan el terme anglès va en negreta, com a la presentació d’un concepte nuclear. Exemple: **maquinari** (***hardware***).
  • Lèxic anglès–català: el de 24_specs/termes.toml. El fitxer n’és la font de veritat, i el glossari de termes (12_sigles_simbols.qmd §Termes) se’n genera: un terme anglès que hi és es diu com hi consta, amb les observacions d’ús de la seva fila. Un terme nou s’afegeix al fitxer i es presenta al text, a la primera aparició del llibre, en el mateix commit, amb el terme català en negreta i l’anglès en cursiva entre parèntesis («memòria cau (cache)»). La comprovació del lèxic (§Comprovacions per nivells) atura el commit si una presentació del text no coincideix amb el fitxer (la forma catalana, el seu plural o una de les formes de presentacio del terme), si presenta un terme que no hi és o si un terme del fitxer no té cap presentació (D-115).
  • Quan canvia el terme d’un concepte, els identificadors (#nte-load-store, #sec-carrega-…) no canvien (D-35).
  • Terme català o anglès (D-116):
    • Es fa servir el terme català si una de les fonts lèxiques (§Referència normativa) en dona un per al concepte informàtic, o si, sense cap font, se’n pot formar un sintagma transparent amb termes que hi són («fallada de pàgina», «escriptura immediata»).
    • Entre dues formes catalanes, mana la de la font de més precedència. Si la fitxa del Termcat és d’una altra àrea que la informàtica, o confon dos conceptes que el llibre distingeix, es manté la forma del llibre i l’observació del terme n’anota l’excepció (pseudoinstruction, branch, throughput).
    • L’anglès, només en dos casos: quan ni les fonts ni un sintagma no donen cap terme català, o quan el llibre ha decidit no fer servir el que hi ha, perquè és molt poc usat (heap, pipeline). Tots dos casos són a [en_angles] de termes.toml, la segona taula del glossari, que recull tots els termes que el llibre fa servir en anglès.

Formes que no s’han de fer servir

No són termes anglesos, i per això no són al glossari: són formes que no són normatives o que no són el terme informàtic en català. La taula es genera de [no_admeses] de 24_specs/termes.toml, que és el que llegeix la comprovació de la prosa (§Comprovacions per nivells): atura el commit amb les formes de la primera columna, també en plural, en femení o conjugades, i una forma nova hi entra en el mateix commit que les treu del corpus (D-105, D-115).

No s’escriu S’escriu Observacions
fallo fallada
anidat / anidament, aniuat / aniuament imbricat / imbricació Bucles imbricats, crides imbricades. «Aniuat» no és el terme informàtic en català (D-34).
empotrat encastat Sistemes encastats (embedded systems).
promig mitjana
tamany mida No normatiu. Per a la distinció mida vs. longitud, vegeu més avall.
lliurable lliurament
mapeig, mapejar mapatge, mapar
ample de banda amplada de banda Forma normalitzada (Termcat).
punt flotant coma flotant Calc de floating point (D-37).
comanda ordre En informàtica, command és «ordre» («línia d’ordres», Termcat); al DIEC, «comanda» és un encàrrec comercial (D-106).
solapar, solapament superposar, superposició; fer alhora No és al DIEC. A l’espai, «superposar-se» («els camps no se superposen»); en el temps, «fer-se alhora» o «coincidir» (D-106).
indentar, indentació sagnar, sagnat Indentation és «sagnat» (Termcat; el DIEC defineix «sagnia» remetent a «sagnat»). «Indentar» i «indentació» només són al Termcat en ciències de la salut (D-106).
encuar posar a la cua No és al DIEC; «posar a la cua» és el terme del Termcat (D-106).
descomposa / descomposem / descomposen / descomposat descompondre (descompon, descomponem…) «Descomposar» no és al DIEC. La taula en dona les formes conjugades i no l’infinitiu, perquè la comprovació (§Comprovacions per nivells) també trobaria «descomposició», que és correcte (D-106).
rota / roten / rotat girar, fer una rotació Al DIEC, «rotar» és fer rots. «Rotació» és correcte, i per això hi van les formes conjugades, com a «descomposar» (D-106).
càrrega capacitiva capacitat equivalent Calc de capacitive load (13_contrib.qmd §T6).
sobreeiximent, sobreeixir desbordament, desbordar(-se) Overflow (Termcat).
vector de salts taula de salts Jump table (Viquipèdia).
ordenació de bytes ordre dels bytes Endianness (Termcat).
tipus de dada tipus de dades Data type (Termcat).
gandula tardana «Avaluació tardana» (lazy evaluation, Softcatalà).
seqüència d’escapament seqüència d’escapada
punt d’aturada punt de ruptura Breakpoint (Termcat).
registre de pila punter de pila Stack pointer, sp.
  • enter vs. natural: a EC, enter vol dir amb signe (Ca2, tipus int) i natural, sense signe (tipus unsigned), com a T1 (Codificació de nombres naturals en base 2). Per tant, «enter amb signe» i «natural sense signe» són redundants, i «enter sense signe» és contradictori: s’escriu «enter» o «natural». S’admet la glossa entre parèntesis allà on el text explica la correspondència amb l’anglès o defineix un símbol, com «naturals (sense signe)» a la presentació de lhu/lbu (A2) o \(x_u\) a 12_sigles_simbols.qmd (D-39).
  • mida vs. longitud: mida designa l’espai que ocupa un tipus o una variable en memòria (p. ex. la mida d’un int és de 4 bytes); longitud designa el nombre d’unitats d’un element seqüenciable —bits d’un registre o camp, elements d’un vector, caràcters d’una cadena— (p. ex. la longitud del camp opcode és de 7 bits).

Sigles, símbols i notació

  • Expansió a la primera aparició: la primera vegada que una sigla apareix al llibre, fora dels aprofundiments ({.callout-warning}), s’expandeix. Només a la primera aparició del llibre, no a cada capítol: el lector té el compendi de sigles (12_sigles_simbols.qmd); les expansions que ja hi ha en capítols posteriors (els problemes, les solucions i el laboratori es llegeixen sols) no es treuen (D-89). Si la primera aparició és en un títol, en una taula o en una fórmula, l’expansió va al paràgraf següent (D-118).
  • Format únic de l’expansió, a la primera aparició i a qualsevol altra: l’anglès, en cursiva i en minúscula, tret dels noms propis (IEEE, POSIX, GCC) i de la primera lletra d’una frase; la sigla, en rodona, ni en negreta ni en cursiva; i la forma catalana, que pot anar en negreta si l’expansió és la presentació d’un concepte (§Ressaltat conceptual), però el parèntesi no. Les formes són les de [sigles] de 24_specs/termes.toml (D-118):
    • Forma catalana i expansió anglesa: «unitat d’estat sòlid (solid-state drive, SSD)», «bloc d’activació (stack frame, BA)».
    • Sense forma catalana: «not a number (NaN)», «Institute of Electrical and Electronics Engineers (IEEE)».
    • Una sigla catalana, sense expansió anglesa: «sistema operatiu (SO)».
    • Cap altra variant: ni «(Solid-State Drive, SSD)», ni «(solid-state drive o SSD)», ni «SSD (solid-state drive)».
  • Cada sigla s’ha de recollir a [sigles] de 24_specs/termes.toml, la font de veritat de les sigles, de la qual es genera el compendi de sigles (12_sigles_simbols.qmd §Sigles) (D-118).
  • Un cop definida, s’ha d’usar sempre, en majúscules i sense cursiva. Fora de l’expansió, pot anar en negreta (§Ressaltat conceptual).
  • Sense plural: la sigla no porta marca de plural; el nombre el diu el determinant («les API», «dues GPU», «els LED») (D-79).
  • Article i preposició davant de la sigla: s’apostrofen segons la pronúncia, com fixa la GIEC. Davant de les que es lletregen i comencen amb una lletra de nom vocàlic (a, e, i, o, u, efa, ela, ema, ena, erra, essa) o es llegeixen com un mot que comença en vocal: «l’ISA», «l’MMU», «l’MC», «l’RSE», «l’SO», «d’MP», «de l’LSB», «d’RV32I», «d’UNIX», «d’NVIDIA». Davant de les que es llegeixen com un mot que comença en consonant, no: «la RAM», «la ROM», «de RARS». «La IA», com a l’Optimot. El mateix criteri val per al codi, que es llegeix com un mot: «d’addi», «l’a0», però «de lw», «la sp» (D-80).

Criteri d’inclusió al compendi de sigles: s’inclou tota sigla que aparegui al cos del text o als callouts {.callout-caution}, {.callout-note}, {.callout-tip} o {.callout-important}.

S’exclouen:

  • Sigles que només surten als {.callout-warning} (aprofundiments no avaluables).
  • Noms de camps individuals de registres i bits de control (p. ex. MIE, MPIE, ASID). VPN i PPN no hi entren: a T8 són conceptes (el número de pàgina virtual i el de pàgina física, que donen nom a §Traducció d’adreces) i no només noms de camp, i per això tenen entrada a la taula de sigles (D-40).
  • Sigles institucionals que el lector coneix (UPC, DAC) i referències a temes, fitxers i sessions (T7, A1, L4…). Les dels estudis i les assignatures (GEI, FIB, EC, IC, PRO1) hi entren: qui ve de fora pot no conèixer-les (D-118).
  • Noms de les variants i les extensions de RISC-V (RV32I, RV32IM, RV64I, RVA23…): són noms (§Codi, matemàtiques i cursiva, «Text pla»), i A2 n’explica la nomenclatura (D-118).
  • Operacions lògiques en prosa (AND, OR, XOR, NOT; §Codi, matemàtiques i cursiva).
  • Unitats de mesura de bytes (KB, GB, MB…).
  • La resta de mots en majúscules que no són sigles del llibre: noms propis (GNU, UNIX), noms de camps i de registres en rodona (MR, MD), notacions que defineix un enunciat (NRM, DNRM i INF a P5)… Són a [no_sigles] de 24_specs/termes.toml, cadascun amb el motiu; una clau que no és un sol mot és un text literal («ISO/IEC 9899:2024») (D-118).

La comprovació de les sigles (25_scripts/sigles.py, a cada commit; §Comprovacions per nivells) llegeix el llibre en l’ordre de chapters:, amb la Presentació al principi, el compendi al final i els fragments de 21_riscv/ al lloc on s’inclouen. Atura el commit si una sigla de la taula no s’expandeix, en el format únic, a la primera aparició fora dels aprofundiments (o al paràgraf següent, si és en un títol, en una taula o en una fórmula); si una expansió no segueix el format únic, on sigui; si, per a qualsevol sigla, també les dels aprofundiments que no són a la taula, l’expansió té una de les variants que el format exclou (la sigla en negreta dins del parèntesi, l’anglès en negreta i cursiva, «(anglès o SIGLA)», «SIGLA (anglès)»); si una sigla del text, fora dels aprofundiments, no és a la taula ni a [no_sigles]; si una sigla va en plural (D-79); i si una sigla de la taula no apareix enlloc fora dels aprofundiments. Les cursives no compten com a aparició: una sigla dins d’una expansió anglesa («Advanced RISC Machines») no és una aparició de RISC (D-118).

La taula de sigles (12_sigles_simbols.qmd §Sigles) té tres columnes, «Sigla», «Significat» i «Observacions», i va per ordre alfabètic, sense comptar els signes (E/S s’ordena com «es»). El significat és com l’expansió del text sense la sigla: «Unitat d’estat sòlid (solid-state drive)», «Not a number» o «Sistema operatiu». No s’edita a mà: la genera 25_scripts/gen_glossari.py a auto_termes/, com el glossari de termes (## Termes, més avall), a partir dels camps de cada sigla de [sigles]: ca, la forma catalana; en, l’expansió anglesa; obs, les observacions; i excepcio, el motiu pel qual la comprovació no en mira les aparicions al text, si n’hi ha (D-118).

Símbols i notació (mateix fitxer 12_sigles_simbols.qmd, seccions ## Símbols i ## Notació):

  • ## Símbols: glossari de variables/paràmetres d’equacions (símbol → concepte que representa), contextual per tema. Un mateix símbol pot tenir significats diferents segons on s’usi (p. ex. \(m\) és la mantissa a T5, però la taxa de fallades a T7): en aquest cas s’indica a la columna «Observacions». Columnes: Símbol | Significat | Tema | Observacions. Ordenació: alfabètica pel símbol/nom de variable.
  • ## Notació: operadors i convencions de representació, majoritàriament transversals i estables amb independència del tema (p. ex. \(\oplus\), \(>>>\), \(\lfloor\cdot\rfloor\)). Columnes: Notació | Significat | Tema | Observacions; la columna «Tema» només s’omple quan la notació és pròpia d’un tema (p. ex. la de les taules ISA), i en cas contrari es deixa en blanc. Ordenació: per categoria funcional (operadors lògics/bit a bit, desplaçaments, funcions…), no alfabètica.
  • ## Termes: glossari anglès → català dels termes de 24_specs/termes.toml, amb el tema de la primera presentació al text. No s’edita a mà: el genera 25_scripts/gen_glossari.py a auto_termes/ (una taula per fitxer), que no es versiona i que 12_sigles_simbols.qmd inclou; com auto_riscv/, ha d’existir abans d’invocar quarto, i make render i make taules ja el generen. El tema surt de la primera presentació «terme (english)» del corpus, en l’ordre del llibre, amb els fragments de 21_riscv/ al lloc on els inclou el capítol, i el compendi al final («Compendi»). Només compten les presentacions amb el terme català en negreta. Els termes anglesos són les cursives del cap del parèntesi, que pot portar abans un sinònim o una sigla en negreta, codi o una fórmula: «(write-back o copy-back)», «(BA, stack frame)», «(\(V\), valid bit)». No hi entren les expansions de sigla, tant si la sigla és a [sigles] del fitxer («NaN (Not a Number)») com si la segueix al parèntesi («(fused multiply-add, FMA)»), ni les glosses que no són termes, a [no_presentacions] del fitxer (la interfície de RARS, els noms de camps i de bits). És el lèxic del llibre (§Anglicismes i terminologia obligatòria; D-115). Forma de les cel·les: cada cel·la de les dues taules comença en majúscula, i cada terme va en singular, en anglès i en català, tret dels que gairebé no es fan servir en singular («Excepcions precises», amb nombre = "plural" al fitxer); una presentació en plural al text és la del mateix terme, i --comprova avisa d’un terme del fitxer que sembli plural i no porti nombre. Els termes que el llibre manté en anglès (la segona taula) no surten a la primera (D-108). Columna «Fonts»: les fonts que donen la forma per al concepte del llibre (§Referència normativa), totes i per ordre de precedència, amb l’enllaç a la consulta, o «Sintagma» o «Llibre»; surt del camp fonts del fitxer, i els enllaços els fa el generador amb una plantilla per font, perquè les fitxes no tenen identificadors estables (D-116).
  • Criteri de distinció: si el signe es “llegeix” com una magnitud amb nom i valor contextual → Símbols. Si es “llegeix” com una operació o convenció de representació → Notació.
  • Sigles que també apareixen com a variable d’equació (p. ex. CPI): doble entrada — definició completa a ## Sigles, entrada curta amb remissió («Vegeu CPI a Sigles») a ## Símbols. Criteri: si la sigla apareix dins d’una fórmula matemàtica (no només en prosa), guanya entrada també a Símbols.
  • Excepcions de patró notacional conegudes i acceptades: quan una font de referència (p. ex. Harris & Harris) imposa una notació que trenca un patró general del llibre, es documenta com a excepció explícita (amb un callout #imp- si cal remarcar-ho al text, com a @imp-notacio-desplacament-aritmetic a A3.qmd), no com un error a corregir silenciosament.

Codi, matemàtiques i cursiva

Regla general: el format el determina la naturalesa de l’element, no el context on apareix.

  • Backtick (`) — codi: tot allò que existeix literalment en un programa, en una ISA o en un fitxer: registres (t0; també els CSR: mepc, mstatus…, fins i tot en títols de secció, com fa T9), instruccions (addi), directives (.data), variables i expressions C (i, p++), camps de bits (opcode), adreces concretes (0x10010000), fitxers, ordres i etiquetes.
  • LaTeX math ($…$) — matemàtiques: quantitats, variables i expressions matemàtiques: mides genèriques (\(n\) bits, \(B = 2^b\)), índexs de fórmules i algorismes (\(q_i\)), rangs (\([-2^{11}, 2^{11}-1]\)), operacions (\(rd \leftarrow M_w[rs1 + SignExt(offset)]\)). Els superíndexs numèrics s’escriuen sempre en math ($2^{8}$), també dins de cel·les de taula; no s’usa la sintaxi Pandoc 2^8^.
  • Cursiva — llengua: els termes anglesos, a totes les aparicions (vegeu §Anglicismes), i èmfasi lleu. Mai per a codi ni per a variables matemàtiques.
  • Text pla — la resta: nombres amb unitats («8 bits», «4 bytes»), noms d’arquitectures i extensions (RISC-V, RV32I, extensió M), tipus de format d’instrucció (S, B).

Cas fronterer — variables d’una lletra: si l’element viu en un programa concret (està declarat al codi de l’exemple), backtick (i, p); si viu en una fórmula o algorisme abstracte, math (\(i\), \(n-1\)).

Dins de les fórmules:

  • \text{…}: paraules catalanes, sigles i unitats (\(\text{CPI}\), \(t_h = 2\text{ ns}\), \(\text{núm. encerts}\)). És l’opció per defecte per a qualsevol camp o paraula (\(\text{offset}\), \(\text{índex}\)).
  • \texttt{…}: literals de codi dins d’una fórmula (\(\texttt{0x100100F}\), \(\texttt{vec[i]}\)), també les constants d’un programa (\(\texttt{NC}\), \(\texttt{NF}\)). No \mathtt{…} (D-41).
  • Subíndexs: els que són etiquetes van en cursiva, com la resta del símbol, també quan són sigles: \(t_{clock}\), \(n_{ins}\), \(\text{CPI}_{ideal}\), \(V_{CC}\), \(m_{L1}\), \(t_{MP}\). \text{…} en un subíndex només per a paraules o sintagmes descriptius (\(t_{\text{millorat}}\), \(t_{\text{no-millorat}}\)) i per a les etiquetes d’un \underbrace. La regla de \text{…} per a les sigles s’aplica a la sigla que fa de variable (\(\text{CPI}\), \(\text{TAM}\)), no a l’etiqueta d’un subíndex (D-42).
  • Excepció: les taules ISA (21_riscv/). La notació de transferència de registres hi va tota en cursiva matemàtica: registres i camps (\(rd\), \(rs1\), \(PC\), \(mepc\), \(MPIE\)), operands (\(offset\), \(imm12\)) i funcions (\(SignExt\), \(M_w\)). \(PC\) hi és un registre, al costat de \(rd\), no una sigla de la prosa. La notació és a la taula ## Notació de 12_sigles_simbols.qmd (D-42).

Després d’una fórmula destacada, la frase continua en minúscula, perquè la fórmula en forma part: «on \(t_{exe}\) és el temps…», «on:» (D-112).

Operacions lògiques (AND, OR, XOR, NOT): la forma depèn del context, com la resta d’aquesta secció (D-43).

Context Forma Exemple
Fórmules ($…$), incloses les taules ISA de 21_riscv/ \(\land\), \(\lor\), \(\oplus\) i, per a NOT, la barra superior \(\overline{x}\) (no \(\sim\), \(\neg\) ni \text{ and }) \(rd \leftarrow rs1 \land rs2\), \(csr \leftarrow csr \land \overline{rs1}\), \(\overline{0011\,0011_2}\)
Prosa: nom de l’operació o de la porta AND, OR, XOR, NOT, en majúscules, sense ` ni cursiva «l’OR lògic», «porta NOT», «fer XOR amb tots uns»
Instruccions i pseudoinstruccions Minúscula, amb ` (són codi) and, xori, not
Codi C Els operadors del llenguatge &, \|, ^, ~
Comentaris dels blocs de codi Lliure: no es normalitzen # ~(A xor B)

Els símbols són els de la taula ## Notació de 12_sigles_simbols.qmd. Quan una fórmula combina \(\land\) i \(\lor\), s’hi posen parèntesis encara que la precedència no els faci necessaris: \(\big((a_i \oplus b_i) \land c_i\big) \lor (a_i \land b_i)\).

Criteri per context:

Context Backtick Math Cursiva
Cos del text ✓ ✓ ✓ (anglicismes)
Títols de secció {#sec-} ✓ ✗ (reescriure el títol) ✓ (només manlleus sense equivalent català)
Títols de callout ✓ ✓ ✓ (anglicismes)
Cel·les de taula ✓ ✓ ✓
Captions de figura/taula ✓ ✓ ✓
Comentaris de blocs de codi (tot és codi) ✗ (no es renderitza) ✗
Etiquetes SVG segons 24_specs/svg.md (MONO per a codi); sense MathJax: notació Unicode (×, ≤, ²) ✓ (termes anglesos, font-style="italic")

Manlleus en cursiva als títols de secció: la cursiva als títols de secció es reserva exclusivament als manlleus sense equivalent català consolidat (p. ex. loop tiling), que es mantenen en cursiva també quan encapçalen una secció (com a la resta del text). No s’usa mai per a èmfasi ni per a cap altre motiu; per a la resta de casos, el títol es reescriu. Un cop es fixi un equivalent català per a un manlleu, el títol s’hi actualitza i deixa de dur cursiva.

Exemples d’aplicació (llista de referència ràpida):

  • Sense backtick:
    • RISC-V, RV32I, Extensió “M”, Extensió “Zicsr”.
    • Tipus d’instrucció S, B.
    • Ctrl + R.
    • A RARS: “F3”, “Execute”, “Settings”.
    • Operacions matemàtiques: \(rd \leftarrow M_{w}[rs1 + SignExt(offset)]\).
  • Amb backtick:
    • Registres ISA x0–x31, ABI a0–a7.
    • Registres CSR mepc, mcause, mstatus, mtvec, mip, mie, mtval, satp, etc.
    • Operands rd, rs1, rs2.
    • Instruccions ret, addi, lw, ecall, mret, sfence.vma.
    • Directives .text, .data.
    • Codi addi t0, s1, 100, int main() { return 0; }.
    • Camps de bits opcode, funct3.
    • Variables i i altres elements de codi >>, i++.
    • Ordres quarto render --to html.
    • Noms de fitxers A1.qmd, 15_bibliografia.bib.
    • Noms de branques contingut/t5-vectors.
    • Noms d’etiquetes #nte-TODO, @sec-callouts.
    • Adreces de memòria concretes 0x00400000, 0x10100000–0x10100003.

Format

Callouts

Regles generals:

  • Tots han d’anar etiquetats (p. ex. ::: {#nte-TODO .callout-note}). Cal substituir el TODO per una cadena única.
  • Referenciar sempre amb @prefix-etiqueta des del cos del text, altres callouts, etc.
  • El títol ## títol no és obligatori en callouts curts.
  • Localització: a continuació de la referència o explicació al text.

Numeració: tot callout amb etiqueta (#nte-, #imp-, #cau-, #tip-, #wrn-) el numera Quarto automàticament (el mateix mecanisme de crossref que numera figures i taules), amb el prefix propi de cada tipus definit a _quarto.yml §language (crossref-nte-prefix: "RISC-V", crossref-tip-prefix: "Exemple", crossref-cau-prefix: "Essencial", crossref-wrn-prefix: "Aprofundiment", crossref-imp-prefix: "EC"; les claus callout-*-title fixen el mateix text com a títol visible dins el bloc). No cal cap acció ni cap etiquetatge més enllà del prefix habitual: la numeració («RISC-V 5.3», «Exemple 5.2»…) és conseqüència directa de tenir {#prefix-nom}.

Icones: es couen a custom.scss, que sobreescriu la icona per defecte de Quarto per a .callout-note (CPU, verd), .callout-warning (porta oberta, lila) i .callout-caution (check, vermell). .callout-tip i .callout-important no tenen icona personalitzada i mantenen la de Quarto per defecte (bombeta i cercle d’exclamació, respectivament); és una omissió no deliberada, no un criteri establert. Els colors de tots cinc tipus (incloent-hi tip i important) es defineixen a custom_light.scss/custom_dark.scss ($callout-color-*).

Tipus Prefix Classe Color Aval. Títol Ús i particularitats
RISC-V #nte- .callout-note Verd Sí Sí Material de referència ISA/ABI. Introducció al text sempre que sigui possible. Contingut compartit amb el compendi: fitxer a /21_riscv/ amb {{< include >}}. Figures i taules internes sense etiqueta ni caption. Títols: ## RV32I ISA —, ## Zicsr ISA —, ## RV32IM ISA —, ## RV32F ISA —, ## RV32I ABI —, ## RV32F ABI —, ## Pseudoinstruccions — (totes, de qualsevol extensió: les defineix el manual de l’assemblador, no l’ABI; D-66), ## Directives —, ## RARS —, ## RV32I Registres —, ## Supervisor ISA — (instruccions de l’arquitectura privilegiada disponibles en mode S, com sfence.vma; els CSR de mode M s’agrupen sota RV32I ISA — per coherència amb la resta de CSR de la variant RV32).
Criteri EC #imp- .callout-important Blau Sí No Criteris de l’assignatura. Per defecte, sense títol, curt, en negretes. Si el contingut supera ~4 línies o barreja diversos criteris, s’admet un títol curt (com als #nte-) en lloc de forçar la brevetat. No s’introdueix al text. No seguir una convenció d’EC no penalitza l’avaluació, tret que l’enunciat ho indiqui explícitament: ho diu el primer callout #imp- dels apunts, #imp-convencions-ec (A1) (D-85).
Essencial #cau- .callout-caution Vermell Sí No Contingut indispensable o recordatori fonamental. Per defecte, sense títol, curt, en negretes, i s’ha de llegir com un ressaltat del text. Si el contingut supera ~4 línies o barreja diversos aspectes, s’admet un títol curt en lloc de forçar la brevetat.
Exemple #tip- .callout-tip Groc Sí Sí Il·lustració d’explicacions. Format opcional: Pregunta → Solució → Resposta. Veu: §Criteris generals → Veu impersonal. No s’introdueix al text. Als temes pilot (de moment, T1), la part de resposta dels exemples de pregunta i solució va dins d’un div ::: {.resposta}, que l’HTML plega sota «Mostra la solució» i el PDF deixa igual; els exemples il·lustratius, sense pregunta, no en porten (D-90).
Aprofundiment #wrn- .callout-warning Lila No Sí Contingut d’enriquiment no avaluable. No s’introdueix al text; s’hi pot remetre puntualment amb una referència @wrn-… com a punter opcional, mai com a dependència (el cos del text ha de ser autocontingut sense l’aprofundiment). Si >1 línia: collapse=true.
Figura #fig- No Porta caption. Remissió des del text: §Referències creuades.
Taula #tbl- No Porta caption.
Codi #lst- No Porta caption. Només els blocs que es referencien, amb la forma i la remissió de §Referències creuades.
Equació #eq- No
Secció #sec- No
Problema o exercici #exr- No
Solució #sol- No
Algorisme #thm- No

Disponibles: #alg- #lem- #cor- #prp- #cnj-

Blocs de codi

El camp filename indica el llenguatge o el context del bloc:

Contingut Sintaxi
Pseudocodi ```{.default filename="Pseudocodi: multiplicació seqüencial"}
C ```{.c filename="C"}
Assemblador RV32I ```{.s filename="RV32I"}
Assemblador RV32IM ```{.s filename="RV32IM"}
Assemblador RV32IF ```{.s filename="RV32IF"}
Assemblador RV32IZicsr ```{.s filename="RV32IZicsr"}
Fitxer .s específic ```{.s filename="s3_4_1.s"}
Codi deliberadament incorrecte ```{.s filename="⚠️codi_erroni__nom_reservat.s⚠️"}
Bash ```bash
  • Títol dels blocs de pseudocodi: «Pseudocodi: què fa el bloc» («Pseudocodi: divisió amb restauració», «Pseudocodi: while → do-while»), no «Pseudocodi» sol. «Pseudocodi» al davant marca el llenguatge, com «C» o «RV32I» a la resta de blocs; el que segueix els dos punts diu de quin algorisme o transformació es tracta, que és el que el lector busca quan n’hi ha més d’un a prop. ⚠️ El separador són dos punts, no un guió llarg: el filename arriba al PDF en font monoespaiada, on «—» surt com a --- (D-45).
  • Algorismes (#thm-) en rodona: el text d’un bloc Algorisme no va en cursiva, ni a l’HTML ni al PDF. Al PDF, preamble.tex treu la cursiva de l’estil plain del \newtheorem que genera Quarto; si mai s’hi declara un altre entorn d’estil plain, també sortirà en rodona (D-46).
  • Ressaltat dels blocs .s: definició pròpia, 24_specs/riscv.xml (format KDE, el de skylighting, que és el ressaltador de Pandoc; syntax-definitions: a _quarto.yml, als dos formats). Classes: instruccions (kw), salts, crides, retorns i crides al sistema (cf), registres i CSR (va), directives (pp), etiquetes i crides a macros (fu), paràmetres de macro (at), modes d’arrodoniment (bu), i comentaris, cadenes, caràcters i nombres. El llenguatge s’ha de dir s: Pandoc tria la definició pel nom de la classe abans que per l’extensió, i amb un altre nom guanyaria gnuassembler. Una instrucció o una directiva nova que surti sense ressaltar s’afegeix a la seva llista del fitxer (D-47).
  • Codi deliberadament incorrecte (codi_erroni): un bloc que és incorrecte a posta —un contraexemple, un error que el text explica— porta al filename el prefix codi_erroni__, un nom descriptiu i l’extensió, entre dos senyals d’avís: ⚠️codi_erroni__<nom>.<ext>⚠️. La marca té dos destinataris: el lector, que veu a la capçalera del bloc que aquell codi no s’ha de copiar, i les eines, que l’exclouen per forma de les comprovacions i de les escombrades del corpus (verifica_format_codi.py ja ho fa). Al bloc de gcc, el nom de dins de l’ordre i de la sortida del compilador és el del fitxer, sense els senyals: la marca és del títol del bloc. Al laboratori, el bloc de l’enunciat de #exr-depuracio no porta la marca, perquè el nom és el del fitxer de lliurament: verifica_laboratoris.py en dedueix que no és autònom pel contingut (D-48).
  • Cap referència creuada dins dels blocs de codi. Quan un comentari d’un bloc ha de remetre a una altra part del llibre, la remissió va a la prosa adjacent; dins del bloc hi queda, si cal, el nom del tema o del fitxer en text pla. Quarto no resol @… dins d’un bloc de codi (pandoc no hi analitza res: el contingut és una cadena crua) i es renderitza literalment. A més, els comentaris dels blocs de laboratori l’alumne els copia al seu fitxer.

Estil de codi C

  • Sagnat: múltiples de 4 espais.
  • Comentaris: sempre amb //, línia per línia, també els que n’ocupen més d’una; no /* */. Així es pot desactivar un bloc sencer envoltant-lo amb /* … */, perquè C no admet comentaris /* */ imbricats. A2 ho diu a #imp-codi-format-criteris (D-83).
  • Punt d’entrada: void main() quan el C és notació per traduir a mà a assemblador; int main quan el C es compila de debò o quan la cadena de compilació és el tema. Fora d’EC, en un programa de C normal compilat per a un SO, cal int main (D-49).
  • Porten int main el bloc d’A2.qmd de Aprofundiment 2.8, que es compila de debò i del qual se cita la sortida del compilador, i el de P3.qmd/S3.qmd Exercici 12.37, que tracta del flux de compilació i enllaçat. No són excepcions: són l’altra meitat de la regla.

Estil de codi RISC-V

EC 2.7

La part mecànica dels criteris (F1–F4: columna 0 per a les directives de segment i de visibilitat i per a les etiquetes, 8 espais de sagnat, cap tabulador; F5: el mnemònic o la directiva en un camp de 8 caràcters, i els operands a la columna 16; F6: cap etiqueta ni constant b o B) es comprova amb python3 25_scripts/verifica_format_codi.py sobre tots els blocs .s del corpus, tret dels codi_erroni; --detall en llista les línies. Els operands se separen amb una coma i un espai. La columna dels comentaris no es regula. El format no s’avalua per si mateix (el callout ho diu) (D-50).

Figures i material gràfic

  • Tots els diagrames nous es generen com a SVG (no Mermaid).
  • Text alternatiu i mida a l’HTML: el <desc> de cada SVG n’és el text alternatiu, i el filtre 25_scripts/figures.lua (a filters: de _quarto.yml) el copia a l’alt de la imatge; el peu es queda al .qmd, i el <desc> ha de descriure el que es veu, no repetir-lo. El mateix filtre dona a cada imatge, només a l’HTML, l’amplada del viewBox per 1,4, de manera que el text de totes les figures té la mateixa mida; en un visor estret s’encongeixen fins a la columna, i les que porten {width=…} al .qmd es respecten (24_specs/svg.md §2). Tot SVG consumit porta <title> i <desc> (D-51).
  • Inventari: una taula per figura i una per fitxer font, amb els avisos (orfes, duplicats, placeholders, <title>/<desc>, colors fora de paleta, textLength, peus i remissions). El genera 25_scripts/inventari_figures.py, que mesura pel contingut i no pel nom, quan es demana: make inventari l’escriu a 25_scripts/out_inventari_figures/figures.md, que no es versiona. Els avisos, make comprova els dona a cada commit (§Comprovacions per nivells) (D-104).
  • Fitxers orfes: 25_scripts/orfes.py (a cada commit, amb make comprova) llista els fitxers versionats que cap altre fitxer no cita, tret dels de 22_figs_originals/conservats/ i de la configuració de les eines. Un orfe es mou a conservats/, si és un original que es vol conservar, o s’esborra (D-98).

Política de generació SVG

La prioritat és sempre generar l’SVG des de zero amb elements natius (<rect>, <line>, <text>, etc.). El PDF original es pot usar com a referència visual, però la figura es reprodueix com a SVG natiu.

Figures de nova creació (opció per defecte, tots els temes): - Construïdes des de zero amb elements SVG (<rect>, <line>, <text>, etc.). - Fonts i colors de la paleta del projecte (vegeu §Paleta de colors més avall). - Es desen a 22_figs_originals/; la variant dark es genera automàticament pel pre-render (25_scripts/gen_dark.py).

Figures extretes dels PDF originals (reservat per a figures complexes):

L’extracció via pymupdf (text_as_path=True) és el recurs per a figures que no és viable reproduir com a SVG natiu en un temps raonable (gràfics multisèrie, circuits detallats, geometria molt densa). La decisió es pren conjuntament amb l’editor del llibre. Es desen a 22_figs_originals/, perquè són dels materials dels professors d’EC (§Convencions SVG); vegeu 24_specs/svg.md §15 per a com es refan i la llista de figures existents.

Figures de registres de bits: - Definides a 24_specs/registres.toml (font de veritat). - Generades automàticament pel pre-render (25_scripts/gen_regs.py). - Inclou formats d’instrucció (R, I, S, B, U, J, R4) i un compendi, generat automàticament a partir de les entrades instruccio_tipus_* del TOML, sense entrada pròpia: compendi_registres, amb els set formats, a 11_riscv.qmd i a A2 (#nte-instruccions-tipus; vegeu §T2 i T3, «Formats d’instrucció d’RV32I»). Quins formats porta ho diu COMPENDIS, a gen_regs.py. - Figures de registres CSR: A5_fcsr, A9_mstatus, A9_mtvec, A9_mepc, A9_mcause, A9_mip, A9_mie, A9_satp. - El nom d’un camp d’un bit va girat, perquè no hi cap; la clau horitzontals d’un registre en llista els que no s’han de girar (la «S» d’A5_ieee754_format_registre) (D-52).

Flux de pre-render (_quarto.yml):

El pipeline de pre-render és a _quarto.yml (clau project.pre-render), que n’és la font de veritat: no es duplica aquí. Els generadors que hi intervenen, i el sufix que deixa cadascun a auto_figs/, són a la taula de sufixos de §Convencions SVG; a més, 25_scripts/gen_crops.py hi fa els retalls (§Retalls) i 25_scripts/gen_dark.py, les variants _dark.

Paleta de colors

La paleta completa (colors light i dark, per zona semàntica) és a 24_specs/svg.md §10. La taula de substitució light → dark per al pipeline automàtic és el bloc #svg-dark-replacements de 24_specs/svg.md §13. Per modificar qualsevol color, editeu només aquells blocs. Les variants fosques no es generen ni s’editen a mà: les fa 25_scripts/gen_dark.py al pre-render, per a totes les figures (natives, extretes de PDF, de registres i generades).

El codi de colors és consistent al llarg de tot el llibre i s’aplica tant a les figures SVG com a les taules amb color. Cada tema pot introduir associacions semàntiques pròpies (per exemple, a T7: blau=memòria cau, verd=memòria principal, groc=SSD, vermell=disc; a T8, blau i verd per als processos P1 i P2, blau per a les PTE vàlides, groc per al TLB i vermell per al disc i la fallada de pàgina, i, com a T7, blau=memòria cau i verd=memòria principal), però sempre dins la mateixa paleta.

Convencions SVG

Totes les convencions tècniques de les figures SVG (canvas, marges, escales, fonts, colors, ratlles indicadores, etiquetes, fletxes) són a 24_specs/svg.md. Per crear o modificar una figura SVG, llegiu aquest fitxer com a primera referència.

Convenció de noms dels fitxers font: <F><N>_nom_figura.svg (guió baix, no guió), desats a 22_figs_originals/, on <F><N> és el fitxer que consumeix la figura: A3_, P5_, S3_, L3_… Una figura que també surt al compendi, o un original conservat que el llibre no consumeix (D-68), pren el prefix del tema (A<N>_). La mateixa arrel nomena la secció del .toml d’un generador ([BA.L3_ba_moda]) i la sortida d’auto_figs/ (D-76). Les figures externes s’emmagatzemen a 23_figs_externes/.

Sufixos d’origen. Tot el que hi ha a auto_figs/ es diu <nom>__<origen>_<variant>.svg: l’origen diu d’on surt la figura, i la variant és light o dark (la fosca la fa sempre gen_dark.py). Els sufixos d’origen són:

Sufix D’on surt Qui l’escriu
__original 22_figs_originals/<nom>.svg, figures natives norm_font.py
__extern 23_figs_externes/<nom>.svg, figures d’una font externa norm_font.py
__registre 24_specs/registres.toml gen_regs.py
__BA 24_specs/BA.toml, blocs d’activació gen_BA.py
__mapa 24_specs/mapa.toml, mapes de memòria: la memòria de RARS i la pila en diversos moments d’una crida gen_mapa.py (D-67)
__subrutina 24_specs/subrutines.toml, dependències de dades de les subrutines gen_subrutines.py
__MC 24_specs/MC.toml, memòria cau (simulada) gen_MC.py
__memoria 24_specs/memoria.toml, memòria per bytes gen_memoria.py

Un sufix nou és un generador nou del pre-render (24_specs/svg.md §17), i s’afegeix a aquesta taula. Com que l’origen és al sufix, una figura pot tenir la mateixa arrel amb dos orígens: A3_deps_exemple__original i A3_deps_exemple__subrutina. Els retalls de gen_crops.py no porten sufix d’origen: es diuen com el retall de 24_specs/retalls.toml.

Originals substituïts per una figura generada. Quan el llibre passa a consumir només la versió generada d’una figura, l’original es conserva i passa a 22_figs_originals/conservats/, sense que cap .qmd el consumeixi, perquè es fa servir fora del llibre (les diapositives). El pre-render no el converteix, l’inventari de figures (make inventari) el llista a part i 25_scripts/orfes.py no el compta com a orfe: el criteri és el directori. Les esmenes que necessitin les fa l’editor, des del TODO.md (D-68).

Dins del nom d’un fitxer font, un sufix diu l’eina que l’ha fet: avui només __graphviz (§Figures Graphviz). L’estat d’una figura no ha d’anar al nom (D-53).

Al caption de cada figura externa s’indica la font amb la notació (Font: [@clau]).

Figures externes (les de 23_figs_externes/, que no són obra dels professors de l’assignatura; verificades el 2026-10-06):

Fitxer On Autoria i font Llicència Observacions
A7_Intel_Core_i9-13900K_Labelled_Die_Shot_800x368.jpg A7, #fig-i9-13900k-die Fritzchens Fritz (foto) i JmsDoug (etiquetes), 2023; Wikimedia Commons, [@intel_i9_die_shot] CC0 1.0 (domini públic) Reduïda a 800 × 368 px (D-54)
by-nc-sa.eu.png 14_LICENSE.qmd Creative Commons Cap llicència CC: és una marca de Creative Commons, que la seva política permet fer servir per indicar la llicència d’una obra si s’hi enllaça el deed 14_LICENSE.qmd enllaça el deed de CC BY-NC-SA 4.0 (LICENSE.md)

Les figures extretes dels PDF originals de l’assignatura (les cinc de T6 marcades «extreta de PDF» a l’inventari de figures, make inventari) no són externes: són dels materials dels professors d’EC que recull 14_LICENSE.qmd §Reconeixements.

Figures Graphviz (diagrames d’arbre i grafs)

Els diagrames d’arbre i grafs senzills es generen amb Graphviz (dot -Tsvg) a partir d’un fitxer font .gv (format DOT).

Fitxers:

  • Font: 24_specs/<F><N>_nom_figura__graphviz.gv, amb la mateixa arrel que l’SVG.
  • Sortida: 22_figs_originals/<F><N>_nom_figura__graphviz.svg, generat a mà amb dot i el postprocés de més avall, i versionat; el pre-render en fa les variants __original_light i __original_dark com amb qualsevol altra figura de 22_figs_originals/.

Ordre de generació:

dot -Tsvg 24_specs/<F><N>_nom_figura__graphviz.gv -o /tmp/raw.svg

Després del dot, cal aplicar el postprocés següent (vegeu el fitxer font .gv per a un exemple complet):

  1. width="100%" i height eliminat; viewBox en enters.
  2. font-family amb l’stack complet: 'Liberation Sans', Arial, Helvetica, sans-serif.
  3. Fons blanc del canvas (<polygon fill="white">) → fill="none" stroke="none".
  4. fill="#343a40" explícit a cada element <text>.
  5. Color de les arestes: #adb5bd (stroke neutre del sistema de disseny).
  6. <title> i <desc> a l’arrel, just després de <svg>: el <desc> és el text alternatiu (§Figures i material gràfic). dot no els escriu, i cal tornar-los a posar si es regenera l’SVG.

Les fonts .gv que hi ha: git ls-files '24_specs/*.gv'.

L’SVG de 22_figs_originals/ i les variants d’auto_figs/ prenen el nom de la font (vegeu «Fitxers», més amunt).

Figures dinàmiques

Una figura que mostra una seqüència (els accessos a una memòria cau, per exemple) pot ser dinàmica a l’HTML: un navegador de passos («◀ Anterior», «Següent ▶», «Veure-ho tot») que en mostra un sol pas cada vegada. Al PDF sempre hi va la seqüència estàtica, generada pel mateix script i a partir de la mateixa definició, perquè els dos formats no divergeixin (D-55). El generador n’escriu els fotogrames (a gen_MC.py, fotogrames = true; a gen_T8.py, A8_mv_exemple_tlb_pas<k>.svg, que passen pel mateix norm_font.py i gen_dark.py que la resta de 22_figs_originals/), i el navegador és figures_dinamiques.html, que _quarto.yml inclou a totes les pàgines HTML. Els fotogrames només els cita el JavaScript, i per això són a resources:. Sense JavaScript, es veu la figura estàtica. Marcatge, al bloc HTML de la figura:

::::: {#fig-nom}
:::: {.content-visible when-format="html"}
::: {.fig-dinamica data-passos="5"}
::: {.light-content}
![](/auto_figs/Ax_nom__MC_light.svg)
:::
::: {.dark-content}
![](/auto_figs/Ax_nom__MC_dark.svg)
:::
:::
::::
::: {.content-visible when-format="pdf"}
![](/auto_figs/Ax_nom__MC_light.svg)
:::
Peu.
:::::

data-passos és el nombre de fotogrames (els accessos més l’estat inicial); el navegador en dedueix les rutes de la imatge estàtica, perquè el lloc es pot publicar en un subdirectori.

Retalls (crops) d’una figura font única

Quan una figura “detall” o “zoom” ha de mostrar literalment un subconjunt geomètric d’una figura més gran ja existent (mateixes coordenades, mateix contingut, sense redibuixar ni afegir informació), es defineix com a retall a 24_specs/retalls.toml en lloc de duplicar-lo com a SVG independent, evitant mantenir dues fonts sincronitzades manualment.

Condició d’aplicabilitat: el retall només és vàlid si és un subconjunt net del viewBox de la figura font — cap element ha de quedar tallat a mig camí (connectors, fletxes o etiquetes “penjant” sense l’element que assenyalaven). Si el detall necessita mostrar contingut que no hi és a la figura font (més etiquetes, més precisió, redisseny), continua calent un SVG independent a 22_figs_originals/.

Format de 24_specs/retalls.toml:

[crops.A5_exemple_detall]
source = "A5_exemple__original_light"   # sense extensió; ha d'existir a auto_figs/
title  = "Descripció del detall"         # opcional
x = 54    # min-x del retall, en coordenades del viewBox de la font
y = 60    # min-y
w = 300   # amplada
h = 250   # alçada

L’script 25_scripts/gen_crops.py només reescriu viewBox/width/height de l’element arrel; no toca cap altre contingut. S’executa com a pas de pre-render després de norm_font.py (necessita la font ja normalitzada a auto_figs/) i abans de gen_dark.py (perquè el retall també rebi automàticament la seva variant dark).

Integració al .qmd

::: {#fig-nom-figura}
::: {.content-visible when-format="html"}
::: {.light-content}
![](/auto_figs/Ax_nom_figura__original_light.svg)
:::
::: {.dark-content}
![](/auto_figs/Ax_nom_figura__original_dark.svg)
:::
:::
::: {.content-visible when-format="pdf"}
![](/auto_figs/Ax_nom_figura__original_light.svg)
:::
Caption acabat amb punt.
:::

Notes: - La ruta /auto_figs/ comença amb /, que Quarto interpreta com a relativa a l’arrel del projecte (on és _quarto.yml). És el mètode més robust: no depèn de la ubicació del .qmd dins l’arbre de directoris. - El bloc content-visible when-format="html" conté les dues variants (light/dark); el bloc when-format="pdf" conté només la versió light. Sense aquesta separació, el PDF renderitza totes dues variants i les figures surten duplicades. - Els blocs .light-content i .dark-content no porten style="text-align: center;": les figures amb {#fig-} ja centren automàticament. - El caption (última línia abans del ::: de tancament) és text lliure; Quarto l’associa automàticament a {#fig-} com a caption de la figura. - L’escalat es fa amb width="40%" (p. ex. ![](/auto_figs/Ax_nom_figura__original_light.svg){width="40%"})

Taules

  • Caption obligatori en el cos del text i a tota taula amb etiqueta #tbl-: sense peu, Quarto la numera igualment i en deixa el peu buit («Taula 6.1» sola) (D-102).
  • Hi ha l’opció de .hover.
  • tbl-colwidths="[...]" ha de sumar 100; si no, el PDF no renderitza bé.
  • Comprovació al PDF: python3 25_scripts/verifica_taules.py (--detall, --proposa, --aplica) mira totes les taules que arriben al PDF amb tres criteris: que no desbordi cap element que no es pot partir (codi, un tros de fórmula), que cap mot no es parteixi amb guionet perquè no cap a la columna («Mnemò-nic») ni cap cel·la de codi per dins, que els tbl-colwidths sumin 100 i en tinguin un per columna, i que cap taula amb #tbl- no quedi sense peu. Mesura amb les mètriques reals de les fonts del PDF (fontTools). --aplica escriu un ajust mínim: eixampla només les columnes que no arriben al mínim i treu l’espai de les que en tenen de sobres. Que una capçalera de diverses paraules passi a dues línies pels espais no compta: és la composició normal d’una taula.
  • Amplada: style="width: X%; margin: auto;" (recomanat dins callouts). Classe .striped recomanada per a taules llargues.
| A | B | C |
| :--- | :---: | :--- |
| esquerra | centre | dreta |
: Caption opcional {#tbl-TODO tbl-colwidths="[20,60,20]" style="width: 60%; margin: auto;" .striped}

La referència és @tbl-TODO.

Etiquetes {#sec-} a les capçaleres

Totes les capçaleres ##, ### i #### dels fitxers Ax.qmd han de tenir un identificador {#sec-nom}, perquè s’hi pugui remetre amb @sec-nom. La comprovació slugs de comprova.py atura el commit que en deixi una sense.

Criteris de generació de l’slug:

  1. Parteix del text de la capçalera en minúscules.
  2. Transliteració de caràcters catalans: à→a, á→a, è→e, é→e, í→i, ï→i, ò→o, ó→o, ú→u, ü→u, ç→c, l·l→ll, ·→ (eliminat).
  3. Elimina: ` (backticks), *, #, (, ), ,, ', /.
  4. Substitueix — i — per o -.
  5. Tota seqüència de caràcters no alfanumèrics → un sol guió -.
  6. Elimina guions inicials i finals.
  7. Si l’slug resultant ja existeix al fitxer, afegeix -1, -2… per unicitat. Millor solució: fer el títol de la capçalera prou descriptiu perquè l’slug sigui únic sense sufix numèric (p. ex. ### Algorisme {#sec-algorisme-multiplicacio} en lloc de {#sec-algorisme}).

Excepcions: - Les capçaleres dins callouts (## Títol del callout) no reben {#sec-} (són títols visuals, no seccions del document). - Les capçaleres # de nivell superior (títol del tema) ja solen tenir el tag de tema ({#sec-tema-x}); revisar que sigui consistent.

Equacions

Sintaxi: $$expressió$$ {#eq-NOM}. La referència és @eq-NOM.

Criteri de numeració: s’etiqueten ({#eq-NOM}) — i, per tant, es numeren — només:

  • les equacions referenciades amb @eq- des d’algun punt del llibre (mateix tema, problemes, solucions o laboratori), i
  • les fórmules canòniques del tema susceptibles de ser referenciades (p. ex. la definició del TAM, la Llei d’Amdahl).

La resta d’equacions destacades queden sense etiqueta ni número. Si més endavant cal referenciar una equació no etiquetada, s’etiqueta en aquell moment.

Per al criteri d’ús de LaTeX math vs. backticks per context, vegeu §Codi, matemàtiques i cursiva.

A l’HTML, MathJax 3, el que porta Quarto, i no MathML (html-math-method): amb MathML, a Chrome la tipografia és inferior i els números de les equacions surten en línia, no alineats a la dreta. Els estils de les equacions de styles.css (el desplaçament horitzontal a les pantalles estretes) són per als contenidors de MathJax, mjx-container (D-126).

Bibliografia

  • Ús: [@patterson2020riscv]
  • Definició: al fitxer 15_bibliografia.bib amb format BibTeX.

Referències creuades

Les referències creuades funcionen de manera diferent a HTML i a PDF. Per assegurar la compatibilitat amb les dues sortides:

  • Seccions, callouts, figures, taules, equacions: useu sempre la sintaxi @etiqueta, sola (funciona a HTML i PDF).
  • Figures del cos del text: cadascuna porta almenys una remissió @fig-… des del text, perquè al PDF la figura pot flotar a una altra pàgina; les dels callouts i les subfigures, no cal. L’inventari de figures («Figures del cos del text sense cap remissió @»; §Figures i material gràfic) llista les que no en tenen, i make comprova ho avisa. Les taules es referencien opcionalment (D-44).
  • Blocs de codi: s’hi remet amb @lst-…, no per la posició («el codi següent», «la funció C anterior», «aquest programa»). El bloc referenciat va dins d’un div ::: {#lst-…}, amb el peu a l’última línia, com les figures (§Integració al .qmd): una frase curta que diu què fa el codi, sense repetir-ne el llenguatge, que ja és al filename, i acabada en punt. Als enunciats, si el que fa el codi és el que es pregunta, el peu no ho diu: diu de quin apartat és («Fragment de l’apartat b).»). La remissió porta article, «el @lst-…» («el Codi 2.3»). Només es numeren els llistats #lst-, i en el mateix ordre als dos formats: el tercer llistat d’A2 és «Codi 2.3» a l’HTML i al PDF. Per això un #lst- no va dins d’un bloc .content-visible when-format, i no es fa servir l’atribut lst-cap: dins d’un callout, el bloc sortiria amb dos números al PDF. No porten #lst- els blocs d’una sèrie d’apartats amb lletra (a), b)…): la lletra ja els identifica. I una presentació amb dos punts («es declara així:», «el programa definitiu queda:») no és una remissió: presenta el codi que la segueix, com uns dos punts una fórmula (D-117).
    • Com es comprova: 25_scripts/verifica_llistats.py (§Comprovacions per nivells, comprovació «Llistats»), a cada commit que toca un .qmd. Aturen el commit la forma d’atribut (L1), un llistat sense bloc o sense peu (L2), un llistat dins d’un bloc when-format (L4), un llistat sense remissió (L5) i una remissió a un llistat que no existeix (L6); avisen, a les línies afegides, un peu sense punt (L3) i una remissió per posició al paràgraf de davant o al de darrere d’un bloc (L7), que és un avís perquè la tria és de qui escriu. make comprova-tot hi afegeix «Llistats a la sortida»: cada llistat té la mateixa posició dins del capítol a l’HTML i al PDF, i el PDF no numera cap bloc més. A mà, python3 25_scripts/verifica_llistats.py (el font) i --sortida (després de make render-complet). Les autoproves en vigilen el comportament (bateries llistats i llistats_sortida, §Autoproves de les comprovacions) (D-121).
  • Enllaços amb text propi a una secció, del mateix fitxer o d’un altre: [text](#sec-etiqueta) (funciona a HTML i PDF).
  • ⛔ No useu [@sec-etiqueta] ni [text](@sec-etiqueta): aquestes dues formes només funcionen a PDF.

Exemple — fitxer Sx.qmd amb una secció etiquetada:

Sx.qmd
# Problemes: Solucions seleccionades {#sec-problemes-solucions}

Referència des d’un altre fitxer:

un_altre_fitxer.qmd
- [Solucions de problemes](#sec-problemes-solucions)   ✓ HTML i PDF

A més, com a criteri d’estil de redacció:

  • Com més precises siguin, millor. Ordre de preferència creixent:
    • Tema → secció → subsecció → callout → figura → taula → equació.
    • sec-tema-exemple, @sec-exemple, @fig-exemple, @tbl-exemple, @nte-exemple.
  • Article determinat:
    • Amb: “La” @sec-exemple, @fig-exemple, @tbl-exemple mostra…, “el” @lst-exemple…
    • Sense: “@nte-exemple recull…”
  • Direccionalitat: les referències cap endavant (a contingut encara no presentat, sigui d’una secció posterior o d’un tema posterior) només s’admeten com a punter explícit («s’estudia a…», «es veurà a…», «vegeu…»), mai com a dependència conceptual: el text s’ha de poder seguir sense visitar la destinació. Punters cap endavant acceptats actualment:
    • T1/T2 → T3/T4: compilació, subrutines i pila, matrius, i optimitzacions de bucle (vegeu §T2 i T3).
    • T2 → T3: el punt d’entrada del programa sense etiqueta i el motiu bare-metal (@nte-punt-entrada-etiqueta).
    • T1/T2/T3 → T9: ecall (@sec-ei-ecall; T1, D-78).
    • T1 → T2/T3: les pseudoinstruccions i els salts indirectes a l’exemple de ret (@sec-pseudoinstruccions, @sec-salts-incondicionals-indirectes) (D-78).
    • T1 → T3: la memòria dinàmica (@sec-estructura-memoria) (D-78).
    • T1 → T4: l’extensió M, la multiplicació mòdul \(2^n\) i els casos especials de la divisió (@sec-extensio-m, @wrn-mul-modul-2n, @sec-casos-especials-divisio) (D-78).
    • T1 → T5: l’exponent en excés de la coma flotant (@sec-tema-coma-flotant) (D-78).
    • T2 → T3: els formats B i J (@nte-format-b, @nte-format-j), l’expansió de la amb auipc (@nte-instruccio-auipc), els salts, els desplaçaments i les instruccions lògiques dels exemples de bucles i de macros (@sec-salts, @sec-desplacaments-de-bits, @sec-instruccions-logiques-bit-a-bit) i jalr a la notació del mode base + desplaçament (@sec-salts-incondicionals-indirectes) (D-78).
    • T2 → T9: les pseudoinstruccions d’accés als CSR, a la presentació de les pseudoinstruccions (D-78).
    • T3 → T6: temps d’execució i CPI als problemes de T3 que en calculen (@eq-texe2; exr-t3-bucles-for i exr-t3-bucles-multiplicacio) (D-70).
    • T2 → T8: memòria virtual i MMU (@sec-mv-espais).
    • T5 → T9: fcsr fa obligatòria l’extensió Zicsr (@nte-zicsr), que es presenta a T9.
    • T4 → T7: fallades de memòria cau i localitat espacial en recorreguts de matrius (@sec-tema-mc; vegeu sol-t4-seq-bucles a S4.qmd).
    • T6 → T7: memòries cau (@sec-tema-mc, @fig-i9-13900k-die).
    • T8 → T9: modes de privilegi i excepcions (@sec-ei-csr-privilegis).

Imbricacions

Un callout no en pot contenir cap altre, tampoc per un {{< include >}}. Si el contingut d’un callout en necessita un altre, o bé el de dins surt a continuació del de fora (un aprofundiment d’un callout RISC-V), o bé es fon amb el de fora: el títol passa a un paràgraf en negreta i el contingut hi queda (un exemple dins d’un aprofundiment), i un #cau- dins d’una solució passa a un paràgraf que comença amb «Atenció:». Els divs que no són callouts (.content-visible, .light-content, .resposta…) sí que s’hi poden imbricar. verifica_callouts.py ho comprova (§Comprovacions per nivells) (D-110).

Regla dels : addicionals:

  • Estrictament, Quarto només imposa pujar un nivell (p. ex. ::: → ::::) quan s’imbriquen divs del mateix tipus.
  • A EC s’usa un nivell addicional per facilitar-ne la gestió visual.
EC Quarto
:::: – ::: {.callout-note} – ::: – :::: ::: – ::: {.callout-note} – ::: – :::
:::: {.callout-note} – ::: – ::: – :::: ::: {.callout-note} – ::: – ::: – :::

Presentació visual

  • {style="text-align: center;"} centra el contingut dins del contenidor, però el contenidor en si ocupa tota l’amplada disponible. Amb {#fig-}, {#tbl-}, etc. no cal perquè ja centren automàticament (les figures SVG, vegeu §Integració al .qmd).
    • Imatges dins callouts (només HTML; al PDF no té efecte).
  • {style="width: X%; margin: auto;"} centra el contenidor com a bloc. Funciona bé per a taules i elements de bloc amb amplada definida (width: X%), però no té efecte si el contenidor ja ocupa el 100 % de l’amplada.
    • Taules.
    • Elements de bloc.
  • Imatges sense peu dins dels callouts, al PDF: preamble.tex les centra. Ho fa a les que comencen un paràgraf dins d’un tcolorbox, que és com Quarto escriu els callouts; una imatge dins d’una línia de text no es toca, i fora dels callouts no canvia res (D-56).
  • Blocs de codi al PDF, al seu lloc: Quarto escriu els blocs amb filename com a flotants (codelisting, «Codi 9.1»), i preamble.tex els converteix en blocs normals, amb les ratlles del flotant i, a dalt, el nom del fitxer. Surten on el text els presenta i, si no caben, es parteixen entre pàgines, també dins dels callouts, on van sense fons gris (D-69). Només els llistats #lst- porten número i peu («Codi 2.3: …», amb el nom del fitxer a sota, com a l’HTML), que el filtre 25_scripts/llistats.lua hi prepara (§Referències creuades; D-117).
  • Fórmules en línia, a l’HTML: inline-block sense overflow. Només les que no caben a la columna reben desplaçament horitzontal propi, amb la classe .formula-llarga que hi posa formules_en_linia.html (_quarto.yml, include-after-body) (D-57).
  • CSS mode fosc (custom_dark.scss, secció /*-- scss:rules --*/): el codi inline dins de llegendes, capçaleres i títols de callout porta colors propis:
figcaption,
caption,
.footnotes,
h1, h2, h3, h4,
.callout-title-container {
  code {
    color: #e8e6e3 !important;
    background-color: #2b2d2f !important;
  }
}

Quarto: notes generals

  • Ni les etiquetes (labels) ni els ID poden incloure guions baixos (_).
  • Una bona font per aprendre és la documentació mateixa de Quarto.
  • ::: { (amb espai, Quarto) però ``{ (sense espai, Markdown).

Eines

Instal·lació

L’entorn de treball (l’accés al repositori, VS Code i les seves extensions, Quarto, TinyTeX, Python i les eines de les comprovacions, Java i RARS) i com s’instal·la són a README.md §Instal·lació. Les eines opcionals (hunspell, Java, fontTools i les fonts del PDF) no són imprescindibles: sense, la comprovació que les fa servir surt com a «omesa», i no com a neta.

Comprovacions per nivells

Abans d’un commit no cal passar-ho tot: el que cal depèn del que ha canviat. 25_scripts/comprova.py en dedueix el nivell a partir dels fitxers canviats, i passa les comprovacions que li toquen (D-103). Tres ordres:

make render         # mentre s'edita: l'HTML (1–3 min)
make comprova       # abans de cada commit: les comprovacions del nivell del canvi
make comprova-tot   # abans d'obrir una MR o de publicar: totes, amb el PDF i RARS (5–10 min)

make comprova-branca passa les de tota la branca respecte d’origin/main; les altres opcions són a python3 25_scripts/comprova.py --help i make help. El que a la gramàtica hi és soroll —les regles de LanguageTool desactivades i les formes correctes que marca alguna regla activa— és a 24_specs/gramatica.toml, que es manté a mà, amb el perquè de cada entrada. Una comprovació que atura el commit ha trobat un error; una que avisa no l’atura, però l’avís s’ha de llegir.

Nivells

Nivell Quan Què s’hi afegeix Temps
0 Operatiu Només canvien fitxers que el render no llegeix (TODO.md, 24_specs/registre_de_decisions.md, 24_specs/revisio_externa.md, 24_specs/lexic/, README.md, CLAUDE.md, .claude/, .github/, .githooks/, .vscode/, .gitignore, 05_diapositives/, 22_figs_originals/conservats/, 24_specs/diccionari.txt, 24_specs/diccionari_termes.txt, 24_specs/gramatica.toml), o eines de comprovació i generadors amb la sortida versionada (25_scripts/comprova.py, 25_scripts/escombrada.sh, 25_scripts/lint_prosa.py, 25_scripts/sigles.py, 25_scripts/autoproves.py, 25_scripts/ortografia.py, 25_scripts/gramatica.py, 25_scripts/eines_externes.py, 25_scripts/orfes.py, 25_scripts/inventari_figures.py, 25_scripts/comprova_vores.py, 25_scripts/verifica_*.py, 25_scripts/gen_T4_sumador.py, 25_scripts/gen_T7.py, 25_scripts/gen_T8.py) Les comprovacions que diuen «Sempre» a la taula següent Uns segons
1 Menor Només canvien .qmd, i cap línia canviada (afegida o treta) no porta marcatge: ni @, {, }, $, \, <, ![ o la barra vertical, ni comença amb :::, ---, #, una tanca de codi o [^, ni és buida. Hi entra el codi d’un bloc sense marcatge, que el render no interpreta Les de la prosa Uns segons
2 Contingut Qualsevol altre canvi del text del llibre (25_scripts/gen_glossari.py, 25_scripts/taula_md.py, *.qmd, 24_specs/termes.toml, LICENSE.md, 15_bibliografia.bib, _variables.yml), o un fitxer que no té classe make render 1–3 min
3 Figures 22_figs_originals/, 23_figs_externes/, 24_specs/svg.md, 24_specs/*.gv, 24_specs/registres.toml, 24_specs/BA.toml, 24_specs/mapa.toml, 24_specs/subrutines.toml, 24_specs/MC.toml, 24_specs/memoria.toml, 24_specs/retalls.toml, 25_scripts/figlib.py, 25_scripts/columna_memoria.py, 25_scripts/norm_font.py, 25_scripts/gen_*.py make render-complet, i el recordatori de la revisió estètica 4–8 min
4 Configuració 25_scripts/gen_taules_auto.py, _quarto.yml, preamble.tex, *.scss, styles.css, figures_dinamiques.html, formules_en_linia.html, ieee.csl, 25_scripts/*.lua, 24_specs/riscv.xml, 24_specs/taules_fusio.toml, Makefile Com al nivell 3 4–8 min
make comprova-tot Quan es demana Totes, sobre el corpus sencer, amb make render-complet, RARS i les referències sense resoldre de la sortida 5–10 min

Les comprovacions

Comprovació Què mira Quan Efecte
Registres Els registres versionats són al dia: el diccionari de termes, els SVG de model (a) i les taules generades d’aquesta secció (els arregla make registres); l’arbre del README.md (a mà) Sempre Atura
Autoproves Les comprovacions mateixes: cada eina provada, sobre llibres mínims amb errors coneguts, troba els que ha de trobar i cap més (autoproves.py; §Autoproves de les comprovacions, D-120) En tocar una eina provada o autoproves.py Atura
Lèxic Les presentacions «terme català (english)» del text coincideixen amb 24_specs/termes.toml: cap terme sense entrada, cap forma catalana diferent, cap terme del fitxer sense presentació (gen_glossari.py --comprova; D-115) Sempre Atura
Sigles Les sigles del text, contra [sigles] de 24_specs/termes.toml: l’expansió a la primera aparició del llibre, en el format únic; cap expansió en un altre format; cap sigla del text que no sigui a la taula ni a [no_sigles], ni cap en plural; cap sigla de la taula sense aparició (sigles.py --comprova; D-89, D-118) Sempre Atura
Decisions citades Cada D-n citat en un fitxer versionat existeix al registre de decisions Sempre Atura
Enunciats i solucions Cada #sol- té el seu #exr- amb el mateix slug (D-22) Sempre Atura
Etiquetes {#sec-} Cada capçalera ##–#### d’A1–A9, fora dels callouts i dels blocs de codi, porta la seva etiqueta {#sec-} (§Etiquetes {#sec-} a les capçaleres) Sempre Atura
Eines La sintaxi dels .py (compile) i dels .sh (bash -n) canviats; si canvia comprova.py, l’autoprova de la classificació En tocar un .py o un .sh Atura
Prosa Les formes que no s’han de fer servir i els termes anglesos fora de la cursiva, a la prosa i a les cel·les de les taules (§Anglicismes i terminologia obligatòria), que aturen; i els dobles espais i les cometes, que avisen (lint_prosa.py) En tocar un .qmd: les línies afegides; en tocar 24_specs/termes.toml, les formes i els termes a tot el corpus Atura (formes i termes) o avisa
Ortografia Mots que no són als diccionaris de hunspell (català i anglès) ni al del projecte, 24_specs/diccionari.txt i el de termes, generat de 24_specs/termes.toml (ortografia.py) En tocar un .qmd: les línies afegides Avisa
Gramàtica Concordances, preposicions, puntuació i la resta de regles de LanguageTool, sense les que al llibre fan soroll ni les formes correctes que marquen (gramatica.py, amb 24_specs/gramatica.toml; demana Java 17, i baixa LanguageTool la primera vegada) Només comprova-tot (i make gramatica) Avisa
Callouts imbricats Cap callout dins d’un altre, tampoc per un include (verifica_callouts.py; §Imbricacions, D-110) En tocar un .qmd Atura
Llistats Els llistats #lst- i les remissions als blocs de codi (verifica_llistats.py; §Referències creuades, D-117): la forma de div amb peu, fora dels blocs when-format, cada llistat amb remissió i cada remissió amb llistat (L1, L2 i L4–L6), que aturen; el peu sense punt (L3) i la remissió per posició, «el codi següent» (L7), que avisen En tocar un .qmd: L3 i L7, a les línies afegides Atura (L1, L2, L4–L6) o avisa
Marques TODO TODO a les línies afegides dels .qmd (§Commits) En tocar un .qmd Avisa
Format del codi Els criteris mecànics del format dels blocs d’assemblador (verifica_format_codi.py) Sempre Avisa
Etiquetes b/B Cap etiqueta ni constant b o B als blocs d’assemblador (la regla F6 de verifica_format_codi.py, que atura; D-111) Sempre Atura
Taules al PDF Desbordaments i amplades de les taules del PDF, mesurats sobre el font (verifica_taules.py, amb fontTools i les fonts del PDF) Sempre Avisa
Figures Els avisos de l’inventari de figures: peus, remissions, <title> i <desc>, colors, duplicats (inventari_figures.py --comprova) Sempre Avisa
Vores de les figures Traços que un <rect> posterior tapa en part: les vores que depenen de l’ordre de dibuix (comprova_vores.py; svg.md §7, D-99) En tocar un SVG natiu, figlib.py, gen_regs.py, gen_MC.py o els seus TOML Avisa
Fitxers orfes Fitxers versionats que cap altre no cita (orfes.py, D-98) Sempre Avisa
Classificació Cada fitxer té classe a la taula de comprova.py; si no, el canvi es tracta com a nivell 2 Sempre Avisa
Taules explicatives Les taules de la guia que no es poden generar (les peces del render, el directori .claude/, els sufixos d’origen) tenen una fila per fitxer; el diccionari del projecte no té mots que ja no s’usen Sempre Avisa
Calendari verifica_calendari.py, i el recordatori de passar l’agent verificador-calendari En tocar Lcalendari.qmd Avisa
Programes del laboratori RARS assembla i executa els blocs .s de L1–L6 (verifica_laboratoris.py; demana Java) En tocar L1.qmd–L6.qmd Atura
PDF Formes que afecten el PDF a les línies canviades (when-format, tbl-colwidths, #fig-, ![, $): cal make comprova-tot Nivell 2 Avisa
Revisió estètica El recordatori de mirar el canvi renderitzat, a l’HTML en clar i en fosc i al PDF Nivells 3 i 4 Avisa
Render make render (nivell 2) o make render-complet (nivells 3 i 4, i comprova-tot), que ha d’acabar net i sense cap WARNING Nivells 2, 3 i 4 Atura
Sortida Referències sense resoldre (?@) al _book/ i al PDF, i que hi hagi PDF Només comprova-tot Atura
Llistats a la sortida Cada llistat #lst-, a l’HTML i al PDF amb la mateixa posició dins del capítol, i cap bloc més numerat al PDF (verifica_llistats.py --sortida; D-117) Només comprova-tot Atura

El que no es dedueix dels fitxers ho tria qui treballa:

  • Revisió estètica: mirar el canvi renderitzat, a l’HTML en clar i en fosc i al PDF. La recorda make comprova als nivells 3 i 4.
  • Revisió de continguts: la revisió tècnica i lingüística de tot contingut nou (§IA).
  • Regenerar els registres: make registres, en el mateix commit que els deixa desactualitzats.

Autoproves de les comprovacions

Una comprovació que deixa de veure un error dona per bo el que no ho és, i ningú no se n’adona. Les autoproves ho vigilen: cada bateria fa passar una eina per un text correcte, en què no ha de trobar res, i per un text per cada error que ha d’aturar, en què ha de trobar aquell error. Cada cas munta un llibre mínim en un directori temporal, i per això el resultat no depèn del contingut del llibre; només demanen Python 3.11 o posterior i git, i qualsevol revisor les pot passar al seu ordinador (make autoproves). Quan es passen soles, ho diu la fila «Autoproves» de la taula de més amunt (D-120).

  • Si una autoprova falla, el missatge diu la bateria, el cas i què esperava trobar. O l’eina s’ha espatllat i s’arregla l’eina, o la regla ha canviat i s’actualitza el cas, en el mateix commit que la regla.
  • Un cas nou va a la seva bateria, a BATERIES de 25_scripts/autoproves.py, en el mateix commit que canvia la regla o l’eina. També hi va l’error que una comprovació hagi deixat passar, perquè no torni.
  • Una bateria nova surt a la taula següent amb make registres, i la comprovació «Registres» ho vigila.

Les bateries (els casos de cadascuna, amb el que esperen, a python3 25_scripts/autoproves.py --llista):

Bateria Eina Regla
sigles sigles.py --comprova §Sigles, símbols i notació (D-89, D-118)
lexic gen_glossari.py --comprova §Anglicismes i terminologia obligatòria (D-115, D-116)
prosa lint_prosa.py §Anglicismes, §Formes que no s’han de fer servir, §Commits (D-105, D-116)
format_codi verifica_format_codi.py §Estil de codi RISC-V (D-50, D-111)
callouts verifica_callouts.py §Imbricacions (D-110)
calendari verifica_calendari.py §Convencions globals del laboratori (D-74)
decisions comprova.py (decisions citades, enunciats i solucions, etiquetes {#sec-}) Registre de decisions; §Problemes i solucions (D-22); §Etiquetes {#sec-} a les capçaleres
classificacio comprova.py (autotest()) §Comprovacions per nivells (D-103)
llistats verifica_llistats.py §Referències creuades (D-117, D-121)
llistats_sortida verifica_llistats.py --sortida §Referències creuades (D-117, D-121)

Hooks de git

Les sessions de Claude Code passen comprova.py soles abans de cada commit (el hook abans-commit.sh, §IA). Per a qui no en fa servir, hi ha dos hooks de git opcionals, a .githooks/ (com s’activen, a README.md §Instal·lació):

  • pre-commit: les comprovacions del nivell del canvi, sense el render. Uns segons.
  • pre-push: les de la branca sencera, amb el render que demana el seu nivell (make comprova-branca).

Només aturen el que la guia diu que atura; els avisos es mostren i el commit o el push continua. En un clon on treballa Claude Code no cal activar-los: el render es faria dues vegades.

Les branques, al mirall de GitHub

El GitLab de la UPC no té runners, i el mirall de GitHub rep totes les branques. Per això cada push d’una branca que no sigui main passa make comprova-branca als de GitHub (.github/workflows/comprova.yml), sense que el revisor hagi d’instal·lar res. El resultat és a la pestanya Actions del mirall: una execució que falla vol dir que alguna comprovació atura, i els avisos hi surten com a anotacions i al resum. L’editor el mira abans de fusionar una MR (D-103).

Què es pot fer en local i què depèn de Claude Code

Es pot fer en local Depèn de Claude Code
Totes les comprovacions de comprova.py i les seves autoproves (make autoproves), make render, make render-complet i RARS, amb l’entorn de README.md §Instal·lació El hook abans-commit.sh, que crida comprova.py: els hooks de git en fan l’equivalent
Les skills, que són procediments per al model: les regles són en aquesta guia
Els subagents revisor-linguistic, auditor-xifres i verificador-calendari, que fa un model: una persona en fa l’equivalent a mà. La revisió lingüística comença igual en tots dos casos, amb les eines locals sobre el canvi (python3 25_scripts/ortografia.py i python3 25_scripts/gramatica.py, sense arguments: les línies afegides respecte d’HEAD)

Registres

Un registre és un fitxer, o una part d’un fitxer, que descriu el repositori i que es pot quedar enrere (D-104):

  1. Si es pot generar en renderitzar, es genera i no es versiona: l’índex «📑 Continguts» (continguts.lua), auto_figs/, auto_riscv/ i les taules del lèxic, auto_termes/: el glossari de termes, la taula de sigles i la de formes que no s’han de fer servir (gen_glossari.py, a partir de 24_specs/termes.toml).
  2. Si s’ha de versionar, el genera un script amb --comprova, i make registres els regenera tots: el diccionari de termes (gen_glossari.py --diccionari, que VS Code llegeix sense cap render), els SVG de model (a) (gen_T4_sumador.py, gen_T7.py i gen_T8.py) i les taules generades de §Comprovacions per nivells (les dues de comprova.py --taula i la de les autoproves, autoproves.py --taula). Un registre desactualitzat atura el commit.
  3. Si conté text que no es pot generar, es manté a mà, i comprova.py en vigila les files: l’arbre del README.md atura el commit; les taules de les peces del render (§Renderitzar el projecte), del directori .claude/ (§IA) i dels sufixos d’origen (§Convencions SVG), i els mots del diccionari del projecte que ja no fa servir cap fitxer, avisen.
  4. Una llista que es pot obtenir amb una ordre no s’escriu: s’escriu l’ordre. L’inventari de figures es genera quan es demana (make inventari), i qui fa servir un fitxer, amb git grep.
  5. Les durades s’escriuen en rangs («1–3 min»), no amb la xifra d’una mesura: una xifra exacta seria un registre més, que caldria tornar a mesurar.

Verificació de l’entorn

make comprova fa el render que demana el canvi: make render, que només genera l’HTML, o make render-complet (HTML i PDF), si el canvi és de figures o de configuració. Un canvi de text que pot afectar el PDF —qualsevol bloc when-format, una figura, una taula amb tbl-colwidths, o matemàtiques— en rep un avís, i abans de donar-lo per bo cal make comprova-tot, perquè un render HTML no exercita el PDF (D-58). També abans de compartir material amb alumnes o d’obrir la revisió externa.

El render ha d’acabar net: un error o un WARNING de Quarto aturen el commit (D-103). Per això, una referència a una secció, un callout o una figura que encara no existeix s’escriu com a text, no amb @, i porta un comentari HTML que diu on es calcula que anirà: <!-- descripció -->.

Les sessions de Claude Code tenen el procediment de verificació del render (com esperar-lo en segon pla, les referències trencades al _book/ i al PDF, l’HTML en clar i en fosc) a la skill render (§IA).

Verificació empírica a RARS

  • Quan una afirmació del llibre diu què fa RARS —que una directiva s’accepta, que una pseudoinstrucció existeix, que un programa acaba d’una certa manera—, la manera de resoldre-la és executar RARS 1.6. Es comprova per les adreces del bolcat o per l’estat final dels registres, no per l’absència d’error (D-62).
  • El .jar no es versiona: el de la release que cita README.md §RARS es baixa al directori .cache/ del clon, que git ignora, i 25_scripts/verifica_laboratoris.py ho fa sol, la primera vegada (D-62, D-103).
  • Les sessions de Claude Code en tenen el procediment a la skill rars (§IA).

Escombrades i verificació del corpus

Les regles de les escombrades —les cerques que mesuren el corpus sencer—, cadascuna amb el cas que la va originar, són a la skill escombrada (.claude/skills/escombrada/regles.md), i 25_scripts/escombrada.sh aplica les que no demanen judici (--help).

Protocol de contribució

La branca main està protegida: tot canvi s’integra a través d’una Merge Request (MR).

git checkout main && git pull                   # 1. Actualitzar main
git checkout -b contingut/t5-vectors           # 2. Branca nova (vegeu convenció de noms)
# ... canvis ...
git add A5.qmd
git commit -m "T5: afegeix secció sobre vectors"  # missatge: en català, present, descriptiu
git push origin contingut/t5-vectors           # 3. Pujar branca
# 4. Obrir Merge Request a GitLab apuntant a main

Errades del material publicat

  • Qui trobi una errada al material publicat obre una issue a GitLab amb l’etiqueta errada, que digui el fitxer, l’àncora (#sec-…, @exr-…, @fig-…) i la correcció que proposa.
  • Es corregeix com qualsevol altre canvi: una branca fix/<descriptor> i una Merge Request (§Protocol de contribució), o un push directe de l’editor (§Push directe a main).
  • El missatge del commit tanca la issue amb Closes #n (D-96).

Convenció de noms de branques

Tipus de canvi Format Exemple
Contingut nou contingut/<tema>-<descriptor> contingut/t5-vectors
Correcció fix/<descriptor> fix/t3-errada-alineacio
Configuració/tooling config/<descriptor> config/quarto-pdf-output
Revisió externa revisio/<grup>-t<N>-t<M> revisio/g2-t4-t6
Operació del repositori (l’editor, amb Claude Code) operacions, permanent operacions (D-123)

Durant la fase de revisió externa, cada grup de treball manté una sola branca amb el format revisio/<grup>-t<N>-t<M>, on <grup> identifica el grup i t<N>-t<M> el rang de temes que revisa. La branca s’actualitza amb main periòdicament (git merge main) per evitar divergències grans, i es tanca mitjançant una Merge Request un cop completada la revisió del bloc de temes. Un cop integrada, la branca s’esborra i s’arxiva amb una etiqueta anotada revisio-externa/<grup>-t<N>-t<M> que reculli el commit d’integració.

Commits

  • Un commit per canvi lògic — no agrupeu canvis no relacionats en un sol commit.
  • Missatge en català, en present i descriptiu: "T5: afegeix secció sobre vectors", no "canvis" ni "wip".
  • Abans de fer commit, assegureu-vos que no hi ha cap etiqueta -TODO ni cap TODO que pugueu solucionar vosaltres mateixos al codi (vegeu Callouts).

Format del missatge

Assumpte: una línia curta, en imperatiu, que digui què canvia i on. Sense prefixos fixos (fix:, docs:, [T5]…): la línia d’assumpte és el que es veu a git log --oneline i al git blame, i el text repetit la fa menys llegible.

Cos: explica el perquè. El diff ja diu el què. Quan és pertinent, hi ha d’aparèixer també per què el problema no es va detectar abans, o per què s’ha triat aquesta via i no una altra. Si el canvi repara feina pròpia, s’hi diu obertament: el valor del missatge és que la persona següent —o la sessió següent— no repeteixi l’error.

Autoria: la feina assistida per IA porta una línia Co-Authored-By: al final. L’autoria del contingut és de qui revisa i aprova cada canvi, no del model.

Exemple del format complet (commit 8b9f82d):

L3: restaura el paràgraf del símptoma observable de l'Error 1

El commit 7f0703c («L3 Fase C: redacció») va esborrar el paràgraf que
f136762 havia afegit hores abans, i va tornar a fusionar les dues frases
acabant amb «i el programa no acaba correctament».

Causa: aquell commit va prendre el text de l'extret per a tota la regió. El
paràgraf del símptoma observable es va redactar durant la revisió d'avui i
no és a l'extret, de manera que aplicar-hi l'extret el va suprimir.

La comprovació no ho va detectar perquè es va fer contra el fitxer extret
(«idèntic a l'extret») en lloc de contra la llista de canvis aprovats. Quan
s'hi afegeix contingut acordat durant la revisió, la igualtat amb l'extret
és una alarma, no una confirmació.

Fix-forward: no es reescriu l'historial.

Co-Authored-By: ...
  • Abans de fer commit, make comprova (§Comprovacions per nivells). Entre altres coses, revisa la prosa de les línies afegides dels .qmd: els dobles espais (excepte als blocs de codi, fórmules LaTeX i cel·les de taula), les cometes rectes "..." que haurien de ser cometes baixes «...», les formes que no s’han de fer servir i l’ortografia; i renderitza quan el canvi ho demana (§Verificació de l’entorn).

Push directe a main (només maintainers)

La branca main està protegida. Per als revisors i col·laboradors, el nivell d’accés és el següent:

Rol Push directe a main Merge Requests
Maintainer ✓ (canvis trivials) ✓
Developer ✗ ✓

Els Maintainers poden fer push directe a main exclusivament per a canvis trivials, definits com aquells que afecten un sol fitxer i menys de 5 línies. Per exemple:

  • Correccions tipogràfiques.
  • Canvis d’una sola línia en fitxers de configuració (_quarto.yml, .gitignore).
  • Actualitzacions de CLAUDE.md.

Qualsevol altre canvi requereix una Merge Request. Els Developers sempre han d’usar el flux de Merge Request, sense excepcions.

L’editor del llibre (Roger Baig) no està subjecte a aquesta restricció fins al segon quadrimestre del curs 2026-27: fins llavors pot fer push directe a main de qualsevol canvi, també des de les sessions de Claude Code que dirigeix (D-59).

Renderitzar el projecte

El projecte té dues sortides independents: HTML i PDF. Són pipelines completament separades — HTML usa Bootstrap, PDF usa LaTeX (scrbook). Cap de les dues es construeix sobre l’altra. Les ordres del render, i què en queda a _book/, són a README.md §Renderitzar el projecte.

Renderitzeu amb make. Dos renders del mateix worktree no es poden fer alhora, perquè el pre-render esborra auto_figs/: amb make, el segon espera que acabi el primer, fins a 15 min. quarto render cridat directament i la previsualització de VS Code no hi passen (D-103).

Peces del render que no són al Makefile (totes dues sortides passen per _quarto.yml, de manera que valen per a make render, make render-complet, quarto render i el CI):

Peça Format Què fa
25_scripts/figures.lua HTML (i alt als dos) Text alternatiu des del <desc> de l’SVG i amplada comuna de les figures (§Figures i material gràfic)
25_scripts/titols_pdf.lua PDF Marcadors amb els títols curts del menú de l’HTML («A1 Introducció», «L1 RARS»), presos dels text: de chapters:; la pàgina, l’índex i la capçalera conserven el títol llarg
25_scripts/versio.lua HTML i PDF Hash curt del commit renderitzat, entre parèntesis, després de la data de «Publicat» de la portada i a la portada del PDF, amb -dirty si l’arbre té canvis no confirmats
25_scripts/espai_unitats.lua HTML i PDF Espai que no es parteix entre un nombre i la seva unitat o el % (§Criteris generals, «Nombres»)
25_scripts/plegables.lua HTML i PDF Als temes pilot (de moment, T1): el div .resposta dels exemples, plegat a l’HTML (<details>) i sense canvis al PDF; i, al final de cada enunciat #exr- amb solució, la remissió @sol- a la solució, que no s’escriu a mà (§Callouts, §Problemes i solucions). S’executa at: pre-ast, abans que Quarto converteixi els #exr- en nodes propis
25_scripts/continguts.lua HTML (i PDF) La pàgina «📑 Continguts» (10_continguts.qmd): l’índex dels apunts, A1–A9 fins a ###, amb el número de l’HTML i l’enllaç a cada secció. Els llegeix dels .qmd, i per això no s’escriu a mà; hi surten les capçaleres que surten a la «Taula de continguts» de cada pàgina (les de fora dels callouts i dels divs). Al PDF, treu la pàgina, que ja té el seu índex (D-101)
25_scripts/sagnat_operacio.lua PDF Sagnat francès (\hangindent) a les cel·les de la columna «Operació» de les taules, perquè la segona línia d’una operació partida no comenci arran de la primera (D-109)
25_scripts/llistats.lua PDF El nom del fitxer d’un llistat #lst-, del bloc al peu, que preamble.tex escriu a sota de «Codi 2.3: …»; sense, dins d’un callout el bloc sortiria amb dos números (§Referències creuades; D-117). S’executa at: pre-ast
figures_dinamiques.html HTML Navegador de passos de les figures dinàmiques
formules_en_linia.html HTML Desplaçament horitzontal només per a les fórmules en línia que no caben (§Presentació visual)
preamble.tex PDF Capçaleres, colors i comptadors dels callouts, algorismes en rodona, «Problema»/«Exercici», els blocs de codi al seu lloc i numerats només si són llistats #lst- (§Presentació visual), els caràcters que la font del cos no té (\newunicodechar: ✓, ↔︎, ≡, ≠, ⌊⌋ amb el símbol matemàtic; ⚠ i les icones de les capçaleres de la presentació amb la de fontawesome5, i el caràcter original als marcadors) i les imatges centrades dins dels callouts. Un caràcter nou que surti en blanc al PDF hi ha d’afegir la seva línia: el registre de LaTeX el dona com a «Missing character»

Les pàgines inicials, en un ordre diferent a l’HTML i al PDF (no coincidència coneguda i acceptada): a l’HTML, «👋 Presentació» i, després, «📑 Continguts»; al PDF, l’índex («Continguts», toc-title) i, després, la «Presentació». A l’HTML, la Presentació fa de portada; el PDF, com qualsevol llibre, té una portada pròpia, seguida de l’índex (D-109).

Font monoespaiada del PDF: DejaVu Sans Mono, amb Scale=MatchLowercase (_quarto.yml, monofont): Latin Modern Mono, la de per defecte, no té els glifs de caixa (─) ni el ✓ que fan servir alguns blocs de codi. El CI la instal·la amb el paquet fonts-dejavu-core (.github/workflows/publish.yml), al pas que fa el PDF. La font monoespaiada dels SVG continua sent Liberation Mono (24_specs/svg.md §12) (D-60).

IA

Fitxers obligatoris a passar a les IA: vegeu CLAUDE.md §Fitxers de referència obligatòria.

Abans d’incorporar qualsevol contingut generat per una IA al repositori, cal fer una revisió tècnica i lingüística completa. El model i l’effort recomanats per a cada tipus de tasca consten a CLAUDE.md §Model i effort.

Claude Code: el directori .claude/

El directori .claude/ és versionat: qui obri el repositori amb Claude Code hi troba les mateixes regles. Els hooks i els subagents apliquen regles d’aquest fitxer o de CLAUDE.md. Les skills contenen els procediments que només fan servir aquestes sessions —les escombrades, la verificació del render, RARS i les figures—, amb les regles pròpies del procediment i el cas que justifica cadascuna; les regles del llibre continuen sent aquí.

Peça Què fa Regla
Hook guarda-git.sh Bloqueja el push al remot mirror i les ordres que reescriuen l’historial (--force, rebase, --amend, reset --hard, filter-branch) CLAUDE.md §Flux de treball
Hook abans-commit.sh Abans de cada git commit, python3 25_scripts/comprova.py: les comprovacions del nivell del canvi. Si alguna atura el commit, el commit no es fa; els avisos no l’aturen ni pregunten, sinó que passen a Claude i es mostren a l’usuari. Als nivells 2–4 renderitza, i el make render del nivell 2, com qualsevol make render, esborra el PDF de _book/ (README.md §Renderitzar el projecte) (D-74, D-98, D-103) §Comprovacions per nivells
Hook guarda-generats.sh Bloqueja l’edició a mà dels fitxers generats: auto_figs/, auto_riscv/, auto_termes/, _book/ i les variants _dark.svg, que el pròxim render desfaria §Paleta de colors, §Renderitzar el projecte
Skill escombrada Les regles de les escombrades (regles.md), amb el cas de cadascuna, i 25_scripts/escombrada.sh §Escombrades i verificació del corpus
Skill render Verificació del render: esperar-lo en segon pla, referències trencades, HTML en clar i en fosc, registre de LaTeX §Verificació de l’entorn, §Renderitzar el projecte
Skill rars Verificació empírica a RARS 1.6 sense interfície, i verifica_laboratoris.py §Verificació empírica a RARS
Skill figures Llista de comprovacions per a una figura nova, canviada o retirada §Figures i material gràfic
Subagent auditor-xifres Reprodueix les xifres que publica un commit o un rang (Opus, effort alt, només lectura) §Escombrades i verificació del corpus
Subagent revisor-figures Compara les figures que canvia un diff abans i després, en clar i en fosc, i informa de les diferències que el canvi declarat no explica (Sonnet, només informa) §Figures i material gràfic
Subagent revisor-linguistic Revisió en català normatiu d’un diff: parteix de les troballes d’ortografia.py i gramatica.py i llegeix el que les eines no veuen, com la terminologia, el registre i la claredat (Sonnet, només informa) §Llenguatge
Subagent verificador-calendari Comprova el calendari del laboratori abans d’un commit que el toqui: dates i dies de la setmana (amb verifica_calendari.py), sessions, quadrimestre, festius i examen (Sonnet, només informa) (D-74) §Convencions globals del laboratori

Els scripts de 25_scripts/ que hi intervenen també es fan servir a mà: python3 25_scripts/comprova.py --help (i make comprova) i 25_scripts/escombrada.sh --help.

Els permisos que no han de demanar confirmació són a .claude/settings.json, també versionat. Les aprovacions que Claude Code desa pel seu compte van a .claude/settings.local.json, que git ignora: les que hagin de valer per a tothom s’han de passar a mà a settings.json.