Coverage for apio/commands/apio_upload.py: 78%

1# -*- coding: utf-8 -*- 

2# -- This file is part of the Apio project 

3# -- (C) 2016-2024 FPGAwars 

4# -- Authors 

5# -- * Jesús Arroyo (2016-2019) 

6# -- * Juan Gonzalez (obijuan) (2019-2024) 

7# -- License GPLv2 

8"""Implementation of 'apio upload' command""" 

9 

10import sys 

11from typing import Optional 

12from pathlib import Path 

13import click 

14from apio.managers.scons_manager import SConsManager 

15from apio.utils import cmd_util 

16from apio.commands import options 

17from apio.apio_context import ( 

18 ApioContext, 

19 PackagesPolicy, 

20 ProjectPolicy, 

21 RemoteConfigPolicy, 

22) 

23from apio.managers.programmers import construct_programmer_cmd 

24from apio.common.proto.apio_pb2 import UploadParams 

25 

26 

27# --------- apio upload 

28 

29serial_port_option = click.option( 

30 "serial_port", # Var name. 

31 "-s", 

32 "--serial-port", 

33 type=str, 

34 metavar="serial-port", 

35 help="Set the serial port.", 

36 cls=cmd_util.ApioOption, 

37) 

38 

39serial_num_option = click.option( 

40 "serial_num", # Var name. 

41 "-n", 

42 "--serial-num", 

43 type=str, 

44 metavar="serial-num", 

45 help="Select the device's USB serial number.", 

46 cls=cmd_util.ApioOption, 

47) 

48 

49 

50# -- Text in the rich-text format of the python rich library. 

51APIO_UPLOAD_HELP = """ 

52The command 'apio upload' builds the bitstream file (similar to the \ 

53'apio build' command) and uploads it to the FPGA board. 

54 

55Examples:[code] 

56 apio upload # Typical invocation 

57 apio upload -s /dev/cu.usbserial-1300 # Select serial port 

58 apio upload -n FTXYA34Z # Select serial number[/code] 

59 

60Typically the simple form 'apio upload' is sufficient to locate and program \ 

61the FPGA board. The optional flags '--serial-port' and '--serial-num' allows \ 

62to select the desired board if more than one matching board is detected. 

63 

64[HINT] You can use the command 'apio devices' to list the connected USB and \ 

65serial devices and the command 'apio drivers' to install and uninstall device \ 

66drivers. 

67 

68[HINT] The default programmer command of your board can be overridden using \ 

69the apio.ini option 'programmer-cmd'. 

70""" 

71 

72 

73@click.command( 

74 name="upload", 

75 cls=cmd_util.ApioCommand, 

76 short_help="Upload the bitstream to the FPGA.", 

77 help=APIO_UPLOAD_HELP, 

78) 

79@click.pass_context 

80@serial_port_option 

81@serial_num_option 

82@options.env_option_gen() 

83@options.project_dir_option 

84def cli( 

85 _: click.Context, 

86 # Options 

87 serial_port: str, 

88 serial_num: str, 

89 env: Optional[str], 

90 project_dir: Optional[Path], 

91): 

92 """Implements the upload command.""" 

93 

94 # -- Create a apio context. 

95 apio_ctx = ApioContext( 

96 project_policy=ProjectPolicy.PROJECT_REQUIRED, 

97 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

98 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

99 project_dir_arg=project_dir, 

100 env_arg=env, 

101 ) 

102 

103 # -- Set the shell env. 

104 apio_ctx.set_env_for_packages() 

105 

106 # -- Get the programmer command. 

107 programmer_cmd = construct_programmer_cmd( 

108 apio_ctx, serial_port_flag=serial_port, serial_num_flag=serial_num 

109 ) 

110 

111 # Construct the scons upload params. 

112 upload_params = UploadParams(programmer_cmd=programmer_cmd) 

113 

114 # -- Create the scons manager 

115 scons = SConsManager(apio_ctx) 

116 

117 # Run scons: upload command 

118 exit_code = scons.upload(upload_params) 

119 

120 # -- Done! 

121 sys.exit(exit_code) 

122 

123 

124# Advanced notes: https://github.com/FPGAwars/apio/wiki/Commands#apio-upload