Domain selection capabilities

With CCA, users can exploit multiple domains.

To find out the available domains on your partition use the lszcrypt command:

# lszcrypt

CARD.DOMAIN  TYPE   MODE        STATUS  REQUEST_CNT
-----------------------------------------------------
00           CEX5C  CCA-Coproc  online           36
00.0005      CEX5C  CCA-Coproc  online           10
00.001f      CEX5C  CCA-Coproc  online            7

In the example, there is a single card, designated ID 0. For card 0 there are two domains available, X'05' and X'1f' (31 decimal).

There is a default domain for the system, which can be retrieved using the following command:

# cat /sys/bus/ap/ap_domain

CCA uses this default domain if no other choice is made using the CSU_DEFAULT_DOMAIN environment variable.

You can configure a CCA application to use the multi-domain capabilities with the environment variable CSU_DEFAULT_DOMAIN, or dynamically with the CCA verbs Cryptographic Resource Allocate (CSUACRA) and Cryptographic Resource Deallocate (CSUACRD). The CCA library scans the environment variable one time when the application starts, but not for every request. To achieve more dynamic allocations, use CSUACRA and CSUACRD. CCA does not try to fix bad values for the variable. An error is returned for each request sent to an unconfigured domain, and information is placed into the system log.

Note: The scope of CCA domain selection when using the CSUACRA and the CSUACRD verbs is to a process, not to a thread.

Using CSU_DEFAULT_DOMAIN

Selecting a single domain
To set a single domain for use by the current application, whether that is a configuration utility (such as panel.exe) or a production business application, set the CSU_DEFAULT_DOMAIN variable to the decimal number for that domain. Continuing with the previous example, if domain 31 is desired, use this command:
```
# export CSU_DEFAULT_DOMAIN=31
```
Use cases for a single-domain configuration in a multi-domain system image
- When setting master keys for multiple domains on the same card using the panel.exe utility, set the default domain to the desired value in between configuration actions to target the correct domain.
- If there are two applications that run on the same system but require unique master keys and unique key storage locations:
  - Configure domain X on all cards with the master key for application_1, and configure domain Y on all cards with the master key for application_2.
  - Create unique key storage for each application.
  - Set the CSU_DEFAULT_DOMAIN environment variable for each application.
Selecting any domain
Similar to the multi-card load-balancing approach, there is a way to request that the Linux® device driver load-balances your requests across all domains. It is best used in concert with the multi-card load-balancing approach since there is no extra performance capacity available by using a second domain from the same card. It is very important that all used domains are configured with the same master key. Also, further required configuration (such as decimalization tables) must be the same for all domains, if they are made available to a system that exploits multi-domain load-balancing.
To configure multi-domain load-balancing, use this command:
```
# export CSU_DEFAULT_DOMAIN=DOM-ANY
```