imxrt-log

An extension of imxrt-hal to enable device logging. imxrt-log supports two logging front-ends:

• defmt for efficient logging.
• log for text-based logging.

It supports two different back-end peripherals:

• A high-speed USB serial device.
• Serial UART with DMA.

For more information, see the API documentation. To try the various front- and back-ends on hardware, use the *_logging examples maintained with imxrt-hal.

lib.rs:

Logging extensions for i.MX RT processors.

imxrt-log supports two logging frontends:

• defmt for efficient logging.
• log for text-based logging.

See the defmt and [log] modules for more information.

imxrt-log builds upon the imxrt-hal hardware abstraction layer (HAL) and provides two peripheral backends:

• LPUART with DMA
• USB serial (CDC) device

Mix and match these frontends and backends to integrate logging into your i.MX RT processor. To understand the differences of each frontend, see the package documentation. Read on to learn about building this package, and to understand the differences in each backend.

Building

Given its dependency on imxrt-hal, this package has the same build requirements as imxrt-hal. To learn how to build this package, consult the HAL documentation. Essentially, if you can build the HAL, you can build this package.

This package uses critical-section to ensure safe concurrent access to the log producer. In order for this to build, you must select a correct critical section implementation for your system. See the critical-section documentation for more information.

Design

Logging frontends place log frames in a circular buffer. Compile- and run-time filters prevent log message formatting and copies. For more frontend design details, see the documentation of each frontend module.

Backends read from this circular buffer and asynchronously transfer data out of memory. Backends may buffer data as part of their implementation.

The circular buffer is the limiting resource. Once you initialize a logger with a frontend-backend combination, you cannot initialize any other loggers.

Backend usage

The LPUART and USB backends provide a consistent interface to drive logging. After initializing a front and backend pair, you receive a Poller object. In order to move log messages, you must occasionally call poll() on the poller object. Each poll() call either does nothing, or drives the asynchronous transfer of log messages from your peripheral.

The API allows you to enable or disable interrupts that fire when a transfer completes. Depending on the backend, the interrupt may periodically trigger. If the interrupt periodically triggers, you can use the interrupt to occasionally call poll().

The backends have some behavioral and performance differences. They're also initialized differently. The next section describes these differences.

LPUART with DMA

The LPUART with DMA implementation transports log messages over LPUART using DMA transfers. In summary,

• Initialize your LPUART before initializing the logger.
• If you enable interrupts, define your interrupt handlers.
• Bring your own timer to call poll().
• It uses less memory than USB.

Initialization. The logging initialiation routine requires an LPUART object from imxrt-hal. Configure your Lpuart object with baud rates, parity bits, etc. before supplying it to the logging initialization routine.

The initialization routine also requires a DMA channel. Any DMA channel will do. The implementation fully configures the DMA channel, so there is no need for you to configure the channel.

Interrupts. If you enable interrupts (see Interrupts), the DMA channel asserts its interrupt when each transfer completes. You must call poll() to clear the interrupt. The implementation does not touch LPUART interrupts.

Timers. The interrupts enabled by the LPUART backend cannot periodically trigger. Therefore, you are responsible for periodically calling poll(). Consider using a PIT or GPT timer from imxrt-hal to help with this, or consider calling poll() in a software loop.

Buffer management. The implementation performs DMA transfers directly out of the log message buffer. This means that there is no intermediate buffer for log messages. The implementation frees the log messages from the circular buffer once the transfer completes.

USBD

The USB device implementation transports log messages over USB by presenting a serial (USB CDC) class to a USB host. In summary,

• Simply provide USB register blocks to the logger initialization routine.
• If you enable interrupts, define your interrupt handles.
• You might not need your own timer.
• It uses more memory than LPUART.

Initialization. The logging initialization routine handles all peripheral configuration. You simply provide the USB register block instances; imxrt-hal can help with this.

By default, the initialization routine configures a high-speed USB device with a 512 byte bulk endpoint max packet size. You can change these settings with build-time environment variables, discussed later.

Interrupts. If you enable interrupts (see Interrupts), the USB device controller asserts its interrupt when each transfer completes. It also enables a USB-managed timer to periodically trigger the interrupt. You must call poll() to clear these interrupt conditions.

Timers. If you enable interrupts, the associated USB interrupt periodically fires. You can use this to periodically call poll() without using any other timer or software loop.

The timer has a default interval. You can configure this interval through each logger initialization routine.

If you do not enable interrupts, you're responsible for periodically calling poll(). See the LPUART timers discussion for recommendations.

Buffer management. The implementation copies data out of the circular buffer and places it in an intermediate transfer buffer. Once this copy completes, the implementation frees the log frames from the circular buffer, and starts the USB transfer from this intermediate buffer. The requirement for the intermediate buffer is a USB driver implementation detail that increases this backend's memory requirements.

Examples

It's easiest to use the USB backend because it has a built-in timer, and the implementation handles all peripheral initialization. The example below shows an interrupt-driven USB logger. It uses imxrt-hal APIs to prepare the logger.

use imxrt_log::defmt; // <-- Change 'defmt' to 'log' to change the frontend.
use imxrt_hal as hal;
use imxrt_ral as ral;

use ral::interrupt;
#[cortex_m_rt::interrupt]
fn USB_OTG1() {
    static mut POLLER: Option<imxrt_log::Poller> = None;
    if let Some(poller) = POLLER.as_mut() {
        poller.poll();
    } else {
        let poller = initialize_logger().unwrap();
        *POLLER = Some(poller);
        // Since we enabled interrupts, this interrupt
        // handler will be called for USB traffic and timer
        // events. These are handled by poll().
    }
}

/// Initialize a USB logger.
///
/// Returns `None` if any USB peripheral instance is taken,
/// or if initialization fails.
fn initialize_logger() -> Option<imxrt_log::Poller> {
    let usb_instances = hal::usbd::Instances {
        usb: unsafe { ral::usb::USB1::instance() },
        usbnc: unsafe { ral::usbnc::USBNC1::instance() },
        usbphy: unsafe { ral::usbphy::USBPHY1::instance() },
    };
    // Initialize the logger, and ensure that it triggers interrupts.
    let poller = defmt::usbd(usb_instances, imxrt_log::Interrupts::Enabled).ok()?;
    Some(poller)
}

// Elsewhere in your code, configure USB clocks. Then, pend the USB_OTG1()
// interrupt so that it fires and initializes the logger.
let mut ccm = unsafe { ral::ccm::CCM::instance() };
let mut ccm_analog = unsafe { ral::ccm_analog::CCM_ANALOG::instance() };
hal::ccm::analog::pll3::restart(&mut ccm_analog);
hal::ccm::clock_gate::usb().set(&mut ccm, hal::ccm::clock_gate::ON);

cortex_m::peripheral::NVIC::pend(interrupt::USB_OTG1);
// Safety: interrupt handler is self contained and safe to unmask.
unsafe { cortex_m::peripheral::NVIC::unmask(interrupt::USB_OTG1) };

// After the USB device enumerates and configures, you're ready for
// logging.
::defmt::info!("Hello world!");

For an advanced example that uses RTIC, see the rtic_logging example maintained in the imxrt-hal repository. This example lets you easily explore all frontend-backend combinations, and it works on various i.MX RT development boards.

Package configurations

You can configure this package at compile time.

• Binary configurations use feature flags.
• Variable configurations use environment variables set during compilation.

The table below describes the package feature flags. Default features make it easy for you to use all package features. To reduce dependencies, disable this package's default features, then selectively enable frontends and backends.

This package isn't particularly interesting without a frontend-backend combination, so this configuration is not supported. Any features not listed above are considered an implementation detail and may change without notice.

Environment variables provide additional configuration hooks. The table below describes the supported configuration variables and their effects on the build.

Note:

• IMXRT_LOG_USB_* are always permitted. If usbd is disabled, then IMXRT_LOG_USB_* configurations do nothing.
• If IMXRT_LOG_USB_SPEED=FULL, then IMXRT_LOG_USB_BULK_MPS cannot be 512. On the other hand, if IMXRT_LOG_USB_SPEED=HIGH, then IMXRT_LOG_USB_BULK_MPS must be 512.
• Both IMXRT_LOG_USB_BULK_MPS and IMXRT_LOG_BUFFER_SIZE affect internally-managed buffer sizes. If space is tight, reduces these numbers to reclaim memory.

Limitations

Although it uses critical-section, this logging package may not be designed for immediate use in a multi-core system, like the i.MX RT 1160 and 1170 MCUs. Notably, there's no critical section implementation for these processors that would ensure safe, shared access to the log producer across the cores. Furthermore, its not yet clear how to build embedded Rust applications for these systems.

Despite these limitations, it may be possible to use this package on multi-core MCUs, but you need to treat them as two single-core MCUs. Specifically, you would need to build two binaries -- one for each core, each having separate memory regions for data -- and each core would need to use its own, distinct peripheral for transport. Then, select a single-core critical-section implementation, like the one provided by cortex-m.