Libcaliptra (#496)

* libcaliptra

Derived from the api example in hw-model/c-binding/examples/api, this
is the initial skeleton of a more generic client API for Caliptra,
intended to abstract away the details of the implementation.

Client applications will include caliptra_api.h and implementations
will provide definitions to the functions declared in caliptra_if.h,
check the README.md for more information.

* Add support for integration with the model

This adds a generic reference to demonstrate client application use of the
Caliptra C API, and an example implementation of an interface, in this case
connecting the generic reference application to the hardware model.

Build happens from within the examples/hwmodel/ directory. Run `make` and then
run `./hwmodel` to execute the example.

This also removes the more basic if_test directory as it is now redundant

.github/workflows/build-test.yml

@@ -125,3 +125,6 @@ jobs:
           git submodule update --init
           (cd hw-model/c-binding/examples && make run)
 
+      - name: Caliptra C API Hwmodel Integration Test
+        run: |
+          (cd libcaliptra/examples/hwmodel && make && ./hwmodel)

hw-model/c-binding/examples/Makefile

@@ -34,7 +34,7 @@ $(OUT)/caliptra_model.h:
 
 $(OUT)/%.o: $(SOURCE)
 	$(MKDIR)
-	$(CC) ${CFLAGS} -c $< -o $@
+	$(CC) ${CFLAGS} -g -c $< -o $@
 
 $(TARGET): $(OUT)/caliptra_model.h $(OBJS)
 	$(CC) -o $(TARGET) $(OBJS) $(CFLAGS) -Wl,-L$(OUT)/debug -lcaliptra_hw_model_c_binding -lpthread -lstdc++ -ldl -lm

libcaliptra/.gitignore

@@ -0,0 +1,5 @@
+inc/caliptra_model.h
+src/caliptra_api.o
+libcaliptra/examples/generic/main.o
+libcaliptra/examples/hwmodel/hwmodel
+libcaliptra/examples/hwmodel/interface.o

libcaliptra/Makefile

@@ -0,0 +1,27 @@
+Q=@
+
+ifneq ($(MAKECMDGOALS),clean)
+ifndef RTL_SOC_IFC_INCLUDE_PATH
+$(error RTL_SOC_IFC_INCLUDE_PATH must be defined and point to a location where caliptra_top_reg.h can be found)
+endif
+endif
+
+LIBCALIPTRA = libcaliptra.a
+
+SOURCE += src/caliptra_api.c
+OBJS := $(patsubst %.c,%.o, $(filter %.c,$(SOURCE)))
+
+INCLUDES  = -I$(RTL_SOC_IFC_INCLUDE_PATH)
+INCLUDES += -Iinc
+
+$(LIBCALIPTRA): $(OBJS)
+	@echo [AR] $@
+	$(Q)ar -cq $@ $(OBJS)
+
+%.o: %.c
+	@echo [CC] $< \-\> $@
+	$(Q)$(CC) $(CFLAGS) $(DEFINES) $(INCLUDES) -g -c $< -o $@
+
+clean:
+	@echo [CLEAN] $(OBJS) $(LIBCALIPTRA)
+	$(Q)rm -f $(OBJS) $(LIBCALIPTRA)

libcaliptra/README.md

@@ -0,0 +1,41 @@
+# libcaliptra
+
+## Purpose
+
+libcaliptra is an abstraction layer between SoC applications and the Caliptra implementation in hardware.
+
+## Structure
+
+libcaliptra exists in two parts, the API and the Interface.
+
+### API
+
+Specified in caliptra_api.h and defined in caliptra_api.c
+
+Provides abstract APIs and functionality to SoC applications, independent of hardware details.
+
+### IF
+
+Specified in caliptra_if.h and used by caliptra_api.c
+
+The caliptra implementation must supply the definitions for the functions named in caliptra_if.h
+
+## Build
+
+To compile the API, the following must be provided:
+
+* Standard C headers
+* Access to the caliptra_top_reg.h header
+
+Run `make RTL_SOC_IFC_INCLUDE_PATH=<path>` to generate libcaliptra.a
+
+## Link
+
+To link the API, the following must be provided:
+
+* A main application utilizing these functions
+* An interface implementation
+
+## Implementation and consumer examples
+
+See examples/README.md for details on specific examples.

libcaliptra/examples/README.md

@@ -0,0 +1,23 @@
+# Caliptra C API Examples
+
+In this directory you will find a basic example on how to interact with the
+Caliptra C API and adapt it to your target platform.
+
+## Generic
+
+`generic/`
+
+The generic example contains the main() function, basic Caliptra startup, and firmware interaction.
+
+> NOTE: The current test executes a command that is ignored by ROM and not yet implemented by firmware.
+
+## hwmodel
+
+`hwmodel/`
+
+This is an implementation of the Caliptra C API Interface functions that target the hardware model. It abstracts out model specific details including:
+* ROM and Firmware image file opening
+** The paths are set at compile time, see the Makefile for details
+* Model-specific behavior (loading of ROM)
+* Model object management
+

libcaliptra/examples/generic/main.c

@@ -0,0 +1,63 @@
+// Licensed under the Apache-2.0 license
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <unistd.h>
+
+#include "caliptra_api.h"
+
+// Interface defined values
+extern struct caliptra_fuses  fuses;        // Device-specific location of Caliptra fuse data
+extern struct caliptra_buffer image_bundle; // Device-specific location of Caliptra firmware
+
+int main(int argc, char *argv[])
+{
+    int status;
+
+    fuses = (struct caliptra_fuses){0};
+
+    if ((status = caliptra_init_fuses(&fuses)) != 0)
+    {
+        printf("Failed to init fuses: %d\n", status);
+        return status;
+    }
+
+    // Initialize FSM GO
+    caliptra_bootfsm_go();
+
+    // Wait until ready for FW
+    caliptra_ready_for_firmware();
+
+    // Load Image Bundle
+    // FW_PATH is defined on the compiler command line
+    caliptra_upload_fw(&image_bundle);
+
+    uint32_t FIPS_VERSION = 0x46505652;
+
+    int mb_result;
+    uint32_t fips_ver;
+    struct caliptra_buffer buf = {
+        .data = (uint8_t*)&fips_ver,
+        .len = sizeof(fips_ver),
+    };
+
+    // Run Until RT is ready to receive commands
+    while(1) {
+        caliptra_wait();
+        mb_result = caliptra_mailbox_execute(FIPS_VERSION, &buf, NULL);
+
+        if (mb_result != -EIO)
+        {
+            printf("Caliptra C API Integration Test Failed: %x\n", mb_result);
+            return -1;
+        }
+
+        break;
+    }
+    printf("Caliptra C API Integration Test Passed \n");
+    return 0;
+}
+
+

libcaliptra/examples/generic/main.mk

@@ -0,0 +1,31 @@
+Q=@
+
+SOURCE += ../generic/main.c ../../src/caliptra_api.c
+
+LIBCALIPTRA_ROOT = ../..
+LIBCALIPTRA_INC  = $(LIBCALIPTRA_ROOT)/inc
+
+OBJS := $(patsubst %.c,%.o, $(filter %.c,$(SOURCE)))
+
+# SOC REFERENCE
+RTL_SOC_IFC_INCLUDE_PATH = ../../../hw-latest/caliptra-rtl/src/soc_ifc/rtl
+
+# INCLUDES
+INCLUDES += -I$(RTL_SOC_IFC_INCLUDE_PATH) -I$(LIBCALIPTRA_INC)
+
+.PHONY = run clean
+
+$(TARGET): $(OBJS) $(DEPS)
+	@echo [LINK] $(TARGET)
+	$(Q)$(CC) -o $(TARGET) $(OBJS) $(CFLAGS)
+
+$(CALIPTRA_API):
+	$(Q)make -C ../../
+
+%.o: %.c $(DEPS)
+	@echo [CC] $< \-\> $@
+	$(Q)$(CC) $(CFLAGS) $(DEFINES) $(INCLUDES) -g -c $< -o $@
+
+clean:
+	@echo [CLEAN] $(OBJS) $(TARGET)
+	$(Q)rm -f $(OBJS) $(TARGET)

libcaliptra/examples/hwmodel/Makefile

@@ -0,0 +1,68 @@
+TARGET = hwmodel
+
+.DEFAULT_GOAL = $(TARGET)
+
+LIBCALIPTRA_ROOT = ../../
+LIBCALIPTRA_INC  = 
+
+OUTPUT_DIR = ../../../target/debug
+
+# ROM AND FW DIR
+ROM_FW_DIR = $(OUTPUT_DIR)
+
+ROM_FILE = $(ROM_FW_DIR)/caliptra_rom.bin
+FW_FILE  = $(ROM_FW_DIR)/image_bundle.bin
+
+BUILDER_PATH = ../../../builder
+
+# ROM AND FW FILES
+#
+# These paths are encoded into the binary so the generic
+# main sources don't need a command line.
+DEFINES  = -DROM_PATH=\"$(ROM_FILE)\"
+DEFINES += -DFW_PATH=\"$(FW_FILE)\"
+
+# HW MODEL
+HWMODEL_DIR = $(OUTPUT_DIR)
+HWMODEL_HEADER_DIR = ../../../hw-model/c-binding/out
+HWMODEL_INCLUDE = -I$(HWMODEL_HEADER_DIR)
+HWMODEL_LIB = -Wl,-L$(HWMODEL_DIR) -lcaliptra_hw_model_c_binding
+HWMODEL_FLAGS = -lpthread -lstdc++ -ldl -lm
+HWMODEL_HEADER = $(HWMODEL_HEADER_DIR)/caliptra_model.h
+HWMODEL_BINDING_LIB_OBJ = $(HWMODEL_DIR)/libcaliptra_hw_model_c_binding.a
+
+# DEPENDENCIES
+DEPS += $(HWMODEL_BINDING_LIB_OBJ) $(HWMODEL_HEADER) $(ROM_FILE) $(FW_FILE)
+
+# INCLUDES
+INCLUDES += $(HWMODEL_INCLUDE)
+
+SOURCE += interface.c
+
+CFLAGS += $(HWMODEL_INCLUDE) $(HWMODEL_LIB) $(HWMODEL_FLAGS)
+
+$(ROM_FILE) $(FW_FILE):
+	@echo [IMAGE] caliptra_rom.bin image_bundle.bin
+	$(Q)make -C ../../../rom/dev
+	$(Q)cd ../../../runtime && ./build.sh
+	$(Q)cargo --config="$(EXTRA_CARGO_CONFIG)" run --manifest-path=$(BUILDER_PATH)/Cargo.toml --bin image -- --rom $(ROM_FW_DIR)/caliptra_rom.bin --fw $(ROM_FW_DIR)/image_bundle.bin
+
+$(HWMODEL_BINDING_LIB_OBJ):
+	@echo "[CARGO] c-binding"
+	$(Q)cd ../../../hw-model/c-binding
+	$(Q)cargo build
+
+EXTRA_CARGO_CONFIG = target.'cfg(all())'.rustflags = [\"-Dwarnings\"]
+
+$(TARGET): $(ROM_FILE) $(FW_FILE)
+
+$(HWMODEL_HEADER):
+	@echo "[CARGO] hw-model"
+	$(Q)cd ../../../hw-model
+	$(Q)cargo --config="$(EXTRA_CARGO_CONFIG)" build
+
+run: $(TARGET)
+	@echo [RUN] $(TARGET)
+	$(Q)./$(TARGET)
+
+include ../generic/main.mk

libcaliptra/examples/hwmodel/README.md

@@ -0,0 +1,11 @@
+# hwmodel
+
+This example defines the Caliptra interface functions, allowing the generic application to communicate with the hardware model without having to directly manage model-specific details.
+
+# Prerequisites
+
+The c-binding, rom, and firmware must all be built.
+
+# Build
+
+Running "make" will compile the Caliptra C API, the interface, and link the application against the C binding.