From: Horia Geanta Subject: [PATCH 9/9] crypto: caam - add Run Time Library (RTA) docbook Date: Fri, 18 Jul 2014 19:37:26 +0300 Message-ID: <1405701446-13656-10-git-send-email-horia.geanta@freescale.com> References: <1405701446-13656-1-git-send-email-horia.geanta@freescale.com> Mime-Version: 1.0 Content-Type: text/plain Cc: "David S. Miller" , Carmen Iorga , Kim Phillips , Alexandru Porosanu , Vakul Garg , Ruchika Gupta , "Horia Geanta" , Randy Dunlap To: Herbert Xu , Return-path: Received: from mail-by2lp0239.outbound.protection.outlook.com ([207.46.163.239]:25091 "EHLO na01-by2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1756997AbaGRQjf (ORCPT ); Fri, 18 Jul 2014 12:39:35 -0400 In-Reply-To: <1405701446-13656-1-git-send-email-horia.geanta@freescale.com> Sender: linux-crypto-owner@vger.kernel.org List-ID: Add SGML template for generating RTA docbook. Source code is in drivers/crypto/caam/flib Cc: Randy Dunlap Signed-off-by: Horia Geanta --- Documentation/DocBook/Makefile | 3 +- Documentation/DocBook/rta-api.tmpl | 245 +++++++++++++++++++++ Documentation/DocBook/rta/.gitignore | 1 + Documentation/DocBook/rta/Makefile | 5 + Documentation/DocBook/rta/rta_arch.svg | 381 +++++++++++++++++++++++++++++++++ 5 files changed, 634 insertions(+), 1 deletion(-) create mode 100644 Documentation/DocBook/rta-api.tmpl create mode 100644 Documentation/DocBook/rta/.gitignore create mode 100644 Documentation/DocBook/rta/Makefile create mode 100644 Documentation/DocBook/rta/rta_arch.svg diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index bec06659e0eb..f2917495db49 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -15,7 +15,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ tracepoint.xml drm.xml media_api.xml w1.xml \ - writing_musb_glue_layer.xml + writing_musb_glue_layer.xml rta-api.xml include Documentation/DocBook/media/Makefile @@ -53,6 +53,7 @@ htmldocs: $(HTML) $(call build_main_index) $(call build_images) $(call install_media_images) + $(call install_rta_images) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) diff --git a/Documentation/DocBook/rta-api.tmpl b/Documentation/DocBook/rta-api.tmpl new file mode 100644 index 000000000000..cefd267a00eb --- /dev/null +++ b/Documentation/DocBook/rta-api.tmpl @@ -0,0 +1,245 @@ + + + + + + Writing descriptors for Freescale CAAM using RTA library + + + Horia + Geanta + +
horia.geanta@freescale.com
+ + + + + + 2008-2014 + Freescale Semiconductor + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + About +!Pdrivers/crypto/caam/flib/rta.h About +!Pdrivers/crypto/caam/flib/rta.h Usage + + + + + RTA Integration Overview + + + + Using RTA + + RTA can be used in an application just by including the following header file: + #include flib/rta.h + + + The files in drivers/crypto/caam/desc directory contain several + real-world descriptors written with RTA. You can use them as-is or adapt + them to your needs. + + + RTA routines assume that your code defines a local variable named + "program": + + + struct program prg; + + + struct program *program = &prg; + + + This variable is passed behind the scene to all RTA API calls. + It contains several housekeeping information that are used during + descriptor creation. + + + RTA creates the descriptors and saves them in buffers. It is the user's + job to allocate memory for these buffers before passing them to RTA + program initialization call. + + + A RTA program must start with a call to PROGRAM_CNTXT_INIT and end with + PROGRAM_FINALIZE. PROGRAM_CNTXT_INIT will initialze the members of + 'program' structure with user information (pointer to user's buffer, and + the SEC subversion). The PROGRAM_FINALIZE call checks the descriptor's + validity. + + + The program length is limited to the size of buffer descriptor which + can be maximum 64 words (256 bytes). However, a JUMP command can cause + loading and execution of another Job Descriptor; this allows for much + larger programs to be created. + + + + RTA components + + The content of the package is split mainly in two components: + + + descriptor builder API (drivers/crypto/caam/flib/rta.h) + + + + ready to use RTA descriptors + (drivers/crypto/caam/flib/desc/*.h) + + + + + + These are the main building blocks of descriptors: + + + buffer management: init & finalize + + + SEC commands: MOVE, LOAD, FIFO_LOAD etc. + + + descriptor labels (e.g. used as JUMP destinations) + + + + utility commands: (e.g. PATCH_* commands that update labels and + references) + + + + + + In some cases, descriptor fields can't all be set when the commands are + inserted. These fields must be updated in a similar fashion to what the + linking process does with a binary file. RTA uses PATCH_* commands to + get relevant information and PROGRAM_FINALIZE to complete the + "code relocation". + + + If there is a need for descriptors larger than 64 words, their function + can be split into several smaller ones. In such case the smaller + descriptors are correlated and updated using PATCH_*_NON_LOCAL commands. + These calls must appear after all the descriptors are finalized and not + before as in a single descriptor case (the reason being that only then + references to all descriptors are available). + + + + + + RTA API reference + + Descriptor Buffer Management Routines +!Pdrivers/crypto/caam/flib/rta.h Descriptor Buffer Management Routines +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h rta_sec_era +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h USER_SEC_ERA +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h INTL_SEC_ERA +!Fdrivers/crypto/caam/flib/rta.h PROGRAM_CNTXT_INIT +!Fdrivers/crypto/caam/flib/rta.h PROGRAM_FINALIZE +!Fdrivers/crypto/caam/flib/rta.h PROGRAM_SET_36BIT_ADDR +!Fdrivers/crypto/caam/flib/rta.h PROGRAM_SET_BSWAP +!Fdrivers/crypto/caam/flib/rta.h WORD +!Fdrivers/crypto/caam/flib/rta.h DWORD +!Fdrivers/crypto/caam/flib/rta.h COPY_DATA +!Fdrivers/crypto/caam/flib/rta.h DESC_LEN +!Fdrivers/crypto/caam/flib/rta.h DESC_BYTES +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h program + + + SEC Commands Routines +!Pdrivers/crypto/caam/flib/rta.h SEC Commands Routines +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h rta_share_type +!Fdrivers/crypto/caam/flib/rta.h SHR_HDR +!Fdrivers/crypto/caam/flib/rta.h JOB_HDR +!Fdrivers/crypto/caam/flib/rta.h JOB_HDR_EXT +!Fdrivers/crypto/caam/flib/rta.h MOVE +!Fdrivers/crypto/caam/flib/rta.h MOVEB +!Fdrivers/crypto/caam/flib/rta.h MOVEDW +!Fdrivers/crypto/caam/flib/rta.h FIFOLOAD +!Fdrivers/crypto/caam/flib/rta.h SEQFIFOLOAD +!Fdrivers/crypto/caam/flib/rta.h FIFOSTORE +!Fdrivers/crypto/caam/flib/rta.h SEQFIFOSTORE +!Fdrivers/crypto/caam/flib/rta.h KEY +!Fdrivers/crypto/caam/flib/rta.h SEQINPTR +!Fdrivers/crypto/caam/flib/rta.h SEQOUTPTR +!Fdrivers/crypto/caam/flib/rta.h ALG_OPERATION +!Fdrivers/crypto/caam/flib/rta.h PROTOCOL +!Fdrivers/crypto/caam/flib/rta.h PKHA_OPERATION +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h rta_jump_cond +!Fdrivers/crypto/caam/flib/rta/sec_run_time_asm.h rta_jump_type +!Fdrivers/crypto/caam/flib/rta.h JUMP +!Fdrivers/crypto/caam/flib/rta.h JUMP_INC +!Fdrivers/crypto/caam/flib/rta.h JUMP_DEC +!Fdrivers/crypto/caam/flib/rta.h LOAD +!Fdrivers/crypto/caam/flib/rta.h SEQLOAD +!Fdrivers/crypto/caam/flib/rta.h STORE +!Fdrivers/crypto/caam/flib/rta.h SEQSTORE +!Fdrivers/crypto/caam/flib/rta.h MATHB +!Fdrivers/crypto/caam/flib/rta.h MATHU +!Fdrivers/crypto/caam/flib/rta.h SIGNATURE +!Fdrivers/crypto/caam/flib/rta.h NFIFOADD + + + Self Referential Code Management Routines +!Pdrivers/crypto/caam/flib/rta.h Self Referential Code Management Routines +!Fdrivers/crypto/caam/flib/rta.h REFERENCE +!Fdrivers/crypto/caam/flib/rta.h LABEL +!Fdrivers/crypto/caam/flib/rta.h SET_LABEL +!Fdrivers/crypto/caam/flib/rta.h PATCH_JUMP +!Fdrivers/crypto/caam/flib/rta.h PATCH_JUMP_NON_LOCAL +!Fdrivers/crypto/caam/flib/rta.h PATCH_MOVE +!Fdrivers/crypto/caam/flib/rta.h PATCH_MOVE_NON_LOCAL +!Fdrivers/crypto/caam/flib/rta.h PATCH_LOAD +!Fdrivers/crypto/caam/flib/rta.h PATCH_STORE +!Fdrivers/crypto/caam/flib/rta.h PATCH_STORE_NON_LOCAL +!Fdrivers/crypto/caam/flib/rta.h PATCH_RAW +!Fdrivers/crypto/caam/flib/rta.h PATCH_RAW_NON_LOCAL + + + + + RTA descriptors library + + Job Descriptor Example Routines +!Pdrivers/crypto/caam/flib/desc/jobdesc.h Job Descriptor Constructors +!Fdrivers/crypto/caam/flib/desc/jobdesc.h cnstr_jobdesc_mdsplitkey + + + Auxiliary Data Structures +!Pdrivers/crypto/caam/flib/desc/common.h Shared Descriptor Constructors - shared structures +!Fdrivers/crypto/caam/flib/desc/common.h alginfo +!Fdrivers/crypto/caam/flib/desc/common.h protcmd + + + diff --git a/Documentation/DocBook/rta/.gitignore b/Documentation/DocBook/rta/.gitignore new file mode 100644 index 000000000000..e461c585fde8 --- /dev/null +++ b/Documentation/DocBook/rta/.gitignore @@ -0,0 +1 @@ +!*.svg diff --git a/Documentation/DocBook/rta/Makefile b/Documentation/DocBook/rta/Makefile new file mode 100644 index 000000000000..58981e3ae3ef --- /dev/null +++ b/Documentation/DocBook/rta/Makefile @@ -0,0 +1,5 @@ +RTA_OBJ_DIR=$(objtree)/Documentation/DocBook/ +RTA_SRC_DIR=$(srctree)/Documentation/DocBook/rta + +install_rta_images = \ + $(Q)cp $(RTA_SRC_DIR)/*.svg $(RTA_OBJ_DIR)/rta_api diff --git a/Documentation/DocBook/rta/rta_arch.svg b/Documentation/DocBook/rta/rta_arch.svg new file mode 100644 index 000000000000..d816eed04852 --- /dev/null +++ b/Documentation/DocBook/rta/rta_arch.svg @@ -0,0 +1,381 @@ + + + + + RTA Integration Overview + + + + + + + + + + + + + image/svg+xml + + RTA Integration Overview + + + + + + + + + RTA + + + RTA + + + + + + + + + User space + Kernel space + Platform hardware + Cryptoapplication + QBMAN + + + + QI + + JRI + SEC + + SEC Driver + + SEC QI Driver + + -- 1.8.3.1