MPC18xSWUG Rev. 0, 9/2003 MPC184/MPC185 Security Co-Processor Software User’s Guide This document assumes that the user has a basic familiarity with the MPC18x architecture and theory of operation. A review of the MPC184 or MPC185 user’s manual is suggested prior to beginning application development. This document describes the software drivers provided to access the MPC184 and MPC185 security co-processors, and how to use them.
Table 1 contains acronyms and abbreviations that are used in this user’s manual. Table 1. Acronyms and Abbreviations Term Meaning AESA AES accelerator—This term is synonymous with AESU in the MPC18x User’s Manual and other documentation. AFHA ARC-4 hardware accelerator—This term is synonymous with AFEU in the MPC18x User’s Manual and other documentation. APAD Autopad—The MDHA will automatically pad incomplete message blocks out to 512 bits when APAD is enabled.
Overview 1 Overview The MCP18x device driver controls the communications to the MCP184 and MPC185 chips from a variety of processors. The MPC184 can operate in PCI or 8xx bus mode (PowerQUICC I). The MPC185 operates in 60x bus mode. Both chips are memory mapped and are accessed by applications via the drivers’ system or device memory. The device driver is written in ANSI C. An attempt has been made to write a device driver that is independent from the operating system agnostic, whenever possible.
Device Driver Components 2 Device Driver Components This section is provided to help users understand the internal structure of the device driver. 2.
Device Driver Components • • • • 2.3 Initialize the driver internal variables Initialize the ChannelAssignments table — The device driver will maintain this structure with state information for each channel and user request. A Mutex semaphore protects this structure so multiple tasks are prevented from interfering with each other. Initialize the internal queue — A queue that holds requests to be dispatched when channels are available. The queue will hold up to 16 requests.
User Interface 3 User Interface 3.1 End-User Application The end-user application populates the request structure with the appropriate information. These structures are described in Section 4, “Global Definitions,” and include the operation ID, channel, callback routines (success and error), and data. Once the request is prepared, the end-user application calls the ioctl function and passes the prepared request.
User Interface The code used to request and release a channel and EU is as follows: . . if (status = ioctl(device, IOCTL_RESERVE_CHANNEL_STATIC, &channel)) { printf("IOCTL_RESERVE_CHANNEL_STATIC failed 0x%04x\n", status); return status; } chan_st1 = channel; /* save the channel number */ channel = (channel << 8) | CHA_DES; if (status = ioctl(device, IOCTL_ASSIGN_CHA, &channel)) { printf("IOCTL_ASSIGN_CHA failed 0x%04x\n", status); return status; } . . .
User Interface printf ("Syntax-Logic Error in dynamic descriptor 0x%x\n", status); . . } . /* in callback function notifAes */ if (aesdynReq.status != 0) { printf ("Error detected by HW 0x%x\n", aesdynReq.status) ; . . } 8 MPC184/MPC185 Security Co-Processor Software User’s Guide PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE .
Global Definitions 4 4.1 Global Definitions I/O Control Codes The I/O control code is the second argument in the ioctl function. Internally, these values (as shown in Table 2), are used in conjunction with a base index to create the I/O control codes. The macro for this base index is defined by the MPC18x_IOCTL_INDEX and has a value of 0x0800. Table 2.
Global Definitions 4.2 Channel Definitions The NUM_CHANNELS define is used to specify the number of channels in the MCP18x (see Table 3). If not specified it will be set to a value of 4 as a default. Table 3.
Global Definitions 4.4 Return Code Definitions Table 5 provides a complete list of the error status results that may be returned to the callback routines. Table 5.
Global Definitions Table 5. Callback Error Status Return Code (continued) Define Description Value MPC18x_CANNOT_SETUP_BAR0_ERROR Error due to VxWorks not being able to setup the base address in pciGetBAR0() –1008 MPC18x_VXWORKS_CANNOT_CREATE_QUEUE Error due to VxWorks not being able to create the ISR queue in IOInitQs() –1009 MPC18x_CANCELLED_REQUEST Error due to canceled request –1010 MPC18x_INVALID_ADDRESS Error due to a NULL request –1011 4.5 4.5.
Global Definitions desencReq.keyData = mem.ptr; mem.from = desKey; mem.to = mem.ptr; status = Ioctl(device, IOCTL_COPYFROM, &mem); /* copy data to kernel memory */ mem.sz = len; status = Ioctl(device, IOCTL_MALLOC, &mem); desencReq.inData = mem.ptr; mem.from = desData; mem.to = mem.ptr; mem.sz = len; status = Ioctl(device, IOCTL_COPYFROM, &mem); /* malloc kernel output memory */ mem.sz = len; status = Ioctl(device, IOCTL_MALLOC, &mem); desDecResult = mem.
Global Definitions 4.5.3 MPC18x_NOTIFY_ON_ERROR_CTX Structure Structure returned to the notify_on_error callback routine that was setup in the initial process request. This structure contains the original request structure as well as an error and driver status.
Global Definitions 4.6.1 Random Number Generation Request Structures The following section provides structure definitions for the random number generation process request. 4.6.1.1 RNG_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long rngBytes; unsigned char* rngData; Dynamic channels are valid for this request.
Global Definitions 4.6.2 DES Process Request Structures The following sections provide structure definitions for DES process requests. 4.6.2.
Global Definitions 4.6.2.
Global Definitions 4.6.2.3 DES_CRYPT_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long inBytes; /* multiple of 8 bytes */ unsigned char* inData; unsigned char* outData; /* output length = input length */ Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.2.
Global Definitions 4.6.2.5 DES_GETCTX_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long ivBytes; unsigned char* ivData; Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.2.
Global Definitions 4.6.2.
Global Definitions 4.6.3 ARC4 Process Request Structures The following sections provide structure definitions for ARC4 process requests. 4.6.3.1 ARC4_NEWCTX_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long keyBytes; unsigned char* keyData; Dynamic channels are not valid for this request.
Global Definitions 4.6.3.2 ARC4_LOADCTX_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long ctxBytes; /* 257 bytes */ unsigned char* ctxData; Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.3.3 ARC4_CRYPT_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long inBytes; unsigned char* inData; unsigned char* outData; /* output length = input length */ Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.3.4 ARC4_CRYPT_GETCTX_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long inBytes; unsigned char* inData; unsigned char* outData; /* output length = input length */ unsigned long outCtxBytes; /* 257 bytes */ unsigned char* outCtxData; Dynamic channels are not valid for this request.
Global Definitions 4.6.3.
Global Definitions 4.6.3.
Global Definitions 4.6.4 Hash Request Structures The following sections provide structure definitions for hash requests. 4.6.4.1 HASH_LOADCTX_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long ctxBytes; unsigned char* ctxData; Dynamic channels are not valid for this request.
Global Definitions 4.6.4.2 HASH_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long inBytes; unsigned char* inData; Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions NUM_MDHA_STATIC_PAD_DESC defines the number of descriptors within the DPD_HASH_SA_HASH_PAD_GROUP that use this request. DPD_HASH_SA_HASH_PAD_GROUP (0x4200) defines the group for all descriptors within this request. Table 22.
Global Definitions 4.6.4.3 HASH_GETCTX_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long ctxBytes; unsigned char* ctxData; Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.4.4 HASH_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long ctxBytes; unsigned char* ctxData; unsigned long inBytes; unsigned char* inData; unsigned long outBytes; /* length is fixed by algorithm */ unsigned char* outData; Dynamic channels are valid for this request.
Global Definitions NUM_MDHA_PAD_DESC defines the number of descriptors within the DPD_HASH_LDCTX_HASH_PAD_ULCTX_GROUP that use this request. DPD_HASH_LDCTX_HASH_PAD_ULCTX_GROUP (0x4500) defines the group for all descriptors within this request. Table 25.
Global Definitions 4.6.5 HMAC Request Structures The following sections provide structure definitions for HMAC requests. 4.6.5.1 HMAC_PAD_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long keyBytes; unsigned char* keyData; Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.5.2 HMAC_PAD_HASH_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long keyBytes; unsigned char* keyData; unsigned long inBytes; unsigned char* inData; Dynamic channels are not valid for this request. A channel value of zero is invalid.
Global Definitions 4.6.5.3 HMAC_PAD_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long keyBytes; unsigned char* keyData; unsigned long inBytes; unsigned char* inData; unsigned long outBytes; /* length is fixed by algorithm */ unsigned char* outData; Dynamic channels are valid for this request.
Global Definitions 4.6.6 AES Request Structures The following section provides structure definitions for AES requests. 4.6.6.
Global Definitions 4.6.7 Kasumi Request Structures The following section provides structure definitions for Kasumi requests. 4.6.7.
Global Definitions 4.6.8 Integer Public Key Request Structures The following sections provide structure definitions for integer public key requests. 4.6.8.
Global Definitions 4.6.8.2 MOD_EXP_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long aDataBytes; unsigned char* aData; unsigned long expBytes; unsigned char* expData; unsigned long modBytes; unsigned char* modData; unsigned long outBytes; unsigned char* outData; Dynamic channels are valid for this request.
Global Definitions 4.6.8.3 MOD_R2MODN_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long modBytes; unsigned char* modData; unsigned long outBytes; unsigned char* outData; Dynamic channels are valid for this request. A channel value of zero is valid.
Global Definitions 4.6.8.4 MOD_RRMODP_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long nBytes; unsigned long pBytes; unsigned char* pData; unsigned long outBytes; unsigned char* outData; Dynamic channels are valid for this request. A channel value of zero is valid.
Global Definitions 4.6.8.5 MOD_2OP_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long bDataBytes; unsigned char* bData; unsigned long aDataBytes; unsigned char* aData; unsigned long modBytes; unsigned char* modData; unsigned long outBytes; unsigned char* outData; Dynamic channels are valid for this request.
Global Definitions Table 35.
Global Definitions Table 35.
Global Definitions 4.6.8.6 MOD_CLR_STATIC_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long aDataBytes; Dynamic channels are not valid for this request. A channel value of zero is invalid. NUM_MM_STATIC_CLR_DESC defines the number of descriptors within the DPD_MM_SA_CLR_GROUP that use this request.
Global Definitions 4.6.9 ECC Public Key Request Structures The following sections provide structure definitions for ECC public key requests. 4.6.9.
Global Definitions 4.6.9.
Global Definitions 4.6.9.
Global Definitions 4.6.9.
Global Definitions Table 40.
Global Definitions 4.6.9.5 ECC_2OP_REQ unsigned long opId; unsigned long channel; PMPC18x_NOTIFY_ROUTINE notify; PMPC18x_NOTIFY_CTX pNotifyCtx; PMPC18x_NOTIFY_ON_ERROR_ROUTINE notify_on_error; MPC18x_NOTIFY_ON_ERROR_CTX ctxNotifyOnErr; int status; void* nextReq; unsigned long bDataBytes; unsigned char* bData; unsigned long aDataBytes; unsigned char* aData; unsigned long modBytes; unsigned char* modData; unsigned long outBytes; unsigned char* outData; Dynamic channels are valid for this request.
Global Definitions 4.6.10 IPSec Request Structures The following sections provide structure definitions for IPSec requests. 4.6.10.
Global Definitions Table 42.
Global Definitions NUM_IPSEC_STATIC_CBC_DESC defines the number of descriptors within the DPD_IPSEC_STATIC_CBC_GROUP that use this request. DPD_IPSEC_STATIC_CBC_GROUP (0x7A00) defines the group for all descriptors within this request. Table 43.
Global Definitions Table 43.
Global Definitions Table 43.
Global Definitions 4.6.10.
Global Definitions Table 44.
Global Definitions NUM_IPSEC_STATIC_ECB_DESC defines the number of descriptors within the DPD_IPSEC_STATIC_ECB_GROUP that use this request. DPD_IPSEC_STATIC_ECB_GROUP (0x7B00) defines the group for all descriptors within this request. Table 45.
Global Definitions Table 45.
Global Definitions Table 45.
Global Definitions 4.6.10.
Global Definitions Table 46.
Global Definitions 4.6.10.
Global Definitions Table 47.
Sample Code 5 Sample Code The following sections provide sample codes for DES and IPSec. 5.1 DES Sample /* define the User Structure */ DES_LOADCTX_CRYPT_REQ desencReq; . . . /* fill the User Request structure with appropriate pointers */ desencReq.opId = DPD_TDES_CBC_ENCRYPT_SA_LDCTX_CRYPT ; desencReq.channel = 0; /* dynamic channel */ desencReq.notify = (void*) notifyDes; /* callback function */ desencReq.notify_on_error = (void*) notifyDes; /* callback in case of errors only */ desencReq.
Sample Code 5.2 IPSec Sample /* define User Requests structures */ IPSEC_CBC_REQ ipsecReq; . . . . /* Ipsec dynamic descriptor triple DES with SHA-1 authentication */ ipsecReq.opId = DPD_IPSEC_CBC_TDES_ENCRYPT_SHA_PAD; ipsecReq.channel = 0; ipsecReq.notify = (void *) notifyFunc; ipsecReq.notify_on_error = (void *) notifyFunc; ipsecReq.status = 0; ipsecReq.hashKeyBytes = 16; /* key length for HMAC SHA-1 */ ipsecReq.hashKeyData = authKey; /* pointer to HMAC Key */ ipsecReq.
Porting 6 Porting The following sections describe the main operating system specific concept of semaphores and the interrupt service routine (ISR), and the required files for the code, configuration, and external variables. 6.1 Include Files The interface module code uses the file vxWorks.h. This includes standard VxWorks type includes. Using this code in another system will require redefining those types for that system.
Porting • • 6.2 Linux kernel — init_MUTEX_LOCKED—This call creates the semaphore for later use. — up—This call takes the semaphore, preventing another task from using the resource. — down_timeout—This call gives the semaphore, allowing another process to use the resource. Linux user — sem_init—This call creates the semaphore for later use. — sem_post—This call takes the semaphore, preventing another task from using the resource.
Porting 6.4 Required Externals The software driver requires two external variables: // Specifies the base address of the MPC185 security processor in memory. extern const UINT32 MPC185_BASE_ADRS; // Specifies the base address of the MPC184 in memory.
VxWorks Environment 7 VxWorks Environment The following sections describe the installation of the MPC184 and MPC185 security processor software drivers, BSP integration, and distribution archives. 7.1 Introduction These release notes support MPC184 and MPC185 security processor software drivers interface for use with VxWorks. NOTE Forward slashes are used as pathname delimiters for both UNIX and Windows filenames since this is the default for VxWorks. 7.
VxWorks Environment 7.4 BSP Integration Once the modules are built, they should be linked directly with the user’s board support package, to become integral part of the board image. In VxWorks, the file sysLib.c contains the initialization functions, the memory/address space functions, and the bus interrupt functions. It is recommended to call the function MPC18xDriverInit directly from sysLib.c.
Linux Environment 8 Linux Environment Before starting with the drivers installation, refer to the Readme file included in the Linux package to understand kernel building and board dependencies. 8.1 Installation To install the software drivers, copy the source files into the build directory of choice. 8.2 Building the Interface Modules Throughout the remainder of the installation instructions, the variable provided in Table 49 is used: Table 49.
Linux Environment h/drv/crypto/dpd_Table.h h/drv/crypto/MPC18x.h h/drv/crypto/MPC18x_Descriptors.h h/drv/crypto/MPC18xDriver.h h/drv/crypto/MPC18xNotify.h src/drv/crypto/cha.c src/drv/crypto/dpd.c src/drv/crypto/init.c src/drv/crypto/io.c src/drv/crypto/ioctl.c src/drv/crypto/isr.c src/drv/crypto/request.
Revision History 9 Revision History Table 50 provides a revision history for this user’s manual. Table 50. Document Revision History Rev. No. 0 MOTOROLA Substantive Change(s) Initial release.
Revision History THIS PAGE INTENTIONALLY LEFT BLANK 78 MPC184/MPC185 Security Co-Processor Software User’s Guide PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE MOTOROLA
Revision History THIS PAGE INTENTIONALLY LEFT BLANK MOTOROLA MPC184/MPC185 Security Co-Processor Software User’s Guide PRELIMINARY—SUBJECT TO CHANGE WITHOUT NOTICE 79
HOW TO REACH US: USA/EUROPE/LOCATIONS NOT LISTED: Motorola Literature Distribution P.O. Box 5405, Denver, Colorado 80217 1-480-768-2130 (800) 521-6274 JAPAN: Motorola Japan Ltd. SPS, Technical Information Center 3-20-1, Minami-Azabu Minato-ku Tokyo 106-8573 Japan 81-3-3440-3569 Information in this document is provided solely to enable system and software implementers to use Motorola products.