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

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 pathlib import Path 

12import click 

13from apio.managers.scons_manager import SConsManager 

14from apio.utils import cmd_util 

15from apio.commands import options 

16from apio.apio_context import ( 

17 ApioContext, 

18 PackagesPolicy, 

19 ProjectPolicy, 

20 RemoteConfigPolicy, 

21) 

22from apio.managers.programmers import construct_programmer_cmd 

23from apio.common.proto.apio_scons_pb2 import UploadParams 

24 

25 

26# --------- apio upload 

27 

28serial_port_option = click.option( 

29 "serial_port", # Var name. 

30 "-s", 

31 "--serial-port", 

32 type=str, 

33 metavar="serial-port", 

34 help="Set the serial port.", 

35 cls=cmd_util.ApioOption, 

36) 

37 

38serial_num_option = click.option( 

39 "serial_num", # Var name. 

40 "-n", 

41 "--serial-num", 

42 type=str, 

43 metavar="serial-num", 

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

45 cls=cmd_util.ApioOption, 

46) 

47 

48 

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

50APIO_UPLOAD_HELP = """ 

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

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

53 

54Examples:[code] 

55 apio upload # Typical invocation 

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

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

58 

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

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

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

62 

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

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

65drivers. 

66 

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

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

69""" 

70 

71 

72@click.command( 

73 name="upload", 

74 cls=cmd_util.ApioCommand, 

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

76 help=APIO_UPLOAD_HELP, 

77) 

78@click.pass_context 

79@serial_port_option 

80@serial_num_option 

81@options.env_option_gen() 

82@options.project_dir_option 

83def cli( 

84 _: click.Context, 

85 *, 

86 # Options 

87 serial_port: str, 

88 serial_num: str, 

89 env: str | None, 

90 project_dir: Path | None, 

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)