[v4,08/12] doc: TEE: Add documentation describing TEE in u-boot

This patch adds a brief description of TEE in u-boot.

It gives a basic introduction, description of image generation with mkimage
plus the various ways u-boot can install or chainload a TEE.

Methods covered in this patch are

- tee-standalone
  This is method where u-boot loads a TEE into an area of DRAM or SRAM
  hands off control to a ROM callback or jumps into the TEE intself and
  then once the TEE is installed, returns control to u-boot.

- tee-bootable
  This is the method where u-boot chain-loads the TEE. In this case once
  u-boot hands off control to the TEE execution does not return to u-boot.

Subsequent methods of performing a TEE boot with u-boot may be added over
time, for example "tee-combo" is being discussed.

Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
---
 doc/README.trusted-execution-environment | 123 +++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 doc/README.trusted-execution-environment

> On 26 Feb 2018, at 13:36, Bryan O'Donoghue <bryan.odonoghue@linaro.org> wrote:
> 
> This patch adds a brief description of TEE in u-boot.
> 
> It gives a basic introduction, description of image generation with mkimage
> plus the various ways u-boot can install or chainload a TEE.
> 
> Methods covered in this patch are
> 
> - tee-standalone
>  This is method where u-boot loads a TEE into an area of DRAM or SRAM
>  hands off control to a ROM callback or jumps into the TEE intself and
>  then once the TEE is installed, returns control to u-boot.
> 
> - tee-bootable
>  This is the method where u-boot chain-loads the TEE. In this case once
>  u-boot hands off control to the TEE execution does not return to u-boot.
> 
> Subsequent methods of performing a TEE boot with u-boot may be added over
> time, for example "tee-combo" is being discussed.
> 
> Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> ---
> doc/README.trusted-execution-environment | 123 +++++++++++++++++++++++++++++++
> 1 file changed, 123 insertions(+)
> create mode 100644 doc/README.trusted-execution-environment
> 
> diff --git a/doc/README.trusted-execution-environment b/doc/README.trusted-execution-environment
> new file mode 100644
> index 0000000..12bf615
> --- /dev/null
> +++ b/doc/README.trusted-execution-environment
> @@ -0,0 +1,123 @@
> +Trusted Execution Environment
> +=============================
> +
> +Overview
> +--------
> +Trusted Execution Environment (TEE) specifies a secure mode of execution of a
> +processor. The TEE provides an isolted environment that runs in parallel to the
> +rich execution environment meaning an environment such as a Linux based
> +operating system.
> +
> +TEE may provide access to crypto keys or other pieces of secure silicon that are
> +not available to the rich execution environment or TEE implementations may
> +reside in secure sections of memory only accessible when running in a TEE
> +context.
> +
> +The TEE specification is available here:
> +https://www.globalplatform.org/specificationsdevice.asp
> +
> +In u-boot currently all TEE versions supported are based on the Open Portable
> +Trusted Execution Environment project. OP-TEE is an open source implementation
> +of a TEE.
> +
> +See https://www.op-tee.org/ for more details.
> +
> +Supported TEE methods
> +---------------------
> +
> +In u-boot there are two means of installing a TEE
> +
> +- Installing a TEE (tee-standalone)
> +
> +  In this case u-boot is responsible for loading the TEE into memory, jumping
> +  into the TEE and subsequently handling return of control back to u-boot.
> +
> +  u-boot then is responsible to load and boot a kernel and DTB in the normal
> +  way.
> +
> +  BootROM/SPL
> +        |
> +        v
> +      u-boot ---->
> +                  TEE
> +      u-boot <----
> +        |
> +        v
> +      Linux
> +
> +- Chainloading via a TEE (tee-bootable)
> +
> +  In this case u-boot is responsible for loading the TEE into memory and handing
> +  control to the TEE. The TEE then will enter into secure mode boot-strap itself
> +  and hand control onto a subsequent boot stage - typically a Linux kernel.
> +
> +  When chain-loading in this way u-boot is reponsible for loading bootscripts,
> +  Kernel, DTB etc into memory.
> +
> +  BootROM/SPL
> +        |
> +        v
> +      u-boot
> +        |
> +        v
> +       TEE
> +        |
> +        v
> +      Linux
> +
> +Creating a TEE image with mkimage
> +---------------------------------
> +
> +- "tee" (tee-standalone)
> +
> +  To identify this type of image to u-boot you should use mkimage like this:
> +
> +  mkimage -A arm -T tee -C none -d tee-image.bin uTee-standalone

The type should be “tee-standalone” to avoid confusion with the boot-through
variety.

> +
> +- "tee-bootable"
> +
> +  mkimage -A arm -T tee-bootable -C none -d tee.bin uTee-bootable

Bootable doesn’t really describe this: both the -standalone and this version of
the OPTEE are bootable, but the difference is that this variant also contains the
next-stage payload. Either we keep Tom’s proposed -combo naming or we can
try to describe this as a “tee-with-payload” type.

> +
> +Booting the image types
> +-----------------------
> +
> +- tee-standalone
> +
> +  For a standalone TEE image you should create or reuse an existing board-port
> +  and install the TEE into memory in the appropriate way for your architecture.
> +
> +  Some TEE implementations may reside in a special SRAM area or have special
> +  ROM callbacks in order to setup the TEE correctly.
> +
> +  eg:
> +  board/company/board_name.c
> +
> +  void board_tee_image_process(ulong tee_image, size_t tee_size)
> +  {
> +      /* Install TEE into memory as approrpiate here */
> +  }
> +
> +  U_BOOT_FIT_LOADABLE_HANDLER(IH_TYPE_TEE, board_tee_image_process);
> +
> +- tee-bootable
> +
> +  For a bootable TEE image you need to load the TEE into an appropriate address
> +  in DRAM.
> +
> +  Once done use the bootm command to execute the image.
> +
> +  eg:
> +  => ext4load mmc 0:1 /lib/firmware/uTee-bootable 0x84000000
> +  => bootm 0x84000000
> +
> +  ## Booting kernel from Legacy Image at 84000000 ...
> +   Image Name:
> +   Image Type:   ARM Linux Trusted Execution Environment Bootable Image (uncompressed)
> +   Data Size:    249844 Bytes = 244 KiB
> +   Load Address: 9dffffe4
> +   Entry Point:  9e000000
> +   Verifying Checksum ... OK
> +  ## Flattened Device Tree blob at 83000000
> +   Booting using the fdt blob at 0x83000000
> +   Loading Trusted Execution Environment Bootable Image ... OK
> +   Using Device Tree in place at 83000000, end 83009b4d
> -- 
> 2.7.4
>

On 26/02/18 13:53, Dr. Philipp Tomsich wrote:
>> +  To identify this type of image to u-boot you should use mkimage like this:
>> +
>> +  mkimage -A arm -T tee -C none -d tee-image.bin uTee-standalone
> The type should be “tee-standalone” to avoid confusion with the boot-through
> variety.

Eh, I actually agree with you.

I was thinking that making the change from "tee" to "tee-standalone" and 
might break things for people with their continuous-integration 
jobs/scripts etc.

So I was going to send out an "RFC" patch changing "tee" to 
"tee-standalone".

I'm just as happy to make the name change in this set if it's an agreed 
thing with Tom and Andrew though.

> 
>> +
>> +- "tee-bootable"
>> +
>> +  mkimage -A arm -T tee-bootable -C none -d tee.bin uTee-bootable

> Bootable doesn’t really describe this: both the -standalone and this version of
> the OPTEE are bootable, but the difference is that this variant also contains the
> next-stage payload. Either we keep Tom’s proposed -combo naming or we can
> try to describe this as a “tee-with-payload” type.

Hmm - I thought Tom had suggested

"tee" - stays as is because that's what it's already called.
"tee-standalone" - which I've called "tee-bootable"

and then there was a potential addition "tee-combo" covering what Kever 
may or may not do with his SPL implementation.

but I opted for "tee-bootable" instead of "tee-standalone"..

I think we need two decisions here:

#1 Exiting:
"tee" - stay as
"tee-standalone" - new name more obvious - adds churn into mkimage namespace

#2 Bootable OPTEE (chainload):
"tee-bootable"
"tee-chainload"
"tee-with-payload" (not so sure about this myself)

Tom, Philipp, Andrew ?

--
bod

Bryan,

> On 26 Feb 2018, at 15:39, Bryan O'Donoghue <bryan.odonoghue@linaro.org> wrote:
> 
> 
> 
> On 26/02/18 13:53, Dr. Philipp Tomsich wrote:
>>> +  To identify this type of image to u-boot you should use mkimage like this:
>>> +
>>> +  mkimage -A arm -T tee -C none -d tee-image.bin uTee-standalone
>> The type should be “tee-standalone” to avoid confusion with the boot-through
>> variety.
> 
> Eh, I actually agree with you.
> 
> I was thinking that making the change from "tee" to "tee-standalone" and might break things for people with their continuous-integration jobs/scripts etc.
> 
> So I was going to send out an "RFC" patch changing "tee" to "tee-standalone".
> 
> I'm just as happy to make the name change in this set if it's an agreed thing with Tom and Andrew though.
> 
>>> +
>>> +- "tee-bootable"
>>> +
>>> +  mkimage -A arm -T tee-bootable -C none -d tee.bin uTee-bootable
> 
>> Bootable doesn’t really describe this: both the -standalone and this version of
>> the OPTEE are bootable, but the difference is that this variant also contains the
>> next-stage payload. Either we keep Tom’s proposed -combo naming or we can
>> try to describe this as a “tee-with-payload” type.
> 
> Hmm - I thought Tom had suggested
> 
> "tee" - stays as is because that's what it's already called.
> "tee-standalone" - which I've called "tee-bootable"
> 
> and then there was a potential addition "tee-combo" covering what Kever may or may not do with his SPL implementation.
> 
> but I opted for "tee-bootable" instead of "tee-standalone"..
> 
> I think we need two decisions here:
> 
> #1 Exiting:
> "tee" - stay as
> "tee-standalone" - new name more obvious - adds churn into mkimage namespace
> 
> #2 Bootable OPTEE (chainload):
> "tee-bootable"
> "tee-chainload"
> "tee-with-payload" (not so sure about this myself)
> 
> Tom, Philipp, Andrew ?

Now, I am confused.

I thought there’s only two different paths: the one where the TEE is “installed” as
a secure OS (and then returns control to the bootloader) and the other one where
control os passed to the TEE and it “boot-through" into a next stage (whether a full
U-Boot or Linux).

The “boot-through” approach would be similar to what ATF does ...

Regards,
Philipp.

On 26/02/18 14:56, Dr. Philipp Tomsich wrote:
> Now, I am confused.

Fair enough.

In my view there are really only two required paths i.e. kever's stuff 
can use the existing "tee" type, let's not discuss a third option further.

So for clarity the proposal is

1. Maintain the existing "tee" as is.

    As regards changing the name of "tee" to "tee-standalone" I'd like
    to get Tom or Andrew (both) to say that's what is wanted.

    Since it's TI boards that are using the "tee" name in mkimage
    upstream the name-change is churn there.

    Andrew, Tom ?

2. Add a new bootable type
    The set of names we have for that is

    {tee-bootable, tee-chainload, tee-with-payload}

    I have no strong feelings about the name for the new type either way

    :)

On 02/26/2018 09:06 AM, Bryan O'Donoghue wrote:
> 
> 
> On 26/02/18 14:56, Dr. Philipp Tomsich wrote:
>> Now, I am confused.
> 
> Fair enough.
> 
> In my view there are really only two required paths i.e. kever's stuff
> can use the existing "tee" type, let's not discuss a third option further.
> 
> So for clarity the proposal is
> 
> 1. Maintain the existing "tee" as is.
> 
>    As regards changing the name of "tee" to "tee-standalone" I'd like
>    to get Tom or Andrew (both) to say that's what is wanted.
> 
>    Since it's TI boards that are using the "tee" name in mkimage
>    upstream the name-change is churn there.
> 
>    Andrew, Tom ?
> 

I wouldn't be too opposed to the name change if we decide to go down
this two type path, but I'm still not convinced we are doing the right
thing here.

Lets look at u-boot/include/image.h for a moment, the table of IH_TYPE_*
already has a type for what we are trying to do here: IH_TYPE_KERNEL.
The comment on this table describes "OS Kernel Images" as exactly what
you are doing with your TEE image.

To me what you really want to do is add a new IH_OS_*, which are defined
in a different table above (I see this is already done for ATF
(IH_OS_ARM_TRUSTED_FIRMWARE) which shares a similar “boot-through” flow
like Philipp pointed out).

So I'm still not sure what the technical reason you need a new "type" of
image, when adding your hooks to the existing IH_TYPE_KERNEL path in
U-Boot could be made to do the same thing when it encounters a IH_OS_TEE
OS image.

Andrew

> 2. Add a new bootable type
>    The set of names we have for that is
> 
>    {tee-bootable, tee-chainload, tee-with-payload}
> 
>    I have no strong feelings about the name for the new type either way
> 
>    :)

> On 26 Feb 2018, at 16:26, Andrew F. Davis <afd@ti.com> wrote:
> 
> On 02/26/2018 09:06 AM, Bryan O'Donoghue wrote:
>> 
>> 
>> On 26/02/18 14:56, Dr. Philipp Tomsich wrote:
>>> Now, I am confused.
>> 
>> Fair enough.
>> 
>> In my view there are really only two required paths i.e. kever's stuff
>> can use the existing "tee" type, let's not discuss a third option further.
>> 
>> So for clarity the proposal is
>> 
>> 1. Maintain the existing "tee" as is.
>> 
>>    As regards changing the name of "tee" to "tee-standalone" I'd like
>>    to get Tom or Andrew (both) to say that's what is wanted.
>> 
>>    Since it's TI boards that are using the "tee" name in mkimage
>>    upstream the name-change is churn there.
>> 
>>    Andrew, Tom ?
>> 
> 
> I wouldn't be too opposed to the name change if we decide to go down
> this two type path, but I'm still not convinced we are doing the right
> thing here.
> 
> Lets look at u-boot/include/image.h for a moment, the table of IH_TYPE_*
> already has a type for what we are trying to do here: IH_TYPE_KERNEL.
> The comment on this table describes "OS Kernel Images" as exactly what
> you are doing with your TEE image.
> 
> To me what you really want to do is add a new IH_OS_*, which are defined
> in a different table above (I see this is already done for ATF
> (IH_OS_ARM_TRUSTED_FIRMWARE) which shares a similar “boot-through” flow
> like Philipp pointed out).

The IH_OS_ARM_TRUSTED_FIRMWARE (sorry for not shortening this, 
when I added it) encodes a specific parameter passing convention for the
ATF (i.e. bl31_params_t, platform-specific parameters — and in the future
bl32_params_t for loading up an OPTEE on ARMv8).

The parameter passing convention for an OPTEE on ARMv7 is different
(see https://github.com/OP-TEE/optee_os/blob/master/core/arch/arm/kernel/generic_entry_a32.S#L186)
and therefore affords a separate OS type.

The thing I haven’t understood yet, though, is: how can the “returns to
link-register” variant exist, if the parameter passing (and entry code) in
the upstream OPTEE looks as it does...

> 
> So I'm still not sure what the technical reason you need a new "type" of
> image, when adding your hooks to the existing IH_TYPE_KERNEL path in
> U-Boot could be made to do the same thing when it encounters a IH_OS_TEE
> OS image.
> 
> Andrew
> 
>> 2. Add a new bootable type
>>    The set of names we have for that is
>> 
>>    {tee-bootable, tee-chainload, tee-with-payload}
>> 
>>    I have no strong feelings about the name for the new type either way
>> 
>>    :)

On 02/26/2018 09:32 AM, Dr. Philipp Tomsich wrote:
> 
>> On 26 Feb 2018, at 16:26, Andrew F. Davis <afd@ti.com> wrote:
>>
>> On 02/26/2018 09:06 AM, Bryan O'Donoghue wrote:
>>>
>>>
>>> On 26/02/18 14:56, Dr. Philipp Tomsich wrote:
>>>> Now, I am confused.
>>>
>>> Fair enough.
>>>
>>> In my view there are really only two required paths i.e. kever's stuff
>>> can use the existing "tee" type, let's not discuss a third option further.
>>>
>>> So for clarity the proposal is
>>>
>>> 1. Maintain the existing "tee" as is.
>>>
>>>    As regards changing the name of "tee" to "tee-standalone" I'd like
>>>    to get Tom or Andrew (both) to say that's what is wanted.
>>>
>>>    Since it's TI boards that are using the "tee" name in mkimage
>>>    upstream the name-change is churn there.
>>>
>>>    Andrew, Tom ?
>>>
>>
>> I wouldn't be too opposed to the name change if we decide to go down
>> this two type path, but I'm still not convinced we are doing the right
>> thing here.
>>
>> Lets look at u-boot/include/image.h for a moment, the table of IH_TYPE_*
>> already has a type for what we are trying to do here: IH_TYPE_KERNEL.
>> The comment on this table describes "OS Kernel Images" as exactly what
>> you are doing with your TEE image.
>>
>> To me what you really want to do is add a new IH_OS_*, which are defined
>> in a different table above (I see this is already done for ATF
>> (IH_OS_ARM_TRUSTED_FIRMWARE) which shares a similar “boot-through” flow
>> like Philipp pointed out).
> 
> The IH_OS_ARM_TRUSTED_FIRMWARE (sorry for not shortening this, 
> when I added it) encodes a specific parameter passing convention for the
> ATF (i.e. bl31_params_t, platform-specific parameters — and in the future
> bl32_params_t for loading up an OPTEE on ARMv8).
> 
> The parameter passing convention for an OPTEE on ARMv7 is different
> (see https://github.com/OP-TEE/optee_os/blob/master/core/arch/arm/kernel/generic_entry_a32.S#L186)
> and therefore affords a separate OS type.
> 

I agree, that is what I am suggesting. A new IH_OS_ and not a new image
type IH_TYPE_ as IH_TYPE_KERNEL is already the right type.

> The thing I haven’t understood yet, though, is: how can the “returns to
> link-register” variant exist, if the parameter passing (and entry code) in
> the upstream OPTEE looks as it does...
> 


When the SMC call to install a TEE is made the ROM saves the non-secure
context, so in OP-TEE we simply retrieve this context [0] from the ROM
memory and use it as our non-secure context to return to, this puts us
right back to where the SMC came from when OP-TEE install finishes.

This allows us to do stuff like starting TEE from kernel dynamically at
runtime, something I'm not sure how the other flow could support if it
always expects to be an intermediate boot stage.. but I guess that is
their problem to solve not mine :)

[0]
https://github.com/OP-TEE/optee_os/blob/master/core/arch/arm/plat-ti/main.c#L128

Andrew


>>
>> So I'm still not sure what the technical reason you need a new "type" of
>> image, when adding your hooks to the existing IH_TYPE_KERNEL path in
>> U-Boot could be made to do the same thing when it encounters a IH_OS_TEE
>> OS image.
>>
>> Andrew
>>
>>> 2. Add a new bootable type
>>>    The set of names we have for that is
>>>
>>>    {tee-bootable, tee-chainload, tee-with-payload}
>>>
>>>    I have no strong feelings about the name for the new type either way
>>>
>>>    :)
>

On 26/02/18 15:26, Andrew F. Davis wrote:
> Lets look at u-boot/include/image.h for a moment, the table of IH_TYPE_*
> already has a type for what we are trying to do here: IH_TYPE_KERNEL.
> The comment on this table describes "OS Kernel Images" as exactly what
> you are doing with your TEE image.
> 
> To me what you really want to do is add a new IH_OS_*, which are defined
> in a different table above (I see this is already done for ATF
> (IH_OS_ARM_TRUSTED_FIRMWARE) which shares a similar “boot-through” flow
> like Philipp pointed out).
> 
> So I'm still not sure what the technical reason you need a new "type" of
> image, when adding your hooks to the existing IH_TYPE_KERNEL path in
> U-Boot could be made to do the same thing when it encounters a IH_OS_TEE

I'll have a look and see if your suggestion on IH_TYPE_KERNEL is 
feasible, it looks like is though I don't know for sure until I try.

i.e.
"mkimage -A arm -T kernel -C none -d tee.bin uTee.optee" + hook on the 
OPTEE header on the IH_TYPE_KERNEL path.

---
bod