Shiva's WebpageZola2026-08-24T00:00:00+00:00https://skran.xyz/atom.xmlPorting a 23-year-old C library to Rust2026-08-24T00:00:00+00:002026-08-24T00:00:00+00:00
Shiva Kiran Koninty
https://skran.xyz/articles/gsoc-2026/<p>As an <a rel="external" href="https://summerofcode.withgoogle.com/programs/2026/projects/Q2pKYmUp">accepted contributor</a> for
<a rel="external" href="https://summerofcode.withgoogle.com/">Google Summer of Code</a> 2026, I worked on porting parts
of <a rel="external" href="https://gnu.org/software/libcdio">GNU libcdio</a> to Rust.</p>
<p>This has achieved:</p>
<ul>
<li>A new implementation of libcdio,
<a rel="external" href="https://crates.io/crates/libcdio-rs">libcdio-rs</a>, that is thread safe,
memory safe and wrapped behind hard-to-misuse interfaces.</li>
<li>Bug fixes and thread safety improvements to the existing C library.</li>
</ul>
<p>Two new crates formed as a result:</p>
<ul>
<li><a rel="external" href="https://crates.io/crates/libcdio-cli">libcdio-cli</a></li>
<li><a rel="external" href="https://crates.io/crates/libcdio-rs">libcdio-rs</a></li>
</ul>
<p>In this article, I share the approach and learnings I’ve had from this
experience.</p>
<h2 id="what-is-gnu-libcdio"><a class="zola-anchor" href="#what-is-gnu-libcdio" aria-label="Anchor link for: what-is-gnu-libcdio"><i class="icon"></i></a>
What is GNU libcdio?</h2>
<p>It’s a C library that provides several routines needed for programs
that wish to work with optical media such as CD/DVD and
BluRay, notably by providing an OS agnostic interface.</p>
<p>A few prominent programs that use GNU libcdio include ffmpeg,
GNOME gvfs, mpv, KDE kiso, Kodi, Rufus and VLC.</p>
<p>The library’s first commit traces back to 2003. This is before Git,
as the project originally used <a rel="external" href="https://en.wikipedia.org/wiki/Concurrent_Versions_System">CVS</a>.</p>
<h2 id="why-port-it-to-rust"><a class="zola-anchor" href="#why-port-it-to-rust" aria-label="Anchor link for: why-port-it-to-rust"><i class="icon"></i></a>
Why port it to Rust?</h2>
<p>Rocky Bernstein, the author and maintainer of the project was annoyed
with the vulnerabilities reported due to memory management mistakes
and buffer overflows and chose Rust for renowned memory safety.</p>
<p>He believed that this would also fix up deeply rooted problems and
encourage the participation of the next generation of developers.</p>
<h2 id="scope-of-the-project"><a class="zola-anchor" href="#scope-of-the-project" aria-label="Anchor link for: scope-of-the-project"><i class="icon"></i></a>
Scope of the project</h2>
<ol>
<li>libcdio’s SCSI MMC routines.</li>
<li>libcdio’s utility programs (four).</li>
</ol>
<h2 id="porting-the-scsi-mmc-routines"><a class="zola-anchor" href="#porting-the-scsi-mmc-routines" aria-label="Anchor link for: porting-the-scsi-mmc-routines"><i class="icon"></i></a>
Porting the SCSI MMC routines</h2>
<p><a rel="external" href="https://en.wikipedia.org/wiki/SCSI_Multimedia_Commands">SCSI MMC</a> is a standard defining a command set for accessing
and controlling optical disc readers and writers.</p>
<h3 id="initial-approach-rust-as-a-drop-in-c-replacement"><a class="zola-anchor" href="#initial-approach-rust-as-a-drop-in-c-replacement" aria-label="Anchor link for: initial-approach-rust-as-a-drop-in-c-replacement"><i class="icon"></i></a>
Initial approach: Rust as a drop-in C replacement</h3>
<p>This involves making the Rust interfaces to be C compabible, so that
existing C code that used the library would continue to function,
while gaining the improvements brought upon by Rust.</p>
<p><a rel="external" href="https://github.com/carols10cents/rust-out-your-c-talk">“Rust Out Your C”</a> by Carol Nichols is a good
resource on this.
<img src="https://skran.xyz/articles/gsoc-2026/c-rust-iter-loop.jpg#end" alt="Rust to C iteration loop. Image taken from “Rust out your C” by Carol Nichols" /></p>
<p>This comes with the cost of requiring the Rust toolchain to
build and use GNU libcdio.</p>
<p>With that, the first task was to figure out adding Rust to
its build system.</p>
<h4 id="rust-and-the-gnu-build-system"><a class="zola-anchor" href="#rust-and-the-gnu-build-system" aria-label="Anchor link for: rust-and-the-gnu-build-system"><i class="icon"></i></a>
Rust and the GNU build system</h4>
<p>Being part of GNU, libcdio had naturally used the
<a rel="external" href="https://en.wikipedia.org/wiki/GNU_Autotools">GNU build system</a>, which includes Autoconf,
Automake and Libtool.</p>
<p>These tools come from a very lively era that had a variety of Unices
and other Unix like operating systems. The only thing they all had
supported in common was the POSIX <code>make</code> command and shell scripts.</p>
<p>The GNU build system is kindof a hack that accepted a set of input
files which declared what the program needs such as certain C
libraries, headers and system features such as large file support
and produced a <code>configure</code> shell script that can runs on any
system. Its task is to probe the system for the program’s requirements
and produce a <code>Makefile</code>.</p>
<p>The GNU manuals were helpful in understanding them.</p>
<p>I chose an approach where Cargo would handle just the Rust bits
and produce a static, C-compatible library, which the existing build
system can use to link against the C bits.</p>
<p>The article
<a rel="external" href="https://viruta.org/librsvgs-build-infrastructure-autotools-and-rust.html">“Librsvg’s build infrastructure: Rust and Autotools”</a>
by Federico Mena Quintero was a strong inspiration.</p>
<p><a rel="external" href="https://github.com/libcdio/libcdio/pull/49">“build: Add Rust”</a> is the pull request incorporating this.</p>
<p>However, the users did not agree with the proposal, primarily due
to concerns about Rust’s relatively limited compiler ecosystem,
compared to C.</p>
<p>After a bit of discussion, I went with a change of approach.</p>
<h3 id="final-approach-a-separate-rust-library"><a class="zola-anchor" href="#final-approach-a-separate-rust-library" aria-label="Anchor link for: final-approach-a-separate-rust-library"><i class="icon"></i></a>
Final approach: A separate Rust library</h3>
<p>This has the advantage of unlocking the full capabilities and
benefits of Rust, as there won’t be any constraints associated with
having a C-compatible interface.</p>
<h4 id="libcdio-rs-the-rust-implementation-of-gnu-libcdio"><a class="zola-anchor" href="#libcdio-rs-the-rust-implementation-of-gnu-libcdio" aria-label="Anchor link for: libcdio-rs-the-rust-implementation-of-gnu-libcdio"><i class="icon"></i></a>
libcdio-rs: The Rust implementation of GNU libcdio</h4>
<p>Implementing the SCSI MMC commands in Rust involved communicating with
a disc drive in binary:</p>
<ul>
<li>Constructing requests per the SCSI and MMC specifications</li>
<li>Passing them to the OS specific device interface (such as <code>ioctl()</code>)</li>
<li>Parsing binary responses</li>
</ul>
<p>The OS specific interfaces were abstracted by libcdio’s
<code>mmc_run_cmd()</code> function, which I’d re-used via FFI.</p>
<p>Parsing binary responses were done using the <code>winnow</code> crate’s
routines, which are designed to make these tasks less prone to human
error.</p>
<p>Every function had a unit test, which were performed on a USB based
CD/DVD drive.</p>
<p>Rust’s idioms, such as the newtype pattern, were applied where
possible.</p>
<details>
<summary>Example: An instance of using the newtype pattern</summary>
<p>There are routines that take a track number as input.
However, track numbers, per the spec are valid only from 1 to 100.</p>
<p>Here’s a newtype <code>TrackNumber</code>:</p>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="rust"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Track number.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">///</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Values must be between 1 and 99.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Use [`TrackNumber::try_from`] to construct a new value.</span></span>
<span class="giallo-l"><span>#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]</span></span>
<span class="giallo-l"><span style="color: #C792EA;">pub struct</span><span> TrackNumber(u8);</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;">impl</span><span> TryFrom<u8></span><span style="color: #C792EA;font-style: italic;"> for</span><span> TrackNumber {</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> type</span><span> Error</span><span style="color: #C792EA;"> =</span><span> InvalidTrackNumber;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// Construct `Self` from given track number.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> ///</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// # Errors</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// If the track number not within the range of 1 to 99, inclusive.</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> fn</span><span style="color: #82AAFF;font-style: italic;"> try_from</span><span>(</span><span style="color: #C5E478;">track_number</span><span style="color: #7FDBCA;">:</span><span> u8)</span><span style="color: #7FDBCA;"> -></span><span> Result<</span><span style="color: #7FDBCA;">Self</span><span>,</span><span style="color: #7FDBCA;"> Self::</span><span>Error> {</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span> (</span><span style="color: #F78C6C;">1</span><span style="color: #7FDBCA;">..=</span><span style="color: #F78C6C;">99</span><span>)</span><span style="color: #7FDBCA;">.</span><span style="color: #82AAFF;font-style: italic;">contains</span><span>(</span><span style="color: #7FDBCA;">&</span><span style="color: #C5E478;">track_number</span><span>) {</span></span>
<span class="giallo-l"><span> Ok(</span><span style="color: #7FDBCA;">Self</span><span>(</span><span style="color: #C5E478;">track_number</span><span>))</span></span>
<span class="giallo-l"><span> }</span><span style="color: #C792EA;font-style: italic;"> else</span><span> {</span></span>
<span class="giallo-l"><span> Err(</span><span style="color: #82AAFF;font-style: italic;">InvalidTrackNumber</span><span>(</span><span style="color: #C5E478;">track_number</span><span>))</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span>#[derive(Debug, Error)]</span></span>
<span class="giallo-l"><span>#[error(</span><span style="color: #D9F5DD;">"</span><span style="color: #ECC48D;">invalid track number '{0}'; value must be between 1 and 99</span><span style="color: #D9F5DD;">"</span><span>)]</span></span>
<span class="giallo-l"><span style="color: #C792EA;">pub struct</span><span> InvalidTrackNumber(u8);</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;">impl</span><span> Default</span><span style="color: #C792EA;font-style: italic;"> for</span><span> TrackNumber {</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> fn</span><span style="color: #82AAFF;font-style: italic;"> default</span><span>()</span><span style="color: #7FDBCA;"> -> Self</span><span> {</span></span>
<span class="giallo-l"><span style="color: #7FDBCA;"> Self</span><span>(</span><span style="color: #F78C6C;">1</span><span>)</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span>}</span></span></code></pre></details>
<p>Routines that accept a track number now have a compile-time guarantee
of track numbers being within range:</p>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="rust"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Get the International Standard Recording Code (ISRC) of given track number.</span></span>
<span class="giallo-l"><span style="color: #C792EA;">pub fn</span><span style="color: #82AAFF;font-style: italic;"> isrc</span><span>(</span><span style="color: #7FDBCA;">&self</span><span>,</span><span style="color: #C5E478;"> track_number</span><span style="color: #7FDBCA;">:</span><span> TrackNumber)</span><span style="color: #7FDBCA;"> -></span><span> Result<Option<String>, MmcSubchannelError> {</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// use track_number confidently, without any checks!</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p>It also removes the need to verify track number inputs at every
routine (and having to define an error).</p>
<details>
<summary>Example: Implementing SCSI MMC `START STOP UNIT`</summary>
<p>The <code>START STOP UNIT</code> command is used to:</p>
<ul>
<li>Eject or Close/Open the tray of a drive</li>
<li>Set the drive to a power state such as idle, poweroff or sleep</li>
</ul>
<p>Here’s the existing C implementation of this command from libcdio:</p>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="c"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/**</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> Load or Unload media using a SCSI-MMC START/STOP UNIT command.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;"> @param</span><span style="color: #D7DBE0;font-style: italic;"> p_cdio</span><span style="color: #637777;font-style: italic;"> the CD object to be acted upon.</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> @param</span><span style="color: #D7DBE0;font-style: italic;"> b_eject</span><span style="color: #637777;font-style: italic;"> eject if true and close tray if false</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> @param</span><span style="color: #D7DBE0;font-style: italic;"> b_immediate</span><span style="color: #637777;font-style: italic;"> wait or don't wait for operation to complete</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> @param</span><span style="color: #D7DBE0;font-style: italic;"> power_condition</span><span style="color: #637777;font-style: italic;"> Set CD-ROM to idle/standby/sleep. If nonzero,</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> eject/load is ignored, so set to 0 if you want to eject or load.</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;"> @see</span><span style="color: #637777;font-style: italic;"> mmc_eject_media or mmc_close_tray</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">*/</span></span>
<span class="giallo-l"><span style="color: #C5E478;">driver_return_code_t</span></span>
<span class="giallo-l"><span style="color: #82AAFF;font-style: italic;">mmc_start_stop_unit</span><span>(</span><span style="color: #C792EA;font-style: italic;">const</span><span style="color: #C5E478;"> CdIo_t</span><span style="color: #7FDBCA;"> *</span><span style="color: #D7DBE0;">p_cdio</span><span>,</span><span style="color: #C792EA;"> bool</span><span style="color: #D7DBE0;"> b_eject</span><span>,</span><span style="color: #C792EA;"> bool</span><span style="color: #D7DBE0;"> b_immediate</span><span>,</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> uint8_t</span><span style="color: #D7DBE0;"> power_condition</span><span>,</span><span style="color: #C792EA;"> unsigned int</span><span style="color: #D7DBE0;"> i_timeout_ms</span><span>)</span></span>
<span class="giallo-l"><span>{</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> uint8_t</span><span style="color: #C5E478;"> buf</span><span>[</span><span style="color: #F78C6C;">1</span><span>];</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> void</span><span style="color: #7FDBCA;"> *</span><span> p_buf </span><span style="color: #C792EA;">=</span><span style="color: #7FDBCA;"> &</span><span>buf;</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> const</span><span style="color: #C792EA;"> unsigned int</span><span> i_size </span><span style="color: #C792EA;">=</span><span style="color: #F78C6C;"> 0</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #82AAFF;font-style: italic;"> MMC_CMD_SETUP</span><span style="color: #82AAFF;">(CDIO_MMC_GPCMD_START_STOP_UNIT)</span><span>;</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /* this command doesn't have an allocation length in its CDB */</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span> (b_immediate)</span><span style="color: #C5E478;"> cdb</span><span>.</span><span style="color: #C5E478;">field</span><span>[</span><span style="color: #F78C6C;">1</span><span>]</span><span style="color: #C792EA;"> |=</span><span style="color: #F78C6C;"> 1</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span> (power_condition)</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>.</span><span style="color: #C5E478;">field</span><span>[</span><span style="color: #F78C6C;">4</span><span>]</span><span style="color: #C792EA;"> =</span><span> power_condition </span><span style="color: #C792EA;"><<</span><span style="color: #F78C6C;"> 4</span><span>;</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> else</span><span> {</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span> (b_eject)</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>.</span><span style="color: #C5E478;">field</span><span>[</span><span style="color: #F78C6C;">4</span><span>]</span><span style="color: #C792EA;"> =</span><span style="color: #F78C6C;"> 2</span><span>;</span><span style="color: #637777;font-style: italic;"> /* eject */</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> else</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>.</span><span style="color: #C5E478;">field</span><span>[</span><span style="color: #F78C6C;">4</span><span>]</span><span style="color: #C792EA;"> =</span><span style="color: #F78C6C;"> 3</span><span>;</span><span style="color: #637777;font-style: italic;"> /* close tray for tray-type */</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> return</span><span style="color: #82AAFF;font-style: italic;"> MMC_RUN_CMD</span><span style="color: #82AAFF;">(SCSI_MMC_DATA_WRITE, mmc_timeout_ms)</span><span>;</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p>One problem here is the reliance on human judgement to set
<code>power_condition</code> to zero for <code>b_eject</code> to not be ignored.</p>
<p>Rust algebraic types helped eliminate the invalid input of having both eject
and power condition being set.</p>
<p>Moreover, the exhaustive pattern matching also ensures that all
possible values are handled (such as <code>StartDisc</code>, <code>Jump</code>,
which the C implementation missed).</p>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="rust"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Operations of the `START STOP UNIT` command</span></span>
<span class="giallo-l"><span style="color: #C792EA;">enum</span><span> StartStopOperation {</span></span>
<span class="giallo-l"><span> StopDisc,</span></span>
<span class="giallo-l"><span> StartDisc,</span></span>
<span class="giallo-l"><span> EjectDisc,</span></span>
<span class="giallo-l"><span> LoadStartDisc,</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// Change the online format-layer to the specified value for hybrid discs.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// Only the last two bits will be set.</span></span>
<span class="giallo-l"><span> Jump {</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> layer_number</span><span style="color: #7FDBCA;">:</span><span> u8,</span></span>
<span class="giallo-l"><span> },</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// Place the device in the specified power condition</span></span>
<span class="giallo-l"><span style="color: #82AAFF;font-style: italic;"> Power</span><span>(PowerCondition),</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">/// A power state as defined under MMC `START STOP UNIT`</span></span>
<span class="giallo-l"><span style="color: #C792EA;">enum</span><span> PowerCondition {</span></span>
<span class="giallo-l"><span> Idle</span><span style="color: #C792EA;"> =</span><span style="color: #F78C6C;"> 0x2</span><span>,</span></span>
<span class="giallo-l"><span> Standby</span><span style="color: #C792EA;"> =</span><span style="color: #F78C6C;"> 0x3</span><span>,</span></span>
<span class="giallo-l"><span> Sleep</span><span style="color: #C792EA;"> =</span><span style="color: #F78C6C;"> 0x5</span><span>,</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #C792EA;">impl</span><span> Mmc {</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> fn</span><span style="color: #82AAFF;font-style: italic;"> start_stop_unit</span><span>(</span><span style="color: #7FDBCA;">&self</span><span>,</span><span style="color: #C5E478;"> operation</span><span style="color: #7FDBCA;">:</span><span> StartStopOperation)</span><span style="color: #7FDBCA;"> -></span><span> Result<(), MmcStartStopError> {</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> let</span><span style="color: #C792EA;font-style: italic;"> mut</span><span style="color: #C5E478;"> cdb</span><span style="color: #C792EA;"> =</span><span> Cdb</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">default</span><span>();</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>[</span><span style="color: #F78C6C;">0</span><span>]</span><span style="color: #C792EA;"> =</span><span> MmcCommand</span><span style="color: #7FDBCA;">::</span><span>StartStopUnit</span><span style="color: #C792EA;"> as</span><span> u8;</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>[</span><span style="color: #F78C6C;">1</span><span>]</span><span style="color: #C792EA;"> =</span><span style="color: #F78C6C;"> 0</span><span>;</span><span style="color: #637777;font-style: italic;"> // not using the immediate bit for now</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span style="color: #C792EA;"> let</span><span> StartStopOperation</span><span style="color: #7FDBCA;">::</span><span>Jump {</span><span style="color: #C5E478;"> layer_number</span><span> }</span><span style="color: #C792EA;"> =</span><span style="color: #C5E478;"> operation</span><span> {</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>[</span><span style="color: #F78C6C;">3</span><span>]</span><span style="color: #C792EA;"> =</span><span style="color: #C5E478;"> layer_number</span><span style="color: #7FDBCA;"> &</span><span style="color: #82AAFF;"> LAYER_NUM_BITMASK</span><span>;</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>[</span><span style="color: #F78C6C;">4</span><span>]</span><span style="color: #C792EA;"> |=</span><span style="color: #F78C6C;"> 1</span><span style="color: #C792EA;"> <<</span><span style="color: #82AAFF;"> FORMAT_LAYER_BITPOS</span><span>;</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // Sets the LoEj and Start fields</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // as described in 6.42.3.1 of MMC-6 2g</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>[</span><span style="color: #F78C6C;">4</span><span>]</span><span style="color: #C792EA;"> |=</span><span style="color: #C792EA;font-style: italic;"> match</span><span style="color: #C5E478;"> operation</span><span> {</span></span>
<span class="giallo-l"><span> StartStopOperation</span><span style="color: #7FDBCA;">::</span><span>StartDisc</span><span style="color: #7FDBCA;"> =></span><span style="color: #F78C6C;"> 0b01</span><span>,</span></span>
<span class="giallo-l"><span> StartStopOperation</span><span style="color: #7FDBCA;">::</span><span>EjectDisc</span><span style="color: #7FDBCA;"> =></span><span style="color: #F78C6C;"> 0b10</span><span>,</span></span>
<span class="giallo-l"><span> StartStopOperation</span><span style="color: #7FDBCA;">::</span><span>LoadStartDisc</span><span style="color: #C792EA;"> |</span><span> StartStopOperation</span><span style="color: #7FDBCA;">::</span><span>Jump {</span><span style="color: #7FDBCA;"> ..</span><span> }</span><span style="color: #7FDBCA;"> =></span><span style="color: #F78C6C;"> 0b11</span><span>,</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> _</span><span style="color: #7FDBCA;"> =></span><span style="color: #F78C6C;"> 0b00</span><span>,</span></span>
<span class="giallo-l"><span> };</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span style="color: #C792EA;"> let</span><span> StartStopOperation</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">Power</span><span>(</span><span style="color: #C5E478;">pow_cond</span><span>)</span><span style="color: #C792EA;"> =</span><span style="color: #C5E478;"> operation</span><span> {</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> cdb</span><span>[</span><span style="color: #F78C6C;">4</span><span>]</span><span style="color: #C792EA;"> |=</span><span> (</span><span style="color: #C5E478;">pow_cond</span><span style="color: #C792EA;"> as</span><span> u8</span><span style="color: #7FDBCA;"> &</span><span style="color: #82AAFF;"> POWER_COND_BITMASK</span><span>)</span><span style="color: #C792EA;"> <<</span><span style="color: #82AAFF;"> POWER_COND_BITPOS</span><span>;</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span style="color: #7FDBCA;"> self.</span><span style="color: #82AAFF;font-style: italic;">run_command</span><span>(Some(MmcDirection</span><span style="color: #7FDBCA;">::</span><span>Write),</span><span style="color: #7FDBCA;"> &</span><span style="color: #C792EA;font-style: italic;">mut</span><span> [],</span><span style="color: #C5E478;"> cdb</span><span>)</span><span style="color: #7FDBCA;">?</span><span>;</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span> Ok(())</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"><span style="color: #C792EA;">type</span><span> Cdb</span><span style="color: #C792EA;"> =</span><span> [u8;</span><span style="color: #F78C6C;"> 12</span><span>];</span></span></code></pre></details>
<h2 id="porting-the-utility-programs"><a class="zola-anchor" href="#porting-the-utility-programs" aria-label="Anchor link for: porting-the-utility-programs"><i class="icon"></i></a>
Porting the utility programs</h2>
<p>The utility programs were essentially a demonstration of the library
capabilities.</p>
<p>Designing a CLI program is pretty simple in Rust, thanks to the
<a rel="external" href="https://crates.io/crates/clap"><code>clap</code></a> crate.</p>
<p>The <a rel="external" href="https://rust-cli.github.io/book/">Command line apps in Rust</a> is a neat guide.</p>
<p>However, a wrapper is needed for these to-be-Rust binaries to interface
with the C library.</p>
<h3 id="libcdio-sys-raw-bindings-over-libcdio"><a class="zola-anchor" href="#libcdio-sys-raw-bindings-over-libcdio" aria-label="Anchor link for: libcdio-sys-raw-bindings-over-libcdio"><i class="icon"></i></a>
libcdio-sys: Raw bindings over libcdio</h3>
<p>The first layer in interacting with a C library is to have a <code>-sys</code>
crate, which provides raw Rust bindings, i.e <code>extern fn</code>s, <code>const</code>s,
<code>static</code>s and <code>struct</code>s for every type, value and function exposed
by the C library.</p>
<p>Fortunately, <a rel="external" href="https://crates.io/crates/libcdio-sys">libcdio-sys</a> already existed.
It used [bindgen][bindgen-guide] to generate the bindings from
libcdio’s public C headers at build time.</p>
<p>However, it depended on having libcdio’s headers installed in the
system, and also, did not support vendoring.</p>
<h4 id="adding-vendoring-support-to-libcdio-sys"><a class="zola-anchor" href="#adding-vendoring-support-to-libcdio-sys" aria-label="Anchor link for: adding-vendoring-support-to-libcdio-sys"><i class="icon"></i></a>
Adding vendoring support to libcdio-sys</h4>
<blockquote class="tip">
<p class="alert-title">
<i class="icon"></i>Tip</p>
<p>Vendoring in Rust is a practice where a crate also includes
the underlying C library that it provides bindings for.</p>
</blockquote>
<p>Ideally, these programs should require minimum effort to be installed,
i.e a <code>cargo install</code> should suffice. Having to install the C library
separately from repositories, or worse, having to build it from source
is not encouraging.</p>
<p>Moreover, the versions of libcdio in distro repositories varied:</p>
<ul>
<li>Fedora shipped <code>v2.1.0</code></li>
<li>Debian shipped <code>v2.2.0</code> (Newer than Fedora? 🧐)</li>
<li>Arch shipped <code>v2.3.0</code> (the latest, btw)</li>
</ul>
<p>While libcdio’s interfaces did not change much, the safe wrapper
relied on bugfixes that were about to be introduced in the next
release, <code>v2.4.0</code>. Given the slow pace of distro packaging, one would
have to resort to building and installing libcdio from source to
be able to use the Rust packages.</p>
<p>Vendoring solves this by also building the C library alongside the
<code>-sys</code> crate.</p>
<p>The libgit2-inspired versioning scheme for the <code>libcdio-sys</code> crate
also allows users to have a fine grained control over the version
of the underlying C library.</p>
<p>A custom <code>config.h</code> was made with common values for the most supported
targets to replace the Autotools generated one, and the <code>cc</code> crate was
used to compile the C sources.</p>
<p>This was guarded behind a <code>vendored</code> feature, alongside an opt-out env
variable <code>LIBCDIO_NO_VENDOR</code>, due to the additive nature of Cargo’s
features that might set this anyway if another crate in the dependency
chain happen to enable it.</p>
<p>And finally the default behavior was updated to probe the system
first, and fall back to vendoring if that fails.</p>
<p>Here’s the Pull Request: <a rel="external" href="https://github.com/libcdio/libcdio-sys/pull/10">libcdio-sys</a></p>
<p>As always, Jon Gjengset’s
<a rel="external" href="https://www.youtube.com/watch?v=pePqWoTnSmQ">“Crust of Rust: Build scripts and FFI”</a>
was very helpful.</p>
<h3 id="libcdio-rs-a-safe-rust-wrapper-over-libcdio"><a class="zola-anchor" href="#libcdio-rs-a-safe-rust-wrapper-over-libcdio" aria-label="Anchor link for: libcdio-rs-a-safe-rust-wrapper-over-libcdio"><i class="icon"></i></a>
libcdio-rs: A safe Rust wrapper over libcdio</h3>
<p>The raw Rust bindings provided by <code>-sys</code> crates are too cumbersome
for direct use.</p>
<p>Therefore, another layer abstracts the <code>-sys</code> crate:</p>
<ul>
<li>
<p>Converts raw and C compatible types such as <code>c_int</code>, <code>*const c_char</code>, and <code>CString</code> to standard Rust types such as
<code>i32</code>, <code>&str</code> and <code>String</code>.</p>
</li>
<li>
<p>Encapsulates the C library’s functionality through a neat,
object-oriented interface.</p>
</li>
<li>
<p>Leverages Rust’s borrow checker to enforce memory safety.</p>
<details>
<summary>Example: An ISO 9660 entry whose lifetime is tied to its
parent filesystem instance</summary>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="rust"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/// ISO 9660 file/directory entry.</span></span>
<span class="giallo-l"><span style="color: #C792EA;">pub struct</span><span> IsoEntry<'a> {</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> /// The parent ISO 9660 object</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> pub</span><span>(</span><span style="color: #C792EA;">crate</span><span>)</span><span style="color: #C5E478;"> iso</span><span style="color: #7FDBCA;">: &</span><span>'a Iso,</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> pub</span><span>(</span><span style="color: #C792EA;">crate</span><span>)</span><span style="color: #C5E478;"> stat</span><span style="color: #7FDBCA;">:</span><span> NonNull<</span><span style="color: #C5E478;">iso9660_stat_s</span><span>>,</span></span>
<span class="giallo-l"><span>}</span></span></code></pre></details>
</li>
<li>
<p>Handles memory management using the <code>Drop</code> trait, rather than
having to call destructors manually.</p>
</li>
<li>
<p>Miscellaneous things, such as exposing C emitted logs, for example
using the <a rel="external" href="https://crates.io/crates/tracing"><code>tracing</code></a> crate.</p>
<details>
<summary>Capturing libcdio's C logs in Rust</summary>
<p>libcdio provided for setting a custom log handler, through the
<code>cdio_log_set_handler()</code> function.</p>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="c"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/**</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">* Set a custom log handler for libcdio. The return value is the log</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">* handler being replaced. If the provided parameter is NULL, then</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">* the handler will be reset to the default handler.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">*/</span></span>
<span class="giallo-l"><span style="color: #C5E478;">cdio_log_handler_t</span><span style="color: #82AAFF;font-style: italic;"> cdio_log_set_handler</span><span> (</span><span style="color: #C5E478;">cdio_log_handler_t</span><span style="color: #D7DBE0;"> new_handler</span><span>);</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">/**</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">* This type defines the signature of a log handler. For every</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">* message being logged, the handler will receive the log level and</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">* the message string.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">*/</span></span>
<span class="giallo-l"><span style="color: #C792EA;">typedef void</span><span> (</span><span style="color: #7FDBCA;">*</span><span style="color: #C5E478;">cdio_log_handler_t</span><span>) (</span><span style="color: #C5E478;">cdio_log_level_t</span><span> level,</span><span style="color: #C792EA;font-style: italic;"> const</span><span style="color: #C792EA;"> char</span><span> message</span><span style="color: #C792EA;font-style: italic;">[]</span><span>);</span></span></code></pre>
<p>This handler function would be called for every log produced by the
library and be provided with the log level and the message.</p>
<p>Thus, I defined an <code>extern "C" fn log_handler()</code> which translated
these logs to <code>tracing</code> via its macros passed it to the C library via
<code>init_logger()</code>:</p>
<pre class="giallo" style="color: #D6DEEB; background-color: #011627;"><code data-lang="rust"><span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Handle logs via tracing.</span></span>
<span class="giallo-l"><span style="color: #C792EA;">extern</span><span style="color: #D9F5DD;"> "</span><span style="color: #ECC48D;">C</span><span style="color: #D9F5DD;">"</span><span style="color: #C792EA;"> fn</span><span style="color: #82AAFF;font-style: italic;"> log_handler</span><span>(</span><span style="color: #C5E478;">level</span><span style="color: #7FDBCA;">:</span><span style="color: #C5E478;"> cdio_log_level_t</span><span>,</span><span style="color: #C5E478;"> message</span><span style="color: #7FDBCA;">: *</span><span style="color: #C792EA;font-style: italic;">const</span><span style="color: #C5E478;"> c_char</span><span>) {</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> if</span><span style="color: #C5E478;"> message</span><span style="color: #7FDBCA;">.</span><span style="color: #82AAFF;font-style: italic;">is_null</span><span>() {</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> return</span><span>;</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // SAFETY: message is not null, and is backed by an array on the</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // caller's stack.</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> let</span><span style="color: #C5E478;"> message</span><span style="color: #C792EA;"> = unsafe</span><span> { CStr</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">from_ptr</span><span>(</span><span style="color: #C5E478;">message</span><span>) };</span></span>
<span class="giallo-l"><span style="color: #C792EA;"> let</span><span> Ok(</span><span style="color: #C5E478;">message</span><span>)</span><span style="color: #C792EA;"> =</span><span style="color: #C5E478;"> message</span><span style="color: #7FDBCA;">.</span><span style="color: #82AAFF;font-style: italic;">to_str</span><span>()</span><span style="color: #C792EA;font-style: italic;"> else</span><span> {</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> return</span><span>;</span></span>
<span class="giallo-l"><span> };</span></span>
<span class="giallo-l"><span> #[allow(non_upper_case_globals)]</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> match</span><span style="color: #C5E478;"> level</span><span> {</span></span>
<span class="giallo-l"><span> cdio_log_level_t_CDIO_LOG_ASSERT </span><span style="color: #C792EA;">|</span><span> cdio_log_level_t_CDIO_LOG_ERROR </span><span style="color: #7FDBCA;">=></span><span> {</span></span>
<span class="giallo-l"><span> tracing</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">error!</span><span>(</span><span style="color: #C5E478;">message</span><span>)</span></span>
<span class="giallo-l"><span> }</span></span>
<span class="giallo-l"><span> cdio_log_level_t_CDIO_LOG_WARN </span><span style="color: #7FDBCA;">=></span><span> tracing</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">warn!</span><span>(</span><span style="color: #C5E478;">message</span><span>),</span></span>
<span class="giallo-l"><span> cdio_log_level_t_CDIO_LOG_INFO </span><span style="color: #7FDBCA;">=></span><span> tracing</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">info!</span><span>(</span><span style="color: #C5E478;">message</span><span>),</span></span>
<span class="giallo-l"><span style="color: #C5E478;"> _</span><span style="color: #7FDBCA;"> =></span><span> tracing</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">debug!</span><span>(</span><span style="color: #C5E478;">message</span><span>),</span></span>
<span class="giallo-l"><span> };</span></span>
<span class="giallo-l"><span>}</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">/// Configures libcdio to emit tracing (or "log" crate) logs.</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;">/// This should be called before using any other methods.</span></span>
<span class="giallo-l"><span style="color: #C792EA;">pub</span><span>(</span><span style="color: #C792EA;">crate</span><span>)</span><span style="color: #C792EA;"> fn</span><span style="color: #82AAFF;font-style: italic;"> init_logger</span><span>() {</span></span>
<span class="giallo-l"><span style="color: #C792EA;font-style: italic;"> static</span><span style="color: #82AAFF;"> LOG_HANDLER</span><span style="color: #7FDBCA;">:</span><span> Once</span><span style="color: #C792EA;"> =</span><span> Once</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">new</span><span>();</span></span>
<span class="giallo-l"><span style="color: #82AAFF;"> LOG_HANDLER</span><span style="color: #7FDBCA;">.</span><span style="color: #82AAFF;font-style: italic;">call_once</span><span>(</span><span style="color: #C792EA;">|| unsafe</span><span> {</span></span>
<span class="giallo-l"><span> libcdio_sys</span><span style="color: #7FDBCA;">::</span><span style="color: #82AAFF;font-style: italic;">cdio_log_set_handler</span><span>(Some(</span><span style="color: #C5E478;">log_handler</span><span>));</span></span>
<span class="giallo-l"></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // libcdio doesn't call our log handler unless its log level is</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // appropriate. Since the current log level is chosen by log</span></span>
<span class="giallo-l"><span style="color: #637777;font-style: italic;"> // subscribers, hack around by setting libcdio's log level to debug.</span></span>
<span class="giallo-l"><span> libcdio_sys</span><span style="color: #7FDBCA;">::</span><span style="color: #C5E478;">cdio_loglevel_default</span><span style="color: #C792EA;"> =</span><span> cdio_log_level_t_CDIO_LOG_DEBUG;</span></span>
<span class="giallo-l"><span> });</span></span>
<span class="giallo-l"><span>}</span></span></code></pre>
<p>To make sure logs are not missed, <code>init_logger()</code> must be called at
all entry points of the library such as constructors, so that the
handler gets set as early as possible.</p>
</details>
</li>
</ul>
<h4 id="improvements-to-the-c-library"><a class="zola-anchor" href="#improvements-to-the-c-library" aria-label="Anchor link for: improvements-to-the-c-library"><i class="icon"></i></a>
Improvements to the C library</h4>
<p>As Rust code was calling C code, it has to depend on the C code
upholding certain things to be safe. Things such as reentrancy and
thread safety.</p>
<p>A few things were bypassed, such as the use of a <code>Mutex</code> at the Rust
side to temporaily fix the dangers from C code’s use of mutable
statics.</p>
<p>The C code was <a rel="external" href="https://github.com/libcdio/libcdio/pull/57">updated</a> to use reentrant variants
of functions, such as <code>strtok_r()</code> over <code>strtok()</code>.</p>
<p>A <a rel="external" href="https://github.com/libcdio/libcdio/pull/52">few places</a> were updated to use thread
locals over statics to uphold thread safety.</p>
<p>A few implementations were found to be incorrect according to spec,
which were also <a rel="external" href="https://github.com/libcdio/libcdio/pull/56">fixed</a>.</p>
<h3 id="the-utility-programs"><a class="zola-anchor" href="#the-utility-programs" aria-label="Anchor link for: the-utility-programs"><i class="icon"></i></a>
The utility programs</h3>
<p>libcdio has seven utility programs, out of which, I’d covered:</p>
<ul>
<li><code>iso-read</code>: Extracts files from an ISO 9660 filesystem.</li>
<li><code>iso-info</code>: Lists files and metadata of an ISO 9660 filesystem.</li>
<li><code>cd-drive</code>: Provides details and capabilities of a disc drive.</li>
<li><code>mmc-tool</code>: Allows to issue SCSI MMC commands to a disc drive.</li>
</ul>
<p>These were renamed to <code>iso-cp</code>, <code>iso-ls</code>, <code>drive-info</code> and <code>mmc-cli</code>,
since there were major changes in the inputs and outputs of these
programs and it also avoided a name collision.</p>
<p>Thanks to the <a rel="external" href="https://crates.io/crates/clap"><code>clap</code></a> crate, designing the CLI
interface was simple and idiomatic in a way that is strongly typed.</p>
<p>And now that we had a safe wrapper over <code>libcdio-rs</code>, all that
remained was to plug in the CLI interface with the library routines.</p>
<p>The options and <a rel="external" href="https://github.com/libcdio/libcdio-rs/pull/9">outputs were improved</a>.</p>
<h2 id="a-three-month-journey"><a class="zola-anchor" href="#a-three-month-journey" aria-label="Anchor link for: a-three-month-journey"><i class="icon"></i></a>
A three month journey</h2>
<p>This project has allowed me to expand my Rust expertise to the
domain of systems programming, a level that closer to hardware
than the back end domain that I was already familiar with.</p>
<p>Interpreting lengthy specification sheets and collaborating with
the community and other authors were all quite the experience.</p>
<p>GSoC has been very good program in getting familiar with
distributed model of open source development, and I highly recommend
it.</p>